@atolljs/core 0.1.0

package/src/task.ts

@@ -0,0 +1,99 @@
+import { scoped } from './log';
+import type { ObservableValue } from './observable';
+
+const taskLog = scoped('task');
+
+/**
+ * Point-in-time state of an {@link AsyncTask}. Replaced wholesale on every
+ * transition so `get()` stays stable for `useSyncExternalStore`-style
+ * adapters.
+ */
+export interface TaskSnapshot<R> {
+  /** Result of the last completed run; kept while a newer run is in flight. */
+  data: R | null;
+  pending: boolean;
+  /** True once any run has completed (success or failure). */
+  settled: boolean;
+  /** Wall-clock duration of the last completed run. */
+  elapsedMs: number | null;
+  error: unknown;
+}
+
+/**
+ * An async function turned into a subscribable task: `run` starts an
+ * invocation, and concurrent runs are latest-wins — a stale result is
+ * discarded rather than applied. Framework bindings subscribe to the
+ * snapshot; callers trigger `run`.
+ */
+export interface AsyncTask<A, R> extends ObservableValue<TaskSnapshot<R>> {
+  run(input: A): void;
+  /** No-op if a run is pending or has already settled — for init-style tasks. */
+  runOnce(input: A): void;
+}
+
+export function defineTask<A, R>(fn: (input: A) => Promise<R>): AsyncTask<A, R> {
+  let reqId = 0;
+  let snapshot: TaskSnapshot<R> = { data: null, pending: false, settled: false, elapsedMs: null, error: null };
+  const subscribers = new Set<(s: TaskSnapshot<R>) => void>();
+  const emit = (next: TaskSnapshot<R>) => {
+    snapshot = next;
+    for (const cb of subscribers) cb(next);
+  };
+
+  const task: AsyncTask<A, R> = {
+    get: () => snapshot,
+    subscribe(onChange) {
+      subscribers.add(onChange);
+      return () => {
+        subscribers.delete(onChange);
+      };
+    },
+    run(input: A) {
+      const id = ++reqId;
+      const t0 = performance.now();
+      emit({ ...snapshot, pending: true, error: null });
+      void fn(input).then(
+        (data) => {
+          if (id === reqId) emit({ data, pending: false, settled: true, elapsedMs: performance.now() - t0, error: null });
+        },
+        (error) => {
+          if (id === reqId) emit({ ...snapshot, pending: false, settled: true, error });
+          taskLog.error('task run failed', error);
+        }
+      );
+    },
+    runOnce(input: A) {
+      if (snapshot.pending || snapshot.settled) return;
+      task.run(input);
+    },
+  };
+  return task;
+}
+
+/** Structural check: run/runOnce triggers plus the observable contract. */
+export function isAsyncTask(x: unknown): x is AsyncTask<any, any> {
+  return (
+    typeof x === 'object' &&
+    x !== null &&
+    typeof (x as AsyncTask<any, any>).run === 'function' &&
+    typeof (x as AsyncTask<any, any>).runOnce === 'function' &&
+    typeof (x as AsyncTask<any, any>).get === 'function' &&
+    typeof (x as AsyncTask<any, any>).subscribe === 'function'
+  );
+}
+
+/**
+ * Accepts an {@link AsyncTask} or a plain async function and always returns
+ * a task — framework bindings (useTask, taskState, …) take either, so a
+ * worker client's method drops straight in:
+ *
+ *   const seed = useTask(initIncidents);            // async fn → defineTask
+ *   const page = useTask(incidents.queryIncidents); // client method → task
+ */
+export function toTask<R>(source: AsyncTask<void, R> | (() => Promise<R>)): AsyncTask<void, R>;
+export function toTask<A, R>(source: AsyncTask<A, R> | ((input: A) => Promise<R>)): AsyncTask<A, R>;
+export function toTask<A, R>(
+  source: AsyncTask<A, R> | ((input: A) => Promise<R>),
+): AsyncTask<A, R> {
+  return isAsyncTask(source) ? source : defineTask(source);
+}

package/src/testing/inProcessWorker.ts

