@hkdigital/lib-core 0.3.1

package/dist/util/http/headers.js

@@ -0,0 +1,75 @@
+import * as expect from '../expect/index.js';
+
+/**
+ * Set headers in an existing `Headers` object
+ *
+ * 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)');
+  }
+
+  // expect.objectNoArray(pairs);
+
+  if (pairs instanceof Headers) {
+    throw new Error(
+    	'Invalid parameter [pairs] (should not be a Headers object)');
+  }
+
+  if (!pairs) {
+    return;
+  }
+
+  if (typeof pairs !== 'object') {
+    throw new Error('Invalid value for parameter [pairs]');
+  }
+
+  if (!Array.isArray(pairs)) {
+    pairs = Object.entries(pairs);
+  }
+
+  for (const [name, value] of pairs) {
+    expect.notEmptyString(name);
+    expect.notEmptyString(value);
+
+    // @note Headers should be encoded lowercase in HTTP2
+    const nameLower = name.toLowerCase();
+
+    target.set(nameLower, value); /* overwrites existing value */
+  }
+}

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

@@ -0,0 +1,267 @@
+/**
+ * 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 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 httpPost(options: import("./typedef").HttpRequestOptions): Promise<Response>;
+/**
+ * Make a PUT request
+ *
+ * This function performs an HTTP PUT request, typically used for updating
+ * or replacing resources. It supports optional body, headers, credentials,
+ * and timeout functionality.
+ *
+ * @param {import('./typedef').HttpRequestOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<Response>} Response promise
+ *
+ * @example
+ * // Update a user resource
+ * const response = await httpPut({
+ *   url: 'https://api.example.com/users/123',
+ *   body: JSON.stringify({ name: 'John Doe', email: 'john.doe@example.com' }),
+ *   headers: { 'content-type': 'application/json' }
+ * });
+ *
+ * @example
+ * // Replace a resource with timeout
+ * const response = await httpPut({
+ *   url: 'https://api.example.com/documents/456',
+ *   body: documentData,
+ *   timeoutMs: 10000 // 10 seconds timeout
+ * });
+ */
+export function httpPut(options: import("./typedef").HttpRequestOptions): Promise<Response>;
+/**
+ * Make a DELETE request
+ *
+ * This function performs an HTTP DELETE request, typically used for
+ * removing resources. It supports optional headers, credentials,
+ * and timeout functionality.
+ *
+ * @param {import('./typedef').HttpRequestOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<Response>} Response promise
+ *
+ * @example
+ * // Delete a user resource
+ * const response = await httpDelete({
+ *   url: 'https://api.example.com/users/123'
+ * });
+ *
+ * @example
+ * // Delete with authorization and timeout
+ * const response = await httpDelete({
+ *   url: 'https://api.example.com/posts/456',
+ *   headers: { 'authorization': 'Bearer token123' },
+ *   timeoutMs: 5000
+ * });
+ */
+export function httpDelete(options: import("./typedef").HttpRequestOptions): Promise<Response>;
+/**
+ * Make a PATCH request
+ *
+ * This function performs an HTTP PATCH request, typically used for
+ * partial updates to resources. It supports optional body, headers,
+ * credentials, and timeout functionality.
+ *
+ * @param {import('./typedef').HttpRequestOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<Response>} Response promise
+ *
+ * @example
+ * // Partially update a user's email
+ * const response = await httpPatch({
+ *   url: 'https://api.example.com/users/123',
+ *   body: JSON.stringify({ email: 'newemail@example.com' }),
+ *   headers: { 'content-type': 'application/json' }
+ * });
+ *
+ * @example
+ * // Apply JSON Patch operations
+ * const response = await httpPatch({
+ *   url: 'https://api.example.com/documents/456',
+ *   body: JSON.stringify([
+ *     { op: 'replace', path: '/title', value: 'New Title' },
+ *     { op: 'add', path: '/tags/-', value: 'updated' }
+ *   ]),
+ *   headers: { 'content-type': 'application/json-patch+json' }
+ * });
+ */
+export function httpPatch(options: import("./typedef").HttpRequestOptions): Promise<Response>;
+/**
+ * Make an OPTIONS request
+ *
+ * This function performs an HTTP OPTIONS request, typically used for
+ * discovering allowed methods on a resource or for CORS preflight requests.
+ * It supports optional headers, credentials, and timeout functionality.
+ *
+ * @param {import('./typedef').HttpRequestOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<Response>} Response promise
+ *
+ * @example
+ * // Check allowed methods on a resource
+ * const response = await httpOptions({
+ *   url: 'https://api.example.com/users/123'
+ * });
+ *
+ * const allowedMethods = response.headers.get('Allow');
+ * console.log('Allowed methods:', allowedMethods);
+ *
+ * @example
+ * // CORS preflight check
+ * const response = await httpOptions({
+ *   url: 'https://api.example.com/data',
+ *   headers: {
+ *     'Access-Control-Request-Method': 'POST',
+ *     'Access-Control-Request-Headers': 'Content-Type'
+ *   }
+ * });
+ */
+export function httpOptions(options: import("./typedef").HttpRequestOptions): Promise<Response>;
+/**
+ * Make a HEAD request
+ *
+ * This function performs an HTTP HEAD request, which returns only the
+ * headers of a response without the body. It's useful for checking
+ * resource existence, getting metadata, or cache validation.
+ *
+ * @param {import('./typedef').HttpRequestOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<Response>} Response promise (with empty body)
+ *
+ * @example
+ * // Check if a resource exists
+ * const response = await httpHead({
+ *   url: 'https://api.example.com/users/123'
+ * });
+ *
+ * if (response.ok) {
+ *   console.log('User exists');
+ *   console.log('Last modified:', response.headers.get('Last-Modified'));
+ * }
+ *
+ * @example
+ * // Get content length without downloading
+ * const response = await httpHead({
+ *   url: 'https://api.example.com/large-file.zip'
+ * });
+ *
+ * const contentLength = response.headers.get('Content-Length');
+ * console.log('File size:', contentLength, 'bytes');
+ *
+ * @example
+ * // Cache validation
+ * const response = await httpHead({
+ *   url: 'https://api.example.com/data',
+ *   headers: { 'If-None-Match': '"cached-etag-value"' }
+ * });
+ *
+ * if (response.status === 304) {
+ *   console.log('Cache is still valid');
+ * }
+ */
+export function httpHead(options: import("./typedef").HttpRequestOptions): Promise<Response>;
+/**
+ * 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 httpRequest(options: import("./typedef").HttpRequestOptions): Promise<Response>;
+/**
+ * Default configuration for HTTP requests
+ *
+ * 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.
+ *
+ * @type {Object}
+ */
+export const DEFAULT_HTTP_CONFIG: any;