@hkdigital/lib-sveltekit 0.1.68 → 0.1.70

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

@@ -1,64 +1,84 @@
 /**
  * Make a GET request to fetch JSON encoded data
- * - Expect JSON response from server
  *
- * @param {object} _
- * @param {string|URL} _.url - Url string or URL object
+ * 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 {object} [_.urlSearchParams]
- *   Parameters that should be added to the request url
+ * @param {import('./typedef').JsonGetOptions} options
+ *   Request configuration options
  *
- * @param {[string, string][]} [_.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" ]
+ * @returns {Promise<any>} Parsed JSON data
  *
- * @param {boolean} [_.withCredentials=false]
+ * @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);
+ * }
  *
- * @throws ResponseError
- *   If a network error occurred or the response was not ok
+ * @example
+ * // JSON GET request with parameters
+ * const data = await jsonGet({
+ *   url: 'https://api.example.com/search',
+ *   urlSearchParams: new URLSearchParams({ q: 'search term' }),
+ *   withCredentials: true
+ * });
  *
- * @returns {Promise<any>} parsed JSON data
+ * @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 function jsonGet({ url, urlSearchParams, headers, withCredentials }: {
-    url: string | URL;
-    urlSearchParams?: object;
-    headers?: [string, string][];
-    withCredentials?: boolean;
-}): Promise<any>;
+export function jsonGet(options: import("./typedef").JsonGetOptions): Promise<any>;
 /**
  * Make a POST request to fetch JSON encoded data
- * - Expect JSON response from server
  *
- * @param {object} _
- * @param {string|URL} _.url - Url string or URL object
+ * 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 {any} _.body
- *   Data that will be converted to a JSON encoded string and send to the server
+ * @param {import('./typedef').JsonPostOptions} options
+ *   Request configuration options
  *
- * @param {object} [_.urlSearchParams]
- *   Parameters that should be added to the request url.
+ * @returns {Promise<any>} Parsed JSON data
  *
- *   - Be careful when using urlSearchParams in POST requests, it can be
- *     confusing since the parameters usually go in the body part of
- *     the request.
+ * @example
+ * // Basic JSON POST request
+ * try {
+ *   const newUser = {
+ *     name: "Jane Smith",
+ *     email: "jane@example.com"
+ *   };
  *
- * @param {[string, string][]} [_.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" ]
+ *   const data = await jsonPost({
+ *     url: 'https://api.example.com/users',
+ *     body: JSON.stringify(newUser)
+ *   });
  *
- * @param {boolean} [_.withCredentials=false]
+ *   console.log('Created user with ID:', data.id);
+ * } catch (error) {
+ *   console.error('Failed to create user:', error.message);
+ * }
  *
- * @throws ResponseError
- *   If a network error occurred or the response was not ok
- *
- * @returns {Promise<any>} parsed JSON data
+ * @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 function jsonPost({ url, body, urlSearchParams, headers, withCredentials }: {
-    url: string | URL;
-    body: any;
-    urlSearchParams?: object;
-    headers?: [string, string][];
-    withCredentials?: boolean;
-}): Promise<any>;
+export function jsonPost(options: import("./typedef").JsonPostOptions): Promise<any>;

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

@@ -14,161 +14,211 @@ const ACCEPT = 'accept';
 
 /**
  * Make a GET request to fetch JSON encoded data
- * - Expect JSON response from server
  *
- * @param {object} _
- * @param {string|URL} _.url - Url string or URL object
+ * 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 {object} [_.urlSearchParams]
- *   Parameters that should be added to the request url
+ * @param {import('./typedef').JsonGetOptions} options
+ *   Request configuration options
  *
- * @param {[string, string][]} [_.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" ]
+ * @returns {Promise<any>} Parsed JSON data
  *
- * @param {boolean} [_.withCredentials=false]
+ * @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);
+ * }
  *
- * @throws ResponseError
- *   If a network error occurred or the response was not ok
+ * @example
+ * // JSON GET request with parameters
+ * const data = await jsonGet({
+ *   url: 'https://api.example.com/search',
+ *   urlSearchParams: new URLSearchParams({ q: 'search term' }),
+ *   withCredentials: true
+ * });
  *
- * @returns {Promise<any>} parsed JSON data
+ * @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({
-	url,
-	urlSearchParams,
-	headers,
-	withCredentials
-}) {
-	url = toURL(url);
-
-	if (!headers) {
-		headers = [];
-	}
-
-	headers[ACCEPT] = APPLICATION_JSON;
-
-	const responsePromise = httpRequest({
-		method: METHOD_GET,
-		url,
-		urlSearchParams,
-		headers,
-		withCredentials
-	});
-
-	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;
+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
- * - Expect JSON response from server
  *
- * @param {object} _
- * @param {string|URL} _.url - Url string or URL object
+ * 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 {any} _.body
- *   Data that will be converted to a JSON encoded string and send to the server
+ * @param {import('./typedef').JsonPostOptions} options
+ *   Request configuration options
  *
- * @param {object} [_.urlSearchParams]
- *   Parameters that should be added to the request url.
+ * @returns {Promise<any>} Parsed JSON data
  *
- *   - Be careful when using urlSearchParams in POST requests, it can be
- *     confusing since the parameters usually go in the body part of
- *     the request.
+ * @example
+ * // Basic JSON POST request
+ * try {
+ *   const newUser = {
+ *     name: "Jane Smith",
+ *     email: "jane@example.com"
+ *   };
  *
- * @param {[string, string][]} [_.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" ]
+ *   const data = await jsonPost({
+ *     url: 'https://api.example.com/users',
+ *     body: JSON.stringify(newUser)
+ *   });
  *
- * @param {boolean} [_.withCredentials=false]
+ *   console.log('Created user with ID:', data.id);
+ * } catch (error) {
+ *   console.error('Failed to create user:', error.message);
+ * }
  *
- * @throws ResponseError
- *   If a network error occurred or the response was not ok
- *
- * @returns {Promise<any>} parsed JSON data
+ * @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({
-	url,
-	body,
-	urlSearchParams,
-	headers,
-	withCredentials
-}) {
-	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: 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;
+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/response.d.ts

@@ -1,55 +1,124 @@
 /**
+ * Callback function that reports progress of data loading
+ *
  * @callback progressCallback
+ *
  * @param {object} _
- * @param {number} _.bytesLoaded
- * @param {number} _.size
+ * @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
+ * 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 {object} response
- * @param {string} url - used to produce useful error messages
+ * @param {string} url - The URL used for the request (for error messages)
  *
- * @throws {Error} not found
- * @throws {Error} internal server error
+ * @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
+ * @param {Response} response - Fetch Response object
  *
- * @returns {number} response size or 0 if unknown
+ * @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.
  *
- * @example
- *   const response = await waitForAndCheckResponse( responsePromise );
+ * @param {Promise<Response>} responsePromise - Promise that resolves to a Response
  *
- * @param {Promise<Response>} responsePromise
- * @param {string|URL} url - An url that is used for error messages
+ * @param {string|URL} url - URL used for the request (for error messages)
  *
- * @throws ResponseError - A response error if something went wrong
+ * @throws {ResponseError} When a network error occurs or response is not ok
  *
- * @returns {Promise<Response>} response
+ * @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
- * - Progress can be monitored by suppying an onProgress callback
- * - Loading can be aborted by calling the returned abort function
+ * Load response body as ArrayBuffer with progress monitoring and abort capability
  *
- * @param {Response} response - Fetch response
- * @param {progressCallback} onProgress
+ * 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.
  *
- * @returns {{ bufferPromise: Promise<ArrayBuffer>, abort: () => void }}
+ * @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): {
+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;