@d1g1tal/transportr 1.3.2 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d1g1tal/transportr",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "JavaScript wrapper for the Fetch API",
   "type": "module",
   "exports": {
@@ -45,11 +45,11 @@
     "@skypack/package-check": "^0.2.2",
     "@xmldom/xmldom": "^0.8.10",
     "esbuild": "^0.19.3",
-    "eslint": "^8.49.0",
+    "eslint": "^8.50.0",
     "eslint-plugin-compat": "^4.2.0",
     "eslint-plugin-jsdoc": "^46.8.2",
     "jest": "^29.7.0",
-    "rimraf": "^5.0.1"
+    "rimraf": "^5.0.4"
   },
   "dependencies": {
     "@d1g1tal/chrysalis": "^1.2.3",

package/src/abort-signal.js

@@ -1,7 +1,5 @@
 import { SignalEvents, abortEvent } from './constants.js';
 
-const NativeAbortSignal = globalThis.AbortSignal;
-
 /**
  * @typedef {function(Event):void} EventListener
  * @param {Event} event The event object
@@ -22,27 +20,6 @@ export default class AbortSignal extends EventTarget {
 		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).
 	 *
@@ -61,29 +38,22 @@ export default class AbortSignal extends EventTarget {
 		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.
+	 * A value of {@link Infinity} 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) {
+	timeout(timeout) {
 		if (timeout < 0) {
 			throw new RangeError('The timeout cannot be negative');
 		}
 
-		this.#timeoutId ??= setTimeout(() => this.#abort(AbortSignal.#generateTimeoutEvent(timeout), true), timeout);
+		if (timeout != Infinity) {
+			this.#timeoutId ??= setTimeout(() => this.#abort(new CustomEvent(SignalEvents.TIMEOUT, { detail: { timeout, cause: new DOMException(`The request timed-out after ${timeout / 1000} seconds`, 'TimeoutError') } }), true), timeout);
+		}
 
 		return this.#abortController.signal;
 	}
@@ -99,38 +69,27 @@ export default class AbortSignal extends EventTarget {
 	}
 
 	/**
-	 * Adds an event listener for the specified event type.
+	 * Adds an event listener for the 'abort' event.
 	 *
-	 * @override
-	 * @param {string} eventName The name of the event to listen to
 	 * @param {EventListener} listener The listener to add
-	 * @returns {void}
+	 * @returns {AbortSignal} The AbortSignal
 	 */
-	addEventListener(eventName, listener) {
-		this.#abortController.signal.addEventListener(eventName, listener);
-	}
+	onAbort(listener) {
+		this.#abortController.signal.addEventListener(SignalEvents.ABORT, 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);
+		return this;
 	}
 
 	/**
-	 * Removes an event listener for the specified event type.
+	 * Adds an event listener for the 'timeout' event.
 	 *
-	 * @override
-	 * @param {string} eventName The name of the event to listen to
-	 * @param {EventListener} listener The listener to remove
-	 * @returns {void}
+	 * @param {EventListener} listener The listener to add
+	 * @returns {AbortSignal} The AbortSignal
 	 */
-	removeEventListener(eventName, listener) {
-		this.#abortController.signal.removeEventListener(eventName, listener);
+	onTimeout(listener) {
+		this.#abortController.signal.addEventListener(SignalEvents.TIMEOUT, listener);
+
+		return this;
 	}
 
 	/**
@@ -160,16 +119,4 @@ export default class AbortSignal extends EventTarget {
 			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

@@ -1,4 +1,5 @@
 import HttpRequestMethod from './http-request-methods.js';
+import ResponseStatus from './response-status.js';
 import { MediaType } from '@d1g1tal/media-type';
 import HttpMediaType from './http-media-type.js';
 
@@ -47,4 +48,14 @@ const _abortEvent = new CustomEvent(SignalEvents.ABORT, { detail: { cause: new D
 
 const requestBodyMethods = [ HttpRequestMethod.POST, HttpRequestMethod.PUT, HttpRequestMethod.PATCH ];
 
-export { defaultCharset, endsWithSlashRegEx, mediaTypes, RequestEvents, SignalEvents, _abortEvent as abortEvent, requestBodyMethods };
+const internalServerError = new ResponseStatus(500, 'Internal Server Error');
+
+const eventResponseStatuses = Object.freeze({
+	[RequestEvents.ABORTED]: new ResponseStatus(499, 'Aborted'),
+	[RequestEvents.TIMEOUT]: new ResponseStatus(504, 'Request Timeout')
+});
+
+/** @type {ProxyHandler<import('./transportr.js').RequestOptions>} */
+const abortSignalProxyHandler = { get: (target, property) => property == 'signal' ? target.signal.timeout(target.timeout) : Reflect.get(target, property) };
+
+export { defaultCharset, endsWithSlashRegEx, mediaTypes, RequestEvents, SignalEvents, _abortEvent as abortEvent, requestBodyMethods, internalServerError, eventResponseStatuses, abortSignalProxyHandler };

package/src/transportr.js

@@ -1,16 +1,16 @@
 import SetMultiMap from '@d1g1tal/collections/set-multi-map.js';
 import Subscribr from '@d1g1tal/subscribr';
+import AbortSignal from './abort-signal.js';
 import HttpError from './http-error.js';
 import HttpMediaType from './http-media-type.js';
 import HttpRequestHeader from './http-request-headers.js';
 import HttpRequestMethod from './http-request-methods.js';
 import HttpResponseHeader from './http-response-headers.js';
-import ResponseStatus from './response-status.js';
 import ParameterMap from './parameter-map.js';
-import AbortSignal from './abort-signal.js';
+import ResponseStatus from './response-status.js';
 import { MediaType } from '@d1g1tal/media-type';
-import { _objectMerge, _objectIsEmpty, _type } from '@d1g1tal/chrysalis';
-import { mediaTypes, endsWithSlashRegEx, RequestEvents, SignalEvents, abortEvent, requestBodyMethods } from './constants.js';
+import { _objectMerge, _type } from '@d1g1tal/chrysalis';
+import { RequestEvents, abortEvent, abortSignalProxyHandler, endsWithSlashRegEx, eventResponseStatuses, internalServerError, mediaTypes, requestBodyMethods } from './constants.js';
 
 /**
  * @template T extends ResponseBody
@@ -272,26 +272,6 @@ export default class Transportr {
 		window: null
 	});
 
-	/**
-	 * @private
-	 * @static
-	 * @type {Map<TransportrEvent, ResponseStatus>}
-	 */
-	static #eventResponseStatuses = new Map([
-		[RequestEvents.ABORTED, new ResponseStatus(499, 'Aborted')],
-		[RequestEvents.TIMEOUT, new ResponseStatus(504, 'Gateway Timeout')]
-	]);
-
-	/**
-	 * Returns a {@link AbortSignal} used for aborting requests.
-	 *
-	 * @static
-	 * @returns {AbortSignal} A new {@link AbortSignal} instance.
-	 */
-	static abortSignal() {
-		return new AbortSignal();
-	}
-
 	/**
 	 * Returns a {@link EventRegistration} used for subscribing to global events.
 	 *
@@ -597,12 +577,12 @@ export default class Transportr {
 	 * @async
 	 * @param {string} [path] The path to the endpoint you want to call.
 	 * @param {RequestOptions} [userOptions] The options passed to the public function to use for the request.
-	 * @param {RequestOptions} [options] The options for the request.
+	 * @param {RequestOptions} [options={}] The options for the request.
 	 * @param {ResponseHandler<ResponseBody>} [responseHandler] A function that will be called with the response object.
 	 * @returns {Promise<ResponseBody>} The result of the #request method.
 	 */
