@ariestools/threads 8.0.0

package/README.md

@@ -0,0 +1,946 @@
+[![logo][]](https://xylabs.com)
+
+# @ariestools/threads
+
+[![npm][npm-badge]][npm-link]
+[![license][license-badge]][license-link]
+
+> Web workers & worker threads as simple as a function call
+
+## Install
+
+Using npm:
+
+```sh
+npm install {{name}}
+```
+
+Using yarn:
+
+```sh
+yarn add {{name}}
+```
+
+Using pnpm:
+
+```sh
+pnpm add {{name}}
+```
+
+Using bun:
+
+```sh
+bun add {{name}}
+```
+
+
+## License
+
+See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).
+
+## Reference
+
+### packages
+
+  ### threads
+
+    ### .temp-typedoc
+
+      ### index-browser
+
+        ### functions
+
+          ### <a id="Transfer"></a>Transfer
+
+[**@ariestools/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
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+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
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+function registerSerializer(serializer): void;
+```
+
+Register a custom serializer to extend the default serialization behavior for worker messages.
+
+## Parameters
+
+### serializer
+
+[`SerializerImplementation`](#../interfaces/SerializerImplementation)\<[`JsonSerializable`](#../type-aliases/JsonSerializable)\>
+
+The serializer implementation to register.
+
+## Returns
+
+`void`
+
+          ### <a id="spawn"></a>spawn
+
+[**@ariestools/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 or `worker_threads` 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
+
+[**@ariestools/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
+
+[**@ariestools/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?
+
+((`value`) => `TResult1` \| `PromiseLike`\<`TResult1`\>) \| `null`
+
+The callback to execute when the Promise is resolved.
+
+#### onrejected?
+
+((`reason`) => `TResult2` \| `PromiseLike`\<`TResult2`\>) \| `null`
+
+The callback to execute when the Promise is rejected.
+
+### 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
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+A serializer that can convert between a message format and an input type.
+
+## 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
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+A serializer implementation that receives a fallback (default) serializer for chaining.
+
+## 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
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+Descriptor wrapping a value with its associated transferable objects for zero-copy messaging.
+
+## 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
+
+[**@ariestools/threads**](#../../../../README)
+
+***
+
+```ts
+type Event<ThreadType> = PoolEvent<ThreadType>;
+```
+
+## Type Parameters
+
+### ThreadType
+
+`ThreadType` *extends* [`Thread`](#../../../type-aliases/Thread) = `any`
+
+              ### <a id="EventType"></a>EventType
+
+[**@ariestools/threads**](#../../../../README)
+
+***
+
+```ts
+type EventType = PoolEventType;
+```
+
+        ### type-aliases
+
+          ### <a id="BlobWorker"></a>BlobWorker
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+type BlobWorker = typeof BlobWorkerClass;
+```
+
+Separate class to spawn workers from source code blobs or strings.
+
+          ### <a id="ExposedAs"></a>ExposedAs
+
+[**@ariestools/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;
+```
+
+Maps a worker's exposed API type to its corresponding thread type (`FunctionThread` or `ModuleThread`).
+
+## Type Parameters
+
+### Exposed
+
+`Exposed` *extends* `WorkerFunction` \| `WorkerModule`\<`any`\>
+
+          ### <a id="FunctionThread"></a>FunctionThread
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+type FunctionThread<Args, ReturnType> = ProxyableFunction<Args, ReturnType> & PrivateThreadProps;
+```
+
+A thread wrapping a single exposed function.
+
+## Type Parameters
+
+### Args
+
+`Args` *extends* `any`[] = `any`[]
+
+### ReturnType
+
+`ReturnType` = `any`
+
+          ### <a id="JsonSerializable"></a>JsonSerializable
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+type JsonSerializable = 
+  | JsonSerializablePrimitive
+  | JsonSerializablePrimitive[]
+  | JsonSerializableObject
+  | JsonSerializableObject[];
+```
+
+A JSON-compatible value that can be serialized for worker message passing.
+
+          ### <a id="ModuleThread"></a>ModuleThread
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+type ModuleThread<Methods> = ModuleProxy<Methods> & PrivateThreadProps;
+```
+
+A thread wrapping an exposed module of functions.
+
+## Type Parameters
+
+### Methods
+
+`Methods` *extends* `ModuleMethods` = `any`
+
+          ### <a id="Thread"></a>Thread
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+type Thread = ThreadType;
+```
+
+Re-exported Thread type from the master types module.
+
+          ### <a id="Worker"></a>Worker
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+type Worker = WorkerType;
+```
+
+Worker implementation. Either web worker or a node.js Worker class.
+
+        ### variables
+
+          ### <a id="BlobWorker"></a>BlobWorker
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+BlobWorker: typeof BlobWorker;
+```
+
+Separate class to spawn workers from source code blobs or strings.
+
+          ### <a id="DefaultSerializer"></a>DefaultSerializer
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+const DefaultSerializer: Serializer<JsonSerializable>;
+```
+
+Default serializer that handles Error instances and passes other values through.
+
+          ### <a id="Pool"></a>Pool
+
+[**@ariestools/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
+
+[**@ariestools/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
+
+[**@ariestools/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
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+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
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+type BlobWorker = typeof BlobWorkerClass;
+```
+
+Separate class to spawn workers from source code blobs or strings.
+
+          ### <a id="Worker"></a>Worker
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+type Worker = WorkerType;
+```
+
+Worker implementation. Either web worker or a node.js Worker class.
+
+        ### variables
+
+          ### <a id="BlobWorker"></a>BlobWorker
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+BlobWorker: typeof BlobWorker;
+```
+
+Separate class to spawn workers from source code blobs or strings.
+
+          ### <a id="Worker"></a>Worker
+
+[**@ariestools/threads**](#../../README)
+
+***
+
+```ts
+Worker: typeof WorkerImplementation;
+```
+
+Worker implementation. Either web worker or a node.js Worker class.
+
+## Credits
+
+[Made with 🔥 and ❄️ by XY Labs](https://xylabs.com)
+
+[npm-badge]: https://img.shields.io/npm/v/@ariestools/threads.svg
+[npm-link]: https://www.npmjs.com/package/@ariestools/threads
+[license-badge]: https://img.shields.io/npm/l/@ariestools/threads.svg
+[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE
+[logo]: https://cdn.xy.company/img/brand/XYPersistentCompany_Logo_Icon_Colored.svg