0
# MIME System
1

2
The MIME system in rest.js provides automatic serialization and deserialization of request and response entities based on Content-Type headers. It includes built-in converters for common formats and supports custom converter registration.
3

4
## Capabilities
5

6
### MIME Type Parsing
7

8
Parse MIME type strings into structured objects.
9

10
```javascript { .api }
11
const mime = require('rest/mime');
12

13
/**
14
 * Parse a MIME type string
15
 * @param {string} mimeType - MIME type to parse
16
 * @returns {object} Parsed MIME type object
17
 */
18
function parse(mimeType)
19
```
20

21
**Parsed MIME type object:**
22

23
```javascript { .api }
24
interface ParsedMimeType {
25
  raw: string;        // Original MIME type string
26
  type: string;       // Main type (e.g., 'application/json')
27
  suffix: string;     // MIME suffix including '+' (e.g., '+json')
28
  params: object;     // MIME parameters as key-value pairs
29
}
30
```
31

32
**Usage Example:**
33

34
```javascript
35
const mime = require('rest/mime');
36

37
const parsed = mime.parse('application/vnd.api+json; charset=utf-8');
38
console.log(parsed);
39
// {
40
//   raw: 'application/vnd.api+json; charset=utf-8',
41
//   type: 'application/vnd.api',
42
//   suffix: '+json',
43
//   params: { charset: 'utf-8' }
44
// }
45
```
46

47
### MIME Registry
48

49
Central registry for MIME type converters with hierarchical lookup and custom converter support.
50

51
```javascript { .api }
52
const registry = require('rest/mime/registry');
53

54
/**
55
 * MIME registry for converter management
56
 */
57
interface Registry {
58
  /**
59
   * Look up converter for a MIME type
60
   * @param {string} type - MIME type to find converter for
61
   * @returns {Promise<Converter>} Promise resolving to converter
62
   */
63
  lookup(type: string): Promise<Converter>;
64

65
  /**
66
   * Register a custom converter
67
   * @param {string} type - MIME type
68
   * @param {Converter} converter - Converter implementation
69
   * @returns {Promise<Converter>} Promise resolving to registered converter
70
   */
71
  register(type: string, converter: Converter): Promise<Converter>;
72

73
  /**
74
   * Create a delegate converter that proxies to another type
75
   * @param {string} type - Target MIME type to delegate to
76
   * @returns {Converter} Delegate converter
77
   */
78
  delegate(type: string): Converter;
79

80
  /**
81
   * Create a child registry with local registrations
82
   * @returns {Registry} Child registry
83
   */
84
  child(): Registry;
85
}
86

87
/**
88
 * MIME converter interface
89
 */
90
interface Converter {
91
  /**
92
   * Convert string to object (deserialization)
93
   * @param {string} str - String to convert
94
   * @returns {any} Converted object
95
   */
96
  read(str: string): any;
97

98
  /**
99
   * Convert object to string (serialization)
100
   * @param {any} obj - Object to convert
101
   * @returns {string} Converted string
102
   */
103
  write(obj: any): string;
104
}
105
```
106

107
**Usage Example:**
108

109
```javascript
110
const registry = require('rest/mime/registry');
111

112
// Register custom converter
113
registry.register('application/vnd.myapp+json', {
114
  read: function(str) {
115
    const data = JSON.parse(str);
116
    return { customData: data, timestamp: Date.now() };
117
  },
118
  write: function(obj) {
119
    return JSON.stringify(obj.customData);
120
  }
121
});
122

123
// Use the converter
124
registry.lookup('application/vnd.myapp+json').then(function(converter) {
125
  const obj = converter.read('{"key": "value"}');
126
  console.log(obj); // { customData: { key: "value" }, timestamp: 1234567890 }
127
});
128
```
129

130
### Built-in Converters
131

132
#### JSON Converter
133

134
Handles `application/json` and `+json` suffix types.
135

136
```javascript { .api }
137
const jsonConverter = require('rest/mime/type/application/json');
138

139
/**
140
 * JSON converter with configurable options
141
 * @param {object} [config] - JSON configuration
142
 * @param {function} [config.replacer] - JSON.stringify replacer
143
 * @param {function} [config.reviver] - JSON.parse reviver
144
 */
145
```
146