-	async #get(path, userOptions, options, responseHandler) {
-		return this.#request(path, userOptions, { ...options, method: HttpRequestMethod.GET }, responseHandler);
+	async #get(path, userOptions, options = {}, responseHandler) {
+		return this.#request(path, userOptions, Object.assign(options, { method: HttpRequestMethod.GET }), responseHandler);
 	}
 
 	/**
@@ -621,38 +601,30 @@ export default class Transportr {
 	async #request(path, userOptions = {}, options = {}, responseHandler) {
 		if (_type(path) == Object) { [ path, userOptions ] = [ undefined, path ] }
 
-		try {
-			options = this.#processRequestOptions(userOptions, options);
-		} catch (cause) {
-			return Promise.reject(new HttpError('Unable to process request options', { cause }));
-		}
-
-		this.#publish({ name: RequestEvents.CONFIGURED, data: options, global: options.global });
+		options = this.#processRequestOptions(userOptions, options);
 
+		let response;
 		const url = Transportr.#createUrl(this.#baseUrl, path, options.searchParams);
-		if (_type(options.signal) != AbortSignal) { options.signal = new AbortSignal(options.signal) }
-		options.signal.addEventListener(SignalEvents.ABORT, (event) => this.#publish({ name: RequestEvents.ABORTED, event, global: options.global }));
-		options.signal.addEventListener(SignalEvents.TIMEOUT, (event) => this.#publish({ name: RequestEvents.TIMEOUT, event, global: options.global }));
-
-		Transportr.#activeRequests.add(options.signal);
-
-		let response, result;
 		try {
-			// Proxy the options and trap for the signal to be accessed to start the timeout timer
-			response = await fetch(url, new Proxy(options, { get: Transportr.#requestOptionsProxyHandler(options.timeout) }));
+			Transportr.#activeRequests.add(options.signal);
+			// Proxy the options and trap for the `signal` to be accessed to start the timeout timer
+			response = await fetch(url, new Proxy(options, abortSignalProxyHandler));
 
-			if (!responseHandler && response.status != 204 && response.headers.has(HttpResponseHeader.CONTENT_TYPE)) {
+			if (!responseHandler && response.status != 204) {
 				responseHandler = this.#getResponseHandler(response.headers.get(HttpResponseHeader.CONTENT_TYPE));
 			}
 
-			result = await responseHandler?.(response) ?? response;
+			const result = await responseHandler?.(response) ?? response;
 
 			if (!response.ok) {
 				return Promise.reject(this.#handleError(url, { status: Transportr.#generateResponseStatusFromError('ResponseError', response), entity: result }));
 			}
+
 			this.#publish({ name: RequestEvents.SUCCESS, data: result, global: options.global });
-		} catch (error) {
-			return Promise.reject(this.#handleError(url, { cause: error, status: Transportr.#generateResponseStatusFromError(error.name, response) }));
+
+			return result;
+		} catch (cause) {
+			return Promise.reject(this.#handleError(url, { cause, status: Transportr.#generateResponseStatusFromError(cause.name, response) }));
 		} finally {
 			options.signal.clearTimeout();
 			if (!options.signal.aborted) {
@@ -665,8 +637,6 @@ export default class Transportr {
 				}
 			}
 		}
-
-		return result;
 	}
 
 	/**
@@ -742,23 +712,13 @@ export default class Transportr {
 			requestOptions.body = undefined;
 		}
 
-		return requestOptions;
-	}
+		requestOptions.signal = new AbortSignal(requestOptions.signal)
+			.onAbort((event) => this.#publish({ name: RequestEvents.ABORTED, event, global: requestOptions.global }))
+			.onTimeout((event) => this.#publish({ name: RequestEvents.TIMEOUT, event, global: requestOptions.global }));
 
-	/**
-	 * Returns a Proxy of the options object that traps for 'signal' access.
-	 * If the signal has not been aborted, then it will return a new signal with a timeout.
-	 *
-	 * @private
-	 * @static
-	 * @param {number} timeout The timeout in milliseconds before the signal is aborted.
-	 * @returns {Proxy<RequestOptions>} A proxy for the options object.
-	 */
-	static #requestOptionsProxyHandler(timeout) {
-		return (target, property) => {
-			const value = Reflect.get(target, property);
-			return property == 'signal' && !value.aborted ? value.withTimeout(timeout) : value;
-		};
+		this.#publish({ name: RequestEvents.CONFIGURED, data: requestOptions, global: requestOptions.global });
+
+		return requestOptions;
 	}
 
 	/**
@@ -809,9 +769,9 @@ export default class Transportr {
 	 */
 	static #generateResponseStatusFromError(errorName, response) {
 		switch (errorName) {
-			case 'AbortError': return Transportr.#eventResponseStatuses.get(RequestEvents.ABORTED);
-			case 'TimeoutError': return Transportr.#eventResponseStatuses.get(RequestEvents.TIMEOUT);
-			default: return response ? new ResponseStatus(response.status, response.statusText) : new ResponseStatus(500, 'Internal Server Error');
+			case 'AbortError': return eventResponseStatuses[RequestEvents.ABORTED];
+			case 'TimeoutError': return eventResponseStatuses[RequestEvents.TIMEOUT];
+			default: return response ? new ResponseStatus(response.status, response.statusText) : internalServerError;
 		}
 	}