@hkdigital/lib-core 0.3.1

package/dist/classes/logging/Logger.js

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Logger implementation based on EventEmitter e.g.
+ * for service logging.
+ *
+ * This Logger provides consistent log level filtering and event-based
+ * distribution of log messages. It integrates with the service architecture
+ * to provide controlled, consistent logging across all services.
+ *
+ * @example
+ * // Basic usage
+ * import { Logger, INFO, DEBUG } from './Logger.js';
+ *
+ * const logger = new Logger('myService', INFO);
+ *
+ * // Log at different levels
+ * logger.debug('Detailed information', { value: 42 }); // Filtered out at INFO
+ * logger.info('Operation completed', { items: 27 });   // Will be logged
+ * logger.warn('Unusual condition detected');           // Will be logged
+ *
+ * // Listen to log events
+ * logger.on('log', (logEvent) => {
+ *   // Process all log events
+ *   saveToLogFile(logEvent);
+ * });
+ *
+ * logger.on(ERROR, (logEvent) => {
+ *   // Process only error events
+ *   sendAlertEmail(logEvent);
+ * });
+ *
+ * // Change log level at runtime
+ * logger.setLevel(DEBUG); // Now debug messages will also be logged
+ */
+
+import { EventEmitter } from '../events';
+
+import { DEBUG, INFO, WARN, ERROR, LEVELS } from './constants.js';
+
+/**
+ * Logger class for consistent logging across services
+ * @extends EventEmitter
+ */
+export default class Logger extends EventEmitter {
+  #defaultContext;
+  #hasContext;
+
+  /**
+   * 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, defaultLevel = INFO, context = {}) {
+    super();
+    this.name = name;
+    this.level = defaultLevel;
+
+    this.#defaultContext = structuredClone(context);
+    this.#hasContext = Object.keys(this.#defaultContext).length > 0;
+  }
+
+  /**
+   * 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) {
+    if (LEVELS[level] !== undefined) {
+      this.level = level;
+      return true;
+    }
+
+    console.warn(`Invalid log level: ${level}`);
+    return false;
+  }
+
+  /**
+   * Log a debug message
+   *
+   * @param {string} message - Log message
+   * @param {*} [details] - Additional details
+   * @returns {boolean} True if the log was emitted
+   */
+  debug(message, details) {
+    return this.#log(DEBUG, message, details);
+  }
+
+  /**
+   * Log an info message
+   *
+   * @param {string} message - Log message
+   * @param {*} [details] - Additional details
+   * @returns {boolean} True if the log was emitted
+   */
+  info(message, details) {
+    return this.#log(INFO, message, details);
+  }
+
+  /**
+   * Log a warning message
+   *
+   * @param {string} message - Log message
+   * @param {*} [details] - Additional details
+   * @returns {boolean} True if the log was emitted
+   */
+  warn(message, details) {
+    return this.#log(WARN, message, details);
+  }
+
+  /**
+   * Log an error message
+   *
+   * @param {string} message - Log message
+   * @param {*} [details] - Additional details
+   * @returns {boolean} True if the log was emitted
+   */
+  error(message, details) {
+    return this.#log(ERROR, message, details);
+  }
+
+  /**
+   * 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, additionalContext) {
+    if( typeof namespace !== "string" ) {
+      throw new Error('Invalid namespace');
+    }
+
+    const mergedContext = {
+      ...this.#defaultContext,
+      [namespace]: additionalContext
+    };
+
+    return new Logger(this.name, this.level, mergedContext);
+  }
+
+  /**
+   * 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, eventData ) {
+    const level = eventData.level;
+
+    // Check if this log level should be filtered
+    if (LEVELS[level] < LEVELS[this.level]) {
+      return false; // Below threshold, don't emit
+    }
+
+    this.#logEvent( { ...eventData, eventName });
+  }
+
+  /**
+   * Internal logging method
+   *
+   * @param {string} level - Log level
+   * @param {string} message - Log message
+   * @param {*} [details] - Additional details to include in the log
+   * @returns {boolean} True if the log was emitted, false if filtered
+   */
+  #log(level, message, details) {
+    // Check if this log level should be filtered
+    if (LEVELS[level] < LEVELS[this.level]) {
+      return false; // Below threshold, don't emit
+    }
+
+    const timestamp = new Date();
+
+    const logEvent = {
+      timestamp,
+      source: this.name,
+      level,
+      message,
+      context: this.#hasContext ? this.#defaultContext : null,
+      details: details ?? null
+    };
+
+    // Emit as both specific level event and generic 'log' event
+    this.emit(level, logEvent);
+    this.emit('log', logEvent);
+
+    return true;
+  }
+
+  /**
+   * Internal event loggin method
+   *
+   * @param {import('./typedef.js').LogEvent} logEvent
+   */
+  #logEvent(logEvent) {
+    // Emit as both specific level event and generic 'log' event
+    this.emit(logEvent.level, logEvent);
+    this.emit('log', logEvent);
+
+    return true;
+  }
+}

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

@@ -0,0 +1,12 @@
+export const DEBUG: "debug";
+export const INFO: "info";
+export const WARN: "warn";
+export const ERROR: "error";
+export const NONE: "none";
+export namespace LEVELS {
+    let debug: number;
+    let info: number;
+    let warn: number;
+    let error: number;
+    let none: number;
+}

package/dist/classes/logging/constants.js

