@twin.org/core 0.0.3-next.8 → 0.0.3

package/dist/es/utils/mutex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../../src/utils/mutex.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport {\n\tMessageChannel,\n\ttype MessagePort,\n\tisMainThread,\n\tparentPort,\n\treceiveMessageOnPort\n} from \"node:worker_threads\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { Guards } from \"./guards.js\";\nimport { Is } from \"./is.js\";\nimport { SharedStore } from \"./sharedStore.js\";\nimport { GeneralError } from \"../errors/generalError.js\";\nimport type { IMutexWorkerMessage } from \"../models/IMutexWorkerMessage.js\";\nimport { MutexMessageTypes } from \"../models/mutexMessageTypes.js\";\n\n/**\n * A cross-thread mutex built on Atomics and SharedArrayBuffer.\n *\n * When isMainThread is true (main thread or fork-mode child process) the class acts as\n * the authoritative registry: it creates a SharedArrayBuffer-backed Int32Array for each\n * key on first use and never discards it, because worker threads may hold references to\n * the same underlying memory.\n *\n * When isMainThread is false (a true worker thread) the class synchronously negotiates\n * the shared buffer with the main thread on first use of each key, then caches it locally.\n * The main thread must call Mutex.handleWorkerMessage(msg) from its worker message handler\n * before that worker first calls Mutex.lock().\n *\n * The lock is not re-entrant: a thread that already holds a key and calls lock() again on\n * the same key will block until the timeout elapses.\n */\nexport class Mutex {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<Mutex>();\n\n\t/**\n\t * SharedStore key for the per-thread sparse map from lock key strings to Int32Arrays.\n\t * @internal\n\t */\n\tprivate static readonly _LOCKS_KEY = \"mutexLocks\";\n\n\t/**\n\t * Acquires a lock for the given key. If the lock is already held, it will wait until it is released or until the timeout is reached.\n\t * The lock is not re-entrant: if the same thread tries to acquire the same lock again, it will deadlock until the timeout is reached.\n\t *\n\t * WARNING: this method calls Atomics.wait internally. On the main thread this blocks the Node.js event loop for the\n\t * duration of the wait. Do not call from the main thread while a worker thread may simultaneously need to fetch a\n\t * buffer for a new mutex key, as that fetch requires the main thread's message loop to be running and will deadlock.\n\t * @param key The key to lock on.\n\t * @param options Lock options.\n\t * @param options.timeoutMs The maximum time to wait for the lock in milliseconds, default is 5000.\n\t * @param options.throwOnTimeout Whether to throw an error if the lock could not be acquired within the timeout, default is false.\n\t * @returns True if the lock was acquired, false if it timed out and throwOnTimeout is false.\n\t * @throws GeneralError if the key is invalid or if the lock could not be acquired within the timeout and throwOnTimeout is true.\n\t */\n\tpublic static lock(\n\t\tkey: string,\n\t\toptions?: { timeoutMs?: number; throwOnTimeout?: boolean }\n\t): boolean {\n\t\tGuards.stringValue(Mutex.CLASS_NAME, nameof(key), key);\n\n\t\tconst timeoutMs = options?.timeoutMs ?? 5000;\n\t\tconst throwOnTimeout = options?.throwOnTimeout ?? false;\n\t\tconst deadline = Date.now() + timeoutMs;\n\n\t\tconst lock = Mutex.getOrFetchLock(key, deadline);\n\n\t\tfor (;;) {\n\t\t\t// Atomically swap 0 → 1; if the previous value was 0 we acquired the lock.\n\t\t\tconst previous = Atomics.compareExchange(lock, 0, 0, 1);\n\t\t\tif (previous === 0) {\n\t\t\t\treturn true;\n\t\t\t}\n\n\t\t\t// Otherwise, the lock is held by someone else. Check if we've already timed out before blocking.\n\t\t\tconst remaining = deadline - Date.now();\n\t\t\tif (remaining <= 0) {\n\t\t\t\tif (throwOnTimeout) {\n\t\t\t\t\tthrow new GeneralError(Mutex.CLASS_NAME, \"lockTimeout\", { key, timeoutMs });\n\t\t\t\t}\n\t\t\t\treturn false;\n\t\t\t}\n\n\t\t\t// Block until the value changes away from 1 (i.e. the holder calls unlock)\n\t\t\t// or until the remaining timeout elapses.\n\t\t\tconst waitResult = Atomics.wait(lock, 0, 1, remaining);\n\t\t\tif (waitResult === \"timed-out\") {\n\t\t\t\tif (throwOnTimeout) {\n\t\t\t\t\tthrow new GeneralError(Mutex.CLASS_NAME, \"lockTimeout\", { key, timeoutMs });\n\t\t\t\t}\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Releases the lock for the given key.\n\t * @param key The key to unlock.\n\t * @throws GeneralError if the key is invalid or the lock is not currently held.\n\t */\n\tpublic static unlock(key: string): void {\n\t\tGuards.stringValue(Mutex.CLASS_NAME, nameof(key), key);\n\n\t\tconst locks = Mutex.getLocks();\n\t\tconst lock = locks[key];\n\t\tif (Is.empty(lock)) {\n\t\t\tthrow new GeneralError(Mutex.CLASS_NAME, \"lockNotFound\", { key });\n\t\t}\n\n\t\tconst previous = Atomics.compareExchange(lock, 0, 1, 0);\n\t\tif (previous !== 1) {\n\t\t\tthrow new GeneralError(Mutex.CLASS_NAME, \"lockAlreadyReleased\", { key });\n\t\t}\n\n\t\tAtomics.notify(lock, 0, 1);\n\t}\n\n\t/**\n\t * Inspect a message received from a worker and, if it is a Mutex buffer-fetch request,\n\t * respond to it synchronously. Call from the main thread's worker message handler.\n\t * @param msg The raw message received from the worker.\n\t * @returns True if the message was a Mutex protocol message and was handled, false otherwise.\n\t */\n\tpublic static handleWorkerMessage(msg: unknown): boolean {\n\t\tif (!Is.object<IMutexWorkerMessage>(msg) || msg.type !== MutexMessageTypes.GetBuffer) {\n\t\t\treturn false;\n\t\t}\n\n\t\tGuards.stringValue(Mutex.CLASS_NAME, nameof(msg.key), msg.key);\n\t\tGuards.object<SharedArrayBuffer>(Mutex.CLASS_NAME, nameof(msg.signal), msg.signal);\n\t\tGuards.object<MessagePort>(Mutex.CLASS_NAME, nameof(msg.port), msg.port);\n\n\t\tconst locks = Mutex.getLocks();\n\t\tlocks[msg.key] ??= new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));\n\t\t// Send the buffer to the worker before notifying so that it is guaranteed\n\t\t// to be in port1's receive queue when Atomics.wait returns on the worker side.\n\t\tmsg.port.postMessage({ buffer: locks[msg.key].buffer });\n\t\tAtomics.notify(new Int32Array(msg.signal), 0, 1);\n\t\tmsg.port.close();\n\n\t\treturn true;\n\t}\n\n\t/**\n\t * Returns the Int32Array for the given key, fetching it from the main thread if this\n\t * is a worker thread and the key is not yet in the local cache.\n\t * @param key The lock key.\n\t * @returns The Int32Array backed by a SharedArrayBuffer for this key.\n\t * @internal\n\t */\n\tprivate static getOrFetchLock(key: string, deadline: number): Int32Array {\n\t\tconst locks = Mutex.getLocks();\n\t\tif (!Is.empty(locks[key])) {\n\t\t\treturn locks[key];\n\t\t}\n\n\t\tif (isMainThread) {\n\t\t\t// Main thread or fork-mode process: own the registry entry.\n\t\t\tlocks[key] = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));\n\t\t\treturn locks[key];\n\t\t}\n\n\t\t// Worker thread: synchronously request the SharedArrayBuffer from the main thread.\n\t\t// Mutex.handleWorkerMessage(msg) must be called on the main thread's worker message handler.\n\t\tif (Is.empty(parentPort)) {\n\t\t\tthrow new GeneralError(Mutex.CLASS_NAME, \"bufferFetchFailed\", { key });\n\t\t}\n\n\t\tconst { port1, port2 } = new MessageChannel();\n\t\tconst signal = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));\n\n\t\tconst msg: IMutexWorkerMessage = {\n\t\t\ttype: MutexMessageTypes.GetBuffer,\n\t\t\tkey,\n\t\t\tsignal: signal.buffer,\n\t\t\tport: port2\n\t\t};\n\n\t\tparentPort.postMessage(msg, [port2]);\n\n\t\ttry {\n\t\t\t// Block until the main thread posts the response and fires Atomics.notify.\n\t\t\t// The response is guaranteed to be in port1's queue at this point because\n\t\t\t// port.postMessage executes before Atomics.notify on the main thread.\n\t\t\t// Use the lock deadline so the buffer fetch is bounded by the same timeout.\n\t\t\tconst waitResult = Atomics.wait(signal, 0, 0, Math.max(0, deadline - Date.now()));\n\t\t\tif (waitResult === \"timed-out\") {\n\t\t\t\tthrow new GeneralError(Mutex.CLASS_NAME, \"bufferFetchFailed\", { key });\n\t\t\t}\n\n\t\t\tconst response = receiveMessageOnPort(port1) as {\n\t\t\t\tmessage: { buffer: SharedArrayBuffer };\n\t\t\t} | null;\n\n\t\t\tif (Is.empty(response)) {\n\t\t\t\tthrow new GeneralError(Mutex.CLASS_NAME, \"bufferFetchFailed\", { key });\n\t\t\t}\n\n\t\t\tlocks[key] = new Int32Array(response.message.buffer);\n\t\t\treturn locks[key];\n\t\t} finally {\n\t\t\tport1.close();\n\t\t}\n\t}\n\n\t/**\n\t * Get the shared locks map, creating it if it does not exist.\n\t * @returns The shared locks map.\n\t * @internal\n\t */\n\tprivate static getLocks(): { [key: string]: Int32Array } {\n\t\tlet locks = SharedStore.get<{ [key: string]: Int32Array }>(Mutex._LOCKS_KEY);\n\t\tif (Is.undefined(locks)) {\n\t\t\tlocks = {};\n\t\t\tSharedStore.set(Mutex._LOCKS_KEY, locks);\n\t\t}\n\t\treturn locks;\n\t}\n}\n"]}

