react-cheminfo 0.10.0 → 0.12.0

package/src/worker/core/workerChannel.ts

@@ -1,218 +1,250 @@
+import { toError } from '../../error/core/toError.ts';
+
 import { CancelledRequestError, RequestTimeoutError } from './errors.ts';
+import type { WorkerLike, WorkerRequestMessage } from './messages.ts';
+import type {
+  Outcome,
+  PendingRequest,
+  QueuedRequest,
+} from './workerChannelParts.ts';
+import {
+  DEFAULT_TIMEOUT_MS,
+  positiveMilliseconds,
+  postCancel,
+  runJobInProcess,
+  subscribeToWorker,
+  watchRequest,
+} from './workerChannelParts.ts';
 import type {
-  WorkerLike,
-  WorkerRequestMessage,
-  WorkerResponseMessage,
-} from './messages.ts';
+  WorkerChannel,
+  WorkerChannelOptions,
+  WorkerRequestOptions,
+  WorkerSource,
+} from './workerChannelTypes.ts';
 
 /**
  * Turn a worker into something a page can await.
  *
- * Several requests may be in flight at once; each one is tagged with an
- * identifier the answer echoes, so replies are matched to callers whatever
- * order they arrive in. A request that rejects — cancelled, timed out, or
- * failed — drops out of the pending map at that moment, so a page that fires
- * one job per keystroke never accumulates them.
+ * Every request is tagged with an identifier the answer echoes, so replies are
+ * matched to callers whatever order they arrive in, and a request that rejects
+ * — cancelled, superseded, timed out, or failed — drops out of the pending map
+ * at that moment. The worker may post progress about a job while it runs.
  *
- * The worker is the caller's: the channel posts to it and terminates it when
- * asked, but never creates one, which is what lets a site keep its own lazy
- * construction and its own in-process fallback.
- * @param worker - The worker to talk to, or anything that speaks its three calls.
+ * Handed a worker, the channel posts to it and terminates it when asked, but
+ * never creates one. Handed a function, it creates the worker on the first
+ * request, replaces one that failed or was terminated, and can fall back to an
+ * in-process run where there is no `Worker`.
+ * @param source - The worker, or the function that creates it.
  * @param options - See {@link WorkerChannelOptions}.
  * @returns The channel.
+ * @throws {Error} When the `restart` schedule is asked of a single worker, which cannot be restarted.
  */
