threadsx 2.0.2 → 2.1.0

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown when a value passed to a thread cannot be cloned by the structured
+ * clone algorithm (e.g. functions, class instances with methods, or other
+ * non-serializable values). Wraps the underlying `DataCloneError` / `DOMException`
+ * with an actionable message. Access the original error via `.cause`.
+ */
+export declare class ThreadCloneError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Whether an error is a structured-clone failure. Both browsers and Node's
+ * `worker_threads` throw a `DOMException`/error named `"DataCloneError"` when a
+ * value cannot be cloned across the thread boundary.
+ */
+export declare function isDataCloneError(error: unknown): boolean;

package/dist/errors.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThreadCloneError = void 0;
+exports.isDataCloneError = isDataCloneError;
+/**
+ * Thrown when a value passed to a thread cannot be cloned by the structured
+ * clone algorithm (e.g. functions, class instances with methods, or other
+ * non-serializable values). Wraps the underlying `DataCloneError` / `DOMException`
+ * with an actionable message. Access the original error via `.cause`.
+ */
+class ThreadCloneError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = "ThreadCloneError";
+        this.cause = cause;
+        // Restore the prototype chain — extending built-ins breaks `instanceof`
+        // when compiled down to ES2015 without this.
+        Object.setPrototypeOf(this, ThreadCloneError.prototype);
+    }
+}
+exports.ThreadCloneError = ThreadCloneError;
+/**
+ * Whether an error is a structured-clone failure. Both browsers and Node's
+ * `worker_threads` throw a `DOMException`/error named `"DataCloneError"` when a
+ * value cannot be cloned across the thread boundary.
+ */
+function isDataCloneError(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        error.name === "DataCloneError");
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { registerSerializer } from "./common";
+export { ThreadCloneError } from "./errors";
 export * from "./master/index";
 export { expose } from "./worker/index";
 export { DefaultSerializer, JsonSerializable, Serializer, SerializerImplementation } from "./serializers";

package/dist/index.js

