@hkdigital/lib-core 0.3.1

package/dist/classes/cache/MemoryResponseCache.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview In-memory implementation of response cache.
+ *
+ * This implementation provides a simple in-memory cache for HTTP responses
+ * with the same API as IndexedDbCache. It's useful for tests and environments
+ * where persistent storage isn't needed or available.
+ *
+ * @example
+ * // Create a memory cache
+ * const cache = new MemoryResponseCache();
+ *
+ * // Store a response
+ * const response = await fetch('https://example.com/api/data');
+ * await cache.set('api-data', response, { expiresIn: 3600000 });
+ *
+ * // Retrieve a cached response
+ * const cached = await cache.get('api-data');
+ * if (cached) {
+ *   console.log(cached.response);
+ * }
+ */
+/**
+ * @typedef {Object} CacheEntry
+ * @property {Response} response - Cached Response object
+ * @property {Object} metadata - Cache entry metadata
+ * @property {string} url - Original URL
+ * @property {number} timestamp - When the entry was cached
+ * @property {number|null} expires - Expiration timestamp (null if no expiration)
+ * @property {string|null} etag - ETag header if present
+ * @property {string|null} lastModified - Last-Modified header if present
+ */
+/**
+ * In-memory response cache implementation
+ */
+export default class MemoryResponseCache {
+    /**
+     * Internal cache storage using Map
+     * @type {Map<string, Object>}
+     */
+    cache: Map<string, any>;
+    /**
+     * Get a cached response
+     *
+     * @param {string} key - Cache key
+     * @returns {Promise<CacheEntry|null>} Cache entry or null if not found/expired
+     */
+    get(key: string): Promise<CacheEntry | null>;
+    /**
+     * Store a response in the cache
+     *
+     * @param {string} key - Cache key
+     * @param {Response} response - Response to cache
+     * @param {Object} [metadata={}] - Cache metadata
+     * @returns {Promise<void>}
+     */
+    set(key: string, response: Response, metadata?: any): Promise<void>;
+    /**
+     * Delete a cached entry
+     *
+     * @param {string} key - Cache key
+     * @returns {Promise<boolean>} True if entry was deleted
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all cached responses
+     *
+     * @returns {Promise<void>}
+     */
+    clear(): Promise<void>;
+    /**
+     * Close the cache (no-op for memory cache, for API compatibility)
+     *
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+}
+export type CacheEntry = {
+    /**
+     * - Cached Response object
+     */
+    response: Response;
+    /**
+     * - Cache entry metadata
+     */
+    metadata: any;
+    /**
+     * - Original URL
+     */
+    url: string;
+    /**
+     * - When the entry was cached
+     */
+    timestamp: number;
+    /**
+     * - Expiration timestamp (null if no expiration)
+     */
+    expires: number | null;
+    /**
+     * - ETag header if present
+     */
+    etag: string | null;
+    /**
+     * - Last-Modified header if present
+     */
+    lastModified: string | null;
+};

