react-cheminfo 0.10.0 → 0.12.0

package/src/ui.ts

@@ -5,6 +5,7 @@ export * from './chrome/ui/index.ts';
 export * from './citation/ui/index.ts';
 export * from './clipboard/ui/index.ts';
 export * from './color/ui/index.ts';
+export * from './confirm/ui/index.ts';
 export * from './credits/ui/index.ts';
 export * from './delimited/ui/index.ts';
 export * from './disclosure/ui/index.ts';
@@ -17,8 +18,14 @@ export * from './overlay/ui/index.ts';
 export * from './pedagogy/ui/index.ts';
 export * from './periodic/ui/index.ts';
 export * from './projection/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 './spectra/ui/index.ts';
-export * from './state/ui/index.ts';
+export type {
+  BucketRead,
+  PersistBucketOptions,
+  PersistedBucket,
+} from './state/core/index.ts';
+export { persistBucket } from './state/core/index.ts';

package/src/worker/core/chunks.ts

@@ -0,0 +1,126 @@
+import { clamp } from '../../format/core/clamp.ts';
+
+const DEFAULT_SLICE_MS = 12;
+const DEFAULT_CHUNK_SIZE = 1;
+
+/** How {@link runInChunks} shares the thread. */
+export interface RunInChunksOptions {
+  /**
+   * Milliseconds of work between two turns handed back to the browser. The
+   * default leaves most of a 60 Hz frame for drawing and input.
+   * @default 12
+   */
+  sliceMs?: number;
+  /**
+   * Items worked through between two looks at the clock. Raise it when one
+   * item takes microseconds; with `sliceMs: 0` it is a fixed count of items
+   * between two turns.
+   * @default 1
+   */
+  chunkSize?: number;
+  /**
+   * How many items there are, for the progress of an iterable that cannot say.
+   * An estimate is fine: a count past it raises it.
+   * @default the length of an array, otherwise the count done so far
+   */
+  total?: number;
+  /**
+   * Called at every turn handed back, and once at the end with the exact count.
+   * @default undefined
+   */
+  onProgress?: (done: number, total: number) => void;
+  /**
+   * Stops the run before the next item; the promise then rejects with the
+   * signal's reason.
+   * @default undefined
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Work through a long list on this thread without freezing the page: the work
+ * runs in slices, and the browser gets a turn — to paint the progress, to
+ * handle a click on Cancel — between two of them.
+ *
+ * Meant for items that each cost real work: a molecule parsed, a row enriched,
+ * a record converted. Numeric inner loops belong in a plain `for` loop.
+ * @param items - The items, an array or any iterable, including an async one such as a streamed file.
+ * @param work - Called with each item and its index; may return a promise, which is awaited.
+ * @param options - See {@link RunInChunksOptions}.
+ * @returns How many items were worked through.
+ */
+export async function runInChunks<TItem>(
+  items: Iterable<TItem> | AsyncIterable<TItem>,
+  work: (item: TItem, index: number) => unknown,
+  options: RunInChunksOptions = {},
+): Promise<number> {
+  const {
+    sliceMs = DEFAULT_SLICE_MS,
+    chunkSize = DEFAULT_CHUNK_SIZE,
+    total,
+    onProgress,
+    signal,
+  } = options;
+  const slice = clamp(sliceMs, 0, Number.MAX_SAFE_INTEGER, DEFAULT_SLICE_MS);
+  const every = Math.trunc(
+    clamp(chunkSize, 1, Number.MAX_SAFE_INTEGER, DEFAULT_CHUNK_SIZE),
+  );
+  const known = total ?? (Array.isArray(items) ? items.length : 0);
+
+  signal?.throwIfAborted();
+  let done = 0;
+  let sliceStart = performance.now();
+
+  function isDue(): boolean {
+    return done % every === 0 && performance.now() - sliceStart >= slice;
+  }
+
+  async function settle(result: unknown): Promise<void> {
+    if (result instanceof Promise) await result;
+    signal?.throwIfAborted();
+    if (!isDue()) return;
+    onProgress?.(done, Math.max(known, done));
+    await yieldToBrowser();
+    signal?.throwIfAborted();
+    sliceStart = performance.now();
+  }
+
+  if (Symbol.iterator in items) {
+    // A plain loop, so a synchronous item costs no promise of its own.
+    for (const item of items) {
+      const result = work(item, done);
+      done += 1;
+      if (result instanceof Promise || isDue()) {
+        // eslint-disable-next-line no-await-in-loop -- items run in order, and the thread is handed back between slices
+        await settle(result);
+      } else {
+        signal?.throwIfAborted();
+      }
+    }
+  } else {
+    for await (const item of items) {
+      const result = work(item, done);
+      done += 1;
+      await settle(result);
+    }
+  }
+
+  onProgress?.(done, done);
+  return done;
+}
+
+/**
+ * Give the browser a turn in the middle of long work: it can paint, and read
+ * the click or the message that cancels the work.
+ *
+ * A macrotask rather than a resolved promise, because the browser paints and a
+ * worker reads its messages between tasks, never between microtasks; and
+ * `setTimeout` rather than `requestAnimationFrame`, which a background tab
+ * stops calling and a worker or a test does not have.
+ * @returns When the browser has had its turn.
+ */
+export function yieldToBrowser(): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}

