@hkdigital/lib-core 0.3.1

package/dist/util/function/index.js

@@ -0,0 +1,218 @@
+/**
+ * function.js
+ *
+ * @description
+ * This file contains code for working with functions
+ *
+ * @example
+ *
+ *   import { once } from "./function.js";
+ *
+ *   const sayHelloOnce = once( () => { console.log("Hello"); } );
+ *
+ *   sayHelloOnce();
+ *   sayHelloOnce();
+ *
+ * @example
+ *
+ *   import { defer } from './process.js';
+ *
+ *   defer( () => {
+ *     console.log("The execution of the function has been defered");
+ *   } );
+ */
+
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../expect/index.js';
+
+/* ---------------------------------------------------------------- Internals */
+
+const NEXT_TICK_MESSAGE = 'hk-next-tick';
+
+/**
+ * Detect and return the most suitable setImmediate implementation available
+ * on the current platform
+ */
+function set_immediate_implementation() {
+	if (typeof global !== 'undefined') {
+		if (undefined !== global.setImmediate) {
+			return global.setImmediate;
+		}
+	} else if (typeof window !== 'undefined') {
+		if (window.postMessage && window.addEventListener) {
+			const queue = [];
+
+			window.addEventListener(
+				'message',
+				(event) => {
+					const source = event.source;
+
+					if ((source === window || source === null) && event.data === NEXT_TICK_MESSAGE) {
+						event.stopPropagation();
+						if (queue.length > 0) {
+							const fn = queue.shift();
+							fn();
+						}
+					}
+				},
+				true
+			);
+
+			return function nextTickUsingPostMessage(fn) {
+				expect.function(fn);
+
+				queue.push(fn);
+				window.postMessage(NEXT_TICK_MESSAGE, '*');
+			};
+		}
+	}
+
+	throw new Error('No suitable [setImmediate] implementation available');
+}
+
+/* ------------------------------------------------------------------ Exports */
+
+/**
+ * 'No operation' function
+ * - A function that does nothing
+ */
+export const noop = () => {};
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Wraps a function so that the callback function will be called only once
+ *
+ * @param {function} callback
+ *
+ * @returns {function} callback wrapped in `once` function
+ */
+export function once(callback) {
+	expect.function(callback);
+
+	let ignore = false;
+
+	return function () {
+		if (!ignore) {
+			ignore = true;
+			callback(...arguments);
+		}
+	};
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Returns a debounced function
+ * - The original function is not called more than once during the
+ *   specified interval
+ *
+ * @param {function} fn
+ * @param {number} [intervalMs=200]
+ *
+ * @returns {function} debounced function
+ */
+export function debounce(fn, intervalMs = 200) {
+	let idleTimer;
+	let lastArguments;
+
+	// console.log("debounce");
+
+	return function debounced() {
+		// console.log("debounced");
+
+		if (idleTimer) {
+			// console.log("idleTimer running");
+
+			// The function has been called recently
+			lastArguments = arguments;
+			return;
+		}
+
+		idleTimer = setTimeout(() => {
+			// console.log("idleTimer finished", lastArguments);
+
+			idleTimer = null;
+
+			if (lastArguments) {
+				//
+				// At least one call has been "debounced"
+				// -> make call with last arguments, so function always receives
+				//    the arguments of the last call to the function
+				//
+				fn(...lastArguments);
+				lastArguments = undefined;
+			}
+		}, intervalMs);
+
+		fn(...arguments);
+	};
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Defer the execution of a function
+ *  - Uses the best 'setImmediate' implementation supported by the current
+ *    runtime environment
+ *
+ * @param {function} fn - Function to execute
+ *
+ * --
+ *
+ * @note setImmediate is preferred over nextTick
+ *
+ * @see https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/
+ */
+export const defer = set_immediate_implementation();
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Adds a wrapper around a function that only calls the supplied function
+ * if the (first) supplied argument to the returned function is not `null`
+ *
+ * @param {object} [object]
+ *   Optional function context to be used as `this`
+ *
+ * @param {function} functionOrMethodName
+ *
+ * @returns {function} not null wrapper function
+ */
+// export function ifNotNull( /* object, functionOrMethodName */ )
+// {
+//   let fn;
+
+//   switch( arguments.length )
+//   {
+//     case 1:
+//       fn = arguments[0];
+//       expectFunction( fn, "Missing or invalid parameter [fn]" );
+//       break;
+
+//     case 2:
+//       {
+//         const object = arguments[0];
+//         const methodName = arguments[1];
+
+//         expectObject( object, "Invalid parameter [object]" );
+//         expectNotEmptyString( methodName, "Invalid parameter [methodName]" );
+
+//         fn = object[ methodName ].bind( object );
+
+//         expectFunction( fn, `Invalid method [<object>.${methodName}]` );
+//       }
+//       break;
+
+//     default:
+//       throw new Error("Invalid number of arguments");
+//   }
+
+//   return async ( value ) => {
+//     if( null !== value )
+//     {
+//       await fn( value );
+//     }
+//   };
+// }

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

@@ -0,0 +1,10 @@
+/**
+ * Check if a point lies within a polygon
+ *
+ * @param {number} xPct - X-coordinate as percentage
+ * @param {number} yPct - Y-coordinate as percentage
+ * @param {Array} polygon - Array of [x, y] points
+ *
+ * @returns {boolean} True if the point lies within the polygon
+ */
+export function isPointInPolygon(xPct: number, yPct: number, polygon: any[]): boolean;

package/dist/util/geo/index.js

@@ -0,0 +1,26 @@
+/**
+ * Check if a point lies within a polygon
+ *
+ * @param {number} xPct - X-coordinate as percentage
+ * @param {number} yPct - Y-coordinate as percentage
+ * @param {Array} polygon - Array of [x, y] points
+ *
+ * @returns {boolean} True if the point lies within the polygon
+ */
+export function isPointInPolygon(xPct, yPct, polygon) {
+  let inside = false;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+    const xi = polygon[i][0];
+    const yi = polygon[i][1];
+    const xj = polygon[j][0];
+    const yj = polygon[j][1];
+
+    const intersect =
+      yi > yPct !== yj > yPct &&
+      xPct < ((xj - xi) * (yPct - yi)) / (yj - yi) + xi;
+    if (intersect) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Store a response in the cache
+ *
+ * @param {object} cacheKeyParams - Parameters to use for cache key generation
+ * @param {string|URL} cacheKeyParams.url - URL string or URL object
+ * @param {object} [cacheKeyParams.headers] - Request headers that affect caching
+ * @param {Response} response - Response to cache
+ * @param {object} metadata - Cache metadata
+ * @returns {Promise<void>}
+ */
+export function storeResponseInCache(cacheKeyParams: {
+    url: string | URL;
+    headers?: object;
+}, response: Response, metadata: object): Promise<void>;
+/**
+ * Get a cached response if available and valid
+ *
+ * @param {object} cacheKeyParams - Parameters to use for cache key generation
+ * @param {string|URL} cacheKeyParams.url - URL string or URL object
+ * @param {object} [cacheKeyParams.headers] - Request headers that affect caching
+ *
+ * @returns {Promise<Response|import('./typedef').ResponseWithStale|null>}
+ *   Cached response or null
+ */
+export function getCachedResponse(cacheKeyParams: {
+    url: string | URL;
+    headers?: object;
+}): Promise<Response | import("./typedef").ResponseWithStale | null>;

package/dist/util/http/caching.js

@@ -0,0 +1,263 @@
+import {
+  MemoryResponseCache,
+  IndexedDbCache
+} from '../../classes/cache';
+
+import { browser } from '$app/environment';
+
+import { isTestEnv } from '../env';
+
+let defaultCacheStorage = null;
+
+function getCacheStorage()
+{
+  if( !defaultCacheStorage )
+  {
+    let type;
+
+    if( !browser || isTestEnv )
+    {
+      type = 'memory';
+    }
+    else {
+      type = 'indexed-db';
+    }
+
+    defaultCacheStorage = createCacheStorage( type);
+  }
+
+  return defaultCacheStorage
+}
+
+/**
+ * Store a response in the cache
+ *
+ * @param {object} cacheKeyParams - Parameters to use for cache key generation
+ * @param {string|URL} cacheKeyParams.url - URL string or URL object
+ * @param {object} [cacheKeyParams.headers] - Request headers that affect caching
+ * @param {Response} response - Response to cache
+ * @param {object} metadata - Cache metadata
+ * @returns {Promise<void>}
+ */
+export async function storeResponseInCache(cacheKeyParams, response, metadata) {
+  try {
+    const { url: rawUrl, ...headers } = cacheKeyParams;
+    const url = typeof rawUrl === 'string' ? rawUrl : rawUrl.toString();
+
+    // Generate cache key
+    const cacheKey = generateCacheKey(url, headers);
+
+    // Extract Vary header info
+    const varyHeader = response.headers.get('Vary');
+    let varyHeaders = null;
+
+    if (varyHeader) {
+      varyHeaders = {};
+      const varyFields = varyHeader.split(',').map(field => field.trim().toLowerCase());
+
+      // Store hashes of headers mentioned in Vary
+      for (const field of varyFields) {
+        if (field !== '*') {
+          const value = headers[field];
+          varyHeaders[field] = hashValue(value);
+        }
+      }
+    }
+
+    // Add vary headers to metadata
+    const enhancedMetadata = {
+      ...metadata,
+      varyHeaders
+    };
+
+    // Store in cache
+    await getCacheStorage().set(cacheKey, response, enhancedMetadata);
+  } catch (error) {
+    console.error('Cache storage error:', error);
+  }
+}
+
+/**
+ * Get a cached response if available and valid
+ *
+ * @param {object} cacheKeyParams - Parameters to use for cache key generation
+ * @param {string|URL} cacheKeyParams.url - URL string or URL object
+ * @param {object} [cacheKeyParams.headers] - Request headers that affect caching
+ *
+ * @returns {Promise<Response|import('./typedef').ResponseWithStale|null>}
+ *   Cached response or null
+ */
+export async function getCachedResponse(cacheKeyParams) {
+  try {
+    const { url: rawUrl, ...headers } = cacheKeyParams;
+    const url = typeof rawUrl === 'string' ? rawUrl : rawUrl.toString();
+
+    // Generate cache key
+    const cacheKey = generateCacheKey(url, headers);
+
+    // Get cached entry
+    const cachedEntry = await getCacheStorage().get(cacheKey);
+
+    if (!cachedEntry) {
+      return null;
+    }
+
+    // Validate based on Vary headers
+    if (!isValidForVaryHeaders(cachedEntry, headers)) {
+      return null;
+    }
+
+    const { response, metadata } = cachedEntry;
+
+    // Check if expired
+    const isExpired = metadata.expires && Date.now() > metadata.expires;
+
+    if (!isExpired) {
+      // Not expired, return as-is
+      return response;
+    }
+
+    // Response is stale, add stale info
+    return enhanceResponseWithStale(response, {
+      isStale: true,
+      fresh: null,  // No fresh data available yet
+      timestamp: metadata.timestamp,
+      expires: metadata.expires
+    });
+  } catch (error) {
+    console.error('Cache retrieval error:', error);
+    return null;
+  }
+}
+
+// > Internal functions
+
+/**
+ * Create a cache storage adapter
+ * @param {string} type Type of storage ('indexed-db', 'memory')
+ * @param {Object} options Options for the storage adapter
+ *
+ * @returns {import('../../classes/cache').CacheStorage}
+ */
+function createCacheStorage(type = 'indexed-db', options = {}) {
+  switch (type) {
+    case 'indexed-db':
+      return new IndexedDbCache(
+        {
+          dbName: 'http-cache',
+          storeName: 'responses'
+        } );
+
+    case 'memory':
+      return new MemoryResponseCache();
+
+    default:
+      throw new Error(`Unsupported cache storage type: ${type}`);
+  }
+}
+
+/**
+ * Check if cached entry is valid based on Vary headers
+ *
+ * @param {object} cachedEntry - Cached entry with response and metadata
+ * @param {object} headers - Current request headers
+ * @returns {boolean} True if valid for these headers
+ */
+function isValidForVaryHeaders(cachedEntry, headers) {
+  const { metadata } = cachedEntry;
+
+  // If no vary headers stored, consider valid
+  if (!metadata.varyHeaders) {
+    return true;
+  }
+
+  // Check each stored vary header
+  for (const [name, storedHash] of Object.entries(metadata.varyHeaders)) {
+    const currentValue = headers[name];
+    const currentHash = hashValue(currentValue);
+
+    // Compare hashes
+    if (currentHash !== storedHash) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Generate a cache key based on URL and relevant headers
+ *
+ * @param {string} url - URL string
+ * @param {object} headers - Request headers
+ * @returns {string} Cache key
+ */
+function generateCacheKey(url, headers) {
+  // Start with a hash of the URL
+  const keyParts = [hashValue(url)];
+
+  // If we have headers
+  if (headers && Object.keys(headers).length > 0) {
+    // Get all header names, sorted for consistency
+    const headerNames = Object.keys(headers).sort();
+
+    // Create a hash for each header value
+    const headerHashes = headerNames.map(name => {
+      const value = headers[name];
+      // Format: "name:hash_of_value"
+      return `${name}:${hashValue(value)}`;
+    });
+
+    if (headerHashes.length > 0) {
+      keyParts.push(headerHashes.join('|'));
+    }
+  }
+
+  return keyParts.join('::');
+}
+
+/**
+ * Create a hash of a value
+ *
+ * @param {string} value - Value to hash
+ * @returns {string} Hash representation
+ */
+function hashValue(value) {
+  if (!value) return '';
+
+  // Convert to string if not already
+  const stringValue = String(value);
+
+  // Simple non-cryptographic hash function
+  let hash = 0;
+  for (let i = 0; i < stringValue.length; i++) {
+    const char = stringValue.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return hash.toString(16); // Convert to hex
+}
+
+
+/**
+ * Enhance a Response object with stale data properties
+ *
+ * @param {Response} response - The original Response object
+ * @param {import('./typedef').StaleInfo} staleInfo - Stale data information
+ *
+ * @returns {import('./typedef').ResponseWithStale}
+ *   Enhanced response with stale data properties
+ */
+function enhanceResponseWithStale(response, staleInfo) {
+  // Create a new object that inherits from Response prototype
+  const enhanced = Object.create(
+    Object.getPrototypeOf(response),
+    Object.getOwnPropertyDescriptors(response)
+  );
+
+  // Add stale properties
+  enhanced.isStale = staleInfo.isStale || false;
+  enhanced.fresh = staleInfo.fresh || null;
+
+  return enhanced;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Try to get error information from the server error response
+ *
+ * This method tries to get error info from JSON responses. The
+ * error info may be set as one of the following properties
+ *
+ * - message
+ * - error
+ * - messages (array)
+ * - errors (array)
+ *
+ * Otherwise tris method will use the plain text response
+ *
+ * @param {object} response
+ *
+ * @returns {Error} error
+ */
+export function getErrorFromResponse(response: object): Error;

package/dist/util/http/errors.js

@@ -0,0 +1,97 @@
+import * as expect from '../expect/index.js';
+
+import { CONTENT_TYPE } from '../../constants/http/index.js';
+
+import { APPLICATION_JSON } from '../../constants/mime/index.js';
+
+/**
+ * Try to get error information from the server error response
+ *
+ * This method tries to get error info from JSON responses. The
+ * error info may be set as one of the following properties
+ *
+ * - message
+ * - error
+ * - messages (array)
+ * - errors (array)
+ *
+ * Otherwise tris method will use the plain text response
+ *
+ * @param {object} response
+ *
+ * @returns {Error} error
+ */
+export async function getErrorFromResponse(response) {
+	expect.object(response);
+
+	let message;
+	let details = null;
+
+	const headers = response.headers;
+	const contentType = headers.get(CONTENT_TYPE);
+
+	let content;
+
+	if (contentType === APPLICATION_JSON) {
+		content = await response.json();
+
+		if (content instanceof Object) {
+			if (typeof content.message === 'string') {
+				// Use string propery 'message' as error message
+				message = content.message;
+			} else if (typeof content.error === 'string') {
+				// Use string propery 'error' as error message
+				message = content.error;
+			} else {
+				if (Array.isArray(content.errors)) {
+					// Use array propery 'errors' for error messages
+
+					details = content.errors;
+				} else if (Array.isArray(content.messages)) {
+					// Use array propery 'messages' for error messages
+
+					details = content.messages;
+				}
+
+				if (details) {
+					// Multiple error messages (array) =>
+					//   create string respresentation by combining
+					//   text parts from all error messages
+					const tmp = [];
+
+					for (const current of details) {
+						if (typeof current === 'string') {
+							// Error is a string
+							tmp.push(current);
+						} else if (current instanceof Object && typeof current.message === 'string') {
+							// Error is an object with string property 'message'
+							tmp.push(current.message);
+						} else {
+							// JSON stringify everything else
+							tmp.push(JSON.stringify(current));
+						}
+					} // end for
+
+					message = tmp.join(', ');
+				}
+			}
+		}
+	} else {
+		const tmp = await response.text();
+
+		if (tmp.length) {
+			message = tmp;
+		} else {
+			message = response.statusText;
+		}
+	}
+	// console.log( "message", message );
+
+	const error = new Error(message);
+
+	if (details) {
+		error.details = details;
+	}
+
+	return error;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * 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: Headers, pairs?: null | object | [string, string][]): void;