@@ -0,0 +1,127 @@
+/**
+ * Test double for the Worker global that runs the real worker protocol
+ * in-process: INIT_MEMORY binds every defined shared-memory contract to the
+ * pool's buffer, EXECUTE_TASK dispatches through the real TaskRegistry.
+ * Everything except the OS thread boundary is real.
+ *
+ * Register worker-entry modules via `InProcessWorker.handlerModules` —
+ * importing them performs their TaskRegistry.register side effects, exactly
+ * what a bundled worker entry does at boot.
+ */
+import { bindSharedMemories } from '../contract/sharedMemory';
+import { TaskRegistry } from '../worker/registry';
+
+export class InProcessWorker {
+  static created: InProcessWorker[] = [];
+  static handlerModules: Array<() => Promise<unknown>> = [];
+
+  public executed: any[] = [];
+  public terminated = false;
+  private listeners = {
+    message: new Set<(event: { data: any }) => void>(),
+    error: new Set<(event: any) => void>(),
+  };
+  private ready: Promise<unknown> | null = null;
+  /** Module-load failure — a crashed worker never executes another task. */
+  private dead = false;
+
+  constructor(public url: URL, public options?: any) {
+    InProcessWorker.created.push(this);
+  }
+
+  postMessage(data: any) {
+    queueMicrotask(() => void this.handle(data));
+  }
+
+  /** Imports the registered handler modules — what a real worker's entry does at boot. */
+  private boot(): Promise<unknown> {
+    return (async () => {
+      // workerBootstrap assigns self.onmessage at module load — provide a
+      // minimal stand-in so the real worker entry can be imported in-process.
+      (globalThis as { self?: unknown }).self ??= {
+        postMessage() {},
+        onmessage: null,
+      };
+      for (const load of InProcessWorker.handlerModules) await load();
+    })();
+  }
+
+  /** Module-load failure = a real worker's 'error' event. */
+  private crashOnBoot(err: unknown): void {
+    // A real worker whose entry module fails to load fires 'error' and never
+    // answers a task — mirror that so pools reject in-flight calls (and
+    // respawn) instead of hanging on a ready that never resolves.
+    this.dead = true;
+    const event = {
+      type: 'error',
+      message: `worker entry failed to load: ${(err as Error)?.message ?? String(err)}`,
+      error: err instanceof Error ? err : new Error(String(err)),
+    };
+    for (const l of this.listeners.error) l(event);
+  }
+
+  private async handle(data: any) {
+    if (data.type === 'INIT') {
+      // Message-only pool — the entry still loads; just no shared buffer.
+      this.ready ??= this.boot();
+      try {
+        await this.ready;
+      } catch (err) {
+        this.crashOnBoot(err);
+      }
+      return;
+    }
+    if (data.type === 'INIT_MEMORY') {
+      this.ready ??= this.boot().then(() =>
+        bindSharedMemories((data.memory as WebAssembly.Memory).buffer as unknown as SharedArrayBuffer),
+      );
+      try {
+        await this.ready;
+      } catch (err) {
+        this.crashOnBoot(err);
+      }
+      return;
+    }
+    if (data.type === 'EXECUTE_TASK') {
+      if (this.dead) return;
+      try {
+        await this.ready;
+      } catch {
+        // Boot failed in the meantime — a crashed worker drops the task
+        // (the INIT handler already fired 'error').
+        return;
+      }
+      if (this.dead) return;
+      this.executed.push(data);
+      try {
+        const result = await TaskRegistry.execute(data.taskId, ...(data.args || []));
+        this.emit({ messageId: data.messageId, success: true, result });
+      } catch (err: any) {
+        this.emit({ messageId: data.messageId, success: false, error: err.message || String(err) });
+      }
+    }
+  }
+
+  private emit(msg: any) {
+    for (const l of this.listeners.message) l({ data: msg });
+  }
+
+  /** Simulates a worker crash: fires 'error' listeners like a real worker's error event. */
+  crash(message = 'simulated crash') {
+    const event = { type: 'error', message, error: new Error(message) };
+    for (const l of this.listeners.error) l(event);
+  }
+
+  addEventListener(type: string, l: (event: any) => void) {
+    if (type === 'error') this.listeners.error.add(l);
+    else this.listeners.message.add(l);
+  }
+  removeEventListener(type: string, l: (event: any) => void) {
+    if (type === 'error') this.listeners.error.delete(l);
+    else this.listeners.message.delete(l);
+  }
+  terminate() { this.terminated = true; }
+}
+
+/** Flushes microtasks + the waitAsync observer loop after a shared write. */
+export const flushObservers = () => new Promise((r) => setTimeout(r, 5));

package/src/worker/defineWorker.ts

