@hkdigital/lib-sveltekit 0.0.59 → 0.0.61

package/dist/util/http/http-request.js

@@ -0,0 +1,259 @@
+import { METHOD_GET, METHOD_POST } from '../../constants/http/methods.js';
+
+import { APPLICATION_JSON } from '../../constants/mime/application.js';
+import { CONTENT_TYPE } from '../../constants/http/headers.js';
+
+import { AbortError, TimeoutError } from '../../constants/errors/api.js';
+
+import * as expect from '../expect/index.js';
+
+import { toURL } from './url.js';
+import { setRequestHeaders } from './headers.js';
+import { waitForAndCheckResponse } from './response.js';
+
+/**
+ * Make GET request
+ *
+ * @param {string|URL} url - Url string or URL object
+ *
+ * @param {object} [urlSearchParams]
+ *   Parameters that should be added to the request url
+ *
+ * @param {object} [headers]
+ *   Object that contains custom headers. A header is a name, value pair.
+ *
+ *   e.g. options.headers = { "content-type": "application/json" }
+ *
+ * @param {function} [requestHandler]
+ *   If defined, this function will receive the abort handler function
+ *
+ * @param {number} [timeoutMs]
+ *   If defined, this request will abort after the specified number of
+ *   milliseconds. Values above the the built-in request timeout won't work.
+ *
+ * @returns {Promise<*>} responsePromise
+ */
+export async function httpGet({ url, urlSearchParams, headers, requestHandler, timeoutMs }) {
+	const responsePromise = httpRequest({
+		method: METHOD_GET,
+		url,
+		urlSearchParams,
+		headers,
+		requestHandler,
+		timeoutMs
+	});
+
+	return await waitForAndCheckResponse(responsePromise, url);
+}
+
+/**
+ * Make POST request
+ *
+ * @param {string|URL} url - Url string or URL object
+ *
+ * @param {any} [body] - POST data
+ *
+ * @param {object} [headers]
+ *   Object that contains custom headers. A header is a name, value pair.
+ *
+ *   e.g. options.headers = { "content-type": "application/json" }
+ *
+ * @param {function} [requestHandler]
+ *   If defined, this function will receive the abort handler function
+ *
+ * @param {number} [timeoutMs]
+ *   If defined, this request will abort after the specified number of
+ *   milliseconds. Values above the the built-in request timeout won't work.
+ *
+ * @returns {Promise<*>} responsePromise
+ */
+export async function httpPost({ url, body = null, headers, requestHandler, timeoutMs }) {
+	const responsePromise = httpRequest({
+		method: METHOD_POST,
+		url,
+		body,
+		headers,
+		requestHandler,
+		timeoutMs
+	});
+
+	return await waitForAndCheckResponse(responsePromise, url);
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Make an HTTP request
+ * - This is a low level function, consider using
+ *   httpGet, httpPost, jsonGet or jsonPost instead
+ *
+ * @param {string|URL} url - Url string or URL object
+ *
+ * @param {string} method - Request method: METHOD_GET | METHOD_POST
+ *
+ * @param {object} [urlSearchParams] - URL search parameters as key-value pairs
+ *
+ * @param {any} [body] - POST data
+ *
+ * @param {object} [headers]
+ *   Object that contains custom headers. A header is a name, value pair.
+ *
+ *   e.g. options.headers = { "content-type": "application/json" }
+ *
+ * @param {function} [requestHandler]
+ *   If defined, this function will receive the abort handler function
+ *
+ * @param {number} [timeoutMs]
+ *   If defined, this request will abort after the specified number of
+ *   milliseconds. Values above the the built-in request timeout won't work.
+ *
+ * @throws TypeError - If a network error occurred
+ *
+ * @note Check the `ok` property of the resolved response to check if the
+ *       response was successfull (e.g. in case of a 404, ok is false)
+ *
+ * @returns {Promise<*>} responsePromise
+ */
+export async function httpRequest({
+	method,
+	url,
+	urlSearchParams = null,
+	body = null,
+	headers,
+	requestHandler,
+	timeoutMs
+}) {
+	url = toURL(url);
+
+	// @see https://developer.mozilla.org/en-US/docs/Web/API/Headers
+
+	const requestHeaders = new Headers();
+
+	if (headers) {
+		setRequestHeaders(requestHeaders, headers);
+
+		if (headers[CONTENT_TYPE] === APPLICATION_JSON && typeof body !== 'string') {
+			throw new Error(
+				`Trying to send request with [content-type:${APPLICATION_JSON}], ` +
+					'but body is not a (JSON encoded) string.'
+			);
+		}
+		// IDEA: try to decode the body to catch errors on client side
+	}
+
+	const init = {
+		mode: 'cors',
+		cache: 'no-cache',
+		credentials: 'omit',
+		redirect: 'follow',
+		referrerPolicy: 'no-referrer',
+		headers: requestHeaders
+	};
+
+	// Allow search params also for other request types than GET
+
+	if (urlSearchParams) {
+		if (!(urlSearchParams instanceof URLSearchParams)) {
+			throw new Error(
+				'Invalid parameter [urlSearchParams] ' + '(expected instanceof URLSearchParams)'
+			);
+		}
+
+		const existingParams = url.searchParams;
+
+		for (const [name, value] of urlSearchParams.entries()) {
+			if (existingParams.has(name)) {
+				throw new Error(
+					`Cannot set URL search parameter [${name}] ` + `in url [${url.href}] (already set)`
+				);
+			}
+
+			existingParams.set(name, value);
+		} // end for
+	}
+
+	//
+	// Sort search params to make the url nicer
+	//
+	url.searchParams.sort();
+
+	// console.log( "url", url );
+
+	init.method = method;
+
+	if (METHOD_POST === method) {
+		init.body = body || null; /* : JSON.stringify( body ) */
+	}
+
+	// @see https://developer.mozilla.org/en-US/docs/Web/API/Request/Request
+
+	// console.log( "init", init );
+	// console.log( "headers", init.headers );
+
+	const request = new Request(url, init);
+
+	// @see https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort
+
+	const controller = new AbortController();
+	const signal = controller.signal;
+
+	//
+	// A fetch() promise will reject with a TypeError when a network error
+	// is encountered or CORS is misconfigured on the server-side,
+	// although this usually means permission issues or similar
+	// — a 404 does not constitute a network error, for example.
+	// An accurate check for a successful fetch() would include checking
+	// that the promise resolved, then checking that the Response.ok property
+	// has a value of true. The code would look something like this:
+	//
+	// fetch()
+	// .then( () => {
+	//   if( !response.ok ) {
+	//     throw new Error('Network response was not OK');
+	//   }
+	//   ...
+	// }
+	// .catch((error) => { .. }
+	//
+
+	const promise = fetch(request, { signal });
+
+	if (requestHandler || timeoutMs) {
+		const abort = (reason) => {
+			if (!reason) {
+				reason = new AbortError(`Request [${url.href}] aborted`);
+			}
+
+			controller.abort(reason);
+		};
+
+		/**
+		 * Function that can be used to set a timeout on a request
+		 *
+		 * @param {number} delayMs
+		 */
+		const timeout = (delayMs = 10000) => {
+			expect.positiveNumber(delayMs, 'Invalid value for [delayMs]');
+
+			const timerId = setTimeout(() => {
+				controller.abort(new TimeoutError(`Request [${url.href}] timed out [${delayMs}]`));
+			}, delayMs);
+
+			promise.finally(() => {
+				clearTimeout(timerId);
+			});
+		};
+
+		if (timeoutMs) {
+			timeout(timeoutMs);
+		}
+
+		if (requestHandler) {
+			expect.function(requestHandler, 'Invalid parameter [requestHandler]');
+
+			requestHandler({ controller, abort, timeout });
+		}
+	}
+
+	return promise;
+}

package/dist/util/http/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./headers.js";
+export * from "./errors.js";
+export * from "./url.js";
+export * from "./response.js";

package/dist/util/http/index.js

@@ -0,0 +1,20 @@
+// import * as expect from '../expect/index.js';
+
+// import {
+// 	ResponseError,
+// 	AbortError,
+// 	TimeoutError,
+// 	TypeOrValueError
+// } from '../../constants/errors/index.js';
+
+// import { setRequestHeaders } from './headers.js';
+// import { getErrorFromResponse } from './errors.js';
+
+export * from './headers.js';
+export * from './errors.js';
+export * from './url.js';
+export * from './response.js';
+
+// import { CONTENT_TYPE, METHOD_GET, METHOD_POST } from '../../constants/http/index.js';
+
+// import { APPLICATION_JSON } from '../../constants/mime/index.js';

package/dist/util/http/json-request.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Make a GET request to fetch JSON encoded data
+ * - Expect JSON response from server
+ *
+ * @param {string|URL} url - Url string or URL object
+ *
+ * @param {object} [urlSearchParams]
+ *   Parameters that should be added to the request url
+ *
+ * @param {array[]} [headers]
+ *   List of custom headers. Each header is an array that contains
+ *   the header name and the header value.
+ *   E.g. [ "content-type", "application/json" ]
+ *
+ * @throws ResponseError
+ *   If a network error occurred or the response was not ok
+ *
+ * @returns {any} parsed JSON data
+ */
+export function jsonGet({ url, urlSearchParams, headers }: string | URL): any;
+/**
+ * Make a POST request to fetch JSON encoded data
+ * - Expect JSON response from server
+ *
+ * @param {string|URL} url - Url string or URL object
+ *
+ * @param {any} body
+ *   Data that will be converted to a JSON encoded string and send to the server
+ *
+ * @param {object} [urlSearchParams]
+ *   Parameters that should be added to the request url.
+ *
+ *   @note
+ *   Be careful when using urlSearchParams in POST requests, it can be
+ *   confusing since the parameters usually go in the body part of the request.
+ *
+ * @param {array[]} [headers]
+ *   List of custom headers. Each header is an array that contains
+ *   the header name and the header value.
+ *   E.g. [ "content-type", "application/json" ]
+ *
+ * @throws ResponseError
+ *   If a network error occurred or the response was not ok
+ *
+ * @returns {any} parsed JSON data
+ */
+export function jsonPost({ url, body, urlSearchParams, headers }: string | URL): any;

package/dist/util/http/json-request.js

@@ -0,0 +1,141 @@
+import { METHOD_GET, METHOD_POST } from '../../constants/http/methods.js';
+
+import { APPLICATION_JSON } from '../../constants/mime/application.js';
+import { CONTENT_TYPE } from '../../constants/http/headers.js';
+
+import * as expect from '../expect/index.js';
+
+import { toURL } from './url.js';
+import { ResponseError } from './errors.js';
+import { httpRequest } from './http-request.js';
+import { waitForAndCheckResponse } from './response.js';
+
+const ACCEPT = 'accept';
+
+/**
+ * Make a GET request to fetch JSON encoded data
+ * - Expect JSON response from server
+ *
+ * @param {string|URL} url - Url string or URL object
+ *
+ * @param {object} [urlSearchParams]
+ *   Parameters that should be added to the request url
+ *
+ * @param {array[]} [headers]
+ *   List of custom headers. Each header is an array that contains
+ *   the header name and the header value.
+ *   E.g. [ "content-type", "application/json" ]
+ *
+ * @throws ResponseError
+ *   If a network error occurred or the response was not ok
+ *
+ * @returns {any} parsed JSON data
+ */
+export async function jsonGet({ url, urlSearchParams, headers }) {
+	url = toURL(url);
+
+	if (!headers) {
+		headers = {};
+	}
+
+	headers[ACCEPT] = APPLICATION_JSON;
+
+	const responsePromise = httpRequest({
+		method: METHOD_GET,
+		url,
+		urlSearchParams,
+		headers
+	});
+
+	const response = await waitForAndCheckResponse(responsePromise, url);
+
+	let parsedResponse;
+
+	try {
+		//
+		// @note when security on the client side fails, an `opaque` response
+		//       is returned by the browser (empty body) -> parsing fails
+		//       (use CORS to fix this)
+		//
+		parsedResponse = await response.json();
+	} catch (e) {
+		throw new ResponseError(`Failed to JSON decode server response from [${decodeURI(url.href)}]`, {
+			cause: e
+		});
+	}
+
+	if (parsedResponse.error) {
+		throw new ResponseError(`Server returned response error message [${parsedResponse.error}]`);
+	}
+
+	return parsedResponse;
+}
+
+/**
+ * Make a POST request to fetch JSON encoded data
+ * - Expect JSON response from server
+ *
+ * @param {string|URL} url - Url string or URL object
+ *
+ * @param {any} body
+ *   Data that will be converted to a JSON encoded string and send to the server
+ *
+ * @param {object} [urlSearchParams]
+ *   Parameters that should be added to the request url.
+ *
+ *   @note
+ *   Be careful when using urlSearchParams in POST requests, it can be
+ *   confusing since the parameters usually go in the body part of the request.
+ *
+ * @param {array[]} [headers]
+ *   List of custom headers. Each header is an array that contains
+ *   the header name and the header value.
+ *   E.g. [ "content-type", "application/json" ]
+ *
+ * @throws ResponseError
+ *   If a network error occurred or the response was not ok
+ *
+ * @returns {any} parsed JSON data
+ */
+export async function jsonPost({ url, body, urlSearchParams, headers }) {
+	url = toURL(url);
+
+	if (!headers) {
+		headers = {};
+	} else {
+		expect.object(headers);
+	}
+
+	expect.defined(body);
+
+	headers[ACCEPT] = APPLICATION_JSON;
+	headers[CONTENT_TYPE] = APPLICATION_JSON;
+
+	const responsePromise = httpRequest({ METHOD_POST, url, body, urlSearchParams, headers });
+
+	const response = await waitForAndCheckResponse(responsePromise, url);
+
+	let parsedResponse;
+
+	try {
+		//
+		// @note when security on the client side fails, an `opaque` response
+		//       is returned by the browser (empty body) -> parsing fails
+		//       (use CORS to fix this)
+		//
+		parsedResponse = await response.json();
+	} catch (e) {
+		// console.log( response );
+		throw new ResponseError(`Failed to JSON decode server response from [${decodeURI(url.href)}]`);
+	}
+
+	if (parsedResponse.error) {
+		//
+		// @note this is API specific, but it's quite logical
+		//
+		//
+		throw new ResponseError(`Server returned response error message [${parsedResponse.error}]`);
+	}
+
+	return parsedResponse;
+}

package/dist/util/http/mocks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Create a response value that can be used by a mocked fetch function
+ *
+ * @template T
+ *
+ * @param {T} data
+ *
+ * @returns {{ json: () => Promise<T>}}
+ */
+export function createJsonFetchResponse<T>(data: T): {
+    json: () => Promise<T>;
+};

package/dist/util/http/mocks.js

@@ -0,0 +1,12 @@
+/**
+ * Create a response value that can be used by a mocked fetch function
+ *
+ * @template T
+ *
+ * @param {T} data
+ *
+ * @returns {{ json: () => Promise<T>}}
+ */
+export function createJsonFetchResponse(data /* , options */) {
+	return { json: () => new Promise((resolve) => resolve(data)) };
+}

package/dist/util/http/response.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Check if the response status is ok
+ *
+ * @param {object} response
+ * @param {string} url - used to produce useful error messages
+ *
+ * @throws {Error} not found
+ * @throws {Error} internal server error
+ */
+export function expectResponseOk(response: object, url: string): Promise<void>;
+/**
+ * Wait for a response and check if the response is ok
+ *
+ * @example
+ *   const response = await waitForAndCheckResponse( responsePromise );
+ *
+ * @param {Promise<object>} responsePromise
+ * @param {URL} url - An url that is used for error messages
+ *
+ * @throws ResponseError - A response error if something went wrong
+ *
+ * @returns {object} response
+ */
+export function waitForAndCheckResponse(responsePromise: Promise<object>, url: URL): object;

package/dist/util/http/response.js

@@ -0,0 +1,105 @@
+import { ResponseError } from '../../constants/errors/index.js';
+import * as expect from '../expect/index.js';
+
+import { WWW_AUTHENTICATE } from '../../constants/http/headers.js';
+
+import { toURL } from './url.js';
+
+import { getErrorFromResponse } from './errors.js';
+
+/**
+ * Check if the response status is ok
+ *
+ * @param {object} response
+ * @param {string} url - used to produce useful error messages
+ *
+ * @throws {Error} not found
+ * @throws {Error} internal server error
+ */
+export async function expectResponseOk(response, url) {
+	expect.object(response);
+
+	url = toURL(url);
+
+	// https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200
+	// https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201
+
+	if (200 === response.status || 201 === response.status) {
+		if (!response.ok) {
+			throw new ResponseError(
+				`Server returned - ${response.status} ${response.statusText} ` +
+					`[response.ok=false] [url=${decodeURI(url.href)}]`
+			);
+		}
+
+		// All ok
+		return;
+	}
+
+	// > Handle 401 Unauthorized
+
+	if (401 === response.status) {
+		let errorMessage = 'Server returned [401] Unauthorized';
+
+		const authValue = response.headers.get(WWW_AUTHENTICATE);
+
+		if (authValue) {
+			// Add WWW_AUTHENTICATE response to error message
+
+			errorMessage += ` (${authValue})`;
+		}
+
+		errorMessage += ` [url=${decodeURI(url.href)}]`;
+
+		throw new Error(errorMessage);
+	}
+
+	// > Handle all other error responses
+
+	const error = await getErrorFromResponse(response);
+
+	throw new ResponseError(
+		`Server returned - ${response.status} ${response.statusText} ` + `[url=${decodeURI(url.href)}]`,
+		{ cause: error }
+	);
+}
+
+/**
+ * Wait for a response and check if the response is ok
+ *
+ * @example
+ *   const response = await waitForAndCheckResponse( responsePromise );
+ *
+ * @param {Promise<object>} responsePromise
+ * @param {URL} url - An url that is used for error messages
+ *
+ * @throws ResponseError - A response error if something went wrong
+ *
+ * @returns {object} response
+ */
+export async function waitForAndCheckResponse(responsePromise, url) {
+	expect.promise(responsePromise);
+
+	url = toURL(url);
+
+	let response;
+
+	try {
+		response = await responsePromise;
+
+		if (response && false === response.ok) {
+			// if response.ok is false, it also indicates a network error
+			throw new Error(`Response failed [response.ok=false]`);
+		}
+	} catch (e) {
+		if (e instanceof TypeError || response?.ok === false) {
+			throw new ResponseError(`A network error occurred for request [${decodeURI(url.href)}]`, {
+				cause: e
+			});
+		} else {
+			throw e;
+		}
+	}
+
+	return response;
+}

package/dist/util/http/url.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Ensure to return an URL instance
+ *
+ * @param {string|URL} url
+ *
+ * @returns {URL} url instance
+ */
+export function toURL(url: string | URL): URL;

package/dist/util/http/url.js

@@ -0,0 +1,19 @@
+import { TypeOrValueError } from '../../constants/errors/index.js';
+
+/**
+ * Ensure to return an URL instance
+ *
+ * @param {string|URL} url
+ *
+ * @returns {URL} url instance
+ */
+export function toURL(url) {
+	if (typeof url === 'string') {
+		return new URL(url);
+	} else if (!(url instanceof URL)) {
+		throw new TypeOrValueError('Missing or invalid parameter [url]');
+	}
+
+	// already an URL instance
+	return url;
+}