package/dist/types/encoding/base32.d.ts

@@ -1,5 +1,5 @@
 /**
- * Class to help with base63 Encoding/Decoding.
+ * Class to help with base32 Encoding/Decoding.
  */
 export declare class Base32 {
     /**

package/dist/types/errors/alreadyExistsError.d.ts

@@ -10,7 +10,7 @@ export declare class AlreadyExistsError extends BaseError {
     /**
      * Create a new instance of AlreadyExistsError.
      * @param source The source of the error.
-     * @param message The message as a code.
+     * @param message The message as an i18n key.
      * @param existingId The id for the item.
      * @param properties Any additional information for the error.
      * @param cause The cause of the error if we have wrapped another error.

package/dist/types/errors/baseError.d.ts

@@ -21,7 +21,7 @@ export declare class BaseError extends Error implements IError {
      * Create a new instance of BaseError.
      * @param name The name of the error.
      * @param source The source of the error.
-     * @param message The message as a code.
+     * @param message The message as an i18n key.
      * @param properties Any additional information for the error.
      * @param cause The cause of error if we have wrapped another error.
      */

package/dist/types/errors/conflictError.d.ts

@@ -10,7 +10,7 @@ export declare class ConflictError extends BaseError {
     /**
      * Create a new instance of ConflictError.
      * @param source The source of the error.
-     * @param message The message as a code.
+     * @param message The message as an i18n key.
      * @param conflictId The id that has conflicts.
      * @param conflicts The conflicts that occurred.
      * @param properties Any additional information for the error.

package/dist/types/errors/generalError.d.ts

@@ -10,7 +10,7 @@ export declare class GeneralError extends BaseError {
     /**
      * Create a new instance of GeneralError.
      * @param source The source of the error.
-     * @param message The message as a code.
+     * @param message The message as an i18n key.
      * @param properties Any additional information for the error.
      * @param cause The cause of the error if we have wrapped another error.
      */

package/dist/types/errors/guardError.d.ts

@@ -10,7 +10,7 @@ export declare class GuardError extends BaseError {
     /**
      * Create a new instance of GuardError.
      * @param source The source of the error.
-     * @param message The message as a code.
+     * @param message The message as an i18n key.
      * @param propertyName The property which triggered the guard error for the item.
      * @param propertyValue The property value which triggered the guard error for the item.
      * @param propertyOptions The property options which might be allowed.

package/dist/types/errors/notFoundError.d.ts

@@ -10,7 +10,7 @@ export declare class NotFoundError extends BaseError {
     /**
      * Create a new instance of NotFoundError.
      * @param source The source of the error.
-     * @param message The message as a code.
+     * @param message The message as an i18n key.
      * @param notFoundId The id for the item.
      * @param properties Any additional information for the error.
      * @param cause The cause of the error if we have wrapped another error.

package/dist/types/errors/notSupportedError.d.ts

@@ -10,7 +10,7 @@ export declare class NotSupportedError extends BaseError {
     /**
      * Create a new instance of NotSupportedError.
      * @param source The source of the error.
-     * @param message The message as a code.
+     * @param message The message as an i18n key.
      * @param properties Any additional information for the error.
      * @param cause The cause of the error if we have wrapped another error.
      */

package/dist/types/errors/unauthorizedError.d.ts

@@ -1,6 +1,6 @@
 import { BaseError } from "./baseError.js";
 /**
- * Class to handle errors which are triggered by access not being unauthorized.
+ * Class to handle errors which are triggered by access not being authorized.
  */
 export declare class UnauthorizedError extends BaseError {
     /**
@@ -10,7 +10,7 @@ export declare class UnauthorizedError extends BaseError {
     /**
      * Create a new instance of UnauthorizedError.
      * @param source The source of the error.
-     * @param message The message as a code.
+     * @param message The message as an i18n key.
      * @param properties Any additional information for the error.
      * @param cause The cause of the error if we have wrapped another error.
      */

package/dist/types/errors/unprocessableError.d.ts

@@ -10,7 +10,7 @@ export declare class UnprocessableError extends BaseError {
     /**
      * Create a new instance of UnprocessableError.
      * @param source The source of the error.
-     * @param message The message as a code.
+     * @param message The message as an i18n key.
      * @param properties Any additional information for the error.
      * @param cause The cause of the error if we have wrapped another error.
      */

package/dist/types/factories/factory.d.ts

@@ -29,12 +29,17 @@ export declare class Factory<T> {
      * Clear all the factories, which removes anything registered with the factories.
      */
     static clearFactories(): void;
+    /**
+     * Get the type name of the factory.
+     * @returns The type name of the factory.
+     */
+    typeName(): string;
     /**
      * Register a new generator.
      * @param name The name of the generator.
      * @param generator The function to create an instance.
      */
-    register<U extends T>(name: string, generator: () => U): void;
+    register<U extends T>(name: string, generator: (args?: unknown) => U): void;
     /**
      * Unregister a generator.
      * @param name The name of the generator to unregister.
@@ -56,6 +61,23 @@ export declare class Factory<T> {
      * @returns An instance of the item or undefined if it does not exist.
      */
     getIfExists<U extends T>(name?: string): U | undefined;
+    /**
+     * Create a new instance without caching it.
+     * @param name The name of the instance to generate.
+     * @param args The arguments to pass to the generator.
+     * @returns A new instance of the item.
+     * @throws GuardError if the parameters are invalid.
+     * @throws GeneralError if no item exists to create.
+     */
+    create<U extends T>(name: string, args?: unknown): U;
+    /**
+     * Create a new instance without caching it if it exists.
+     * @param name The name of the instance to generate.
+     * @param args The arguments to pass to the generator.
+     * @returns A new instance of the item if it exists.
+     * @throws GuardError if the parameters are invalid.
+     */
+    createIfExists<U extends T>(name: string, args?: unknown): U | undefined;
     /**
      * Remove all the instances and leave the generators intact.
      */

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

@@ -1,4 +1,3 @@
-import type { ObjectOrArray } from "../models/objectOrArray.js";
 /**
  * Class to help with arrays.
  */
@@ -15,11 +14,5 @@ export declare class ArrayHelper {
      * @param value The object or array to convert.
      * @returns The array.
      */
-    static fromObjectOrArray<T = unknown>(value: undefined): undefined;
-    /**
-     * Convert an object or array to an array.
-     * @param value The object or array to convert.
-     * @returns The array.
-     */
-    static fromObjectOrArray<T = unknown>(value: ObjectOrArray<T>): T[];
+    static fromObjectOrArray<T = unknown>(value: T | T[] | undefined): T extends undefined ? undefined : T[];
 }

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

@@ -6,20 +6,27 @@ export declare class ErrorHelper {
     /**
      * Format Errors and returns just their messages.
      * @param error The error to format.
-     * @param includeDetails Whether to include error details, defaults to false.
+     * @param options Options for formatting the error.
+     * @param options.includeStack Whether to include the stack trace in the output, defaults to false.
+     * @param options.includeAdditional Whether to include additional error information in the output, defaults to false.
      * @returns The error formatted including any causes errors.
      */
-    static formatErrors(error: unknown, includeDetails?: boolean): string[];
+    static formatErrors(error: unknown, options?: {
+        includeStack?: boolean;
+        includeAdditional?: boolean;
+    }): string[];
     /**
      * Localize the content of an error and any causes.
      * @param error The error to format.
      * @returns The localized version of the errors flattened.
      */
-    static localizeErrors(error: unknown): IError[];
+    static localizeErrors(error: unknown): (IError & {
+        additional?: string[];
+    })[];
     /**
      * Localize the content of an error and any causes.
      * @param error The error to format.
      * @returns The localized version of the errors flattened.
      */
-    static formatValidationErrors(error: IError): string | undefined;
+    static formatValidationErrors(error: IError): string[] | undefined;
 }

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/randomHelper.d.ts

@@ -2,10 +2,26 @@
  * Class to help with random generation.
  */
 export declare class RandomHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
     /**
      * Generate a new random array.
      * @param length The length of buffer to create.
      * @returns The random array.
      */
     static generate(length: number): Uint8Array;
+    /**
+     * Generate a new UUIDv7.
+     * @param format The format of the UUIDv7 string.
+     * @returns The UUIDv7 string.
+     */
+    static generateUuidV7(format?: "standard" | "compact"): string;
+    /**
+     * Extract the unix timestamp (ms) from a UUIDv7.
+     * @param uuid The UUIDv7 string.
+     * @returns The unix timestamp in milliseconds.
+     */
+    static uuidV7ExtractTimestamp(uuid: string): number;
 }

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.
  */
@@ -221,4 +221,13 @@ export declare class Guards {
      * @throws GuardError If the value does not match the assertion.
      */
     static email(source: string, property: string, value: unknown): asserts value is string;
+    /**
+     * Is the property a string containing uuidV7.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @param format The format of the uuidV7, either standard or compact.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static uuidV7(source: string, property: string, value: unknown, format?: "standard" | "compact"): asserts value is string;
 }

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

@@ -220,4 +220,11 @@ export declare class Is {
      * @returns True if the object is a class, false otherwise.
      */
     static class<T = unknown>(obj: unknown): obj is new (...args: any[]) => T;
+    /**
+     * Is the value a uuidV7 string.
+     * @param value The value to test.
+     * @param format The format of the UUIDv7 string.
+     * @returns True if the value is a uuidV7 string.
+     */
+    static uuidV7(value: unknown, format?: "standard" | "compact"): value is string;
 }

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. If the lock is already held, it will wait until it is released or until the timeout is reached.
+     * The lock is not re-entrant: if the same thread tries to acquire the same lock again, it will deadlock until the timeout is reached.
+     *
+     * WARNING: this method calls Atomics.wait internally. On the main thread this blocks the Node.js event loop for the
+     * duration of the wait. Do not call from the main thread while a worker thread may simultaneously need to fetch a
+     * buffer for a new mutex key, as that fetch requires the main thread's message loop to be running and will deadlock.
+     * @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;
+    }): 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;
+}