package/dist/classes/cache/MemoryResponseCache.js

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview In-memory implementation of response cache.
+ *
+ * This implementation provides a simple in-memory cache for HTTP responses
+ * with the same API as IndexedDbCache. It's useful for tests and environments
+ * where persistent storage isn't needed or available.
+ *
+ * @example
+ * // Create a memory cache
+ * const cache = new MemoryResponseCache();
+ *
+ * // Store a response
+ * const response = await fetch('https://example.com/api/data');
+ * await cache.set('api-data', response, { expiresIn: 3600000 });
+ *
+ * // Retrieve a cached response
+ * const cached = await cache.get('api-data');
+ * if (cached) {
+ *   console.log(cached.response);
+ * }
+ */
+
+/**
+ * @typedef {Object} CacheEntry
+ * @property {Response} response - Cached Response object
+ * @property {Object} metadata - Cache entry metadata
+ * @property {string} url - Original URL
+ * @property {number} timestamp - When the entry was cached
+ * @property {number|null} expires - Expiration timestamp (null if no expiration)
+ * @property {string|null} etag - ETag header if present
+ * @property {string|null} lastModified - Last-Modified header if present
+ */
+
+/**
+ * In-memory response cache implementation
+ */
+export default class MemoryResponseCache {
+  /**
+   * Create a new in-memory cache
+   */
+  constructor() {
+    /**
+     * Internal cache storage using Map
+     * @type {Map<string, Object>}
+     */
+    this.cache = new Map();
+  }
+
+  /**
+   * Get a cached response
+   *
+   * @param {string} key - Cache key
+   * @returns {Promise<CacheEntry|null>} Cache entry or null if not found/expired
+   */
+  async get(key) {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if expired
+    if (entry.expires && Date.now() > entry.expires) {
+      this.delete(key);
+      return null;
+    }
+
+    // Update last accessed time
+    entry.lastAccessed = Date.now();
+
+    return {
+      response: entry.response.clone(),
+      metadata: entry.metadata,
+      url: entry.url,
+      timestamp: entry.timestamp,
+      expires: entry.expires,
+      etag: entry.etag,
+      lastModified: entry.lastModified
+    };
+  }
+
+  /**
+   * Store a response in the cache
+   *
+   * @param {string} key - Cache key
+   * @param {Response} response - Response to cache
+   * @param {Object} [metadata={}] - Cache metadata
+   * @returns {Promise<void>}
+   */
+  async set(key, response, metadata = {}) {
+    const now = Date.now();
+
+    // Calculate expiration time if expiresIn is provided
+    let expires = metadata.expires || null;
+    if (!expires && metadata.expiresIn) {
+      expires = now + metadata.expiresIn;
+    }
+
+    this.cache.set(key, {
+      response: response.clone(),
+      metadata,
+      url: response.url,
+      timestamp: now,
+      lastAccessed: now,
+      expires,
+      etag: response.headers.get('ETag'),
+      lastModified: response.headers.get('Last-Modified')
+    });
+  }
+
+  /**
+   * Delete a cached entry
+   *
+   * @param {string} key - Cache key
+   * @returns {Promise<boolean>} True if entry was deleted
+   */
+  async delete(key) {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all cached responses
+   *
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    this.cache.clear();
+  }
+
+  /**
+   * Close the cache (no-op for memory cache, for API compatibility)
+   *
+   * @returns {Promise<void>}
+   */
+  async close() {
+    // No-op for memory cache
+  }
+}

package/dist/classes/cache/index.d.ts

@@ -0,0 +1,3 @@
+export { default as MemoryResponseCache } from "./MemoryResponseCache.js";
+export { default as IndexedDbCache } from "./IndexedDbCache.js";
+export * from "./typedef.js";

package/dist/classes/cache/index.js

@@ -0,0 +1,5 @@
+
+export { default as MemoryResponseCache } from "./MemoryResponseCache.js";
+export { default as IndexedDbCache } from "./IndexedDbCache.js";
+
+export * from './typedef.js';

package/dist/classes/cache/typedef.d.ts

@@ -0,0 +1,67 @@
+declare const _default: {};
+export default _default;
+export type CacheEntry = {
+    /**
+     * - Cached Response object
+     */
+    response: Response;
+    /**
+     * - Cache entry metadata
+     */
+    metadata: any;
+    /**
+     * - Original URL
+     */
+    url: string;
+    /**
+     * - When the entry was cached
+     */
+    timestamp: number;
+    /**
+     * - Expiration timestamp (null if no expiration)
+     */
+    expires: number | null;
+    /**
+     * - ETag header if present
+     */
+    etag: string | null;
+    /**
+     * - Last-Modified header if present
+     */
+    lastModified: string | null;
+    cacheVersion: string | null;
+};
+export type CacheStorage = {
+    /**
+     *   Get a cached response for a key
+     */
+    get: (arg0: string) => Promise<CacheEntry | null>;
+    /**
+     *   Store a response in the cache
+     */
+    set: (arg0: string, arg1: Response, arg2: any) => Promise<void>;
+    /**
+     *   Remove a cached response
+     */
+    delete: (arg0: string) => Promise<boolean>;
+    /**
+     *   Clear all cached responses
+     */
+    clear: () => Promise<void>;
+};
+export type IDBRequestEvent = {
+    /**
+     * - The request that generated the event
+     */
+    target: IDBRequest;
+};
+export type IDBVersionChangeEvent = {
+    /**
+     * - The request that generated the event
+     */
+    target: IDBOpenDBRequest;
+    /**
+     * - The transaction for database upgrade
+     */
+    transaction?: IDBTransaction;
+};

package/dist/classes/cache/typedef.js

