@d1g1tal/transportr 1.2.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d1g1tal/transportr",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "JavaScript wrapper for the Fetch API",
   "type": "module",
   "exports": {
@@ -44,11 +44,11 @@
   "devDependencies": {
     "@skypack/package-check": "^0.2.2",
     "@xmldom/xmldom": "^0.8.10",
-    "esbuild": "^0.19.0",
-    "eslint": "^8.46.0",
-    "eslint-plugin-compat": "^4.1.4",
-    "eslint-plugin-jsdoc": "^46.4.6",
-    "jest": "^29.6.2",
+    "esbuild": "^0.19.3",
+    "eslint": "^8.49.0",
+    "eslint-plugin-compat": "^4.2.0",
+    "eslint-plugin-jsdoc": "^46.8.1",
+    "jest": "^29.7.0",
     "rimraf": "^5.0.1"
   },
   "dependencies": {

package/src/abort-signal.js

@@ -0,0 +1,175 @@
+import { SignalEvents, abortEvent } from './constants.js';
+
+const NativeAbortSignal = globalThis.AbortSignal;
+
+/**
+ * @typedef {function(Event):void} EventListener
+ * @param {Event} event The event object
+ */
+
+export default class AbortSignal extends EventTarget {
+	/** @type {AbortController} */
+	#abortController;
+	/** @type {number} */
+	#timeoutId;
+
+	/**
+	 * @param {AbortSignal} signal The signal to listen to
+	 */
+	constructor(signal) {
+		super();
+		this.#abortController = new AbortController();
+		signal?.addEventListener(SignalEvents.ABORT, (event) => this.#abort(event));
+	}
+
+	/**
+	 * Returns an {@link AbortSignal} instance that is already set as aborted.
+	 *
+	 * @static
+	 * @returns {AbortSignal} The abort signal
+	 */
+	static abort() {
+		return NativeAbortSignal.abort();
+	}
+
+	/**
+	 * Returns an AbortSignal instance that will automatically abort after a specified time.
+	 *
+	 * @static
+	 * @param {number} time The time in milliseconds to wait before aborting
+	 * @returns {AbortSignal} The abort signal
+	 */
+	static timeout(time) {
+		return NativeAbortSignal.timeout(time);
+	}
+
+	/**
+	 * The aborted property is a Boolean that indicates whether the request has been aborted (true) or not (false).
+	 *
+	 * @returns {boolean} Whether the signal was aborted or not
+	 */
+	get aborted() {
+		return this.#abortController.signal.aborted;
+	}
+
+	/**
+	 * The reason property returns a DOMException object indicating the reason the operation was aborted, or null if the operation is not aborted.
+	 *
+	 * @returns {DOMException} The reason the signal was aborted
+	 */
+	get reason() {
+		return this.#abortController.signal.reason;
+	}
+
+	/**
+	 * throws the signal's abort reason if the signal has been aborted; otherwise it does nothing.
+	 *
+	 * @returns {void}
+	 */
+	throwIfAborted() {
+		this.#abortController.signal.throwIfAborted();
+	}
+
+	/**
+	 * Returns an AbortSignal instance that will be aborted when the provided amount of milliseconds have passed.
+	 * A value of -1 (which is the default) means there is no timeout.
+	 * Note: You can't set this property to a value less than 0.
+	 *
+	 * @param {number} timeout The timeout in milliseconds
+	 * @returns {AbortSignal} The abort signal
+	 */
+	withTimeout(timeout) {
+		if (timeout < 0) {
+			throw new RangeError('The timeout cannot be negative');
+		}
+
+		this.#timeoutId ??= setTimeout(() => this.#abort(AbortSignal.#generateTimeoutEvent(timeout), true), timeout);
+
+		return this.#abortController.signal;
+	}
+
+	/**
+	 * Clears the timeout.
+	 * Note: This does not abort the signal, dispatch the timeout event, or reset the timeout.
+	 *
+	 * @returns {void}
+	 */
+	clearTimeout() {
+		clearTimeout(this.#timeoutId);
+	}
+
+	/**
+	 * Adds an event listener for the specified event type.
+	 *
+	 * @override
+	 * @param {string} eventName The name of the event to listen to
+	 * @param {EventListener} listener The listener to add
+	 * @returns {void}
+	 */
+	addEventListener(eventName, listener) {
+		this.#abortController.signal.addEventListener(eventName, listener);
+	}
+
+	/**
+	 * Dispatches an event to this EventTarget.
+	 *
+	 * @override
+	 * @param {Event} event The event to dispatch
+	 * @returns {boolean} Whether the event was dispatched or not
+	 */
+	dispatchEvent(event) {
+		return this.#abortController.signal.dispatchEvent(event);
+	}
+
+	/**
+	 * Removes an event listener for the specified event type.
+	 *
+	 * @override
+	 * @param {string} eventName The name of the event to listen to
+	 * @param {EventListener} listener The listener to remove
+	 * @returns {void}
+	 */
+	removeEventListener(eventName, listener) {
+		this.#abortController.signal.removeEventListener(eventName, listener);
+	}
+
+	/**
+	 * Aborts the signal. This is so naughty. ¯\_(ツ)_/¯
+	 *
+	 * @param {Event} event The event to abort with
+	 * @returns {void}
+	 */
+	abort(event) {
+		this.#abort(event);
+	}
+
+	/**
+	 * Aborts the signal.
+	 *
+	 * @private
+	 * @param {Event} event The event to abort with
+	 * @param {boolean} [dispatchEvent = false] Whether to dispatch the event or not
+	 * @returns {void}
+	 * @fires SignalEvents.ABORT When the signal is aborted
+	 * @fires SignalEvents.TIMEOUT When the signal times out
+	 */
+	#abort(event = abortEvent, dispatchEvent = false) {
+		clearTimeout(this.#timeoutId);
+		this.#abortController.abort(event.detail?.cause);
+		if (dispatchEvent) {
+			this.#abortController.signal.dispatchEvent(event);
+		}
+	}
+
+	/**
+	 * Generates a timeout event.
+	 *
+	 * @private
+	 * @static
+	 * @param {number} timeout The timeout in milliseconds
+	 * @returns {CustomEvent} The timeout event
+	 */
+	static #generateTimeoutEvent(timeout) {
+		return new CustomEvent(SignalEvents.TIMEOUT, { detail: { timeout, cause: new DOMException(`The request timed-out after ${timeout / 1000} seconds`, 'TimeoutError') } });
+	}
+}

package/src/constants.js

@@ -0,0 +1,50 @@
+import HttpRequestMethod from './http-request-methods.js';
+import { MediaType } from '@d1g1tal/media-type';
+import HttpMediaType from './http-media-type.js';
+
+/** @typedef {'configured'|'success'|'error'|'aborted'|'timeout'|'complete'} RequestEvent */
+
+/** @type {string} */
+const defaultCharset = 'utf-8';
+
+/** @type {RegExp} */
+const endsWithSlashRegEx = /\/$/;
+
+/** @typedef {Map<string, MediaType>} MediaTypeMap A map of media types. */
+
+/** @type {MediaTypeMap} */
+const mediaTypes = new Map([
+	[HttpMediaType.PNG, new MediaType(HttpMediaType.PNG)],
+	[HttpMediaType.TEXT, new MediaType(HttpMediaType.TEXT, { defaultCharset })],
+	[HttpMediaType.JSON, new MediaType(HttpMediaType.JSON, { defaultCharset })],
+	[HttpMediaType.HTML, new MediaType(HttpMediaType.HTML, { defaultCharset })],
+	[HttpMediaType.JAVA_SCRIPT, new MediaType(HttpMediaType.JAVA_SCRIPT, { defaultCharset })],
+	[HttpMediaType.CSS, new MediaType(HttpMediaType.CSS, { defaultCharset })],
+	[HttpMediaType.XML, new MediaType(HttpMediaType.XML, { defaultCharset })],
+	[HttpMediaType.BIN, new MediaType(HttpMediaType.BIN)]
+]);
+
+/**
+ * @static
+ * @constant {Object<string, RequestEvent>}
+ */
+const RequestEvents = Object.freeze({
+	CONFIGURED: 'configured',
+	SUCCESS: 'success',
+	ERROR: 'error',
+	ABORTED: 'aborted',
+	TIMEOUT: 'timeout',
+	COMPLETE: 'complete',
+	ALL_COMPLETE: 'all-complete'
+});
+
+const SignalEvents = Object.freeze({
+	ABORT: 'abort',
+	TIMEOUT: 'timeout'
+});
+
+const _abortEvent = new CustomEvent(SignalEvents.ABORT, { detail: { cause: new DOMException('The request was aborted', 'AbortError') } });
+
+const requestBodyMethods = [ HttpRequestMethod.POST, HttpRequestMethod.PUT, HttpRequestMethod.PATCH ];
+
+export { defaultCharset, endsWithSlashRegEx, mediaTypes, RequestEvents, SignalEvents, _abortEvent as abortEvent, requestBodyMethods };

package/src/http-media-type.js

@@ -61,6 +61,8 @@ const HttpMediaType = {
 	JSON: 'application/json',
 	/** JavaScript Object Notation LD Format */
 	JSON_LD: 'application/ld+json',
+	/** JavaScript Object Notation (JSON) Merge Patch */
+	JSON_MERGE_PATCH: 'application/merge-patch+json',
 	/** Musical Instrument Digital Interface (MIDI) */
 	MID: 'audio/midi',
 	/** Musical Instrument Digital Interface (MIDI) */

package/src/parameter-map.js

@@ -0,0 +1,221 @@
+/**
+ * @typedef {Map<string, Array<*>>} ParameterMap
+ * @extends Map
+ */
+
+/**
+ * A {@link Map} that can contain multiple, unique, values for the same key.
+ *
+ * @type {ParameterMap<string, Array<*>>}
+ */
+export default class ParameterMap extends Map {
+	/**
+	 * @param {Iterable<[string, *]>|Object} parameters The initial parameters to set.
+	 * @returns {ParameterMap<string, *>} The ParameterMap with the updated key and value.
+	 */
+	constructor(parameters = {}) {
+		super();
+		for (const [key, value] of ParameterMap.#entries(parameters)) {
+			this.append(key, value);
+		}
+	}
+
+	/**
+	 * Adds a new element with a specified key and value to the ParameterMap.
+	 * If an element with the same key already exists, the value will be replaced in the underlying {@link Set}.
+	 *
+	 * @override
+	 * @param {string} key The key to set.
+	 * @param {*} value The value to add to the ParameterMap
+	 * @returns {ParameterMap<string, *>} The ParameterMap with the updated key and value.
+	 */
+	set(key, value) {
+		const array = super.get(key);
+		if (array?.length > 0) {
+			array.length = 0;
+			array[0] = value;
+		} else {
+			super.set(key, [value]);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Adds all key-value pairs from an iterable or object to the ParameterMap.
+	 * If a key already exists, the value will be replaced in the underlying {@link Array}.
+	 *
+	 * @param {Iterable<[string, *]>|Object} parameters The parameters to set.
+	 * @returns {ParameterMap<string, *>} The ParameterMap with the updated key and value.
+	 */
+	setAll(parameters) {
+		for (const [key, value] of ParameterMap.#entries(parameters)) {
+			this.set(key, value);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Returns the value associated to the key, or undefined if there is none.
+	 * If the key has multiple values, the first value will be returned.
+	 * If the key has no values, undefined will be returned.
+	 *
+	 * @override
+	 * @param {string} key The key to get.
+	 * @returns {*} The value associated to the key, or undefined if there is none.
+	 */
+	get(key) {
+		return super.get(key)?.[0];
+	}
+
+	/**
+	 * Returns an array of all values associated to the key, or undefined if there are none.
+	 *
+	 * @param {string} key The key to get.
+	 * @returns {Array<*>} An array of all values associated to the key, or undefined if there are none.
+	 */
+	getAll(key) {
+		return super.get(key);
+	}
+
+	/**
+	 * Appends a new value to an existing key inside a ParameterMap, or adds the new key if it does not exist.
+	 *
+	 * @param {string} key The key to append.
+	 * @param {*} value The value to append.
+	 * @returns {ParameterMap<string, *>} The ParameterMap with the updated key and value to allow chaining.
+	 */
+	append(key, value) {
+		const array = super.get(key);
+		if (array?.length > 0) {
+			array.push(value);
+		} else {
+			super.set(key, [value]);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Appends all key-value pairs from an iterable or object to the ParameterMap.
+	 * If a key already exists, the value will be appended to the underlying {@link Array}.
+	 * If a key does not exist, the key and value will be added to the ParameterMap.
+	 *
+	 * @param {Iterable<[string, *]>|Object} parameters The parameters to append.
+	 * @returns {ParameterMap<string, *>} The ParameterMap with the updated key and value.
+	 */
+	appendAll(parameters) {
+		for (const [key, value] of ParameterMap.#entries(parameters)) {
+			this.append(key, value);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Checks if a specific key has a specific value.
+	 *
+	 * @param {*} value The value to check.
+	 * @returns {boolean} True if the key has the value, false otherwise.
+	 */
+	hasValue(value) {
+		for (const array of super.values()) {
+			if (array.includes(value)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Removes a specific value from a specific key.
+	 *
+	 * @param {*} value The value to remove.
+	 * @returns {boolean} True if the value was removed, false otherwise.
+	 */
+	deleteValue(value) {
+		for (const array of this.values()) {
+			if (array.includes(value)) {
+				return array.splice(array.indexOf(value), 1).length > 0;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Determines whether the ParameterMap contains anything.
+	 *
+	 * @returns {boolean} True if the ParameterMap size is greater than 0, false otherwise.
+	 */
+	isEmpty() {
+		return this.size === 0;
+	}
+
+	/**
+	 * Returns an Object that can be serialized to JSON.
+	 * If a key has only one value, the value will be a single value.
+	 * If a key has multiple values, the value will be an array of values.
+	 * If a key has no values, the value will be undefined.
+	 *
+	 * @override
+	 * @returns {Object} The Object to be serialized to JSON.
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON_behavior}
+	 */
+	toJSON() {
+		const obj = Object.create(null);
+
+		for (const [key, values] of super.entries()) {
+			obj[key] = values.length === 1 ? values[0] : values;
+		}
+
+		return obj;
+	}
+
+	/**
+	 * Returns an iterator that yields all key-value pairs in the map as arrays in their insertion order.
+	 *
+	 * @override
+	 * @yields {[string, *]} An iterator for the key-value pairs in the map.
+	 */
+	*entries() {
+		for (const [key, array] of super.entries()) {
+			for (const value of array) { yield [key, value] }
+		}
+	}
+
+	/**
+	 * Returns an iterator that yields all key-value pairs in the map as arrays in their insertion order.
+	 *
+	 * @override
+	 * @yields {[string, *]} An iterator for the key-value pairs in the map.
+	 */
+	*[Symbol.iterator]() {
+		yield* this.entries();
+	}
+
+	/**
+	 * Returns an iterable of key, value pairs for every entry in the parameters object.
+	 *
+	 * @private
+	 * @static
+	 * @param {Iterable<[string, *]>|Object} parameters The parameters to set.
+	 * @returns {Iterable<[string, *]>} An iterable of key, value pairs for every entry in the parameters object.
+	 */
+	static #entries(parameters) {
+		return parameters[Symbol.iterator] ? parameters : Object.entries(parameters);
+	}
+
+	/**
+	 * A String value that is used in the creation of the default string description of an object.
+	 * Called by the built-in method {@link Object.prototype.toString}.
+	 *
+	 * @override
+	 * @returns {string} The default string description of this object.
+	 */
+	get [Symbol.toStringTag]() {
+		return 'ParameterMap';
+	}
+}