@hkdigital/lib-core 0.3.1

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

@@ -0,0 +1,224 @@
+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 { ResponseError } from '../../constants/errors/index.js';
+
+import * as expect from '../expect/index.js';
+
+import { toURL } from './url.js';
+import { httpRequest } from './http-request.js';
+import { waitForAndCheckResponse } from './response.js';
+
+const ACCEPT = 'accept';
+
+/**
+ * Make a GET request to fetch JSON encoded data
+ *
+ * This function performs a GET request and expects a JSON response from the server.
+ * It handles common error cases and parses the JSON response.
+ *
+ * @param {import('./typedef').JsonGetOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<any>} Parsed JSON data
+ *
+ * @example
+ * // Basic JSON GET request
+ * try {
+ *   const data = await jsonGet({
+ *     url: 'https://api.example.com/users/123'
+ *   });
+ *   console.log(data); // { id: 123, name: "John Doe", ... }
+ * } catch (error) {
+ *   console.error('Failed to fetch user data:', error.message);
+ * }
+ *
+ * @example
+ * // JSON GET request with parameters
+ * const data = await jsonGet({
+ *   url: 'https://api.example.com/search',
+ *   urlSearchParams: new URLSearchParams({ q: 'search term' }),
+ *   withCredentials: true
+ * });
+ *
+ * @example
+ * // Using advanced options
+ * const data = await jsonGet({
+ *   url: 'https://api.example.com/data',
+ *   timeoutMs: 5000,
+ *   requestHandler: ({ abort }) => {
+ *     // Store abort function
+ *     window.abortDataRequest = abort;
+ *   }
+ * });
+ */
+export async function jsonGet(options) {
+  // Extract specific parameters needed for this function
+  const {
+    url: rawUrl,
+    urlSearchParams,
+    headers,
+    withCredentials,
+    ...otherOptions
+  } = options;
+
+  const url = toURL(rawUrl);
+
+  // Apply JSON-specific defaults
+  const jsonHeaders = headers || {};
+  jsonHeaders[ACCEPT] = APPLICATION_JSON;
+
+  // Create request with all options
+  const responsePromise = httpRequest({
+    method: METHOD_GET,
+    url,
+    urlSearchParams,
+    headers: jsonHeaders,
+    withCredentials,
+    ...otherOptions // Pass through any other options
+  });
+
+  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
+ *
+ * This function performs a POST request with JSON data and expects a JSON
+ * response from the server. It handles common error cases and parses the JSON response.
+ *
+ * @param {import('./typedef').JsonPostOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<any>} Parsed JSON data
+ *
+ * @example
+ * // Basic JSON POST request
+ * try {
+ *   const newUser = {
+ *     name: "Jane Smith",
+ *     email: "jane@example.com"
+ *   };
+ *
+ *   const data = await jsonPost({
+ *     url: 'https://api.example.com/users',
+ *     body: JSON.stringify(newUser)
+ *   });
+ *
+ *   console.log('Created user with ID:', data.id);
+ * } catch (error) {
+ *   console.error('Failed to create user:', error.message);
+ * }
+ *
+ * @example
+ * // JSON POST with authentication and timeout
+ * const data = await jsonPost({
+ *   url: 'https://api.example.com/protected/resource',
+ *   body: JSON.stringify({ action: 'update' }),
+ *   headers: {
+ *     'authorization': 'Bearer ' + token
+ *   },
+ *   withCredentials: true,
+ *   timeoutMs: 5000
+ * });
+ */
+export async function jsonPost(options) {
+  // Extract specific parameters needed for this function
+  const {
+    url: rawUrl,
+    body,
+    urlSearchParams,
+    headers,
+    withCredentials,
+    ...otherOptions
+  } = options;
+
+  const url = toURL(rawUrl);
+
+  // Apply JSON-specific defaults and validation
+  expect.defined(body);
+
+  const jsonHeaders = headers || {};
+  jsonHeaders[ACCEPT] = APPLICATION_JSON;
+  jsonHeaders[CONTENT_TYPE] = APPLICATION_JSON;
+
+  // Check if body is a string when using application/json
+  if (
+    jsonHeaders[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.'
+    );
+  }
+
+  // Create request with all options
+  const responsePromise = httpRequest({
+    method: METHOD_POST,
+    url,
+    body,
+    urlSearchParams,
+    headers: jsonHeaders,
+    withCredentials,
+    ...otherOptions // Pass through any other options
+  });
+
+  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) {
+    //
+    // @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,20 @@
+/**
+ * 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>;
+};
+/**
+ * Create a response value that can be used by a mocked fetch function
+ *
+ * @param {ArrayBuffer} arrayBuffer
+ *
+ * @returns {Response}
+ */
+export function createStreamedResponse(arrayBuffer: ArrayBuffer): Response;

package/dist/util/http/mocks.js

@@ -0,0 +1,65 @@
+import { CONTENT_TYPE, CONTENT_LENGTH } from '../../constants/http/index.js';
+
+import { OCTET_STREAM } from '../../constants/mime/index.js';
+
+/**
+ * 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)) };
+}
+
+/**
+ * Create a response value that can be used by a mocked fetch function
+ *
+ * @param {ArrayBuffer} arrayBuffer
+ *
+ * @returns {Response}
+ */
+export function createStreamedResponse(arrayBuffer /*, options */) {
+	const byteLength = arrayBuffer.byteLength;
+	const chunkSize = Math.ceil(byteLength / 10);
+
+	const body = new ReadableStream({
+		start(controller) {
+			let offset = 0;
+
+			function pushChunk() {
+				if (offset >= byteLength) {
+					controller.close();
+					return;
+				}
+
+				// Calculate the size of the current chunk
+				const currentChunkSize = Math.min(chunkSize, byteLength - offset);
+
+				// Create a new ArrayBuffer for this chunk
+				const chunk = arrayBuffer.slice(offset, offset + currentChunkSize);
+
+				controller.enqueue(chunk);
+				offset += currentChunkSize;
+
+				// Schedule next chunk
+				setTimeout(pushChunk, 0);
+			}
+
+			// Start pushing chunks
+			pushChunk();
+		}
+	});
+
+	const response = new Response(body, {
+		headers: new Headers({
+			[CONTENT_TYPE]: OCTET_STREAM,
+			[CONTENT_LENGTH]: String(byteLength)
+		})
+	});
+
+	return response;
+}

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

@@ -0,0 +1,125 @@
+/**
+ * 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)
+ */
+/**
+ * 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 function expectResponseOk(response: object, url: string): Promise<void>;
+/**
+ * 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: Response): number;
+/**
+ * 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 function waitForAndCheckResponse(responsePromise: Promise<Response>, url: string | URL): Promise<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: Response, onProgress?: progressCallback): {
+    bufferPromise: Promise<ArrayBuffer>;
+    abort: () => void;
+};
+/**
+ * Callback function that reports progress of data loading
+ */
+export type progressCallback = (_: {
+    bytesLoaded: number;
+    size: number;
+}) => any;