@twin.org/core 0.0.3 → 0.0.4-next.10

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/Factory.md

@@ -72,6 +72,34 @@ All the factories.
 
 ***
 
+### getFactory() {#getfactory}
+
+> `static` **getFactory**\<`T`\>(`typeName`): `Factory`\<`T`\> \| `undefined`
+
+Get a specific factory by type name.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+#### Parameters
+
+##### typeName
+
+`string`
+
+The type name of the factory.
+
+#### Returns
+
+`Factory`\<`T`\> \| `undefined`
+
+The factory instance if it exists, otherwise undefined.
+
+***
+
 ### resetFactories() {#resetfactories}
 
 > `static` **resetFactories**(): `void`

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/Guards.md

@@ -536,6 +536,114 @@ GuardError If the value does not match the assertion.
 
 ***
 
+### dateString() {#datestring}
+
+> `static` **dateString**(`source`, `property`, `value`): `asserts value is string`
+
+Is the property a date-only string (ISO 8601 date, no time component).
+
+#### Parameters
+
+##### source
+
+`string`
+
+The source of the error.
+
+##### property
+
+`string`
+
+The name of the property.
+
+##### value
+
+`unknown`
+
+The value to test.
+
+#### Returns
+
+`asserts value is string`
+
+#### Throws
+
+GuardError If the value does not match the assertion.
+
+***
+
+### dateTimeString() {#datetimestring}
+
+> `static` **dateTimeString**(`source`, `property`, `value`): `asserts value is string`
+
+Is the property a date-time string (ISO 8601 with T separator).
+
+#### Parameters
+
+##### source
+
+`string`
+
+The source of the error.
+
+##### property
+
+`string`
+
+The name of the property.
+
+##### value
+
+`unknown`
+
+The value to test.
+
+#### Returns
+
+`asserts value is string`
+
+#### Throws
+
+GuardError If the value does not match the assertion.
+
+***
+
+### timeString() {#timestring}
+
+> `static` **timeString**(`source`, `property`, `value`): `asserts value is string`
+
+Is the property a time-only string (ISO 8601 time, no date component).
+
+#### Parameters
+
+##### source
+
+`string`
+
+The source of the error.
+
+##### property
+
+`string`
+
+The name of the property.
+
+##### value
+
+`unknown`
+
+The value to test.
+
+#### Returns
+
+`asserts value is string`
+
+#### Throws
+
+GuardError If the value does not match the assertion.
+
+***
+
 ### timestampMilliseconds() {#timestampmilliseconds}
 
 > `static` **timestampMilliseconds**(`source`, `property`, `value`): `asserts value is number`

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/Mutex.md

@@ -37,14 +37,14 @@ Runtime name for the class.
 
 ### lock() {#lock}
 
-> `static` **lock**(`key`, `options?`): `boolean`
+> `static` **lock**(`key`, `options?`): `Promise`\<`boolean`\>
 
-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.
+Acquires a lock for the given key without blocking the event loop. If the lock is already
+held, it suspends the current async task until the lock is released or the timeout is reached.
+Use this in async single-threaded contexts (e.g. the main thread or a Fastify route handler)
+where calling the synchronous lock() would freeze the event loop and deadlock.
+The lock is not re-entrant: if the same context holds the key and calls lockAsync() again on
+the same key, it will suspend until the timeout elapses.
 
 #### Parameters
 
@@ -72,7 +72,7 @@ Whether to throw an error if the lock could not be acquired within the timeout,
 
 #### Returns
 
-`boolean`
+`Promise`\<`boolean`\>
 
 True if the lock was acquired, false if it timed out and throwOnTimeout is false.
 

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
 

package/docs/reference/classes/SharedObjectBuffer.md