@@ -14,9 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Transfer = exports.DefaultSerializer = exports.expose = exports.registerSerializer = void 0;
+exports.Transfer = exports.DefaultSerializer = exports.expose = exports.ThreadCloneError = exports.registerSerializer = void 0;
 var common_1 = require("./common");
 Object.defineProperty(exports, "registerSerializer", { enumerable: true, get: function () { return common_1.registerSerializer; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ThreadCloneError", { enumerable: true, get: function () { return errors_1.ThreadCloneError; } });
 __exportStar(require("./master/index"), exports);
 var index_1 = require("./worker/index");
 Object.defineProperty(exports, "expose", { enumerable: true, get: function () { return index_1.expose; } });

package/dist/master/implementation.node.js

@@ -40,12 +40,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultPoolSize = void 0;
 exports.getWorkerImplementation = getWorkerImplementation;
 exports.isWorkerRuntime = isWorkerRuntime;
+// NOTE: `callsites` is intentionally pinned to ^3. v4+ is ESM-only and would
+// break the CommonJS (dist/) build. Do not bump it to v4 without moving the
+// package to ESM-first output. (See .github/dependabot.yml, which also ignores
+// its major updates.)
 const callsites_1 = __importDefault(require("callsites"));
 const os_1 = require("os");
 const path = __importStar(require("path"));
 const url_1 = require("url");
 let detectedTsRuntime;
 exports.defaultPoolSize = (0, os_1.cpus)().length;
+/**
+ * Whether the application opted out of threadsx installing SIGINT/SIGTERM
+ * handlers (which call `process.exit()`), via `THREADS_SKIP_SIGNAL_HANDLERS`.
+ */
+function signalHandlersDisabled() {
+    const value = typeof process !== "undefined" && process.env
+        ? process.env.THREADS_SKIP_SIGNAL_HANDLERS
+        : undefined;
+    return value === "1" || value === "true";
+}
 /**
  * Detects an available TypeScript runtime so `.ts`/`.tsx` worker files can be
  * spawned directly during development. Prefers `tsx`, falls back to `ts-node`.
@@ -168,8 +182,14 @@ function initWorkerThreadsWorker() {
         allWorkers = [];
     };
     // Take care to not leave orphaned processes behind. See #147.
-    process.on("SIGINT", () => terminateWorkersAndMaster());
-    process.on("SIGTERM", () => terminateWorkersAndMaster());
+    //
+    // These handlers call process.exit(), which hijacks the host application's
+    // own shutdown. Applications that manage their own graceful shutdown can opt
+    // out by setting THREADS_SKIP_SIGNAL_HANDLERS. See upstream #388 / #484.
+    if (!signalHandlersDisabled()) {
+        process.on("SIGINT", () => terminateWorkersAndMaster());
+        process.on("SIGTERM", () => terminateWorkersAndMaster());
+    }
     class BlobWorker extends Worker {
         constructor(blob, options) {
             super(Buffer.from(blob).toString("utf-8"), Object.assign(Object.assign({}, options), { fromSource: true }));

package/dist/master/invocation-proxy.js

@@ -14,6 +14,7 @@ exports.createProxyModule = createProxyModule;
 const debug_1 = __importDefault(require("debug"));
 const observable_fns_1 = require("observable-fns");
 const common_1 = require("../common");
+const errors_1 = require("../errors");
 const observable_promise_1 = require("../observable-promise");
 const transferable_1 = require("../transferable");
 const messages_1 = require("../types/messages");
@@ -26,6 +27,12 @@ const isJobStartMessage = (data) => data && data.type === messages_1.WorkerMessa
 function createObservableForJob(worker, jobUID) {
     return new observable_fns_1.Observable(observer => {
         let asyncType;
+        let settled = false;
+        const cleanup = () => {
+            worker.removeEventListener("message", messageHandler);
+            worker.removeEventListener("error", errorHandler);
+            worker.removeEventListener("exit", exitHandler);
+        };
         const messageHandler = ((event) => {
             debugMessages("Message from worker:", event.data);
             if (!event.data || event.data.uid !== jobUID)
@@ -38,31 +45,52 @@ function createObservableForJob(worker, jobUID) {
                     if (typeof event.data.payload !== "undefined") {
                         observer.next((0, common_1.deserialize)(event.data.payload));
                     }
+                    settled = true;
                     observer.complete();
-                    worker.removeEventListener("message", messageHandler);
+                    cleanup();
                 }
                 else {
-                    if (event.data.payload) {
+                    if (typeof event.data.payload !== "undefined") {
                         observer.next((0, common_1.deserialize)(event.data.payload));
                     }
                     if (event.data.complete) {
+                        settled = true;
                         observer.complete();
-                        worker.removeEventListener("message", messageHandler);
+                        cleanup();
                     }
                 }
             }
             else if (isJobErrorMessage(event.data)) {
                 const error = (0, common_1.deserialize)(event.data.error);
-                if (asyncType === "promise" || !asyncType) {
-                    observer.error(error);
-                }
-                else {
-                    observer.error(error);
-                }
-                worker.removeEventListener("message", messageHandler);
+                settled = true;
+                observer.error(error);
+                cleanup();
             }
         });
+        // If the worker crashes or is terminated before the job produces a result,
+        // reject the pending job instead of leaving the promise hanging forever.
+        // See #386.
+        const errorHandler = ((event) => {
+            if (settled)
+                return;
+            settled = true;
+            const error = event && event.data instanceof Error
+                ? event.data
+                : Error(String((event && event.data) || "Worker errored before the job completed."));
+            observer.error(error);
+            cleanup();
+        });
+        const exitHandler = ((event) => {
+            if (settled)
+                return;
+            settled = true;
+            const exitCode = event ? event.data : undefined;
+            observer.error(Error(`Worker terminated before the job completed (exit code: ${exitCode}).`));
+            cleanup();
+        });
         worker.addEventListener("message", messageHandler);
+        worker.addEventListener("error", errorHandler);
+        worker.addEventListener("exit", exitHandler);
         return () => {
             if (asyncType === "observable" || !asyncType) {
                 const cancelMessage = {
@@ -71,7 +99,7 @@ function createObservableForJob(worker, jobUID) {
                 };
                 worker.postMessage(cancelMessage);
             }
-            worker.removeEventListener("message", messageHandler);
+            cleanup();
         };
     });
 }
@@ -114,6 +142,12 @@ function createProxyFunction(worker, method) {
             worker.postMessage(runMessage, transferables);
         }
         catch (error) {
+            if ((0, errors_1.isDataCloneError)(error)) {
+                const cloneError = new errors_1.ThreadCloneError(`Cannot send arguments to the worker thread: a value is not structured-cloneable. ` +
+                    `Functions, class instances and other non-serializable values cannot be passed to a thread. ` +
+                    `Original error: ${error.message}`, error);
+                return observable_promise_1.ObservablePromise.from(Promise.reject(cloneError));
+            }
             return observable_promise_1.ObservablePromise.from(Promise.reject(error));
         }
         return observable_promise_1.ObservablePromise.from((0, observable_fns_1.multicast)(createObservableForJob(worker, uid)));

package/dist/master/pool.d.ts

@@ -54,33 +54,10 @@ export interface PoolOptions {
     /** No. of worker threads to spawn and to be managed by the pool. */
     size?: number;
 }
-declare class WorkerPool<ThreadType extends Thread> implements Pool<ThreadType> {
-    static EventType: typeof PoolEventType;
-    private readonly debug;
-    private readonly eventObservable;
-    private readonly options;
-    private readonly workers;
-    private readonly eventSubject;
-    private initErrors;
-    private isClosing;
-    private nextTaskID;
-    private taskQueue;
-    constructor(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions);
-    private findIdlingWorker;
-    private runPoolTask;
-    private run;
-    private scheduleWork;
-    private taskCompletion;
-    settled(allowResolvingImmediately?: boolean): Promise<Error[]>;
-    completed(allowResolvingImmediately?: boolean): Promise<void>;
-    events(): Observable<PoolEvent<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 function PoolConstructor<ThreadType extends Thread>(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions): Pool<ThreadType>;
 /**
  * Thread pool constructor. Creates a new pool and spawns its worker threads.
  */

package/dist/master/pool.js

@@ -173,11 +173,16 @@ class WorkerPool {
             yield new Promise((resolve, reject) => {
                 const subscription = this.eventObservable.subscribe({
                     next(event) {
-                        if (event.type === pool_types_1.PoolEventType.taskQueueDrained) {
+                        if (event.type === pool_types_1.PoolEventType.taskQueueDrained || event.type === pool_types_1.PoolEventType.terminated) {
                             subscription.unsubscribe();
                             resolve(void 0);
                         }
                     },
+                    complete() {
+                        // The pool was terminated while we were waiting; resolve instead of hanging.
+                        subscription.unsubscribe();
+                        resolve(void 0);
+                    },
                     error: reject // make a pool-wide error reject the completed() result promise
                 });
             });
@@ -192,7 +197,7 @@ class WorkerPool {
             const earlyExitPromise = new Promise((resolve, reject) => {
                 const subscription = this.eventObservable.subscribe({
                     next(event) {
-                        if (event.type === pool_types_1.PoolEventType.taskQueueDrained) {
+                        if (event.type === pool_types_1.PoolEventType.taskQueueDrained || event.type === pool_types_1.PoolEventType.terminated) {
                             subscription.unsubscribe();
                             resolve(settlementPromise);
                         }
@@ -201,6 +206,11 @@ class WorkerPool {
                             reject(event.error);
                         }
                     },
+                    complete() {
+                        // The pool was terminated while we were waiting; resolve instead of hanging.
+                        subscription.unsubscribe();
+                        resolve(settlementPromise);
+                    },
                     error: reject // make a pool-wide error reject the completed() result promise
                 });
             });
@@ -270,7 +280,17 @@ class WorkerPool {
                 remainingQueue: [...this.taskQueue]
             });
             this.eventSubject.complete();
-            yield Promise.all(this.workers.map((worker) => __awaiter(this, void 0, void 0, function* () { return thread_1.Thread.terminate(yield worker.init); })));
+            yield Promise.all(this.workers.map((worker) => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    yield thread_1.Thread.terminate(yield worker.init);
+                }
+                catch (error) {
+                    // The worker never finished initializing (e.g. it hit the init
+                    // timeout), so `worker.init` rejected and there is no thread to
+                    // terminate here — spawn() already tore down the underlying worker.
+                    this.debug("Worker did not initialize; nothing to terminate:", error);
+                }
+            })));
         });
     }
 }
