@d1g1tal/media-type 4.0.0

package/src/media-type-parameters.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Class representing the parameters for a media type record.
+ * This class has the equivalent surface API to a JavaScript {@link Map}.
+ *
+ * However, {@link MediaTypeParameters} methods will always interpret their arguments
+ * as appropriate for media types, so parameter names will be lowercased,
+ * and attempting to set invalid characters will throw an {@link Error}.
+ *
+ * @example charset=utf-8
+ * @module MediaTypeParameters
+ */
+export default class MediaTypeParameters {
+    /**
+     * Create a new MediaTypeParameters instance.
+     *
+     * @param {Map.<string, string>} map The map of parameters for a media type.
+     */
+    constructor(map: Map<string, string>);
+    _map: Map<string, string>;
+    /**
+     * Gets the number of media type parameters.
+     *
+     * @returns {number} The number of media type parameters
+     */
+    get size(): number;
+    /**
+     * Gets the media type parameter value for the supplied name.
+     *
+     * @param {string} name The name of the media type parameter to retrieve.
+     * @returns {string} The media type parameter value.
+     */
+    get(name: string): string;
+    /**
+     * Indicates whether the media type parameter with the specified name exists or not.
+     *
+     * @param {string} name The name of the media type parameter to check.
+     * @returns {boolean} true if the media type parameter exists, false otherwise.
+     */
+    has(name: string): boolean;
+    /**
+     * Adds a new media type parameter using the specified name and value to the MediaTypeParameters.
+     * If an parameter with the same name already exists, the parameter will be updated.
+     *
+     * @param {string} name The name of the media type parameter to set.
+     * @param {string} value The media type parameter value.
+     * @returns {MediaTypeParameters} This instance.
+     */
+    set(name: string, value: string): MediaTypeParameters;
+    /**
+     * Clears all the media type parameters.
+     */
+    clear(): void;
+    /**
+     * Removes the media type parameter using the specified name.
+     *
+     * @param {string} name The name of the media type parameter to delete.
+     * @returns {boolean} true if the parameter existed and has been removed, or false if the parameter does not exist.
+     */
+    delete(name: string): boolean;
+    /**
+     * Executes a provided function once per each name/value pair in the MediaTypeParameters, in insertion order.
+     *
+     * @param {function(string, string): void} callback The function called on each iteration.
+     * @param {*} [thisArg] Optional object when binding 'this' to the callback.
+     */
+    forEach(callback: (arg0: string, arg1: string) => void, thisArg?: any): void;
+    /**
+     * Returns an iterable of parameter names.
+     *
+     * @returns {IterableIterator<string>} The {@link IterableIterator} of media type parameter names.
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Returns an iterable of parameter values.
+     *
+     * @returns {IterableIterator<string>} The {@link IterableIterator} of media type parameter values.
+     */
+    values(): IterableIterator<string>;
+    /**
+     * Returns an iterable of name, value pairs for every parameter entry in the media type parameters.
+     *
+     * @returns {IterableIterator<Array<Array<string>>>} The media type parameter entries.
+     */
+    entries(): IterableIterator<Array<Array<string>>>;
+    /**
+     * A method that returns the default iterator for the {@link MediaTypeParameters}. Called by the semantics of the for-of statement.
+     *
+     * @returns {Iterator<string, string, undefined>} The {@link Symbol.iterator} for the media type parameters.
+     */
+    [Symbol.iterator](): Iterator<string, string, undefined>;
+}

package/src/media-type-parameters.js

