@twin.org/core 0.0.4-next.8 → 0.9.0-next.1

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

@@ -27,6 +27,7 @@ export * from "./helpers/randomHelper.js";
 export * from "./helpers/stringHelper.js";
 export * from "./helpers/uint8ArrayHelper.js";
 export * from "./models/coerceType.js";
+export * from "./models/IDuration.js";
 export * from "./models/compressionType.js";
 export * from "./models/healthStatus.js";
 export * from "./models/IComponent.js";
@@ -40,10 +41,15 @@ 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/duration.js";
+export * from "./types/durationRegExp.js";
 export * from "./types/objectOrArray.js";
 export * from "./types/singleOccurrenceArray.js";
 export * from "./types/singleOccurrenceArrayDepthHelper.js";
@@ -57,5 +63,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/IDuration.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Represents a duration broken down into its component parts.
+ */
+export interface IDuration {
+    /**
+     * The number of years.
+     */
+    years: number;
+    /**
+     * The number of months.
+     */
+    months: number;
+    /**
+     * The number of weeks.
+     */
+    weeks: number;
+    /**
+     * The number of days.
+     */
+    days: number;
+    /**
+     * The number of hours.
+     */
+    hours: number;
+    /**
+     * The number of minutes.
+     */
+    minutes: number;
+    /**
+     * The number of seconds.
+     */
+    seconds: number;
+    /**
+     * The number of milliseconds.
+     */
+    milliseconds?: number;
+    /**
+     * The number of microseconds.
+     */
+    microseconds?: number;
+    /**
+     * The number of nanoseconds.
+     */
+    nanoseconds?: number;
+}

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

@@ -42,6 +42,10 @@ export declare const CoerceType: {
      * Uint8Array.
      */
     readonly Uint8Array: "uint8array";
+    /**
+     * Duration in seconds.
+     */
+    readonly Duration: "duration";
 };
 /**
  * The types the extracted data can be coerced to.

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

@@ -0,0 +1,29 @@
+import type { IDuration } from "../models/IDuration.js";
+/**
+ * Helper methods for working with ISO 8601 durations.
+ */
+export declare class Duration {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Parse an ISO 8601 duration string into its component parts.
+     * @param value The string to parse.
+     * @returns The parsed duration, or undefined if the string is not a valid ISO 8601 duration.
+     */
+    static parse(value: string): IDuration | undefined;
+    /**
+     * Convert a duration object to an ISO 8601 duration string.
+     * @param duration The duration to convert.
+     * @returns The ISO 8601 duration string (e.g. "P1Y2M3DT4H5M6S").
+     */
+    static toString(duration: IDuration): string;
+    /**
+     * Convert a duration object to total seconds.
+     * Year and month components use the average values 365.25 days and 30.4375 days.
+     * @param duration The duration to convert.
+     * @returns The total number of seconds.
+     */
+    static toSeconds(duration: IDuration): number;
+}

package/dist/types/types/durationRegExp.d.ts

@@ -0,0 +1 @@
+export declare const DURATION_REG_EXP: RegExp;

package/dist/types/types/url.d.ts

