@atolljs/core 0.1.13 → 0.1.15

package/dist/worker/workerBootstrap.js

@@ -1,12 +1,12 @@
-import { devtoolsEnabled as e, enableWorkerDevtoolsForwarding as t } from "../devtools.js";
-import { fmtBytes as n, scoped as r } from "../log.js";
-import { bindSharedMemories as i, getDefinedSharedMemoryCount as a } from "../contract/sharedMemory.js";
-import { measureAtoll as o } from "../userTiming.js";
-import { TaskRegistry as s } from "./registry.js";
-//#region src/worker/workerBootstrap.ts
-var c = r("worker"), l = (e, t, n, r) => {
+import { TaskRegistry as e } from "./registry.js";
+import { bindSharedMemories as t, getDefinedSharedMemoryCount as n } from "../contract/sharedMemory.js";
+import { devtoolsEnabled as r, enableWorkerDevtoolsForwarding as i } from "../devtools.js";
+import { fmtBytes as a, scoped as o } from "../log.js";
+import { measureAtoll as s } from "../userTiming.js";
+// src/worker/workerBootstrap.ts
+var c = o("worker"), l = (e, t, n, r) => {
 	let i = performance.now();
-	o(`atoll run ${e}`, n, i, {
+	s(`atoll run ${e}`, n, i, {
 		track: "tasks",
 		color: r ? "secondary" : "error",
 		properties: [["message", t], ["outcome", r ? "ok" : "error"]],
@@ -14,55 +14,43 @@ var c = r("worker"), l = (e, t, n, r) => {
 	});
 }, u = !1, d = !1;
 function f() {
-	if (!d) {
-		if (typeof self > "u") {
-			c.warn("workerBootstrap: no worker global found — skipping message wiring");
-			return;
-		}
-		d = !0, self.onmessage = async (r) => {
-			let o = r.data;
-			if (o.type === "INIT") {
-				u = !0, o.devtools && t(), a() > 0 && c.warn("pool sent INIT without memory, but shared-memory contracts are defined — field access will throw until bound"), c.info("initialized (message-only pool — no shared memory)");
+	d || (typeof self > "u" ? c.warn("workerBootstrap: no worker global found — skipping message wiring") : (d = !0, self.onmessage = async (o) => {
+		let s = o.data;
+		if (s.type === "INIT") u = !0, s.devtools && i(), n() > 0 && c.warn("pool sent INIT without memory, but shared-memory contracts are defined — field access will throw until bound"), c.info("initialized (message-only pool — no shared memory)");
+		else if (s.type === "INIT_MEMORY") {
+			let e = s.memory?.buffer ?? s.buffer;
+			if (!e) {
+				c.warn("INIT_MEMORY arrived without a buffer — contracts stay unbound");
 				return;
 			}
-			if (o.type === "INIT_MEMORY") {
-				let e = o.memory?.buffer ?? o.buffer;
-				if (!e) {
-					c.warn("INIT_MEMORY arrived without a buffer — contracts stay unbound");
-					return;
-				}
-				i(e), u = !0, o.devtools && t(), c.info(`shared memory initialized (${n(e.byteLength)})`);
+			t(e), u = !0, s.devtools && i(), c.info(`shared memory initialized (${a(e.byteLength)})`);
+		} else if (s.type === "EXECUTE_TASK") {
+			let { messageId: t, taskId: n, args: i } = s;
+			if (!u) {
+				c.warn(`rejected ${n} — shared memory not initialized`), self.postMessage({
+					messageId: t,
+					success: !1,
+					error: "Shared memory not initialized in worker."
+				});
 				return;
 			}
-			if (o.type === "EXECUTE_TASK") {
-				let { messageId: t, taskId: n, args: r } = o;
-				if (!u) {
-					c.warn(`rejected ${n} — shared memory not initialized`), self.postMessage({
-						messageId: t,
-						success: !1,
-						error: "Shared memory not initialized in worker."
-					});
-					return;
-				}
-				let i = performance.now();
-				try {
-					let a = await s.execute(n, ...r || []);
-					e() && l(n, t, i, !0), c.debug(`task ${n} → ${(performance.now() - i).toFixed(1)}ms`), self.postMessage({
-						messageId: t,
-						success: !0,
-						result: a
-					});
-				} catch (r) {
-					e() && l(n, t, i, !1), c.warn(`task ${n} failed: ${r.message || String(r)}`), self.postMessage({
-						messageId: t,
-						success: !1,
-						error: r.message || String(r)
-					});
-				}
+			let a = performance.now();
+			try {
+				let o = await e.execute(n, ...i || []);
+				r() && l(n, t, a, !0), c.debug(`task ${n} → ${(performance.now() - a).toFixed(1)}ms`), self.postMessage({
+					messageId: t,
+					success: !0,
+					result: o
+				});
+			} catch (e) {
+				r() && l(n, t, a, !1), c.warn(`task ${n} failed: ${e.message || String(e)}`), self.postMessage({
+					messageId: t,
+					success: !1,
+					error: e.message || String(e)
+				});
 			}
-		};
-	}
+		}
+	}));
 }
 queueMicrotask(f);
-//#endregion
 export { f as installWorkerListener };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/core",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Typed shared-memory worker pools — defineWorker/connectWorker, SharedArrayBuffer contracts, cross-thread reactivity",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
@@ -55,10 +55,10 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-vue": "^6.0.9",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^4.1.12",
     "esbuild": "0.28.2",
     "fast-json-stringify": "^7.0.1",
-    "happy-dom": "^20.14.5",
+    "happy-dom": "^21.0.4",
     "htmlparser2": "^12.0.0",
     "nx": "23.3.0",
     "react": "^19.3.0",
@@ -68,10 +68,10 @@
     "rxjs": "^7.8.2",
     "svelte": "^5.57.1",
     "typescript": "^7.0.2",
-    "vite": "^8.3.1",
-    "vitest": "^4.1.11",
+    "vite": "^8.3.5",
+    "vitest": "^4.1.12",
     "vue": "^3.5.43",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "dependencies": {
     "msgpackr": "^2.1.0",
@@ -79,7 +79,11 @@
   },
   "overrides": {
     "nx": {
-      "undici": "7.29.1"
+      "undici": "7.30.1",
+      "minimatch": "11.0.4"
+    },
+    "@nx/devkit": {
+      "minimatch": "11.0.4"
     }
   },
   "repository": {

package/src/contract/types.ts

@@ -41,6 +41,25 @@ export interface MemoryPersistence {
   stop(): void | Promise<void>;
 }
 
+/**
+ * A worker lifecycle transition, emitted by pools and dedicated workers
+ * through `onLifecycle`/`onWorkerEvent` — the seam error boundaries build
+ * on. `'error'` fires when a worker's error event lands (before respawn);
+ * `'respawn'` when the replacement is attached; `'terminate'` when the
+ * runner tears down deliberately.
+ */
+export interface WorkerLifecycleEvent {
+  type: 'error' | 'respawn' | 'terminate';
+  /** The emitting runner's devtools correlation id ('worker-N'/'pool-N'). */
+  poolId: string;
+  /** Worker slot in a pool; always 0 for a dedicated worker. */
+  slot?: number;
+  /** The crash/error message on 'error' events. */
+  message?: string;
+}
+
+export type WorkerLifecycleListener = (event: WorkerLifecycleEvent) => void;
+
 export interface WorkerPoolConfig<S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap> {
   /** Worker entry as a URL — e.g. `new URL('./worker.ts', import.meta.url)`. */
   workerUrl?: URL;
@@ -85,6 +104,13 @@ export interface WorkerPoolConfig<S extends SharedSpec = SharedSpec, T extends T
   maxQueue?: number;
   /** Default true — a worker 'error' rejects its in-flight tasks and spawns a replacement. */
   respawn?: boolean;
+  /**
+   * Lifecycle observer — called on worker 'error' (before respawn),
+   * 'respawn', and 'terminate'. Island boundaries subscribe through
+   * `client.onWorkerEvent` to detect crashes; config-level listeners get
+   * the same events.
+   */
+  onLifecycle?: WorkerLifecycleListener;
   /**
    * Default per-task timeout in ms (per-call `options.timeout` overrides).
    * The timer starts at enqueue, so it bounds queue-wait + execution together.

package/src/index.ts

@@ -48,6 +48,8 @@ export type {
   MemoryPersistence,
   SharedWorkerConfig,
   ViewType,
+  WorkerLifecycleEvent,
+  WorkerLifecycleListener,
   WorkerPoolConfig,
 } from './contract/types';
 

package/src/pool/dedicatedWorker.ts

@@ -1,7 +1,15 @@
 import type { MemoryManager } from './memory';
 import { TaskAbortedError, TaskTimeoutError, WorkerCrashedError } from './errors';
 import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
-import type { MemoryPersistence, TaskContract, TaskMap, TaskResult, WorkerPoolConfig } from '../contract/types';
+import type {
+  MemoryPersistence,
+  TaskContract,
+  TaskMap,
+  TaskResult,
+  WorkerLifecycleEvent,
+  WorkerLifecycleListener,
+  WorkerPoolConfig,
+} from '../contract/types';
 import { devtoolsEnabled, emitDevtools, estimateCloneBytes, nextDevtoolsId, type EmittedDevtoolsEvent } from '../devtools';
 import { fmtBytes, scoped } from '../log';
 import { measureTaskCall } from '../userTiming';
@@ -66,6 +74,7 @@ export class DedicatedWorker<S extends SharedSpec = SharedSpec> {
   private readonly mem: ChannelMemory<S>;
   private readonly spawn: () => Worker;
   private readonly respawn: boolean;
+  private readonly onLifecycle?: WorkerLifecycleListener;
   private readonly taskTimeout?: number;
   private readonly label?: string;
   private worker: Worker | null = null;
@@ -87,6 +96,7 @@ export class DedicatedWorker<S extends SharedSpec = SharedSpec> {
     const url = config.workerUrl;
     this.spawn = config.createWorker ?? (() => new Worker(url!, { type: 'module' }));
     this.respawn = config.respawn ?? true;
+    this.onLifecycle = config.onLifecycle;
     this.taskTimeout = config.taskTimeout;
     this.label = config.name;
     this.poolId = nextDevtoolsId('worker', config.name);
@@ -178,12 +188,18 @@ export class DedicatedWorker<S extends SharedSpec = SharedSpec> {
     this.checkDrained();
   }
 
+  /** Fan out a lifecycle transition — error boundaries subscribe through this. */
+  private lifecycle(type: WorkerLifecycleEvent['type'], message?: string): void {
+    this.onLifecycle?.({ type, poolId: this.poolId, slot: 0, message });
+  }
+
   private handleError(event: unknown): void {
     if (this.closed) return;
     const e = event as { message?: string; error?: Error } | undefined;
     const message = e?.message ?? (e?.error ? String(e.error) : 'worker error');
     workerLog.warn(`worker error: ${message}`);
     emitDevtools({ type: 'worker:error', poolId: this.poolId, slot: 0, message });
+    this.lifecycle('error', message);
     this.rejectPending(message);
     this.worker?.terminate();
     this.worker = null;
@@ -191,6 +207,7 @@ export class DedicatedWorker<S extends SharedSpec = SharedSpec> {
       workerLog.info('respawning crashed worker');
       this.attach(this.spawn());
       emitDevtools({ type: 'worker:respawn', poolId: this.poolId, slot: 0 });
+      this.lifecycle('respawn');
     }
     this.checkDrained();
   }
@@ -320,6 +337,7 @@ export class DedicatedWorker<S extends SharedSpec = SharedSpec> {
   public terminate(): void {
     if (this.closed) return;
     this.closed = true;
+    this.lifecycle('terminate');
     this.devtoolsOff?.();
     void this.persistence?.stop()?.catch?.((e: unknown) => workerLog.warn('memory persistence stop failed', e));
     workerLog.info('terminating dedicated worker');

package/src/pool/workerClient.ts

@@ -1,6 +1,10 @@
 import type { ServiceMethod, TaskRunner } from '../service';
 import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
-import type { MemoryConfig, Prettify } from '../contract/types';
+import type {
+  MemoryConfig,
+  Prettify,
+  WorkerLifecycleListener,
+} from '../contract/types';
 import { WorkerPool, type RunOptions } from './workerPool';
 import { DedicatedWorker } from './dedicatedWorker';
 import type {
@@ -123,6 +127,13 @@ export interface ConnectWorkerConfig<S extends SharedSpec> {
   maxQueue?: number;
   /** Default true — a crashed worker is replaced and its in-flight calls reject. */
   respawn?: boolean;
+  /**
+   * Lifecycle observer — fires on worker 'error' (before respawn),
+   * 'respawn', and 'terminate'. For per-callsite subscriptions (island
+   * boundaries, telemetry) prefer `client.onWorkerEvent(fn)`, which can be
+   * attached after connect and supports multiple listeners.
+   */
+  onLifecycle?: WorkerLifecycleListener;
   /** Default per-call timeout ms (`client.with({ timeout })` overrides). */
   taskTimeout?: number;
   /** Default true: pool spawns on first method call (or start()). False spawns immediately. */
@@ -153,6 +164,13 @@ export type WorkerClient<W extends WorkerDefinition, S extends SharedSpec> = Wor
    */
   readonly pool: WorkerRunner<S> | null;
   readonly sharedMemory: ConnectWorkerConfig<S>['sharedMemory'] | undefined;
+  /**
+   * Subscribe to worker lifecycle transitions ('error' | 'respawn' |
+   * 'terminate') — the crash-detection seam error boundaries build on.
+   * Listeners attach lazily: subscribing before the pool spawns still sees
+   * every event. Returns the unsubscribe.
+   */
+  onWorkerEvent(fn: WorkerLifecycleListener): () => void;
 };
 
 /**
@@ -181,6 +199,9 @@ export function connectWorker<
   S extends SharedSpec = W extends WorkerDefinition<infer X> ? X : SharedSpec,
 >(config: ConnectWorkerConfig<S>): WorkerClient<W, S> {
   let pool: WorkerRunner<S> | null = null;
+  // Lifecycle subscribers register before/after spawn identically — the set
+  // outlives any single runner, and the runner's config fan-out reads it.
+  const lifecycleSubs = new Set<WorkerLifecycleListener>();
   const spawn = (): WorkerRunner<S> => {
     if (pool) return pool;
     const count = resolveWorkerCount(config.workers ?? config.poolSize);
@@ -195,6 +216,10 @@ export function connectWorker<
       memory: config.memory,
       respawn: config.respawn,
       taskTimeout: config.taskTimeout,
+      onLifecycle: (event: Parameters<WorkerLifecycleListener>[0]) => {
+        config.onLifecycle?.(event);
+        for (const fn of [...lifecycleSubs]) fn(event);
+      },
     };
     pool =
       count === 1
@@ -224,6 +249,10 @@ export function connectWorker<
     get sharedMemory() {
       return config.sharedMemory;
     },
+    onWorkerEvent: (fn: WorkerLifecycleListener): (() => void) => {
+      lifecycleSubs.add(fn);
+      return () => lifecycleSubs.delete(fn);
+    },
   };
 
   return makeClientProxy([], spawn, reserved) as WorkerClient<W, S>;

package/src/pool/workerPool.ts

@@ -1,7 +1,7 @@
 import type { MemoryManager } from './memory';
 import { PoolQueueFullError, TaskAbortedError, TaskTimeoutError, WorkerCrashedError } from './errors';
 import { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
-import { MemoryPersistence, PoolTasks, TaskContract, TaskMap, TaskResult, WorkerPoolConfig } from '../contract/types';
+import { MemoryPersistence, PoolTasks, TaskContract, TaskMap, TaskResult, WorkerLifecycleEvent, WorkerLifecycleListener, WorkerPoolConfig } from '../contract/types';
 import { devtoolsEnabled, emitDevtools, estimateCloneBytes, nextDevtoolsId, type EmittedDevtoolsEvent } from '../devtools';
 import { measureTaskCall } from '../userTiming';
 import { forwardWorkerDevtools, sendInit, setupChannelMemory, type ChannelMemory } from './workerChannel';
@@ -98,6 +98,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
   private readonly concurrency: number;
   private readonly maxQueue: number;
   private readonly respawn: boolean;
+  private readonly onLifecycle?: WorkerLifecycleListener;
   private readonly taskTimeout?: number;
   private closed = false;
   /** Dashboard fault injection (`pool.chaos`); null unless devtools set it. */
@@ -133,6 +134,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     this.concurrency = config.concurrency ?? 1;
     this.maxQueue = config.maxQueue ?? Infinity;
     this.respawn = config.respawn ?? true;
+    this.onLifecycle = config.onLifecycle;
     this.taskTimeout = config.taskTimeout;
     this.label = config.name;
     this.poolId = nextDevtoolsId('pool', config.name);
@@ -264,6 +266,11 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     this.checkDrained();
   }
 
+  /** Fan out a lifecycle transition — error boundaries subscribe through this. */
+  private lifecycle(type: WorkerLifecycleEvent['type'], slot?: number, message?: string): void {
+    this.onLifecycle?.({ type, poolId: this.poolId, slot, message });
+  }
+
   private handleWorkerError(slot: WorkerSlot, event: unknown) {
     if (this.closed) return; // pool terminated — a late error event can't respawn
     const e = event as { message?: string; error?: Error } | undefined;
@@ -271,6 +278,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     poolLog.warn(`worker error: ${message}`);
     const idx = this.slots.indexOf(slot);
     emitDevtools({ type: 'worker:error', poolId: this.poolId, slot: idx, message });
+    this.lifecycle('error', idx >= 0 ? idx : undefined, message);
 
     // Reject the dead worker's in-flight tasks. Orphaned (already
     // aborted/timed-out) entries are dropped without re-counting.
@@ -293,6 +301,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
       poolLog.info('respawning crashed worker');
       this.addWorker(this.spawn());
       emitDevtools({ type: 'worker:respawn', poolId: this.poolId, slot: this.slots.length - 1 });
+      this.lifecycle('respawn', this.slots.length - 1);
     } else if (this.slots.length === 0) {
       // No workers left to ever serve the queue.
       for (const entry of this.queue.splice(0)) {
@@ -495,6 +504,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
 
   public terminate(): void {
     this.closed = true;
+    this.lifecycle('terminate');
     this.devtoolsOff?.();
     // Final flush + release — fire-and-forget; terminate() stays synchronous.
     void this.persistence?.stop()?.catch?.((e: unknown) =>