@@ -0,0 +1,141 @@
+import { asciiLowercase, solelyContainsHTTPQuotedStringTokenCodePoints, solelyContainsHTTPTokenCodePoints } from './utils.js';
+
+/**
+ * Class representing the parameters for a media type record.
+ * This class has the equivalent surface API to a JavaScript {@link Map}.
+ *
+ * However, {@link MediaTypeParameters} methods will always interpret their arguments
+ * as appropriate for media types, so parameter names will be lowercased,
+ * and attempting to set invalid characters will throw an {@link Error}.
+ *
+ * @example charset=utf-8
+ * @module MediaTypeParameters
+ */
+export default class MediaTypeParameters {
+	/**
+	 * Create a new MediaTypeParameters instance.
+	 *
+	 * @param {Map.<string, string>} map The map of parameters for a media type.
+	 */
+	constructor(map) {
+		this._map = map;
+	}
+
+	/**
+	 * Gets the number of media type parameters.
+	 *
+	 * @returns {number} The number of media type parameters
+	 */
+	get size() {
+		return this._map.size;
+	}
+
+	/**
+	 * Gets the media type parameter value for the supplied name.
+	 *
+	 * @param {string} name The name of the media type parameter to retrieve.
+	 * @returns {string} The media type parameter value.
+	 */
+	get(name) {
+		return this._map.get(asciiLowercase(String(name)));
+	}
+
+	/**
+	 * Indicates whether the media type parameter with the specified name exists or not.
+	 *
+	 * @param {string} name The name of the media type parameter to check.
+	 * @returns {boolean} true if the media type parameter exists, false otherwise.
+	 */
+	has(name) {
+		return this._map.has(asciiLowercase(String(name)));
+	}
+
+	/**
+	 * Adds a new media type parameter using the specified name and value to the MediaTypeParameters.
+	 * If an parameter with the same name already exists, the parameter will be updated.
+	 *
+	 * @param {string} name The name of the media type parameter to set.
+	 * @param {string} value The media type parameter value.
+	 * @returns {MediaTypeParameters} This instance.
+	 */
+	set(name, value) {
+		name = asciiLowercase(String(name));
+		value = String(value);
+
+		if (!solelyContainsHTTPTokenCodePoints(name)) {
+			throw new Error(`Invalid media type parameter name "${name}": only HTTP token code points are valid.`);
+		}
+
+		if (!solelyContainsHTTPQuotedStringTokenCodePoints(value)) {
+			throw new Error(`Invalid media type parameter value "${value}": only HTTP quoted-string token code points are valid.`);
+		}
+
+		this._map.set(name, value);
+
+		return this;
+	}
+
+	/**
+	 * Clears all the media type parameters.
+	 */
+	clear() {
+		this._map.clear();
+	}
+
+	/**
+	 * Removes the media type parameter using the specified name.
+	 *
+	 * @param {string} name The name of the media type parameter to delete.
+	 * @returns {boolean} true if the parameter existed and has been removed, or false if the parameter does not exist.
+	 */
+	delete(name) {
+		name = asciiLowercase(String(name));
+		return this._map.delete(name);
+	}
+
+	/**
+	 * Executes a provided function once per each name/value pair in the MediaTypeParameters, in insertion order.
+	 *
+	 * @param {function(string, string): void} callback The function called on each iteration.
+	 * @param {*} [thisArg] Optional object when binding 'this' to the callback.
+	 */
+	forEach(callback, thisArg) {
+		this._map.forEach(callback, thisArg);
+	}
+
+	/**
+	 * Returns an iterable of parameter names.
+	 *
+	 * @returns {IterableIterator<string>} The {@link IterableIterator} of media type parameter names.
+	 */
+	keys() {
+		return this._map.keys();
+	}
+
+	/**
+	 * Returns an iterable of parameter values.
+	 *
+	 * @returns {IterableIterator<string>} The {@link IterableIterator} of media type parameter values.
+	 */
+	values() {
+		return this._map.values();
+	}
+
+	/**
+	 * Returns an iterable of name, value pairs for every parameter entry in the media type parameters.
+	 *
+	 * @returns {IterableIterator<Array<Array<string>>>} The media type parameter entries.
+	 */
+	entries() {
+		return this._map.entries();
+	}
+
+	/**
+	 * A method that returns the default iterator for the {@link MediaTypeParameters}. Called by the semantics of the for-of statement.
+	 *
+	 * @returns {Iterator<string, string, undefined>} The {@link Symbol.iterator} for the media type parameters.
+	 */
+	[Symbol.iterator]() {
+		return this._map[Symbol.iterator]();
+	}
+}

