@hkdigital/lib-core 0.3.1

package/dist/classes/services/typedef.js

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview Type definitions for the service management system.
+ * 
+ * This file contains all TypeScript/JSDoc type definitions used throughout
+ * the service management system. Import these types in your service
+ * implementations and when using the ServiceManager.
+ * 
+ * @example
+ * // In your service implementation
+ * import { ServiceBase } from './ServiceBase.js';
+ * 
+ * // @ typedef {import('./typedef.js').ServiceConfig} ServiceConfig
+ * // @ typedef {import('./typedef.js').HealthStatus} HealthStatus
+ * 
+ * class MyService extends ServiceBase {
+ *   async _init(config) {
+ *     // config is typed as ServiceConfig
+ *   }
+ *   
+ *   async _healthCheck() {
+ *     // Return type is HealthStatus
+ *     return { latency: 10 };
+ *   }
+ * }
+ * 
+ * @example
+ * // When using ServiceManager
+ * import { ServiceManager } from './ServiceManager.js';
+ * 
+ * // @ typedef {import('./typedef.js').ServiceManagerConfig} ServiceManagerConfig
+ * // @ typedef {import('./typedef.js').ServiceRegistrationOptions} ServiceRegistrationOptions
+ * 
+ * const config = {
+ *   environment: 'development',
+ *   stopTimeout: 5000
+ * };
+ * 
+ * const manager = new ServiceManager(config);
+ * 
+ * const options = {
+ *   dependencies: ['database'],
+ *   tags: ['critical']
+ * };
+ * 
+ * manager.register('auth', AuthService, {}, options);
+ */
+
+/**
+ * Service configuration object passed to service initialization
+ *
+ * @typedef {Object} ServiceConfig
+ * @property {*} [key] - Service-specific configuration properties
+ */
+
+/**
+ * Options for creating a service instance
+ *
+ * @typedef {Object} ServiceOptions
+ * @property {string} [logLevel] - Initial log level for the service
+ * @property {number} [shutdownTimeout=5000] - Timeout for graceful shutdown
+ */
+
+/**
+ * Options for stopping a service
+ *
+ * @typedef {Object} StopOptions
+ * @property {number} [timeout] - Override shutdown timeout
+ * @property {boolean} [force=false] - Force stop even if timeout exceeded
+ */
+
+/**
+ * Health status returned by service health checks
+ *
+ * @typedef {Object} HealthStatus
+ * @property {string} name - Service name
+ * @property {string} state - Current service state
+ * @property {boolean} healthy - Whether the service is healthy
+ * @property {string} [error] - Error message if unhealthy
+ * @property {string} [checkError] - Error from health check itself
+ * @property {*} [key] - Additional health check properties
+ */
+
+/**
+ * @typedef {Object} StateChangeEvent
+ * @property {string} service - Service name (added by ServiceManager)
+ * @property {string} oldState - Previous state
+ * @property {string} newState - New state
+ */
+
+/**
+ * @typedef {Object} HealthChangeEvent
+ * @property {string} service - Service name (added by ServiceManager)
+ * @property {boolean} healthy - Current health status
+ * @property {boolean} [wasHealthy] - Previous health status
+ */
+
+/**
+ * Event emitted when service encounters an error
+ *
+ * @typedef {Object} ServiceErrorEvent
+ * @property {string} service - Service name
+ * @property {string} operation - Operation that failed
+ * @property {Error} error - Error that occurred
+ */
+
+/**
+ * Service class constructor type
+ *
+ * @typedef {new (name: string, options?: ServiceOptions) => ServiceInstance} ServiceConstructor
+ */
+
+/**
+ * Options for registering a service
+ *
+ * @typedef {Object} ServiceRegistrationOptions
+ * @property {string[]} [dependencies=[]] - Services this service depends on
+ * @property {string[]} [tags=[]] - Tags for grouping services
+ * @property {number} [priority=0] - Startup priority (higher starts first)
+ */
+
+/**
+ * Configuration for ServiceManager
+ *
+ * @typedef {Object} ServiceManagerConfig
+ * @property {boolean} [debug=false] - Debug mode switch
+ * @property {boolean} [autoStart=false] - Auto-start services on registration
+ * @property {number} [stopTimeout=10000] - Default timeout for stopping services
+ * @property {string} [logLevel] - Initial log level for ServiceManager
+ * @property {LogConfig} [logConfig={}] - Logging configuration
+ */
+
+/**
+ * Logging configuration
+ *
+ * @typedef {Object} LogConfig
+ * @property {string} [defaultLevel] - Default log level for services
+ * @property {string} [globalLevel] - Override level for all services
+ * @property {Object<string, string>} [serviceLevels] - Per-service log levels
+ */
+
+/**
+ * Internal service registry entry
+ *
+ * @typedef {Object} ServiceEntry
+ * @property {ServiceConstructor} ServiceClass - Service class constructor
+ * @property {ServiceInstance|null} instance - Service instance (lazy-created)
+ * @property {ServiceConfig} config - Service configuration
+ * @property {string[]} dependencies - Service dependencies
+ * @property {Set<string>} dependents - Services that depend on this one
+ * @property {string[]} tags - Service tags
+ * @property {number} priority - Startup priority
+ */
+
+/**
+ * Result of health check for all services
+ * @typedef {Object<string, HealthStatus>} HealthCheckResult
+ */
+
+/**
+ * Base class interface that services must implement
+ *
+ * @typedef {Object} ServiceInstance
+ * @property {string} name - Service name
+ * @property {string} state - Current state
+ * @property {boolean} healthy - Health status
+ * @property {Error|null} error - Last error
+ * @property {import('../logging').Logger} logger - Service logger
+ * @property {(config?: ServiceConfig) => Promise<boolean>} initialize
+ * @property {() => Promise<boolean>} start
+ * @property {(options?: StopOptions) => Promise<boolean>} stop
+ * @property {() => Promise<boolean>} recover
+ * @property {() => Promise<boolean>} destroy
+ * @property {() => Promise<HealthStatus>} getHealth
+ * @property {(level: string) => boolean} setLogLevel
+ * @property {(event: string, handler: Function) => Function} on
+ * @property {(event: string, data: any) => boolean} emit
+ */
+
+export {};