@@ -0,0 +1,41 @@
+
+/**
+ * @typedef {Object} CacheEntry
+ * @property {Response} response - Cached Response object
+ * @property {Object} metadata - Cache entry metadata
+ * @property {string} url - Original URL
+ * @property {number} timestamp - When the entry was cached
+ * @property {number|null} expires - Expiration timestamp (null if no expiration)
+ * @property {string|null} etag - ETag header if present
+ * @property {string|null} lastModified - Last-Modified header if present
+ * @property {string|null} cacheVersion
+ */
+
+/**
+ * @typedef {Object} CacheStorage
+ * @property {function(string): Promise<CacheEntry|null>} get
+ *   Get a cached response for a key
+ * @property {function(string, Response, Object): Promise<void>} set
+ *   Store a response in the cache
+ * @property {function(string): Promise<boolean>} delete
+ *   Remove a cached response
+ * @property {function(): Promise<void>} clear
+ *   Clear all cached responses
+ */
+
+// > IndexedDB
+
+/**
+ * @typedef {Object} IDBRequestEvent
+ * @property {IDBRequest} target - The request that generated the event
+ */
+
+/**
+ * @typedef {Object} IDBVersionChangeEvent
+ * @property {IDBOpenDBRequest} target - The request that generated the event
+ * @property {IDBTransaction} [target.transaction] - The transaction for database upgrade
+ */
+
+// > Export default
+
+export default {};

package/dist/classes/data/IterableTree.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @typedef {object} Options
+ * @property {boolean} walkArrays
+ * @property {boolean} ignoreEmptyObjectLeaves
+ * @property {boolean} expandPathKeys
+ * @property {boolean} outputIntermediateNodes
+ */
+export default class IterableTree {
+    /**
+     * Construct an object that can be used to iterate paths and values in
+     * an object.
+     * - Returns path-value pairs for all leaves of the object (tree)
+     * - Iterates "own properties" only (not inherited properties)
+     *
+     * @param {object} obj - Object to iterate
+     * @param {Options} [options]
+     * @param {string[]} [_parentArrPath]
+     *
+     *
+     * @return {Iterator} iterable object
+     */
+    constructor(obj: object, options?: Options, _parentArrPath?: string[]);
+    obj: any;
+    _parentArrPath: string[];
+    /**
+     * Get an iterator to iterate over all object [ path, value ] entries
+     *
+     * @returns {Iterator} object entries iterator
+     */
+    entries(): Iterator<any, any, any>;
+    /**
+     * Get an iterator to iterate over all object paths
+     *
+     * @returns {Iterator} object path iterator
+     */
+    paths(): Iterator<any, any, any>;
+    /**
+     * Get an iterator to iterate over all values at the leaves of the paths in
+     * the object
+     *
+     * @returns {Iterator} object value iterator
+     */
+    values(): Iterator<any, any, any>;
+    #private;
+}
+export type Options = {
+    walkArrays: boolean;
+    ignoreEmptyObjectLeaves: boolean;
+    expandPathKeys: boolean;
+    outputIntermediateNodes: boolean;
+};

package/dist/classes/data/IterableTree.js