@@ -0,0 +1,16 @@
+
+// Log level names
+export const DEBUG = 'debug';
+export const INFO = 'info';
+export const WARN = 'warn';
+export const ERROR = 'error';
+export const NONE = 'none';
+
+// Level values for filtering (higher = more important)
+export const LEVELS = {
+  [DEBUG]: 1,
+  [INFO]: 2,
+  [WARN]: 3,
+  [ERROR]: 4,
+  [NONE]: 6
+};

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

@@ -0,0 +1,2 @@
+export { default as Logger } from "./Logger.js";
+export * from "./constants.js";

package/dist/classes/logging/index.js

@@ -0,0 +1,4 @@
+
+export { default as Logger } from './Logger.js';
+
+export * from './constants.js';

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

@@ -0,0 +1,34 @@
+declare const _default: {};
+export default _default;
+export type LogEventData = {
+    /**
+     * - When the log event was created
+     */
+    timestamp: Date;
+    /**
+     * - Name of the source where the event came from
+     */
+    source: string;
+    /**
+     * - Log level (DEBUG, INFO, WARN, ERROR)
+     */
+    level: string;
+    /**
+     * - The log message
+     */
+    message: string;
+    /**
+     *   Default context data from the logger (null if no context)
+     */
+    context: any | null;
+    /**
+     * - Additional details provided with the log (optional)
+     */
+    details?: any;
+};
+/**
+ * eventName - Original event name if log came from an event (optional)
+ */
+export type LogEvent = LogEventData & {
+    eventName?: string;
+};

package/dist/classes/logging/typedef.js

@@ -0,0 +1,17 @@
+/**
+ * @typedef {Object} LogEventData
+ * @property {Date} timestamp - When the log event was created
+ * @property {string} source - Name of the source where the event came from
+ * @property {string} level - Log level (DEBUG, INFO, WARN, ERROR)
+ * @property {string} message - The log message
+ * @property {Object|null} context
+ *   Default context data from the logger (null if no context)
+ * @property {*} [details] - Additional details provided with the log (optional)
+ */
+
+/**
+ * @typedef {LogEventData & { eventName?: string }} LogEvent
+ * eventName - Original event name if log came from an event (optional)
+ */
+
+export default {};

package/dist/classes/promise/HkPromise.d.ts

@@ -0,0 +1,121 @@
+/**
+ * HkPromise extends the default javascript Promise class
+ * - Exposes methods to interact with the state of the
+ *   promise, such as 'resolve' and 'reject'
+ */
+export default class HkPromise extends Promise<any> {
+    /**
+     * @param {()=>void} [initFn]
+     */
+    constructor(initFn?: () => void);
+    /**
+     * Get value of property [resolved]
+     *
+     * @returns {boolean} true if the promise has been resolved
+     */
+    get resolved(): boolean;
+    /**
+     * Get value of property [rejected]
+     *
+     * @returns {boolean} true if the promise was rejected
+     */
+    get rejected(): boolean;
+    /**
+     * Get value of property [pending]
+     *
+     * @returns {boolean} true if the promise is still pending
+     */
+    get pending(): boolean;
+    /**
+     * Get value of property [cancelled]
+     *
+     * @returns {boolean} true if the promise was cancelled
+     */
+    get cancelled(): boolean;
+    /**
+     * Get value of property [timeout]
+     *
+     * @returns {boolean} true if the promise was cancelled due to a timeout
+     */
+    get timeout(): boolean;
+    /**
+     * Resolve the promise
+     *
+     * @param {any} [value] - Value to pass to the "then" callbacks
+     *
+     * @returns {object} this
+     */
+    resolve(...args: any[]): object;
+    /**
+     * Resolve the promise if the promise is still pending
+     *
+     * @param {any} [value] - Value to pass to the "catch" callbacks
+     *
+     * @returns {object} this
+     */
+    tryResolve(...args: any[]): object;
+    /**
+     * Reject the promise
+     *
+     * @param {Object} [errorOrInfo]
+     *   Object to pass to the "catch" callbacks, usually an Error object
+     *
+     * @returns {object} this
+     */
+    reject(...args: any[]): object;
+    /**
+     * Reject the promise if the promise is still pending
+     *
+     * @param {Object} [errorOrInfo]
+     *   Object to pass to the "catch" callbacks, usually an Error object
+     *
+     * @returns {object} this
+     */
+    tryReject(...args: any[]): object;
+    /**
+     * Reject the promise and set this.cancelled=true
+     *
+     * @param {Object} [errorOrInfo]
+     *   Object to pass to the "catch" callbacks, usually an Error object
+     *
+     * @returns {object} this
+     */
+    cancel(errorOrInfo?: any, ...args: any[]): object;
+    /**
+     * Reject the promise and set this.cancelled=true
+     *
+     * @param {Object} [errorOrInfo]
+     *   Object to pass to the "catch" callbacks, usually an Error object
+     *
+     * @returns {object} this
+     */
+    tryCancel(...args: any[]): object;
+    /**
+     * Specify the number of milliseconds until the promise should time out.
+     * - When a timeout occurs: the promise is cancelled and the following
+     *   properties are both set
+     *
+     *      this.timeout=true
+     *      this.cancelled=true
+     *
+     * @param {number} ms
+     *   Number of milliseconds after which the promise should time out
+     *
+     * @param {string} [message="Timeout"]
+     *   Message of the error that will be thrown when the timeout occurs
+     */
+    setTimeout(ms: number, message?: string): this;
+    /**
+     * Register a callback that is called when the promise resolves
+     *
+     * @param {function} callback
+     */
+    then(...args: any[]): Promise<any>;
+    /**
+     * Register a callback that is called when the promise rejects, is
+     * cancelled or times out
+     *
+     * @param {function} callback
+     */
+    catch(...args: any[]): Promise<any>;
+}