0
# Parameter Management
1

2
Map-like interface for accessing and modifying MIME type parameters with automatic validation, case-insensitive handling, and full iteration support.
3

4
## Capabilities
5

6
### MIMETypeParameters Class
7

8
Provides a Map-like interface for MIME type parameters with built-in validation and case normalization.
9

10
```javascript { .api }
11
/**
12
 * Creates a new parameters wrapper around a Map instance
13
 * @param {Map} map - Internal Map instance for parameter storage
14
 */
15
class MIMETypeParameters {
16
  constructor(map);
17
}
18
```
19

20
### Size Property
21

22
Gets the number of parameters.
23

24
```javascript { .api }
25
/**
26
 * Gets the number of parameters
27
 * @returns {number} The number of parameter key-value pairs
28
 */
29
get size();
30
```
31

32
**Usage Examples:**
33

34
```javascript
35
const MIMEType = require("whatwg-mimetype");
36

37
const mimeType = new MIMEType("text/html;charset=utf-8;boundary=something");
38
console.log(mimeType.parameters.size); // 2
39
```
40

41
### Get Method
42

43
Retrieves a parameter value by name (case-insensitive).
44

45
```javascript { .api }
46
/**
47
 * Gets a parameter value by name (case-insensitive)
48
 * @param {string} name - Parameter name to look up
49
 * @returns {string|undefined} Parameter value or undefined if not found
50
 */
51
get(name);
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
const mimeType = new MIMEType("text/html;charset=utf-8;Boundary=abc123");
58

59
console.log(mimeType.parameters.get("charset")); // "utf-8"
60
console.log(mimeType.parameters.get("CHARSET")); // "utf-8" (case-insensitive)
61
console.log(mimeType.parameters.get("boundary")); // "abc123"
62
console.log(mimeType.parameters.get("missing")); // undefined
63
```
64

65
### Has Method
66

67
Checks if a parameter exists (case-insensitive).
68

69
```javascript { .api }
70
/**
71
 * Checks if a parameter exists (case-insensitive)
72
 * @param {string} name - Parameter name to check
73
 * @returns {boolean} True if the parameter exists
74
 */
75
has(name);
76
```
77

78
**Usage Examples:**
79

80
```javascript
81
const mimeType = new MIMEType("text/html;charset=utf-8");
82

83
console.log(mimeType.parameters.has("charset")); // true
84
console.log(mimeType.parameters.has("CHARSET")); // true (case-insensitive)
85
console.log(mimeType.parameters.has("boundary")); // false
86
```
87

88
### Set Method
89

90
Sets a parameter value with validation of both name and value.
91

92
```javascript { .api }
93
/**
94
 * Sets a parameter value with validation
95
 * @param {string} name - Parameter name (will be normalized to lowercase)
96
 * @param {string} value - Parameter value
97
 * @returns {Map} The underlying Map instance (for chaining)
98
 * @throws {Error} If name contains invalid characters
99
 * @throws {Error} If value contains invalid characters
100
 */
101
set(name, value);
102
```
103

104
**Usage Examples:**
105

106
```javascript
107
const mimeType = new MIMEType("text/html");
108

109
// Set new parameter
110
mimeType.parameters.set("charset", "utf-8");
111
console.log(mimeType.toString()); // "text/html;charset=utf-8"
112

113
// Update existing parameter
114
mimeType.parameters.set("CHARSET", "iso-8859-1"); // case-insensitive
115
console.log(mimeType.parameters.get("charset")); // "iso-8859-1"
116

117
// Parameter names are normalized to lowercase
118
mimeType.parameters.set("Boundary", "abc123");
119
console.log(mimeType.parameters.get("boundary")); // "abc123"
120

121
// Invalid parameter names throw errors
122
try {
123
  mimeType.parameters.set("invalid@name", "value");
124
} catch (error) {
125
  console.log(error.message); // 'Invalid MIME type parameter name "invalid@name": only HTTP token code points are valid.'
126
}
127

128
// Invalid parameter values throw errors
129
try {
130
  mimeType.parameters.set("charset", "invalid\x00value");
131
} catch (error) {
132
  console.log(error.message); // 'Invalid MIME type parameter value "invalid\x00value": only HTTP quoted-string token code points are valid.'
133
}
134
```
135

136
### Delete Method
137

138
Removes a parameter by name (case-insensitive).
139

140
```javascript { .api }
141
/**
142
 * Removes a parameter by name (case-insensitive)
143
 * @param {string} name - Parameter name to remove
144
 * @returns {boolean} True if the parameter existed and was removed
145
 */
146
delete(name);
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
const mimeType = new MIMEType("text/html;charset=utf-8;boundary=abc123");
153

154
console.log(mimeType.parameters.delete("charset")); // true
155
console.log(mimeType.parameters.has("charset")); // false
156
console.log(mimeType.toString()); // "text/html;boundary=abc123"
157

158
console.log(mimeType.parameters.delete("BOUNDARY")); // true (case-insensitive)
159
console.log(mimeType.parameters.delete("missing")); // false
160
```
161

