@twin.org/core 0.0.4-next.1 → 0.0.4-next.11

package/dist/es/utils/sharedObjectBuffer.js

@@ -0,0 +1,305 @@
+import { GeneralError, Is, ObjectHelper, SharedStore } from "@twin.org/core";
+import { SharedObjectBufferMessageTypes } from "../models/sharedObjectBufferMessageTypes.js";
+/**
+ * Manages per-object SharedArrayBuffers that store objects as UTF-8 JSON.
+ * Buffer layout: 4-byte Int32 header (current data byte length) followed by the JSON-encoded object.
+ * Buffers are explicitly created with create and cached in SharedStore.
+ * On a worker thread an existing buffer is fetched via a MessagePort handshake
+ * (same protocol as Mutex) and cached locally.
+ * Buffers grow automatically when the payload exceeds capacity; when the payload drops well below
+ * capacity the buffer is replaced with a smaller one. The caller must hold the objectId-keyed Mutex
+ * around every read and write. The main thread's worker message handler must forward messages to
+ * both Mutex.handleWorkerMessage and SharedObjectBuffer.handleWorkerMessage.
+ */
+export class SharedObjectBuffer {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "SharedObjectBuffer";
+    /**
+     * Default payload capacity per object (1 MiB). The first caller that creates the buffer
+     * for an object determines its initial capacity; later callers that pass a different value
+     * are ignored.
+     */
+    static DEFAULT_CAPACITY_BYTES = 1 * 1024 * 1024;
+    /**
+     * Default upper bound for how large a buffer may grow (256 MiB).
+     * Override per-object via the maxCapacityBytes option on create.
+     */
+    static MAX_CAPACITY_BYTES = 256 * 1024 * 1024;
+    /**
+     * Bytes reserved for the data-length header at the start of each buffer.
+     * @internal
+     */
+    static _HEADER_BYTES = 4;
+    /**
+     * Multiplier applied to the current capacity when growing or sizing a replacement buffer.
+     * @internal
+     */
+    static _GROW_FACTOR = 2;
+    /**
+     * Fraction of payload capacity below which a buffer is replaced with a smaller one.
+     * A value of 0.25 means the buffer is shrunk when the payload is below 25 % of capacity.
+     * Shrinking only applies when the capacity already exceeds DEFAULT_CAPACITY_BYTES.
+     * @internal
+     */
+    static _SHRINK_THRESHOLD = 0.25;
+    /**
+     * SharedStore key under which the per-object buffer map lives on each thread.
+     * @internal
+     */
+    static _STORE_KEY = "sharedObjectBuffers";
+    /**
+     * Cached worker_threads module; undefined = not yet loaded, null = unavailable.
+     * @internal
+     */
+    // false positive: this is a type not an actual import
+    // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+    static _workerThreadsModule;
+    /**
+     * Create the buffer for the given objectId if it does not already exist.
+     * Must be called while holding Mutex.lock(objectId).
+     * @param objectId The object id that identifies the buffer.
+     * @param options Optional capacity configuration used when creating the buffer.
+     */
+    static async create(objectId, options) {
+        await SharedObjectBuffer.getOrFetchBuffer(objectId, options ?? {});
+    }
+    /**
+     * Read and decode the object stored for the given objectId.
+     * Must be called while holding Mutex.lock(objectId).
+     * @param objectId The object id that identifies the buffer.
+     * @returns The stored object, or undefined when nothing has been written yet.
+     */
+    static async read(objectId) {
+        const buf = await SharedObjectBuffer.getOrFetchBuffer(objectId);
+        if (Is.undefined(buf)) {
+            return undefined;
+        }
+        return SharedObjectBuffer.decode(buf);
+    }
+    /**
+     * Encode and write the object into the buffer for the given objectId.
+     * The buffer must already exist, usually by calling create first.
+     * When the encoded payload exceeds the current buffer capacity the buffer is grown
+     * in-place via SharedArrayBuffer.grow so every thread with a reference sees the
+     * new size without any pointer swap. When the payload is smaller than
+     * _SHRINK_THRESHOLD of the current capacity and the capacity exceeds
+     * DEFAULT_CAPACITY_BYTES, the buffer is replaced with a smaller one on the calling thread.
+     * Must be called while holding Mutex.lock(objectId).
+     * @param objectId The object id that identifies the buffer.
+     * @param value The object to persist.
+     */
+    static async write(objectId, value) {
+        const encoded = ObjectHelper.toBytes(value);
+        let buf = await SharedObjectBuffer.getOrFetchBuffer(objectId);
+        if (Is.undefined(buf)) {
+            throw new GeneralError(SharedObjectBuffer.CLASS_NAME, "notCreated", {
+                objectId
+            });
+        }
+        const payloadCapacity = buf.byteLength - SharedObjectBuffer._HEADER_BYTES;
+        const maxPayloadCapacity = buf.maxByteLength - SharedObjectBuffer._HEADER_BYTES;
+        if (encoded.length > payloadCapacity) {
+            // Grow the buffer in-place. SharedArrayBuffer.grow is atomic: all threads that
+            // hold a reference see the enlarged buffer without a pointer swap.
+            const newPayloadCapacity = Math.max(encoded.length, payloadCapacity * SharedObjectBuffer._GROW_FACTOR);
+            const newByteLength = Math.min(SharedObjectBuffer._HEADER_BYTES + newPayloadCapacity, buf.maxByteLength);
+            if (encoded.length > newByteLength - SharedObjectBuffer._HEADER_BYTES) {
+                throw new GeneralError(SharedObjectBuffer.CLASS_NAME, "capacityExceeded", {
+                    objectId,
+                    required: encoded.length,
+                    capacity: maxPayloadCapacity
+                });
+            }
+            buf.grow(newByteLength);
+        }
+        else if (payloadCapacity > SharedObjectBuffer.DEFAULT_CAPACITY_BYTES &&
+            encoded.length < payloadCapacity * SharedObjectBuffer._SHRINK_THRESHOLD) {
+            // Replace with a smaller buffer when far below capacity. The caller writes
+            // the payload into the returned buffer immediately after.
+            buf = SharedObjectBuffer.shrinkBuffer(objectId, encoded.length, buf.maxByteLength);
+        }
+        new Uint8Array(buf, SharedObjectBuffer._HEADER_BYTES).set(encoded);
+        Atomics.store(new Int32Array(buf, 0, 1), 0, encoded.length);
+    }
+    /**
+     * Remove the stored object and release the buffer for the given objectId.
+     * The entry is deleted from the local cache so subsequent reads or writes will
+     * create or fetch a fresh buffer. Worker threads that have cached the old buffer
+     * reference continue using it until they restart or re-request via the worker protocol.
+     * Must be called while holding Mutex.lock(objectId).
+     * @param objectId The object id that identifies the buffer.
+     */
+    static remove(objectId) {
+        delete SharedObjectBuffer.getBuffers()[objectId];
+    }
+    /**
+     * Inspect a message from a worker thread and, if it is a SharedObjectBuffer
+     * buffer-fetch request, respond to it synchronously.
+     * Call this from the main thread's worker message handler alongside
+     * Mutex.handleWorkerMessage.
+     * @param msg The raw message received from the worker.
+     * @returns True if the message was a SharedObjectBuffer protocol message, false otherwise.
+     */
+    static handleWorkerMessage(msg) {
+        if (!Is.object(msg) ||
+            msg.type !== SharedObjectBufferMessageTypes.GetBuffer) {
+            return false;
+        }
+        const { objectId: objectName, port, signal, options } = msg;
+        const buf = Is.object(options)
+            ? SharedObjectBuffer.getOrCreateBuffer(objectName, options)
+            : SharedObjectBuffer.getBuffers()[objectName];
+        // Deliver the buffer before waking the worker so it is in the port's receive
+        // queue when Atomics.wait returns (same ordering guarantee as Mutex).
+        port.postMessage({ buffer: buf });
+        Atomics.notify(new Int32Array(signal), 0, 1);
+        port.close();
+        return true;
+    }
+    /**
+     * Decode the object from a SharedArrayBuffer.
+     * @param buf The SharedArrayBuffer to decode.
+     * @returns The decoded object, or undefined when nothing has been written.
+     * @internal
+     */
+    static decode(buf) {
+        const dataLen = Atomics.load(new Int32Array(buf, 0, 1), 0);
+        if (dataLen === 0) {
+            return undefined;
+        }
+        const bytes = new Uint8Array(buf, SharedObjectBuffer._HEADER_BYTES, dataLen);
+        return ObjectHelper.fromBytes(bytes);
+    }
+    /**
+     * Return the cached buffer for the object, creating or fetching it if needed.
+     * Applies a double-check after the async loadWorkerThreads call to handle the
+     * case where another coroutine populated the cache while this one yielded.
+     * @param objectId The object id that identifies the buffer.
+     * @param options Optional capacity configuration when creating the buffer.
+     * @returns The SharedArrayBuffer for the object.
+     * @internal
+     */
+    static async getOrFetchBuffer(objectId, options) {
+        const buffers = SharedObjectBuffer.getBuffers();
+        if (!Is.undefined(buffers[objectId])) {
+            return buffers[objectId];
+        }
+        const wt = await SharedObjectBuffer.loadWorkerThreads();
+        // Re-check after the await: another coroutine may have populated the cache.
+        if (!Is.undefined(buffers[objectId])) {
+            return buffers[objectId];
+        }
+        if (Is.empty(wt) || wt.isMainThread) {
+            if (!Is.object(options)) {
+                return buffers[objectId];
+            }
+            return SharedObjectBuffer.getOrCreateBuffer(objectId, options);
+        }
+        // Worker thread: synchronously request the SharedArrayBuffer from the main thread.
+        if (Is.empty(wt.parentPort)) {
+            throw new GeneralError(SharedObjectBuffer.CLASS_NAME, "bufferFetchFailed", { objectId });
+        }
+        const { port1, port2 } = new wt.MessageChannel();
+        const signal = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+        const request = {
+            type: SharedObjectBufferMessageTypes.GetBuffer,
+            objectId,
+            signal: signal.buffer,
+            port: port2,
+            options
+        };
+        wt.parentPort.postMessage(request, [port2]);
+        try {
+            // Block until the main thread posts the buffer and fires Atomics.notify.
+            // The response is guaranteed to be in port1's queue when wait returns because
+            // port.postMessage executes before Atomics.notify on the main thread.
+            const waitResult = Atomics.wait(signal, 0, 0, 30_000);
+            if (waitResult === "timed-out") {
+                throw new GeneralError(SharedObjectBuffer.CLASS_NAME, "bufferFetchFailed", { objectId });
+            }
+            const response = wt.receiveMessageOnPort(port1);
+            if (Is.empty(response)) {
+                throw new GeneralError(SharedObjectBuffer.CLASS_NAME, "bufferFetchFailed", { objectId });
+            }
+            if (Is.undefined(response.message.buffer)) {
+                return undefined;
+            }
+            buffers[objectId] = response.message.buffer;
+            return buffers[objectId];
+        }
+        finally {
+            port1.close();
+        }
+    }
+    /**
+     * Get or create the growable buffer on the main thread (or in a fork-mode process).
+     * @param objectId The object id that identifies the buffer.
+     * @param options Optional capacity configuration for new buffers.
+     * @returns The existing or newly created SharedArrayBuffer.
+     * @internal
+     */
+    static getOrCreateBuffer(objectId, options) {
+        const buffers = SharedObjectBuffer.getBuffers();
+        if (Is.undefined(buffers[objectId])) {
+            const maxCapacity = options?.maxCapacityBytes ?? SharedObjectBuffer.MAX_CAPACITY_BYTES;
+            const initialCapacity = Math.min(options?.initialCapacityBytes ?? SharedObjectBuffer.DEFAULT_CAPACITY_BYTES, maxCapacity);
+            buffers[objectId] = new SharedArrayBuffer(SharedObjectBuffer._HEADER_BYTES + initialCapacity, {
+                maxByteLength: SharedObjectBuffer._HEADER_BYTES + maxCapacity
+            });
+        }
+        return buffers[objectId];
+    }
+    /**
+     * Create a new smaller SharedArrayBuffer, register it in SharedStore, and return it.
+     * The new buffer is empty; write writes the current payload into it immediately
+     * after this call returns. Callers on other threads that have cached the old buffer
+     * reference continue using it until they restart or re-request via the worker protocol.
+     * @param objectId The object id that identifies the buffer.
+     * @param dataLen Byte length of the payload that will be written next.
+     * @param maxByteLength The maxByteLength to preserve from the old buffer.
+     * @returns The new, smaller SharedArrayBuffer registered in SharedStore.
+     * @internal
+     */
+    static shrinkBuffer(objectId, dataLen, maxByteLength) {
+        const newCapacity = Math.max(dataLen * SharedObjectBuffer._GROW_FACTOR, SharedObjectBuffer.DEFAULT_CAPACITY_BYTES);
+        const newBuf = new SharedArrayBuffer(SharedObjectBuffer._HEADER_BYTES + newCapacity, {
+            maxByteLength
+        });
+        SharedObjectBuffer.getBuffers()[objectId] = newBuf;
+        return newBuf;
+    }
+    /**
+     * Return the per-thread buffer map from SharedStore, creating it if absent.
+     * @returns The map of object id to SharedArrayBuffer.
+     * @internal
+     */
+    static getBuffers() {
+        let buffers = SharedStore.get(SharedObjectBuffer._STORE_KEY);
+        if (Is.undefined(buffers)) {
+            buffers = {};
+            SharedStore.set(SharedObjectBuffer._STORE_KEY, buffers);
+        }
+        return buffers;
+    }
+    /**
+     * Lazily load node:worker_threads, returning null in environments where it is unavailable.
+     * @returns The worker_threads module or null.
+     * @internal
+     */
+    // false positive: this is a type not an actual import
+    // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+    static async loadWorkerThreads() {
+        if (SharedObjectBuffer._workerThreadsModule === undefined) {
+            try {
+                SharedObjectBuffer._workerThreadsModule = await import("node:worker_threads");
+            }
+            catch {
+                SharedObjectBuffer._workerThreadsModule = null;
+            }
+        }
+        return SharedObjectBuffer._workerThreadsModule;
+    }
+}
+//# sourceMappingURL=sharedObjectBuffer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sharedObjectBuffer.js","sourceRoot":"","sources":["../../../src/utils/sharedObjectBuffer.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { MessagePort } from \"node:worker_threads\";\nimport { GeneralError, Is, ObjectHelper, SharedStore } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport type { ISharedObjectBufferOptions } from \"../models/ISharedObjectBufferOptions.js\";\nimport type { ISharedObjectBufferWorkerMessage } from \"../models/ISharedObjectBufferWorkerMessage.js\";\nimport { SharedObjectBufferMessageTypes } from \"../models/sharedObjectBufferMessageTypes.js\";\n\n/**\n * Manages per-object SharedArrayBuffers that store objects as UTF-8 JSON.\n * Buffer layout: 4-byte Int32 header (current data byte length) followed by the JSON-encoded object.\n * Buffers are explicitly created with create and cached in SharedStore.\n * On a worker thread an existing buffer is fetched via a MessagePort handshake\n * (same protocol as Mutex) and cached locally.\n * Buffers grow automatically when the payload exceeds capacity; when the payload drops well below\n * capacity the buffer is replaced with a smaller one. The caller must hold the objectId-keyed Mutex\n * around every read and write. The main thread's worker message handler must forward messages to\n * both Mutex.handleWorkerMessage and SharedObjectBuffer.handleWorkerMessage.\n */\nexport class SharedObjectBuffer {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<SharedObjectBuffer>();\n\n\t/**\n\t * Default payload capacity per object (1 MiB). The first caller that creates the buffer\n\t * for an object determines its initial capacity; later callers that pass a different value\n\t * are ignored.\n\t */\n\tpublic static readonly DEFAULT_CAPACITY_BYTES = 1 * 1024 * 1024;\n\n\t/**\n\t * Default upper bound for how large a buffer may grow (256 MiB).\n\t * Override per-object via the maxCapacityBytes option on create.\n\t */\n\tpublic static readonly MAX_CAPACITY_BYTES = 256 * 1024 * 1024;\n\n\t/**\n\t * Bytes reserved for the data-length header at the start of each buffer.\n\t * @internal\n\t */\n\tprivate static readonly _HEADER_BYTES = 4;\n\n\t/**\n\t * Multiplier applied to the current capacity when growing or sizing a replacement buffer.\n\t * @internal\n\t */\n\tprivate static readonly _GROW_FACTOR = 2;\n\n\t/**\n\t * Fraction of payload capacity below which a buffer is replaced with a smaller one.\n\t * A value of 0.25 means the buffer is shrunk when the payload is below 25 % of capacity.\n\t * Shrinking only applies when the capacity already exceeds DEFAULT_CAPACITY_BYTES.\n\t * @internal\n\t */\n\tprivate static readonly _SHRINK_THRESHOLD = 0.25;\n\n\t/**\n\t * SharedStore key under which the per-object buffer map lives on each thread.\n\t * @internal\n\t */\n\tprivate static readonly _STORE_KEY = \"sharedObjectBuffers\";\n\n\t/**\n\t * Cached worker_threads module; undefined = not yet loaded, null = unavailable.\n\t * @internal\n\t */\n\t// false positive: this is a type not an actual import\n\t// eslint-disable-next-line @typescript-eslint/consistent-type-imports\n\tprivate static _workerThreadsModule: typeof import(\"node:worker_threads\") | null | undefined;\n\n\t/**\n\t * Create the buffer for the given objectId if it does not already exist.\n\t * Must be called while holding Mutex.lock(objectId).\n\t * @param objectId The object id that identifies the buffer.\n\t * @param options Optional capacity configuration used when creating the buffer.\n\t */\n\tpublic static async create(\n\t\tobjectId: string,\n\t\toptions?: ISharedObjectBufferOptions\n\t): Promise<void> {\n\t\tawait SharedObjectBuffer.getOrFetchBuffer(objectId, options ?? {});\n\t}\n\n\t/**\n\t * Read and decode the object stored for the given objectId.\n\t * Must be called while holding Mutex.lock(objectId).\n\t * @param objectId The object id that identifies the buffer.\n\t * @returns The stored object, or undefined when nothing has been written yet.\n\t */\n\tpublic static async read<T>(objectId: string): Promise<T | undefined> {\n\t\tconst buf = await SharedObjectBuffer.getOrFetchBuffer(objectId);\n\t\tif (Is.undefined(buf)) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn SharedObjectBuffer.decode<T>(buf);\n\t}\n\n\t/**\n\t * Encode and write the object into the buffer for the given objectId.\n\t * The buffer must already exist, usually by calling create first.\n\t * When the encoded payload exceeds the current buffer capacity the buffer is grown\n\t * in-place via SharedArrayBuffer.grow so every thread with a reference sees the\n\t * new size without any pointer swap. When the payload is smaller than\n\t * _SHRINK_THRESHOLD of the current capacity and the capacity exceeds\n\t * DEFAULT_CAPACITY_BYTES, the buffer is replaced with a smaller one on the calling thread.\n\t * Must be called while holding Mutex.lock(objectId).\n\t * @param objectId The object id that identifies the buffer.\n\t * @param value The object to persist.\n\t */\n\tpublic static async write<T>(objectId: string, value: T): Promise<void> {\n\t\tconst encoded = ObjectHelper.toBytes(value);\n\t\tlet buf = await SharedObjectBuffer.getOrFetchBuffer(objectId);\n\n\t\tif (Is.undefined(buf)) {\n\t\t\tthrow new GeneralError(SharedObjectBuffer.CLASS_NAME, \"notCreated\", {\n\t\t\t\tobjectId\n\t\t\t});\n\t\t}\n\n\t\tconst payloadCapacity = buf.byteLength - SharedObjectBuffer._HEADER_BYTES;\n\t\tconst maxPayloadCapacity = buf.maxByteLength - SharedObjectBuffer._HEADER_BYTES;\n\n\t\tif (encoded.length > payloadCapacity) {\n\t\t\t// Grow the buffer in-place. SharedArrayBuffer.grow is atomic: all threads that\n\t\t\t// hold a reference see the enlarged buffer without a pointer swap.\n\t\t\tconst newPayloadCapacity = Math.max(\n\t\t\t\tencoded.length,\n\t\t\t\tpayloadCapacity * SharedObjectBuffer._GROW_FACTOR\n\t\t\t);\n\t\t\tconst newByteLength = Math.min(\n\t\t\t\tSharedObjectBuffer._HEADER_BYTES + newPayloadCapacity,\n\t\t\t\tbuf.maxByteLength\n\t\t\t);\n\t\t\tif (encoded.length > newByteLength - SharedObjectBuffer._HEADER_BYTES) {\n\t\t\t\tthrow new GeneralError(SharedObjectBuffer.CLASS_NAME, \"capacityExceeded\", {\n\t\t\t\t\tobjectId,\n\t\t\t\t\trequired: encoded.length,\n\t\t\t\t\tcapacity: maxPayloadCapacity\n\t\t\t\t});\n\t\t\t}\n\t\t\tbuf.grow(newByteLength);\n\t\t} else if (\n\t\t\tpayloadCapacity > SharedObjectBuffer.DEFAULT_CAPACITY_BYTES &&\n\t\t\tencoded.length < payloadCapacity * SharedObjectBuffer._SHRINK_THRESHOLD\n\t\t) {\n\t\t\t// Replace with a smaller buffer when far below capacity. The caller writes\n\t\t\t// the payload into the returned buffer immediately after.\n\t\t\tbuf = SharedObjectBuffer.shrinkBuffer(objectId, encoded.length, buf.maxByteLength);\n\t\t}\n\n\t\tnew Uint8Array(buf, SharedObjectBuffer._HEADER_BYTES).set(encoded);\n\t\tAtomics.store(new Int32Array(buf, 0, 1), 0, encoded.length);\n\t}\n\n\t/**\n\t * Remove the stored object and release the buffer for the given objectId.\n\t * The entry is deleted from the local cache so subsequent reads or writes will\n\t * create or fetch a fresh buffer. Worker threads that have cached the old buffer\n\t * reference continue using it until they restart or re-request via the worker protocol.\n\t * Must be called while holding Mutex.lock(objectId).\n\t * @param objectId The object id that identifies the buffer.\n\t */\n\tpublic static remove(objectId: string): void {\n\t\tdelete SharedObjectBuffer.getBuffers()[objectId];\n\t}\n\n\t/**\n\t * Inspect a message from a worker thread and, if it is a SharedObjectBuffer\n\t * buffer-fetch request, respond to it synchronously.\n\t * Call this from the main thread's worker message handler alongside\n\t * Mutex.handleWorkerMessage.\n\t * @param msg The raw message received from the worker.\n\t * @returns True if the message was a SharedObjectBuffer protocol message, false otherwise.\n\t */\n\tpublic static handleWorkerMessage(msg: unknown): boolean {\n\t\tif (\n\t\t\t!Is.object<ISharedObjectBufferWorkerMessage>(msg) ||\n\t\t\tmsg.type !== SharedObjectBufferMessageTypes.GetBuffer\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst {\n\t\t\tobjectId: objectName,\n\t\t\tport,\n\t\t\tsignal,\n\t\t\toptions\n\t\t} = msg as ISharedObjectBufferWorkerMessage & {\n\t\t\tport: MessagePort;\n\t\t};\n\n\t\tconst buf = Is.object(options)\n\t\t\t? SharedObjectBuffer.getOrCreateBuffer(objectName, options)\n\t\t\t: SharedObjectBuffer.getBuffers()[objectName];\n\n\t\t// Deliver the buffer before waking the worker so it is in the port's receive\n\t\t// queue when Atomics.wait returns (same ordering guarantee as Mutex).\n\t\tport.postMessage({ buffer: buf });\n\t\tAtomics.notify(new Int32Array(signal), 0, 1);\n\t\tport.close();\n\n\t\treturn true;\n\t}\n\n\t/**\n\t * Decode the object from a SharedArrayBuffer.\n\t * @param buf The SharedArrayBuffer to decode.\n\t * @returns The decoded object, or undefined when nothing has been written.\n\t * @internal\n\t */\n\tprivate static decode<T>(buf: SharedArrayBuffer): T | undefined {\n\t\tconst dataLen = Atomics.load(new Int32Array(buf, 0, 1), 0);\n\t\tif (dataLen === 0) {\n\t\t\treturn undefined;\n\t\t}\n\t\tconst bytes = new Uint8Array(buf, SharedObjectBuffer._HEADER_BYTES, dataLen);\n\t\treturn ObjectHelper.fromBytes<T>(bytes);\n\t}\n\n\t/**\n\t * Return the cached buffer for the object, creating or fetching it if needed.\n\t * Applies a double-check after the async loadWorkerThreads call to handle the\n\t * case where another coroutine populated the cache while this one yielded.\n\t * @param objectId The object id that identifies the buffer.\n\t * @param options Optional capacity configuration when creating the buffer.\n\t * @returns The SharedArrayBuffer for the object.\n\t * @internal\n\t */\n\tprivate static async getOrFetchBuffer(\n\t\tobjectId: string,\n\t\toptions?: ISharedObjectBufferOptions\n\t): Promise<SharedArrayBuffer | undefined> {\n\t\tconst buffers = SharedObjectBuffer.getBuffers();\n\n\t\tif (!Is.undefined(buffers[objectId])) {\n\t\t\treturn buffers[objectId];\n\t\t}\n\n\t\tconst wt = await SharedObjectBuffer.loadWorkerThreads();\n\n\t\t// Re-check after the await: another coroutine may have populated the cache.\n\t\tif (!Is.undefined(buffers[objectId])) {\n\t\t\treturn buffers[objectId];\n\t\t}\n\n\t\tif (Is.empty(wt) || wt.isMainThread) {\n\t\t\tif (!Is.object(options)) {\n\t\t\t\treturn buffers[objectId];\n\t\t\t}\n\t\t\treturn SharedObjectBuffer.getOrCreateBuffer(objectId, options);\n\t\t}\n\n\t\t// Worker thread: synchronously request the SharedArrayBuffer from the main thread.\n\t\tif (Is.empty(wt.parentPort)) {\n\t\t\tthrow new GeneralError(SharedObjectBuffer.CLASS_NAME, \"bufferFetchFailed\", { objectId });\n\t\t}\n\n\t\tconst { port1, port2 } = new wt.MessageChannel();\n\t\tconst signal = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));\n\n\t\tconst request: ISharedObjectBufferWorkerMessage = {\n\t\t\ttype: SharedObjectBufferMessageTypes.GetBuffer,\n\t\t\tobjectId,\n\t\t\tsignal: signal.buffer,\n\t\t\tport: port2,\n\t\t\toptions\n\t\t};\n\n\t\twt.parentPort.postMessage(request, [port2]);\n\n\t\ttry {\n\t\t\t// Block until the main thread posts the buffer and fires Atomics.notify.\n\t\t\t// The response is guaranteed to be in port1's queue when wait returns because\n\t\t\t// port.postMessage executes before Atomics.notify on the main thread.\n\t\t\tconst waitResult = Atomics.wait(signal, 0, 0, 30_000);\n\t\t\tif (waitResult === \"timed-out\") {\n\t\t\t\tthrow new GeneralError(SharedObjectBuffer.CLASS_NAME, \"bufferFetchFailed\", { objectId });\n\t\t\t}\n\n\t\t\tconst response = wt.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(SharedObjectBuffer.CLASS_NAME, \"bufferFetchFailed\", { objectId });\n\t\t\t}\n\n\t\t\tif (Is.undefined(response.message.buffer)) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tbuffers[objectId] = response.message.buffer;\n\t\t\treturn buffers[objectId];\n\t\t} finally {\n\t\t\tport1.close();\n\t\t}\n\t}\n\n\t/**\n\t * Get or create the growable buffer on the main thread (or in a fork-mode process).\n\t * @param objectId The object id that identifies the buffer.\n\t * @param options Optional capacity configuration for new buffers.\n\t * @returns The existing or newly created SharedArrayBuffer.\n\t * @internal\n\t */\n\tprivate static getOrCreateBuffer(\n\t\tobjectId: string,\n\t\toptions?: ISharedObjectBufferOptions\n\t): SharedArrayBuffer {\n\t\tconst buffers = SharedObjectBuffer.getBuffers();\n\t\tif (Is.undefined(buffers[objectId])) {\n\t\t\tconst maxCapacity = options?.maxCapacityBytes ?? SharedObjectBuffer.MAX_CAPACITY_BYTES;\n\t\t\tconst initialCapacity = Math.min(\n\t\t\t\toptions?.initialCapacityBytes ?? SharedObjectBuffer.DEFAULT_CAPACITY_BYTES,\n\t\t\t\tmaxCapacity\n\t\t\t);\n\t\t\tbuffers[objectId] = new SharedArrayBuffer(\n\t\t\t\tSharedObjectBuffer._HEADER_BYTES + initialCapacity,\n\t\t\t\t{\n\t\t\t\t\tmaxByteLength: SharedObjectBuffer._HEADER_BYTES + maxCapacity\n\t\t\t\t}\n\t\t\t);\n\t\t}\n\t\treturn buffers[objectId];\n\t}\n\n\t/**\n\t * Create a new smaller SharedArrayBuffer, register it in SharedStore, and return it.\n\t * The new buffer is empty; write writes the current payload into it immediately\n\t * after this call returns. Callers on other threads that have cached the old buffer\n\t * reference continue using it until they restart or re-request via the worker protocol.\n\t * @param objectId The object id that identifies the buffer.\n\t * @param dataLen Byte length of the payload that will be written next.\n\t * @param maxByteLength The maxByteLength to preserve from the old buffer.\n\t * @returns The new, smaller SharedArrayBuffer registered in SharedStore.\n\t * @internal\n\t */\n\tprivate static shrinkBuffer(\n\t\tobjectId: string,\n\t\tdataLen: number,\n\t\tmaxByteLength: number\n\t): SharedArrayBuffer {\n\t\tconst newCapacity = Math.max(\n\t\t\tdataLen * SharedObjectBuffer._GROW_FACTOR,\n\t\t\tSharedObjectBuffer.DEFAULT_CAPACITY_BYTES\n\t\t);\n\t\tconst newBuf = new SharedArrayBuffer(SharedObjectBuffer._HEADER_BYTES + newCapacity, {\n\t\t\tmaxByteLength\n\t\t});\n\t\tSharedObjectBuffer.getBuffers()[objectId] = newBuf;\n\t\treturn newBuf;\n\t}\n\n\t/**\n\t * Return the per-thread buffer map from SharedStore, creating it if absent.\n\t * @returns The map of object id to SharedArrayBuffer.\n\t * @internal\n\t */\n\tprivate static getBuffers(): { [objectId: string]: SharedArrayBuffer } {\n\t\tlet buffers = SharedStore.get<{ [objectId: string]: SharedArrayBuffer }>(\n\t\t\tSharedObjectBuffer._STORE_KEY\n\t\t);\n\t\tif (Is.undefined(buffers)) {\n\t\t\tbuffers = {};\n\t\t\tSharedStore.set(SharedObjectBuffer._STORE_KEY, buffers);\n\t\t}\n\t\treturn buffers;\n\t}\n\n\t/**\n\t * Lazily load node:worker_threads, returning null in environments where it is unavailable.\n\t * @returns The worker_threads module or null.\n\t * @internal\n\t */\n\t// false positive: this is a type not an actual import\n\t// eslint-disable-next-line @typescript-eslint/consistent-type-imports\n\tprivate static async loadWorkerThreads(): Promise<typeof import(\"node:worker_threads\") | null> {\n\t\tif (SharedObjectBuffer._workerThreadsModule === undefined) {\n\t\t\ttry {\n\t\t\t\tSharedObjectBuffer._workerThreadsModule = await import(\"node:worker_threads\");\n\t\t\t} catch {\n\t\t\t\tSharedObjectBuffer._workerThreadsModule = null;\n\t\t\t}\n\t\t}\n\t\treturn SharedObjectBuffer._workerThreadsModule;\n\t}\n}\n"]}

