@adukiorg/anza 0.2.0

package/src/core/workers/index.js

@@ -0,0 +1,169 @@
+/**
+ * src/core/workers/index.js
+ *
+ * Public workers entry point.
+ * Aggregates dedicated, pooled, shared, broadcast, locking, and offscreen
+ * primitives into a single unified public facade.
+ *
+ * Public API:
+ *   workers.run(script, task, opts)      – pool task
+ *   workers.dedicated(script)            – raw dedicated worker
+ *   workers.shared(script, name)         – shared worker connection
+ *   workers.lock(name, fn, opts)         – web lock
+ *   workers.broadcast(name, payload)     – fire-and-forget broadcast
+ *   workers.subscribe(name, fn, signal)  – channel subscription
+ *   workers.offscreen(canvas, script, opts) – offscreen canvas
+ *   workers.close(script)               – terminate one pool
+ *   workers.clear()                     – terminate all pools + clear broadcasts
+ *
+ * Feature gates:
+ *   has.worker, has.shared, has.channel, has.locks, has.offscreen, has.isolated
+ *
+ * Source: plan.md Phase 8
+ */
+
+import { Dedicated, DedicatedWorker } from './dedicated.js';
+import { Pool, WorkerPool } from './pool.js';
+import { Shared, SharedConnection } from './shared.js';
+import { broadcast } from './broadcast.js';
+import { lock } from './locks.js';
+import { offscreen, Offscreen, OffscreenHandle } from './offscreen.js';
+
+/** Runtime feature detection */
+export const has = {
+  worker: typeof Worker !== 'undefined',
+  shared: typeof SharedWorker !== 'undefined',
+  channel: typeof BroadcastChannel !== 'undefined',
+  locks: typeof navigator !== 'undefined' && !!navigator.locks,
+  offscreen: typeof OffscreenCanvas !== 'undefined',
+  isolated: typeof crossOriginIsolated !== 'undefined' && crossOriginIsolated
+};
+
+// Pool registry — one pool per script URL
+const pools = new Map();
+
+export const workers = {
+  /**
+   * Runs a prioritized CPU-bound task in a lazily allocated dedicated worker pool.
+   *
+   * @param {string} script - Worker script URL
+   * @param {string} task   - Task name
+   * @param {object} [opts] - TaskOptions: payload, priority, signal, timeout, transferables, meta
+   */
+  run(script, task, opts = {}) {
+    if (!has.worker) {
+      return Promise.reject(new Error('Web Workers are not available in this environment'));
+    }
+    if (!pools.has(script)) {
+      pools.set(script, new Pool(script, opts));
+    }
+    return pools.get(script).run(task, opts);
+  },
+
+  /**
+   * Creates a raw Dedicated worker (not pooled).
+   * Use this when you need a single long-lived worker with direct control.
+   *
+   * @param {string} script
+   * @returns {Dedicated}
+   */
+  dedicated(script) {
+    if (!has.worker) {
+      throw new Error('Web Workers are not available in this environment');
+    }
+    return new Dedicated(script);
+  },
+
+  /**
+   * Opens a connection to a SharedWorker (or dedicated fallback).
+   *
+   * @param {string} script
+   * @param {string} [name]
+   * @returns {Shared}
+   */
+  shared(script, name) {
+    const connection = new Shared(script, name);
+    connection.connect();
+    return connection;
+  },
+
+  /**
+   * Acquires a named Web Lock and executes `fn` within it.
+   * See locks.js for lock name conventions and option details.
+   */
+  lock,
+
+  /**
+   * Sends a message to a named BroadcastChannel.
+   *
+   * @param {string} name
+   * @param {any}    payload
+   */
+  broadcast(name, payload) {
+    if (!has.channel) return; // degrade silently — optional cross-tab notification
+    broadcast.broadcast(name, payload);
+  },
+
+  /**
+   * Subscribes to messages on a named BroadcastChannel.
+   * Returns a dispose function.
+   *
+   * @param {string}      name
+   * @param {Function}    fn
+   * @param {AbortSignal} [signal]
+   */
+  subscribe(name, fn, signal) {
+    if (!has.channel) return () => {};
+    return broadcast.subscribe(name, fn, signal);
+  },
+
+  /**
+   * Transfers an HTMLCanvasElement to a worker for off-main-thread rendering.
+   * Returns a Promise that resolves to an Offscreen handle after the ready
+   * handshake completes.
+   *
+   * @param {HTMLCanvasElement} canvas
+   * @param {string}            script
+   * @param {object}            [opts]
+   */
+  offscreen,
+
+  /**
+   * Terminates the pool for one script URL and removes it from the registry.
+   *
+   * @param {string} script
+   */
+  close(script) {
+    const pool = pools.get(script);
+    if (pool) {
+      pool.terminate();
+      pools.delete(script);
+    }
+  },
+
+  /**
+   * Terminates all pools and clears all broadcast channels.
+   */
+  clear() {
+    for (const [script, pool] of pools) {
+      pool.terminate();
+      pools.delete(script);
+    }
+    broadcast.clear();
+  }
+};
+
+export {
+  Dedicated,
+  Pool,
+  Shared,
+  Offscreen,
+  broadcast,
+  lock,
+  offscreen,
+  // Compatibility aliases
+  DedicatedWorker,
+  WorkerPool,
+  SharedConnection,
+  OffscreenHandle
+};