package/src/media-type.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Class used to parse media types.
+ *
+ * @see https://mimesniff.spec.whatwg.org/#understanding-mime-types
+ * @module MediaType
+ */
+export default class MediaType {
+    /**
+     * Static factor method for parsing a media type.
+     *
+     * @param {string} string The media type to parse
+     * @returns {MediaType} The parsed {@link MediaType} object
+     */
+    static parse(string: string): MediaType;
+    /**
+     * Create a new MediaType instance from a string representation.
+     *
+     * @param {string} string The media type to parse
+     */
+    constructor(string: string);
+    _type: string;
+    _subtype: string;
+    _parameters: MediaTypeParameters;
+    /**
+     * Gets the media type essence (type/subtype).
+     *
+     * @returns {string} The media type without any parameters
+     */
+    get essence(): string;
+    /**
+     * Sets the type.
+     */
+    set type(arg: string);
+    /**
+     * Gets the type.
+     *
+     * @returns {string} The type.
+     */
+    get type(): string;
+    /**
+     * Sets the subtype.
+     */
+    set subtype(arg: string);
+    /**
+     * Gets the subtype.
+     *
+     * @returns {string} The subtype.
+     */
+    get subtype(): string;
+    /**
+     * Gets the parameters.
+     *
+     * @returns {MediaTypeParameters} The media type parameters.
+     */
+    get parameters(): MediaTypeParameters;
+    /**
+     * Gets the serialized version of the media type.
+     *
+     * @returns {string} The serialized media type.
+     */
+    toString(): string;
+    /**
+     * Determines if this instance is a JavaScript media type.
+     *
+     * @param {Object} [options] Optional options.
+     * @param {boolean} [options.prohibitParameters=false] The option to prohibit parameters when checking if the media type is JavaScript.
+     * @returns {boolean} true if this instance represents a JavaScript media type, false otherwise.
+     */
+    isJavaScript({ prohibitParameters }?: {
+        prohibitParameters?: boolean;
+    }): boolean;
+    /**
+     * Determines if this instance is an XML media type.
+     *
+     * @returns {boolean} true if this instance represents an XML media type, false otherwise.
+     */
+    isXML(): boolean;
+    /**
+     * Determines if this instance is an HTML media type.
+     *
+     * @returns {boolean} true if this instance represents an HTML media type, false otherwise.
+     */
+    isHTML(): boolean;
+    /**
+     * Gets the name of the class.
+     *
+     * @returns {string} The class name
+     */
+    get [Symbol.toStringTag](): string;
+}
+import MediaTypeParameters from "./media-type-parameters.js";

package/src/media-type.js

