@xylabs/threads 4.13.4 → 4.13.6

package/dist/browser/{index-browser-B8TCfn7g.d.ts → index-browser-C-9qksMi.d.ts}

@@ -1,4 +1,4 @@
-import { F as FunctionThread, M as ModuleThread, S as StripAsync, W as Worker$1, B as BlobWorker$1, a as WorkerImplementation } from './master-D4MAqspp.js';
+import { F as FunctionThread, M as ModuleThread, S as StripAsync, W as Worker$1, B as BlobWorker$1, a as WorkerImplementation } from './master-C8XAGDqb.js';
 import './master/pool-browser.js';
 import { W as WorkerFunction, a as WorkerModule } from './worker-04t9iwDh.js';
 import './master/implementation.browser.js';
@@ -8,13 +8,24 @@ type ArbitraryWorkerInterface = WorkerFunction & WorkerModule<string> & {
 };
 type ArbitraryThreadType = FunctionThread<any, any> & ModuleThread<any>;
 type ExposedToThreadType<Exposed extends WorkerFunction | WorkerModule<any>> = Exposed extends ArbitraryWorkerInterface ? ArbitraryThreadType : Exposed extends WorkerFunction ? FunctionThread<Parameters<Exposed>, StripAsync<ReturnType<Exposed>>> : Exposed extends WorkerModule<any> ? ModuleThread<Exposed> : never;
+/**
+ * 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.
+ *
+ * @param worker Instance of `Worker`. Either a web worker, `worker_threads` worker or `tiny-worker` worker.
+ * @param [options]
+ * @param [options.timeout] Init message timeout. Default: 10000 or set by environment variable.
+ */
 declare function spawn<Exposed extends WorkerFunction | WorkerModule<any> = ArbitraryWorkerInterface>(worker: Worker$1, options?: {
     timeout?: number;
 }): Promise<ExposedToThreadType<Exposed>>;
 
 type BlobWorker = typeof BlobWorker$1;
+/** Separate class to spawn workers from source code blobs or strings. */
 declare const BlobWorker: typeof BlobWorker$1;
 type Worker = Worker$1;
+/** Worker implementation. Either web worker or a node.js Worker class. */
 declare const Worker: typeof WorkerImplementation;
 
 export { BlobWorker as B, type ExposedToThreadType as E, Worker as W, spawn as s };

package/dist/browser/index-browser.d.ts

@@ -1,8 +1,8 @@
 export { D as DefaultSerializer, J as JsonSerializable, S as Serializer, a as SerializerImplementation, r as registerSerializer } from './common-Cuiya5FG.js';
-export { B as BlobWorker, E as ExposedAs, W as Worker, s as spawn } from './index-browser-B8TCfn7g.js';
+export { B as BlobWorker, E as ExposedAs, W as Worker, s as spawn } from './index-browser-C-9qksMi.js';
 export { Pool, QueuedTask, Thread } from './master/pool-browser.js';
-export { a as Transfer, T as TransferDescriptor } from './transferable-Cv9t618f.js';
-export { F as FunctionThread, M as ModuleThread } from './master-D4MAqspp.js';
+export { a as Transfer, T as TransferDescriptor } from './transferable-Blu_CzPT.js';
+export { F as FunctionThread, M as ModuleThread } from './master-C8XAGDqb.js';
 export { isWorkerRuntime } from './master/implementation.browser.js';
 import './worker-04t9iwDh.js';
 import 'observable-fns';

package/dist/browser/master/implementation.browser.d.ts

@@ -1,6 +1,6 @@
-import { I as ImplementationExport } from '../master-D4MAqspp.js';
+import { I as ImplementationExport } from '../master-C8XAGDqb.js';
 import 'observable-fns';
-import '../transferable-Cv9t618f.js';
+import '../transferable-Blu_CzPT.js';
 
 declare const defaultPoolSize: number;
 declare function getWorkerImplementation(): ImplementationExport;

package/dist/browser/master/index-browser.d.ts

@@ -1,7 +1,7 @@
-export { F as FunctionThread, M as ModuleThread } from '../master-D4MAqspp.js';
+export { F as FunctionThread, M as ModuleThread } from '../master-C8XAGDqb.js';
 export { Pool, Thread } from './pool-browser.js';
-export { B as BlobWorker, W as Worker, s as spawn } from '../index-browser-B8TCfn7g.js';
+export { B as BlobWorker, W as Worker, s as spawn } from '../index-browser-C-9qksMi.js';
 export { isWorkerRuntime } from './implementation.browser.js';
 import 'observable-fns';
-import '../transferable-Cv9t618f.js';
+import '../transferable-Blu_CzPT.js';
 import '../worker-04t9iwDh.js';

package/dist/browser/master/pool-browser.d.ts

@@ -1,14 +1,19 @@
 import { Observable } from 'observable-fns';
-import { T as Thread$1, b as WorkerEvent } from '../master-D4MAqspp.js';
-import '../transferable-Cv9t618f.js';
+import { T as Thread$1, b as WorkerEvent } from '../master-C8XAGDqb.js';
+import '../transferable-Blu_CzPT.js';
 
 type Thread = Thread$1;