package/src/worker/core/index.ts

@@ -1,8 +1,25 @@
+export type { RunInChunksOptions } from './chunks.ts';
+export { runInChunks, yieldToBrowser } from './chunks.ts';
 export { CancelledRequestError, RequestTimeoutError } from './errors.ts';
-export type { WorkerLike } from './messages.ts';
+export type {
+  WorkerCancelMessage,
+  WorkerEventLike,
+  WorkerLike,
+  WorkerProgressMessage,
+  WorkerRequestMessage,
+  WorkerResponseMessage,
+} from './messages.ts';
+export type {
+  ServeWorkerRequestsOptions,
+  WorkerScopeLike,
+} from './serveWorkerRequests.ts';
+export { serveWorkerRequests } from './serveWorkerRequests.ts';
+export { createWorkerChannel } from './workerChannel.ts';
 export type {
   WorkerChannel,
   WorkerChannelOptions,
+  WorkerJobContext,
   WorkerRequestOptions,
-} from './workerChannel.ts';
-export { createWorkerChannel } from './workerChannel.ts';
+  WorkerSchedule,
+  WorkerSource,
+} from './workerChannelTypes.ts';

package/src/worker/core/messages.ts

@@ -7,8 +7,28 @@ export interface WorkerRequestMessage<TRequest> {
 }
 
 /**
- * What a worker posts back. An `Error` does not survive the boundary, so a
- * failure travels as its message and becomes an `Error` again on this side.
+ * What a channel created with `cooperativeCancel` posts when nobody waits for
+ * a job any more, so a worker that checks can stop early.
+ */
+export interface WorkerCancelMessage {
+  /** Serial number of the request to stop. */
+  id: number;
+  /** Always `true`: this message asks for a stop. */
+  cancel: true;
+}
+
+/** What a worker posts while a job runs, as often as it has news. */
+export interface WorkerProgressMessage<TProgress> {
+  /** Serial number of the request the news is about. */
+  id: number;
+  /** How far the job is, in whatever shape the two sides agreed on. */
+  progress: 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.
  */
 export type WorkerResponseMessage<TResponse> =
   | { id: number; ok: true; response: TResponse }
@@ -20,8 +40,8 @@ export type WorkerResponseMessage<TResponse> =
  * scheduling be unit-tested without a thread.
  */
 export interface WorkerLike {
-  /** Send one message to the worker. */
-  postMessage(message: unknown): void;
+  /** Send one message to the worker, handing over the listed buffers. */
+  postMessage(message: unknown, transfer?: Transferable[]): void;
   /** Listen to what the worker answers, or to its failing outright. */
   addEventListener(
     type: 'message' | 'error',
@@ -45,3 +65,58 @@ export interface WorkerEventLike {
    */
   readonly message?: string;
 }
+
+/**
+ * Whether a message is the answer that ends a job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and a well-formed outcome.
+ */
+export function isResponseMessage(
+  message: unknown,
+): message is WorkerResponseMessage<unknown> {
+  if (!hasId(message)) return false;
+  const candidate = message as { ok?: unknown; message?: unknown };
+  if (typeof candidate.ok !== 'boolean') return false;
+  return candidate.ok || typeof candidate.message === 'string';
+}
+
+/**
+ * Whether a message is news about a running job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and a progress, and no outcome.
+ */
+export function isProgressMessage(
+  message: unknown,
+): message is WorkerProgressMessage<unknown> {
+  return hasId(message) && 'progress' in message && !('ok' in message);
+}
+
+/**
+ * Whether a message asks a worker for a job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and a request.
+ */
+export function isRequestMessage(
+  message: unknown,
+): message is WorkerRequestMessage<unknown> {
+  return hasId(message) && 'request' in message;
+}
+
+/**
+ * Whether a message asks a worker to stop a job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and `cancel: true`.
+ */
+export function isCancelMessage(
+  message: unknown,
+): message is WorkerCancelMessage {
+  return hasId(message) && (message as { cancel?: unknown }).cancel === true;
+}
+
+function hasId(message: unknown): message is { id: number } {
+  return (
+    typeof message === 'object' &&
+    message !== null &&
+    typeof (message as { id?: unknown }).id === 'number'
+  );
+}

package/src/worker/core/serveWorkerRequests.ts

@@ -0,0 +1,144 @@
+import { errorMessage } from '../../error/core/toError.ts';
+
+import type {
+  WorkerProgressMessage,
+  WorkerResponseMessage,
+} from './messages.ts';
+import { isCancelMessage, isRequestMessage } from './messages.ts';
+import type { WorkerJobContext } from './workerChannelTypes.ts';
+
+/** As much of a dedicated worker's global scope as {@link serveWorkerRequests} uses. */
+export interface WorkerScopeLike {
+  /** Listen to what the page posts. */
+  addEventListener(
+    type: 'message',
+    listener: (event: { data: unknown }) => void,
+  ): void;
+  /** Answer the page, handing over the listed buffers. */
+  postMessage(message: unknown, transfer?: Transferable[]): void;
+}
+
+/** Where {@link serveWorkerRequests} listens, and what it hands over. */
+export interface ServeWorkerRequestsOptions<TRequest, TResponse> {
+  /**
+   * The scope to serve.
+   * @default the global scope, when the code runs in a dedicated worker
+   */
+  scope?: WorkerScopeLike;
+  /**
+   * Checks that a request has the shape the handler expects; one that does not
+   * is answered with a failure and never reaches the handler.
+   * @default undefined — every request is handed over as it came
+   */
+  accepts?: (request: unknown) => request is TRequest;
+  /**
+   * The buffers of an answer to hand over rather than copy, e.g. the grid of
+   * a sampled orbital.
+   * @default undefined — every answer is copied
+   */
+  transfer?: (response: TResponse) => Transferable[];
+}
+
+/**
+ * The worker's half of `createWorkerChannel`: answer every request the page
+ * posts with what the handler returns.
+ *
+ * The handler receives a signal that is aborted when the page sends the cancel
+ * message of a `cooperativeCancel` channel, and a `reportProgress` that posts
+ * news the caller's `onProgress` receives. A failure travels back as its
+ * message. Called in a module that the page also imports for its in-process
+ * fallback, it attaches nothing there, because that scope is not a worker's.
+ * @param handler - Runs one job; may be async.
+ * @param options - See {@link ServeWorkerRequestsOptions}.
+ * @returns Whether a scope was found and is now served.
+ */
+export function serveWorkerRequests<TRequest, TResponse, TProgress = never>(
+  handler: (
+    request: TRequest,
+    context: WorkerJobContext<TProgress>,
+  ) => TResponse | Promise<TResponse>,
+  options: ServeWorkerRequestsOptions<TRequest, TResponse> = {},
+): boolean {
+  const { accepts, transfer } = options;
+  const scope = options.scope ?? dedicatedWorkerScope();
+  if (scope === undefined) return false;
+  const running = new Map<number, AbortController>();
+
+  scope.addEventListener('message', (event) => {
+    const message = event.data;
+    if (isCancelMessage(message)) {
+      running.get(message.id)?.abort();
+      return;
+    }
+    if (!isRequestMessage(message)) return;
+
+    const { id, request } = message;
+    if (accepts !== undefined && !accepts(request)) {
+      answer(scope, {
+        id,
+        ok: false,
+        message: 'not a request this worker handles',
+      });
+      return;
+    }
+    const controller = new AbortController();
+    running.set(id, controller);
+    const context: WorkerJobContext<TProgress> = {
+      signal: controller.signal,
+      reportProgress: (progress) => {
+        if (controller.signal.aborted) return;
+        const news: WorkerProgressMessage<TProgress> = { id, progress };
+        scope.postMessage(news);
+      },
+    };
+
+    void Promise.resolve()
+      .then(() => handler(request as TRequest, context))
+      .then(
+        (response) => {
+          answer(scope, { id, ok: true, response }, transfer);
+        },
+        (error: unknown) => {
+          answer(scope, { id, ok: false, message: errorMessage(error) });
+        },
+      )
+      .finally(() => {
+        running.delete(id);
+      });
+  });
+  return true;
+}
+
+function answer<TResponse>(
+  scope: WorkerScopeLike,
+  message: WorkerResponseMessage<TResponse>,
+  transfer?: (response: TResponse) => Transferable[],
+): void {
+  try {
+    if (transfer === undefined || !message.ok) scope.postMessage(message);
+    else scope.postMessage(message, transfer(message.response));
+  } catch (error) {
+    // An answer that cannot be listed or cloned still has to end the job on the page.
+    scope.postMessage({
+      id: message.id,
+      ok: false,
+      message: errorMessage(error),
+    });
+  }
+}
+
+function dedicatedWorkerScope(): WorkerScopeLike | undefined {
+  const candidate = globalThis as {
+    postMessage?: unknown;
+    addEventListener?: unknown;
+    window?: unknown;
+  };
+  if (
+    typeof candidate.postMessage !== 'function' ||
+    typeof candidate.addEventListener !== 'function' ||
+    candidate.window !== undefined
+  ) {
+    return undefined;
+  }
+  return globalThis as unknown as WorkerScopeLike;
+}