Skip to content

Commit d41f8ff

Browse files
bmeckTrottaduh95
authored and
RafaelGSS
committed
util: add MIME utilities (#21128)
Co-authored-by: Rich Trott <[email protected]> Co-authored-by: Antoine du Hamel <[email protected]> PR-URL: #21128 Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Robert Nagy <[email protected]> Reviewed-By: Jacob Smith <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 9ed9aa8 commit d41f8ff

16 files changed

+5123
-17
lines changed

‎doc/api/errors.md

+6
Original file line numberDiff line numberDiff line change
@@ -1967,6 +1967,12 @@ An invalid HTTP token was supplied.
19671967

19681968
An IP address is not valid.
19691969

1970+
<a id="ERR_INVALID_MIME_SYNTAX"></a>
1971+
1972+
### `ERR_INVALID_MIME_SYNTAX`
1973+
1974+
The syntax of a MIME is not valid.
1975+
19701976
<a id="ERR_INVALID_MODULE"></a>
19711977

19721978
### `ERR_INVALID_MODULE`

‎doc/api/util.md

+353
Original file line numberDiff line numberDiff line change
@@ -1024,6 +1024,355 @@ Otherwise, returns `false`.
10241024
See [`assert.deepStrictEqual()`][] for more information about deep strict
10251025
equality.
10261026

1027+
## Class: `util.MIMEType`
1028+
1029+
<!-- YAML
1030+
added: REPLACEME
1031+
-->
1032+
1033+
> Stability: 1 - Experimental
1034+
1035+
An implementation of [the MIMEType class](https://bmeck.github.io/node-proposal-mime-api/).
1036+
1037+
In accordance with browser conventions, all properties of `MIMEType` objects
1038+
are implemented as getters and setters on the class prototype, rather than as
1039+
data properties on the object itself.
1040+
1041+
A MIME string is a structured string containing multiple meaningful
1042+
components. When parsed, a `MIMEType` object is returned containing
1043+
properties for each of these components.
1044+
1045+
### Constructor: `new MIMEType(input)`
1046+
1047+
* `input` {string} The input MIME to parse
1048+
1049+
Creates a new `MIMEType` object by parsing the `input`.
1050+
1051+
```mjs
1052+
import { MIMEType } from 'node:util';
1053+
1054+
const myMIME = new MIMEType('text/plain');
1055+
```
1056+
1057+
```cjs
1058+
const { MIMEType } = require('node:util');
1059+
1060+
const myMIME = new MIMEType('text/plain');
1061+
```
1062+
1063+
A `TypeError` will be thrown if the `input` is not a valid MIME. Note
1064+
that an effort will be made to coerce the given values into strings. For
1065+
instance:
1066+
1067+
```mjs
1068+
import { MIMEType } from 'node:util';
1069+
const myMIME = new MIMEType({ toString: () => 'text/plain' });
1070+
console.log(String(myMIME));
1071+
// Prints: text/plain
1072+
```
1073+
1074+
```cjs
1075+
const { MIMEType } = require('node:util');
1076+
const myMIME = new MIMEType({ toString: () => 'text/plain' });
1077+
console.log(String(myMIME));
1078+
// Prints: text/plain
1079+
```
1080+
1081+
#### `mime.type`
1082+
1083+
* {string}
1084+
1085+
Gets and sets the type portion of the MIME.
1086+
1087+
```mjs
1088+
import { MIMEType } from 'node:util';
1089+
1090+
const myMIME = new MIMEType('text/javascript');
1091+
console.log(myMIME.type);
1092+
// Prints: text
1093+
myMIME.type = 'application';
1094+
console.log(myMIME.type);
1095+
// Prints: application
1096+
console.log(String(myMIME));
1097+
// Prints: application/javascript
1098+
```
1099+
1100+
```cjs
1101+
const { MIMEType } = require('node:util');
1102+
1103+
const myMIME = new MIMEType('text/javascript');
1104+
console.log(myMIME.type);
1105+
// Prints: text
1106+
myMIME.type = 'application';
1107+
console.log(myMIME.type);
1108+
// Prints: application
1109+
console.log(String(myMIME));
1110+
// Prints: application/javascript/javascript
1111+
```
1112+
1113+
#### `mime.subtype`
1114+
1115+
* {string}
1116+
1117+
Gets and sets the subtype portion of the MIME.
1118+
1119+
```mjs
1120+
import { MIMEType } from 'node:util';
1121+
1122+
const myMIME = new MIMEType('text/ecmascript');
1123+
console.log(myMIME.subtype);
1124+
// Prints: ecmascript
1125+
myMIME.subtype = 'javascript';
1126+
console.log(myMIME.subtype);
1127+
// Prints: javascript
1128+
console.log(String(myMIME));
1129+
// Prints: text/javascript
1130+
```
1131+
1132+
```cjs
1133+
const { MIMEType } = require('node:util');
1134+
1135+
const myMIME = new MIMEType('text/ecmascript');
1136+
console.log(myMIME.subtype);
1137+
// Prints: ecmascript
1138+
myMIME.subtype = 'javascript';
1139+
console.log(myMIME.subtype);
1140+
// Prints: javascript
1141+
console.log(String(myMIME));
1142+
// Prints: text/javascript
1143+
```
1144+
1145+
#### `mime.essence`
1146+
1147+
* {string}
1148+
1149+
Gets the essence of the MIME. This property is read only.
1150+
Use `mime.type` or `mime.subtype` to alter the MIME.
1151+
1152+
```mjs
1153+
import { MIMEType } from 'node:util';
1154+
1155+
const myMIME = new MIMEType('text/javascript;key=value');
1156+
console.log(myMIME.essence);
1157+
// Prints: text/javascript
1158+
myMIME.type = 'application';
1159+
console.log(myMIME.essence);
1160+
// Prints: application/javascript
1161+
console.log(String(myMIME));
1162+
// Prints: application/javascript;key=value
1163+
```
1164+
1165+
```cjs
1166+
const { MIMEType } = require('node:util');
1167+
1168+
const myMIME = new MIMEType('text/javascript;key=value');
1169+
console.log(myMIME.essence);
1170+
// Prints: text/javascript
1171+
myMIME.type = 'application';
1172+
console.log(myMIME.essence);
1173+
// Prints: application/javascript
1174+
console.log(String(myMIME));
1175+
// Prints: application/javascript;key=value
1176+
```
1177+
1178+
#### `mime.params`
1179+
1180+
* {MIMEParams}
1181+
1182+
Gets the [`MIMEParams`][] object representing the
1183+
parameters of the MIME. This property is read-only. See
1184+
[`MIMEParams`][] documentation for details.
1185+
1186+
#### `mime.toString()`
1187+
1188+
* Returns: {string}
1189+
1190+
The `toString()` method on the `MIMEType` object returns the serialized MIME.
1191+
1192+
Because of the need for standard compliance, this method does not allow users
1193+
to customize the serialization process of the MIME.
1194+
1195+
#### `mime.toJSON()`
1196+
1197+
* Returns: {string}
1198+
1199+
Alias for [`mime.toString()`][].
1200+
1201+
This method is automatically called when an `MIMEType` object is serialized
1202+
with [`JSON.stringify()`][].
1203+
1204+
```mjs
1205+
import { MIMEType } from 'node:util';
1206+
1207+
const myMIMES = [
1208+
new MIMEType('image/png'),
1209+
new MIMEType('image/gif'),
1210+
];
1211+
console.log(JSON.stringify(myMIMES));
1212+
// Prints: ["image/png", "image/gif"]
1213+
```
1214+
1215+
```cjs
1216+
const { MIMEType } = require('node:util');
1217+
1218+
const myMIMES = [
1219+
new MIMEType('image/png'),
1220+
new MIMEType('image/gif'),
1221+
];
1222+
console.log(JSON.stringify(myMIMES));
1223+
// Prints: ["image/png", "image/gif"]
1224+
```
1225+
1226+
### Class: `util.MIMEParams`
1227+
1228+
<!-- YAML
1229+
added: REPLACEME
1230+
-->
1231+
1232+
The `MIMEParams` API provides read and write access to the parameters of a
1233+
`MIMEType`.
1234+
1235+
#### Constructor: `new MIMEParams()`
1236+
1237+
Creates a new `MIMEParams` object by with empty parameters
1238+
1239+
```mjs
1240+
import { MIMEParams } from 'node:util';
1241+
1242+
const myParams = new MIMEParams();
1243+
```
1244+
1245+
```cjs
1246+
const { MIMEParams } = require('node:util');
1247+
1248+
const myParams = new MIMEParams();
1249+
```
1250+
1251+
#### `mimeParams.delete(name)`
1252+
1253+
* `name` {string}
1254+
1255+
Remove all name-value pairs whose name is `name`.
1256+
1257+
#### `mimeParams.entries()`
1258+
1259+
* Returns: {Iterator}
1260+
1261+
Returns an iterator over each of the name-value pairs in the parameters.
1262+
Each item of the iterator is a JavaScript `Array`. The first item of the array
1263+
is the `name`, the second item of the array is the `value`.
1264+
1265+
#### `mimeParams.get(name)`
1266+
1267+
* `name` {string}
1268+
* Returns: {string} or `null` if there is no name-value pair with the given
1269+
`name`.
1270+
1271+
Returns the value of the first name-value pair whose name is `name`. If there
1272+
are no such pairs, `null` is returned.
1273+
1274+
#### `mimeParams.has(name)`
1275+
1276+
* `name` {string}
1277+
* Returns: {boolean}
1278+
1279+
Returns `true` if there is at least one name-value pair whose name is `name`.
1280+
1281+
#### `mimeParams.keys()`
1282+
1283+
* Returns: {Iterator}
1284+
1285+
Returns an iterator over the names of each name-value pair.
1286+
1287+
```mjs
1288+
import { MIMEType } from 'node:util';
1289+
1290+
const { params } = new MIMEType('text/plain;foo=0;bar=1');
1291+
for (const name of params.keys()) {
1292+
console.log(name);
1293+
}
1294+
// Prints:
1295+
// foo
1296+
// bar
1297+
```
1298+
1299+
```cjs
1300+
const { MIMEType } = require('node:util');
1301+
1302+
const { params } = new MIMEType('text/plain;foo=0;bar=1');
1303+
for (const name of params.keys()) {
1304+
console.log(name);
1305+
}
1306+
// Prints:
1307+
// foo
1308+
// bar
1309+
```
1310+
1311+
#### `mimeParams.set(name, value)`
1312+
1313+
* `name` {string}
1314+
* `value` {string}
1315+
1316+
Sets the value in the `MIMEParams` object associated with `name` to
1317+
`value`. If there are any pre-existing name-value pairs whose names are `name`,
1318+
set the first such pair's value to `value`.
1319+
1320+
```mjs
1321+
import { MIMEType } from 'node:util';
1322+
1323+
const { params } = new MIMEType('text/plain;foo=0;bar=1');
1324+
params.set('foo', 'def');
1325+
params.set('baz', 'xyz');
1326+
console.log(params.toString());
1327+
// Prints: foo=def&bar=1&baz=xyz
1328+
```
1329+
1330+
```cjs
1331+
const { MIMEType } = require('node:util');
1332+
1333+
const { params } = new MIMEType('text/plain;foo=0;bar=1');
1334+
params.set('foo', 'def');
1335+
params.set('baz', 'xyz');
1336+
console.log(params.toString());
1337+
// Prints: foo=def&bar=1&baz=xyz
1338+
```
1339+
1340+
#### `mimeParams.values()`
1341+
1342+
* Returns: {Iterator}
1343+
1344+
Returns an iterator over the values of each name-value pair.
1345+
1346+
#### `mimeParams[@@iterator]()`
1347+
1348+
* Returns: {Iterator}
1349+
1350+
Alias for [`mimeParams.entries()`][].
1351+
1352+
```mjs
1353+
import { MIMEType } from 'node:util';
1354+
1355+
const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
1356+
for (const [name, value] of params) {
1357+
console.log(name, value);
1358+
}
1359+
// Prints:
1360+
// foo bar
1361+
// xyz baz
1362+
```
1363+
1364+
```cjs
1365+
const { MIMEType } = require('node:util');
1366+
1367+
const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
1368+
for (const [name, value] of params) {
1369+
console.log(name, value);
1370+
}
1371+
// Prints:
1372+
// foo bar
1373+
// xyz baz
1374+
```
1375+
10271376
## `util.parseArgs([config])`
10281377

10291378
<!-- YAML
@@ -2903,6 +3252,8 @@ util.log('Timestamped message.');
29033252
[`Int16Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int16Array
29043253
[`Int32Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int32Array
29053254
[`Int8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int8Array
3255+
[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
3256+
[`MIMEparams`]: #class-utilmimeparams
29063257
[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
29073258
[`Object.assign()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
29083259
[`Object.freeze()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze
@@ -2920,6 +3271,8 @@ util.log('Timestamped message.');
29203271
[`WebAssembly.Module`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module
29213272
[`assert.deepStrictEqual()`]: assert.md#assertdeepstrictequalactual-expected-message
29223273
[`console.error()`]: console.md#consoleerrordata-args
3274+
[`mime.toString()`]: #mimetostring
3275+
[`mimeParams.entries()`]: #mimeparamsentries
29233276
[`napi_create_external()`]: n-api.md#napi_create_external
29243277
[`target` and `handler`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy#Terminology
29253278
[`tty.hasColors()`]: tty.md#writestreamhascolorscount-env

0 commit comments

Comments
 (0)