@@ -281,6 +301,8 @@ WorkerPool.EventType = pool_types_1.PoolEventType;
 function PoolConstructor(spawnWorker, optionsOrSize) {
     // The function exists only so we don't need to use `new` to create a pool (we still can, though).
     // If the Pool is a class or not is an implementation detail that should not concern the user.
+    // The explicit `Pool<ThreadType>` return type keeps the private `WorkerPool` class out of the
+    // public type surface, so consumers can name/re-export the pool type (#417).
     return new WorkerPool(spawnWorker, optionsOrSize);
 }
 PoolConstructor.EventType = pool_types_1.PoolEventType;

package/dist/transferable.d.ts

@@ -1,4 +1,5 @@
 import { $transferable } from "./symbols";
+export type Transferable = object;
 export interface TransferDescriptor<T = any> {
     [$transferable]: true;
     send: T;

package/dist/types/master.d.ts

@@ -1,7 +1,28 @@
 import { Observable } from "observable-fns";
 import { ObservablePromise } from "../observable-promise";
 import { $errors, $events, $terminate, $worker } from "../symbols";
-import { TransferDescriptor } from "../transferable";
+import { Transferable, TransferDescriptor } from "../transferable";
+declare class EventTarget {
+    addEventListener(type: string, listener: any, options?: any): void;
+    removeEventListener(type: string, listener: any, options?: any): void;
+    dispatchEvent(event: any): boolean;
+}
+interface WorkerOptions {
+    type?: "classic" | "module";
+    credentials?: "omit" | "same-origin" | "include";
+    name?: string;
+}
+interface URL {
+    readonly href: string;
+    toString(): string;
+}
+interface Blob {
+    readonly size: number;
+    readonly type: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    slice(start?: number, end?: number, contentType?: string): Blob;
+    text(): Promise<string>;
+}
 interface ObservableLikeSubscription {
     unsubscribe(): any;
 }

package/dist/types/master.js

@@ -1,5 +1,4 @@
 "use strict";
-/// <reference lib="dom" />
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkerEventType = void 0;
 const symbols_1 = require("../symbols");

package/dist/types/worker.d.ts

@@ -1,3 +1,4 @@
+import { Transferable } from "../transferable";
 type UnsubscribeFn = () => void;
 export interface AbstractedWorkerAPI {
     isWorkerRuntime(): boolean;

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

@@ -1,6 +1,6 @@
 declare const _default: {
     isWorkerRuntime: () => boolean;
-    postMessageToMaster: (message: any, transferList?: Transferable[]) => void;
+    postMessageToMaster: (message: any, transferList?: import("../transferable").Transferable[]) => void;
     subscribeToMasterMessages: (onMessage: (data: any) => void) => () => void;
 };
 export default _default;

package/dist/worker/implementation.worker_threads.d.ts

@@ -1,7 +1,7 @@
 declare function testImplementation(): void;
 declare const _default: {
     isWorkerRuntime: () => boolean;
-    postMessageToMaster: (message: any, transferList?: Transferable[]) => void;
+    postMessageToMaster: (message: any, transferList?: import("../transferable").Transferable[]) => void;
     subscribeToMasterMessages: (onMessage: (data: any) => void) => () => void;
     testImplementation: typeof testImplementation;
 };

package/dist-esm/errors.js

@@ -0,0 +1,26 @@
+/**
+ * Thrown when a value passed to a thread cannot be cloned by the structured
+ * clone algorithm (e.g. functions, class instances with methods, or other
+ * non-serializable values). Wraps the underlying `DataCloneError` / `DOMException`
+ * with an actionable message. Access the original error via `.cause`.
+ */
+export class ThreadCloneError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = "ThreadCloneError";
+        this.cause = cause;
+        // Restore the prototype chain — extending built-ins breaks `instanceof`
+        // when compiled down to ES2015 without this.
+        Object.setPrototypeOf(this, ThreadCloneError.prototype);
+    }
+}
+/**
+ * Whether an error is a structured-clone failure. Both browsers and Node's
+ * `worker_threads` throw a `DOMException`/error named `"DataCloneError"` when a
+ * value cannot be cloned across the thread boundary.
+ */
+export function isDataCloneError(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        error.name === "DataCloneError");
+}