+/** Thread utility functions. Use them to manage or inspect a `spawn()`-ed thread. */
 declare const Thread: {
+    /** Return an observable that can be used to subscribe to all errors happening in the thread. */
     errors<ThreadT extends Thread$1>(thread: ThreadT): Observable<Error>;
+    /** Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging. */
     events<ThreadT extends Thread$1>(thread: ThreadT): Observable<WorkerEvent>;
+    /** Terminate a thread. Remember to terminate every thread when you are done using it. */
     terminate<ThreadT extends Thread$1>(thread: ThreadT): Promise<void>;
 };
 
+/** Pool event type. Specifies the type of each `PoolEvent`. */
 declare enum PoolEventType {
     initialized = "initialized",
     taskCanceled = "taskCanceled",
@@ -20,6 +25,7 @@ declare enum PoolEventType {
     terminated = "terminated"
 }
 type TaskRunFunction<ThreadType extends Thread, Return> = (worker: ThreadType) => Promise<Return>;
+/** Pool event. Subscribe to those events using `pool.events()`. Useful for debugging. */
 type PoolEvent<ThreadType extends Thread> = {
     type: PoolEventType.initialized;
     size: number;
@@ -49,17 +55,33 @@ type PoolEvent<ThreadType extends Thread> = {
     type: PoolEventType.terminated;
     remainingQueue: Array<QueuedTask<ThreadType, any>>;
 };
+/**
+ * Task that has been `pool.queued()`-ed.
+ */
 interface QueuedTask<ThreadType extends Thread, Return> {
+    /** @private */
     id: number;
+    /** @private */
     run: TaskRunFunction<ThreadType, Return>;
+    /**
+     * Queued tasks can be cancelled until the pool starts running them on a worker thread.
+     */
     cancel(): void;
+    /**
+     * `QueuedTask` is thenable, so you can `await` it.
+     * Resolves when the task has successfully been executed. Rejects if the task fails.
+     */
     then: Promise<Return>['then'];
 }
 
 interface PoolOptions {
+    /** Maximum no. of tasks to run on one worker thread at a time. Defaults to one. */
     concurrency?: number;
+    /** Maximum no. of jobs to be queued for execution before throwing an error. */
     maxQueuedJobs?: number;
+    /** Gives that pool a name to be used for debug logging, letting you distinguish between log output of different pools. */
     name?: string;
+    /** No. of worker threads to spawn and to be managed by the pool. */
     size?: number;
 }
 declare class WorkerPool<ThreadType extends Thread> implements Pool<ThreadType> {
@@ -85,18 +107,55 @@ declare class WorkerPool<ThreadType extends Thread> implements Pool<ThreadType>
     queue(taskFunction: TaskRunFunction<ThreadType, any>): QueuedTask<ThreadType, any>;
     terminate(force?: boolean): Promise<void>;
 }
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
 declare function PoolConstructor<ThreadType extends Thread>(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions): WorkerPool<ThreadType>;
 declare namespace Pool {
     type Event<ThreadType extends Thread = any> = PoolEvent<ThreadType>;
     type EventType = PoolEventType;
 }
+/**
+ * Thread pool managing a set of worker threads.
+ * Use it to queue tasks that are run on those threads with limited
+ * concurrency.
+ */
 interface Pool<ThreadType extends Thread> {
+    /**
+     * Returns a promise that resolves once the task queue is emptied.
+     * Promise will be rejected if any task fails.
+     *
+     * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
+     */
     completed(allowResolvingImmediately?: boolean): Promise<any>;
+    /**
+     * Returns a promise that resolves once the task queue is emptied.
+     * Failing tasks will not cause the promise to be rejected.
+     *
+     * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
+     */
     settled(allowResolvingImmediately?: boolean): Promise<Error[]>;
+    /**
+     * Returns an observable that yields pool events.
+     */
     events(): Observable<PoolEvent<ThreadType>>;
+    /**
+     * Queue a task and return a promise that resolves once the task has been dequeued,
+     * started and finished.
+     *
+     * @param task An async function that takes a thread instance and invokes it.
+     */
     queue<Return>(task: TaskRunFunction<ThreadType, Return>): QueuedTask<ThreadType, Return>;
+    /**
+     * Terminate all pool threads.
+     *
+     * @param force Set to `true` to kill the thread even if it cannot be stopped gracefully.
+     */
     terminate(force?: boolean): Promise<void>;
 }
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
 declare const Pool: typeof PoolConstructor & {
     EventType: typeof PoolEventType;
 };

package/dist/browser/{master-D4MAqspp.d.ts → master-C8XAGDqb.d.ts}

@@ -1,11 +1,24 @@
 import { Observable, SubscriptionObserver, ObservableLike as ObservableLike$1 } from 'observable-fns';
-import { $ as $errors, b as $events, c as $terminate, d as $worker, T as TransferDescriptor } from './transferable-Cv9t618f.js';
+import { $ as $errors, b as $events, c as $terminate, d as $worker, T as TransferDescriptor } from './transferable-Blu_CzPT.js';
 
 type Initializer<T> = (observer: SubscriptionObserver<T>) => UnsubscribeFn | void;
 type Thenable<T> = {
     then: (onFulfilled?: (value: T) => any, onRejected?: (error: any) => any) => any;
 };
 type UnsubscribeFn = () => void;
+/**
+ * Creates a hybrid, combining the APIs of an Observable and a Promise.
+ *
+ * It is used to proxy async process states when we are initially not sure
+ * if that async process will yield values once (-> Promise) or multiple
+ * times (-> Observable).
+ *
+ * Note that the observable promise inherits some of the observable's characteristics:
+ * The `init` function will be called *once for every time anyone subscribes to it*.
+ *
+ * If this is undesired, derive a hot observable from it using `makeHot()` and
+ * subscribe to that.
+ */
 declare class ObservablePromise<T> extends Observable<T> implements Promise<T> {
     readonly [Symbol.toStringTag] = "[object ObservablePromise]";
     private initHasRun;
@@ -59,27 +72,39 @@ interface AnyFunctionThread extends PrivateThreadProps {
 }
 interface AnyModuleThread extends PrivateThreadProps {
 }
+/** Worker thread. Either a `FunctionThread` or a `ModuleThread`. */
 type Thread = AnyFunctionThread | AnyModuleThread;
 type TransferList = Transferable[];
+/** Worker instance. Either a web worker or a node.js Worker provided by `worker_threads` or `tiny-worker`. */
 interface Worker extends EventTarget {
     postMessage(value: any, transferList?: TransferList): void;
+    /** In nodejs 10+ return type is Promise while with tiny-worker and in browser return type is void */
     terminate(callback?: (error?: Error, exitCode?: number) => void): void | Promise<number>;
 }
 interface ThreadsWorkerOptions extends WorkerOptions {
+    /** Whether to apply CORS protection workaround. Defaults to true. */
     CORSWorkaround?: boolean;
+    /** Prefix for the path passed to the Worker constructor. Web worker only. */
     _baseURL?: string;
+    /** Resource limits passed on to Node worker_threads */
     resourceLimits?: {
+        /** The size of a pre-allocated memory range used for generated code. */
         codeRangeSizeMb?: number;
+        /** The maximum size of the main heap in MB. */
         maxOldGenerationSizeMb?: number;
+        /** The maximum size of a heap space for recently created objects. */
         maxYoungGenerationSizeMb?: number;
     };
+    /** Data passed on to node.js worker_threads. */
     workerData?: any;
 }
+/** Worker implementation. Either web worker or a node.js Worker class. */
 declare class WorkerImplementation extends EventTarget implements Worker {
     constructor(path: string, options?: ThreadsWorkerOptions);
     postMessage(value: any, transferList?: TransferList): void;
     terminate(): void | Promise<number>;
 }
+/** Class to spawn workers from a blob or source string. */
 declare class BlobWorker extends WorkerImplementation {
     constructor(blob: Blob, options?: ThreadsWorkerOptions);
     static fromText(source: string, options?: ThreadsWorkerOptions): WorkerImplementation;
@@ -88,6 +113,7 @@ interface ImplementationExport {
     blob: typeof BlobWorker;
     default: typeof WorkerImplementation;
 }
+/** Event as emitted by worker thread. Subscribe to using `Thread.events(thread)`. */
 declare enum WorkerEventType {
     internalError = "internalError",
     message = "message",

package/dist/browser/transferable-Blu_CzPT.d.ts

@@ -0,0 +1,48 @@
+declare const $errors: unique symbol;
+declare const $events: unique symbol;
+declare const $terminate: unique symbol;
+declare const $transferable: unique symbol;
+declare const $worker: unique symbol;
+
+interface TransferDescriptor<T = any> {
+    [$transferable]: true;
+    send: T;
+    transferables: Transferable[];
+}
+/**
+ * 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!
+ *
+ * @param transferable Array buffer, message port or similar.
+ * @see <https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast>
+ */
+declare function Transfer(transferable: Transferable): 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!
+ *
+ * @param transferable Array buffer, message port or similar.
+ * @see <https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast>
+ */
+declare function Transfer<T>(payload: T, transferables: Transferable[]): TransferDescriptor;
+
+export { $errors as $, type TransferDescriptor as T, Transfer as a, $events as b, $terminate as c, $worker as d };

package/dist/browser/worker/worker.browser.d.ts

@@ -1,6 +1,6 @@
 import { A as AbstractedWorkerAPI, W as WorkerFunction, a as WorkerModule } from '../worker-04t9iwDh.js';
 export { r as registerSerializer } from '../common-Cuiya5FG.js';
-export { a as Transfer } from '../transferable-Cv9t618f.js';
+export { a as Transfer } from '../transferable-Blu_CzPT.js';
 
 declare const isWorkerRuntime: AbstractedWorkerAPI['isWorkerRuntime'];
 declare const postMessageToMaster: AbstractedWorkerAPI['postMessageToMaster'];

package/dist/neutral/master/spawn.d.ts

@@ -1,4 +1,4 @@
-import { F as FunctionThread, M as ModuleThread, S as StripAsync, a as Worker } from '../master-DDdg1BKb.js';
+import { F as FunctionThread, M as ModuleThread, S as StripAsync, a as Worker } from '../master-zgnSDvrP.js';
 import 'observable-fns';
 import '../observable-promise.js';
 
@@ -12,6 +12,15 @@ type ArbitraryWorkerInterface = WorkerFunction & WorkerModule<string> & {
 };
 type ArbitraryThreadType = FunctionThread<any, any> & ModuleThread<any>;
 type ExposedToThreadType<Exposed extends WorkerFunction | WorkerModule<any>> = Exposed extends ArbitraryWorkerInterface ? ArbitraryThreadType : Exposed extends WorkerFunction ? FunctionThread<Parameters<Exposed>, StripAsync<ReturnType<Exposed>>> : Exposed extends WorkerModule<any> ? ModuleThread<Exposed> : never;
+/**
+ * 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.
+ *
+ * @param worker Instance of `Worker`. Either a web worker, `worker_threads` worker or `tiny-worker` worker.
+ * @param [options]
+ * @param [options.timeout] Init message timeout. Default: 10000 or set by environment variable.
+ */
 declare function spawn<Exposed extends WorkerFunction | WorkerModule<any> = ArbitraryWorkerInterface>(worker: Worker, options?: {
     timeout?: number;
 }): Promise<ExposedToThreadType<Exposed>>;

package/dist/neutral/master/thread.d.ts

@@ -1,11 +1,15 @@
 import { Observable } from 'observable-fns';
-import { T as Thread$1, W as WorkerEvent } from '../master-DDdg1BKb.js';
+import { T as Thread$1, W as WorkerEvent } from '../master-zgnSDvrP.js';
 import '../observable-promise.js';
 
 type Thread = Thread$1;
+/** Thread utility functions. Use them to manage or inspect a `spawn()`-ed thread. */
 declare const Thread: {
+    /** Return an observable that can be used to subscribe to all errors happening in the thread. */
     errors<ThreadT extends Thread$1>(thread: ThreadT): Observable<Error>;
+    /** Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging. */
     events<ThreadT extends Thread$1>(thread: ThreadT): Observable<WorkerEvent>;
+    /** Terminate a thread. Remember to terminate every thread when you are done using it. */
     terminate<ThreadT extends Thread$1>(thread: ThreadT): Promise<void>;
 };
 

package/dist/neutral/{master-DDdg1BKb.d.ts → master-zgnSDvrP.d.ts}

@@ -47,12 +47,16 @@ interface AnyFunctionThread extends PrivateThreadProps {
 }
 interface AnyModuleThread extends PrivateThreadProps {
 }
+/** Worker thread. Either a `FunctionThread` or a `ModuleThread`. */
 type Thread = AnyFunctionThread | AnyModuleThread;
 type TransferList = Transferable[];
+/** Worker instance. Either a web worker or a node.js Worker provided by `worker_threads` or `tiny-worker`. */
 interface Worker extends EventTarget {
     postMessage(value: any, transferList?: TransferList): void;
+    /** In nodejs 10+ return type is Promise while with tiny-worker and in browser return type is void */
     terminate(callback?: (error?: Error, exitCode?: number) => void): void | Promise<number>;
 }
+/** Event as emitted by worker thread. Subscribe to using `Thread.events(thread)`. */
 declare enum WorkerEventType {
     internalError = "internalError",
     message = "message",

package/dist/neutral/observable-promise.d.ts

@@ -5,6 +5,19 @@ type Thenable<T> = {
     then: (onFulfilled?: (value: T) => any, onRejected?: (error: any) => any) => any;
 };
 type UnsubscribeFn = () => void;
+/**
+ * Creates a hybrid, combining the APIs of an Observable and a Promise.
+ *
+ * It is used to proxy async process states when we are initially not sure
+ * if that async process will yield values once (-> Promise) or multiple
+ * times (-> Observable).
+ *
+ * Note that the observable promise inherits some of the observable's characteristics:
+ * The `init` function will be called *once for every time anyone subscribes to it*.
+ *
+ * If this is undesired, derive a hot observable from it using `makeHot()` and
+ * subscribe to that.
+ */
 declare class ObservablePromise<T> extends Observable<T> implements Promise<T> {
     readonly [Symbol.toStringTag] = "[object ObservablePromise]";
     private initHasRun;

package/dist/neutral/observable.d.ts

@@ -2,6 +2,15 @@ import { Observable, ObservableLike } from 'observable-fns';
 export { Observable } from 'observable-fns';
 
 declare const $observers: unique symbol;
+/**
+ * Observable subject. Implements the Observable interface, but also exposes
+ * the `next()`, `error()`, `complete()` methods to initiate observable
+ * updates "from the outside".
+ *
+ * Use `Observable.from(subject)` to derive an observable that proxies all
+ * values, errors and the completion raised on this subject, but does not
+ * expose the `next()`, `error()`, `complete()` methods.
+ */
 declare class Subject<T> extends Observable<T> implements ObservableLike<T> {
     private [$observers];
     constructor();

package/dist/node/{index-node-DB1sNl0d.d.ts → index-node-COoRYkbY.d.ts}

@@ -1,13 +1,17 @@
-import { F as FunctionThread, M as ModuleThread, S as StripAsync, a as Worker$1, B as BlobWorker$1, b as WorkerImplementation } from './master-BjjSaJAj.js';
+import { F as FunctionThread, M as ModuleThread, S as StripAsync, a as Worker$1, B as BlobWorker$1, b as WorkerImplementation } from './master-DBU-F6eB.js';
 import { Observable } from 'observable-fns';
-import { T as Thread, P as PoolEvent, a as PoolEventType, b as TaskRunFunction, Q as QueuedTask } from './pool-types-Bzei07Nj.js';
+import { T as Thread, P as PoolEvent, a as PoolEventType, b as TaskRunFunction, Q as QueuedTask } from './pool-types-BnrcRDgC.js';
 import { W as WorkerFunction, a as WorkerModule } from './worker-04t9iwDh.js';
 import './master/implementation.node.js';
 
 interface PoolOptions {
+    /** Maximum no. of tasks to run on one worker thread at a time. Defaults to one. */
     concurrency?: number;
+    /** Maximum no. of jobs to be queued for execution before throwing an error. */
     maxQueuedJobs?: number;
+    /** Gives that pool a name to be used for debug logging, letting you distinguish between log output of different pools. */
     name?: string;
+    /** No. of worker threads to spawn and to be managed by the pool. */
     size?: number;
 }
 declare class WorkerPool<ThreadType extends Thread> implements Pool<ThreadType> {
@@ -33,18 +37,55 @@ declare class WorkerPool<ThreadType extends Thread> implements Pool<ThreadType>
     queue(taskFunction: TaskRunFunction<ThreadType, any>): QueuedTask<ThreadType, any>;
     terminate(force?: boolean): Promise<void>;
 }
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
 declare function PoolConstructor<ThreadType extends Thread>(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions): WorkerPool<ThreadType>;
 declare namespace Pool {
     type Event<ThreadType extends Thread = any> = PoolEvent<ThreadType>;
     type EventType = PoolEventType;
 }
+/**
+ * Thread pool managing a set of worker threads.
+ * Use it to queue tasks that are run on those threads with limited
+ * concurrency.
+ */
 interface Pool<ThreadType extends Thread> {
+    /**
+     * Returns a promise that resolves once the task queue is emptied.
+     * Promise will be rejected if any task fails.
+     *
+     * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
+     */
     completed(allowResolvingImmediately?: boolean): Promise<any>;
+    /**
+     * Returns a promise that resolves once the task queue is emptied.
+     * Failing tasks will not cause the promise to be rejected.
+     *
+     * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
+     */
     settled(allowResolvingImmediately?: boolean): Promise<Error[]>;
+    /**
+     * Returns an observable that yields pool events.
+     */
     events(): Observable<PoolEvent<ThreadType>>;
+    /**
+     * Queue a task and return a promise that resolves once the task has been dequeued,
+     * started and finished.
+     *
+     * @param task An async function that takes a thread instance and invokes it.
+     */
     queue<Return>(task: TaskRunFunction<ThreadType, Return>): QueuedTask<ThreadType, Return>;
+    /**
+     * Terminate all pool threads.
+     *
+     * @param force Set to `true` to kill the thread even if it cannot be stopped gracefully.
+     */
     terminate(force?: boolean): Promise<void>;
 }
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
 declare const Pool: typeof PoolConstructor & {
     EventType: typeof PoolEventType;
 };
@@ -54,13 +95,24 @@ type ArbitraryWorkerInterface = WorkerFunction & WorkerModule<string> & {
 };
 type ArbitraryThreadType = FunctionThread<any, any> & ModuleThread<any>;
 type ExposedToThreadType<Exposed extends WorkerFunction | WorkerModule<any>> = Exposed extends ArbitraryWorkerInterface ? ArbitraryThreadType : Exposed extends WorkerFunction ? FunctionThread<Parameters<Exposed>, StripAsync<ReturnType<Exposed>>> : Exposed extends WorkerModule<any> ? ModuleThread<Exposed> : never;
+/**
+ * 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.
+ *
+ * @param worker Instance of `Worker`. Either a web worker, `worker_threads` worker or `tiny-worker` worker.
+ * @param [options]
+ * @param [options.timeout] Init message timeout. Default: 10000 or set by environment variable.
+ */
 declare function spawn<Exposed extends WorkerFunction | WorkerModule<any> = ArbitraryWorkerInterface>(worker: Worker$1, options?: {
     timeout?: number;
 }): Promise<ExposedToThreadType<Exposed>>;
 
 type BlobWorker = typeof BlobWorker$1;
+/** Separate class to spawn workers from source code blobs or strings. */
 declare const BlobWorker: typeof BlobWorker$1;
 type Worker = Worker$1;
+/** Worker implementation. Either web worker or a node.js Worker class. */
 declare const Worker: typeof WorkerImplementation;
 
 export { BlobWorker as B, type ExposedToThreadType as E, Pool as P, Worker as W, spawn as s };

package/dist/node/index-node.d.ts

@@ -1,8 +1,8 @@
 export { D as DefaultSerializer, J as JsonSerializable, S as Serializer, a as SerializerImplementation, r as registerSerializer } from './common-Cuiya5FG.js';
-export { B as BlobWorker, E as ExposedAs, P as Pool, W as Worker, s as spawn } from './index-node-DB1sNl0d.js';
-export { Q as QueuedTask, T as Thread } from './pool-types-Bzei07Nj.js';
-export { a as Transfer, T as TransferDescriptor } from './transferable-Cv9t618f.js';
-export { F as FunctionThread, M as ModuleThread } from './master-BjjSaJAj.js';
+export { B as BlobWorker, E as ExposedAs, P as Pool, W as Worker, s as spawn } from './index-node-COoRYkbY.js';
+export { Q as QueuedTask, T as Thread } from './pool-types-BnrcRDgC.js';
+export { a as Transfer, T as TransferDescriptor } from './transferable-Blu_CzPT.js';
+export { F as FunctionThread, M as ModuleThread } from './master-DBU-F6eB.js';
 export { isWorkerRuntime } from './master/implementation.node.js';
 import 'observable-fns';
 import './worker-04t9iwDh.js';

package/dist/node/master/implementation.node.d.ts

@@ -1,6 +1,6 @@
-import { I as ImplementationExport } from '../master-BjjSaJAj.js';
+import { I as ImplementationExport } from '../master-DBU-F6eB.js';
 import 'observable-fns';
-import '../transferable-Cv9t618f.js';
+import '../transferable-Blu_CzPT.js';
 
 declare const defaultPoolSize: number;
 declare function getWorkerImplementation(): ImplementationExport;

package/dist/node/master/index-node.d.ts

@@ -1,7 +1,7 @@
-export { F as FunctionThread, M as ModuleThread } from '../master-BjjSaJAj.js';
-export { B as BlobWorker, P as Pool, W as Worker, s as spawn } from '../index-node-DB1sNl0d.js';
-export { T as Thread } from '../pool-types-Bzei07Nj.js';
+export { F as FunctionThread, M as ModuleThread } from '../master-DBU-F6eB.js';
+export { B as BlobWorker, P as Pool, W as Worker, s as spawn } from '../index-node-COoRYkbY.js';
+export { T as Thread } from '../pool-types-BnrcRDgC.js';
 export { isWorkerRuntime } from './implementation.node.js';
 import 'observable-fns';
-import '../transferable-Cv9t618f.js';
+import '../transferable-Blu_CzPT.js';
 import '../worker-04t9iwDh.js';

package/dist/node/master/pool-node.d.ts

@@ -1,12 +1,16 @@
 import { Observable } from 'observable-fns';
-import { T as Thread, P as PoolEvent, a as PoolEventType, b as TaskRunFunction, Q as QueuedTask } from '../pool-types-Bzei07Nj.js';
-import '../master-BjjSaJAj.js';
-import '../transferable-Cv9t618f.js';
+import { T as Thread, P as PoolEvent, a as PoolEventType, b as TaskRunFunction, Q as QueuedTask } from '../pool-types-BnrcRDgC.js';
+import '../master-DBU-F6eB.js';
+import '../transferable-Blu_CzPT.js';
 
 interface PoolOptions {
+    /** Maximum no. of tasks to run on one worker thread at a time. Defaults to one. */
     concurrency?: number;
+    /** Maximum no. of jobs to be queued for execution before throwing an error. */
     maxQueuedJobs?: number;
+    /** Gives that pool a name to be used for debug logging, letting you distinguish between log output of different pools. */
     name?: string;
+    /** No. of worker threads to spawn and to be managed by the pool. */
     size?: number;
 }
 declare class WorkerPool<ThreadType extends Thread> implements Pool<ThreadType> {
@@ -32,18 +36,55 @@ declare class WorkerPool<ThreadType extends Thread> implements Pool<ThreadType>
     queue(taskFunction: TaskRunFunction<ThreadType, any>): QueuedTask<ThreadType, any>;
     terminate(force?: boolean): Promise<void>;
 }
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
 declare function PoolConstructor<ThreadType extends Thread>(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions): WorkerPool<ThreadType>;
 declare namespace Pool {
     type Event<ThreadType extends Thread = any> = PoolEvent<ThreadType>;
     type EventType = PoolEventType;
 }
+/**
+ * Thread pool managing a set of worker threads.
+ * Use it to queue tasks that are run on those threads with limited
+ * concurrency.
+ */
 interface Pool<ThreadType extends Thread> {
+    /**
+     * Returns a promise that resolves once the task queue is emptied.
+     * Promise will be rejected if any task fails.
+     *
+     * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
+     */
     completed(allowResolvingImmediately?: boolean): Promise<any>;
+    /**
+     * Returns a promise that resolves once the task queue is emptied.
+     * Failing tasks will not cause the promise to be rejected.
+     *
+     * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
+     */
     settled(allowResolvingImmediately?: boolean): Promise<Error[]>;
+    /**
+     * Returns an observable that yields pool events.
+     */
     events(): Observable<PoolEvent<ThreadType>>;
+    /**
+     * Queue a task and return a promise that resolves once the task has been dequeued,
+     * started and finished.
+     *
+     * @param task An async function that takes a thread instance and invokes it.
+     */
     queue<Return>(task: TaskRunFunction<ThreadType, Return>): QueuedTask<ThreadType, Return>;
+    /**
+     * Terminate all pool threads.
+     *
+     * @param force Set to `true` to kill the thread even if it cannot be stopped gracefully.
+     */
     terminate(force?: boolean): Promise<void>;
 }
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
 declare const Pool: typeof PoolConstructor & {
     EventType: typeof PoolEventType;
 };

package/dist/node/{master-BjjSaJAj.d.ts → master-DBU-F6eB.d.ts}

@@ -1,11 +1,24 @@
 import { Observable, SubscriptionObserver, ObservableLike as ObservableLike$1 } from 'observable-fns';
-import { $ as $errors, b as $events, c as $terminate, d as $worker, T as TransferDescriptor } from './transferable-Cv9t618f.js';
+import { $ as $errors, b as $events, c as $terminate, d as $worker, T as TransferDescriptor } from './transferable-Blu_CzPT.js';
 
 type Initializer<T> = (observer: SubscriptionObserver<T>) => UnsubscribeFn | void;
 type Thenable<T> = {
     then: (onFulfilled?: (value: T) => any, onRejected?: (error: any) => any) => any;
 };
 type UnsubscribeFn = () => void;
+/**
+ * Creates a hybrid, combining the APIs of an Observable and a Promise.
+ *
+ * It is used to proxy async process states when we are initially not sure
+ * if that async process will yield values once (-> Promise) or multiple
+ * times (-> Observable).
+ *
+ * Note that the observable promise inherits some of the observable's characteristics:
+ * The `init` function will be called *once for every time anyone subscribes to it*.
+ *
+ * If this is undesired, derive a hot observable from it using `makeHot()` and
+ * subscribe to that.
+ */
 declare class ObservablePromise<T> extends Observable<T> implements Promise<T> {
     readonly [Symbol.toStringTag] = "[object ObservablePromise]";
     private initHasRun;
@@ -59,27 +72,39 @@ interface AnyFunctionThread extends PrivateThreadProps {
 }
 interface AnyModuleThread extends PrivateThreadProps {
 }
+/** Worker thread. Either a `FunctionThread` or a `ModuleThread`. */
 type Thread = AnyFunctionThread | AnyModuleThread;
 type TransferList = Transferable[];
+/** Worker instance. Either a web worker or a node.js Worker provided by `worker_threads` or `tiny-worker`. */
 interface Worker extends EventTarget {
     postMessage(value: any, transferList?: TransferList): void;
+    /** In nodejs 10+ return type is Promise while with tiny-worker and in browser return type is void */
     terminate(callback?: (error?: Error, exitCode?: number) => void): void | Promise<number>;
 }
 interface ThreadsWorkerOptions extends WorkerOptions {
+    /** Whether to apply CORS protection workaround. Defaults to true. */
     CORSWorkaround?: boolean;
+    /** Prefix for the path passed to the Worker constructor. Web worker only. */
     _baseURL?: string;
+    /** Resource limits passed on to Node worker_threads */
     resourceLimits?: {
+        /** The size of a pre-allocated memory range used for generated code. */
         codeRangeSizeMb?: number;
+        /** The maximum size of the main heap in MB. */
         maxOldGenerationSizeMb?: number;
+        /** The maximum size of a heap space for recently created objects. */
         maxYoungGenerationSizeMb?: number;
     };
+    /** Data passed on to node.js worker_threads. */
     workerData?: any;
 }
+/** Worker implementation. Either web worker or a node.js Worker class. */
 declare class WorkerImplementation extends EventTarget implements Worker {
     constructor(path: string, options?: ThreadsWorkerOptions);
     postMessage(value: any, transferList?: TransferList): void;
     terminate(): void | Promise<number>;
 }
+/** Class to spawn workers from a blob or source string. */
 declare class BlobWorker extends WorkerImplementation {
     constructor(blob: Blob, options?: ThreadsWorkerOptions);
     static fromText(source: string, options?: ThreadsWorkerOptions): WorkerImplementation;
@@ -88,6 +113,7 @@ interface ImplementationExport {
     blob: typeof BlobWorker;
     default: typeof WorkerImplementation;
 }
+/** Event as emitted by worker thread. Subscribe to using `Thread.events(thread)`. */
 declare enum WorkerEventType {
     internalError = "internalError",
     message = "message",

package/dist/node/{pool-types-Bzei07Nj.d.ts → pool-types-BnrcRDgC.d.ts}

@@ -1,13 +1,18 @@
 import { Observable } from 'observable-fns';
-import { T as Thread$1, W as WorkerEvent } from './master-BjjSaJAj.js';
+import { T as Thread$1, W as WorkerEvent } from './master-DBU-F6eB.js';
 
 type Thread = Thread$1;
+/** Thread utility functions. Use them to manage or inspect a `spawn()`-ed thread. */
 declare const Thread: {
+    /** Return an observable that can be used to subscribe to all errors happening in the thread. */
     errors<ThreadT extends Thread$1>(thread: ThreadT): Observable<Error>;
+    /** Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging. */
     events<ThreadT extends Thread$1>(thread: ThreadT): Observable<WorkerEvent>;
+    /** Terminate a thread. Remember to terminate every thread when you are done using it. */
     terminate<ThreadT extends Thread$1>(thread: ThreadT): Promise<void>;
 };
 
+/** Pool event type. Specifies the type of each `PoolEvent`. */
 declare enum PoolEventType {
     initialized = "initialized",
     taskCanceled = "taskCanceled",
@@ -19,6 +24,7 @@ declare enum PoolEventType {
     terminated = "terminated"
 }
 type TaskRunFunction<ThreadType extends Thread, Return> = (worker: ThreadType) => Promise<Return>;
+/** Pool event. Subscribe to those events using `pool.events()`. Useful for debugging. */
 type PoolEvent<ThreadType extends Thread> = {
     type: PoolEventType.initialized;
     size: number;
@@ -48,10 +54,22 @@ type PoolEvent<ThreadType extends Thread> = {
     type: PoolEventType.terminated;
     remainingQueue: Array<QueuedTask<ThreadType, any>>;
 };
+/**
+ * Task that has been `pool.queued()`-ed.
+ */
 interface QueuedTask<ThreadType extends Thread, Return> {
+    /** @private */
     id: number;
+    /** @private */
     run: TaskRunFunction<ThreadType, Return>;
+    /**
+     * Queued tasks can be cancelled until the pool starts running them on a worker thread.
+     */
     cancel(): void;
+    /**
+     * `QueuedTask` is thenable, so you can `await` it.
+     * Resolves when the task has successfully been executed. Rejects if the task fails.
+     */
     then: Promise<Return>['then'];
 }
 

package/dist/node/transferable-Blu_CzPT.d.ts

@@ -0,0 +1,48 @@
+declare const $errors: unique symbol;
+declare const $events: unique symbol;
+declare const $terminate: unique symbol;
+declare const $transferable: unique symbol;
+declare const $worker: unique symbol;
+
+interface TransferDescriptor<T = any> {
+    [$transferable]: true;
+    send: T;
+    transferables: Transferable[];
+}
+/**
+ * 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!
+ *
+ * @param transferable Array buffer, message port or similar.
+ * @see <https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast>
+ */
+declare function Transfer(transferable: Transferable): 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!
+ *
+ * @param transferable Array buffer, message port or similar.
+ * @see <https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast>
+ */
+declare function Transfer<T>(payload: T, transferables: Transferable[]): TransferDescriptor;
+
+export { $errors as $, type TransferDescriptor as T, Transfer as a, $events as b, $terminate as c, $worker as d };

package/dist/node/worker/worker.node.d.ts

@@ -2,7 +2,7 @@ import { A as AbstractedWorkerAPI, W as WorkerFunction, a as WorkerModule } from
 import * as worker_threads from 'worker_threads';
 import { MessagePort } from 'node:worker_threads';
 export { r as registerSerializer } from '../common-Cuiya5FG.js';
-export { a as Transfer } from '../transferable-Cv9t618f.js';
+export { a as Transfer } from '../transferable-Blu_CzPT.js';
 
 declare const isWorkerRuntime: AbstractedWorkerAPI['isWorkerRuntime'];
 declare const postMessageToMaster: AbstractedWorkerAPI['postMessageToMaster'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/threads",
-  "version": "4.13.4",
+  "version": "4.13.6",
   "description": "Web workers & worker threads as simple as a function call",
   "keywords": [
     "thread",
@@ -113,7 +113,7 @@
     "package-compile-tsup": "tsup --config tsup.browser.config.ts && tsup --config tsup.node.config.ts && tsup --config tsup.neutral.config.ts"
   },
   "dependencies": {
-    "@xylabs/assert": "^4.13.4",
+    "@xylabs/assert": "^4.13.6",
     "debug": "^4.4.1",
     "is-observable-2-1-0": "npm:is-observable@2.1.0",
     "observable-fns": "^0.6.1"
@@ -122,8 +122,8 @@
     "@swc/core": "^1.12.11",
     "@types/debug": "^4.1.12",
     "@types/node": "^24.0.13",
-    "@xylabs/eslint-config-flat": "^7.0.0-rc.7",
-    "@xylabs/ts-scripts-yarn3": "^7.0.0-rc.7",
+    "@xylabs/eslint-config-flat": "^7.0.0-rc.8",
+    "@xylabs/ts-scripts-yarn3": "^7.0.0-rc.8",
     "tiny-worker": "^2.3.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3"

package/dist/browser/transferable-Cv9t618f.d.ts

@@ -1,15 +0,0 @@
-declare const $errors: unique symbol;
-declare const $events: unique symbol;
-declare const $terminate: unique symbol;
-declare const $transferable: unique symbol;
-declare const $worker: unique symbol;
-
-interface TransferDescriptor<T = any> {
-    [$transferable]: true;
-    send: T;
-    transferables: Transferable[];
-}
-declare function Transfer(transferable: Transferable): TransferDescriptor;
-declare function Transfer<T>(payload: T, transferables: Transferable[]): TransferDescriptor;
-
-export { $errors as $, type TransferDescriptor as T, Transfer as a, $events as b, $terminate as c, $worker as d };

package/dist/node/transferable-Cv9t618f.d.ts

@@ -1,15 +0,0 @@
-declare const $errors: unique symbol;
-declare const $events: unique symbol;
-declare const $terminate: unique symbol;
-declare const $transferable: unique symbol;
-declare const $worker: unique symbol;
-
-interface TransferDescriptor<T = any> {
-    [$transferable]: true;
-    send: T;
-    transferables: Transferable[];
-}
-declare function Transfer(transferable: Transferable): TransferDescriptor;
-declare function Transfer<T>(payload: T, transferables: Transferable[]): TransferDescriptor;
-
-export { $errors as $, type TransferDescriptor as T, Transfer as a, $events as b, $terminate as c, $worker as d };