@@ -0,0 +1,188 @@
+import MediaTypeParameters from './media-type-parameters.js';
+import parse from './parser.js';
+import serialize from './serializer.js';
+import { asciiLowercase, solelyContainsHTTPTokenCodePoints } from './utils.js';
+
+/**
+ * Class used to parse media types.
+ *
+ * @see https://mimesniff.spec.whatwg.org/#understanding-mime-types
+ * @module MediaType
+ */
+export default class MediaType {
+	/**
+	 * Create a new MediaType instance from a string representation.
+	 *
+	 * @param {string} string The media type to parse
+	 */
+	constructor(string) {
+		string = String(string);
+		const result = parse(string);
+		if (result === null) {
+			throw new Error(`Could not parse media type string '${string}'`);
+		}
+
+		this._type = result.type;
+		this._subtype = result.subtype;
+		this._parameters = new MediaTypeParameters(result.parameters);
+	}
+
+	/**
+	 * Static factor method for parsing a media type.
+	 *
+	 * @param {string} string The media type to parse
+	 * @returns {MediaType} The parsed {@link MediaType} object
+	 */
+	static parse(string) {
+		try {
+			return new this(string);
+		} catch (e) {
+			return null;
+		}
+	}
+
+	/**
+	 * Gets the media type essence (type/subtype).
+	 *
+	 * @returns {string} The media type without any parameters
+	 */
+	get essence() {
+		return `${this.type}/${this.subtype}`;
+	}
+
+	/**
+	 * Gets the type.
+	 *
+	 * @returns {string} The type.
+	 */
+	get type() {
+		return this._type;
+	}
+
+	/**
+	 * Sets the type.
+	 */
+	set type(value) {
+		value = asciiLowercase(String(value));
+
+		if (value.length === 0) {
+			throw new Error('Invalid type: must be a non-empty string');
+		}
+		if (!solelyContainsHTTPTokenCodePoints(value)) {
+			throw new Error(`Invalid type ${value}: must contain only HTTP token code points`);
+		}
+
+		this._type = value;
+	}
+
+	/**
+	 * Gets the subtype.
+	 *
+	 * @returns {string} The subtype.
+	 */
+	get subtype() {
+		return this._subtype;
+	}
+
+	/**
+	 * Sets the subtype.
+	 */
+	set subtype(value) {
+		value = asciiLowercase(String(value));
+
+		if (value.length === 0) {
+			throw new Error('Invalid subtype: must be a non-empty string');
+		}
+		if (!solelyContainsHTTPTokenCodePoints(value)) {
+			throw new Error(`Invalid subtype ${value}: must contain only HTTP token code points`);
+		}
+
+		this._subtype = value;
+	}
+
+	/**
+	 * Gets the parameters.
+	 *
+	 * @returns {MediaTypeParameters} The media type parameters.
+	 */
+	get parameters() {
+		return this._parameters;
+	}
+
+	/**
+	 * Gets the serialized version of the media type.
+	 *
+	 * @returns {string} The serialized media type.
+	 */
+	toString() {
+		// The serialize function works on both 'media type records' (i.e. the results of parse) and on this class, since
+		// this class's interface is identical.
+		return serialize(this);
+	}
+
+	/**
+	 * Determines if this instance is a JavaScript media type.
+	 *
+	 * @param {Object} [options] Optional options.
+	 * @param {boolean} [options.prohibitParameters=false] The option to prohibit parameters when checking if the media type is JavaScript.
+	 * @returns {boolean} true if this instance represents a JavaScript media type, false otherwise.
+	 */
+	isJavaScript({prohibitParameters = false} = {}) {
+		switch (this._type) {
+			case 'text': {
+				switch (this._subtype) {
+					case 'ecmascript':
+					case 'javascript':
+					case 'javascript1.0':
+					case 'javascript1.1':
+					case 'javascript1.2':
+					case 'javascript1.3':
+					case 'javascript1.4':
+					case 'javascript1.5':
+					case 'jscript':
+					case 'livescript':
+					case 'x-ecmascript':
+					case 'x-javascript': return !prohibitParameters || this._parameters.size === 0;
+					default: return false;
+				}
+			}
+			case 'application': {
+				switch (this._subtype) {
+					case 'ecmascript':
+					case 'javascript':
+					case 'x-ecmascript':
+					case 'x-javascript': return !prohibitParameters || this._parameters.size === 0;
+					default: return false;
+				}
+			}
+			default: return false;
+		}
+	}
+
+	/**
+	 * Determines if this instance is an XML media type.
+	 *
+	 * @returns {boolean} true if this instance represents an XML media type, false otherwise.
+	 */
+	isXML() {
+		return (this._subtype === 'xml' && (this._type === 'text' || this._type === 'application')) || this._subtype.endsWith('+xml');
+	}
+
+	/**
+	 * Determines if this instance is an HTML media type.
+	 *
+	 * @returns {boolean} true if this instance represents an HTML media type, false otherwise.
+	 */
+	isHTML() {
+		return this._subtype === 'html' && this._type === 'text';
+	}
+
+	/**
+	 * Gets the name of the class.
+	 *
+	 * @returns {string} The class name
+	 */
+	get [Symbol.toStringTag]() {
+		return 'MediaType';
+	}
+}

package/src/parser.d.ts

@@ -0,0 +1,13 @@
+export default parse;
+/**
+ * Function to parse a media type.
+ *
+ * @module parser
+ * @param {string} input The media type to parse
+ * @returns {{ type: string, subtype: string, parameters: Map<string, string> }} An object populated with the parsed media type properties and any parameters.
+ */
+declare function parse(input: string): {
+    type: string;
+    subtype: string;
+    parameters: Map<string, string>;
+};

package/src/parser.js

