@hkdigital/lib-core 0.3.1

package/dist/classes/promise/HkPromise.js

@@ -0,0 +1,377 @@
+/**
+ * Hkpromise.js
+ *
+ * @description
+ * HkPromise extends the default Promise class. A HkPromise offers some
+ * additional methods, e.g. resolve, reject and setTimeout, which makes it
+ * easier to use than the build in Promise class in some code constructions.
+ *
+ * @example
+ *
+ *   import HkPromise from "./HkPromise.js";
+ *
+ *   function() {
+ *     const promise = new HkPromise();
+ *
+ *     setTimeout( promise.resolve, 1000 );
+ *
+ *     return promise;
+ *   }
+ */
+
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../../util/expect/index.js';
+
+import { noop } from '../../util/function/index.js';
+
+/* ---------------------------------------------------------------- Internals */
+
+const resolved$ = Symbol('resolved');
+const rejected$ = Symbol('rejected');
+const pending$ = Symbol('pending');
+
+const timeout$ = Symbol('timeout');
+const cancelled$ = Symbol('cancelled');
+
+const resolveFn$ = Symbol('resolveFn');
+const rejectFn$ = Symbol('rejectFn');
+
+const timeoutTimer$ = Symbol('timeoutTimer');
+
+const hasThen$ = Symbol('hasThen');
+
+/* ------------------------------------------------------------------- Export */
+
+/**
+ * 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 {
+	// > TODO: convert to JS private properties
+	// #resolveFn
+	// #rejectFn
+	// #pending
+	// #resolved
+	// #rejected
+	// #cancelled
+	// #timeout
+	// #timeoutTimer
+	// #hasThen
+
+	/**
+	 * @param {()=>void} [initFn]
+	 */
+	constructor(initFn) {
+		let _resolveFn;
+		let _rejectFn;
+
+		super((resolveFn, rejectFn) => {
+			//
+			// @note if initFn cannot be called an exception will be thrown:
+			// TypeError: Promise resolve or reject function is not callable
+			//
+			if (initFn) {
+				initFn(resolveFn, rejectFn);
+			}
+
+			_resolveFn = resolveFn;
+			_rejectFn = rejectFn;
+		});
+
+		// @note some values are not initialized on purpose,
+		//       to save time during promise creation
+
+		this[resolveFn$] = _resolveFn;
+		this[rejectFn$] = _rejectFn;
+
+		// this[ resolved$ ] = false;
+		// this[ rejected$ ] = false;
+
+		this[pending$] = true;
+
+		// this[ cancelled$ ] = false;
+		// this[ timeout$ ] = false;
+
+		// this[ timeoutTimer$ ] = undefined;
+	}
+
+	/**
+	 * Get value of property [resolved]
+	 *
+	 * @returns {boolean} true if the promise has been resolved
+	 */
+	get resolved() {
+		return this[resolved$] ? true : false;
+	}
+
+	/**
+	 * Get value of property [rejected]
+	 *
+	 * @returns {boolean} true if the promise was rejected
+	 */
+	get rejected() {
+		return this[rejected$] ? true : false;
+	}
+
+	/**
+	 * Get value of property [pending]
+	 *
+	 * @returns {boolean} true if the promise is still pending
+	 */
+	get pending() {
+		return this[pending$];
+	}
+
+	/**
+	 * Get value of property [cancelled]
+	 *
+	 * @returns {boolean} true if the promise was cancelled
+	 */
+	get cancelled() {
+		return this[cancelled$] ? true : false;
+	}
+
+	/**
+	 * Get value of property [timeout]
+	 *
+	 * @returns {boolean} true if the promise was cancelled due to a timeout
+	 */
+	get timeout() {
+		return this[timeout$] ? true : false;
+	}
+
+	/**
+	 * Resolve the promise
+	 *
+	 * @param {any} [value] - Value to pass to the "then" callbacks
+	 *
+	 * @returns {object} this
+	 */
+	resolve(/* value */) {
+		// -- Check current Promise state
+
+		if (!this[pending$]) {
+			if (this[resolved$]) {
+				throw new Error('Cannot resolve Promise. Promise has already resolved');
+			} else {
+				throw new Error('Cannot resolve Promise. Promise has already been rejected');
+			}
+		}
+
+		// -- Clear timeout timer (if any)
+
+		if (undefined !== this[timeoutTimer$]) {
+			clearTimeout(this[timeoutTimer$]);
+
+			this[timeoutTimer$] = undefined;
+		}
+
+		// -- Set flags and call resolve function
+
+		this[resolved$] = true;
+		this[pending$] = false;
+
+		this[resolveFn$](...arguments);
+
+		return this;
+	}
+
+	// -------------------------------------------------------------------- Method
+
+	/**
+	 * Resolve the promise if the promise is still pending
+	 *
+	 * @param {any} [value] - Value to pass to the "catch" callbacks
+	 *
+	 * @returns {object} this
+	 */
+	tryResolve(/* value */) {
+		if (this[pending$]) {
+			this.resolve(...arguments);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Reject the promise
+	 *
+	 * @param {Object} [errorOrInfo]
+	 *   Object to pass to the "catch" callbacks, usually an Error object
+	 *
+	 * @returns {object} this
+	 */
+	reject(/* errorOrInfo */) {
+		if (!this[hasThen$]) {
+			//
+			// No then (or await) has been used
+			// add catch to prevent useless unhandled promise rejection
+			//
+			this.catch(noop);
+		}
+
+		// -- Check current Promise state
+
+		if (!this[pending$]) {
+			if (this[resolved$]) {
+				throw new Error('Cannot reject Promise. Promise has already resolved');
+			} else {
+				throw new Error('Cannot reject Promise. Promise has already been rejected');
+			}
+		}
+
+		// -- Clear timeout timer (if any)
+
+		if (undefined !== this[timeoutTimer$]) {
+			clearTimeout(this[timeoutTimer$]);
+
+			this[timeoutTimer$] = undefined;
+		}
+
+		// -- Set flags and call reject function
+
+		this[rejected$] = true;
+		this[pending$] = false;
+
+		this[rejectFn$](...arguments);
+
+		return this;
+	}
+
+	/**
+	 * 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(/* errorOrInfo */) {
+		if (this[pending$]) {
+			this.reject(...arguments);
+		}
+
+		return this;
+	}
+
+	/**
+	 * 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) {
+		if (errorOrInfo) {
+			if (!(errorOrInfo instanceof Object)) {
+				throw new Error('Invalid parameter [errorOrInfo] (expected (error) object');
+			}
+		} else {
+			errorOrInfo = new Error('Cancelled');
+		}
+
+		errorOrInfo.cancelled = true;
+
+		this[cancelled$] = true;
+		this.reject(...arguments);
+
+		return this;
+	}
+
+	/**
+	 * 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(/*errorOrInfo*/) {
+		if (this[pending$]) {
+			this.cancel(...arguments);
+		}
+
+		return this;
+	}
+
+	/**
+	 * 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, message = 'Timeout') {
+		expect.number(ms);
+		expect.string(message);
+
+		// -- Check current Promise state
+
+		if (!this[pending$]) {
+			if (this[resolved$]) {
+				throw new Error('Cannot set timeout. Promise has already resolved');
+			} else {
+				throw new Error('Cannot set timeout. Promise has already been rejected');
+			}
+		}
+
+		// -- Clear existing timeout (if any)
+
+		if (undefined !== this[timeoutTimer$]) {
+			clearTimeout(this[timeoutTimer$]);
+		}
+
+		// -- Set timeout
+
+		const err = new Error(message);
+
+		this[timeoutTimer$] = setTimeout(() => {
+			if (!this[pending$]) {
+				// Promise has already been resolved (should not happen)
+				return;
+			}
+
+			this[timeout$] = true;
+			this[cancelled$] = true;
+
+			err.timeout = true;
+			err.cancelled = true;
+
+			this.reject(err);
+		}, ms);
+
+		// return this -> chainable method
+		return this;
+	}
+
+	/**
+	 * Register a callback that is called when the promise resolves
+	 *
+	 * @param {function} callback
+	 */
+	then(/* callback */) {
+		this[hasThen$] = true;
+
+		return super.then(...arguments);
+	}
+
+	/**
+	 * Register a callback that is called when the promise rejects, is
+	 * cancelled or times out
+	 *
+	 * @param {function} callback
+	 */
+	catch(/* callback */) {
+		return super.catch(...arguments);
+	}
+} // end class

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

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