package/dist/classes/stores/SubscribersCount.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Class that can be used to add a `SubscribersCount` store to classes
+ * or other objects
+ */
+export default class SubscribersCount {
+    /**
+     * Create a writable store with added 'subscribeCount' functionality
+     */
+    static writable(...args: any[]): any;
+    /**
+     * Add subscriber count functionality to an existing store by wrapping
+     * the store with a Proxy
+     *
+     * @template T;
+     *
+     * @param {import('svelte/store').Writable<T>} store
+     */
+    static wrap<T>(store: import("svelte/store").Writable<T>): any;
+    increment(): void;
+    decrement(): void;
+    /**
+     * Subscribe to `SubscribersCount` store
+     *
+     * @param {(value:number)=>void} fn
+     *
+     * @returns {()=>void} unsubscribe
+     */
+    subscribe(fn: (value: number) => void): () => void;
+    /**
+     * Subscribe to `SubscribersCount` store and receive an update once if the
+     * count is zero.
+     *
+     * @param {(value:number)=>void} fn
+     *
+     * @returns {()=>void} unsubscribe
+     */
+    onceEmpty(fn: (value: number) => void): () => void;
+    #private;
+}

package/dist/classes/stores/SubscribersCount.js

@@ -0,0 +1,107 @@
+import { writable, get } from 'svelte/store';
+
+/**
+ * Class that can be used to add a `SubscribersCount` store to classes
+ * or other objects
+ */
+export default class SubscribersCount {
+	#count;
+
+	constructor() {
+		this.#count = writable(0);
+	}
+
+	increment() {
+		this.#count.update((value) => value + 1);
+	}
+
+	decrement() {
+		this.#count.update((value) => value - 1);
+	}
+
+	/**
+	 * Subscribe to `SubscribersCount` store
+	 *
+	 * @param {(value:number)=>void} fn
+	 *
+	 * @returns {()=>void} unsubscribe
+	 */
+	subscribe(fn) {
+		return this.#count.subscribe(fn);
+	}
+
+	/**
+	 * Subscribe to `SubscribersCount` store and receive an update once if the
+	 * count is zero.
+	 *
+	 * @param {(value:number)=>void} fn
+	 *
+	 * @returns {()=>void} unsubscribe
+	 */
+	onceEmpty(fn) {
+		let unsubscribe = this.#count.subscribe((value) => {
+			if (value === 0) {
+				unsubscribe();
+				fn(value);
+			}
+		});
+
+		return unsubscribe;
+	}
+
+	/**
+	 * Create a writable store with added 'subscribeCount' functionality
+	 */
+	static writable() {
+		const store = writable(...arguments);
+
+		return SubscribersCount.wrap(store);
+	}
+
+	/**
+	 * Add subscriber count functionality to an existing store by wrapping
+	 * the store with a Proxy
+	 *
+	 * @template T;
+	 *
+	 * @param {import('svelte/store').Writable<T>} store
+	 */
+	static wrap(store) {
+		// expect.store( store );
+
+		const counter = new SubscribersCount();
+
+		const handler = {
+			/**
+			 * @param {any} target
+			 * @param {string} prop
+			 */
+			get(target, prop) {
+				switch (prop) {
+					case 'subscribe': {
+						return /* subscribe */ function () {
+							counter.increment();
+							const unsubscribe = target[prop](...arguments);
+
+							return /* unsubscribe */ () => {
+								counter.decrement();
+								unsubscribe();
+							};
+						};
+					}
+
+					case 'value':
+						return get(store);
+
+					case 'subscribersCount':
+						return counter;
+				}
+
+				return Reflect.get(target, prop);
+				// return target[prop];
+			}
+		};
+
+		return new Proxy(store, handler);
+	}
+}

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

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

