@xylabs/threads/README.md

Web workers & worker threads as simple as a function call

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

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

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

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

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

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

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

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

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

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

[**@xylabs/threads**](#../../../../README)

***

```ts
type Event<ThreadType> = PoolEvent<ThreadType>;
```

## Type Parameters

### ThreadType

`ThreadType` *extends* [`Thread`](#../../../type-aliases/Thread) = `any`

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

[**@xylabs/threads**](#../../../../README)

***

```ts
type EventType = PoolEventType;
```

        ### type-aliases

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

[**@xylabs/threads**](#../../README)

***

```ts
type BlobWorker = typeof BlobWorkerClass;
```

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

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

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

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

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

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

[**@xylabs/threads**](#../../README)

***

```ts
type Thread = ThreadType;
```

Re-exported Thread type from the master types module.

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

[**@xylabs/threads**](#../../README)

***

```ts
type Worker = WorkerType;
```

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

        ### variables

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

[**@xylabs/threads**](#../../README)

***

```ts
BlobWorker: typeof BlobWorker;
```

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

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

[**@xylabs/threads**](#../../README)

***

```ts
const DefaultSerializer: Serializer<JsonSerializable>;
```

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

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

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

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

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

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

[**@xylabs/threads**](#../../README)

***

```ts
type BlobWorker = typeof BlobWorkerClass;
```

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

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

[**@xylabs/threads**](#../../README)

***

```ts
type Worker = WorkerType;
```

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

        ### variables

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

[**@xylabs/threads**](#../../README)

***

```ts
BlobWorker: typeof BlobWorker;
```

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

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

[**@xylabs/threads**](#../../README)

***

```ts
Worker: typeof WorkerImplementation;
```

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


[npm-badge]: https://img.shields.io/npm/v/@xylabs/threads.svg
[npm-link]: https://www.npmjs.com/package/@xylabs/threads
[license-badge]: https://img.shields.io/npm/l/@xylabs/threads.svg
[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE