@rapidrest/core 1.14.0 → 2.0.0

package/dist/lib/TelemetryUtils.js

@@ -21,10 +21,20 @@ export class Event {
         this.origin = serviceName ? `${serviceName}:${config.get("version")}` : "unknown";
         this.type = data.type;
         this.userId = userId;
-        // Copy all fields in data to this object
         const tmp = data;
-        for (let key in tmp) {
-            if (key !== "environment" && key !== "origin" && key !== "userId") {
+        const protectedFields = new Set([
+            "environment",
+            "origin",
+            "uid",
+            "userId",
+            "__proto__",
+            "constructor",
+            "prototype",
+        ]);
+        for (const key of Object.keys(tmp)) {
+            // We intentionally exclude only these fields from copying here. All others, including timestamp
+            // the caller can override in order to provide more accurate information about the event.
+            if (!protectedFields.has(key)) {
                 this[key] = tmp[key];
             }
         }
@@ -40,6 +50,14 @@ export class Event {
  * The `on` function allows code within the same application or service to listen for outgoing events that have been
  * sent via the `record` function.
  *
+ * The utility uses an application specific JWT access token for sending telemetry events. The purpose of using an
+ * application specific JWT token versus user token is to identify a potentially compromised application server. This
+ * also allows the server to send telemetry events on behalf of the user that the user may not otherwise have permission
+ * to send.
+ *
+ * Note: This class is considered a runtime singleton and intentionally uses static state. Do not initialize this
+ * class more than once in your application.
+ *
  * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
  */
 export class EventUtils {
@@ -48,7 +66,7 @@ export class EventUtils {
      *
      * @param config The application configuration to use.
      * @param logger The logging utility to use.
-     * @param jwtToken The user's JWT token to send telemetry events on behalf of.
+     * @param jwtToken The application's JWT token to send telemetry events on behalf of.
      */
     static async init(config, logger, jwtToken) {
         EventUtils.config = config;
@@ -86,7 +104,7 @@ export class EventUtils {
                 const response = await axios.post(url, event, {
                     headers: {
                         Authorization: "jwt " + EventUtils.token,
-                    }
+                    },
                 });
             }
             else {
@@ -132,6 +150,24 @@ export class EventUtils {
             EventUtils.listeners.set(type, callbacks);
         }
     }
+    /**
+     * Unregisters a `callback` previously registered via `on()` for the given event `type`. Since `EventUtils` is
+     * a long-lived process-wide singleton, any listener registered dynamically (rather than once at startup) must
+     * eventually be removed via this method or its closure - and anything it captures - is retained for the life
+     * of the process.
+     *
+     * @param type The type of event the callback was registered for.
+     * @param callback The exact function reference passed to `on()`.
+     */
+    static off(type, callback) {
+        const callbacks = EventUtils.listeners.get(type);
+        if (callbacks) {
+            const idx = callbacks.indexOf(callback);
+            if (idx >= 0) {
+                callbacks.splice(idx, 1);
+            }
+        }
+    }
 }
 EventUtils.initialized = false;
 EventUtils.listeners = new Map();

package/dist/lib/TelemetryUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"TelemetryUtils.js","sourceRoot":"","sources":["../../src/TelemetryUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TelemetryUtils.js","sourceRoot":"","sources":["../../src/TelemetryUtils.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kDAAkD;AAClD,+EAA+E;AAC/E,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAYzC;;;;GAIG;AACH,MAAM,OAAO,KAAK;IA+Bd,YAAY,MAAW,EAAE,MAAc,EAAE,IAAc;QAfvD;;WAEG;QACa,cAAS,GAAS,IAAI,IAAI,EAAE,CAAC;QAazC,IAAI,CAAC,GAAG,GAAG,MAAM,EAAE,CAAC;QACpB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;QACxE,MAAM,WAAW,GAAW,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAClF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,MAAM,GAAG,GAAQ,IAAW,CAAC;QAC7B,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;YAC5B,aAAa;YACb,QAAQ;YACR,KAAK;YACL,QAAQ;YACR,WAAW;YACX,aAAa;YACb,WAAW;SACd,CAAC,CAAC;QACH,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,gGAAgG;YAChG,yFAAyF;YACzF,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,IAAY,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,CAAC;QACL,CAAC;IACL,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,UAAU;IAQnB;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAW,EAAE,MAAW,EAAE,QAAgB;QAC/D,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC;QAC3B,UAAU,CAAC,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC;QACjC,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC;QAC3B,UAAU,CAAC,KAAK,GAAG,QAAQ,CAAC;QAE5B,qCAAqC;QACrC,MAAM,OAAO,GAAQ,MAAM,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC9E,UAAU,CAAC,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC;QAExC,UAAU,CAAC,WAAW,GAAG,IAAI,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAmB,EAAE,IAAa;QACzD,IAAI,CAAC;YACD,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;YAC5F,CAAC;YAED,IAAI,IAAI,EAAE,CAAC;gBACP,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;YACpB,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;YAC5D,CAAC;YAED,0DAA0D;YAC1D,MAAM,KAAK,GAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAEvG,gCAAgC;YAChC,MAAM,OAAO,GAAW,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;YACxE,IAAI,OAAO,EAAE,CAAC;gBACV,MAAM,GAAG,GAAW,OAAO,GAAG,SAAS,CAAC;gBACxC,MAAM,QAAQ,GAAkB,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE;oBACzD,OAAO,EAAE;wBACL,aAAa,EAAE,MAAM,GAAG,UAAU,CAAC,KAAK;qBAC3C;iBACJ,CAAC,CAAC;YACP,CAAC;iBAAM,CAAC;gBACJ,UAAU,CAAC,MAAM,EAAE,KAAK,CACpB,wFAAwF,CAC3F,CAAC;YACN,CAAC;YAED,kCAAkC;YAClC,MAAM,SAAS,GAA2B,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC7E,IAAI,SAAS,EAAE,CAAC;gBACZ,KAAK,IAAI,IAAI,IAAI,SAAS,EAAE,CAAC;oBACzB,IAAI,CAAC,KAAK,CAAC,CAAC;gBAChB,CAAC;YACL,CAAC;QACL,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;gBACrB,OAAO,CAAC,IAAI,CAAC,0CAA0C,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1E,CAAC;iBAAM,CAAC;gBACJ,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,0CAA0C,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACpF,CAAC;QACL,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,EAAE,CAAC,IAAY,EAAE,QAAkB;QAC7C,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;QAC5F,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvC,CAAC;QAED,MAAM,SAAS,GAA2B,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzE,sGAAsG;QACtG,yDAAyD;QACzD,sBAAsB;QACtB,IAAI,SAAS,EAAE,CAAC;YACZ,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC9C,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,QAAkB;QAC9C,MAAM,SAAS,GAA2B,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzE,IAAI,SAAS,EAAE,CAAC;YACZ,MAAM,GAAG,GAAW,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAChD,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;gBACX,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC7B,CAAC;QACL,CAAC;IACL,CAAC;;AA3Hc,sBAAW,GAAY,KAAK,CAAC;AAE7B,oBAAS,GAA4B,IAAI,GAAG,EAAE,CAAC"}

package/dist/lib/UserUtils.js

@@ -34,12 +34,10 @@ export class UserUtils {
      * @param organizationUids The list of universally unique identifiers to search for.
      */
     static hasOrganizations(user, organizationUids) {
-        if (user && user.orgs && Array.isArray(user.orgs) && Array.isArray(organizationUids)) {
+        if (user && Array.isArray(organizationUids)) {
             for (const organizationUid of organizationUids) {
-                for (const uid of user.orgs) {
-                    if (uid === organizationUid) {
-                        return true;
-                    }
+                if (UserUtils.hasOrganization(user, organizationUid)) {
+                    return true;
                 }
             }
         }
@@ -59,6 +57,7 @@ export class UserUtils {
                 const parts = externalId.split(":");
                 if (parts.length === 2 && parts[0] === type) {
                     result = parts[1];
+                    break;
                 }
             }
         }
@@ -77,7 +76,7 @@ export class UserUtils {
             if (user.roles) {
                 if (Array.isArray(user.roles)) {
                     result = user.roles.includes(role);
-                    if (!result && orgUid !== "") {
+                    if (!result && orgUid) {
                         result = user.roles.includes(`${orgUid}.${role}`);
                     }
                 }

package/dist/lib/UserUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"UserUtils.js","sourceRoot":"","sources":["../../src/UserUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"UserUtils.js","sourceRoot":"","sources":["../../src/UserUtils.ts"],"names":[],"mappings":"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"}

package/dist/lib/ValidationUtils.js

@@ -43,10 +43,10 @@ export class ValidationUtils {
         return val;
     }
     /**
-     * Validates that the provided array is not empty.
+     * Validates that the provided array is not empty (nor `null`/`undefined`).
      */
     static checkEmpty(val) {
-        if (val && val.length === 0) {
+        if (!val || val.length === 0) {
             throw new Error("Value cannot be empty.");
         }
         return val;
@@ -82,7 +82,9 @@ export class ValidationUtils {
      * Validates that the provided object is not null or empty.
      */
     static checkNull(val) {
-        if (typeof val !== "boolean" && !val) {
+        // `0` is a valid, non-null value (matching `ObjectUtils.validate`'s own nullable convention), so numbers
+        // are excluded from the falsy check alongside booleans.
+        if (typeof val !== "boolean" && typeof val !== "number" && !val) {
             throw new Error("Value cannot be null.");
         }
         return val;
@@ -127,7 +129,17 @@ export class ValidationUtils {
      * Validates that the provided value is an entity `version` number (e.g. `value > 0`).
      */
     static checkVersion(val) {
-        const num = Number(val);
+        // `Number()` coerces several "empty" inputs - `null`, `""`/whitespace-only strings, `[]` - to `0`
+        // rather than `NaN`, which would otherwise let missing/malformed input silently through as if it were
+        // a legitimate version `0` instead of being rejected below. `undefined` needs no such guard since
+        // `Number(undefined)` already evaluates to `NaN`.
+        const isEmpty = val === null ||
+            (typeof val === "string" && val.trim() === "") ||
+            (Array.isArray(val) && val.length === 0);
+        const num = isEmpty ? NaN : Number(val);
+        if (isNaN(num)) {
+            throw new Error("Value is not a valid version number.");
+        }
         return Math.max(num, 0);
     }
 }

package/dist/lib/ValidationUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"ValidationUtils.js","sourceRoot":"","sources":["../../src/ValidationUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ValidationUtils.js","sourceRoot":"","sources":["../../src/ValidationUtils.ts"],"names":[],"mappings":"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"}

package/dist/lib/index.js

@@ -1,5 +1,6 @@
 export * from "./ApiError.js";
 export * from "./AlertUtils.js";
+export * from "./CacheUtils.js";
 export * from "./ClassLoader.js";
 export * from "./decorators/index.js";
 export * from "./FileUtils.js";
@@ -7,6 +8,7 @@ export * from "./JWTUtils.js";
 export * from "./Logger.js";
 export * from "./MemoryStore.js";
 export * from "./MessagingUtils.js";
+export * from "./NotificationsUtils.js";
 export * from "./ObjectFactory.js";
 export * from "./ObjectUtils.js";
 export * from "./OASUtils.js";

package/dist/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC"}

package/dist/lib/threads/ThreadPool.js

@@ -67,6 +67,10 @@ export class ThreadPool {
     constructor(max = 0, logger) {
         /** The maximum number of threads allowed. */
         this.maxThreads = os.cpus().length;
+        /** Tracks workers whose "exit" event has already fired, so a dead worker left in `workers` (e.g. exited
+         * without `restartOnExit`) is never sent a message via `postMessage()`, which throws synchronously once a
+         * worker has exited. */
+        this.exitedWorkers = new WeakSet();
         // The `os.cpus().length` fallback can never actually be selected: `this.maxThreads`'s field initializer
         // already evaluates to that same (always-truthy on a real OS) value before the constructor body runs, so
         // it's only falsy when `os.cpus().length` itself is falsy too. Kept as defense in depth.
@@ -78,7 +82,28 @@ export class ThreadPool {
         this.shutdown = false;
         this.workers = new Array();
     }
-    createWorker(idx, options) {
+    /**
+     * @param onRestart Invoked with the replacement `Worker` whenever `restartOnExit` recreates the worker for
+     * `idx`. Lets `start()` re-attach its readiness-tracking listeners to the replacement - without this, a
+     * worker that crashes and is restarted before ever reporting ready would leave `start()`'s returned promise
+     * hanging forever, since nothing would be listening for the *replacement's* readiness signal.
+     */
+    /**
+     * Invokes every callback registered for `type` via `on()`, passing `idx` and optional `data`. Centralizes
+     * the "look up listeners, no-op if none registered" dispatch idiom shared by every worker event handler in
+     * `createWorker()`/`stop()` below, so a future change to how listeners are invoked - or a new message type
+     * that needs routing to a given event - only has to be made in one place instead of risking a hand-copied
+     * site being missed (as happened with WorkerMessageType.ERROR previously falling through to "message").
+     */
+    dispatch(type, idx, data) {
+        const listeners = this.callbacks.get(type);
+        if (listeners) {
+            for (const callback of listeners) {
+                callback(idx, data);
+            }
+        }
+    }
+    createWorker(idx, options, onRestart) {
         if (!options.entry || !!options.worker) {
             options.entry = path.join(_dirname, "ThreadWorkerEntry.js");
         }
@@ -88,31 +113,48 @@ export class ThreadPool {
         };
         this.logger?.debug(`Creating thread worker: ${JSON.stringify(options)}`);
         const worker = new Worker(options.entry, workerOptions);
-        worker.on("error", (error) => {
-            const listeners = this.callbacks.get("error");
-            if (listeners) {
-                for (const callback of listeners) {
-                    callback(idx, error);
-                }
+        // Dispatches registered "online" callbacks for entry-mode pools, which have no other way to signal
+        // readiness at the application level. Guarded to worker-mode's exclusion (`!options.worker`) so a
+        // worker-mode pool - which reports readiness via the WorkerMessageType.ONLINE message handled below -
+        // doesn't fire "online" callbacks twice for the same worker.
+        worker.on("online", () => {
+            if (options && !options.worker) {
+                this.dispatch("online", idx);
             }
         });
+        worker.on("error", (error) => {
+            this.dispatch("error", idx, error);
+        });
         worker.on("exit", async (code) => {
+            // Mark this worker instance as exited regardless of shutdown/restart state so send()/sendAll()/
+            // sendTo() never call postMessage() on it - postMessage() throws synchronously once a worker has
+            // exited, and a restarted worker gets a brand new Worker instance anyway so marking the old one here
+            // is harmless.
+            this.exitedWorkers.add(worker);
             // While stop() is in progress it fires "exit" callbacks itself, using the authoritative exit code
             // returned by terminate() - which is what triggers this very event. Firing them again here would
             // invoke every registered "exit" callback twice per worker for a single stop() call.
             if (!this.shutdown) {
-                const listeners = this.callbacks.get("exit");
-                if (listeners) {
-                    for (const callback of listeners) {
-                        callback(idx, code);
-                    }
-                }
+                this.dispatch("exit", idx, code);
             }
             // Restart worker thread
             if (options?.restartOnExit && !this.shutdown) {
                 worker.removeAllListeners();
-                const newWorker = this.createWorker(idx, options);
-                this.workers[idx] = newWorker;
+                // createWorker() calls `new Worker(...)`, which can throw synchronously (e.g. non-cloneable
+                // workerData, thread-limit/OOM errors) - especially likely in a crash-loop scenario, which is
+                // exactly when restartOnExit is most active. This listener is itself async, and Node does not
+                // attach a rejection handler to an EventEmitter listener's returned promise, so an uncaught throw
+                // here would become an unhandled rejection capable of crashing the whole host process. Routing
+                // the failure to "error" listeners instead keeps it recoverable, consistent with how every other
+                // worker failure in this file is reported.
+                try {
+                    const newWorker = this.createWorker(idx, options, onRestart);
+                    this.workers[idx] = newWorker;
+                    onRestart?.(newWorker);
+                }
+                catch (error) {
+                    this.dispatch("error", idx, error);
+                }
             }
         });
         worker.on("message", (msg) => {
@@ -121,24 +163,17 @@ export class ThreadPool {
                     this.logger?.log(msg.data);
                     break;
                 case WorkerMessageType.ONLINE:
-                    {
-                        const listeners = this.callbacks.get("online");
-                        if (listeners) {
-                            for (const callback of listeners) {
-                                callback(idx);
-                            }
-                        }
-                    }
+                    this.dispatch("online", idx);
+                    break;
+                case WorkerMessageType.ERROR:
+                    // A post-startup runtime error reported by the worker (see ThreadWorkerEntry.js's message
+                    // handler). Must route to "error" listeners like the native worker.on("error", ...) case
+                    // above, not fall through to "message" - otherwise anything monitoring failures only via
+                    // pool.on("error", ...) never learns the worker failed.
+                    this.dispatch("error", idx, msg.data);
                     break;
                 default:
-                    {
-                        const listeners = this.callbacks.get("message");
-                        if (listeners) {
-                            for (const callback of listeners) {
-                                callback(idx, msg);
-                            }
-                        }
-                    }
+                    this.dispatch("message", idx, msg);
                     break;
             }
         });
@@ -152,61 +187,155 @@ export class ThreadPool {
      */
     start(options, num = this.max) {
         this.shutdown = false;
+        // Terminate any workers left over from a previous start() call so they aren't leaked (their thread and
+        // listeners would otherwise become unreachable once `this.workers[i]` is overwritten below).
+        for (const worker of this.workers) {
+            worker.removeAllListeners();
+            void worker.terminate();
+        }
+        this.workers.length = 0;
         return new Promise((resolve, reject) => {
             let numReady = 0;
-            if (!options) {
-                options = {};
+            let settled = false;
+            // Copied rather than mutated in place - `options` may be the caller's own object (reused across
+            // multiple start() calls, or even frozen), and it shouldn't gain an `allowTs` property - or, via
+            // createWorker() below, an `entry` property - that the caller never set themselves. Everything past
+            // this point operates on `resolvedOptions`, never the original `options` parameter.
+            const resolvedOptions = { ...options };
+            resolvedOptions.allowTs = "allowTs" in resolvedOptions ? resolvedOptions.allowTs : true;
+            const target = Math.min(num, this.maxThreads);
+            if (target <= 0) {
+                // Nothing to create; resolve immediately instead of hanging forever waiting for readiness signals
+                // that will never arrive.
+                this.logger?.debug("No worker threads to create.");
+                resolve();
+                return;
             }
-            options.allowTs = "allowTs" in options ? options.allowTs : true;
-            for (let i = 0; i < num && i < this.maxThreads; i++) {
-                const worker = this.createWorker(i, options);
-                worker.on("online", () => {
-                    if (options && !options.worker) {
+            // If any worker fails to start, terminate every worker created during this start() call (the
+            // failed one and any siblings that succeeded) before rejecting. Without this, a failed start()
+            // leaks running worker threads that the caller has no reference to, since the returned promise
+            // is the only thing that told them startup failed - they have no reason to call stop(). `shutdown`
+            // is set first (mirroring stop()) so createWorker()'s persistent "exit" handler treats this as a
+            // controlled teardown rather than a crash to restart via `restartOnExit`. Listeners are
+            // deliberately left attached (unlike the leftover-worker cleanup above) rather than calling
+            // `removeAllListeners()`: a worker mid-teardown that still fires a genuine "error" event with no
+            // listener left on it would make Node throw and crash the whole process.
+            const failStartup = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timeoutHandle);
+                this.shutdown = true;
+                for (const worker of this.workers) {
+                    void worker.terminate();
+                }
+                this.workers.length = 0;
+                reject(error);
+            };
+            // Guard against a worker that never reports readiness and never errors either.
+            const timeoutMs = resolvedOptions.startupTimeoutMs ?? ThreadPool.START_TIMEOUT_MS;
+            const timeoutHandle = setTimeout(() => {
+                failStartup(new Error(`Timed out waiting for worker threads to start after ${timeoutMs}ms.`));
+            }, timeoutMs);
+            timeoutHandle.unref?.();
+            const succeed = () => {
+                settled = true;
+                clearTimeout(timeoutHandle);
+                resolve();
+            };
+            // Attaches the readiness-tracking listeners used to resolve/reject this start() call to `w`. Defined
+            // once per slot and re-invoked (via createWorker's `onRestart` hook below) on any replacement worker
+            // created by `restartOnExit` before this promise settles, so a worker that crashes and restarts
+            // during startup - before ever reporting ready - still lets start() resolve once the *replacement*
+            // becomes ready, instead of hanging forever with no listener tracking it.
+            const attachReadyListeners = (w) => {
+                let ready = false;
+                w.on("online", () => {
+                    if (settled) {
+                        return;
+                    }
+                    if (!resolvedOptions.worker) {
+                        ready = true;
                         numReady++;
                     }
                     // When all workers have finished being created resolve
-                    if (numReady >= num || numReady >= this.maxThreads) {
-                        resolve();
+                    if (numReady >= target) {
+                        succeed();
                     }
                 });
-                worker.on("message", (msg) => {
+                // If a worker fails to start before it ever reaches readiness, reject instead of leaving the
+                // returned promise hanging forever.
+                w.on("error", (error) => {
+                    if (!ready) {
+                        failStartup(error);
+                    }
+                });
+                w.on("message", (msg) => {
+                    if (settled) {
+                        return;
+                    }
                     switch (msg.type) {
                         case WorkerMessageType.ERROR:
-                            reject(msg.data);
-                            break;
+                            failStartup(msg.data);
+                            return;
                         case WorkerMessageType.ONLINE:
+                            ready = true;
                             numReady++;
                             break;
                     }
                     // When all workers have finished being created resolve
-                    if (numReady >= num || numReady >= this.maxThreads) {
-                        resolve();
+                    if (numReady >= target) {
+                        succeed();
                     }
                 });
+            };
+            for (let i = 0; i < target; i++) {
+                const worker = this.createWorker(i, resolvedOptions, (newWorker) => {
+                    if (!settled) {
+                        attachReadyListeners(newWorker);
+                    }
+                });
+                attachReadyListeners(worker);
                 this.workers[i] = worker;
             }
             this.logger?.debug(`Created ${this.workers.length} worker(s)`);
         });
     }
     /**
-     * Stops all running thread executions.
+     * Stops all running thread executions. Each worker is given `ThreadPool.STOP_GRACE_PERIOD_MS` to gracefully
+     * finish its own `stop()` and exit on its own before being force-terminated.
      */
     async stop() {
         const listeners = this.callbacks.get("exit");
         this.shutdown = true;
-        // Send the stop signal so the workers know to terminate
+        // Send the stop signal so the workers know to shut down gracefully
         this.sendAll({ type: WorkerMessageType.STOP });
-        // Give the message above a chance to propogate
-        await sleep(10);
-        for (let idx = 0; idx < this.workers.length; idx++) {
-            const worker = this.workers[idx];
-            const exitCode = await worker.terminate();
+        // Terminate all workers concurrently so shutdown latency is bounded by the slowest worker rather than
+        // scaling linearly with pool size. Each worker gets a grace period to exit on its own (i.e. for its
+        // ThreadWorker.stop() to actually finish) before being force-terminated, so in-flight cleanup work
+        // (flushing writes, closing connections, etc.) isn't cut off by an arbitrary fixed delay.
+        await Promise.all(this.workers.map(async (worker, idx) => {
+            let exitCode;
+            if (this.exitedWorkers.has(worker)) {
+                // Already exited (e.g. crashed with no restartOnExit, before stop() was ever called) - there's
+                // nothing to wait for or terminate.
+                exitCode = 0;
+            }
+            else {
+                const exitedOnOwn = new Promise((resolve) => worker.once("exit", resolve));
+                const timedOut = sleep(ThreadPool.STOP_GRACE_PERIOD_MS).then(() => undefined);
+                exitCode = await Promise.race([exitedOnOwn, timedOut]);
+                if (exitCode === undefined) {
+                    exitCode = await worker.terminate();
+                }
+            }
             if (listeners) {
                 for (const callback of listeners) {
                     callback(idx, exitCode);
                 }
             }
-        }
+        }));
         // Drop all terminated workers so `size`/`send()` don't keep referencing dead workers across a
         // subsequent start()/stop() cycle. `workers` is a `readonly` array reference, so it's truncated in place.
         this.workers.length = 0;
@@ -237,7 +366,9 @@ export class ThreadPool {
         let idx = startIdx;
         do {
             const worker = this.workers[idx];
-            if (worker) {
+            // Skip a worker that has already exited (e.g. crashed with no restartOnExit) rather than trying the
+            // next one - postMessage() throws synchronously on an exited worker.
+            if (worker && !this.exitedWorkers.has(worker)) {
                 worker.postMessage(msg);
                 this.lastThread = idx;
                 return;
@@ -247,12 +378,16 @@ export class ThreadPool {
         throw new Error("No available workers in the pool.");
     }
     /**
-     * Sends the provided message to all worker threads in the pool.
+     * Sends the provided message to all worker threads in the pool. Workers that have already exited (e.g.
+     * crashed with no `restartOnExit`) are silently skipped rather than throwing, so one dead worker doesn't
+     * prevent delivery to every worker after it in the array.
      * @param msg The message to send to all workers.
      */
     sendAll(msg) {
         for (const worker of this.workers) {
-            worker.postMessage(msg);
+            if (!this.exitedWorkers.has(worker)) {
+                worker.postMessage(msg);
+            }
         }
     }
     /**
@@ -261,11 +396,16 @@ export class ThreadPool {
      * @param msg The message to send the next available worker thread.
      */
     sendTo(id, msg) {
-        if (this.workers[id]) {
-            this.workers[id].postMessage(msg);
+        const worker = this.workers[id];
+        if (worker && !this.exitedWorkers.has(worker)) {
+            worker.postMessage(msg);
         }
     }
 }
+/** The maximum amount of time, in milliseconds, `stop()` waits for a worker to exit on its own before force-terminating it. */
+ThreadPool.STOP_GRACE_PERIOD_MS = 5000;
+/** The default maximum amount of time, in milliseconds, `start()` waits for all workers to report readiness before rejecting. Overridable per-call via `WorkerOptions.startupTimeoutMs`. */
+ThreadPool.START_TIMEOUT_MS = 30000;
 __decorate([
     Logger,
     __metadata("design:type", Object)