@@ -11,6 +11,7 @@ export declare class Url {
     /**
      * Create a new instance of Url.
      * @param url The url string.
+     * @throws GuardError if the url is not valid.
      */
     constructor(url: string);
     /**

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>;
     /**

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

@@ -1,4 +1,5 @@
 import { CoerceType } from "../models/coerceType.js";
+import type { IDuration } from "../models/IDuration.js";
 /**
  * Coerce an object from one type to another.
  */
@@ -6,71 +7,69 @@ export declare class Coerce {
     /**
      * Coerce the value to a string.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced string, or undefined if the value cannot be coerced.
      */
     static string(value: unknown): string | undefined;
     /**
      * Coerce the value to a number.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced number, or undefined if the value cannot be coerced.
      */
     static number(value: unknown): number | undefined;
     /**
      * Coerce the value to an integer.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced integer, or undefined if the value cannot be coerced.
      */
     static integer(value: unknown): number | undefined;
     /**
      * Coerce the value to a bigint.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced bigint, or undefined if the value cannot be coerced.
      */
     static bigint(value: unknown): bigint | undefined;
     /**
      * Coerce the value to a boolean.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced boolean, or undefined if the value cannot be coerced.
      */
     static boolean(value: unknown): boolean | undefined;
     /**
      * Coerce the value to a date.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced date, or undefined if the value cannot be coerced.
      */
     static date(value: unknown): Date | undefined;
     /**
      * Coerce the value to a date/time.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced date/time, or undefined if the value cannot be coerced.
      */
     static dateTime(value: unknown): Date | undefined;
     /**
      * Coerce the value to a time.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced time, or undefined if the value cannot be coerced.
      */
     static time(value: unknown): Date | undefined;
+    /**
+     * Coerce the value to a duration object.
+     * Accepts an IDuration object, ISO 8601 duration strings (e.g. "PT1H", "P1Y2M3DT4H5M6S"),
+     * or numeric values already expressed as seconds (stored in the seconds field).
+     * @param value The value to coerce.
+     * @returns The duration object, or undefined if the value cannot be coerced.
+     */
+    static duration(value: unknown): IDuration | undefined;
     /**
      * Coerce the value to an object.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced object, or undefined if the value cannot be coerced.
      */
     static object<T = unknown>(value: unknown): T | undefined;
     /**
      * Coerce the value to a Uint8Array.
      * @param value The value to coerce.
-     * @throws TypeError If the value can not be coerced.
-     * @returns The value if it can be coerced.
+     * @returns The coerced Uint8Array, or undefined if the value cannot be coerced.
      */
     static uint8Array(value: unknown): Uint8Array | undefined;
     /**

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

@@ -8,7 +8,7 @@ export declare class Compression {
      */
     static readonly CLASS_NAME: string;
     /**
-     * Compress bytes using GZIP.
+     * Compress bytes using the specified compression type.
      * @param bytes The bytes to compress.
      * @param type The type of compression to use.
      * @returns The compressed bytes.

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

@@ -1,3 +1,4 @@
+import type { IDuration } from "../models/IDuration.js";
 import type { ObjectOrArray } from "../types/objectOrArray.js";
 /**
  * Class to handle guard operations for parameters.
@@ -254,4 +255,12 @@ export declare class Guards {
      * @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;
+    /**
+     * Is the property a valid ISO 8601 duration string or IDuration object.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static duration(source: string, property: string, value: unknown): asserts value is string | IDuration;
 }

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

@@ -1,3 +1,4 @@
+import type { IDuration } from "../models/IDuration.js";
 /**
  * Class to check types of objects.
  */
@@ -5,25 +6,25 @@ export declare class Is {
     /**
      * Is the property undefined.
      * @param value The value to test.
-     * @returns True if the value is a empty.
+     * @returns True if the value is undefined.
      */
     static undefined(value: unknown): value is undefined;
     /**
      * Is the property null.
      * @param value The value to test.
-     * @returns True if the value is a empty.
+     * @returns True if the value is null.
      */
     static null(value: unknown): value is null;
     /**
      * Is the property null or undefined.
      * @param value The value to test.
-     * @returns True if the value is a empty.
+     * @returns True if the value is null or undefined.
      */
     static empty(value: unknown): value is undefined | null;
     /**
-     * Is the property is not null or undefined.
+     * Is the property not null or undefined.
      * @param value The value to test.
-     * @returns True if the value is a not empty.
+     * @returns True if the value is not null or undefined.
      */
     static notEmpty(value: unknown): boolean;
     /**
@@ -33,9 +34,9 @@ export declare class Is {
      */
     static string(value: unknown): value is string;
     /**
-     * Is the value a string.
+     * Is the value a non-empty string.
      * @param value The value to test.
-     * @returns True if the value is a string.
+     * @returns True if the value is a non-empty string.
      */
     static stringValue(value: unknown): value is string;
     /**
@@ -134,13 +135,13 @@ export declare class Is {
     /**
      * Is the value a timestamp in seconds.
      * @param value The value to test.
-     * @returns True if the value is a date.
+     * @returns True if the value is a timestamp in seconds.
      */
     static timestampSeconds(value: unknown): value is number;
     /**
      * Is the value a timestamp in milliseconds.
      * @param value The value to test.
-     * @returns True if the value is a date.
+     * @returns True if the value is a timestamp in milliseconds.
      */
     static timestampMilliseconds(value: unknown): value is number;
     /**
@@ -227,4 +228,10 @@ export declare class Is {
      * @returns True if the value is a uuidV7 string.
      */
     static uuidV7(value: unknown, format?: "standard" | "compact"): value is string;
+    /**
+     * Is the value a valid ISO 8601 duration string or an IDuration object.
+     * @param value The value to test.
+     * @returns True if the value is a valid ISO 8601 duration string or an IDuration object.
+     */
+    static duration(value: unknown): value is string | IDuration;
 }

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

@@ -19,6 +19,17 @@ export declare class Mutex {
      * Runtime name for the class.
      */
     static readonly CLASS_NAME: string;
+    /**
+     * Gets the default timeout in milliseconds for lock acquisition.
+     * @returns The default timeout in milliseconds.
+     */
+    static getDefaultTimeoutMs(): number;
+    /**
+     * Sets the default timeout in milliseconds for lock acquisition.
+     * @param timeoutMs The default timeout in milliseconds.
+     * @throws GeneralError if timeoutMs is not a non-negative integer.
+     */
+    static setDefaultTimeoutMs(timeoutMs: number): void;
     /**
      * 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.
@@ -28,7 +39,7 @@ export declare class Mutex {
      * 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.timeoutMs The maximum time to wait for the lock in milliseconds, defaults to getDefaultTimeoutMs().
      * @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.

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

@@ -0,0 +1,74 @@
+import type { ISharedObjectBufferOptions } from "../models/ISharedObjectBufferOptions.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 declare class SharedObjectBuffer {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * 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 readonly DEFAULT_CAPACITY_BYTES: number;
+    /**
+     * Default upper bound for how large a buffer may grow (256 MiB).
+     * Override per-object via the maxCapacityBytes option on create.
+     */
+    static readonly MAX_CAPACITY_BYTES: number;
+    /**
+     * 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 create(objectId: string, options?: ISharedObjectBufferOptions): Promise<void>;
+    /**
+     * 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 read<T>(objectId: string): Promise<T | undefined>;
+    /**
+     * 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 write<T>(objectId: string, value: T): Promise<void>;
+    /**
+     * 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: string): void;
+    /**
+     * 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: unknown): boolean;
+}

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

@@ -1,6 +1,6 @@
 /**
- * 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 declare class SharedStore {
     /**