@hkdigital/lib-core 0.3.1

package/dist/classes/data/Selector.js

@@ -0,0 +1,190 @@
+/**
+ * Selector.js
+ *
+ * @description
+ * This file contains a class that can be used to select items from lists of
+ * objects.
+ *
+ * @TODO
+ * Allow other selection criteria than exact key-value pair matches
+ *
+ * @example
+ *
+ *   import Selector from "./Selector.js";
+ *
+ *   const selector = new Selector( { age: 42 } );
+ *
+ *   const items =
+ *     [
+ *       { name: "Maria", age: 41 },
+ *       { name: "John",  age: 42 },
+ *       { name: "Max", age: 43 }
+ *     ]
+ *
+ *   const item = selector.findFirst( items );
+ *
+ *   console.log( item );
+ */
+
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../../util/expect/index.js';
+
+/* ------------------------------------------------------------------- Export */
+
+/**
+ * Construct a Selector class
+ */
+export default class Selector {
+	/** @type {function|null} test function */
+	#testFn = null;
+
+	/**
+	 * Constructor
+	 *
+	 * @param {object|null} selector
+	 */
+	constructor(selector) {
+		this.#updateTestFn(selector);
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * 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(items) {
+		if (!items) {
+			return null;
+		}
+
+		for (const item of items) {
+			if (this.#testFn(item)) {
+				return item;
+			}
+		}
+
+		return null;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * 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(items) {
+		const result = [];
+
+		if (!items) {
+			return result;
+		}
+
+		for (const item of items) {
+			if (this.#testFn(item)) {
+				result.push(item);
+			}
+		}
+
+		return result;
+	}
+
+	/* ------------------------------------------------------- Internal methods */
+
+	/**
+	 * Update the internal selector function
+	 */
+	#updateTestFn(selector) {
+		// > Case A: selector=null
+
+		if (null === selector) {
+			this.#testFn = this.#returnTrue;
+			return;
+		}
+
+		// > Validate selector
+
+		expect.objectOrNull(selector);
+
+		const keys = Object.keys(selector);
+		const n = keys.length;
+
+		// > Case B: selector has not properties
+
+		if (!n) {
+			this.#testFn = this.#returnTrue;
+			return;
+		}
+
+		// > Case C: selector with single key-value pair
+
+		if (1 === n) {
+			const key = keys[0];
+			const value = selector[key];
+
+			this.#testFn = this.#testKeyValue.bind(this, key, value);
+		}
+
+		// > Case D: selector with multiple key-value pairs
+
+		const selectorValues = [];
+
+		for (const key of keys) {
+			selectorValues.push(selector[key]);
+		}
+
+		this.#testFn = this.#testMultipleKeyValues.bind(this, keys, selectorValues);
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Always return true
+	 * - This function is used if the test function should always return true
+	 *
+	 * @returns {boolean} true
+	 */
+	#returnTrue() {
+		return true;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Return true if the item matches the key-value pair
+	 * - This function is used if the test function should test a
+	 *   single key-value pair
+	 */
+	#testKeyValue(key, value, item) {
+		return value === item[key];
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Return true if the item matches all key-value pairs
+	 * - This function is used if the test function should test multiple
+	 *   key-value pairs
+	 */
+	#testMultipleKeyValues(keys, values, item) {
+		let isMatch = true;
+
+		for (let j = 0, n = keys.length; j < n; j = j + 1) {
+			if (values[j] !== item[keys[j]]) {
+				isMatch = false;
+				break;
+			}
+		} // end for
+
+		return isMatch;
+	}
+} // end class

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

@@ -0,0 +1,2 @@
+export { default as Selector } from "./Selector.js";
+export { default as IterableTree } from "./IterableTree.js";

package/dist/classes/data/index.js

@@ -0,0 +1,2 @@
+export { default as Selector } from './Selector.js';
+export { default as IterableTree } from './IterableTree.js';

package/dist/classes/events/EventEmitter.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview Simple event emitter implementation to support event-based architecture
+ * in service management and other parts of the application.
+ *
+ * This implementation provides standard event publishing and subscription methods
+ * with support for namespaced events, wildcard listeners, and callback removal.
+ *
+ * @example
+ * // Basic usage
+ * import { EventEmitter } from './EventEmitter.js';
+ *
+ * // Create an emitter
+ * const events = new EventEmitter();
+ *
+ * // Subscribe to events
+ * const unsubscribe = events.on('data-loaded', (data) => {
+ *   console.log('Data loaded:', data);
+ * });
+ *
+ * // Subscribe to all events with a specific prefix
+ * events.on('database:*', ({ event, data }) => {
+ *   console.log(`Database event ${event}:`, data);
+ * });
+ *
+ * // Emit events
+ * events.emit('data-loaded', { items: [1, 2, 3] });
+ * events.emit('database:connected', { connectionId: 'abc123' });
+ *
+ * // Clean up when done
+ * unsubscribe();
+ *
+ * // Or remove all listeners
+ * events.removeAllListeners();
+ */
+/**
+ * EventEmitter class for event-based programming
+ */
+export default class EventEmitter {
+    /**
+     * Map to store event handlers
+     * @type {Map<string, Set<Function>>}
+     * @private
+     */
+    private eventHandlers;
+    /**
+     * Map to store wildcard event handlers (events ending with *)
+     * @type {Map<string, Set<Function>>}
+     * @private
+     */
+    private wildcardHandlers;
+    /**
+     * Register an event handler
+     *
+     * @param {string} eventName - Event name to listen for. Can use wildcard (*)
+     *        at the end to listen to all events with a specific prefix.
+     * @param {Function} handler - Handler function to call when event is emitted
+     * @returns {Function} Function to remove this specific handler
+     *
+     * @example
+     * // Listen for a specific event
+     * emitter.on('userLoggedIn', (user) => {
+     *   console.log(`User logged in: ${user.name}`);
+     * });
+     *
+     * // Listen for all events with a prefix
+     * emitter.on('api:*', ({ event, data }) => {
+     *   console.log(`API event ${event}:`, data);
+     * });
+     */
+    on(eventName: string, handler: Function): Function;
+    /**
+     * Register a one-time event handler that will be removed after first execution
+     *
+     * @param {string} eventName - Event name to listen for
+     * @param {Function} handler - Handler function to call when event is emitted
+     * @returns {Function} Function to remove this specific handler
+     *
+     * @example
+     * emitter.once('initialization', () => {
+     *   console.log('Initialization happened');
+     * });
+     */
+    once(eventName: string, handler: Function): Function;
+    /**
+     * Remove an event handler
+     *
+     * @param {string} eventName - Event name the handler was registered for
+     * @param {Function} handler - Handler function to remove
+     * @returns {boolean} True if the handler was removed, false otherwise
+     *
+     * @example
+     * const handler = (data) => console.log(data);
+     * emitter.on('data', handler);
+     * emitter.off('data', handler);
+     */
+    off(eventName: string, handler: Function): boolean;
+    /**
+     * Remove all event handlers for a specific event
+     *
+     * @param {string} [eventName] - Event name to remove handlers for.
+     *        If not provided, removes all handlers for all events.
+     *
+     * @example
+     * // Remove all 'data' event handlers
+     * emitter.removeAllListeners('data');
+     *
+     * // Remove all event handlers
+     * emitter.removeAllListeners();
+     */
+    removeAllListeners(eventName?: string): void;
+    /**
+     * Emit an event
+     *
+     * @param {string} eventName - Name of the event to emit
+     * @param {*} data - Data to pass to event handlers
+     * @returns {boolean} True if there were handlers for this event, false otherwise
+     *
+     * @example
+     * emitter.emit('dataLoaded', { users: [...] });
+     */
+    emit(eventName: string, data: any): boolean;
+    /**
+     * Get the number of listeners for a specific event
+     *
+     * @param {string} eventName - Event name to count listeners for
+     * @returns {number} Number of listeners for this event
+     *
+     * @example
+     * const count = emitter.listenerCount('data');
+     * console.log(`There are ${count} data event listeners`);
+     */
+    listenerCount(eventName: string): number;
+    /**
+     * Get all registered event names
+     *
+     * @returns {string[]} Array of event names that have listeners
+     *
+     * @example
+     * console.log('Events with listeners:', emitter.eventNames());
+     */
+    eventNames(): string[];
+}

package/dist/classes/events/EventEmitter.js

@@ -0,0 +1,275 @@
+/**
+ * @fileoverview Simple event emitter implementation to support event-based architecture
+ * in service management and other parts of the application. 
+ * 
+ * This implementation provides standard event publishing and subscription methods
+ * with support for namespaced events, wildcard listeners, and callback removal.
+ *
+ * @example
+ * // Basic usage
+ * import { EventEmitter } from './EventEmitter.js';
+ * 
+ * // Create an emitter
+ * const events = new EventEmitter();
+ * 
+ * // Subscribe to events
+ * const unsubscribe = events.on('data-loaded', (data) => {
+ *   console.log('Data loaded:', data);
+ * });
+ * 
+ * // Subscribe to all events with a specific prefix
+ * events.on('database:*', ({ event, data }) => {
+ *   console.log(`Database event ${event}:`, data);
+ * });
+ * 
+ * // Emit events
+ * events.emit('data-loaded', { items: [1, 2, 3] });
+ * events.emit('database:connected', { connectionId: 'abc123' });
+ * 
+ * // Clean up when done
+ * unsubscribe();
+ * 
+ * // Or remove all listeners
+ * events.removeAllListeners();
+ */
+
+/**
+ * EventEmitter class for event-based programming
+ */
+export default class EventEmitter {
+  /**
+   * Create a new EventEmitter instance
+   */
+  constructor() {
+    /**
+     * Map to store event handlers
+     * @type {Map<string, Set<Function>>}
+     * @private
+     */
+    this.eventHandlers = new Map();
+    
+    /**
+     * Map to store wildcard event handlers (events ending with *)
+     * @type {Map<string, Set<Function>>}
+     * @private
+     */
+    this.wildcardHandlers = new Map();
+  }
+  
+  /**
+   * Register an event handler
+   * 
+   * @param {string} eventName - Event name to listen for. Can use wildcard (*)
+   *        at the end to listen to all events with a specific prefix.
+   * @param {Function} handler - Handler function to call when event is emitted
+   * @returns {Function} Function to remove this specific handler
+   * 
+   * @example
+   * // Listen for a specific event
+   * emitter.on('userLoggedIn', (user) => {
+   *   console.log(`User logged in: ${user.name}`);
+   * });
+   * 
+   * // Listen for all events with a prefix
+   * emitter.on('api:*', ({ event, data }) => {
+   *   console.log(`API event ${event}:`, data);
+   * });
+   */
+  on(eventName, handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('Event handler must be a function');
+    }
+    
+    // Handle wildcard listeners
+    if (eventName.endsWith('*')) {
+      const prefix = eventName.slice(0, -1);
+      
+      if (!this.wildcardHandlers.has(prefix)) {
+        this.wildcardHandlers.set(prefix, new Set());
+      }
+      
+      this.wildcardHandlers.get(prefix).add(handler);
+      
+      return () => this.off(eventName, handler);
+    }
+    
+    // Handle normal listeners
+    if (!this.eventHandlers.has(eventName)) {
+      this.eventHandlers.set(eventName, new Set());
+    }
+    
+    this.eventHandlers.get(eventName).add(handler);
+    
+    return () => this.off(eventName, handler);
+  }
+  
+  /**
+   * Register a one-time event handler that will be removed after first execution
+   * 
+   * @param {string} eventName - Event name to listen for
+   * @param {Function} handler - Handler function to call when event is emitted
+   * @returns {Function} Function to remove this specific handler
+   * 
+   * @example
+   * emitter.once('initialization', () => {
+   *   console.log('Initialization happened');
+   * });
+   */
+  once(eventName, handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('Event handler must be a function');
+    }
+    
+    const wrapper = (...args) => {
+      this.off(eventName, wrapper);
+      handler(...args);
+    };
+    
+    return this.on(eventName, wrapper);
+  }
+  
+  /**
+   * Remove an event handler
+   * 
+   * @param {string} eventName - Event name the handler was registered for
+   * @param {Function} handler - Handler function to remove
+   * @returns {boolean} True if the handler was removed, false otherwise
+   * 
+   * @example
+   * const handler = (data) => console.log(data);
+   * emitter.on('data', handler);
+   * emitter.off('data', handler);
+   */
+  off(eventName, handler) {
+    // Handle wildcard listeners
+    if (eventName.endsWith('*')) {
+      const prefix = eventName.slice(0, -1);
+      const handlers = this.wildcardHandlers.get(prefix);
+      
+      if (handlers) {
+        return handlers.delete(handler);
+      }
+      
+      return false;
+    }
+    
+    // Handle normal listeners
+    const handlers = this.eventHandlers.get(eventName);
+    
+    if (handlers) {
+      return handlers.delete(handler);
+    }
+    
+    return false;
+  }
+  
+  /**
+   * Remove all event handlers for a specific event
+   * 
+   * @param {string} [eventName] - Event name to remove handlers for.
+   *        If not provided, removes all handlers for all events.
+   * 
+   * @example
+   * // Remove all 'data' event handlers
+   * emitter.removeAllListeners('data');
+   * 
+   * // Remove all event handlers
+   * emitter.removeAllListeners();
+   */
+  removeAllListeners(eventName) {
+    if (eventName) {
+      // Handle wildcard listeners
+      if (eventName.endsWith('*')) {
+        const prefix = eventName.slice(0, -1);
+        this.wildcardHandlers.delete(prefix);
+      } else {
+        this.eventHandlers.delete(eventName);
+      }
+    } else {
+      // Clear all handlers
+      this.eventHandlers.clear();
+      this.wildcardHandlers.clear();
+    }
+  }
+  
+  /**
+   * Emit an event
+   * 
+   * @param {string} eventName - Name of the event to emit
+   * @param {*} data - Data to pass to event handlers
+   * @returns {boolean} True if there were handlers for this event, false otherwise
+   * 
+   * @example
+   * emitter.emit('dataLoaded', { users: [...] });
+   */
+  emit(eventName, data) {
+    let handled = false;
+    
+    // Call specific event handlers
+    const handlers = this.eventHandlers.get(eventName);
+    if (handlers && handlers.size > 0) {
+      handlers.forEach(handler => handler(data));
+      handled = true;
+    }
+    
+    // Call matching wildcard handlers
+    this.wildcardHandlers.forEach((handlers, prefix) => {
+      if (eventName.startsWith(prefix)) {
+        handlers.forEach(handler => 
+          handler({ event: eventName, data })
+        );
+        handled = true;
+      }
+    });
+    
+    return handled;
+  }
+  
+  /**
+   * Get the number of listeners for a specific event
+   * 
+   * @param {string} eventName - Event name to count listeners for
+   * @returns {number} Number of listeners for this event
+   * 
+   * @example
+   * const count = emitter.listenerCount('data');
+   * console.log(`There are ${count} data event listeners`);
+   */
+  listenerCount(eventName) {
+    let count = 0;
+    
+    // Count specific event handlers
+    const handlers = this.eventHandlers.get(eventName);
+    if (handlers) {
+      count += handlers.size;
+    }
+    
+    // Count matching wildcard handlers
+    this.wildcardHandlers.forEach((handlers, prefix) => {
+      if (eventName.startsWith(prefix)) {
+        count += handlers.size;
+      }
+    });
+    
+    return count;
+  }
+  
+  /**
+   * Get all registered event names
+   * 
+   * @returns {string[]} Array of event names that have listeners
+   * 
+   * @example
+   * console.log('Events with listeners:', emitter.eventNames());
+   */
+  eventNames() {
+    const events = [...this.eventHandlers.keys()];
+    
+    // Add wildcard events
+    this.wildcardHandlers.forEach((_, prefix) => {
+      events.push(`${prefix}*`);
+    });
+    
+    return events;
+  }
+}

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