package/dist-esm/index.js

@@ -1,4 +1,5 @@
 export { registerSerializer } from "./common";
+export { ThreadCloneError } from "./errors";
 export * from "./master/index";
 export { expose } from "./worker/index";
 export { DefaultSerializer } from "./serializers";

package/dist-esm/master/implementation.node.js

@@ -1,10 +1,24 @@
 /// <reference lib="dom" />
+// NOTE: `callsites` is intentionally pinned to ^3. v4+ is ESM-only and would
+// break the CommonJS (dist/) build. Do not bump it to v4 without moving the
+// package to ESM-first output. (See .github/dependabot.yml, which also ignores
+// its major updates.)
 import getCallsites from "callsites";
 import { cpus } from 'os';
 import * as path from "path";
 import { fileURLToPath } from "url";
 let detectedTsRuntime;
 export const defaultPoolSize = cpus().length;
+/**
+ * Whether the application opted out of threadsx installing SIGINT/SIGTERM
+ * handlers (which call `process.exit()`), via `THREADS_SKIP_SIGNAL_HANDLERS`.
+ */
+function signalHandlersDisabled() {
+    const value = typeof process !== "undefined" && process.env
+        ? process.env.THREADS_SKIP_SIGNAL_HANDLERS
+        : undefined;
+    return value === "1" || value === "true";
+}
 /**
  * Detects an available TypeScript runtime so `.ts`/`.tsx` worker files can be
  * spawned directly during development. Prefers `tsx`, falls back to `ts-node`.
@@ -127,8 +141,14 @@ function initWorkerThreadsWorker() {
         allWorkers = [];
     };
     // Take care to not leave orphaned processes behind. See #147.
-    process.on("SIGINT", () => terminateWorkersAndMaster());
-    process.on("SIGTERM", () => terminateWorkersAndMaster());
+    //
+    // These handlers call process.exit(), which hijacks the host application's
+    // own shutdown. Applications that manage their own graceful shutdown can opt
+    // out by setting THREADS_SKIP_SIGNAL_HANDLERS. See upstream #388 / #484.
+    if (!signalHandlersDisabled()) {
+        process.on("SIGINT", () => terminateWorkersAndMaster());
+        process.on("SIGTERM", () => terminateWorkersAndMaster());
+    }
     class BlobWorker extends Worker {
         constructor(blob, options) {
             super(Buffer.from(blob).toString("utf-8"), Object.assign(Object.assign({}, options), { fromSource: true }));

package/dist-esm/master/invocation-proxy.js

@@ -7,6 +7,7 @@
 import DebugLogger from "debug";
 import { multicast, Observable } from "observable-fns";
 import { deserialize, serialize } from "../common";
+import { isDataCloneError, ThreadCloneError } from "../errors";
 import { ObservablePromise } from "../observable-promise";
 import { isTransferDescriptor } from "../transferable";
 import { MasterMessageType, WorkerMessageType } from "../types/messages";
@@ -19,6 +20,12 @@ const isJobStartMessage = (data) => data && data.type === WorkerMessageType.runn
 function createObservableForJob(worker, jobUID) {
     return new Observable(observer => {
         let asyncType;
+        let settled = false;
+        const cleanup = () => {
+            worker.removeEventListener("message", messageHandler);
+            worker.removeEventListener("error", errorHandler);
+            worker.removeEventListener("exit", exitHandler);
+        };
         const messageHandler = ((event) => {
             debugMessages("Message from worker:", event.data);
             if (!event.data || event.data.uid !== jobUID)
@@ -31,31 +38,52 @@ function createObservableForJob(worker, jobUID) {
                     if (typeof event.data.payload !== "undefined") {
                         observer.next(deserialize(event.data.payload));
                     }
+                    settled = true;
                     observer.complete();
-                    worker.removeEventListener("message", messageHandler);
+                    cleanup();
                 }
                 else {
-                    if (event.data.payload) {
+                    if (typeof event.data.payload !== "undefined") {
                         observer.next(deserialize(event.data.payload));
                     }
                     if (event.data.complete) {
+                        settled = true;
                         observer.complete();
-                        worker.removeEventListener("message", messageHandler);
+                        cleanup();
                     }
                 }
             }
             else if (isJobErrorMessage(event.data)) {
                 const error = deserialize(event.data.error);
-                if (asyncType === "promise" || !asyncType) {
-                    observer.error(error);
-                }
-                else {
-                    observer.error(error);
-                }
-                worker.removeEventListener("message", messageHandler);
+                settled = true;
+                observer.error(error);
+                cleanup();
             }
         });
+        // If the worker crashes or is terminated before the job produces a result,
+        // reject the pending job instead of leaving the promise hanging forever.
+        // See #386.
+        const errorHandler = ((event) => {
+            if (settled)
+                return;
+            settled = true;
+            const error = event && event.data instanceof Error
+                ? event.data
+                : Error(String((event && event.data) || "Worker errored before the job completed."));
+            observer.error(error);
+            cleanup();
+        });
+        const exitHandler = ((event) => {
+            if (settled)
+                return;
+            settled = true;
+            const exitCode = event ? event.data : undefined;
+            observer.error(Error(`Worker terminated before the job completed (exit code: ${exitCode}).`));
+            cleanup();
+        });
         worker.addEventListener("message", messageHandler);
+        worker.addEventListener("error", errorHandler);
+        worker.addEventListener("exit", exitHandler);
         return () => {
             if (asyncType === "observable" || !asyncType) {
                 const cancelMessage = {
@@ -64,7 +92,7 @@ function createObservableForJob(worker, jobUID) {
                 };
                 worker.postMessage(cancelMessage);
             }
-            worker.removeEventListener("message", messageHandler);
+            cleanup();
         };
     });
 }
@@ -107,6 +135,12 @@ export function createProxyFunction(worker, method) {
             worker.postMessage(runMessage, transferables);
         }
         catch (error) {
+            if (isDataCloneError(error)) {
+                const cloneError = new ThreadCloneError(`Cannot send arguments to the worker thread: a value is not structured-cloneable. ` +
+                    `Functions, class instances and other non-serializable values cannot be passed to a thread. ` +
+                    `Original error: ${error.message}`, error);
+                return ObservablePromise.from(Promise.reject(cloneError));
+            }
             return ObservablePromise.from(Promise.reject(error));
         }
         return ObservablePromise.from(multicast(createObservableForJob(worker, uid)));

package/dist-esm/master/pool.js

@@ -166,11 +166,16 @@ class WorkerPool {
             yield new Promise((resolve, reject) => {
                 const subscription = this.eventObservable.subscribe({
                     next(event) {
-                        if (event.type === PoolEventType.taskQueueDrained) {
+                        if (event.type === PoolEventType.taskQueueDrained || event.type === PoolEventType.terminated) {
                             subscription.unsubscribe();
                             resolve(void 0);
                         }
                     },
+                    complete() {
+                        // The pool was terminated while we were waiting; resolve instead of hanging.
+                        subscription.unsubscribe();
+                        resolve(void 0);
+                    },
                     error: reject // make a pool-wide error reject the completed() result promise
                 });
             });
@@ -185,7 +190,7 @@ class WorkerPool {
             const earlyExitPromise = new Promise((resolve, reject) => {
                 const subscription = this.eventObservable.subscribe({
                     next(event) {
-                        if (event.type === PoolEventType.taskQueueDrained) {
+                        if (event.type === PoolEventType.taskQueueDrained || event.type === PoolEventType.terminated) {
                             subscription.unsubscribe();
                             resolve(settlementPromise);
                         }
@@ -194,6 +199,11 @@ class WorkerPool {
                             reject(event.error);
                         }
                     },
+                    complete() {
+                        // The pool was terminated while we were waiting; resolve instead of hanging.
+                        subscription.unsubscribe();
+                        resolve(settlementPromise);
+                    },
                     error: reject // make a pool-wide error reject the completed() result promise
                 });
             });
@@ -263,7 +273,17 @@ class WorkerPool {
                 remainingQueue: [...this.taskQueue]
             });
             this.eventSubject.complete();
-            yield Promise.all(this.workers.map((worker) => __awaiter(this, void 0, void 0, function* () { return Thread.terminate(yield worker.init); })));
+            yield Promise.all(this.workers.map((worker) => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    yield Thread.terminate(yield worker.init);
+                }
+                catch (error) {
+                    // The worker never finished initializing (e.g. it hit the init
+                    // timeout), so `worker.init` rejected and there is no thread to
+                    // terminate here — spawn() already tore down the underlying worker.
+                    this.debug("Worker did not initialize; nothing to terminate:", error);
+                }
+            })));
         });
     }
 }
@@ -274,6 +294,8 @@ WorkerPool.EventType = PoolEventType;
 function PoolConstructor(spawnWorker, optionsOrSize) {
     // The function exists only so we don't need to use `new` to create a pool (we still can, though).
     // If the Pool is a class or not is an implementation detail that should not concern the user.
+    // The explicit `Pool<ThreadType>` return type keeps the private `WorkerPool` class out of the
+    // public type surface, so consumers can name/re-export the pool type (#417).
     return new WorkerPool(spawnWorker, optionsOrSize);
 }
 PoolConstructor.EventType = PoolEventType;

package/dist-esm/types/master.js

@@ -1,4 +1,3 @@
-/// <reference lib="dom" />
 import { $errors, $events, $terminate, $worker } from "../symbols";
 /** Event as emitted by worker thread. Subscribe to using `Thread.events(thread)`. */
 export var WorkerEventType;