package/dist/classes/promise/index.js

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

package/dist/classes/services/ServiceBase.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @typedef {import('./typedef.js').ServiceConfig} ServiceConfig
+ * @typedef {import('./typedef.js').ServiceOptions} ServiceOptions
+ * @typedef {import('./typedef.js').StopOptions} StopOptions
+ * @typedef {import('./typedef.js').HealthStatus} HealthStatus
+ * @typedef {import('./typedef.js').StateChangeEvent} StateChangeEvent
+ * @typedef {import('./typedef.js').HealthChangeEvent} HealthChangeEvent
+ * @typedef {import('./typedef.js').ServiceErrorEvent} ServiceErrorEvent
+ */
+/**
+ * Base class for all services with lifecycle management
+ * @extends EventEmitter
+ */
+export class ServiceBase extends EventEmitter {
+    /**
+     * Create a new service instance
+     *
+     * @param {string} name - Service name
+     * @param {ServiceOptions} [options={}] - Service options
+     */
+    constructor(name: string, options?: ServiceOptions);
+    /** @type {string} */
+    name: string;
+    /** @type {string} */
+    state: string;
+    /** @type {boolean} */
+    healthy: boolean;
+    /** @type {Error|null} */
+    error: Error | null;
+    /** @type {Logger} */
+    logger: Logger;
+    /** @private @type {number} */
+    private _shutdownTimeout;
+    /**
+     * Initialize the service with configuration
+     *
+     * @param {ServiceConfig} [config={}] - Service-specific configuration
+     *
+     * @returns {Promise<boolean>} True if initialization succeeded
+     */
+    initialize(config?: ServiceConfig): Promise<boolean>;
+    /**
+     * Start the service
+     *
+     * @returns {Promise<boolean>} True if the service started successfully
+     */
+    start(): Promise<boolean>;
+    /**
+     * Stop the service with optional timeout
+     *
+     * @param {StopOptions} [options={}] - Stop options
+     *
+     * @returns {Promise<boolean>} True if the service stopped successfully
+     */
+    stop(options?: StopOptions): Promise<boolean>;
+    /**
+     * Recover the service from error state
+     *
+     * @returns {Promise<boolean>} True if recovery succeeded
+     */
+    recover(): Promise<boolean>;
+    /**
+     * Destroy the service and cleanup resources
+     *
+     * @returns {Promise<boolean>} True if destruction succeeded
+     */
+    destroy(): Promise<boolean>;
+    /**
+     * Get the current health status of the service
+     *
+     * @returns {Promise<HealthStatus>} Health status object
+     */
+    getHealth(): Promise<HealthStatus>;
+    /**
+     * Set the service log level
+     *
+     * @param {string} level - New log level
+     *
+     * @returns {boolean} True if the level was set successfully
+     */
+    setLogLevel(level: string): boolean;
+    /**
+     * Initialize the service (override in subclass)
+     *
+     * @protected
+     * @param {ServiceConfig} config - Service configuration
+     *
+     * @returns {Promise<void>}
+     */
+    protected _init(config: ServiceConfig): Promise<void>;
+    /**
+     * Start the service (override in subclass)
+     *
+     * @protected
+     *
+     * @returns {Promise<void>}
+     */
+    protected _start(): Promise<void>;
+    /**
+     * Stop the service (override in subclass)
+     *
+     * @protected
+     *
+     * @returns {Promise<void>}
+     */
+    protected _stop(): Promise<void>;
+    /**
+     * Destroy the service (optional override)
+     *
+     * @protected
+     *
+     * @returns {Promise<void>}
+     */
+    protected _destroy(): Promise<void>;
+    /**
+     * Recover from error state (optional override)
+     *
+     * @protected
+     *
+     * @returns {Promise<void>}
+     */
+    protected _recover(): Promise<void>;
+    /**
+     * Perform health check (optional override)
+     *
+     * @protected
+     *
+     * @returns {Promise<Object>} Additional health information
+     */
+    protected _healthCheck(): Promise<any>;
+    /**
+     * Set the service state and emit event
+     *
+     * @private
+     * @param {string} newState - New state value
+     */
+    private _setState;
+    /**
+     * Set the health status and emit event if changed
+     *
+     * @private
+     * @param {boolean} healthy - New health status
+     */
+    private _setHealthy;
+    /**
+     * Set error state and emit error event
+     *
+     * @private
+     * @param {string} operation - Operation that failed
+     * @param {Error} error - Error that occurred
+     */
+    private _setError;
+}
+export default ServiceBase;
+export type ServiceConfig = import("./typedef.js").ServiceConfig;
+export type ServiceOptions = import("./typedef.js").ServiceOptions;
+export type StopOptions = import("./typedef.js").StopOptions;
+export type HealthStatus = import("./typedef.js").HealthStatus;
+export type StateChangeEvent = import("./typedef.js").StateChangeEvent;
+export type HealthChangeEvent = import("./typedef.js").HealthChangeEvent;
+export type ServiceErrorEvent = import("./typedef.js").ServiceErrorEvent;
+import { EventEmitter } from '../events';
+import { Logger } from '../logging';