147
#### Form URL Encoded Converter
148

149
Handles `application/x-www-form-urlencoded` content.
150

151
```javascript { .api }
152
const formConverter = require('rest/mime/type/application/x-www-form-urlencoded');
153

154
/**
155
 * Form URL encoding converter
156
 */
157
interface FormConverter {
158
  read(str: string): object;
159
  write(obj: object): string;
160
}
161
```
162

163
#### Multipart Form Data Converter
164

165
Handles `multipart/form-data` (browser only with FormData support).
166

167
```javascript { .api }
168
const multipartConverter = require('rest/mime/type/multipart/form-data');
169

170
/**
171
 * Multipart form data converter (browser only)
172
 */
173
```
174

175
#### Plain Text Converter
176

177
Handles `text/plain` content.
178

179
```javascript { .api }
180
const textConverter = require('rest/mime/type/text/plain');
181

182
/**
183
 * Plain text converter (pass-through)
184
 */
185
```
186

187
#### HAL Converter
188

189
Handles `application/hal+json` (Hypertext Application Language).
190

191
```javascript { .api }
192
const halConverter = require('rest/mime/type/application/hal');
193

194
/**
195
 * HAL (Hypertext Application Language) converter
196
 * Provides hypermedia navigation capabilities
197
 */
198
```
199

200
## MIME Interceptor Integration
201

202
The MIME interceptor automatically applies appropriate converters based on Content-Type headers:
203

204
```javascript
205
const rest = require('rest');
206
const mime = require('rest/interceptor/mime');
207

208
const client = rest.wrap(mime, {
209
  mime: 'application/json',                    // Default request MIME type
210
  accept: 'application/json, text/plain',      // Accept header
211
  registry: customRegistry,                    // Custom registry (optional)
212
  permissive: false                           // Reject unknown MIME types
213
});
214

215
// Automatic JSON serialization
216
client({
217
  path: '/api/users',
218
  method: 'POST',
219
  entity: { name: 'John', email: 'john@example.com' }
220
}).then(function(response) {
221
  // response.entity is automatically parsed as JSON
222
  console.log('Created user:', response.entity);
223
});
224
```
225

226
## Custom Converter Registration
227

228
Create and register custom MIME converters for specialized formats:
229

230
```javascript
231
const registry = require('rest/mime/registry');
232

233
// Custom XML converter example
234
const xmlConverter = {
235
  read: function(str) {
236
    // Parse XML string to object
237
    // (using a hypothetical XML parser)
238
    return parseXML(str);
239
  },
240
  write: function(obj) {
241
    // Convert object to XML string
242
    return toXML(obj);
243
  }
244
};
245

246
// Register the converter
247
registry.register('application/xml', xmlConverter);
248
registry.register('text/xml', xmlConverter);
249

250
// Create delegate for related types
251
registry.register('+xml', registry.delegate('application/xml'));
252

253
// Use with MIME interceptor
254
const mime = require('rest/interceptor/mime');
255
const client = rest.wrap(mime, {
256
  mime: 'application/xml',
257
  accept: 'application/xml'
258
});
259
```
260

261
## Child Registries
262

263
Create isolated MIME registries for different parts of your application:
264

265
```javascript
266
const registry = require('rest/mime/registry');
267

268
// Create child registry
269
const apiRegistry = registry.child();
270

271
// Register converters only for this registry
272
apiRegistry.register('application/vnd.api+json', customApiConverter);
273

274
// Use child registry with interceptor
275
const mime = require('rest/interceptor/mime');
276
const apiClient = rest.wrap(mime, {
277
  registry: apiRegistry,
278
  mime: 'application/vnd.api+json'
279
});
280
```
281

282
## Content Negotiation
283

284
The MIME system supports automatic content negotiation through Accept headers:
285

286
```javascript
287
const mime = require('rest/interceptor/mime');
288

289
const client = rest.wrap(mime, {
290
  accept: 'application/json;q=1.0, application/xml;q=0.8, text/plain;q=0.5'
291
});
292

293
// Server can respond with any of the accepted types
294
// Response will be automatically converted based on Content-Type
295
```