@@ -0,0 +1,109 @@
+import {
+	asciiLowercase,
+	collectAnHTTPQuotedString, isHTTPWhitespaceChar, removeLeadingAndTrailingHTTPWhitespace,
+	removeTrailingHTTPWhitespace, solelyContainsHTTPQuotedStringTokenCodePoints, solelyContainsHTTPTokenCodePoints
+} from './utils.js';
+
+/**
+ * Function to parse a media type.
+ *
+ * @module parser
+ * @param {string} input The media type to parse
+ * @returns {{ type: string, subtype: string, parameters: Map<string, string> }} An object populated with the parsed media type properties and any parameters.
+ */
+const parse = (input) => {
+	input = removeLeadingAndTrailingHTTPWhitespace(input);
+
+	let position = 0;
+	let type = '';
+	while (position < input.length && input[position] !== '/') {
+		type += input[position];
+		++position;
+	}
+
+	if (type.length === 0 || !solelyContainsHTTPTokenCodePoints(type)) {
+		return null;
+	}
+
+	if (position >= input.length) {
+		return null;
+	}
+
+	// Skips past "/"
+	++position;
+
+	let subtype = '';
+	while (position < input.length && input[position] !== ';') {
+		subtype += input[position];
+		++position;
+	}
+
+	subtype = removeTrailingHTTPWhitespace(subtype);
+
+	if (subtype.length === 0 || !solelyContainsHTTPTokenCodePoints(subtype)) {
+		return null;
+	}
+
+	const mediaType = {
+		type: asciiLowercase(type),
+		subtype: asciiLowercase(subtype),
+		parameters: new Map()
+	};
+
+	while (position < input.length) {
+		// Skip past ";"
+		++position;
+
+		while (isHTTPWhitespaceChar(input[position])) {
+			++position;
+		}
+
+		let parameterName = '';
+		while (position < input.length && input[position] !== ';' && input[position] !== '=') {
+			parameterName += input[position];
+			++position;
+		}
+		parameterName = asciiLowercase(parameterName);
+
+		if (position < input.length) {
+			if (input[position] === ';') {
+				continue;
+			}
+
+			// Skip past "="
+			++position;
+		}
+
+		let parameterValue = null;
+		if (input[position] === '"') {
+			[parameterValue, position] = collectAnHTTPQuotedString(input, position);
+
+			while (position < input.length && input[position] !== ';') {
+				++position;
+			}
+		} else {
+			parameterValue = '';
+			while (position < input.length && input[position] !== ';') {
+				parameterValue += input[position];
+				++position;
+			}
+
+			parameterValue = removeTrailingHTTPWhitespace(parameterValue);
+
+			if (parameterValue === '') {
+				continue;
+			}
+		}
+
+		if (parameterName.length > 0 &&
+			solelyContainsHTTPTokenCodePoints(parameterName) &&
+			solelyContainsHTTPQuotedStringTokenCodePoints(parameterValue) &&
+			!mediaType.parameters.has(parameterName)) {
+			mediaType.parameters.set(parameterName, parameterValue);
+		}
+	}
+
+	return mediaType;
+};
+
+export default parse;

package/src/serializer.d.ts

@@ -0,0 +1,11 @@
+export default serialize;
+export type MediaType = import('./media-type.js').default;
+/** @typedef { import('./media-type.js').default } MediaType */
+/**
+ * A function that serializes the provided {@link mediaType} to a string.
+ *
+ * @module serializer
+ * @param {MediaType} mediaType The media type to serialize.
+ * @returns {string} The serialized media type.
+ */
+declare function serialize(mediaType: MediaType): string;

package/src/serializer.js

@@ -0,0 +1,35 @@
+import { solelyContainsHTTPTokenCodePoints } from './utils.js';
+// eslint-disable-next-line jsdoc/valid-types
+/** @typedef { import('./media-type.js').default } MediaType */
+
+/**
+ * A function that serializes the provided {@link mediaType} to a string.
+ *
+ * @module serializer
+ * @param {MediaType} mediaType The media type to serialize.
+ * @returns {string} The serialized media type.
+ */
+const serialize = (mediaType) => {
+	let serialization = `${mediaType.type}/${mediaType.subtype}`;
+
+	if (mediaType.parameters.size === 0) {
+		return serialization;
+	}
+
+	for (let [name, value] of mediaType.parameters) {
+		serialization += ';';
+		serialization += name;
+		serialization += '=';
+
+		if (!solelyContainsHTTPTokenCodePoints(value) || value.length === 0) {
+			value = value.replace(/(["\\])/ug, '\\$1');
+			value = `"${value}"`;
+		}
+
+		serialization += value;
+	}
+
+	return serialization;
+};
+
+export default serialize;