@hkdigital/lib-sveltekit 0.1.68 → 0.1.70

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

@@ -1,11 +1,40 @@
 /**
  * Set headers in an existing `Headers` object
- * - Existing headers with the same name will be overwritten
- * - The supplied `Headers` object will be updated, this function does not
- *   return any value
  *
- * @param {Headers} target - Headers object to set the extra headers in
+ * This function adds or updates headers in an existing Headers object.
+ * Existing headers with the same name will be overwritten.
+ * The supplied `Headers` object will be updated in place.
+ *
+ * @param {Headers} target
+ *   Headers object to set the extra headers in
  *
  * @param {null|object|[string, string][]} [pairs]
+ *   Headers to add, can be null, an object of name-value pairs,
+ *   or an array of [name, value] pairs
+ *
+ * @throws {Error} If target is not a Headers object
+ * @throws {Error} If pairs is a Headers object
+ * @throws {Error} If pairs is not null, object, or array
+ * @throws {Error} If any header name or value is empty
+ *
+ * @example
+ * // Add headers from an object
+ * const headers = new Headers();
+ * setRequestHeaders(headers, {
+ *   'content-type': 'application/json',
+ *   'accept': 'application/json'
+ * });
+ *
+ * @example
+ * // Add headers from an array of pairs
+ * const headers = new Headers();
+ * setRequestHeaders(headers, [
+ *   ['content-type', 'application/json'],
+ *   ['authorization', 'Bearer token123']
+ * ]);
+ *
+ * @example
+ * // Passing null is valid and does nothing
+ * setRequestHeaders(headers, null);
  */
 export function setRequestHeaders(target: Headers, pairs?: null | object | [string, string][]): void;

package/dist/util/http/headers.js

@@ -2,44 +2,74 @@ import * as expect from '../expect/index.js';
 
 /**
  * Set headers in an existing `Headers` object
- * - Existing headers with the same name will be overwritten
- * - The supplied `Headers` object will be updated, this function does not
- *   return any value
  *
- * @param {Headers} target - Headers object to set the extra headers in
+ * This function adds or updates headers in an existing Headers object.
+ * Existing headers with the same name will be overwritten.
+ * The supplied `Headers` object will be updated in place.
+ *
+ * @param {Headers} target
+ *   Headers object to set the extra headers in
  *
  * @param {null|object|[string, string][]} [pairs]
+ *   Headers to add, can be null, an object of name-value pairs,
+ *   or an array of [name, value] pairs
+ *
+ * @throws {Error} If target is not a Headers object
+ * @throws {Error} If pairs is a Headers object
+ * @throws {Error} If pairs is not null, object, or array
+ * @throws {Error} If any header name or value is empty
+ *
+ * @example
+ * // Add headers from an object
+ * const headers = new Headers();
+ * setRequestHeaders(headers, {
+ *   'content-type': 'application/json',
+ *   'accept': 'application/json'
+ * });
+ *
+ * @example
+ * // Add headers from an array of pairs
+ * const headers = new Headers();
+ * setRequestHeaders(headers, [
+ *   ['content-type', 'application/json'],
+ *   ['authorization', 'Bearer token123']
+ * ]);
+ *
+ * @example
+ * // Passing null is valid and does nothing
+ * setRequestHeaders(headers, null);
  */
 export function setRequestHeaders(target, pairs) {
-	if (!(target instanceof Headers)) {
-		throw new Error('Invalid parameter [target] (expected Headers object)');
-	}
+  if (!(target instanceof Headers)) {
+    throw new Error('Invalid parameter [target] (expected Headers object)');
+  }
 
-	// expect.objectNoArray(pairs);
+  // expect.objectNoArray(pairs);
 
-	if (pairs instanceof Headers) {
-		throw new Error('Invalid parameter [pairs] (should not be a Headers object)');
-	}
+  if (pairs instanceof Headers) {
+    throw new Error(
+    	'Invalid parameter [pairs] (should not be a Headers object)');
+  }
 
-	if (!pairs) {
-		return;
-	}
+  if (!pairs) {
+    return;
+  }
 
-	if (typeof pairs !== 'object') {
-		throw new Error('Invalid value for parameter [pairs]');
-	}
+  if (typeof pairs !== 'object') {
+    throw new Error('Invalid value for parameter [pairs]');
+  }
 
-	if (!Array.isArray(pairs)) {
-		pairs = Object.entries(pairs);
-	}
+  if (!Array.isArray(pairs)) {
+    pairs = Object.entries(pairs);
+  }
 
-	for (const [name, value] of pairs) {
-		expect.notEmptyString(name);
-		expect.notEmptyString(value);
+  for (const [name, value] of pairs) {
+    expect.notEmptyString(name);
+    expect.notEmptyString(value);
 
-		// @note Headers should be encoded lowercase in HTTP2
-		const nameLower = name.toLowerCase();
+    // @note Headers should be encoded lowercase in HTTP2
+    const nameLower = name.toLowerCase();
 
-		target.set(nameLower, value); /* overwrites existing value */
-	}
+    target.set(nameLower, value); /* overwrites existing value */
+  }
 }

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

