@twin.org/core 0.0.3-next.9 → 0.0.4-next.1

package/dist/types/helpers/objectHelper.d.ts

@@ -58,8 +58,8 @@ export declare class ObjectHelper {
     static propertySet(obj: unknown, property: string, value: unknown): void;
     /**
      * Delete the property of an unknown object.
-     * @param obj The object to set the property from.
-     * @param property The property to set
+     * @param obj The object to delete the property from.
+     * @param property The property to delete.
      */
     static propertyDelete(obj: unknown, property: string): void;
     /**
@@ -74,26 +74,30 @@ export declare class ObjectHelper {
      * Pick a subset of properties from an object.
      * @param obj The object to pick the properties from.
      * @param keys The property keys to pick.
-     * @returns The partial object.
+     * @returns The picked object.
      */
-    static pick<T>(obj: T | undefined, keys?: (keyof T)[]): Partial<T>;
+    static pick<T, K extends keyof T>(obj: T, keys?: K[]): Pick<T, K>;
+    /**
+     * Pick a subset of properties from an object.
+     * @param obj The object to pick the properties from.
+     * @param keys The property keys to pick.
+     * @returns The picked object, or undefined if the input was undefined.
+     */
+    static pick<T, K extends keyof T>(obj: T | undefined, keys?: K[]): Pick<T, K> | undefined;
     /**
      * Omit a subset of properties from an object.
      * @param obj The object to omit the properties from.
      * @param keys The property keys to omit.
-     * @returns The partial object.
+     * @returns The object without the omitted keys.
      */
-    static omit<T>(obj: T | undefined, keys?: (keyof T)[]): Partial<T>;
+    static omit<T, K extends keyof T>(obj: T, keys?: K[]): Omit<T, K>;
     /**
-     * Split an object into two with the specified keys.
-     * @param obj The object to split.
-     * @param keys The property keys to split.
-     * @returns The two partial objects.
+     * Omit a subset of properties from an object.
+     * @param obj The object to omit the properties from.
+     * @param keys The property keys to omit.
+     * @returns The object without the omitted keys, or undefined if the input was undefined.
      */
-    static split<T>(obj: T | undefined, keys?: (keyof T)[]): {
-        picked: Partial<T> | undefined;
-        omitted: Partial<T> | undefined;
-    };
+    static omit<T, K extends keyof T>(obj: T | undefined, keys?: K[]): Omit<T, K> | undefined;
     /**
      * Converter the non JSON primitives to extended types.
      * @param obj The object to convert.

package/dist/types/helpers/stringHelper.d.ts

@@ -14,6 +14,12 @@ export declare class StringHelper {
      * @returns The trimmed string or the original.
      */
     static trimLeadingSlashes(value: string): string;
+    /**
+     * Trim both leading and trailing slashes from a string.
+     * @param value The value to trim.
+     * @returns The trimmed string or the original.
+     */
+    static trimLeadingAndTrailingSlashes(value: string): string;
     /**
      * Convert the input string to kebab case.
      * @param input The input to convert.

package/dist/types/index.d.ts

@@ -28,19 +28,25 @@ export * from "./helpers/stringHelper.js";
 export * from "./helpers/uint8ArrayHelper.js";
 export * from "./models/coerceType.js";
 export * from "./models/compressionType.js";
+export * from "./models/healthStatus.js";
 export * from "./models/IComponent.js";
 export * from "./models/IError.js";
+export * from "./models/IHealth.js";
 export * from "./models/II18nShared.js";
 export * from "./models/IKeyValue.js";
 export * from "./models/ILabelledValue.js";
 export * from "./models/ILocale.js";
 export * from "./models/ILocaleDictionary.js";
 export * from "./models/ILocalesIndex.js";
+export * from "./models/IMutexWorkerMessage.js";
 export * from "./models/IPatchOperation.js";
 export * from "./models/IUrlParts.js";
 export * from "./models/IValidationFailure.js";
-export * from "./models/objectOrArray.js";
+export * from "./models/mutexMessageTypes.js";
 export * from "./types/bitString.js";
+export * from "./types/objectOrArray.js";
+export * from "./types/singleOccurrenceArray.js";
+export * from "./types/singleOccurrenceArrayDepthHelper.js";
 export * from "./types/url.js";
 export * from "./types/urn.js";
 export * from "./utils/asyncCache.js";
@@ -50,5 +56,6 @@ export * from "./utils/converter.js";
 export * from "./utils/guards.js";
 export * from "./utils/i18n.js";
 export * from "./utils/is.js";
+export * from "./utils/mutex.js";
 export * from "./utils/sharedStore.js";
 export * from "./utils/validation.js";

package/dist/types/models/IComponent.d.ts

@@ -1,3 +1,4 @@
+import type { IHealth } from "./IHealth.js";
 /**
  * Interface describing a component which can be bootstrapped, started and stopped.
  */
@@ -13,6 +14,12 @@ export interface IComponent {
      * @returns True if the bootstrapping process was successful.
      */
     bootstrap?(nodeLoggingComponentType?: string): Promise<boolean>;
+    /**
+     * Teardown the component by releasing any resources it holds.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns True if the teardown process was successful.
+     */
+    teardown?(nodeLoggingComponentType?: string): Promise<boolean>;
     /**
      * The component needs to be started when the node is initialized.
      * @param nodeLoggingComponentType The node logging component type.
@@ -25,4 +32,9 @@ export interface IComponent {
      * @returns Nothing.
      */
     stop?(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Returns the health status of the component.
+     * @returns The health status of the component, can return multiple entries for elements within the component.
+     */
+    health?(): Promise<IHealth[]>;
 }

package/dist/types/models/IError.d.ts

@@ -7,7 +7,7 @@ export interface IError {
      */
     name: string;
     /**
-     * The message for the error.
+     * The message for the error as an i18n key.
      */
     message: string;
     /**

package/dist/types/models/IHealth.d.ts

@@ -0,0 +1,32 @@
+import type { HealthStatus } from "./healthStatus.js";
+/**
+ * Provides health information for a component.
+ */
+export interface IHealth {
+    /**
+     * The source of the health information.
+     */
+    source: string;
+    /**
+     * The description of the component as an i18n key.
+     */
+    description?: string;
+    /**
+     * The overall status of the component, the entries can also report their own health.
+     */
+    status: HealthStatus;
+    /**
+     * The message for the status if there are further details to provide as an i18n key.
+     */
+    message?: string;
+    /**
+     * Data to substitute in the i18n key for the message.
+     */
+    data?: {
+        [id: string]: unknown;
+    };
+    /**
+     * The grouped child components, if any.
+     */
+    grouped?: IHealth[];
+}

package/dist/types/models/IMutexWorkerMessage.d.ts

@@ -0,0 +1,23 @@
+import type { MessagePort } from "node:worker_threads";
+import type { MutexMessageTypes } from "./mutexMessageTypes.js";
+/**
+ * Message sent from a worker thread to the main thread to request a SharedArrayBuffer for a given mutex key.
+ */
+export interface IMutexWorkerMessage {
+    /**
+     * The message type.
+     */
+    type: typeof MutexMessageTypes.GetBuffer;
+    /**
+     * The mutex key for which the buffer is requested.
+     */
+    key: string;
+    /**
+     * The SharedArrayBuffer for the mutex, sent from the worker to the main thread.
+     */
+    signal: SharedArrayBuffer;
+    /**
+     * The MessagePort for the main thread to respond with the buffer, sent from the worker to the main thread.
+     */
+    port: MessagePort;
+}

package/dist/types/models/healthStatus.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The health status of the component.
+ */
+export declare const HealthStatus: {
+    /**
+     * OK.
+     */
+    readonly Ok: "ok";
+    /**
+     * Warning.
+     */
+    readonly Warning: "warning";
+    /**
+     * Error.
+     */
+    readonly Error: "error";
+};
+/**
+ * The health status of the component.
+ */
+export type HealthStatus = (typeof HealthStatus)[keyof typeof HealthStatus];

package/dist/types/models/mutexMessageTypes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mutex message types.
+ */
+export declare const MutexMessageTypes: {
+    /**
+     * Get buffer.
+     */
+    readonly GetBuffer: "twin:mutex:getBuffer";
+};
+/**
+ * Mutex message types.
+ */
+export type MutexMessageTypes = (typeof MutexMessageTypes)[keyof typeof MutexMessageTypes];

package/dist/types/types/singleOccurrenceArray.d.ts

@@ -0,0 +1,6 @@
+import type { SingleOccurrenceArrayDepthHelper } from "./singleOccurrenceArrayDepthHelper.js";
+/**
+ * Utility type to create a non-empty array with values of type T and exactly one value of type U.
+ */
+export type SingleOccurrenceArray<T = unknown, U = never> = SingleOccurrenceArrayDepthHelper<T, U, [
+]>;

package/dist/types/types/singleOccurrenceArrayDepthHelper.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Helper with bounded recursion depth to keep type instantiation tractable.
+ */
+export type SingleOccurrenceArrayDepthHelper<T, U, Depth extends 0[]> = Depth["length"] extends 16 ? [U, ...T[]] : [U, ...T[]] | [T, ...SingleOccurrenceArrayDepthHelper<T, U, [0, ...Depth]>];

package/dist/types/utils/asyncCache.d.ts

@@ -10,18 +10,19 @@ export declare class AsyncCache {
      * @param cacheFailures Cache failure results, defaults to false.
      * @returns The response.
      */
-    static exec<T = unknown>(key: string, ttlMs: number | undefined, requestMethod: () => Promise<T>, cacheFailures?: boolean): Promise<T> | undefined;
+    static exec<T = unknown>(key: string, ttlMs: number | undefined, requestMethod: () => Promise<T>, cacheFailures?: boolean): Promise<T>;
     /**
      * Get an entry from the cache.
      * @param key The key to get from the cache.
-     * @returns The item from the cache if it exists.
+     * @returns The item from the cache if it exists, or undefined if the key is missing, expired, or
+     * its request is still in-progress. Throws if a cached failure exists for the key.
      */
     static get<T = unknown>(key: string): Promise<T | undefined>;
     /**
      * Set an entry into the cache.
      * @param key The key to set in the cache.
      * @param value The value to set in the cache.
-     * @param ttlMs The TTL of the entry in the cache in ms, defaults to 1s.
+     * @param ttlMs The TTL of the entry in the cache in milliseconds. Defaults to 1000 (1 second).
      * @returns Nothing.
      */
     static set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
@@ -39,4 +40,11 @@ export declare class AsyncCache {
      * Perform a cleanup of the expired entries in the cache.
      */
     static cleanupExpired(): void;
+    /**
+     * Resolve a waiter by re-running its request method safely.
+     * @param requestMethod The method to execute.
+     * @param resolve The resolver for the waiter.
+     * @param reject The rejector for the waiter.
+     */
+    private static resolveWaiter;
 }

package/dist/types/utils/guards.d.ts

@@ -1,4 +1,4 @@
-import type { ObjectOrArray } from "../models/objectOrArray.js";
+import type { ObjectOrArray } from "../types/objectOrArray.js";
 /**
  * Class to handle guard operations for parameters.
  */

package/dist/types/utils/mutex.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A cross-thread mutex built on Atomics and SharedArrayBuffer.
+ *
+ * When isMainThread is true (main thread or fork-mode child process) the class acts as
+ * the authoritative registry: it creates a SharedArrayBuffer-backed Int32Array for each
+ * key on first use and never discards it, because worker threads may hold references to
+ * the same underlying memory.
+ *
+ * When isMainThread is false (a true worker thread) the class synchronously negotiates
+ * the shared buffer with the main thread on first use of each key, then caches it locally.
+ * The main thread must call Mutex.handleWorkerMessage(msg) from its worker message handler
+ * before that worker first calls Mutex.lock().
+ *
+ * The lock is not re-entrant: a thread that already holds a key and calls lock() again on
+ * the same key will block until the timeout elapses.
+ */
+export declare class Mutex {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Acquires a lock for the given key without blocking the event loop. If the lock is already
+     * held, it suspends the current async task until the lock is released or the timeout is reached.
+     * Use this in async single-threaded contexts (e.g. the main thread or a Fastify route handler)
+     * where calling the synchronous lock() would freeze the event loop and deadlock.
+     * The lock is not re-entrant: if the same context holds the key and calls lockAsync() again on
+     * the same key, it will suspend until the timeout elapses.
+     * @param key The key to lock on.
+     * @param options Lock options.
+     * @param options.timeoutMs The maximum time to wait for the lock in milliseconds, default is 5000.
+     * @param options.throwOnTimeout Whether to throw an error if the lock could not be acquired within the timeout, default is false.
+     * @returns True if the lock was acquired, false if it timed out and throwOnTimeout is false.
+     * @throws GeneralError if the key is invalid or if the lock could not be acquired within the timeout and throwOnTimeout is true.
+     */
+    static lock(key: string, options?: {
+        timeoutMs?: number;
+        throwOnTimeout?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Releases the lock for the given key.
+     * @param key The key to unlock.
+     * @throws GeneralError if the key is invalid or the lock is not currently held.
+     */
+    static unlock(key: string): void;
+    /**
+     * Inspect a message received from a worker and, if it is a Mutex buffer-fetch request,
+     * respond to it synchronously. Call from the main thread's worker message handler.
+     * @param msg The raw message received from the worker.
+     * @returns True if the message was a Mutex protocol message and was handled, false otherwise.
+     */
+    static handleWorkerMessage(msg: unknown): boolean;
+}