@ariestools/threads
Web workers & worker threads as simple as a function call
Internal status: public-only package with zero consumers inside this monorepo. The
dead.package.internal/dead.repo.internalignores and coverage excludes for this package are intentional.
Install
Using npm:
npm install {{name}}
Using yarn:
yarn add {{name}}
Using pnpm:
pnpm add {{name}}
Using bun:
bun add {{name}}
License
See the LICENSE file for license rights and limitations (LGPL-3.0-only).
Reference
packages
threads
### .temp-typedoc
### index-browser
### functions
### <a id="Transfer"></a>Transfer
Call Signature
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
See
https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast
Call Signature
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
See
https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast
### <a id="isWorkerRuntime"></a>isWorkerRuntime
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
function registerSerializer(serializer): void;
Register a custom serializer to extend the default serialization behavior for worker messages.
Parameters
serializer
SerializerImplementation<JsonSerializable>
The serializer implementation to register.
Returns
void
### <a id="spawn"></a>spawn
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<Exposed>>
### interfaces
### <a id="Pool"></a>Pool
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
Methods
completed()
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()
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()
events(): Observable<PoolEvent<ThreadType>>;
Returns an observable that yields pool events.
Returns
Observable<PoolEvent<ThreadType>>
queue()
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<ThreadType, Return>
terminate()
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
Task that has been pool.queued()-ed.
Type Parameters
ThreadType
ThreadType extends Thread
Return
Return
Properties
then
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()
cancel(): void;
Queued tasks can be cancelled until the pool starts running them on a worker thread.
Returns
void
### <a id="Serializer"></a>Serializer
A serializer that can convert between a message format and an input type.
Type Parameters
Msg
Msg = JsonSerializable
Input
Input = any
Methods
deserialize()
deserialize(message): Input;
Parameters
message
Msg
Returns
Input
serialize()
serialize(input): Msg;
Parameters
input
Input
Returns
Msg
### <a id="SerializerImplementation"></a>SerializerImplementation
A serializer implementation that receives a fallback (default) serializer for chaining.
Type Parameters
Msg
Msg = JsonSerializable
Input
Input = any
Methods
deserialize()
deserialize(message, defaultDeserialize): Input;
Parameters
message
Msg
defaultDeserialize
(msg) => Input
Returns
Input
serialize()
serialize(input, defaultSerialize): Msg;
Parameters
input
Input
defaultSerialize
(inp) => Msg
Returns
Msg
### <a id="TransferDescriptor"></a>TransferDescriptor
Descriptor wrapping a value with its associated transferable objects for zero-copy messaging.
Type Parameters
T
T = any
Properties
[$transferable]
[$transferable]: true;
send
send: T;
transferables
transferables: Transferable[];
### namespaces
### Pool
### type-aliases
### <a id="Event"></a>Event
type Event<ThreadType> = PoolEvent<ThreadType>;
Type Parameters
ThreadType
ThreadType extends Thread = any
### <a id="EventType"></a>EventType
type EventType = PoolEventType;
### type-aliases
### <a id="BlobWorker"></a>BlobWorker
type BlobWorker = typeof BlobWorkerClass;
Separate class to spawn workers from source code blobs or strings.
### <a id="ExposedAs"></a>ExposedAs
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
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
type JsonSerializable =
| JsonSerializablePrimitive
| JsonSerializablePrimitive[]
| JsonSerializableObject
| JsonSerializableObject[];
A JSON-compatible value that can be serialized for worker message passing.
### <a id="ModuleThread"></a>ModuleThread
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
type Thread = ThreadType;
Re-exported Thread type from the master types module.
### <a id="Worker"></a>Worker
type Worker = WorkerType;
Worker implementation. Either web worker or a node.js Worker class.
### variables
### <a id="BlobWorker"></a>BlobWorker
BlobWorker: typeof BlobWorker;
Separate class to spawn workers from source code blobs or strings.
### <a id="DefaultSerializer"></a>DefaultSerializer
const DefaultSerializer: Serializer<JsonSerializable>;
Default serializer that handles Error instances and passes other values through.
### <a id="Pool"></a>Pool
Pool: <ThreadType>(spawnWorker, optionsOrSize?) => WorkerPool<ThreadType> & object;
Thread pool constructor. Creates a new pool and spawns its worker threads.
Type Declaration
EventType
EventType: typeof PoolEventType;
### <a id="Thread"></a>Thread
Thread: object;
Thread utility functions. Use them to manage or inspect a spawn()-ed thread.
Type Declaration
errors()
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()
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()
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
Worker: typeof WorkerImplementation;
Worker implementation. Either web worker or a node.js Worker class.
### index-node
### functions
### <a id="isWorkerRuntime"></a>isWorkerRuntime
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
type BlobWorker = typeof BlobWorkerClass;
Separate class to spawn workers from source code blobs or strings.
### <a id="Worker"></a>Worker
type Worker = WorkerType;
Worker implementation. Either web worker or a node.js Worker class.
### variables
### <a id="BlobWorker"></a>BlobWorker
BlobWorker: typeof BlobWorker;
Separate class to spawn workers from source code blobs or strings.
### <a id="Worker"></a>Worker
Worker: typeof WorkerImplementation;
Worker implementation. Either web worker or a node.js Worker class.