@@ -0,0 +1 @@
+export { default as EventEmitter } from "./EventEmitter.js";

package/dist/classes/events/index.js

@@ -0,0 +1,2 @@
+
+export { default as EventEmitter } from './EventEmitter.js';

package/dist/classes/index.d.ts

@@ -0,0 +1,4 @@
+export * as data from "./data/index.js";
+export * as streams from "./streams/index.js";
+export * as stores from "./stores/index.js";
+export * as svelte from "./svelte/index.js";

package/dist/classes/index.js

@@ -0,0 +1,4 @@
+export * as data from './data/index.js';
+export * as streams from './streams/index.js';
+export * as stores from './stores/index.js';
+export * as svelte from './svelte/index.js';

package/dist/classes/logging/Logger.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Logger class for consistent logging across services
+ * @extends EventEmitter
+ */
+export default class Logger extends EventEmitter {
+    /**
+     * Create a new Logger instance
+     *
+     * @param {string} name - Name of the service/component for this logger
+     * @param {string} [defaultLevel=INFO] - Initial log level threshold
+     * @param {Object} [context={}] - Default context data for all logs
+     */
+    constructor(name: string, defaultLevel?: string, context?: any);
+    name: string;
+    level: string;
+    /**
+     * Set the minimum log level threshold
+     *
+     * @param {string} level - New log level (DEBUG, INFO, WARN, ERROR or NONE)
+     * @returns {boolean} True if level was valid and set, false otherwise
+     */
+    setLevel(level: string): boolean;
+    /**
+     * Log a debug message
+     *
+     * @param {string} message - Log message
+     * @param {*} [details] - Additional details
+     * @returns {boolean} True if the log was emitted
+     */
+    debug(message: string, details?: any): boolean;
+    /**
+     * Log an info message
+     *
+     * @param {string} message - Log message
+     * @param {*} [details] - Additional details
+     * @returns {boolean} True if the log was emitted
+     */
+    info(message: string, details?: any): boolean;
+    /**
+     * Log a warning message
+     *
+     * @param {string} message - Log message
+     * @param {*} [details] - Additional details
+     * @returns {boolean} True if the log was emitted
+     */
+    warn(message: string, details?: any): boolean;
+    /**
+     * Log an error message
+     *
+     * @param {string} message - Log message
+     * @param {*} [details] - Additional details
+     * @returns {boolean} True if the log was emitted
+     */
+    error(message: string, details?: any): boolean;
+    /**
+     * Create a child logger with additional context
+     *
+     * @param {string} namespace
+     *   Namespace of the context (needed for chaining contexts)
+     *
+     * @param {Object} additionalContext - Additional context data
+     *
+     * @returns {Logger} New logger instance with merged context
+     */
+    context(namespace: string, additionalContext: any): Logger;
+    /**
+     * Log an event from an event emitter of type LogEvent
+     *
+     * E.g. an event that was created by another Logger instance and should be
+     * forwarded to this logger.
+     *
+     * @param {string} eventName
+     * @param {import('./typedef.js').LogEventData} eventData
+     */
+    logFromEvent(eventName: string, eventData: import("./typedef.js").LogEventData): boolean;
+    #private;
+}
+import { EventEmitter } from '../events';