@@ -0,0 +1,135 @@
+import './workerBootstrap'; // side-effect: wires self.onmessage (guarded for main-thread import)
+import { TaskRegistry } from './registry';
+import { scoped } from '../log';
+import type { ServiceMethod } from '../service';
+import type { SharedMemory, SharedSpec } from '../contract/sharedMemory';
+
+const workerLog = scoped('worker');
+
+/**
+ * One worker-exposed method: a plain function (siblings reachable via `this`)
+ * or a {@link ServiceMethod} unit (`{ def, run }` — schemas enforced on the
+ * wire).
+ */
+export type WorkerMethod = ((...args: any[]) => any) | ServiceMethod<any[], any>;
+export type WorkerMethodMap = Record<string, WorkerMethod>;
+export type WorkerServiceMap = Record<string, WorkerMethodMap>;
+
+type ReservedKey = (typeof RESERVED_CLIENT_KEYS)[number];
+
+/** Turns any reserved keys in M into `never`-typed members — a compile error. */
+type NoReserved<M> = [Extract<keyof M, ReservedKey>] extends [never]
+  ? M
+  : M & { [K in Extract<keyof M, ReservedKey>]: never };
+
+export interface DefineWorkerConfig<
+  S extends SharedSpec,
+  M extends WorkerMethodMap,
+  Svc extends WorkerServiceMap,
+> {
+  /**
+   * Optional — carried in the type so connectWorker can check the main-side
+   * contract matches. Binding is global via workerBootstrap.
+   */
+  sharedMemory?: SharedMemory<S>;
+  /** Flat methods → taskId = method name. */
+  methods?: NoReserved<M>;
+  /** Namespaced methods → taskId = `${service}.${method}`. */
+  services?: NoReserved<Svc>;
+}
+
+export interface WorkerDefinition<
+  S extends SharedSpec = SharedSpec,
+  M extends WorkerMethodMap = {},
+  Svc extends WorkerServiceMap = {},
+> {
+  readonly methods: M;
+  readonly services: Svc;
+  readonly sharedMemory?: SharedMemory<S>;
+}
+
+/**
+ * Client-surface keys a worker method must not claim — a method named
+ * `pool` or `then` would collide with {@link connectWorker}'s API (or make
+ * the client look like a thenable).
+ */
+export const RESERVED_CLIENT_KEYS = ['start', 'terminate', 'pool', 'sharedMemory', 'then', 'with'] as const;
+
+const isUnit = (x: unknown): x is ServiceMethod<any[], any> =>
+  typeof x === 'object' && x !== null && 'run' in x;
+
+const RESERVED = new Set<string>(RESERVED_CLIENT_KEYS);
+
+/**
+ * The worker-side half of the tRPC-style pair: the worker script owns the
+ * runtime (importing this module wires `self.onmessage` via workerBootstrap)
+ * and the method list — the main thread imports only `typeof` the returned
+ * definition and drives it through a {@link connectWorker} Proxy client.
+ *
+ *   // incidents.worker.ts — the whole worker entry
+ *   export const incidentsWorker = defineWorker({
+ *     sharedMemory: incidentsMemory,
+ *     methods: { seedIncidents, queryIncidents, computeMetrics },
+ *   });
+ *   export type IncidentsWorker = typeof incidentsWorker;
+ *
+ * Flat methods register under their own name; `services: { svc: { m } }`
+ * registers `svc.m`. Plain functions are invoked with `this` bound to the
+ * methods object (sibling calls); ServiceMethod units contribute their
+ * `def` schemas (and a `def.taskId` override) and run bound to the unit.
+ *
+ * BOOTSTRAP ORDERING (Node): the `@atolljs/node/shim` import must
+ * evaluate before this module — it binds `self = parentPort`, which
+ * workerBootstrap needs at import time. Keep `import '@atolljs/node/shim'`
+ * first in the worker entry.
+ */
+export function defineWorker<
+  S extends SharedSpec,
+  M extends WorkerMethodMap = {},
+  Svc extends WorkerServiceMap = {},
+>(config: DefineWorkerConfig<S, M, Svc>): WorkerDefinition<S, M, Svc> {
+  const methods = (config.methods ?? {}) as M;
+  const services = (config.services ?? {}) as Svc;
+
+  let count = 0;
+  const register = (taskId: string, name: string, method: WorkerMethod, thisArg: object) => {
+    if (RESERVED.has(name)) {
+      throw new Error(`defineWorker: "${name}" is reserved for the client API — rename the method`);
+    }
+    if (isUnit(method)) {
+      const { def } = method;
+      TaskRegistry.register(
+        {
+          taskId: def.taskId ?? taskId,
+          ...(def.dataType ? { dataType: def.dataType } : {}),
+          ...(def.argsSchema ? { argsSchema: def.argsSchema } : {}),
+          ...(def.resultSchema ? { resultSchema: def.resultSchema } : {}),
+        },
+        method.run.bind(method),
+      );
+    } else {
+      TaskRegistry.register({ taskId }, method.bind(thisArg));
+    }
+    count++;
+  };
+
+  for (const [name, method] of Object.entries(methods)) {
+    register(name, name, method, methods);
+  }
+  for (const [service, serviceMethods] of Object.entries(services)) {
+    if (RESERVED.has(service)) {
+      throw new Error(`defineWorker: service name "${service}" is reserved for the client API — rename it`);
+    }
+    for (const [name, method] of Object.entries(serviceMethods)) {
+      register(`${service}.${name}`, name, method, serviceMethods);
+    }
+  }
+
+  workerLog.info(`worker defined — ${count} method(s)`);
+
+  const definition: WorkerDefinition<S, M, Svc> = { methods, services };
+  if (config.sharedMemory) {
+    (definition as { sharedMemory?: SharedMemory<S> }).sharedMemory = config.sharedMemory;
+  }
+  return definition;
+}

