react-cheminfo 0.64.0 → 0.65.0

package/src/structure/ui/useStructureDraft.ts

@@ -0,0 +1,47 @@
+import { useCallback, useState } from 'react';
+
+/** What a structure editor is drawing, and how a page reloads it. */
+export interface StructureDraft<TValue> {
+  /** What the canvas holds: the structure last loaded or last drawn. */
+  value: TValue;
+  /**
+   * What `StructureEditor` takes as `revision`: it reloads `value` into the
+   * canvas each time this changes, and only then.
+   */
+  revision: number;
+  /**
+   * Put a structure in the canvas, replacing what is drawn: an example, the
+   * query a dialog is opened on, a Clear button loading the empty string.
+   * @param value - The structure, as the editor's `inputFormat` reads it.
+   */
+  load: (value: TValue) => void;
+  /**
+   * Keep what the editor drew, without reloading the canvas: what its
+   * `onChange` hands over. The same value twice changes nothing.
+   * @param value - The structure the editor reports.
+   */
+  update: (value: TValue) => void;
+}
+
+/**
+ * The draft a `StructureEditor` is fed: what it draws, and the revision that
+ * makes it reload. The editor is uncontrolled, so feeding every stroke back
+ * into it would replace the structure under the pen; this keeps the drawing
+ * out of the canvas until the page means to load one.
+ * @param initial - What the canvas opens on.
+ * @returns The draft, and the two ways to change it.
+ */
+export function useStructureDraft<TValue = string>(
+  initial: TValue,
+): StructureDraft<TValue> {
+  const [draft, setDraft] = useState({ value: initial, revision: 0 });
+  const load = useCallback((value: TValue) => {
+    setDraft((previous) => ({ value, revision: previous.revision + 1 }));
+  }, []);
+  const update = useCallback((value: TValue) => {
+    setDraft((previous) =>
+      Object.is(previous.value, value) ? previous : { ...previous, value },
+    );
+  }, []);
+  return { value: draft.value, revision: draft.revision, load, update };
+}

package/src/ui.ts

@@ -27,12 +27,14 @@ export * from './parallel/ui/index.ts';
 export * from './pedagogy/ui/index.ts';
 export * from './periodic/ui/index.ts';
 export * from './projection/ui/index.ts';
+export * from './property/ui/index.ts';
 export * from './range/ui/index.ts';
 export * from './router/ui/index.ts';
 export * from './scatter/ui/index.ts';
 export * from './scatter3d/ui/index.ts';
 export * from './share/ui/index.ts';
 export * from './shared/ui/index.ts';
+export * from './shell/ui/index.ts';
 export * from './split/ui/index.ts';
 export * from './taxonomy/ui/index.ts';
 // The conformer table, from the structure module's file rather than its

package/src/worker/core/index.ts