package/dist/classes/stores/index.js

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

package/dist/classes/streams/LogTransformStream.d.ts

@@ -0,0 +1,4 @@
+export default class LogTransformStream extends TransformStream<any, any> {
+    constructor();
+    start(): void;
+}

package/dist/classes/streams/LogTransformStream.js

@@ -0,0 +1,19 @@
+export default class LogTransformStream extends TransformStream {
+	constructor() {
+		const transformer = {
+			/**
+			 * Log the chunk and enqueue the unchanged chunk
+			 *
+			 * @param {any} chunk
+			 * @param {any} controller
+			 */
+			transform: (chunk, controller) => {
+				console.log('log', chunk);
+				controller.enqueue(chunk);
+			}
+		};
+
+		super(transformer);
+	}
+	start() {}
+}

package/dist/classes/streams/ServerEventsStore.d.ts

@@ -0,0 +1,22 @@
+export default class ServerEventsStore {
+    /**
+     * @param {object} _
+     * @param {Zods.AbsOrRelUrl} _.url
+     */
+    constructor({ url }: {
+        url: Zods.AbsOrRelUrl;
+    });
+    /** @type {SubscribersCount} */
+    subscribersCount: SubscribersCount;
+    /**
+     * Subscribe to Server Send Events
+     *
+     * @param {import("svelte/store").Subscriber<object|null>} fn
+     *
+     * @returns {()=>void} unsubscribe
+     */
+    subscribe(fn: import("svelte/store").Subscriber<object | null>): () => void;
+    #private;
+}
+import SubscribersCount from '../stores/SubscribersCount.js';
+import * as Zods from '../../zod/all.js';

package/dist/classes/streams/ServerEventsStore.js

@@ -0,0 +1,110 @@
+import { writable } from 'svelte/store';
+
+// eslint-disable-next-line no-unused-vars
+import * as Zods from '../../zod/all.js';
+
+import SubscribersCount from '../stores/SubscribersCount.js';
+
+// > Class
+
+export default class ServerEventsStore {
+	/** @type {Zods.AbsOrRelUrl} */
+	#url;
+
+	/** @type {import("svelte/store").Writable<object|null>} */
+	#store;
+
+	/** @type {boolean} */
+	#starting = false;
+
+	/** @type {ReadableStream<Uint8Array>|null} */
+	#stream = null;
+
+	/** @type {SubscribersCount} */
+	subscribersCount;
+
+	/**
+	 * @param {object} _
+	 * @param {Zods.AbsOrRelUrl} _.url
+	 */
+	constructor({ url }) {
+		this.#url = Zods.AbsOrRelUrl.parse(url);
+
+		this.#store = writable(null);
+
+		this.subscribersCount = new SubscribersCount();
+	}
+
+	/**
+	 * Subscribe to Server Send Events
+	 *
+	 * @param {import("svelte/store").Subscriber<object|null>} fn
+	 *
+	 * @returns {()=>void} unsubscribe
+	 */
+	subscribe(fn) {
+		this.subscribersCount.increment();
+
+		const unsubscribe = this.#store?.subscribe(fn);
+
+		this.#tryStartStream();
+
+		return () => {
+			this.subscribersCount.decrement();
+			unsubscribe?.();
+		};
+	}
+
+	async #tryStartStream() {
+		if (this.#stream || this.#starting) {
+			return;
+		}
+
+		try {
+			this.#starting = true;
+
+			const aborter = new AbortController();
+			const signal = aborter.signal;
+
+			const response = await fetch(this.#url, { signal });
+
+			const stream = (this.#stream = response.body);
+
+			this.#starting = false;
+
+			const reader =
+				// @ts-ignore
+				stream.pipeThrough(new TextDecoderStream()).getReader();
+
+			// const textDecoder = new TextDecoder('utf-8');
+
+			while (!signal.aborted) {
+				const { value, done } = await reader.read();
+
+				if (undefined === value) {
+					break;
+				}
+
+				const obj = JSON.parse(value);
+				// const obj = JSON.parse(textDecoder.decode(value));
+
+				if (!done) {
+					this.#store.set(obj);
+				}
+
+				// console.log({ ...obj, done });
+
+				if (done) {
+					break;
+				}
+			} // end for
+		} catch (e) {
+			this.#starting = false;
+			this.#stream = null;
+
+			if (e instanceof Error && e.name !== 'AbortError') {
+				throw e;
+			}
+		}
+	}
+}

package/dist/classes/streams/TimeStampSource.d.ts

@@ -0,0 +1,13 @@
+export default class TimestampSource {
+    /**
+     * Stream start function
+     *
+     * @param {ReadableStreamDefaultController} ctr
+     */
+    start(ctr: ReadableStreamDefaultController): void;
+    /**
+     * Stop generation of new stream output
+     */
+    cancel(): void;
+    #private;
+}

package/dist/classes/streams/TimeStampSource.js

@@ -0,0 +1,26 @@
+export default class TimestampSource {
+  /** @type {number|NodeJS.Timeout|undefined} */
+  #interval;
+
+  constructor() {}
+
+  /**
+   * Stream start function
+   *
+   * @param {ReadableStreamDefaultController} ctr
+   */
+  start(ctr) {
+    ctr.enqueue(JSON.stringify({ now: Date.now() }));
+
+    this.#interval = setInterval(() => {
+      return ctr.enqueue(JSON.stringify({ now: Date.now() }));
+    }, 1000);
+  }
+
+  /**
+   * Stop generation of new stream output
+   */
+  cancel() {
+    clearInterval(this.#interval);
+  }
+}

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

