@xylabs/threads 4.13.21 → 4.13.23

package/README.md

@@ -15,12 +15,867 @@
 
 Web workers & worker threads as simple as a function call
 
-## API Documentation
+## Reference
 
-**@xylabs/sdk-js**
+**@xylabs/threads**
 
 ***
 
+## Modules
+
+- [index-browser](#index-browser/README)
+- [index-node](#index-node/README)
+
+### index-browser
+
+  ### functions
+
+    ### <a id="Transfer"></a>Transfer
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+## Call Signature
+
+```ts
+function Transfer(transferable): TransferDescriptor;
+```
+
+Mark a transferable object as such, so it will no be serialized and
+deserialized on messaging with the main thread, but to transfer
+ownership of it to the receiving thread.
+
+Only works with array buffers, message ports and few more special
+types of objects, but it's much faster than serializing and
+deserializing them.
+
+Note:
+The transferable object cannot be accessed by this thread again
+unless the receiving thread transfers it back again!
+
+### Parameters
+
+### transferable
+
+`Transferable`
+
+Array buffer, message port or similar.
+
+### Returns
+
+[`TransferDescriptor`](#../interfaces/TransferDescriptor)
+
+### See
+
+<https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast>
+
+## Call Signature
+
+```ts
+function Transfer<T>(payload, transferables): TransferDescriptor;
+```
+
+Mark transferable objects within an arbitrary object or array as
+being a transferable object. They will then not be serialized
+and deserialized on messaging with the main thread, but ownership
+of them will be tranferred to the receiving thread.
+
+Only array buffers, message ports and few more special types of
+objects can be transferred, but it's much faster than serializing and
+deserializing them.
+
+Note:
+The transferable object cannot be accessed by this thread again
+unless the receiving thread transfers it back again!
+
+### Type Parameters
+
+### T
+
+`T`
+
+### Parameters
+
+### payload
+
+`T`
+
+### transferables
+
+`Transferable`[]
+
+### Returns
+
+[`TransferDescriptor`](#../interfaces/TransferDescriptor)
+
+### See
+
+<https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast>
+
+    ### <a id="isWorkerRuntime"></a>isWorkerRuntime
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+function isWorkerRuntime(): boolean;
+```
+
+## Returns
+
+`boolean`
+
+    ### <a id="registerSerializer"></a>registerSerializer
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+function registerSerializer(serializer): void;
+```
+
+## Parameters
+
+### serializer
+
+[`SerializerImplementation`](#../interfaces/SerializerImplementation)\<[`JsonSerializable`](#../type-aliases/JsonSerializable)\>
+
+## Returns
+
+`void`
+
+    ### <a id="spawn"></a>spawn
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+function spawn<Exposed>(worker, options?): Promise<ExposedAs<Exposed>>;
+```
+
+Spawn a new thread. Takes a fresh worker instance, wraps it in a thin
+abstraction layer to provide the transparent API and verifies that
+the worker has initialized successfully.
+
+## Type Parameters
+
+### Exposed
+
+`Exposed` *extends* `WorkerFunction` \| `WorkerModule`\<`any`\> = `ArbitraryWorkerInterface`
+
+## Parameters
+
+### worker
+
+`Worker`
+
+Instance of `Worker`. Either a web worker, `worker_threads` worker or `tiny-worker` worker.
+
+### options?
+
+### timeout?
+
+`number`
+
+Init message timeout. Default: 10000 or set by environment variable.
+
+## Returns
+
+`Promise`\<[`ExposedAs`](#../type-aliases/ExposedAs)\<`Exposed`\>\>
+
+  ### interfaces
+
+    ### <a id="Pool"></a>Pool
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+Thread pool managing a set of worker threads.
+Use it to queue tasks that are run on those threads with limited
+concurrency.
+
+## Type Parameters
+
+### ThreadType
+
+`ThreadType` *extends* [`Thread`](#../type-aliases/Thread)
+
+## Methods
+
+### completed()
+
+```ts
+completed(allowResolvingImmediately?): Promise<any>;
+```
+
+Returns a promise that resolves once the task queue is emptied.
+Promise will be rejected if any task fails.
+
+### Parameters
+
+#### allowResolvingImmediately?
+
+`boolean`
+
+Set to `true` to resolve immediately if task queue is currently empty.
+
+### Returns
+
+`Promise`\<`any`\>
+
+***
+
+### settled()
+
+```ts
+settled(allowResolvingImmediately?): Promise<Error[]>;
+```
+
+Returns a promise that resolves once the task queue is emptied.
+Failing tasks will not cause the promise to be rejected.
+
+### Parameters
+
+#### allowResolvingImmediately?
+
+`boolean`
+
+Set to `true` to resolve immediately if task queue is currently empty.
+
+### Returns
+
+`Promise`\<`Error`[]\>
+
+***
+
+### events()
+
+```ts
+events(): Observable<PoolEvent<ThreadType>>;
+```
+
+Returns an observable that yields pool events.
+
+### Returns
+
+`Observable`\<`PoolEvent`\<`ThreadType`\>\>
+
+***
+
+### queue()
+
+```ts
+queue<Return>(task): QueuedTask<ThreadType, Return>;
+```
+
+Queue a task and return a promise that resolves once the task has been dequeued,
+started and finished.
+
+### Type Parameters
+
+#### Return
+
+`Return`
+
+### Parameters
+
+#### task
+
+`TaskRunFunction`\<`ThreadType`, `Return`\>
+
+An async function that takes a thread instance and invokes it.
+
+### Returns
+
+[`QueuedTask`](#QueuedTask)\<`ThreadType`, `Return`\>
+
+***
+
+### terminate()
+
+```ts
+terminate(force?): Promise<void>;
+```
+
+Terminate all pool threads.
+
+### Parameters
+
+#### force?
+
+`boolean`
+
+Set to `true` to kill the thread even if it cannot be stopped gracefully.
+
+### Returns
+
+`Promise`\<`void`\>
+
+    ### <a id="QueuedTask"></a>QueuedTask
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+Task that has been `pool.queued()`-ed.
+
+## Type Parameters
+
+### ThreadType
+
+`ThreadType` *extends* [`Thread`](#../type-aliases/Thread)
+
+### Return
+
+`Return`
+
+## Properties
+
+### then()
+
+```ts
+then: <TResult1, TResult2>(onfulfilled?, onrejected?) => Promise<TResult1 | TResult2>;
+```
+
+`QueuedTask` is thenable, so you can `await` it.
+Resolves when the task has successfully been executed. Rejects if the task fails.
+
+Attaches callbacks for the resolution and/or rejection of the Promise.
+
+### Type Parameters
+
+#### TResult1
+
+`TResult1` = `Return`
+
+#### TResult2
+
+`TResult2` = `never`
+
+### Parameters
+
+#### onfulfilled?
+
+The callback to execute when the Promise is resolved.
+
+`null` | (`value`) => `TResult1` \| `PromiseLike`\<`TResult1`\>
+
+#### onrejected?
+
+The callback to execute when the Promise is rejected.
+
+`null` | (`reason`) => `TResult2` \| `PromiseLike`\<`TResult2`\>
+
+### Returns
+
+`Promise`\<`TResult1` \| `TResult2`\>
+
+A Promise for the completion of which ever callback is executed.
+
+## Methods
+
+### cancel()
+
+```ts
+cancel(): void;
+```
+
+Queued tasks can be cancelled until the pool starts running them on a worker thread.
+
+### Returns
+
+`void`
+
+    ### <a id="Serializer"></a>Serializer
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+## Type Parameters
+
+### Msg
+
+`Msg` = [`JsonSerializable`](#../type-aliases/JsonSerializable)
+
+### Input
+
+`Input` = `any`
+
+## Methods
+
+### deserialize()
+
+```ts
+deserialize(message): Input;
+```
+
+### Parameters
+
+#### message
+
+`Msg`
+
+### Returns
+
+`Input`
+
+***
+
+### serialize()
+
+```ts
+serialize(input): Msg;
+```
+
+### Parameters
+
+#### input
+
+`Input`
+
+### Returns
+
+`Msg`
+
+    ### <a id="SerializerImplementation"></a>SerializerImplementation
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+## Type Parameters
+
+### Msg
+
+`Msg` = [`JsonSerializable`](#../type-aliases/JsonSerializable)
+
+### Input
+
+`Input` = `any`
+
+## Methods
+
+### deserialize()
+
+```ts
+deserialize(message, defaultDeserialize): Input;
+```
+
+### Parameters
+
+#### message
+
+`Msg`
+
+#### defaultDeserialize
+
+(`msg`) => `Input`
+
+### Returns
+
+`Input`
+
+***
+
+### serialize()
+
+```ts
+serialize(input, defaultSerialize): Msg;
+```
+
+### Parameters
+
+#### input
+
+`Input`
+
+#### defaultSerialize
+
+(`inp`) => `Msg`
+
+### Returns
+
+`Msg`
+
+    ### <a id="TransferDescriptor"></a>TransferDescriptor
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+## Type Parameters
+
+### T
+
+`T` = `any`
+
+## Properties
+
+### \[$transferable\]
+
+```ts
+[$transferable]: true;
+```
+
+***
+
+### send
+
+```ts
+send: T;
+```
+
+***
+
+### transferables
+
+```ts
+transferables: Transferable[];
+```
+
+  ### namespaces
+
+    ### Pool
+
+      ### type-aliases
+
+        ### <a id="Event"></a>Event
+
+[**@xylabs/threads**](#../../../../README)
+
+***
+
+```ts
+type Event<ThreadType> = PoolEvent<ThreadType>;
+```
+
+## Type Parameters
+
+### ThreadType
+
+`ThreadType` *extends* [`Thread`](#../../../type-aliases/Thread) = `any`
+
+        ### <a id="EventType"></a>EventType
+
+[**@xylabs/threads**](#../../../../README)
+
+***
+
+```ts
+type EventType = PoolEventType;
+```
+
+  ### type-aliases
+
+    ### <a id="BlobWorker"></a>BlobWorker
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+type BlobWorker = typeof BlobWorkerClass;
+```
+
+    ### <a id="ExposedAs"></a>ExposedAs
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+type ExposedAs<Exposed> = Exposed extends ArbitraryWorkerInterface ? ArbitraryThreadType : Exposed extends WorkerFunction ? FunctionThread<Parameters<Exposed>, StripAsync<ReturnType<Exposed>>> : Exposed extends WorkerModule<any> ? ModuleThread<Exposed> : never;
+```
+
+## Type Parameters
+
+### Exposed
+
+`Exposed` *extends* `WorkerFunction` \| `WorkerModule`\<`any`\>
+
+    ### <a id="FunctionThread"></a>FunctionThread
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+type FunctionThread<Args, ReturnType> = ProxyableFunction<Args, ReturnType> & PrivateThreadProps;
+```
+
+## Type Parameters
+
+### Args
+
+`Args` *extends* `any`[] = `any`[]
+
+### ReturnType
+
+`ReturnType` = `any`
+
+    ### <a id="JsonSerializable"></a>JsonSerializable
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+type JsonSerializable = 
+  | JsonSerializablePrimitive
+  | JsonSerializablePrimitive[]
+  | JsonSerializableObject
+  | JsonSerializableObject[];
+```
+
+    ### <a id="ModuleThread"></a>ModuleThread
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+type ModuleThread<Methods> = ModuleProxy<Methods> & PrivateThreadProps;
+```
+
+## Type Parameters
+
+### Methods
+
+`Methods` *extends* `ModuleMethods` = `any`
+
+    ### <a id="Thread"></a>Thread
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+type Thread = ThreadType;
+```
+
+    ### <a id="Worker"></a>Worker
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+type Worker = WorkerType;
+```
+
+  ### variables
+
+    ### <a id="BlobWorker"></a>BlobWorker
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+BlobWorker: typeof BlobWorker;
+```
+
+Separate class to spawn workers from source code blobs or strings.
+
+    ### <a id="DefaultSerializer"></a>DefaultSerializer
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+const DefaultSerializer: Serializer<JsonSerializable>;
+```
+
+    ### <a id="Pool"></a>Pool
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+Pool: <ThreadType>(spawnWorker, optionsOrSize?) => WorkerPool<ThreadType> & object;
+```
+
+Thread pool constructor. Creates a new pool and spawns its worker threads.
+
+## Type declaration
+
+### EventType
+
+```ts
+EventType: typeof PoolEventType;
+```
+
+    ### <a id="Thread"></a>Thread
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+Thread: object;
+```
+
+Thread utility functions. Use them to manage or inspect a `spawn()`-ed thread.
+
+## Type declaration
+
+### errors()
+
+```ts
+errors<ThreadT>(thread): Observable<Error>;
+```
+
+Return an observable that can be used to subscribe to all errors happening in the thread.
+
+### Type Parameters
+
+#### ThreadT
+
+`ThreadT` *extends* `Thread`
+
+### Parameters
+
+#### thread
+
+`ThreadT`
+
+### Returns
+
+`Observable`\<`Error`\>
+
+### events()
+
+```ts
+events<ThreadT>(thread): Observable<WorkerEvent>;
+```
+
+Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging.
+
+### Type Parameters
+
+#### ThreadT
+
+`ThreadT` *extends* `Thread`
+
+### Parameters
+
+#### thread
+
+`ThreadT`
+
+### Returns
+
+`Observable`\<`WorkerEvent`\>
+
+### terminate()
+
+```ts
+terminate<ThreadT>(thread): Promise<void>;
+```
+
+Terminate a thread. Remember to terminate every thread when you are done using it.
+
+### Type Parameters
+
+#### ThreadT
+
+`ThreadT` *extends* `Thread`
+
+### Parameters
+
+#### thread
+
+`ThreadT`
+
+### Returns
+
+`Promise`\<`void`\>
+
+    ### <a id="Worker"></a>Worker
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+Worker: typeof WorkerImplementation;
+```
+
+Worker implementation. Either web worker or a node.js Worker class.
+
+### index-node
+
+  ### functions
+
+    ### <a id="isWorkerRuntime"></a>isWorkerRuntime
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+function isWorkerRuntime(): boolean;
+```
+
+## Returns
+
+`boolean`
+
+  ### type-aliases
+
+    ### <a id="BlobWorker"></a>BlobWorker
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+type BlobWorker = typeof BlobWorkerClass;
+```
+
+    ### <a id="Worker"></a>Worker
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+type Worker = WorkerType;
+```
+
+  ### variables
+
+    ### <a id="BlobWorker"></a>BlobWorker
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+BlobWorker: typeof BlobWorker;
+```
+
+Separate class to spawn workers from source code blobs or strings.
+
+    ### <a id="Worker"></a>Worker
+
+[**@xylabs/threads**](#../../README)
+
+***
+
+```ts
+Worker: typeof WorkerImplementation;
+```
+
+Worker implementation. Either web worker or a node.js Worker class.
 
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/threads",
-  "version": "4.13.21",
+  "version": "4.13.23",
   "description": "Web workers & worker threads as simple as a function call",
   "keywords": [
     "thread",
@@ -113,15 +113,15 @@
     "package-compile-tsup": "tsup --config tsup.browser.config.ts && tsup --config tsup.node.config.ts && tsup --config tsup.neutral.config.ts"
   },
   "dependencies": {
-    "@xylabs/assert": "^4.13.21",
+    "@xylabs/assert": "^4.13.23",
     "debug": "^4.4.1",
     "is-observable-2-1-0": "npm:is-observable@2.1.0",
     "observable-fns": "^0.6.1"
   },
   "devDependencies": {
-    "@swc/core": "^1.12.14",
+    "@swc/core": "^1.13.1",
     "@types/debug": "^4.1.12",
-    "@types/node": "^24.0.14",
+    "@types/node": "^24.0.15",
     "@xylabs/eslint-config-flat": "^7.0.0",
     "@xylabs/ts-scripts-yarn3": "^7.0.0",
     "eslint": "^9.31.0",