@@ -0,0 +1,243 @@
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../../util/expect/index.js';
+
+import { PATH_SEPARATOR } from '../../util/object/index.js';
+
+/* ------------------------------------------------------------------ Typedef */
+
+/**
+ * @typedef {object} Options
+ * @property {boolean} walkArrays
+ * @property {boolean} ignoreEmptyObjectLeaves
+ * @property {boolean} expandPathKeys
+ * @property {boolean} outputIntermediateNodes
+ */
+
+/* ------------------------------------------------------------------ Exports */
+
+export default class IterableTree {
+	/**
+	 * @type {Options}
+	 */
+	#options;
+
+	/**
+	 * Construct an object that can be used to iterate paths and values in
+	 * an object.
+	 * - Returns path-value pairs for all leaves of the object (tree)
+	 * - Iterates "own properties" only (not inherited properties)
+	 *
+	 * @param {object} obj - Object to iterate
+	 * @param {Options} [options]
+	 * @param {string[]} [_parentArrPath]
+	 *
+	 *
+	 * @return {Iterator} iterable object
+	 */
+	constructor(obj, options, _parentArrPath) {
+		//super( ...arguments );
+
+		expect.object(obj);
+
+		this.obj = obj;
+
+		this.#options = Object.assign(
+			{
+				walkArrays: false,
+				ignoreEmptyObjectLeaves: false,
+				expandPathKeys: false,
+				outputIntermediateNodes: false
+			},
+			options
+		);
+
+		this._parentArrPath = _parentArrPath || null;
+	}
+
+	/* --------------------------------------------------------- Public methods */
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Get an iterator to iterate over all object [ path, value ] entries
+	 *
+	 * @returns {Iterator} object entries iterator
+	 */
+	*entries() {
+		const obj = this.obj;
+		const parentArrPath = this._parentArrPath;
+
+		const options = this.options;
+
+		let { expandPathKeys, ignoreEmptyObjectLeaves, outputIntermediateNodes } = this.#options;
+
+		if (parentArrPath) {
+			// Never expand keys if not in root object
+			expandPathKeys = false;
+		}
+
+		// @note keys are own properties only
+		const keys = Object.keys(obj);
+
+		let pathKeys;
+
+		if (expandPathKeys) {
+			pathKeys = [];
+		}
+
+		// -- STEP 1: Normal object iteration (and gather path keys)
+
+		for (let j = 0, n = keys.length; j < n; j = j + 1) {
+			const key = keys[j];
+
+			if (expandPathKeys && key.includes(PATH_SEPARATOR)) {
+				// Gather pathKeys
+				pathKeys.push(key);
+				continue;
+			}
+
+			const valueAtPath = obj[key];
+
+			if (undefined === valueAtPath) {
+				// Ignore path-value pair if valueAtPath is undefined
+				continue;
+			}
+
+			let path;
+
+			if (parentArrPath) {
+				path = parentArrPath.slice(0);
+				path.push(key);
+			} else {
+				path = [key];
+			}
+
+			// No recursion >>
+
+			if (!this.#shouldRecurse(valueAtPath)) {
+				if (
+					ignoreEmptyObjectLeaves &&
+					valueAtPath instanceof Object &&
+					0 === Object.keys(valueAtPath).length
+				) {
+					// Ignore empty object leave
+					continue;
+				}
+
+				yield [path, valueAtPath];
+				continue;
+			}
+
+			// Recursion >>
+
+			// console.log( { path, valueAtPath, outputIntermediateNodes } );
+
+			if (outputIntermediateNodes) {
+				// outputIntermediateNodes=true
+				// -> Output itermediate node
+
+				if (Array.isArray(valueAtPath)) {
+					// Intermediate node is an array
+					yield [path, []];
+				} else {
+					// Intermediate node is plain object
+					yield [path, {}];
+				}
+			}
+
+			const objectIterator = new IterableTree(valueAtPath, options, path);
+
+			for (const entry of objectIterator.entries()) {
+				yield entry;
+			}
+		} // end for
+
+		// -- STEP 2: Output entries from "path keys"
+
+		if (!pathKeys || !pathKeys.length) {
+			// No path keys -> done
+			return;
+		}
+
+		for (let j = 0, n = pathKeys.length; j < n; j = j + 1) {
+			// @note path keys do not output intermediate nodes
+
+			const key = pathKeys[j];
+
+			const valueAtPath = obj[key];
+			const path = key.split(PATH_SEPARATOR);
+
+			yield [path, valueAtPath];
+		}
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Get an iterator to iterate over all object paths
+	 *
+	 * @returns {Iterator} object path iterator
+	 */
+	*paths() {
+		for (const entry of this.entries()) {
+			yield entry[0];
+		}
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Get an iterator to iterate over all values at the leaves of the paths in
+	 * the object
+	 *
+	 * @returns {Iterator} object value iterator
+	 */
+	*values() {
+		for (const entry of this.entries()) {
+			yield entry[1];
+		}
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Returns true if the iterator should recurse into the specified value
+	 *
+	 * @param {string} value
+	 *
+	 * @return {boolean} true if the value should be iterated
+	 */
+	#shouldRecurse(value) {
+		if (!(value instanceof Object)) {
+			// not an object -> no recursion
+			return false;
+		}
+
+		const walkArrays = this.#options.walkArrays;
+
+		if (walkArrays && Array.isArray(value)) {
+			// walkArrays=true AND isArray
+
+			if (!value.length) {
+				// Array is empty -> no recursion
+				return false;
+			}
+
+			return true;
+		}
+
+		if ('[object Object]' !== value.toString()) {
+			// Not a plain object -> no recursion
+			return false;
+		}
+
+		if (Object.keys(value).length) {
+			// Object is not empty -> recursion
+			return true;
+		}
+
+		// Otherwise -> no recursion
+		return false;
+	}
+} // end class

package/dist/classes/data/Selector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Construct a Selector class
+ */
+export default class Selector {
+    /**
+     * Constructor
+     *
+     * @param {object|null} selector
+     */
+    constructor(selector: object | null);
+    /**
+     * Returns the first item from the list of items that matches the selector
+     *
+     * @template {object} T
+     * @param {T[]|null} items
+     *
+     * @returns {T|null} item or null if not found
+     */
+    findFirst<T extends unknown>(items: T[] | null): T | null;
+    /**
+     * Returns all items from the list of items that match the selector
+     *
+     * @template {object} T
+     * @param {T[]|null} items
+     *
+     * @returns {T[]|null} item or null if not found
+     */
+    findAll<T extends unknown>(items: T[] | null): T[] | null;
+    #private;
+}