@@ -0,0 +1,3 @@
+export { default as LogTransformStream } from "./LogTransformStream.js";
+export { default as ServerEventsStore } from "./ServerEventsStore.js";
+export { default as TimeStampSource } from "./TimeStampSource.js";

package/dist/classes/streams/index.js

@@ -0,0 +1,3 @@
+export { default as LogTransformStream } from './LogTransformStream.js';
+export { default as ServerEventsStore } from './ServerEventsStore.js';
+export { default as TimeStampSource } from './TimeStampSource.js';

package/dist/classes/svelte/audio/AudioLoader.svelte.d.ts

@@ -0,0 +1,30 @@
+/**
+ * AudioLoader instance
+ * - Loads audio data from network into an ArrayBuffer
+ * - Loaded data can be transferred to an AudioBufferSourceNode
+ */
+export default class AudioLoader extends NetworkLoader {
+    /**
+     * Get an AudioBufferSourceNode instance
+     *
+     * @note AudioBufferSourceNodes can play only once, a new source node
+     *       must be created otherwise
+     *
+     * @param {AudioContext} audioContext
+     *
+     * @returns {Promise<AudioBufferSourceNode>}
+     */
+    getAudioBufferSourceNode(audioContext: AudioContext): Promise<AudioBufferSourceNode>;
+    /**
+     * Gets data as AudioBuffer
+     * - Stores created AudioBuffer instance internally
+     * - Transfers data from internal ArrayBuffer, which will be detached
+     *
+     * @param {AudioContext} audioContext
+     *
+     * @returns {Promise<AudioBuffer>}
+     */
+    getAudioBuffer(audioContext: AudioContext): Promise<AudioBuffer>;
+    #private;
+}
+import { NetworkLoader } from '../network-loader/index.js';

package/dist/classes/svelte/audio/AudioLoader.svelte.js

@@ -0,0 +1,58 @@
+import {
+  NetworkLoader,
+  ERROR_NOT_LOADED,
+  ERROR_TRANSFERRED
+} from '../network-loader/index.js';
+
+/**
+ * AudioLoader instance
+ * - Loads audio data from network into an ArrayBuffer
+ * - Loaded data can be transferred to an AudioBufferSourceNode
+ */
+export default class AudioLoader extends NetworkLoader {
+  /** @type {AudioBuffer|null} */
+  #audioBuffer = null;
+
+  /**
+   * Get an AudioBufferSourceNode instance
+   *
+   * @note AudioBufferSourceNodes can play only once, a new source node
+   *       must be created otherwise
+   *
+   * @param {AudioContext} audioContext
+   *
+   * @returns {Promise<AudioBufferSourceNode>}
+   */
+  async getAudioBufferSourceNode(audioContext) {
+    if (!this.#audioBuffer) {
+      this.#audioBuffer = await this.getAudioBuffer(audioContext);
+    }
+
+    return new AudioBufferSourceNode(audioContext, {
+      buffer: this.#audioBuffer
+    });
+  }
+
+  /**
+   * Gets data as AudioBuffer
+   * - Stores created AudioBuffer instance internally
+   * - Transfers data from internal ArrayBuffer, which will be detached
+   *
+   * @param {AudioContext} audioContext
+   *
+   * @returns {Promise<AudioBuffer>}
+   */
+  async getAudioBuffer(audioContext) {
+    if (!this._buffer) {
+      throw new Error(ERROR_NOT_LOADED);
+    }
+
+    if (this._buffer.detached) {
+      throw new Error(ERROR_TRANSFERRED);
+    }
+
+    this.#audioBuffer = await audioContext.decodeAudioData(this._buffer);
+
+    return this.#audioBuffer;
+  }
+} // end class