Parses, serializes, and manipulates MIME types, according to the WHATWG MIME Sniffing Standard. 

Parses, serializes, and manipulates MIME types, according to the WHATWG MIME Sniffing Standard

timothygu

tmpvar

domenic

sebmaster

joris-van-der-wel

zirro

whatwg-mimetype

  "description": "Parses, serializes, and manipulates MIME types, according to the WHATWG MIME Sniffing Standard",

  "author": "Domenic Denicola <d@domenic.me> (https://domenic.me/)",

    "pretest": "node scripts/get-latest-platform-tests.js"

# Parse, serialize, and manipulate MIME types

This package will parse [MIME types](https://mimesniff.spec.whatwg.org/#understanding-mime-types) into a structured format, which can then be manipulated and serialized:

const MIMEType = require("content-type-parser");

const MIMEType = require("whatwg-mimetype");

const mimeType = new MIMEType(`Text/HTML;Charset="utf-8"`);

console.assert(mimeType.toString() === "text/html;charset=utf-8");

console.assert(mimeType.type === "text");

console.assert(mimeType.subtype === "html");

console.assert(mimeType.essence === "text/html");

console.assert(mimeType.parameters.get("charset") === "utf-8");

mimeType.parameters.set("charset", "windows-1252");

console.assert(mimeType.parameters.get("charset") === "windows-1252");

console.assert(mimeType.toString() === "text/html;charset=windows-1252");

console.assert(mimeType.isHTML() === true);

console.assert(mimeType.isXML() === false);

Parsing is a fairly complex process; see [the specification](https://mimesniff.spec.whatwg.org/#parsing-a-mime-type) for details (and similarly [for serialization](https://mimesniff.spec.whatwg.org/#serializing-a-mime-type)).

If the passed string cannot be parsed as a MIME type, the `MIMEType` constructor will throw.

This package's algorithms conform to those of the WHATWG [MIME Sniffing Standard](https://mimesniff.spec.whatwg.org/), and is aligned up to commit [cc81ec4](https://github.com/whatwg/mimesniff/commit/cc81ec48288944562c4554069da1d74a71e199fb).

This package's main module's default export is a class, `MIMEType`. Its constructor takes a string which it will attempt to parse into a MIME type; if parsing fails, an `Error` will be thrown.

- `type`: the MIME type's [type](https://mimesniff.spec.whatwg.org/#mime-type-type), e.g. `"text"`

- `subtype`: the MIME type's [subtype](https://mimesniff.spec.whatwg.org/#mime-type-subtype), e.g. `"html"`

- `essence`: the MIME type's [essence](https://mimesniff.spec.whatwg.org/#mime-type-essence), e.g. `"text/html"`

- `parameters`: an instance of `MIMETypeParameters`, containing this MIME type's [parameters](https://mimesniff.spec.whatwg.org/#mime-type-parameters)

`type` and `subtype` can be changed. They will be validated to be non-empty and only contain [HTTP token code points](https://mimesniff.spec.whatwg.org/#http-token-code-point).

`essence` is only a getter, and cannot be changed.

`parameters` is also a getter, but the contents of the `MIMETypeParameters` object are mutable, as described below.

- `toString()` serializes the MIME type to a string

- `isHTML()`: returns true if this instance represents [a HTML MIME type](https://mimesniff.spec.whatwg.org/#html-mime-type)

- `isXML()`: returns true if this instance represents [an XML MIME type](https://mimesniff.spec.whatwg.org/#xml-mime-type)

_Note: the `isHTML()` and `isXML()` methods are speculative, and may be removed or changed in future major versions. See [whatwg/mimesniff#48](https://github.com/whatwg/mimesniff/issues/48) for brainstorming in this area. Currently we implement these mainly because they are useful in jsdom._

The `MIMETypeParameters` class, instances of which are returned by `mimeType.parameters`, has equivalent surface API to a [JavaScript `Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map).

However, `MIMETypeParameters` methods will always interpret their arguments as appropriate for MIME types, so e.g. parameter names will be lowercased, and attempting to set invalid characters will throw.

const mimeType = new MIMEType(`x/x;a=b;c=D;E="F"`);

for (const [name, value] of mimeType.parameters) {

console.assert(mimeType.parameters.has("a"));

console.assert(mimeType.parameters.has("A"));

console.assert(mimeType.parameters.get("A") === "b");

console.assert(mimeType.parameters.get("q") === "X");

console.assert(mimeType.toString() === "x/x;a=b;c=d;e=F;q=X");

If you want primitives on which to build your own API, you can get direct access to the parsing and serialization algorithms as follows:

const parse = require("content-type-parser/parser");

const serialize = require("content-type-parser/serialize");

const parse = require("whatwg-mimetype/parser");

const serialize = require("whatwg-mimetype/serialize");

`parse(string)` returns an object containing the `type` and `subtype` strings, plus `parameters`, which is a `Map`. This is roughly our equivalent of the spec's [MIME type record](https://mimesniff.spec.whatwg.org/#mime-type). If parsing fails, it instead returns `null`.

`serialize(record)` operates on the such an object, giving back a string according to the serialization algorithm.

		@@ -11,3 +11,3 @@ {
		],
		"version": "2.0.0",
		"version": "2.0.1",
		"author": "Domenic Denicola <d@domenic.me> (https://domenic.me/)",
		@@ -14,0 +14,0 @@ "license": "MIT",

		@@ -6,3 +6,3 @@ # Parse, serialize, and manipulate MIME types
		```js
		const MIMEType = require("content-type-parser");
		const MIMEType = require("whatwg-mimetype");

		@@ -28,4 +28,2 @@ const mimeType = new MIMEType(`Text/HTML;Charset="utf-8"`);

		If the passed string cannot be parsed as a MIME type, the `MIMEType` constructor will throw.

		This package's algorithms conform to those of the WHATWG [MIME Sniffing Standard](https://mimesniff.spec.whatwg.org/), and is aligned up to commit [cc81ec4](https://github.com/whatwg/mimesniff/commit/cc81ec48288944562c4554069da1d74a71e199fb).
		@@ -94,4 +92,4 @@
		```js
		const parse = require("content-type-parser/parser");
		const serialize = require("content-type-parser/serialize");
		const parse = require("whatwg-mimetype/parser");
		const serialize = require("whatwg-mimetype/serialize");
		```
		@@ -98,0 +96,0 @@

Worsened metrics