package/src/core/workers/locks.js

@@ -0,0 +1,160 @@
+/**
+ * src/core/workers/locks.js
+ *
+ * Web Locks API Facade.
+ * Provides exclusive or shared operational execution blocks with AbortSignal
+ * and timeout controls. Combines caller signal + timeout into a single signal.
+ * Exposes ifAvailable and steal modes. Falls back to a same-tab queue when
+ * the Web Locks API is unavailable.
+ *
+ * Lock name conventions:
+ *   idb:<store>      – IndexedDB store access
+ *   opfs:<file>      – Origin Private File System file
+ *   auth:<op>        – Authentication operation (e.g. auth:refresh)
+ *   sync:<role>      – Background sync (e.g. sync:leader)
+ *   cache:<name>     – Cache invalidation (e.g. cache:avatar)
+ *
+ * Source: plan.md Phase 6
+ */
+
+// Same-tab fallback queue when Web Locks API is absent.
+// Maps lock name → Promise chain (exclusive, ordered).
+const fallbackQueue = new Map();
+
+/**
+ * Acquires a named lock and executes `fn` within it.
+ *
+ * @param {string}   name        Lock name (see conventions above)
+ * @param {Function} fn          Async callback to execute while holding the lock
+ * @param {object}   [options]
+ * @param {AbortSignal} [options.signal]      External abort signal
+ * @param {'exclusive'|'shared'} [options.mode='exclusive']
+ * @param {number}   [options.timeout]        ms before acquisition times out
+ * @param {boolean}  [options.ifAvailable]    Acquire only if lock is immediately available
+ * @param {boolean}  [options.steal]          Forcibly pre-empt any existing holder
+ * @returns {Promise<any>}
+ */
+export async function lock(name, fn, options = {}) {
+  const { signal, mode = 'exclusive', timeout, ifAvailable = false, steal = false } = options;
+
+  // -- Same-tab fallback --
+  if (typeof navigator === 'undefined' || !navigator.locks) {
+    return _fallback(name, fn, { signal, timeout, ifAvailable });
+  }
+
+  // -- Combine signal + timeout --
+  let controller = null;
+  let timer = null;
+
+  if (signal || timeout) {
+    controller = new AbortController();
+
+    if (signal) {
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+      } else {
+        signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+      }
+    }
+
+    if (timeout) {
+      timer = setTimeout(() => {
+        const reason = new Error(`Lock "${name}" acquisition timed out after ${timeout}ms`);
+        reason.name = 'TimeoutError';
+        controller.abort(reason);
+      }, timeout);
+    }
+  }
+
+  const active = controller?.signal ?? undefined;
+
+  const requestOpts = { mode, signal: active };
+  if (ifAvailable) requestOpts.ifAvailable = true;
+  if (steal) requestOpts.steal = true;
+
+  try {
+    return await navigator.locks.request(name, requestOpts, async (acquired) => {
+      // ifAvailable returns null when the lock is not immediately grantable
+      if (acquired === null) {
+        throw new DOMException(`Lock "${name}" is not available`, 'NotAllowedError');
+      }
+      return await fn();
+    });
+  } catch (err) {
+    // Rethrow AbortError with the original abort reason when present
+    if (err.name === 'AbortError' && active?.aborted) {
+      throw active.reason ?? err;
+    }
+    throw err;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Same-tab mutual exclusion fallback (no Web Locks API).
+ * Uses a promise chain to serialise callbacks for each lock name.
+ * Does not support shared mode (all locks are exclusive in fallback).
+ */
+async function _fallback(name, fn, { signal, timeout, ifAvailable } = {}) {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('Aborted', 'AbortError');
+  }
+
+  if (ifAvailable) {
+    // In fallback mode we cannot check availability — always treat as unavailable
+    // when there is already an active chain for this name.
+    if (fallbackQueue.has(name)) {
+      throw new DOMException(`Lock "${name}" is not available (fallback)`, 'NotAllowedError');
+    }
+  }
+
+  const prior = fallbackQueue.get(name) ?? Promise.resolve();
+
+  let resolveChain;
+  const link = new Promise((res) => { resolveChain = res; });
+  fallbackQueue.set(name, prior.then(() => link));
+
+  let timer = null;
+  let controller = null;
+
+  if (signal || timeout) {
+    controller = new AbortController();
+    if (signal) {
+      signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+    }
+    if (timeout) {
+      timer = setTimeout(() => {
+        const r = new Error(`Lock "${name}" acquisition timed out after ${timeout}ms`);
+        r.name = 'TimeoutError';
+        controller.abort(r);
+      }, timeout);
+    }
+  }
+
+  const combined = controller?.signal;
+
+  try {
+    // Wait for the chain, but bail early if aborted while queued
+    await Promise.race([
+      prior,
+      ...(combined
+        ? [new Promise((_, rej) => combined.addEventListener('abort', () => rej(combined.reason), { once: true }))]
+        : [])
+    ]);
+
+    if (combined?.aborted) {
+      throw combined.reason ?? new DOMException('Aborted', 'AbortError');
+    }
+
+    return await fn();
+  } finally {
+    if (timer) clearTimeout(timer);
+    resolveChain();
+    // Clean up the map when the chain is idle
+    const remaining = fallbackQueue.get(name);
+    if (remaining === prior.then(() => link)) {
+      fallbackQueue.delete(name);
+    }
+  }
+}