162
### Clear Method
163

164
Removes all parameters.
165

166
```javascript { .api }
167
/**
168
 * Removes all parameters
169
 */
170
clear();
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
const mimeType = new MIMEType("text/html;charset=utf-8;boundary=abc123");
177

178
console.log(mimeType.parameters.size); // 2
179
mimeType.parameters.clear();
180
console.log(mimeType.parameters.size); // 0
181
console.log(mimeType.toString()); // "text/html"
182
```
183

184
### Iteration Methods
185

186
Methods for iterating over parameters, providing Map-like iteration capabilities.
187

188
```javascript { .api }
189
/**
190
 * Executes a callback for each parameter
191
 * @param {function} callbackFn - Function to execute for each parameter
192
 * @param {*} [thisArg] - Value to use as 'this' when executing callback
193
 */
194
forEach(callbackFn, thisArg);
195

196
/**
197
 * Returns an iterator for parameter names
198
 * @returns {Iterator<string>} Iterator for parameter names
199
 */
200
keys();
201

202
/**
203
 * Returns an iterator for parameter values
204
 * @returns {Iterator<string>} Iterator for parameter values
205
 */
206
values();
207

208
/**
209
 * Returns an iterator for [name, value] pairs
210
 * @returns {Iterator<[string, string]>} Iterator for parameter entries
211
 */
212
entries();
213

214
/**
215
 * Makes the parameters object iterable (same as entries())
216
 * @returns {Iterator<[string, string]>} Iterator for parameter entries
217
 */
218
[Symbol.iterator]();
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
const mimeType = new MIMEType("text/html;charset=utf-8;boundary=abc123");
225

226
// forEach iteration
227
mimeType.parameters.forEach((value, name) => {
228
  console.log(`${name}: ${value}`);
229
});
230
// Output:
231
// charset: utf-8
232
// boundary: abc123
233

234
// for...of iteration (uses Symbol.iterator)
235
for (const [name, value] of mimeType.parameters) {
236
  console.log(`${name} = ${value}`);
237
}
238
// Output:
239
// charset = utf-8
240
// boundary = abc123
241

242
// Individual iterators
243
for (const name of mimeType.parameters.keys()) {
244
  console.log(`Parameter: ${name}`);
245
}
246

247
for (const value of mimeType.parameters.values()) {
248
  console.log(`Value: ${value}`);
249
}
250

251
for (const [name, value] of mimeType.parameters.entries()) {
252
  console.log(`${name}: ${value}`);
253
}
254
```
255

256
## Map Compatibility
257

258
The MIMETypeParameters class provides full compatibility with JavaScript Map operations:
259

260
```javascript
261
const mimeType = new MIMEType("text/html;charset=utf-8");
262

263
// Size property
264
console.log(mimeType.parameters.size); // 1
265

266
// Standard Map methods work as expected
267
console.log(mimeType.parameters.has("charset")); // true
268
console.log(mimeType.parameters.get("charset")); // "utf-8"
269

270
// Iteration works like Map
271
const params = Array.from(mimeType.parameters);
272
console.log(params); // [["charset", "utf-8"]]
273

274
// Convert to plain object
275
const paramsObj = Object.fromEntries(mimeType.parameters);
276
console.log(paramsObj); // { charset: "utf-8" }
277
```
278

279
## Parameter Name and Value Validation
280

281
Parameter names and values are validated according to HTTP token and quoted-string specifications:
282

283
```javascript
284
const mimeType = new MIMEType("text/html");
285

286
// Valid parameter names: HTTP token characters
287
mimeType.parameters.set("charset", "utf-8"); // ✓ Valid
288
mimeType.parameters.set("my-param", "value"); // ✓ Valid (hyphens allowed)
289
mimeType.parameters.set("param123", "value"); // ✓ Valid (numbers allowed)
290

291
// Invalid parameter names
292
try {
293
  mimeType.parameters.set("param with spaces", "value");
294
} catch (error) {
295
  // ✗ Spaces not allowed in parameter names
296
}
297

298
try {
299
  mimeType.parameters.set("param@invalid", "value");
300
} catch (error) {
301
  // ✗ @ symbol not allowed in parameter names
302
}
303

304
// Valid parameter values: HTTP quoted-string characters
305
mimeType.parameters.set("param", "simple-value"); // ✓ Valid
306
mimeType.parameters.set("param", "value with spaces"); // ✓ Valid
307
mimeType.parameters.set("param", "value/with/slashes"); // ✓ Valid
308

309
// Invalid parameter values (control characters)
310
try {
311
  mimeType.parameters.set("param", "value\x00with\x01control");
312
} catch (error) {
313
  // ✗ Control characters not allowed
314
}
315
```