@xylabs/threads
Advanced tools
Web workers & worker threads as simple as a function call
Using npm:
npm install {{name}}
Using yarn:
yarn add {{name}}
Using pnpm:
pnpm add {{name}}
Using bun:
bun add {{name}}
See the LICENSE file for license rights and limitations (LGPL-3.0-only).
### .temp-typedoc
### index-browser
### functions
### <a id="Transfer"></a>Transfer
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!
Transferable
Array buffer, message port or similar.
https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast
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!
T
T
Transferable[]
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.
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.
SerializerImplementation<JsonSerializable>
The serializer implementation to register.
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.
Exposed extends WorkerFunction | WorkerModule<any> = ArbitraryWorkerInterface
Worker
Instance of Worker. Either a web worker or worker_threads worker.
number
Init message timeout. Default: 10000 or set by environment variable.
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.
ThreadType extends Thread
completed(allowResolvingImmediately?): Promise<any>;
Returns a promise that resolves once the task queue is emptied. Promise will be rejected if any task fails.
boolean
Set to true to resolve immediately if task queue is currently empty.
Promise<any>
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.
boolean
Set to true to resolve immediately if task queue is currently empty.
Promise<Error[]>
events(): Observable<PoolEvent<ThreadType>>;
Returns an observable that yields pool events.
Observable<PoolEvent<ThreadType>>
queue<Return>(task): QueuedTask<ThreadType, Return>;
Queue a task and return a promise that resolves once the task has been dequeued, started and finished.
Return
TaskRunFunction<ThreadType, Return>
An async function that takes a thread instance and invokes it.
QueuedTask<ThreadType, Return>
terminate(force?): Promise<void>;
Terminate all pool threads.
boolean
Set to true to kill the thread even if it cannot be stopped gracefully.
Promise<void>
### <a id="QueuedTask"></a>QueuedTask
Task that has been pool.queued()-ed.
ThreadType extends Thread
Return
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.
TResult1 = Return
TResult2 = never
((value) => TResult1 | PromiseLike<TResult1>) | null
The callback to execute when the Promise is resolved.
((reason) => TResult2 | PromiseLike<TResult2>) | null
The callback to execute when the Promise is rejected.
Promise<TResult1 | TResult2>
A Promise for the completion of which ever callback is executed.
cancel(): void;
Queued tasks can be cancelled until the pool starts running them on a worker thread.
void
### <a id="Serializer"></a>Serializer
A serializer that can convert between a message format and an input type.
Msg = JsonSerializable
Input = any
deserialize(message): Input;
Msg
Input
serialize(input): Msg;
Input
Msg
### <a id="SerializerImplementation"></a>SerializerImplementation
A serializer implementation that receives a fallback (default) serializer for chaining.
Msg = JsonSerializable
Input = any
deserialize(message, defaultDeserialize): Input;
Msg
(msg) => Input
Input
serialize(input, defaultSerialize): Msg;
Input
(inp) => Msg
Msg
### <a id="TransferDescriptor"></a>TransferDescriptor
Descriptor wrapping a value with its associated transferable objects for zero-copy messaging.
T = any
[$transferable]: true;
send: T;
transferables: Transferable[];
### namespaces
### Pool
### type-aliases
### <a id="Event"></a>Event
type Event<ThreadType> = PoolEvent<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).
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.
Args extends any[] = any[]
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.
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.
EventType: typeof PoolEventType;
### <a id="Thread"></a>Thread
Thread: object;
Thread utility functions. Use them to manage or inspect a spawn()-ed thread.
errors<ThreadT>(thread): Observable<Error>;
Return an observable that can be used to subscribe to all errors happening in the thread.
ThreadT extends Thread
ThreadT
Observable<Error>
events<ThreadT>(thread): Observable<WorkerEvent>;
Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging.
ThreadT extends Thread
ThreadT
Observable<WorkerEvent>
terminate<ThreadT>(thread): Promise<void>;
Terminate a thread. Remember to terminate every thread when you are done using it.
ThreadT extends Thread
ThreadT
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.
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.
FAQs
Web workers & worker threads as simple as a function call
The npm package @xylabs/threads receives a total of 4,777 weekly downloads. As such, @xylabs/threads popularity was classified as popular.
We found that @xylabs/threads demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Docker and Socket have uncovered malicious Checkmarx KICS images and suspicious code extension releases in a broader supply chain compromise.
Product
Stay on top of alert changes with filtered subscriptions, batched summaries, and notification routing built for triage.
Research
Malicious Namastex.ai npm packages appear to replicate TeamPCP-style Canister Worm tradecraft, including exfiltration and self-propagation.