@atolljs/core 0.1.13 → 0.1.15

package/dist/pool/dedicatedWorker.js

@@ -1,11 +1,11 @@
-import { devtoolsEnabled as e, emitDevtools as t, estimateCloneBytes as n, nextDevtoolsId as r } from "../devtools.js";
-import { fmtBytes as i, scoped as a } from "../log.js";
-import { TaskAbortedError as o, TaskTimeoutError as s, WorkerCrashedError as c } from "./errors.js";
+import { TaskAbortedError as e, TaskTimeoutError as t, WorkerCrashedError as n } from "./errors.js";
+import { devtoolsEnabled as r, emitDevtools as i, estimateCloneBytes as a, nextDevtoolsId as o } from "../devtools.js";
+import { fmtBytes as s, scoped as c } from "../log.js";
 import { measureTaskCall as l } from "../userTiming.js";
 import { forwardWorkerDevtools as u, sendInit as d, setupChannelMemory as f } from "./workerChannel.js";
 import { CHAOS_FAILURE as p, KILL_MESSAGE as m, applyChaos as h, registerDevtoolsRunner as g } from "./devtoolsCommands.js";
-//#region src/pool/dedicatedWorker.ts
-var _ = a("worker"), v = a("task"), y = () => ({
+// src/pool/dedicatedWorker.ts
+var _ = c("worker"), v = c("task"), y = () => ({
 	count: 0,
 	mean: 0,
 	max: 0,
@@ -19,6 +19,7 @@ var _ = a("worker"), v = a("task"), y = () => ({
 	mem;
 	spawn;
 	respawn;
+	onLifecycle;
 	taskTimeout;
 	label;
 	worker = null;
@@ -35,20 +36,20 @@ var _ = a("worker"), v = a("task"), y = () => ({
 		aborted: 0,
 		runMs: y()
 	};
-	constructor(n) {
-		if (this.mem = f(n, "DedicatedWorker"), !n.workerUrl && !n.createWorker) throw Error("DedicatedWorker requires either `workerUrl` or `createWorker` in its config.");
-		let a = n.workerUrl;
-		this.spawn = n.createWorker ?? (() => new Worker(a, { type: "module" })), this.respawn = n.respawn ?? !0, this.taskTimeout = n.taskTimeout, this.label = n.name, this.poolId = r("worker", n.name), this.sharedMemory = this.mem.sharedMemory, this.persistence = this.mem.persistence;
-		let o = this.mem.sharedMemory?.totalBytes ?? this.mem.injectedBuffer?.byteLength;
-		_.info(o === void 0 ? "spawning 1 dedicated worker, message-only" : `spawning 1 dedicated worker with ${i(o)} shared buffer`), t({
+	constructor(e) {
+		if (this.mem = f(e, "DedicatedWorker"), !e.workerUrl && !e.createWorker) throw Error("DedicatedWorker requires either `workerUrl` or `createWorker` in its config.");
+		let t = e.workerUrl;
+		this.spawn = e.createWorker ?? (() => new Worker(t, { type: "module" })), this.respawn = e.respawn ?? !0, this.onLifecycle = e.onLifecycle, this.taskTimeout = e.taskTimeout, this.label = e.name, this.poolId = o("worker", e.name), this.sharedMemory = this.mem.sharedMemory, this.persistence = this.mem.persistence;
+		let n = this.mem.sharedMemory?.totalBytes ?? this.mem.injectedBuffer?.byteLength;
+		_.info(n === void 0 ? "spawning 1 dedicated worker, message-only" : `spawning 1 dedicated worker with ${s(n)} shared buffer`), i({
 			type: "pool:init",
 			poolId: this.poolId,
 			label: this.label,
 			poolSize: 1,
 			concurrency: 0,
-			memoryBytes: o,
+			memoryBytes: n,
 			dedicated: !0
-		}), this.attach(this.spawn()), e() && (this.devtoolsOff = g({
+		}), this.attach(this.spawn()), r() && (this.devtoolsOff = g({
 			poolId: this.poolId,
 			label: this.label,
 			dedicated: !0,
@@ -68,16 +69,12 @@ var _ = a("worker"), v = a("task"), y = () => ({
 		this.worker = e, e.addEventListener("message", (t) => {
 			if (this.worker !== e) return;
 			let n = t.data;
-			if (n.type === "ATOLL_DEVTOOLS" && n.event) {
-				u(this.poolId, 0, n.event);
-				return;
-			}
-			this.handleReply(n);
+			n.type === "ATOLL_DEVTOOLS" && n.event ? u(this.poolId, 0, n.event) : this.handleReply(n);
 		}), e.addEventListener("error", (t) => {
 			this.worker === e && this.handleError(t);
 		});
-		let n = d(e, this.mem);
-		_.debug(`dedicated worker spawned, ${n} sent`), t({
+		let t = d(e, this.mem);
+		_.debug(`dedicated worker spawned, ${t} sent`), i({
 			type: "worker:spawn",
 			poolId: this.poolId,
 			slot: 0
@@ -86,116 +83,124 @@ var _ = a("worker"), v = a("task"), y = () => ({
 	detach(e) {
 		e.timer && clearTimeout(e.timer), e.signal && e.onSignalAbort && e.signal.removeEventListener("abort", e.onSignalAbort);
 	}
-	handleReply(r) {
-		let i = r.messageId === void 0 ? void 0 : this.pending.get(r.messageId);
-		if (i) {
-			if (this.pending.delete(r.messageId), this.detach(i), !i.done) {
-				i.done = !0;
-				let a = performance.now() - i.sentAt;
-				this.statsAgg.runMs.add(a), r.success ? (this.statsAgg.completed++, v.debug(`← ${i.contract.taskId} ok`), e() && (t({
+	handleReply(e) {
+		let t = e.messageId === void 0 ? void 0 : this.pending.get(e.messageId);
+		if (t) {
+			if (this.pending.delete(e.messageId), this.detach(t), !t.done) {
+				t.done = !0;
+				let n = performance.now() - t.sentAt;
+				this.statsAgg.runMs.add(n), e.success ? (this.statsAgg.completed++, v.debug(`← ${t.contract.taskId} ok`), r() && (i({
 					type: "task:settle",
 					poolId: this.poolId,
-					callId: i.callId,
-					taskId: i.contract.taskId,
+					callId: t.callId,
+					taskId: t.contract.taskId,
 					outcome: "ok",
-					runMs: a,
-					resultBytes: n(r.result)
-				}), l(this.poolId, i.contract.taskId, i.callId, 0, i.sentAt, i.sentAt + a, !0)), i.resolve(r.result)) : (this.statsAgg.failed++, v.warn(`← ${i.contract.taskId} failed: ${r.error}`), e() && (t({
+					runMs: n,
+					resultBytes: a(e.result)
+				}), l(this.poolId, t.contract.taskId, t.callId, 0, t.sentAt, t.sentAt + n, !0)), t.resolve(e.result)) : (this.statsAgg.failed++, v.warn(`← ${t.contract.taskId} failed: ${e.error}`), r() && (i({
 					type: "task:settle",
 					poolId: this.poolId,
-					callId: i.callId,
-					taskId: i.contract.taskId,
+					callId: t.callId,
+					taskId: t.contract.taskId,
 					outcome: "error",
-					runMs: a,
-					error: r.error
-				}), l(this.poolId, i.contract.taskId, i.callId, 0, i.sentAt, i.sentAt + a, !1)), i.reject(Error(r.error)));
+					runMs: n,
+					error: e.error
+				}), l(this.poolId, t.contract.taskId, t.callId, 0, t.sentAt, t.sentAt + n, !1)), t.reject(Error(e.error)));
 			}
 			this.checkDrained();
 		}
 	}
+	lifecycle(e, t) {
+		this.onLifecycle?.({
+			type: e,
+			poolId: this.poolId,
+			slot: 0,
+			message: t
+		});
+	}
 	handleError(e) {
 		if (this.closed) return;
-		let n = e, r = n?.message ?? (n?.error ? String(n.error) : "worker error");
-		_.warn(`worker error: ${r}`), t({
+		let t = e, n = t?.message ?? (t?.error ? String(t.error) : "worker error");
+		_.warn(`worker error: ${n}`), i({
 			type: "worker:error",
 			poolId: this.poolId,
 			slot: 0,
-			message: r
-		}), this.rejectPending(r), this.worker?.terminate(), this.worker = null, this.respawn && (_.info("respawning crashed worker"), this.attach(this.spawn()), t({
+			message: n
+		}), this.lifecycle("error", n), this.rejectPending(n), this.worker?.terminate(), this.worker = null, this.respawn && (_.info("respawning crashed worker"), this.attach(this.spawn()), i({
 			type: "worker:respawn",
 			poolId: this.poolId,
 			slot: 0
-		})), this.checkDrained();
+		}), this.lifecycle("respawn")), this.checkDrained();
 	}
 	rejectPending(e) {
-		let n = new c(e);
-		for (let r of this.pending.values()) this.detach(r), !r.done && (r.done = !0, this.statsAgg.failed++, t({
+		let t = new n(e);
+		for (let n of this.pending.values()) this.detach(n), n.done || (n.done = !0, this.statsAgg.failed++, i({
 			type: "task:settle",
 			poolId: this.poolId,
-			callId: r.callId,
-			taskId: r.contract.taskId,
+			callId: n.callId,
+			taskId: n.contract.taskId,
 			outcome: "crashed",
 			error: e
-		}), r.reject(n));
+		}), n.reject(t));
 		this.pending.clear();
 	}
 	cancel(e, n) {
-		e.done || (e.done = !0, this.detach(e), this.statsAgg.aborted++, t({
+		e.done || (e.done = !0, this.detach(e), this.statsAgg.aborted++, i({
 			type: "task:settle",
 			poolId: this.poolId,
 			callId: e.callId,
 			taskId: e.contract.taskId,
-			outcome: n instanceof s ? "timeout" : "aborted"
+			outcome: n instanceof t ? "timeout" : "aborted"
 		}), e.reject(n));
 	}
 	checkDrained() {
 		if (!(this.pending.size > 0)) for (let e of this.drainWaiters.splice(0)) e();
 	}
-	dispatch(r, i, a) {
+	dispatch(o, s, c) {
 		let l = this.worker;
-		return this.closed || l === null ? Promise.reject(new c("DedicatedWorker has been terminated — no worker available.")) : a?.signal?.aborted ? Promise.reject(new o()) : new Promise((c, u) => {
+		return this.closed || l === null ? Promise.reject(new n("DedicatedWorker has been terminated — no worker available.")) : c?.signal?.aborted ? Promise.reject(new e()) : new Promise((n, u) => {
 			let d = {
-				contract: r,
+				contract: o,
 				callId: ++this.nextCallId,
 				sentAt: performance.now(),
-				resolve: c,
+				resolve: n,
 				reject: u,
 				done: !1,
-				signal: a?.signal
+				signal: c?.signal
 			};
-			a?.signal && (d.onSignalAbort = () => this.cancel(d, new o()), a.signal.addEventListener("abort", d.onSignalAbort, { once: !0 }));
-			let f = a?.timeout ?? this.taskTimeout;
-			f !== void 0 && (d.timer = setTimeout(() => this.cancel(d, new s()), f));
+			c?.signal && (d.onSignalAbort = () => this.cancel(d, new e()), c.signal.addEventListener("abort", d.onSignalAbort, { once: !0 }));
+			let f = c?.timeout ?? this.taskTimeout;
+			f !== void 0 && (d.timer = setTimeout(() => this.cancel(d, new t()), f));
 			let m = this.nextMessageId++;
-			this.pending.set(m, d), v.debug(`→ ${r.taskId}`, { args: i }), t({
+			this.pending.set(m, d), v.debug(`→ ${o.taskId}`, { args: s }), i({
 				type: "task:enqueue",
 				poolId: this.poolId,
 				callId: d.callId,
-				taskId: r.taskId
-			}), e() && t({
+				taskId: o.taskId
+			}), r() && i({
 				type: "task:dispatch",
 				poolId: this.poolId,
 				callId: d.callId,
-				taskId: r.taskId,
+				taskId: o.taskId,
 				slot: 0,
 				waitMs: 0,
-				argBytes: n(i)
+				argBytes: a(s)
 			});
 			let g = {
 				type: "EXECUTE_TASK",
 				messageId: m,
-				taskId: r.taskId,
-				args: i
+				taskId: o.taskId,
+				args: s
 			};
 			this.chaos ? h(this.chaos, {
 				live: () => this.pending.get(m) === d,
 				fail: () => this.handleReply({
 					messageId: m,
-					taskId: r.taskId,
+					taskId: o.taskId,
 					success: !1,
 					error: p
 				}),
-				timeout: () => this.cancel(d, new s()),
+				timeout: () => this.cancel(d, new t()),
 				post: () => l.postMessage(g)
 			}) : l.postMessage(g);
 		});
@@ -239,11 +244,10 @@ var _ = a("worker"), v = a("task"), y = () => ({
 		});
 	}
 	terminate() {
-		this.closed || (this.closed = !0, this.devtoolsOff?.(), this.persistence?.stop()?.catch?.((e) => _.warn("memory persistence stop failed", e)), _.info("terminating dedicated worker"), t({
+		this.closed || (this.closed = !0, this.lifecycle("terminate"), this.devtoolsOff?.(), this.persistence?.stop()?.catch?.((e) => _.warn("memory persistence stop failed", e)), _.info("terminating dedicated worker"), i({
 			type: "pool:terminate",
 			poolId: this.poolId
 		}), this.rejectPending("worker terminated"), this.worker?.terminate(), this.worker = null, this.checkDrained());
 	}
 };
-//#endregion
 export { b as DedicatedWorker };

package/dist/pool/devtoolsCommands.js

@@ -1,5 +1,5 @@
 import { registerDevtoolsCommand as e } from "../devtools.js";
-//#region src/pool/devtoolsCommands.ts
+// src/pool/devtoolsCommands.ts
 var t = "chaos: injected failure", n = "killed from devtools", r = /* @__PURE__ */ new Map(), i = null, a = (e) => {
 	let t = e.poolId;
 	if (typeof t != "string") throw Error("poolId (string) is required");
@@ -55,5 +55,4 @@ var t = "chaos: injected failure", n = "killed from devtools", r = /* @__PURE__
 		}
 	}, e.delayMs ?? 0);
 };
-//#endregion
 export { t as CHAOS_FAILURE, n as KILL_MESSAGE, d as applyChaos, s as parseChaos, u as registerDevtoolsRunner };

package/dist/pool/errors.js

@@ -1,4 +1,4 @@
-//#region src/pool/errors.ts
+// src/pool/errors.ts
 var e = class extends Error {
 	constructor(e = "WorkerPool task queue is full") {
 		super(e), this.name = "PoolQueueFullError";
@@ -16,5 +16,4 @@ var e = class extends Error {
 		super(e), this.name = "WorkerCrashedError";
 	}
 };
-//#endregion
 export { e as PoolQueueFullError, t as TaskAbortedError, n as TaskTimeoutError, r as WorkerCrashedError };

package/dist/pool/memory.js

@@ -1,4 +1,4 @@
-//#region src/pool/memory.ts
+// src/pool/memory.ts
 var e = class {
 	memory;
 	maxPages;
@@ -31,5 +31,4 @@ var e = class {
 		return this.memory.buffer;
 	}
 };
-//#endregion
 export { e as MemoryManager };

package/dist/pool/subWorkerClient.js

@@ -1,5 +1,5 @@
 import { connectWorker as e } from "./workerClient.js";
-//#region src/pool/subWorkerClient.ts
+// src/pool/subWorkerClient.ts
 function t(t) {
 	let n = { ...t };
 	return typeof t.worker != "function" && (n.worker = () => {
@@ -7,5 +7,4 @@ function t(t) {
 		return new Worker(t.worker, { type: "module" });
 	}), e(n);
 }
-//#endregion
 export { t as connectSubWorker };

package/dist/pool/workerChannel.js

@@ -1,50 +1,49 @@
-import { devtoolsEnabled as e, forwardDevtools as t } from "../devtools.js";
-import { MemoryManager as n } from "./memory.js";
-//#region src/pool/workerChannel.ts
-function r(e, t) {
-	if ((e.sharedMemory || e.sharedBuffer !== void 0) && (typeof SharedArrayBuffer > "u" || typeof crossOriginIsolated < "u" && !crossOriginIsolated)) throw Error(`${t} requires SharedArrayBuffer in a cross-origin isolated context — serve the page with COOP/COEP headers.`);
+import { MemoryManager as e } from "./memory.js";
+import { devtoolsEnabled as t, forwardDevtools as n } from "../devtools.js";
+// src/pool/workerChannel.ts
+function r(t, n) {
+	if ((t.sharedMemory || t.sharedBuffer !== void 0) && (typeof SharedArrayBuffer > "u" || typeof crossOriginIsolated < "u" && !crossOriginIsolated)) throw Error(`${n} requires SharedArrayBuffer in a cross-origin isolated context — serve the page with COOP/COEP headers.`);
 	let r;
-	if (e.sharedBuffer !== void 0 && (r = typeof e.sharedBuffer == "function" ? e.sharedBuffer() : e.sharedBuffer, !r)) throw Error(`${t}: \`sharedBuffer\` resolved to an empty buffer — the producing pool or contract has no bound memory yet.`);
-	if (!e.sharedMemory) return {
+	if (t.sharedBuffer !== void 0 && (r = typeof t.sharedBuffer == "function" ? t.sharedBuffer() : t.sharedBuffer, !r)) throw Error(`${n}: \`sharedBuffer\` resolved to an empty buffer — the producing pool or contract has no bound memory yet.`);
+	if (!t.sharedMemory) return {
 		sharedMemory: void 0,
 		injectedBuffer: r,
 		persistence: void 0
 	};
-	let i = e.sharedMemory, a;
-	return r ? i.bind(r) : (a = new n(e.memory), a.ensureCapacity(i.totalBytes), i.bind(a.getBuffer())), {
+	let i = t.sharedMemory, a;
+	return r ? i.bind(r) : (a = new e(t.memory), a.ensureCapacity(i.totalBytes), i.bind(a.getBuffer())), {
 		sharedMemory: i,
 		memoryManager: a,
 		injectedBuffer: r,
-		persistence: e.persistence?.(i)
+		persistence: t.persistence?.(i)
 	};
 }
-function i(t, n) {
-	return n.memoryManager ? (t.postMessage({
+function i(e, n) {
+	return n.memoryManager ? (e.postMessage({
 		type: "INIT_MEMORY",
 		memory: n.memoryManager.memory,
-		devtools: e()
-	}), "INIT_MEMORY") : n.injectedBuffer ? (t.postMessage({
+		devtools: t()
+	}), "INIT_MEMORY") : n.injectedBuffer ? (e.postMessage({
 		type: "INIT_MEMORY",
 		buffer: n.injectedBuffer,
-		devtools: e()
-	}), "INIT_MEMORY") : (t.postMessage({
+		devtools: t()
+	}), "INIT_MEMORY") : (e.postMessage({
 		type: "INIT",
-		devtools: e()
+		devtools: t()
 	}), "INIT");
 }
-function a(e, n, r) {
-	let i = (t) => `${e}#${n}~${t}`;
-	t({
+function a(e, t, r) {
+	let i = (n) => `${e}#${t}~${n}`;
+	n({
 		...r,
 		...r.poolId === void 0 ? {} : { poolId: i(r.poolId) },
 		worker: r.worker === void 0 ? {
 			poolId: e,
-			slot: n
+			slot: t
 		} : {
 			poolId: i(r.worker.poolId),
 			slot: r.worker.slot
 		}
 	});
 }
-//#endregion
 export { a as forwardWorkerDevtools, i as sendInit, r as setupChannelMemory };

package/dist/pool/workerClient.d.ts

@@ -1,6 +1,6 @@
 import type { ServiceMethod, TaskRunner } from '../service.js';
 import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory.js';
-import type { MemoryConfig, Prettify } from '../contract/types.js';
+import type { MemoryConfig, Prettify, WorkerLifecycleListener } from '../contract/types.js';
 import { WorkerPool, type RunOptions } from './workerPool.js';
 import { DedicatedWorker } from './dedicatedWorker.js';
 import type { WorkerDefinition, WorkerMethodMap } from '../worker/defineWorker.js';
@@ -62,6 +62,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. */
@@ -84,6 +91,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;
 };
 /**
  * One-line worker hookup for the main thread — the WorkerPool boilerplate

package/dist/pool/workerClient.js

@@ -1,6 +1,6 @@
 import { WorkerPool as e } from "./workerPool.js";
 import { DedicatedWorker as t } from "./dedicatedWorker.js";
-//#region src/pool/workerClient.ts
+// src/pool/workerClient.ts
 var n = (e, t, r, i) => {
 	let a = /* @__PURE__ */ new Map();
 	return new Proxy(() => {}, {
@@ -23,27 +23,31 @@ function r(e) {
 }
 var i = (e) => e === "auto" ? typeof navigator < "u" ? navigator.hardwareConcurrency ?? 4 : 4 : Math.max(1, Math.floor(e ?? 1));
 function a(r) {
-	let a = null, o = () => {
+	let a = null, o = /* @__PURE__ */ new Set(), s = () => {
 		if (a) return a;
-		let n = i(r.workers ?? r.poolSize), o = {
+		let n = i(r.workers ?? r.poolSize), s = {
 			sharedMemory: r.sharedMemory,
 			sharedBuffer: r.sharedBuffer,
 			createWorker: typeof r.worker == "function" ? r.worker : () => new Worker(r.worker, { type: "module" }),
 			name: r.name,
 			memory: r.memory,
 			respawn: r.respawn,
-			taskTimeout: r.taskTimeout
+			taskTimeout: r.taskTimeout,
+			onLifecycle: (e) => {
+				r.onLifecycle?.(e);
+				for (let t of [...o]) t(e);
+			}
 		};
-		return a = n === 1 ? new t(o) : new e({
-			...o,
+		return a = n === 1 ? new t(s) : new e({
+			...s,
 			poolSize: n,
 			concurrency: r.concurrency,
 			maxQueue: r.maxQueue
 		}), a;
 	};
-	return r.lazy === !1 && o(), n([], o, {
+	return r.lazy === !1 && s(), n([], s, {
 		start: () => {
-			o();
+			s();
 		},
 		terminate: () => {
 			a?.terminate(), a = null;
@@ -53,8 +57,8 @@ function a(r) {
 		},
 		get sharedMemory() {
 			return r.sharedMemory;
-		}
+		},
+		onWorkerEvent: (e) => (o.add(e), () => o.delete(e))
 	});
 }
-//#endregion
 export { a as connectWorker, i as resolveWorkerCount, r as workerClient };

package/dist/pool/workerPool.d.ts

@@ -51,6 +51,7 @@ declare class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     private readonly concurrency;
     private readonly maxQueue;
     private readonly respawn;
+    private readonly onLifecycle?;
     private readonly taskTimeout?;
     private closed;
     /** Dashboard fault injection (`pool.chaos`); null unless devtools set it. */
@@ -72,6 +73,8 @@ declare class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     /** Adds a spawned worker: one message + one error listener, then the INIT handshake. */
     private addWorker;
     private handleReply;
+    /** Fan out a lifecycle transition — error boundaries subscribe through this. */
+    private lifecycle;
     private handleWorkerError;
     /** Least-busy worker below its concurrency cap, if any. */
     private pickWorker;