@hkdigital/lib-core 0.3.1

package/dist/util/http/response.js

@@ -0,0 +1,294 @@
+import { ResponseError } from '../../constants/errors/index.js';
+import * as expect from '../expect/index.js';
+import { toURL } from './url.js';
+
+import {
+  WWW_AUTHENTICATE,
+  CONTENT_LENGTH
+} from '../../constants/http/headers.js';
+
+import { href } from './url.js';
+
+import { getErrorFromResponse } from './errors.js';
+
+// > Types
+
+/**
+ * Callback function that reports progress of data loading
+ *
+ * @callback progressCallback
+ *
+ * @param {object} _
+ * @param {number} _.bytesLoaded - Number of bytes loaded so far
+ * @param {number} _.size - Total size of the response in bytes (0 if unknown)
+ */
+
+// > Exports
+
+/**
+ * Check if the response status is ok (in 200-299 range)
+ * This function examines HTTP status codes and throws appropriate errors for
+ * non-successful responses, with special handling for 401 Unauthorized.
+ *
+ * @param {object} response - Fetch Response object to check
+ *
+ * @param {string} url - The URL used for the request (for error messages)
+ *
+ * @throws {Error} When response has 401 status with authorization details
+ * @throws {ResponseError} When response has other non-successful status codes
+ *
+ * @example
+ * // Check if response was successful
+ * try {
+ *   await expectResponseOk(response, 'https://api.example.com/data');
+ *   // Process successful response here
+ * } catch (error) {
+ *   // Handle specific error types
+ *   if (error.message.includes('401')) {
+ *     // Handle unauthorized error
+ *   }
+ * }
+ */
+export async function expectResponseOk(response, url) {
+  expect.object(response);
+
+  // 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=${href(url)}]`
+      );
+    }
+
+    // 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=${href(url)}]`;
+
+    throw new Error(errorMessage);
+  }
+
+  // > Handle all other error responses
+
+  const error = await getErrorFromResponse(response);
+
+  throw new ResponseError(
+    `Server returned - ${response.status} ${response.statusText} ` +
+      `[url=${href(url)}]`,
+    { cause: error }
+  );
+}
+
+/**
+ * Get the response size from the content-length response header
+ *
+ * @param {Response} response - Fetch Response object
+ *
+ * @returns {number} Response size in bytes, or 0 if content-length is not set
+ *
+ * @example
+ * const response = await fetch('https://example.com/large-file.zip');
+ * const size = getResponseSize(response);
+ * console.log(`Download size: ${size} bytes`);
+ */
+export function getResponseSize(response) {
+  const sizeStr = response.headers.get(CONTENT_LENGTH);
+
+  if (!sizeStr) {
+    return 0;
+  }
+
+  return parseInt(sizeStr, 10);
+}
+
+/**
+ * Wait for a response and check if the response is ok
+ * This function awaits a response promise and performs error checking,
+ * wrapping network errors in a standardized ResponseError format.
+ *
+ * @param {Promise<Response>} responsePromise - Promise that resolves to a Response
+ *
+ * @param {string|URL} url - URL used for the request (for error messages)
+ *
+ * @throws {ResponseError} When a network error occurs or response is not ok
+ *
+ * @returns {Promise<Response>} The response if successful
+ *
+ * @example
+ * // Handle a fetch promise with proper error handling
+ * const responsePromise = fetch('https://api.example.com/data');
+ * try {
+ *   const response = await waitForAndCheckResponse(
+ *     responsePromise,
+ *     'https://api.example.com/data'
+ *   );
+ *   // Process response
+ * } catch (error) {
+ *   // Handle standardized ResponseError
+ *   console.error(error.message);
+ * }
+ */
+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 [${href(url)}]`,
+        {
+          cause: e
+        }
+      );
+    } else {
+      throw e;
+    }
+  }
+
+  return response;
+}
+
+/**
+ * Load response body as ArrayBuffer with progress monitoring and abort capability
+ *
+ * This function reads a response body stream chunk by chunk, with optional
+ * progress reporting. It provides an abort mechanism to cancel an in-progress
+ * download.
+ *
+ * @param {Response} response - Fetch Response object to read
+ *
+ * @param {progressCallback} [onProgress] - Optional callback for progress updates
+ *
+ * @returns {{
+ *   bufferPromise: Promise<ArrayBuffer>,
+ *   abort: () => void
+ * }} Object containing the buffer promise and abort function
+ *
+ * @example
+ * // Download a file with progress monitoring and abort capability
+ * const response = await fetch('https://example.com/large-file.zip');
+ *
+ * const { bufferPromise, abort } = loadResponseBuffer(
+ *   response,
+ *   ({ bytesLoaded, size }) => {
+ *     // Update progress UI
+ *     const percent = size ? Math.round((bytesLoaded / size) * 100) : 0;
+ *     console.log(`Downloaded ${bytesLoaded} bytes (${percent}%)`);
+ *   }
+ * );
+ *
+ * // To abort the download:
+ * // abort();
+ *
+ * try {
+ *   const buffer = await bufferPromise;
+ *   // Process the complete buffer
+ * } catch (error) {
+ *   console.error('Download failed or was aborted', error);
+ * }
+ */
+export function loadResponseBuffer(response, onProgress) {
+  // @note size might be 0
+  // @note might not be send by server in dev mode
+  const size = getResponseSize(response);
+
+  let bytesLoaded = 0;
+
+  if (onProgress /*&& size*/) {
+    onProgress({ bytesLoaded, size });
+  }
+
+  if (!response.body) {
+    throw new Error('Missing [response.body]');
+  }
+
+  let reader;
+  let aborted = false;
+
+  /**
+   * Read chunks from response body using reader
+   *
+   * @returns {Promise<ArrayBuffer>}
+   */
+  async function read() {
+    reader = response.body.getReader();
+    let chunks = [];
+
+    for (;;) {
+      const { done, value } = await reader.read();
+
+      if (value) {
+        // @note value is an ArrayBuffer
+        bytesLoaded += value.byteLength;
+
+        chunks.push(value);
+
+        if (onProgress /*&& size*/) {
+          onProgress({ bytesLoaded, size });
+        }
+      }
+
+      if (done || aborted) {
+        // Loading complete or aborted by user
+        break;
+      }
+    } // end for
+
+    if (size && bytesLoaded !== size) {
+      console.error(`Received [${bytesLoaded}], but expected [${size}] bytes`);
+    }
+
+    // Concat the chunks into a single array
+    let buffer = new ArrayBuffer(bytesLoaded);
+    let body = new Uint8Array(buffer);
+
+    let offset = 0;
+
+    // Place the chunks in the buffer
+    for (let chunk of chunks) {
+      body.set(chunk, offset);
+      offset += chunk.byteLength;
+    } // end for
+
+    return buffer;
+  }
+
+  const bufferPromise = read();
+
+  return {
+    bufferPromise,
+    abort: () => {
+      aborted = true;
+
+      if (reader) {
+        reader.cancel('Aborted by user');
+      }
+    }
+  };
+} // end fn

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

@@ -0,0 +1,184 @@
+export type HttpRequestOptions = {
+    /**
+     * URL string or URL object for the request
+     */
+    url: string | URL;
+    /**
+     * HTTP method to use (GET, POST, etc.)
+     */
+    method?: string;
+    /**
+     * Parameters to add to the URL
+     */
+    urlSearchParams?: any | URLSearchParams;
+    /**
+     * Request body (for POST, PUT, etc.)
+     */
+    body?: any;
+    /**
+     * HTTP headers as name-value pairs
+     */
+    headers?: any;
+    /**
+     * Whether to include credentials
+     */
+    withCredentials?: boolean;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeoutMs?: number;
+    /**
+     * Handler for abort/timeout control
+     */
+    requestHandler?: Function;
+    /**
+     * CORS mode ('cors', 'no-cors', 'same-origin')
+     */
+    mode?: string;
+    /**
+     * Cache mode ('default', 'no-cache', etc.)
+     */
+    cache?: string;
+    /**
+     * Redirect mode ('follow', 'error', 'manual')
+     */
+    redirect?: string;
+    /**
+     * Referrer policy
+     */
+    referrerPolicy?: string;
+    /**
+     * Enable or disabled automatic caching
+     */
+    cacheEnabled?: boolean;
+};
+export type RequestHandlerParams = {
+    /**
+     *   The AbortController instance for this request
+     */
+    controller: AbortController;
+    /**
+     * Function to abort the request
+     */
+    abort: (reason?: Error) => void;
+    /**
+     * Function to set a timeout
+     */
+    timeout: (delayMs: number) => void;
+};
+export type RequestHandler = (params: RequestHandlerParams) => void;
+export type JsonGetOptions = {
+    /**
+     * URL string or URL object for the request
+     */
+    url: string | URL;
+    /**
+     * Parameters to add to the URL
+     */
+    urlSearchParams?: any | URLSearchParams;
+    /**
+     * HTTP headers as name-value pairs
+     */
+    headers?: any;
+    /**
+     * Whether to include credentials
+     */
+    withCredentials?: boolean;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeoutMs?: number;
+    /**
+     * Handler for abort/timeout control
+     */
+    requestHandler?: RequestHandler;
+    /**
+     * CORS mode ('cors', 'no-cors', 'same-origin')
+     */
+    mode?: string;
+    /**
+     * Cache mode ('default', 'no-cache', etc.)
+     */
+    cache?: string;
+    /**
+     * Redirect mode ('follow', 'error', 'manual')
+     */
+    redirect?: string;
+    /**
+     * Referrer policy
+     */
+    referrerPolicy?: string;
+    /**
+     * Enable or disabled automatic caching
+     */
+    cacheEnabled?: boolean;
+};
+export type JsonPostOptions = {
+    /**
+     * URL string or URL object for the request
+     */
+    url: string | URL;
+    /**
+     * Request body (will be sent as JSON)
+     */
+    body: any;
+    /**
+     * Parameters to add to the URL
+     */
+    urlSearchParams?: any | URLSearchParams;
+    /**
+     * HTTP headers as name-value pairs
+     */
+    headers?: any;
+    /**
+     * Whether to include credentials
+     */
+    withCredentials?: boolean;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeoutMs?: number;
+    /**
+     * Handler for abort/timeout control
+     */
+    requestHandler?: RequestHandler;
+    /**
+     * CORS mode ('cors', 'no-cors', 'same-origin')
+     */
+    mode?: string;
+    /**
+     * Cache mode ('default', 'no-cache', etc.)
+     */
+    cache?: string;
+    /**
+     * Redirect mode ('follow', 'error', 'manual')
+     */
+    redirect?: string;
+    /**
+     * Referrer policy
+     */
+    referrerPolicy?: string;
+    /**
+     * Enable or disabled automatic caching
+     */
+    cacheEnabled?: boolean;
+};
+export type StaleInfo = {
+    /**
+     * Whether the response contains stale data
+     */
+    isStale: boolean;
+    /**
+     *   Promise that resolves to fresh data (if available)
+     */
+    fresh: Promise<Response> | null;
+    /**
+     * When the response was originally cached
+     */
+    timestamp: number;
+    /**
+     * When the response expires
+     */
+    expires: number | null;
+};
+export type ResponseWithStale = Response;

package/dist/util/http/typedef.js

@@ -0,0 +1,93 @@
+/**
+ * @typedef {Object} HttpRequestOptions
+ * @property {string|URL} url URL string or URL object for the request
+ * @property {string} [method] HTTP method to use (GET, POST, etc.)
+ *
+ * @property {Object|URLSearchParams} [urlSearchParams]
+ *   Parameters to add to the URL
+ *
+ * @property {*} [body] Request body (for POST, PUT, etc.)
+ * @property {Object} [headers] HTTP headers as name-value pairs
+ * @property {boolean} [withCredentials] Whether to include credentials
+ * @property {number} [timeoutMs] Request timeout in milliseconds
+ * @property {Function} [requestHandler] Handler for abort/timeout control
+ * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
+ * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
+ * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
+ * @property {string} [referrerPolicy] Referrer policy
+ * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
+ */
+
+/**
+ * @typedef {Object} RequestHandlerParams
+ *
+ * @property {AbortController} controller
+ *   The AbortController instance for this request
+ *
+ * @property {(reason?: Error) => void} abort Function to abort the request
+ * @property {(delayMs: number) => void} timeout Function to set a timeout
+ */
+
+/**
+ * @callback RequestHandler
+ * @param {RequestHandlerParams} params Parameters for controlling the request
+ * @returns {void}
+ */
+
+/**
+ * @typedef {Object} JsonGetOptions
+ * @property {string|URL} url URL string or URL object for the request
+ *
+ * @property {Object|URLSearchParams} [urlSearchParams]
+ *   Parameters to add to the URL
+ *
+ * @property {Object} [headers] HTTP headers as name-value pairs
+ * @property {boolean} [withCredentials] Whether to include credentials
+ * @property {number} [timeoutMs] Request timeout in milliseconds
+ * @property {RequestHandler} [requestHandler] Handler for abort/timeout control
+ * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
+ * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
+ * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
+ * @property {string} [referrerPolicy] Referrer policy
+ * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
+ */
+
+/**
+ * @typedef {Object} JsonPostOptions
+ * @property {string|URL} url URL string or URL object for the request
+ * @property {*} body Request body (will be sent as JSON)
+ *
+ * @property {Object|URLSearchParams} [urlSearchParams]
+ *   Parameters to add to the URL
+ *
+ * @property {Object} [headers] HTTP headers as name-value pairs
+ * @property {boolean} [withCredentials] Whether to include credentials
+ * @property {number} [timeoutMs] Request timeout in milliseconds
+ * @property {RequestHandler} [requestHandler] Handler for abort/timeout control
+ * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
+ * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
+ * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
+ * @property {string} [referrerPolicy] Referrer policy
+ * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
+ */
+
+/**
+ * @typedef {Object} StaleInfo
+ * @property {boolean} isStale Whether the response contains stale data
+ *
+ * @property {Promise<Response>|null} fresh
+ *   Promise that resolves to fresh data (if available)
+ *
+ * @property {number} timestamp When the response was originally cached
+ * @property {number|null} expires When the response expires
+ */
+
+/**
+ * @typedef {Response} ResponseWithStale
+ * @property {boolean} isStale Whether this response contains stale data
+ *
+ * @property {Promise<Response>|null} fresh
+ *   Promise for fresh data if this is stale
+ */
+
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * Returns an URL instance
+ * - Prefixes the URL with the current orign if the url is relative
+ *
+ * @param {string|URL} url
+ *
+ * @returns {URL} url instance
+ */
+export function toURL(url: string | URL): URL;
+/**
+ * Checks if the url starts with a protocol specification such
+ * as https://
+ *
+ * @param {string} url
+ *
+ * @return {boolean} true if the value looks like an array
+ */
+export function hasProtocol(url: string): boolean;
+/**
+ * Convert an url to an absolute url and apply decodeURI to
+ * convert URI encoded characters to normal characters
+ *
+ * @param {string|URL} url
+ */
+export function href(url: string | URL): string;

package/dist/util/http/url.js

@@ -0,0 +1,52 @@
+import { TypeOrValueError } from '../../constants/errors/index.js';
+
+/**
+ * Returns an URL instance
+ * - Prefixes the URL with the current orign if the url is relative
+ *
+ * @param {string|URL} url
+ *
+ * @returns {URL} url instance
+ */
+export function toURL(url) {
+	if (typeof url === 'string') {
+		if (hasProtocol(url)) {
+			return new URL(url);
+		} else {
+			// Use location.origin aas baseUrl
+			return new URL(url, location.origin);
+		}
+	} else if (!(url instanceof URL)) {
+		throw new TypeOrValueError('Missing or invalid parameter [url]');
+	}
+
+	// already an URL instance
+	return url;
+}
+
+/**
+ * Checks if the url starts with a protocol specification such
+ * as https://
+ *
+ * @param {string} url
+ *
+ * @return {boolean} true if the value looks like an array
+ */
+export function hasProtocol(url) {
+	if (/^([a-zA-Z]{2,})s?:\/\//.test(url)) {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Convert an url to an absolute url and apply decodeURI to
+ * convert URI encoded characters to normal characters
+ *
+ * @param {string|URL} url
+ */
+export function href(url) {
+	const urlObj = toURL(url);
+	return decodeURI(urlObj.href);
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Returns the unchanged image meta object or the last item of
+ * an array of ImageMeta objects. This is assumed to be a list
+ * of sorted responsive image formats, so it should be the
+ * largest image.
+ *
+ * @param {ImageMeta|ImageMeta[]} imageMeta
+ */
+export function toSingleImageMeta(imageMeta: ImageMeta | ImageMeta[]): import("../../typedef").ImageMeta;
+/**
+ * Calculate effective width based on container dimensions and fit mode
+ *
+ * @param {object} params
+ * @param {number} [params.containerWidth] Container width in pixels
+ * @param {number} [params.containerHeight] Container height in pixels
+ * @param {number} params.imageAspectRatio Original image aspect ratio (width/height)
+ * @param {'cover'|'contain'|'fill'} [params.fit='contain'] Fit mode
+ * @returns {number} Effective width needed
+ */
+export function calculateEffectiveWidth({ containerWidth, containerHeight, imageAspectRatio, fit }: {
+    containerWidth?: number;
+    containerHeight?: number;
+    imageAspectRatio: number;
+    fit?: "cover" | "contain" | "fill";
+}): number;