package/dist/es/utils/sharedStore.js

@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0.
 import { Is } from "./is.js";
 /**
- * Provide a store for shared objects which can be accesses through multiple
- * instance loads of a packages.
+ * Provide a store for shared objects which can be accessed through multiple
+ * instance loads of a package.
  */
 export class SharedStore {
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"sharedStore.js","sourceRoot":"","sources":["../../../src/utils/sharedStore.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B;;;GAGG;AACH,MAAM,OAAO,WAAW;IACvB;;;;OAIG;IACI,MAAM,CAAC,GAAG,CAAc,IAAY;QAC1C,8DAA8D;QAC9D,MAAM,MAAM,GAAI,UAAkB,CAAC,eAAe,CAAC;QACnD,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO;QACR,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAM,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,GAAG,CAAc,IAAY,EAAE,KAAQ;QACpD,8DAA8D;QAC9D,IAAI,EAAE,CAAC,SAAS,CAAE,UAAkB,CAAC,eAAe,CAAC,EAAE,CAAC;YACvD,8DAA8D;YAC7D,UAAkB,CAAC,eAAe,GAAG,EAAE,CAAC;QAC1C,CAAC;QAED,8DAA8D;QAC7D,UAAkB,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACnD,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,MAAM,CAAC,IAAY;QAChC,8DAA8D;QAC9D,MAAM,MAAM,GAAI,UAAkB,CAAC,eAAe,CAAC;QACnD,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACF,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is } from \"./is.js\";\n\n/**\n * Provide a store for shared objects which can be accesses through multiple\n * instance loads of a packages.\n */\nexport class SharedStore {\n\t/**\n\t * Get a property from the shared store.\n\t * @param prop The name of the property to get.\n\t * @returns The property if it exists.\n\t */\n\tpublic static get<T = unknown>(prop: string): T | undefined {\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst shared = (globalThis as any).__TWIN_SHARED__;\n\t\tif (Is.undefined(shared)) {\n\t\t\treturn;\n\t\t}\n\n\t\treturn shared[prop] as T;\n\t}\n\n\t/**\n\t * Set the property in the shared store.\n\t * @param prop The name of the property to set.\n\t * @param value The value to set.\n\t */\n\tpublic static set<T = unknown>(prop: string, value: T): void {\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tif (Is.undefined((globalThis as any).__TWIN_SHARED__)) {\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t(globalThis as any).__TWIN_SHARED__ = {};\n\t\t}\n\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t(globalThis as any).__TWIN_SHARED__[prop] = value;\n\t}\n\n\t/**\n\t * Remove a property from the shared store.\n\t * @param prop The name of the property to remove.\n\t */\n\tpublic static remove(prop: string): void {\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst shared = (globalThis as any).__TWIN_SHARED__;\n\t\tif (!Is.undefined(shared)) {\n\t\t\tdelete shared[prop];\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"sharedStore.js","sourceRoot":"","sources":["../../../src/utils/sharedStore.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B;;;GAGG;AACH,MAAM,OAAO,WAAW;IACvB;;;;OAIG;IACI,MAAM,CAAC,GAAG,CAAc,IAAY;QAC1C,8DAA8D;QAC9D,MAAM,MAAM,GAAI,UAAkB,CAAC,eAAe,CAAC;QACnD,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO;QACR,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAM,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,GAAG,CAAc,IAAY,EAAE,KAAQ;QACpD,8DAA8D;QAC9D,IAAI,EAAE,CAAC,SAAS,CAAE,UAAkB,CAAC,eAAe,CAAC,EAAE,CAAC;YACvD,8DAA8D;YAC7D,UAAkB,CAAC,eAAe,GAAG,EAAE,CAAC;QAC1C,CAAC;QAED,8DAA8D;QAC7D,UAAkB,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACnD,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,MAAM,CAAC,IAAY;QAChC,8DAA8D;QAC9D,MAAM,MAAM,GAAI,UAAkB,CAAC,eAAe,CAAC;QACnD,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACF,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is } from \"./is.js\";\n\n/**\n * Provide a store for shared objects which can be accessed through multiple\n * instance loads of a package.\n */\nexport class SharedStore {\n\t/**\n\t * Get a property from the shared store.\n\t * @param prop The name of the property to get.\n\t * @returns The property if it exists.\n\t */\n\tpublic static get<T = unknown>(prop: string): T | undefined {\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst shared = (globalThis as any).__TWIN_SHARED__;\n\t\tif (Is.undefined(shared)) {\n\t\t\treturn;\n\t\t}\n\n\t\treturn shared[prop] as T;\n\t}\n\n\t/**\n\t * Set the property in the shared store.\n\t * @param prop The name of the property to set.\n\t * @param value The value to set.\n\t */\n\tpublic static set<T = unknown>(prop: string, value: T): void {\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tif (Is.undefined((globalThis as any).__TWIN_SHARED__)) {\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t(globalThis as any).__TWIN_SHARED__ = {};\n\t\t}\n\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t(globalThis as any).__TWIN_SHARED__[prop] = value;\n\t}\n\n\t/**\n\t * Remove a property from the shared store.\n\t * @param prop The name of the property to remove.\n\t */\n\tpublic static remove(prop: string): void {\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst shared = (globalThis as any).__TWIN_SHARED__;\n\t\tif (!Is.undefined(shared)) {\n\t\t\tdelete shared[prop];\n\t\t}\n\t}\n}\n"]}

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