-export function createWorkerChannel<TRequest, TResponse>(
-  worker: WorkerLike,
-  options: WorkerChannelOptions = {},
-): WorkerChannel<TRequest, TResponse> {
-  const name = options.name ?? 'worker';
-  const defaultTimeoutMs = positiveMilliseconds(
-    options.defaultTimeoutMs,
+export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
+  source: WorkerSource,
+  options: WorkerChannelOptions<TRequest, TResponse, TProgress> = {},
+): WorkerChannel<TRequest, TResponse, TProgress> {
+  const {
+    name = 'worker',
+    schedule = 'parallel',
+    cooperativeCancel = false,
+    defaultTimeoutMs,
+    runInProcess,
+  } = options;
+  const fallbackTimeoutMs = positiveMilliseconds(
+    defaultTimeoutMs,
     DEFAULT_TIMEOUT_MS,
   );
+  const factory = typeof source === 'function' ? source : undefined;
+  if (schedule === 'restart' && factory === undefined) {
+    throw new Error(`${name}: the restart schedule needs a worker factory`);
+  }
+  const hasNoWorker = !('Worker' in globalThis);
+  const runLocally = factory && hasNoWorker ? runInProcess : undefined;
 
-  const pending = new Map<number, PendingRequest<TResponse>>();
+  const pending = new Map<number, PendingRequest<TResponse, TProgress>>();
+  let worker: WorkerLike | null = null;
+  let closed = false;
   let nextId = 0;
-  let terminated = false;
+  let activeId: number | null = null;
+  let queued: QueuedRequest<TRequest> | null = null;
+  if (typeof source !== 'function') {
+    worker = source;
+    listen(source);
+  }
 
-  function settle(id: number): PendingRequest<TResponse> | undefined {
+  function take(id: number): PendingRequest<TResponse, TProgress> | undefined {
     const entry = pending.get(id);
-    if (entry === undefined) return undefined;
     pending.delete(id);
-    entry.dispose();
+    entry?.dispose();
     return entry;
   }
 
+  function complete(id: number, outcome: Outcome<TResponse>): void {
+    const entry = take(id);
+    if (outcome.ok) entry?.resolve(outcome.response);
+    else entry?.reject(outcome.error);
+    if (activeId === id) {
+      activeId = null;
+      startQueued();
+    }
+  }
+
+  function drop(id: number, error: Error): boolean {
+    const entry = take(id);
+    if (entry === undefined) return false;
+    entry.controller?.abort();
+    if (cooperativeCancel && entry.dispatched) postCancel(worker, id);
+    entry.reject(error);
+    return true;
+  }
+
+  function dropAll(reason: string): void {
+    for (const id of pending.keys()) {
+      drop(id, new CancelledRequestError(`${name} request ${id} ${reason}`));
+    }
+    queued = null;
+  }
+
   function rejectAll(error: Error): void {
     for (const entry of pending.values()) {
       entry.dispose();
+      entry.controller?.abort();
       entry.reject(error);
     }
     pending.clear();
+    activeId = null;
+    queued = null;
   }
 
-  worker.addEventListener('message', (event) => {
-    const message = event.data;
-    if (!isResponseMessage(message)) return;
-    const entry = settle(message.id);
-    if (entry === undefined) return;
-    if (message.ok) entry.resolve(message.response as TResponse);
-    else entry.reject(new Error(message.message));
-  });
+  function abandonActive(): void {
+    activeId = null;
+    if (factory !== undefined && worker !== null) {
+      worker.terminate();
+      worker = null;
+    }
+  }
 
-  worker.addEventListener('error', (event) => {
-    const detail = event.message ?? '';
-    rejectAll(
-      new Error(detail === '' ? `${name} failed` : `${name} failed: ${detail}`),
-    );
-  });
+  function startQueued(): void {
+    const next = queued;
+    queued = null;
+    if (next !== null) dispatch(next.id, next.payload, next.transfer);
+  }
 
-  return {
-    get pendingCount() {
-      return pending.size;
-    },
-    request: (payload: TRequest, requestOptions: WorkerRequestOptions = {}) => {
-      const { signal, timeoutMs } = requestOptions;
-      if (terminated) {
-        return Promise.reject(
-          new CancelledRequestError(`${name} was terminated`),
-        );
-      }
-      if (signal?.aborted === true) {
-        return Promise.reject(
-          new CancelledRequestError(`${name} request was cancelled`),
-        );
+  function dispatch(id: number, payload: TRequest, transfer?: Transferable[]) {
+    const entry = pending.get(id);
+    if (entry === undefined) return;
+    entry.dispatched = true;
+    if (schedule !== 'parallel') activeId = id;
+    if (runLocally !== undefined) {
+      entry.controller = runJobInProcess(
+        runLocally,
+        payload,
+        (progress) => pending.get(id)?.onProgress?.(progress),
+        (outcome) => complete(id, outcome),
+      );
+      return;
+    }
+    const message: WorkerRequestMessage<TRequest> = { id, request: payload };
+    try {
+      const target = currentWorker();
+      if (transfer === undefined) target.postMessage(message);
+      else target.postMessage(message, transfer);
+    } catch (error) {
+      complete(id, { ok: false, error: toError(error) });
+    }
+  }
+
+  function currentWorker(): WorkerLike {
+    if (worker === null) {
+      if (factory === undefined) {
+        throw new CancelledRequestError(`${name} was terminated`);
       }
+      worker = factory();
+      listen(worker);
+    }
+    return worker;
+  }
 
-      nextId += 1;
-      const id = nextId;
-      const budget = positiveMilliseconds(timeoutMs, defaultTimeoutMs);
-
-      return new Promise<TResponse>((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          settle(id)?.reject(
-            new RequestTimeoutError(
-              `${name} request ${id} timed out after ${budget} ms`,
-            ),
-          );
-        }, budget);
-        const onAbort = () => {
-          settle(id)?.reject(
-            new CancelledRequestError(`${name} request ${id} was cancelled`),
-          );
-        };
-        signal?.addEventListener('abort', onAbort);
-
-        pending.set(id, {
-          resolve,
-          reject,
-          dispose: () => {
-            clearTimeout(timeout);
-            signal?.removeEventListener('abort', onAbort);
-          },
-        });
-
-        const message: WorkerRequestMessage<TRequest> = {
-          id,
-          request: payload,
-        };
-        try {
-          worker.postMessage(message);
-        } catch (error) {
-          settle(id);
-          reject(error instanceof Error ? error : new Error(String(error)));
+  function listen(target: WorkerLike): void {
+    subscribeToWorker(target, {
+      progress: (id, progress) => {
+        if (target !== worker) return;
+        pending.get(id)?.onProgress?.(progress as TProgress);
+      },
+      answer: (id, outcome) => {
+        if (target === worker) complete(id, outcome as Outcome<TResponse>);
+      },
+      failure: (detail) => {
+        if (target !== worker) return;
+        if (factory !== undefined) {
+          target.terminate();
+          worker = null;
         }
-      });
-    },
-    terminate: () => {
-      terminated = true;
-      rejectAll(new CancelledRequestError(`${name} was terminated`));
-      worker.terminate();
-    },
-  };
-}
-
-/** How a channel names itself and how long it waits. */
-export interface WorkerChannelOptions {
-  /**
-   * What the channel is called in the message of an error it raises, e.g.
-   * `conformers`.
-   * @default 'worker'
-   */
-  name?: string;
-  /**
-   * Milliseconds a request waits before it is given up on, when the call passes
-   * no budget of its own. A value that is not a positive finite number falls
-   * back to two minutes.
-   * @default 120000
-   */
-  defaultTimeoutMs?: number;
-}
+        const suffix = detail === '' ? '' : `: ${detail}`;
+        rejectAll(new Error(`${name} failed${suffix}`));
+      },
+    });
+  }
 
-/** What one call may ask of the channel. */
-export interface WorkerRequestOptions {
-  /**
-   * Abort the call. Its promise then rejects with a
-   * {@link CancelledRequestError}; the worker itself is left alone, since a job
-   * already running cannot be interrupted from outside.
-   * @default undefined
-   */
-  signal?: AbortSignal;
-  /**
-   * Milliseconds this call alone waits, overriding the channel default —
-   * a calculation budget is often a user preference. A value that is not a
-   * positive finite number falls back to the channel default.
-   * @default the channel's defaultTimeoutMs
-   */
-  timeoutMs?: number;
-}
+  function expire(id: number, budget: number): void {
+    const message = `${name} request ${id} timed out after ${budget} ms`;
+    if (drop(id, new RequestTimeoutError(message)) && activeId === id) {
+      abandonActive();
+      startQueued();
+    }
+  }
 
-/** A channel to one worker, over which several jobs may be in flight. */
-export interface WorkerChannel<TRequest, TResponse> {
-  /**
-   * Post one job and wait for the answer that carries its identifier.
-   * @param payload - The job.
-   * @param options - Per-call signal and budget.
-   * @returns What the worker answered.
-   */
-  request: (
+  function request(
     payload: TRequest,
-    options?: WorkerRequestOptions,
-  ) => Promise<TResponse>;
-  /** How many requests are still waiting for an answer. */
-  readonly pendingCount: number;
-  /**
-   * Terminate the worker, rejecting everything still waiting with a
-   * {@link CancelledRequestError}. The channel accepts no further request.
-   */
-  terminate: () => void;
-}
-
-interface PendingRequest<TResponse> {
-  resolve: (response: TResponse) => void;
-  reject: (error: Error) => void;
-  dispose: () => void;
-}
+    requestOptions: WorkerRequestOptions<TProgress> = {},
+  ): Promise<TResponse> {
+    const { signal, timeoutMs, onProgress, transfer } = requestOptions;
+    if (closed || signal?.aborted === true) {
+      const reason = closed ? 'was terminated' : 'request was cancelled';
+      return Promise.reject(new CancelledRequestError(`${name} ${reason}`));
+    }
+    if (schedule !== 'parallel') {
+      dropAll('was superseded by a newer request');
+      if (schedule === 'restart' && activeId !== null) abandonActive();
+    }
 
-const DEFAULT_TIMEOUT_MS = 120_000;
+    nextId += 1;
+    const id = nextId;
+    const budget = positiveMilliseconds(timeoutMs, fallbackTimeoutMs);
+    const cancelled = `${name} request ${id} was cancelled`;
 
-function isResponseMessage(
-  message: unknown,
-): message is WorkerResponseMessage<unknown> {
-  if (typeof message !== 'object' || message === null) return false;
-  const candidate = message as {
-    id?: unknown;
-    ok?: unknown;
-    message?: unknown;
-  };
-  if (typeof candidate.id !== 'number' || typeof candidate.ok !== 'boolean') {
-    return false;
+    return new Promise<TResponse>((resolve, reject) => {
+      pending.set(
+        id,
+        watchRequest({
+          resolve,
+          reject,
+          onProgress,
+          signal,
+          budget,
+          onTimeout: () => expire(id, budget),
+          onAbort: () => drop(id, new CancelledRequestError(cancelled)),
+        }),
+      );
+      if (schedule === 'latest' && activeId !== null) {
+        queued = { id, payload, transfer };
+      } else {
+        dispatch(id, payload, transfer);
+      }
+    });
   }
-  return candidate.ok || typeof candidate.message === 'string';
-}
 
-function positiveMilliseconds(value: number | undefined, fallback: number) {
-  return typeof value === 'number' && Number.isFinite(value) && value > 0
-    ? value
-    : fallback;
+  return {
+    request,
+    get pendingCount() {
+      return pending.size;
+    },
+    cancel: () => dropAll('was cancelled'),
+    terminate: () => {
+      rejectAll(new CancelledRequestError(`${name} was terminated`));
+      worker?.terminate();
+      if (factory === undefined) closed = true;
+      else worker = null;
+    },
+  };
 }

package/src/worker/core/workerChannelParts.ts

@@ -0,0 +1,183 @@
+import { toError } from '../../error/core/toError.ts';
+
+import type { WorkerLike } from './messages.ts';
+import { isProgressMessage, isResponseMessage } from './messages.ts';
+import type { WorkerJobContext } from './workerChannelTypes.ts';
+
+/** How long a request waits when neither the call nor the channel says. */
+export const DEFAULT_TIMEOUT_MS = 120_000;
+
+/** One request waiting for its answer. */
+export interface PendingRequest<TResponse, TProgress> {
+  /** Settle the caller's promise with the answer. */
+  resolve: (response: TResponse) => void;
+  /** Settle the caller's promise with a failure. */
+  reject: (error: Error) => void;
+  /** Clear the timer and the abort listener. */
+  dispose: () => void;
+  /** Where the progress of this request goes. */
+  onProgress: ((progress: TProgress) => void) | undefined;
+  /** Whether the job has been handed to the worker, or started in-process. */
+  dispatched: boolean;
+  /**
+   * Aborts the in-process run of the job.
+   * @default undefined — the job runs in a worker
+   */
+  controller?: AbortController;
+}
+
+/** What {@link watchRequest} needs to keep an eye on one request. */
+interface WatchedRequest<TResponse, TProgress> {
+  /** Settle the caller's promise with the answer. */
+  resolve: (response: TResponse) => void;
+  /** Settle the caller's promise with a failure. */
+  reject: (error: Error) => void;
+  /** Where the progress of this request goes. */
+  onProgress: ((progress: TProgress) => void) | undefined;
+  /** The caller's signal, if any. */
+  signal: AbortSignal | undefined;
+  /** Milliseconds before `onTimeout` is called. */
+  budget: number;
+  /** Called once the budget has run out. */
+  onTimeout: () => void;
+  /** Called when the caller's signal aborts. */
+  onAbort: () => void;
+}
+
+/** The one request a `latest` channel keeps until the running job answers. */
+export interface QueuedRequest<TRequest> {
+  /** Its identifier. */
+  id: number;
+  /** The job. */
+  payload: TRequest;
+  /** The buffers to hand over with it. */
+  transfer: Transferable[] | undefined;
+}
+
+/** How a job ended. */
+export type Outcome<TResponse> =
+  { ok: true; response: TResponse } | { ok: false; error: Error };
+
+/** What a channel does with each kind of message a worker sends. */
+interface WorkerMessageHandlers {
+  /** News about a running job. */
+  progress: (id: number, progress: unknown) => void;
+  /** The end of a job. */
+  answer: (id: number, outcome: Outcome<unknown>) => void;
+  /** The worker failed outright, with what it said, possibly nothing. */
+  failure: (detail: string) => void;
+}
+
+/**
+ * Start the timer and the abort listener of one request.
+ * @param watched - See {@link WatchedRequest}.
+ * @returns The pending entry, whose `dispose` stops both.
+ */
+export function watchRequest<TResponse, TProgress>(
+  watched: WatchedRequest<TResponse, TProgress>,
+): PendingRequest<TResponse, TProgress> {
+  const { resolve, reject, onProgress, signal, budget, onTimeout, onAbort } =
+    watched;
+  const timeout = setTimeout(onTimeout, budget);
+  signal?.addEventListener('abort', onAbort);
+  return {
+    resolve,
+    reject,
+    onProgress,
+    dispatched: false,
+    dispose: () => {
+      clearTimeout(timeout);
+      signal?.removeEventListener('abort', onAbort);
+    },
+  };
+}
+
+/**
+ * Ask a worker to stop a job, without ever throwing: a worker that cannot take
+ * the message is ended some other way.
+ * @param worker - The worker running the job, if there still is one.
+ * @param id - The job's identifier.
+ */
+export function postCancel(worker: WorkerLike | null, id: number): void {
+  try {
+    worker?.postMessage({ id, cancel: true });
+  } catch {
+    // Nothing else to do: the caller has already been told.
+  }
+}
+
+/**
+ * Listen to a worker, sorting what it posts into progress and answers and
+ * dropping anything that is not the protocol.
+ * @param target - The worker.
+ * @param handlers - See {@link WorkerMessageHandlers}.
+ */
+export function subscribeToWorker(
+  target: WorkerLike,
+  handlers: WorkerMessageHandlers,
+): void {
+  target.addEventListener('message', (event) => {
+    const message = event.data;
+    if (isProgressMessage(message)) {
+      handlers.progress(message.id, message.progress);
+    } else if (isResponseMessage(message)) {
+      handlers.answer(
+        message.id,
+        message.ok
+          ? { ok: true, response: message.response }
+          : { ok: false, error: new Error(message.message) },
+      );
+    }
+  });
+  target.addEventListener('error', (event) => {
+    handlers.failure(event.message ?? '');
+  });
+}
+
+/**
+ * Run one job on this thread as a worker would: with a signal the channel
+ * aborts, progress routed back, and every outcome — a throw included —
+ * reported exactly once, never synchronously.
+ * @param runner - The in-process implementation of the job.
+ * @param payload - The job.
+ * @param reportProgress - Where the job's progress goes.
+ * @param complete - Called with the outcome.
+ * @returns The controller that aborts the job's signal.
+ */
+export function runJobInProcess<TRequest, TResponse, TProgress>(
+  runner: (
+    request: TRequest,
+    context: WorkerJobContext<TProgress>,
+  ) => Promise<TResponse>,
+  payload: TRequest,
+  reportProgress: (progress: TProgress) => void,
+  complete: (outcome: Outcome<TResponse>) => void,
+): AbortController {
+  const controller = new AbortController();
+  void Promise.resolve()
+    .then(() => runner(payload, { signal: controller.signal, reportProgress }))
+    .then(
+      (response) => {
+        complete({ ok: true, response });
+      },
+      (error: unknown) => {
+        complete({ ok: false, error: toError(error) });
+      },
+    );
+  return controller;
+}
+
+/**
+ * A budget in milliseconds, or the fallback when it is not a positive number.
+ * @param value - The budget asked for.
+ * @param fallback - The budget to use otherwise.
+ * @returns A positive finite number of milliseconds.
+ */
+export function positiveMilliseconds(
+  value: number | undefined,
+  fallback: number,
+): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : fallback;
+}