@@ -18,6 +18,7 @@ export { createWorkerChannel } from './workerChannel.ts';
 export type {
   WorkerChannel,
   WorkerChannelOptions,
+  WorkerFailure,
   WorkerJobContext,
   WorkerRequestOptions,
   WorkerSchedule,

package/src/worker/core/messages.ts

@@ -27,12 +27,13 @@ export interface WorkerProgressMessage<TProgress> {
 
 /**
  * What a worker posts once a job is over. An `Error` does not survive the
- * boundary, so a failure travels as its message and becomes an `Error` again
- * on this side.
+ * boundary, so a failure travels as its message — plus, when the worker was
+ * told how, a `detail` the page reads to say it in its own words — and becomes
+ * an `Error` again on this side.
  */
 export type WorkerResponseMessage<TResponse> =
   | { id: number; ok: true; response: TResponse }
-  | { id: number; ok: false; message: string };
+  | { id: number; ok: false; message: string; detail?: unknown };
 
 /**
  * As much of a `Worker` as a channel uses. A real `Worker` satisfies it, and so

package/src/worker/core/oclResourcesUrl.ts

@@ -0,0 +1,21 @@
+/** The file OpenChemLib's static resources are served as, at the site's root. */
+export const OCL_RESOURCES_FILE = 'openchemlib-resources.json';
+
+/**
+ * Where OpenChemLib's static resources sit, as this page is mounted.
+ *
+ * A worker fetches them, but a worker has no `document` and so cannot read the
+ * `<base>` the page carries, and its own script address is no help either: it
+ * sits under `assets/` in the build and under `src/` in development. So the
+ * page resolves the address and posts it with the job — the argument
+ * `registerResources` needs in a worker.
+ * @param file - The file, relative to the site's own root.
+ * @returns The absolute address, or `undefined` outside a page, where
+ * `registerResources` reads the file from the installed package instead.
+ */
+export function oclResourcesUrl(
+  file: string = OCL_RESOURCES_FILE,
+): string | undefined {
+  const baseUri = globalThis.document?.baseURI;
+  return baseUri ? new URL(file, baseUri).href : undefined;
+}

package/src/worker/core/serveWorkerRequests.ts

@@ -37,6 +37,14 @@ export interface ServeWorkerRequestsOptions<TRequest, TResponse> {
    * @default undefined — every answer is copied
    */
   transfer?: (response: TResponse) => Transferable[];
+  /**
+   * What a failed answer carries besides its message, for the page's channel
+   * to word the failure in its own language — the key of a translatable
+   * message and its values, say. It must survive being posted; answering
+   * `undefined` adds nothing.
+   * @default undefined — a failure carries its message alone
+   */
+  detail?: (error: unknown) => unknown;
 }
 
 /**
@@ -59,7 +67,7 @@ export function serveWorkerRequests<TRequest, TResponse, TProgress = never>(
   ) => TResponse | Promise<TResponse>,
   options: ServeWorkerRequestsOptions<TRequest, TResponse> = {},
 ): boolean {
-  const { accepts, transfer } = options;
+  const { accepts, transfer, detail } = options;
   const scope = options.scope ?? dedicatedWorkerScope();
   if (scope === undefined) return false;
   const running = new Map<number, AbortController>();
@@ -99,7 +107,15 @@ export function serveWorkerRequests<TRequest, TResponse, TProgress = never>(
           answer(scope, { id, ok: true, response }, transfer);
         },
         (error: unknown) => {
-          answer(scope, { id, ok: false, message: errorMessage(error) });
+          const message = errorMessage(error);
+          const extra =
+            detail === undefined ? undefined : describe(detail, error);
+          answer(
+            scope,
+            extra === undefined
+              ? { id, ok: false, message }
+              : { id, ok: false, message, detail: extra },
+          );
         },
       )
       .finally(() => {
@@ -127,6 +143,18 @@ function answer<TResponse>(
   }
 }
 
+function describe(
+  detail: (error: unknown) => unknown,
+  error: unknown,
+): unknown {
+  try {
+    return detail(error);
+  } catch {
+    // A detail that cannot be worked out leaves the message to say it all.
+    return undefined;
+  }
+}
+
 function dedicatedWorkerScope(): WorkerScopeLike | undefined {
   const candidate = globalThis as {
     postMessage?: unknown;

package/src/worker/core/workerChannel.ts

@@ -1,7 +1,7 @@
 import { toError } from '../../error/core/toError.ts';
 
 import { CancelledRequestError, RequestTimeoutError } from './errors.ts';
-import type { WorkerLike, WorkerRequestMessage } from './messages.ts';
+import type { WorkerRequestMessage } from './messages.ts';
 import type {
   Outcome,
   PendingRequest,
@@ -12,7 +12,6 @@ import {
   positiveMilliseconds,
   postCancel,
   runJobInProcess,
-  subscribeToWorker,
   watchRequest,
 } from './workerChannelParts.ts';
 import type {
@@ -21,6 +20,7 @@ import type {
   WorkerRequestOptions,
   WorkerSource,
 } from './workerChannelTypes.ts';
+import { createWorkerSlot } from './workerSlot.ts';
 
 /**
  * Turn a worker into something a page can await.
@@ -30,10 +30,9 @@ import type {
  * — 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.
  *
- * 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`.
+ * Handed a worker, the channel posts to it and terminates it when asked. Handed
+ * a function, it creates the worker when needed and can run the job in-process
+ * instead; see `createWorkerSlot`.
  * @param source - The worker, or the function that creates it.
  * @param options - See {@link WorkerChannelOptions}.
  * @returns The channel.
@@ -43,38 +42,44 @@ 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 { name = 'worker', schedule = 'parallel' } = options;
+  const { cooperativeCancel = false, retryAfterWorkerFailure } = options;
+  const { defaultTimeoutMs, runInProcess, failure } = options;
   const fallbackTimeoutMs = positiveMilliseconds(
     defaultTimeoutMs,
     DEFAULT_TIMEOUT_MS,
   );
-  const factory = typeof source === 'function' ? source : undefined;
-  if (schedule === 'restart' && factory === undefined) {
+  if (schedule === 'restart' && typeof source !== 'function') {
     throw new Error(`${name}: the restart schedule needs a worker factory`);
   }
-  const hasNoWorker = !('Worker' in globalThis);
-  const runLocally = factory && hasNoWorker ? runInProcess : undefined;
+  const retries = typeof source === 'function' && retryAfterWorkerFailure;
 
   const pending = new Map<number, PendingRequest<TResponse, TProgress>>();
-  let worker: WorkerLike | null = null;
+  const posted = new Map<number, QueuedRequest<TRequest>>();
+  const retried = new Set<number>();
   let closed = false;
   let nextId = 0;
   let activeId: number | null = null;
   let queued: QueuedRequest<TRequest> | null = null;
-  if (typeof source !== 'function') {
-    worker = source;
-    listen(source);
-  }
+  const slot = createWorkerSlot<TRequest, TResponse, TProgress>(source, {
+    name,
+    runInProcess,
+    failure,
+    isWaited: (id) => pending.has(id),
+    report: {
+      progress: (id, progress) => {
+        pending.get(id)?.onProgress?.(progress as TProgress);
+      },
+      answer: (id, outcome) => complete(id, outcome),
+      failure: (error) => workerFailed(error),
+    },
+  });
 
   function take(id: number): PendingRequest<TResponse, TProgress> | undefined {
     const entry = pending.get(id);
     pending.delete(id);
+    posted.delete(id);
+    retried.delete(id);
     entry?.dispose();
     return entry;
   }
@@ -93,7 +98,7 @@ export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
     const entry = take(id);
     if (entry === undefined) return false;
     entry.controller?.abort();
-    if (cooperativeCancel && entry.dispatched) postCancel(worker, id);
+    if (cooperativeCancel && entry.dispatched) postCancel(slot.current, id);
     entry.reject(error);
     return true;
   }
@@ -106,22 +111,18 @@ export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
   }
 
   function rejectAll(error: Error): void {
-    for (const entry of pending.values()) {
-      entry.dispose();
+    for (const [id, entry] of pending) {
+      take(id);
       entry.controller?.abort();
       entry.reject(error);
     }
-    pending.clear();
     activeId = null;
     queued = null;
   }
 
   function abandonActive(): void {
     activeId = null;
-    if (factory !== undefined && worker !== null) {
-      worker.terminate();
-      worker = null;
-    }
+    slot.abandon();
   }
 
   function startQueued(): void {
@@ -135,55 +136,55 @@ export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
     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);
+      const target = slot.acquire();
+      if (target !== null) {
+        if (retries && transfer === undefined) {
+          posted.set(id, { id, payload, transfer });
+        }
+        const message: WorkerRequestMessage<TRequest> = {
+          id,
+          request: payload,
+        };
+        if (transfer === undefined) target.postMessage(message);
+        else target.postMessage(message, transfer);
+        return;
+      }
     } catch (error) {
       complete(id, { ok: false, error: toError(error) });
+      return;
     }
+    entry.controller = runJobInProcess(
+      slot.runLocally,
+      payload,
+      (progress) => pending.get(id)?.onProgress?.(progress),
+      (outcome) => complete(id, outcomeOf(outcome)),
+    );
   }
 
-  function currentWorker(): WorkerLike {
-    if (worker === null) {
-      if (factory === undefined) {
-        throw new CancelledRequestError(`${name} was terminated`);
-      }
-      worker = factory();
-      listen(worker);
-    }
-    return worker;
+  function outcomeOf(outcome: Outcome<TResponse>): Outcome<TResponse> {
+    return outcome.ok
+      ? outcome
+      : { ok: false, error: slot.jobFailed(outcome.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;
-        }
-        const suffix = detail === '' ? '' : `: ${detail}`;
-        rejectAll(new Error(`${name} failed${suffix}`));
-      },
-    });
+  function workerFailed(error: Error): void {
+    if (!retries) {
+      rejectAll(error);
+      return;
+    }
+    activeId = null;
+    for (const [id, entry] of pending) {
+      if (!entry.dispatched) continue;
+      const job = posted.get(id);
+      if (job === undefined || retried.has(id)) {
+        drop(id, error);
+        continue;
+      }
+      retried.add(id);
+      dispatch(id, job.payload);
+    }
+    if (activeId === null) startQueued();
   }
 
   function expire(id: number, budget: number): void {
@@ -242,9 +243,8 @@ export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
     cancel: () => dropAll('was cancelled'),
     terminate: () => {
       rejectAll(new CancelledRequestError(`${name} was terminated`));
-      worker?.terminate();
-      if (factory === undefined) closed = true;
-      else worker = null;
+      slot.terminate();
+      if (!slot.hasFactory) closed = true;
     },
   };
 }

package/src/worker/core/workerChannelParts.ts

@@ -1,8 +1,12 @@
 import { toError } from '../../error/core/toError.ts';
 
-import type { WorkerLike } from './messages.ts';
+import type {
+  WorkerEventLike,
+  WorkerLike,
+  WorkerResponseMessage,
+} from './messages.ts';
 import { isProgressMessage, isResponseMessage } from './messages.ts';
-import type { WorkerJobContext } from './workerChannelTypes.ts';
+import type { WorkerFailure, WorkerJobContext } from './workerChannelTypes.ts';
 
 /** How long a request waits when neither the call nor the channel says. */
 export const DEFAULT_TIMEOUT_MS = 120_000;
@@ -62,10 +66,13 @@ export type Outcome<TResponse> =
 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;
+  /** The end of a job, as the worker posted it. */
+  answer: (id: number, message: WorkerResponseMessage<unknown>) => void;
+  /**
+   * The worker failed outright, with what it said — possibly nothing — and
+   * the error event itself.
+   */
+  failure: (detail: string, event: WorkerEventLike) => void;
 }
 
 /**
@@ -121,19 +128,32 @@ export function subscribeToWorker(
     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) },
-      );
+      handlers.answer(message.id, message);
     }
   });
   target.addEventListener('error', (event) => {
-    handlers.failure(event.message ?? '');
+    handlers.failure(event.message ?? '', event);
   });
 }
 
+/**
+ * The error a failure rejects its requests with when the channel is given no
+ * `failure` of its own: the job's own error or message, `<name> failed: …` for
+ * a worker that died, and what creating the worker threw.
+ * @param failure - What went wrong.
+ * @returns The error.
+ */
+export function defaultFailureError(failure: WorkerFailure): Error {
+  if (failure.kind === 'worker') {
+    const suffix = failure.message === '' ? '' : `: ${failure.message}`;
+    return new Error(`${failure.name} failed${suffix}`);
+  }
+  if (failure.cause instanceof Error) return failure.cause;
+  return failure.kind === 'job'
+    ? new Error(failure.message)
+    : toError(failure.cause);
+}
+
 /**
  * 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 —

package/src/worker/core/workerChannelTypes.ts

@@ -63,14 +63,59 @@ export interface WorkerChannelOptions<TRequest, TResponse, TProgress = never> {
   cooperativeCancel?: boolean;
   /**
    * The same job run on this thread, used instead of the worker where the page
-   * has no `Worker` at all — Node.js, a unit test. Only a channel built from a
-   * function that creates the worker falls back to it.
+   * has no `Worker` at all — Node.js, a unit test — or where creating one
+   * throws, as a browser refuses a page framed under an opaque origin a worker
+   * from its own server; every later job then runs here too. Only a channel
+   * built from a function that creates the worker falls back to it.
    * @default undefined — every job goes to the worker
    */
   runInProcess?: (
     request: TRequest,
     context: WorkerJobContext<TProgress>,
   ) => Promise<TResponse>;
+  /**
+   * Turn what went wrong into the error the requests reject with, so a page
+   * can say it in its own words — a translated message, an error class of its
+   * own. Answering `undefined` keeps the default error. Cancellations and
+   * timeouts are not failures: they keep their own error classes.
+   * @default undefined — the job's message, or `<name> failed: …`
+   */
+  failure?: (failure: WorkerFailure) => Error | undefined;
+  /**
+   * Post a job again, once, on a fresh worker when its worker failed before
+   * answering, rather than reporting the failure: a worker whose module graph
+   * was still loading when the channel replaced it dies without having run
+   * anything. A job posted with buffers to transfer is not posted twice. Only
+   * a channel built from a function that creates the worker can do it.
+   * @default false
+   */
+  retryAfterWorkerFailure?: boolean;
+}
+
+/** What went wrong, before it becomes the error a request rejects with. */
+export interface WorkerFailure {
+  /**
+   * `job`: the job failed — its worker answered with a failure, or its
+   * in-process run threw. `worker`: the worker itself failed outright; an
+   * empty `message` means it never ran at all, its module graph not loading.
+   * `start`: creating the worker threw, and no in-process run stood in.
+   */
+  kind: 'job' | 'worker' | 'start';
+  /** The channel's name, e.g. `conformers`. */
+  name: string;
+  /** What was said: the job's message, the error event's, or the thrown error's. */
+  message: string;
+  /**
+   * The `detail` a failed answer carried, as `serveWorkerRequests` was told to
+   * write it — the key of a translatable message, say.
+   * @default undefined
+   */
+  detail?: unknown;
+  /**
+   * What the failure came with: the failed answer the worker posted, the error
+   * the in-process run threw, the error event, or what the factory threw.
+   */
+  cause: unknown;
 }
 
 /** What one call may ask of the channel. */