@@ -14,7 +14,7 @@ export declare class ConflictError extends BaseError {
      * @param conflictId The id that has conflicts.
      * @param conflicts The conflicts that occurred.
      * @param properties Any additional information for the error.
-     * @param cause The cause or the error if we have wrapped another error.
+     * @param cause The cause of the error if we have wrapped another error.
      */
     constructor(source: string, message: string, conflictId?: string, conflicts?: string[], properties?: {
         [id: string]: unknown;

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

@@ -1,6 +1,6 @@
 import { BaseError } from "./baseError.js";
 /**
- * Class to handle errors.
+ * Class to handle general-purpose errors.
  */
 export declare class GeneralError extends BaseError {
     /**

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

@@ -1,6 +1,6 @@
 import { BaseError } from "./baseError.js";
 /**
- * Class to handle errors.
+ * Class to handle errors raised when a method has not been implemented.
  */
 export declare class NotImplementedError extends BaseError {
     /**

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

@@ -5,7 +5,7 @@ import type { IValidationFailure } from "../models/IValidationFailure.js";
  */
 export declare class ValidationError extends BaseError {
     /**
-     * Runtime name for the class.s
+     * Runtime name for the class.
      */
     static readonly CLASS_NAME: string;
     /**

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

@@ -21,6 +21,12 @@ export declare class Factory<T> {
     static getFactories(): {
         [typeName: string]: Factory<unknown>;
     };
+    /**
+     * Get a specific factory by type name.
+     * @param typeName The type name of the factory.
+     * @returns The factory instance if it exists, otherwise undefined.
+     */
+    static getFactory<T = unknown>(typeName: string): Factory<T> | undefined;
     /**
      * Reset all the factories, which removes any created instances, but not the registrations.
      */

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

@@ -6,7 +6,7 @@ export declare class ArrayHelper {
      * Do the two arrays match.
      * @param arr1 The first array.
      * @param arr2 The second array.
-     * @returns True if both arrays are empty of have the same values.
+     * @returns True if both arrays are empty or have the same values.
      */
     static matches(arr1: unknown, arr2: unknown): boolean;
     /**

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

@@ -4,7 +4,7 @@ import type { IError } from "../models/IError.js";
  */
 export declare class ErrorHelper {
     /**
-     * Format Errors and returns just their messages.
+     * Format errors and returns just their messages.
      * @param error The error to format.
      * @param options Options for formatting the error.
      * @param options.includeStack Whether to include the stack trace in the output, defaults to false.

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

@@ -26,7 +26,7 @@ export declare class JsonHelper {
      * Applies a RFC 6902 diff set to an object.
      * Based on https://www.rfc-editor.org/rfc/rfc6902.
      * @param object The object to patch.
-     * @param patches The second object.
+     * @param patches The patch operations to apply.
      * @returns The updated object.
      * @throws GeneralError if the patch fails.
      */

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

@@ -99,13 +99,13 @@ export declare class ObjectHelper {
      */
     static omit<T, K extends keyof T>(obj: T | undefined, keys?: K[]): Omit<T, K> | undefined;
     /**
-     * Converter the non JSON primitives to extended types.
+     * Convert the non JSON primitives to extended types.
      * @param obj The object to convert.
      * @returns The object with extended properties.
      */
     static toExtended(obj: any): any;
     /**
-     * Converter the extended types to non JSON primitives.
+     * Convert the extended types to non JSON primitives.
      * @param obj The object to convert.
      * @returns The object with regular properties.
      */

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

@@ -76,8 +76,8 @@ export declare class StringHelper {
     static words(input: string): string[];
     /**
      * Check if a Node.js Buffer or Uint8Array is UTF-8.
-     * Url https://tools.ietf.org/html/rfc3629
-     * Source https://github.com/hcodes/isutf8
+     * @see https://tools.ietf.org/html/rfc3629
+     * @see https://github.com/hcodes/isutf8
      * UTF8-char = UTF8-1 / UTF8-2 / UTF8-3 / UTF8-4.
      * UTF8-1    = %x00-7F.
      * UTF8-2    = %xC2-DF UTF8-tail.

package/dist/types/index.d.ts

@@ -40,9 +40,12 @@ export * from "./models/ILocaleDictionary.js";
 export * from "./models/ILocalesIndex.js";
 export * from "./models/IMutexWorkerMessage.js";
 export * from "./models/IPatchOperation.js";
+export * from "./models/ISharedObjectBufferOptions.js";
+export * from "./models/ISharedObjectBufferWorkerMessage.js";
 export * from "./models/IUrlParts.js";
 export * from "./models/IValidationFailure.js";
 export * from "./models/mutexMessageTypes.js";
+export * from "./models/sharedObjectBufferMessageTypes.js";
 export * from "./types/bitString.js";
 export * from "./types/objectOrArray.js";
 export * from "./types/singleOccurrenceArray.js";
@@ -57,5 +60,6 @@ export * from "./utils/guards.js";
 export * from "./utils/i18n.js";
 export * from "./utils/is.js";
 export * from "./utils/mutex.js";
+export * from "./utils/sharedObjectBuffer.js";
 export * from "./utils/sharedStore.js";
 export * from "./utils/validation.js";

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

@@ -23,13 +23,13 @@ export interface IComponent {
     /**
      * The component needs to be started when the node is initialized.
      * @param nodeLoggingComponentType The node logging component type.
-     * @returns Nothing.
+     * @returns A promise that resolves when the component has started.
      */
     start?(nodeLoggingComponentType?: string): Promise<void>;
     /**
      * The component needs to be stopped when the node is closed.
      * @param nodeLoggingComponentType The node logging component type.
-     * @returns Nothing.
+     * @returns A promise that resolves when the component has stopped.
      */
     stop?(nodeLoggingComponentType?: string): Promise<void>;
     /**

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

@@ -1,5 +1,5 @@
 /**
- * Model for a local.
+ * Model for a locale.
  */
 export interface ILocale {
     /**

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

@@ -0,0 +1,17 @@
+/**
+ * Options for configuring buffer capacity when creating a shared object buffer.
+ */
+export interface ISharedObjectBufferOptions {
+    /**
+     * Initial payload capacity hint in bytes.
+     * Only honoured when the buffer does not yet exist; ignored on subsequent writes.
+     * @default 1 MiB.
+     */
+    initialCapacityBytes?: number;
+    /**
+     * Maximum allowed payload capacity in bytes. The buffer will never grow beyond this limit.
+     * Only honoured when the buffer does not yet exist; ignored on subsequent writes.
+     * @default 256 MiB.
+     */
+    maxCapacityBytes?: number;
+}

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

@@ -0,0 +1,29 @@
+import type { MessagePort } from "node:worker_threads";
+import type { ISharedObjectBufferOptions } from "./ISharedObjectBufferOptions.js";
+import type { SharedObjectBufferMessageTypes } from "./sharedObjectBufferMessageTypes.js";
+/**
+ * Message sent from a worker thread to the main thread to request the SharedArrayBuffer for an object.
+ */
+export interface ISharedObjectBufferWorkerMessage {
+    /**
+     * The message type discriminant.
+     */
+    type: typeof SharedObjectBufferMessageTypes.GetBuffer;
+    /**
+     * The object id name that identifies which buffer is being requested.
+     */
+    objectId: string;
+    /**
+     * One-shot SharedArrayBuffer used for the Atomics.wait/notify handshake so the
+     * worker can block synchronously until the main thread has posted the response.
+     */
+    signal: SharedArrayBuffer;
+    /**
+     * MessagePort through which the main thread returns the object buffer.
+     */
+    port: MessagePort;
+    /**
+     * Options for creating or fetching the buffer.
+     */
+    options?: ISharedObjectBufferOptions;
+}

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

@@ -7,7 +7,7 @@ export interface IValidationFailure {
      */
     property: string;
     /**
-     * The reason the validation failed as an i18 resource error.
+     * The reason the validation failed as an i18n resource key.
      */
     reason: string;
     /**

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

@@ -0,0 +1,13 @@
+/**
+ * Message type constants for the SharedObjectBuffer worker-to-main-thread protocol.
+ */
+export declare const SharedObjectBufferMessageTypes: {
+    /**
+     * Worker requests the SharedArrayBuffer for a named object from the main thread.
+     */
+    readonly GetBuffer: "twin:sharedObjectBuffer:getBuffer";
+};
+/**
+ * Union of all SharedObjectBuffer message type strings.
+ */
+export type SharedObjectBufferMessageTypes = (typeof SharedObjectBufferMessageTypes)[keyof typeof SharedObjectBufferMessageTypes];

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

@@ -23,7 +23,7 @@ export declare class AsyncCache {
      * @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 milliseconds. Defaults to 1000 (1 second).
-     * @returns Nothing.
+     * @returns A promise that resolves when the entry has been stored.
      */
     static set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
     /**
@@ -40,11 +40,4 @@ 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;
 }