@@ -0,0 +1,192 @@
+# Class: SharedObjectBuffer
+
+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.
+
+## Constructors
+
+### Constructor
+
+> **new SharedObjectBuffer**(): `SharedObjectBuffer`
+
+#### Returns
+
+`SharedObjectBuffer`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+***
+
+### DEFAULT\_CAPACITY\_BYTES {#default_capacity_bytes}
+
+> `readonly` `static` **DEFAULT\_CAPACITY\_BYTES**: `number`
+
+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.
+
+***
+
+### MAX\_CAPACITY\_BYTES {#max_capacity_bytes}
+
+> `readonly` `static` **MAX\_CAPACITY\_BYTES**: `number`
+
+Default upper bound for how large a buffer may grow (256 MiB).
+Override per-object via the maxCapacityBytes option on create.
+
+## Methods
+
+### create() {#create}
+
+> `static` **create**(`objectId`, `options?`): `Promise`\<`void`\>
+
+Create the buffer for the given objectId if it does not already exist.
+Must be called while holding Mutex.lock(objectId).
+
+#### Parameters
+
+##### objectId
+
+`string`
+
+The object id that identifies the buffer.
+
+##### options?
+
+[`ISharedObjectBufferOptions`](../interfaces/ISharedObjectBufferOptions.md)
+
+Optional capacity configuration used when creating the buffer.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### read() {#read}
+
+> `static` **read**\<`T`\>(`objectId`): `Promise`\<`T` \| `undefined`\>
+
+Read and decode the object stored for the given objectId.
+Must be called while holding Mutex.lock(objectId).
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### objectId
+
+`string`
+
+The object id that identifies the buffer.
+
+#### Returns
+
+`Promise`\<`T` \| `undefined`\>
+
+The stored object, or undefined when nothing has been written yet.
+
+***
+
+### write() {#write}
+
+> `static` **write**\<`T`\>(`objectId`, `value`): `Promise`\<`void`\>
+
+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).
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### objectId
+
+`string`
+
+The object id that identifies the buffer.
+
+##### value
+
+`T`
+
+The object to persist.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### remove() {#remove}
+
+> `static` **remove**(`objectId`): `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).
+
+#### Parameters
+
+##### objectId
+
+`string`
+
+The object id that identifies the buffer.
+
+#### Returns
+
+`void`
+
+***
+
+### handleWorkerMessage() {#handleworkermessage}
+
+> `static` **handleWorkerMessage**(`msg`): `boolean`
+
+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.
+
+#### Parameters
+
+##### msg
+
+`unknown`
+
+The raw message received from the worker.
+
+#### Returns
+
+`boolean`
+
+True if the message was a SharedObjectBuffer protocol message, false otherwise.

package/docs/reference/classes/SharedStore.md

@@ -1,7 +1,7 @@
 # Class: SharedStore
 
-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.
 
 ## Constructors
 

package/docs/reference/classes/StringHelper.md

@@ -297,19 +297,6 @@ The string split into words.
 > `static` **isUtf8**(`data`): `boolean`
 
 Check if a Node.js Buffer or Uint8Array is UTF-8.
-Url https://tools.ietf.org/html/rfc3629
-Source 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.
-UTF8-3    = %xE0 %xA0-BF UTF8-tail.
--           %xE1-EC 2( UTF8-tail ).
--           %xED %x80-9F UTF8-tail.
--           %xEE-EF 2( UTF8-tail ).
-UTF8-4    = %xF0 %x90-BF 2( UTF8-tail ).
--           %xF1-F3 3( UTF8-tail ).
--           %xF4 %x80-8F 2( UTF8-tail ).
-UTF8-tail = %x80-BF.
 
 #### Parameters
 
@@ -324,3 +311,19 @@ The data to check.
 `boolean`
 
 True if the data is utf8.
+
+#### See
+
+ - https://tools.ietf.org/html/rfc3629
+ - 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.
+UTF8-3    = %xE0 %xA0-BF UTF8-tail.
+-           %xE1-EC 2( UTF8-tail ).
+-           %xED %x80-9F UTF8-tail.
+-           %xEE-EF 2( UTF8-tail ).
+UTF8-4    = %xF0 %x90-BF 2( UTF8-tail ).
+-           %xF1-F3 3( UTF8-tail ).
+-           %xF4 %x80-8F 2( UTF8-tail ).
+UTF8-tail = %x80-BF.