@ariestools/threads

@ariestools/threads

Web workers & worker threads as simple as a function call

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

@ariestools/threads

---

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

TransferDescriptor

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

TransferDescriptor

See

https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast

      ### <a id="isWorkerRuntime"></a>isWorkerRuntime

@ariestools/threads

---

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

---

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

@ariestools/threads

---

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

@ariestools/threads

---

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

@ariestools/threads

---

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

@ariestools/threads

---

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

@ariestools/threads

---

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

@ariestools/threads

---

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

@ariestools/threads

---

type Event<ThreadType> = PoolEvent<ThreadType>;

Type Parameters

ThreadType

ThreadType extends Thread = any

          ### <a id="EventType"></a>EventType

@ariestools/threads

---

type EventType = PoolEventType;

    ### type-aliases

      ### <a id="BlobWorker"></a>BlobWorker

@ariestools/threads

---

type BlobWorker = typeof BlobWorkerClass;

Separate class to spawn workers from source code blobs or strings.

      ### <a id="ExposedAs"></a>ExposedAs

@ariestools/threads

---

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

---

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

---

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

---

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

---

type Thread = ThreadType;

Re-exported Thread type from the master types module.

      ### <a id="Worker"></a>Worker

@ariestools/threads

---

type Worker = WorkerType;

Worker implementation. Either web worker or a node.js Worker class.

    ### variables

      ### <a id="BlobWorker"></a>BlobWorker

@ariestools/threads

---

BlobWorker: typeof BlobWorker;

Separate class to spawn workers from source code blobs or strings.

      ### <a id="DefaultSerializer"></a>DefaultSerializer

@ariestools/threads

---

const DefaultSerializer: Serializer<JsonSerializable>;

Default serializer that handles Error instances and passes other values through.

      ### <a id="Pool"></a>Pool

@ariestools/threads

---

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

@ariestools/threads

---

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

@ariestools/threads

---

Worker: typeof WorkerImplementation;

Worker implementation. Either web worker or a node.js Worker class.

  ### index-node

    ### functions

      ### <a id="isWorkerRuntime"></a>isWorkerRuntime

@ariestools/threads

---

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

---

type BlobWorker = typeof BlobWorkerClass;

Separate class to spawn workers from source code blobs or strings.

      ### <a id="Worker"></a>Worker

@ariestools/threads

---

type Worker = WorkerType;

Worker implementation. Either web worker or a node.js Worker class.

    ### variables

      ### <a id="BlobWorker"></a>BlobWorker

@ariestools/threads

---

BlobWorker: typeof BlobWorker;

Separate class to spawn workers from source code blobs or strings.

      ### <a id="Worker"></a>Worker

@ariestools/threads

---

Worker: typeof WorkerImplementation;

Worker implementation. Either web worker or a node.js Worker class.

Credits

Made with and by XY Labs