@twin.org/core 0.0.4-next.7 → 0.0.4-next.9

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

@@ -6,71 +6,61 @@ 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 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/is.d.ts

@@ -5,25 +5,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 +33,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 +134,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;
     /**

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

package/docs/changelog.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.0.4-next.9](https://github.com/iotaledger/twin-framework/compare/core-v0.0.4-next.8...core-v0.0.4-next.9) (2026-06-15)
+
+
+### Features
+
+* shared object buffer ([#355](https://github.com/iotaledger/twin-framework/issues/355)) ([70d82ea](https://github.com/iotaledger/twin-framework/commit/70d82ea8f43f01aa840ae90ee0b1f23b064a07c6))
+
+
+### Bug Fixes
+
+* linting ([b77511d](https://github.com/iotaledger/twin-framework/commit/b77511de8781707088b1beb4c92f12d7d6e0fd5f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.0.4-next.8 to 0.0.4-next.9
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.4-next.8 to 0.0.4-next.9
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.4-next.8 to 0.0.4-next.9
+
+## [0.0.4-next.8](https://github.com/iotaledger/twin-framework/compare/core-v0.0.4-next.7...core-v0.0.4-next.8) (2026-06-10)
+
+
+### Miscellaneous Chores
+
+* **core:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.0.4-next.7 to 0.0.4-next.8
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.4-next.7 to 0.0.4-next.8
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.4-next.7 to 0.0.4-next.8
+
 ## [0.0.4-next.7](https://github.com/iotaledger/twin-framework/compare/core-v0.0.4-next.6...core-v0.0.4-next.7) (2026-06-10)
 
 

package/docs/reference/classes/ArrayHelper.md

@@ -38,7 +38,7 @@ The second array.
 
 `boolean`
 
-True if both arrays are empty of have the same values.
+True if both arrays are empty or have the same values.
 
 ***
 

package/docs/reference/classes/AsyncCache.md

@@ -125,7 +125,7 @@ The TTL of the entry in the cache in milliseconds. Defaults to 1000 (1 second).
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the entry has been stored.
 
 ***
 

package/docs/reference/classes/Coerce.md

@@ -32,11 +32,7 @@ The value to coerce.
 
 `string` \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced string, or undefined if the value cannot be coerced.
 
 ***
 
@@ -58,11 +54,7 @@ The value to coerce.
 
 `number` \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced number, or undefined if the value cannot be coerced.
 
 ***
 
@@ -84,11 +76,7 @@ The value to coerce.
 
 `number` \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced integer, or undefined if the value cannot be coerced.
 
 ***
 
@@ -110,11 +98,7 @@ The value to coerce.
 
 `bigint` \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced bigint, or undefined if the value cannot be coerced.
 
 ***
 
@@ -136,11 +120,7 @@ The value to coerce.
 
 `boolean` \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced boolean, or undefined if the value cannot be coerced.
 
 ***
 
@@ -162,11 +142,7 @@ The value to coerce.
 
 `Date` \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced date, or undefined if the value cannot be coerced.
 
 ***
 
@@ -188,11 +164,7 @@ The value to coerce.
 
 `Date` \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced date/time, or undefined if the value cannot be coerced.
 
 ***
 
@@ -214,11 +186,7 @@ The value to coerce.
 
 `Date` \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced time, or undefined if the value cannot be coerced.
 
 ***
 
@@ -246,11 +214,7 @@ The value to coerce.
 
 `T` \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced object, or undefined if the value cannot be coerced.
 
 ***
 
@@ -272,11 +236,7 @@ The value to coerce.
 
 `Uint8Array`\<`ArrayBufferLike`\> \| `undefined`
 
-The value if it can be coerced.
-
-#### Throws
-
-TypeError If the value can not be coerced.
+The coerced Uint8Array, or undefined if the value cannot be coerced.
 
 ***
 

package/docs/reference/classes/Compression.md

@@ -26,7 +26,7 @@ Runtime name for the class.
 
 > `static` **compress**(`bytes`, `type`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
 
-Compress bytes using GZIP.
+Compress bytes using the specified compression type.
 
 #### Parameters
 

package/docs/reference/classes/ConflictError.md

@@ -48,7 +48,7 @@ Any additional information for the error.
 
 `unknown`
 
-The cause or the error if we have wrapped another error.
+The cause of the error if we have wrapped another error.
 
 #### Returns
 

package/docs/reference/classes/ErrorHelper.md

@@ -18,7 +18,7 @@ Error helper functions.
 
 > `static` **formatErrors**(`error`, `options?`): `string`[]
 
-Format Errors and returns just their messages.
+Format errors and returns just their messages.
 
 #### Parameters
 

package/docs/reference/classes/GeneralError.md

@@ -1,6 +1,6 @@
 # Class: GeneralError
 
-Class to handle errors.
+Class to handle general-purpose errors.
 
 ## Extends
 

package/docs/reference/classes/Is.md

@@ -32,7 +32,7 @@ The value to test.
 
 `value is undefined`
 
-True if the value is a empty.
+True if the value is undefined.
 
 ***
 
@@ -54,7 +54,7 @@ The value to test.
 
 `value is null`
 
-True if the value is a empty.
+True if the value is null.
 
 ***
 
@@ -76,7 +76,7 @@ The value to test.
 
 value is null \| undefined
 
-True if the value is a empty.
+True if the value is null or undefined.
 
 ***
 
@@ -84,7 +84,7 @@ True if the value is a empty.
 
 > `static` **notEmpty**(`value`): `boolean`
 
-Is the property is not null or undefined.
+Is the property not null or undefined.
 
 #### Parameters
 
@@ -98,7 +98,7 @@ The value to test.
 
 `boolean`
 
-True if the value is a not empty.
+True if the value is not null or undefined.
 
 ***
 
@@ -128,7 +128,7 @@ True if the value is a string.
 
 > `static` **stringValue**(`value`): `value is string`
 
-Is the value a string.
+Is the value a non-empty string.
 
 #### Parameters
 
@@ -142,7 +142,7 @@ The value to test.
 
 `value is string`
 
-True if the value is a string.
+True if the value is a non-empty string.
 
 ***
 
@@ -512,7 +512,7 @@ The value to test.
 
 `value is number`
 
-True if the value is a date.
+True if the value is a timestamp in seconds.
 
 ***
 
@@ -534,7 +534,7 @@ The value to test.
 
 `value is number`
 
-True if the value is a date.
+True if the value is a timestamp in milliseconds.
 
 ***
 

package/docs/reference/classes/JsonHelper.md

@@ -105,7 +105,7 @@ The object to patch.
 
 [`IPatchOperation`](../interfaces/IPatchOperation.md)[]
 
-The second object.
+The patch operations to apply.
 
 #### Returns
 

package/docs/reference/classes/NotImplementedError.md

@@ -1,6 +1,6 @@
 # Class: NotImplementedError
 
-Class to handle errors.
+Class to handle errors raised when a method has not been implemented.
 
 ## Extends
 

package/docs/reference/classes/ObjectHelper.md

@@ -506,7 +506,7 @@ The object without the omitted keys, or undefined if the input was undefined.
 
 > `static` **toExtended**(`obj`): `any`
 
-Converter the non JSON primitives to extended types.
+Convert the non JSON primitives to extended types.
 
 #### Parameters
 
@@ -528,7 +528,7 @@ The object with extended properties.
 
 > `static` **fromExtended**(`obj`): `any`
 
-Converter the extended types to non JSON primitives.
+Convert the extended types to non JSON primitives.
 
 #### Parameters