package/src/core/workers/offscreen.js

@@ -0,0 +1,166 @@
+/**
+ * src/core/workers/offscreen.js
+ *
+ * OffscreenCanvas Transfer Lifecycle.
+ * Hands canvas rendering to a background Worker. The worker must respond with
+ * { ok: true } on its port after receiving the canvas to signal readiness.
+ *
+ * Lifecycle:
+ *   open()   – transfer canvas + wait for ready acknowledgement
+ *   send()   – dispatch render commands
+ *   resize() – forward new dimensions and device pixel ratio
+ *   close()  – terminate the worker (terminate() is an alias)
+ *
+ * Source: plan.md Phase 7
+ */
+
+export class Offscreen {
+  #canvas;
+  #script;
+  #worker = null;
+  #port = null;
+  #ready = false;
+  #closed = false;
+  #onError;
+  #onResize;
+
+  /**
+   * @param {HTMLCanvasElement} canvas
+   * @param {string}            script   Worker script URL
+   * @param {object}            [opts]
+   * @param {Function}          [opts.onError]   Called when the worker reports an error
+   * @param {Function}          [opts.onResize]  Called after a resize message is forwarded
+   */
+  constructor(canvas, script, opts = {}) {
+    this.#canvas = canvas;
+    this.#script = script;
+    this.#onError = opts.onError ?? null;
+    this.#onResize = opts.onResize ?? null;
+  }
+
+  get ready() { return this.#ready; }
+  get closed() { return this.#closed; }
+
+  /**
+   * Transfers canvas control to the worker and waits for the ready handshake.
+   *
+   * The worker must send `{ ok: true }` on the received port after it has
+   * initialised its rendering context.
+   *
+   * @returns {Promise<this>}
+   */
+  open() {
+    if (this.#closed) {
+      return Promise.reject(new Error('OffscreenCanvas handle is closed'));
+    }
+    if (this.#ready) {
+      return Promise.resolve(this);
+    }
+
+    if (!this.#supports()) {
+      return Promise.reject(new Error('OffscreenCanvas is not supported in this environment'));
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        const offscreen = this.#canvas.transferControlToOffscreen();
+        this.#worker = new Worker(this.#script, { type: 'module' });
+
+        this.#worker.addEventListener('error', (e) => {
+          const err = new Error(e.message ?? 'Worker error');
+          if (!this.#ready) {
+            reject(err);
+          }
+          this.#onError?.(err);
+        });
+
+        // MessageChannel for the ready handshake
+        const channel = new MessageChannel();
+        this.#port = channel.port1;
+
+        this.#port.onmessage = (e) => {
+          if (!this.#ready && e.data?.ok) {
+            this.#ready = true;
+            resolve(this);
+          }
+        };
+
+        this.#worker.postMessage(
+          { canvas: offscreen, port: channel.port2 },
+          [offscreen, channel.port2]
+        );
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Sends a render command to the worker.
+   *
+   * @param {any}           payload
+   * @param {Transferable[]} [transferables]
+   */
+  send(payload, transferables = []) {
+    if (this.#closed) throw new Error('OffscreenCanvas handle is closed');
+    if (!this.#ready) throw new Error('OffscreenCanvas handle is not ready — call open() first');
+    this.#port.postMessage(payload, transferables);
+  }
+
+  /**
+   * Forwards updated dimensions and device pixel ratio to the worker.
+   *
+   * @param {object} [opts]
+   * @param {number} [opts.width]   New CSS width in pixels (defaults to canvas.clientWidth)
+   * @param {number} [opts.height]  New CSS height in pixels (defaults to canvas.clientHeight)
+   * @param {number} [opts.dpr]     Device pixel ratio (defaults to devicePixelRatio)
+   */
+  resize(opts = {}) {
+    const width = opts.width ?? this.#canvas.clientWidth;
+    const height = opts.height ?? this.#canvas.clientHeight;
+    const dpr = opts.dpr ?? (typeof devicePixelRatio !== 'undefined' ? devicePixelRatio : 1);
+    this.send({ type: 'resize', width, height, dpr });
+    this.#onResize?.({ width, height, dpr });
+  }
+
+  /**
+   * Terminates the worker and releases the handle.
+   * `terminate()` is kept as an alias for back-compat.
+   */
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#ready = false;
+    try { this.#port?.close(); } catch { /* best-effort */ }
+    try { this.#worker?.terminate(); } catch { /* best-effort */ }
+    this.#port = null;
+    this.#worker = null;
+  }
+
+  terminate() { return this.close(); }
+
+  #supports() {
+    return (
+      typeof OffscreenCanvas !== 'undefined' &&
+      typeof this.#canvas.transferControlToOffscreen === 'function'
+    );
+  }
+}
+
+// Compatibility alias
+export { Offscreen as OffscreenHandle };
+
+/**
+ * Convenience factory — creates an Offscreen handle, transfers the canvas,
+ * and returns the instance (ready state established after the returned
+ * promise resolves).
+ *
+ * @param {HTMLCanvasElement} canvas
+ * @param {string}            script
+ * @param {object}            [opts]
+ * @returns {Promise<Offscreen>}
+ */
+export function offscreen(canvas, script, opts = {}) {
+  const handle = new Offscreen(canvas, script, opts);
+  return handle.open();
+}