@@ -1,125 +1,103 @@
 /**
- * @callback requestHandler
- * @param {Object} _
- * @param {AbortController} _.controller
- * @param {( reason?: Error ) => void} _.abort
- * @param {( delayMs: number) => void} _.timeout
+ * Make a GET request
+ *
+ * This function performs an HTTP GET request with optional parameters,
+ * headers, credentials, and timeout functionality.
+ *
+ * @param {import('./typedef').HttpRequestOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<Response>} Response promise
+ *
+ * @example
+ * // Basic GET request
+ * const response = await httpGet({
+ *   url: 'https://api.example.com/data'
+ * });
+ *
+ * @example
+ * // GET request with URL parameters and timeout
+ * const response = await httpGet({
+ *   url: 'https://api.example.com/search',
+ *   urlSearchParams: new URLSearchParams({ q: 'search term' }),
+ *   timeoutMs: 5000
+ * });
+ *
+ * @example
+ * // GET request with abort capability
+ * const response = await httpGet({
+ *   url: 'https://api.example.com/large-data',
+ *   requestHandler: ({ abort }) => {
+ *     // Store abort function for later use
+ *     window.abortDataRequest = abort;
+ *   }
+ * });
  */
+export function httpGet(options: import("./typedef").HttpRequestOptions): Promise<Response>;
 /**
- * Make GET request
- *
- * @param {object} _
- *
- * @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 {boolean} [_.withCredentials=false]
- *
- * @param {requestHandler} [_.requestHandler]
- *
- * @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<Response>} responsePromise
+ * Make a POST request
+ *
+ * This function performs an HTTP POST request with optional body,
+ * headers, credentials, and timeout functionality.
+ *
+ * @param {import('./typedef').HttpRequestOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<Response>} Response promise
+ *
+ * @example
+ * // Basic POST request with JSON data
+ * const response = await httpPost({
+ *   url: 'https://api.example.com/users',
+ *   body: JSON.stringify({ name: 'John Doe', email: 'john@example.com' }),
+ *   headers: { 'content-type': 'application/json' }
+ * });
+ *
+ * @example
+ * // POST request with timeout
+ * const response = await httpPost({
+ *   url: 'https://api.example.com/upload',
+ *   body: formData,
+ *   timeoutMs: 30000 // 30 seconds timeout
+ * });
  */
-export function httpGet({ url, urlSearchParams, headers, withCredentials, requestHandler, timeoutMs }: {
-    url: string | URL;
-    urlSearchParams?: object;
-    headers?: object;
-    withCredentials?: boolean;
-    requestHandler?: requestHandler;
-    timeoutMs?: number;
-}): Promise<Response>;
+export function httpPost(options: import("./typedef").HttpRequestOptions): Promise<Response>;
 /**
- * Make POST request
- *
- * @param {object} _
- *
- * @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 {boolean} [_.withCredentials=false]
- *
- * @param {requestHandler} [_.requestHandler]
- *
- * @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<Response>} responsePromise
+ * Make an HTTP request (low-level function)
+ *
+ * This is a low-level function that powers httpGet and httpPost.
+ * It provides complete control over request configuration.
+ *
+ * @param {import('./typedef').HttpRequestOptions} options
+ *   Request configuration options
+ *
+ * @throws {TypeError} If a network error occurred
+ * @returns {Promise<Response>} Response promise
+ *
+ * @example
+ * // Custom HTTP request with PUT method
+ * const response = await httpRequest({
+ *   method: 'PUT',
+ *   url: 'https://api.example.com/resources/123',
+ *   body: JSON.stringify({ status: 'updated' }),
+ *   headers: { 'content-type': 'application/json' },
+ *   withCredentials: true
+ * });
+ *
+ * // Check if response was successful
+ * if (response.ok) {
+ *   // Process response
+ * } else {
+ *   // Handle error based on status
+ * }
  */
-export function httpPost({ url, body, headers, withCredentials, requestHandler, timeoutMs }: {
-    url: string | URL;
-    body?: any;
-    headers?: object;
-    withCredentials?: boolean;
-    requestHandler?: requestHandler;
-    timeoutMs?: number;
-}): Promise<Response>;
+export function httpRequest(options: import("./typedef").HttpRequestOptions): Promise<Response>;
 /**
- * Make an HTTP request
- * - This is a low level function, consider using
- *   httpGet, httpPost, jsonGet or jsonPost instead
- *
- * @param {object} _
- *
- * @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 {boolean} [_.withCredentials=false]
- *   Whether to include credentials (cookies, HTTP authentication, and client
- *   SSL certificates) with cross-origin requests. When true, sets fetch
- *   credentials to 'include', otherwise to 'omit'.
- *
- * @param {requestHandler} [_.requestHandler]
- *
- * @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
+ * Default configuration for HTTP requests
  *
- * @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)
+ * This object contains default settings used by the HTTP request functions.
+ * It can be used as a reference for available options and their default values.
  *
- * @returns {Promise<Response>} responsePromise
+ * @type {Object}
  */
-export function httpRequest({ method, url, urlSearchParams, body, headers, withCredentials, requestHandler, timeoutMs }: {
-    url: string | URL;
-    method: string;
-    urlSearchParams?: object;
-    body?: any;
-    headers?: object;
-    withCredentials?: boolean;
-    requestHandler?: requestHandler;
-    timeoutMs?: number;
-}): Promise<Response>;
-export type requestHandler = (_: {
-    controller: AbortController;
-    abort: (reason?: Error) => void;
-    timeout: (delayMs: number) => void;
-}) => any;
+export const DEFAULT_HTTP_CONFIG: any;