@xylabs/threads

[![logo][]](https://xylabs.com)

[![main-build][]][main-build-link]
[![npm-badge][]][npm-link]
[![npm-downloads-badge][]][npm-link]
[![jsdelivr-badge][]][jsdelivr-link]
[![npm-license-badge][]](LICENSE)
[![codacy-badge][]][codacy-link]
[![codeclimate-badge][]][codeclimate-link]
[![snyk-badge][]][snyk-link]
[![socket-badge][]][socket-link]

Web workers & worker threads as simple as a function call

Reference

@xylabs/threads

*

Modules

- index-browser
- index-node

$3

### functions

### Transfer

@xylabs/threads

*

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!

$3

$3

Transferable

Array buffer, message port or similar.

$3

TransferDescriptor

$3

Call Signature

`ts
function Transfer(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!

$3

$3

T

$3

$3

T

$3

Transferable[]

$3

TransferDescriptor

$3

### isWorkerRuntime

@xylabs/threads

*

`ts
function isWorkerRuntime(): boolean;
`

Returns

boolean

### registerSerializer

@xylabs/threads

*

`ts
function registerSerializer(serializer): void;
`

Parameters

$3

SerializerImplementation\<JsonSerializable\>

Returns

void

### spawn

@xylabs/threads

*

`ts
function spawn(worker, options?): Promise>;
`

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

$3

Exposed extends WorkerFunction \| WorkerModule\<any\> = ArbitraryWorkerInterface

Parameters

$3

Worker

Instance of Worker. Either a web worker, worker_threads worker or tiny-worker worker.

$3

$3

number

Init message timeout. Default: 10000 or set by environment variable.

Returns

Promise\<ExposedAs\<Exposed\>\>

### interfaces

### Pool

@xylabs/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

$3

ThreadType extends Thread

Methods

$3

`ts
completed(allowResolvingImmediately?): Promise;
`

Returns a promise that resolves once the task queue is emptied.
Promise will be rejected if any task fails.

$3

#### allowResolvingImmediately?

boolean

Set to true to resolve immediately if task queue is currently empty.

$3

Promise\<any\>

*

$3

`ts
settled(allowResolvingImmediately?): Promise;
`

Returns a promise that resolves once the task queue is emptied.
Failing tasks will not cause the promise to be rejected.

$3

#### allowResolvingImmediately?

boolean

Set to true to resolve immediately if task queue is currently empty.

$3

Promise\<Error[]\>

*

$3

`ts
events(): Observable>;
`

Returns an observable that yields pool events.

$3

Observable\<PoolEvent\<ThreadType\>\>

*

$3

`ts
queue(task): QueuedTask;
`

Queue a task and return a promise that resolves once the task has been dequeued,
started and finished.

$3

#### Return

Return

$3

#### task

TaskRunFunction\<ThreadType, Return\>

An async function that takes a thread instance and invokes it.

$3

QueuedTask\<ThreadType, Return\>

*

$3

`ts
terminate(force?): Promise;
`

Terminate all pool threads.

$3

#### force?

boolean

Set to true to kill the thread even if it cannot be stopped gracefully.

$3

Promise\<void\>

### QueuedTask

@xylabs/threads

*

Task that has been pool.queued()-ed.

Type Parameters

$3

ThreadType extends Thread

$3

Return

Properties

$3

`ts
then: (onfulfilled?, onrejected?) => Promise;
`

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.

$3

#### TResult1

TResult1 = Return

#### TResult2

TResult2 = never

$3

#### 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\>

$3

Promise\<TResult1 \| TResult2\>

A Promise for the completion of which ever callback is executed.

Methods

$3

`ts
cancel(): void;
`

Queued tasks can be cancelled until the pool starts running them on a worker thread.

$3

void

### Serializer

@xylabs/threads

*

Type Parameters

$3

Msg = JsonSerializable

$3

Input = any

Methods

$3

`ts
deserialize(message): Input;
`

$3

#### message

Msg

$3

Input

*

$3

`ts
serialize(input): Msg;
`

$3

#### input

Input

$3

Msg

### SerializerImplementation

@xylabs/threads

*

Type Parameters

$3

Msg = JsonSerializable

$3

Input = any

Methods

$3

`ts
deserialize(message, defaultDeserialize): Input;
`

$3

#### message

Msg

#### defaultDeserialize

(msg) => Input

$3

Input

*

$3

`ts
serialize(input, defaultSerialize): Msg;
`

$3

#### input

Input

#### defaultSerialize

(inp) => Msg

$3

Msg

### TransferDescriptor

@xylabs/threads

*

Type Parameters

$3

T = any

Properties

$3

`ts
[$transferable]: true;
`

*

$3

`ts
send: T;
`

*

$3

`ts
transferables: Transferable[];
`

### namespaces

### Pool

### type-aliases

### Event

@xylabs/threads

*

`ts
type Event = PoolEvent;
`

Type Parameters

$3

ThreadType extends Thread = any

### EventType

@xylabs/threads

*

`ts
type EventType = PoolEventType;
`

### type-aliases

### BlobWorker

@xylabs/threads

*

`ts
type BlobWorker = typeof BlobWorkerClass;
`

### ExposedAs

@xylabs/threads

*

`ts
type ExposedAs = Exposed extends ArbitraryWorkerInterface ? ArbitraryThreadType : Exposed extends WorkerFunction ? FunctionThread, StripAsync>> : Exposed extends WorkerModule ? ModuleThread : never;
`

Type Parameters

$3

Exposed extends WorkerFunction \| WorkerModule\<any\>

### FunctionThread

@xylabs/threads

*

`ts
type FunctionThread = ProxyableFunction & PrivateThreadProps;
`

Type Parameters

$3

Args extends any[] = any[]

$3

ReturnType = any

### JsonSerializable

@xylabs/threads

*

`ts
type JsonSerializable =
| JsonSerializablePrimitive
| JsonSerializablePrimitive[]
| JsonSerializableObject
| JsonSerializableObject[];
`

### ModuleThread

@xylabs/threads

*

`ts
type ModuleThread = ModuleProxy & PrivateThreadProps;
`

Type Parameters

$3

Methods extends ModuleMethods = any

### Thread

@xylabs/threads

*

`ts
type Thread = ThreadType;
`

### Worker

@xylabs/threads

*

`ts
type Worker = WorkerType;
`

### variables

### BlobWorker

@xylabs/threads

*

`ts
BlobWorker: typeof BlobWorker;
`

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

### DefaultSerializer

@xylabs/threads

*

`ts
const DefaultSerializer: Serializer;
`

### Pool

@xylabs/threads

*

`ts
Pool: (spawnWorker, optionsOrSize?) => WorkerPool & object;
`

Thread pool constructor. Creates a new pool and spawns its worker threads.

Type declaration

$3

`ts
EventType: typeof PoolEventType;
`

### Thread

@xylabs/threads

*

`ts
Thread: object;
`

Thread utility functions. Use them to manage or inspect a spawn()-ed thread.

Type declaration

$3

`ts
errors(thread): Observable;
`

Return an observable that can be used to subscribe to all errors happening in the thread.

$3

#### ThreadT

ThreadT extends Thread

$3

#### thread

ThreadT

$3

Observable\<Error\>

$3

`ts
events(thread): Observable;
`

Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging.

$3

#### ThreadT

ThreadT extends Thread

$3

#### thread

ThreadT

$3

Observable\<WorkerEvent\>

$3

`ts
terminate(thread): Promise;
`

Terminate a thread. Remember to terminate every thread when you are done using it.

$3

#### ThreadT

ThreadT extends Thread

$3

#### thread

ThreadT

$3

Promise\<void\>

### Worker

@xylabs/threads

*

`ts
Worker: typeof WorkerImplementation;
`

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

$3

### functions

### isWorkerRuntime

@xylabs/threads

*

`ts
function isWorkerRuntime(): boolean;
`

Returns

boolean

### type-aliases

### BlobWorker

@xylabs/threads

*

`ts
type BlobWorker = typeof BlobWorkerClass;
`

### Worker

@xylabs/threads

*

`ts
type Worker = WorkerType;
`

### variables

### BlobWorker

@xylabs/threads

*

`ts
BlobWorker: typeof BlobWorker;
`

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

### Worker

@xylabs/threads

*

`ts
Worker: typeof WorkerImplementation;
``

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

Part of sdk-js

Maintainers

- Arie Trouw (arietrouw.com)
- Matt Jones
- Joel Carter
- Jordan Trouw

License

> See the LICENSE file for license details

Credits

Made with 🔥 and ❄️ by XYLabs

[logo]: https://cdn.xy.company/img/brand/XYPersistentCompany_Logo_Icon_Colored.svg

[main-build]: https://github.com/xylabs/sdk-js/actions/workflows/build.yml/badge.svg
[main-build-link]: https://github.com/xylabs/sdk-js/actions/workflows/build.yml
[npm-badge]: https://img.shields.io/npm/v/@xylabs/threads.svg
[npm-link]: https://www.npmjs.com/package/@xylabs/threads
[codacy-badge]: https://app.codacy.com/project/badge/Grade/c8e15e14f37741c18cfb47ac7245c698
[codacy-link]: https://www.codacy.com/gh/xylabs/sdk-js/dashboard?utm_source=github.com&utm_medium=referral&utm_content=xylabs/sdk-js&utm_campaign=Badge_Grade
[codeclimate-badge]: https://api.codeclimate.com/v1/badges/c5eb068f806f0b047ea7/maintainability
[codeclimate-link]: https://codeclimate.com/github/xylabs/sdk-js/maintainability
[snyk-badge]: https://snyk.io/test/github/xylabs/sdk-js/badge.svg?targetFile=package.json
[snyk-link]: https://snyk.io/test/github/xylabs/sdk-js?targetFile=package.json

[npm-downloads-badge]: https://img.shields.io/npm/dw/@xylabs/threads
[npm-license-badge]: https://img.shields.io/npm/l/@xylabs/threads

[jsdelivr-badge]: https://data.jsdelivr.com/v1/package/npm/@xylabs/threads/badge
[jsdelivr-link]: https://www.jsdelivr.com/package/npm/@xylabs/threads

[socket-badge]: https://socket.dev/api/badge/npm/package/@xylabs/threads
[socket-link]: https://socket.dev/npm/package/@xylabs/threads