@xylabs/threads 5.0.83 → 5.0.86

package/README.md

@@ -15,6 +15,8 @@
 
 Web workers & worker threads as simple as a function call
 
+
+
 ## Reference
 
 **@xylabs/threads**
@@ -23,8 +25,10 @@ Web workers & worker threads as simple as a function call
 
 ## Modules
 
-- [index-browser](#index-browser/README)
-- [index-node](#index-node/README)
+| Module | Description |
+| ------ | ------ |
+| [index-browser](#index-browser/README) | - |
+| [index-node](#index-node/README) | - |
 
 ### index-browser
 
@@ -39,7 +43,7 @@ Web workers & worker threads as simple as a function call
 ## Call Signature
 
 ```ts
-function Transfer(transferable): TransferDescriptor;
+function Transfer(transferable: Transferable): TransferDescriptor;
 ```
 
 Mark a transferable object as such, so it will no be serialized and
@@ -56,11 +60,9 @@ unless the receiving thread transfers it back again!
 
 ### Parameters
 
-### transferable
-
-`Transferable`
-
-Array buffer, message port or similar.
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `transferable` | `Transferable` | Array buffer, message port or similar. |
 
 ### Returns
 
@@ -73,7 +75,7 @@ Array buffer, message port or similar.
 ## Call Signature
 
 ```ts
-function Transfer<T>(payload, transferables): TransferDescriptor;
+function Transfer<T>(payload: T, transferables: Transferable[]): TransferDescriptor;
 ```
 
 Mark transferable objects within an arbitrary object or array as
@@ -91,19 +93,16 @@ unless the receiving thread transfers it back again!
 
 ### Type Parameters
 
-### T
-
-`T`
+| Type Parameter |
+| ------ |
+| `T` |
 
 ### Parameters
 
-### payload
-
-`T`
-
-### transferables
-
-`Transferable`[]
+| Parameter | Type |
+| ------ | ------ |
+| `payload` | `T` |
+| `transferables` | `Transferable`[] |
 
 ### Returns
 
@@ -123,10 +122,14 @@ unless the receiving thread transfers it back again!
 function isWorkerRuntime(): boolean;
 ```
 
+Check whether the current code is running inside a web worker context.
+
 ## Returns
 
 `boolean`
 
+True if running in a worker, false otherwise.
+
     ### <a id="registerSerializer"></a>registerSerializer
 
 [**@xylabs/threads**](#../../README)
@@ -134,14 +137,16 @@ function isWorkerRuntime(): boolean;
 ***
 
 ```ts
-function registerSerializer(serializer): void;
+function registerSerializer(serializer: SerializerImplementation<JsonSerializable>): void;
 ```
 
-## Parameters
+Register a custom serializer to extend the default serialization behavior for worker messages.
 
-### serializer
+## Parameters
 
-[`SerializerImplementation`](#../interfaces/SerializerImplementation)\<[`JsonSerializable`](#../type-aliases/JsonSerializable)\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `serializer` | [`SerializerImplementation`](#../interfaces/SerializerImplementation)\<[`JsonSerializable`](#../type-aliases/JsonSerializable)\> | The serializer implementation to register. |
 
 ## Returns
 
@@ -154,7 +159,9 @@ function registerSerializer(serializer): void;
 ***
 
 ```ts
-function spawn<Exposed>(worker, options?): Promise<ExposedAs<Exposed>>;
+function spawn<Exposed>(worker: Worker, options?: {
+  timeout?: number;
+}): Promise<ExposedAs<Exposed>>;
 ```
 
 Spawn a new thread. Takes a fresh worker instance, wraps it in a thin
@@ -163,25 +170,17 @@ the worker has initialized successfully.
 
 ## Type Parameters
 
-### Exposed
-
-`Exposed` *extends* `WorkerFunction` \| `WorkerModule`\<`any`\> = `ArbitraryWorkerInterface`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Exposed` *extends* `WorkerFunction` \| `WorkerModule`\<`any`\> | `ArbitraryWorkerInterface` |
 
 ## Parameters
 
-### worker
-
-`Worker`
-
-Instance of `Worker`. Either a web worker or `worker_threads` worker.
-
-### options?
-
-### timeout?
-
-`number`
-
-Init message timeout. Default: 10000 or set by environment variable.
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `worker` | `Worker` | Instance of `Worker`. Either a web worker or `worker_threads` worker. |
+| `options?` | \{ `timeout?`: `number`; \} | - |
+| `options.timeout?` | `number` | Init message timeout. Default: 10000 or set by environment variable. |
 
 ## Returns
 
@@ -201,16 +200,16 @@ concurrency.
 
 ## Type Parameters
 
-### ThreadType
-
-`ThreadType` *extends* [`Thread`](#../type-aliases/Thread)
+| Type Parameter |
+| ------ |
+| `ThreadType` *extends* [`Thread`](#../type-aliases/Thread) |
 
 ## Methods
 
 ### completed()
 
 ```ts
-completed(allowResolvingImmediately?): Promise<any>;
+completed(allowResolvingImmediately?: boolean): Promise<any>;
 ```
 
 Returns a promise that resolves once the task queue is emptied.
@@ -218,11 +217,9 @@ Promise will be rejected if any task fails.
 
 ### Parameters
 
-#### allowResolvingImmediately?
-
-`boolean`
-
-Set to `true` to resolve immediately if task queue is currently empty.
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `allowResolvingImmediately?` | `boolean` | Set to `true` to resolve immediately if task queue is currently empty. |
 
 ### Returns
 
@@ -233,7 +230,7 @@ Set to `true` to resolve immediately if task queue is currently empty.
 ### settled()
 
 ```ts
-settled(allowResolvingImmediately?): Promise<Error[]>;
+settled(allowResolvingImmediately?: boolean): Promise<Error[]>;
 ```
 
 Returns a promise that resolves once the task queue is emptied.
@@ -241,11 +238,9 @@ 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.
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `allowResolvingImmediately?` | `boolean` | Set to `true` to resolve immediately if task queue is currently empty. |
 
 ### Returns
 
@@ -270,7 +265,7 @@ Returns an observable that yields pool events.
 ### queue()
 
 ```ts
-queue<Return>(task): QueuedTask<ThreadType, Return>;
+queue<Return>(task: TaskRunFunction<ThreadType, Return>): QueuedTask<ThreadType, Return>;
 ```
 
 Queue a task and return a promise that resolves once the task has been dequeued,
@@ -278,17 +273,15 @@ started and finished.
 
 ### Type Parameters
 
-#### Return
-
-`Return`
+| Type Parameter |
+| ------ |
+| `Return` |
 
 ### Parameters
 
-#### task
-
-`TaskRunFunction`\<`ThreadType`, `Return`\>
-
-An async function that takes a thread instance and invokes it.
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `task` | `TaskRunFunction`\<`ThreadType`, `Return`\> | An async function that takes a thread instance and invokes it. |
 
 ### Returns
 
@@ -299,18 +292,16 @@ An async function that takes a thread instance and invokes it.
 ### terminate()
 
 ```ts
-terminate(force?): Promise<void>;
+terminate(force?: boolean): Promise<void>;
 ```
 
 Terminate all pool threads.
 
 ### Parameters
 
-#### force?
-
-`boolean`
-
-Set to `true` to kill the thread even if it cannot be stopped gracefully.
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `force?` | `boolean` | Set to `true` to kill the thread even if it cannot be stopped gracefully. |
 
 ### Returns
 
@@ -326,56 +317,16 @@ Task that has been `pool.queued()`-ed.
 
 ## Type Parameters
 
-### ThreadType
-
-`ThreadType` *extends* [`Thread`](#../type-aliases/Thread)
-
-### Return
-
-`Return`
+| Type Parameter |
+| ------ |
+| `ThreadType` *extends* [`Thread`](#../type-aliases/Thread) |
+| `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.
-
-(`value`) => `TResult1` \| `PromiseLike`\<`TResult1`\> | `null`
-
-#### onrejected?
-
-The callback to execute when the Promise is rejected.
-
-(`reason`) => `TResult2` \| `PromiseLike`\<`TResult2`\> | `null`
-
-### Returns
-
-`Promise`\<`TResult1` \| `TResult2`\>
-
-A Promise for the completion of which ever callback is executed.
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="then"></a> `then` | \<`TResult1`, `TResult2`\>(`onfulfilled?`: (`value`: `Return`) => `TResult1` \| `PromiseLike`\<`TResult1`\> \| `null`, `onrejected?`: (`reason`: `any`) => `TResult2` \| `PromiseLike`\<`TResult2`\> \| `null`) => `Promise`\<`TResult1` \| `TResult2`\> | `QueuedTask` is thenable, so you can `await` it. Resolves when the task has successfully been executed. Rejects if the task fails. |
 
 ## Methods
 
@@ -397,29 +348,28 @@ Queued tasks can be cancelled until the pool starts running them on a worker thr
 
 ***
 
-## Type Parameters
-
-### Msg
-
-`Msg` = [`JsonSerializable`](#../type-aliases/JsonSerializable)
+A serializer that can convert between a message format and an input type.
 
-### Input
+## Type Parameters
 
-`Input` = `any`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Msg` | [`JsonSerializable`](#../type-aliases/JsonSerializable) |
+| `Input` | `any` |
 
 ## Methods
 
 ### deserialize()
 
 ```ts
-deserialize(message): Input;
+deserialize(message: Msg): Input;
 ```
 
 ### Parameters
 
-#### message
-
-`Msg`
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `Msg` |
 
 ### Returns
 
@@ -430,14 +380,14 @@ deserialize(message): Input;
 ### serialize()
 
 ```ts
-serialize(input): Msg;
+serialize(input: Input): Msg;
 ```
 
 ### Parameters
 
-#### input
-
-`Input`
+| Parameter | Type |
+| ------ | ------ |
+| `input` | `Input` |
 
 ### Returns
 
@@ -449,33 +399,29 @@ serialize(input): Msg;
 
 ***
 
-## Type Parameters
-
-### Msg
-
-`Msg` = [`JsonSerializable`](#../type-aliases/JsonSerializable)
+A serializer implementation that receives a fallback (default) serializer for chaining.
 
-### Input
+## Type Parameters
 
-`Input` = `any`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Msg` | [`JsonSerializable`](#../type-aliases/JsonSerializable) |
+| `Input` | `any` |
 
 ## Methods
 
 ### deserialize()
 
 ```ts
-deserialize(message, defaultDeserialize): Input;
+deserialize(message: Msg, defaultDeserialize: (msg: Msg) => Input): Input;
 ```
 
 ### Parameters
 
-#### message
-
-`Msg`
-
-#### defaultDeserialize
-
-(`msg`) => `Input`
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `Msg` |
+| `defaultDeserialize` | (`msg`: `Msg`) => `Input` |
 
 ### Returns
 
@@ -486,18 +432,15 @@ deserialize(message, defaultDeserialize): Input;
 ### serialize()
 
 ```ts
-serialize(input, defaultSerialize): Msg;
+serialize(input: Input, defaultSerialize: (inp: Input) => Msg): Msg;
 ```
 
 ### Parameters
 
-#### input
-
-`Input`
-
-#### defaultSerialize
-
-(`inp`) => `Msg`
+| Parameter | Type |
+| ------ | ------ |
+| `input` | `Input` |
+| `defaultSerialize` | (`inp`: `Input`) => `Msg` |
 
 ### Returns
 
@@ -509,35 +452,21 @@ serialize(input, defaultSerialize): Msg;
 
 ***
 
-## Type Parameters
+Descriptor wrapping a value with its associated transferable objects for zero-copy messaging.
 
-### T
+## Type Parameters
 
-`T` = `any`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `T` | `any` |
 
 ## Properties
 
-### \[$transferable\]
-
-```ts
-[$transferable]: true;
-```
-
-***
-
-### send
-
-```ts
-send: T;
-```
-
-***
-
-### transferables
-
-```ts
-transferables: Transferable[];
-```
+| Property | Type |
+| ------ | ------ |
+| <a id="transferable"></a> `[$transferable]` | `true` |
+| <a id="send"></a> `send` | `T` |
+| <a id="transferables"></a> `transferables` | `Transferable`[] |
 
   ### namespaces
 
@@ -557,9 +486,9 @@ type Event<ThreadType> = PoolEvent<ThreadType>;
 
 ## Type Parameters
 
-### ThreadType
-
-`ThreadType` *extends* [`Thread`](#../../../type-aliases/Thread) = `any`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `ThreadType` *extends* [`Thread`](#../../../type-aliases/Thread) | `any` |
 
         ### <a id="EventType"></a>EventType
 
@@ -595,11 +524,13 @@ Separate class to spawn workers from source code blobs or strings.
 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
+Maps a worker's exposed API type to its corresponding thread type (`FunctionThread` or `ModuleThread`).
 
-### Exposed
+## Type Parameters
 
-`Exposed` *extends* `WorkerFunction` \| `WorkerModule`\<`any`\>
+| Type Parameter |
+| ------ |
+| `Exposed` *extends* `WorkerFunction` \| `WorkerModule`\<`any`\> |
 
     ### <a id="FunctionThread"></a>FunctionThread
 
@@ -611,15 +542,14 @@ type ExposedAs<Exposed> = Exposed extends ArbitraryWorkerInterface ? ArbitraryTh
 type FunctionThread<Args, ReturnType> = ProxyableFunction<Args, ReturnType> & PrivateThreadProps;
 ```
 
-## Type Parameters
-
-### Args
+A thread wrapping a single exposed function.
 
-`Args` *extends* `any`[] = `any`[]
-
-### ReturnType
+## Type Parameters
 
-`ReturnType` = `any`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Args` *extends* `any`[] | `any`[] |
+| `ReturnType` | `any` |
 
     ### <a id="JsonSerializable"></a>JsonSerializable
 
@@ -635,6 +565,8 @@ type JsonSerializable =
   | JsonSerializableObject[];
 ```
 
+A JSON-compatible value that can be serialized for worker message passing.
+
     ### <a id="ModuleThread"></a>ModuleThread
 
 [**@xylabs/threads**](#../../README)
@@ -645,11 +577,13 @@ type JsonSerializable =
 type ModuleThread<Methods> = ModuleProxy<Methods> & PrivateThreadProps;
 ```
 
-## Type Parameters
+A thread wrapping an exposed module of functions.
 
-### Methods
+## Type Parameters
 
-`Methods` *extends* `ModuleMethods` = `any`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Methods` *extends* `ModuleMethods` | `any` |
 
     ### <a id="Thread"></a>Thread
 
@@ -661,7 +595,7 @@ type ModuleThread<Methods> = ModuleProxy<Methods> & PrivateThreadProps;
 type Thread = ThreadType;
 ```
 
-Thread utility functions. Use them to manage or inspect a `spawn()`-ed thread.
+Re-exported Thread type from the master types module.
 
     ### <a id="Worker"></a>Worker
 
@@ -699,6 +633,8 @@ Separate class to spawn workers from source code blobs or strings.
 const DefaultSerializer: Serializer<JsonSerializable>;
 ```
 
+Default serializer that handles Error instances and passes other values through.
+
     ### <a id="Pool"></a>Pool
 
 [**@xylabs/threads**](#../../README)
@@ -706,18 +642,18 @@ const DefaultSerializer: Serializer<JsonSerializable>;
 ***
 
 ```ts
-Pool: <ThreadType>(spawnWorker, optionsOrSize?) => WorkerPool<ThreadType> & object;
+Pool: <ThreadType>(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions) => WorkerPool<ThreadType> & {
+  EventType: typeof PoolEventType;
+};
 ```
 
 Thread pool constructor. Creates a new pool and spawns its worker threads.
 
 ## Type Declaration
 
-### EventType
-
-```ts
-EventType: typeof PoolEventType;
-```
+| Name | Type |
+| ------ | ------ |
+| `EventType` | *typeof* `PoolEventType` |
 
     ### <a id="Thread"></a>Thread
 
@@ -726,84 +662,22 @@ EventType: typeof PoolEventType;
 ***
 
 ```ts
-Thread: object;
+Thread: {
+  errors: Observable<Error>;
+  events: Observable<WorkerEvent>;
+  terminate: Promise<void>;
+};
 ```
 
 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`\>
+| Name | Type | Description |
+| ------ | ------ | ------ |
+| `errors()` | (`thread`: `ThreadT`) => `Observable`\<`Error`\> | Return an observable that can be used to subscribe to all errors happening in the thread. |
+| `events()` | (`thread`: `ThreadT`) => `Observable`\<`WorkerEvent`\> | Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging. |
+| `terminate()` | (`thread`: `ThreadT`) => `Promise`\<`void`\> | Terminate a thread. Remember to terminate every thread when you are done using it. |
 
     ### <a id="Worker"></a>Worker
 
@@ -831,10 +705,14 @@ Worker implementation. Either web worker or a node.js Worker class.
 function isWorkerRuntime(): boolean;
 ```
 
+Check whether the current code is running inside a Node.js worker thread.
+
 ## Returns
 
 `boolean`
 
+True if running in a worker thread (not the main thread), false otherwise.
+
   ### type-aliases
 
     ### <a id="BlobWorker"></a>BlobWorker