package/src/worker/registry.ts

@@ -0,0 +1,42 @@
+import { TaskContract } from '../contract/types';
+import { scoped } from '../log';
+
+const regLog = scoped('registry');
+
+export type TaskHandler<Args extends any[] = any[], Result = any> =
+  (...args: Args) => Result | Promise<Result>;
+
+interface RegisteredTask {
+  contract: TaskContract;
+  handler: TaskHandler;
+}
+
+export class TaskRegistry {
+  private static tasks: Map<string, RegisteredTask> = new Map();
+
+  public static register<Args extends any[], Result>(
+    contract: TaskContract<Args, Result>,
+    handler: TaskHandler<Args, Result>
+  ): void {
+    this.tasks.set(contract.taskId, { contract, handler });
+    regLog.debug(`registered "${contract.taskId}"`, {
+      args: contract.argsSchema ? 'validated' : 'unvalidated',
+      result: contract.resultSchema ? 'validated' : 'unvalidated',
+    });
+  }
+
+  public static getContract(taskId: string): TaskContract | undefined {
+    return this.tasks.get(taskId)?.contract;
+  }
+
+  public static async execute(taskId: string, ...args: any[]): Promise<any> {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      throw new Error(`Task handler not found for id: ${taskId}`);
+    }
+    const { contract, handler } = task;
+    const validatedArgs = contract.argsSchema ? contract.argsSchema.parse(args) : args;
+    const result = await handler(...validatedArgs);
+    return contract.resultSchema ? contract.resultSchema.parse(result) : result;
+  }
+}

package/src/worker/workerBootstrap.ts

@@ -0,0 +1,56 @@
+import { TaskRegistry } from './registry';
+import { bindSharedMemories, getDefinedSharedMemoryCount } from '../contract/sharedMemory';
+import { fmtBytes, scoped } from '../log';
+
+const workerLog = scoped('worker');
+
+let memoryInitialized = false;
+
+if (typeof self === 'undefined') {
+  // Imported outside a worker context (e.g. a Nest entry that shares the
+  // atoll-nestjs barrel with the worker entry) — nothing to wire.
+  workerLog.warn('workerBootstrap: no worker global found — skipping message wiring');
+} else {
+  self.onmessage = async (event) => {
+  const data = event.data;
+
+  if (data.type === 'INIT') {
+    memoryInitialized = true;
+    if (getDefinedSharedMemoryCount() > 0) {
+      workerLog.warn(
+        'pool sent INIT without memory, but shared-memory contracts are defined — field access will throw until bound',
+      );
+    }
+    workerLog.info('initialized (message-only pool — no shared memory)');
+    return;
+  }
+
+  if (data.type === 'INIT_MEMORY') {
+    const memory = data.memory as WebAssembly.Memory;
+    bindSharedMemories(memory.buffer as unknown as SharedArrayBuffer);
+    memoryInitialized = true;
+    workerLog.info(`shared memory initialized (${fmtBytes(memory.buffer.byteLength)})`);
+    return;
+  }
+
+  if (data.type === 'EXECUTE_TASK') {
+    const { messageId, taskId, args } = data;
+
+    if (!memoryInitialized) {
+      workerLog.warn(`rejected ${taskId} — shared memory not initialized`);
+      self.postMessage({ messageId, success: false, error: 'Shared memory not initialized in worker.' });
+      return;
+    }
+
+    const t0 = performance.now();
+    try {
+      const result = await TaskRegistry.execute(taskId, ...(args || []));
+      workerLog.debug(`task ${taskId} → ${(performance.now() - t0).toFixed(1)}ms`);
+      self.postMessage({ messageId, success: true, result });
+    } catch (err: any) {
+      workerLog.warn(`task ${taskId} failed: ${err.message || String(err)}`);
+      self.postMessage({ messageId, success: false, error: err.message || String(err) });
+    }
+    }
+  };
+}