react-cheminfo 0.75.0 → 0.77.0

package/src/osiris/core/poolTypes.ts

@@ -0,0 +1,140 @@
+/**
+ * What a page asks the prediction pool, and what it hears back.
+ *
+ * A prediction costs 210 to 380 ms of one thread, so a set of any size is
+ * answered a molecule at a time rather than all at once: a row appears as soon
+ * as it is read and fills in when its worker returns. Everything here is shaped
+ * around that — a per-result callback rather than a promise over the set, a
+ * progress figure, a cancel that works, and a way to say which rows the reader
+ * can actually see so those are computed first.
+ */
+
+import type { WorkerLike } from '../../worker/core/messages.ts';
+
+import type { PredictRequest, PredictResponse } from './predictProtocol.ts';
+import type { ResourceSource } from './predictors.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from './types.ts';
+
+/** One molecule to predict. */
+export interface PredictionInput {
+  /**
+   * The caller's key for the row, echoed on the answer. It is the row's read
+   * position, never its idCode: a real list holds the same structure twice
+   * under two names, and both rows have to fill in.
+   */
+  key: string;
+  /** The idCode, with the editor's atom coordinates after a space or without. */
+  idCode: string;
+  /**
+   * The name the source carried.
+   * @default the canonical SMILES
+   */
+  label?: string;
+}
+
+/** What came back for one molecule. */
+export type PredictionOutcome =
+  | { key: string; ok: true; properties: OsirisProperties }
+  | { key: string; ok: false; message: string };
+
+/** How far the pool has got. */
+export interface PredictionProgress {
+  /** Molecules answered, whether predicted or refused. */
+  done: number;
+  /** Molecules accepted since the run started. */
+  total: number;
+  /** Molecules still queued or still being worked on. */
+  pending: number;
+  /** Whether anything is still to come. */
+  running: boolean;
+}
+
+/** How a pool is built, and who it reports to. */
+export interface PredictionPoolOptions {
+  /**
+   * Where the workers register OpenChemLib's resources from — the absolute URL
+   * of the site's own `openchemlib-resources.json`, resolved on the main
+   * thread. See {@link ResourceSource}.
+   */
+  resources: ResourceSource;
+  /**
+   * How many workers to run. Clamped to 1 to 8.
+   * @default one fewer than the machine's cores, which measured 2.45x on two workers and 4.57x on four
+   */
+  size?: number;
+  /**
+   * Makes one worker, which serves `runPredictionJob` for the requests
+   * `isPredictRequest` accepts. Only called where the page has a `Worker` at
+   * all. The site writes it because a bundler resolves a worker's address
+   * against the module naming it: written in this package, the URL would point
+   * inside `node_modules` rather than at a chunk the site's build emitted.
+   */
+  createWorker: () => WorkerLike;
+  /**
+   * The same job on this thread, used where there is no `Worker` — Node, a
+   * unit test.
+   * @default `runPredictionJob`, the same function the worker serves
+   */
+  runInProcess?: (request: PredictRequest) => Promise<PredictResponse>;
+  /**
+   * Called once per molecule, as each one comes back.
+   * @default undefined
+   */
+  onResult?: (outcome: PredictionOutcome) => void;
+  /**
+   * Called whenever the count of answered molecules changes.
+   * @default undefined
+   */
+  onProgress?: (progress: PredictionProgress) => void;
+  /**
+   * Called once when the resource tables did not load. Every answer from every
+   * worker would be `unknown`, so the run stops and nothing more is dispatched.
+   * @default undefined
+   */
+  onUnavailable?: (message: string) => void;
+  /**
+   * Milliseconds one molecule may take before it is given up on.
+   * @default 60000
+   */
+  timeoutMs?: number;
+}
+
+/** A pool of workers answering one molecule at a time, each. */
+export interface PredictionPool {
+  /** How many workers it runs. */
+  readonly size: number;
+  /** How far it has got. */
+  readonly progress: PredictionProgress;
+  /**
+   * Add molecules to predict. One already queued or in flight is ignored, so a
+   * page may resubmit its whole set whenever the set changes.
+   * @param molecules - The molecules.
+   */
+  submit: (molecules: readonly PredictionInput[]) => void;
+  /**
+   * Say which rows to answer first — the ones the reader can see. Molecules
+   * already being worked on are left alone; only what is still queued moves.
+   * @param keys - The keys, most wanted first.
+   */
+  prioritize: (keys: readonly string[]) => void;
+  /**
+   * Why one risk came back as it did. Jumps the queue, because it is a click.
+   * A {@link PredictionPool.cancel} is about the set, not about the click, so
+   * an explanation it drops is asked for again.
+   * @param idCode - The molecule, coordinates included or not.
+   * @param risk - Which of the four risks to explain.
+   * @returns The findings, with the matched atoms and bonds of every fragment.
+   * @throws {Error} When even the second ask was dropped, with a sentence to show the reader.
+   */
+  riskDetail: (idCode: string, risk: RiskType) => Promise<RiskDetail>;
+  /**
+   * Drop everything queued and stop reporting. The molecule each worker is
+   * already on cannot be interrupted — the library call is synchronous — so it
+   * finishes and its answer is thrown away, within about 400 ms. A
+   * {@link PredictionPool.submit} made in the same turn is still dispatched, on
+   * the slots those abandoned answers free.
+   */
+  cancel: () => void;
+  /** Cancel, and end every worker. */
+  terminate: () => void;
+}

package/src/osiris/core/predictIdCode.ts

@@ -0,0 +1,69 @@
+/**
+ * Prediction from the only thing worth keeping per row.
+ *
+ * A row never holds an `OCL.Molecule` — ten thousand of them cost 198 MB — so
+ * what travels to a worker is the idCode, and the molecule is rebuilt there in
+ * a quarter of a millisecond against the 380 ms the prediction itself costs.
+ */
+
+import { splitIdCode } from '../../structure/core/editorValue.ts';
+
+import type { ComputePropertiesOptions } from './computeProperties.ts';
+import { computeProperties } from './computeProperties.ts';
+import type { OsirisPredictors } from './predictors.ts';
+import { riskDetail } from './riskDetail.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from './types.ts';
+
+/**
+ * What is said when an idCode cannot be read.
+ *
+ * An idCode is written by a program, not typed by a chemist, so there is no
+ * position to point at and no parser reason worth repeating: OpenChemLib
+ * answers a malformed one with `Cannot set properties of undefined`, which
+ * names nothing anyone can act on. Worse, it does not always throw — `zzzz`
+ * reads as a 117-atom molecule — so this is the floor, not the whole guard.
+ */
+export const UNREADABLE_ID_CODE_MESSAGE = 'This structure could not be read.';
+
+/**
+ * Predict everything the tool shows, from an idCode.
+ * @param value - The idCode, with the editor's atom coordinates after a space or without them.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @param options - See {@link ComputePropertiesOptions}.
+ * @returns The ten numbers, the four risks, and what to call the molecule.
+ * @throws {Error} When the idCode cannot be read, or describes no atoms.
+ */
+export function predictIdCode(
+  value: string,
+  predictors: OsirisPredictors,
+  options: ComputePropertiesOptions = {},
+): OsirisProperties {
+  return computeProperties(read(value, predictors), predictors, options);
+}
+
+/**
+ * Why one risk came back as it did, from an idCode.
+ * @param value - The idCode, coordinates included or not.
+ * @param risk - Which of the four risks to explain.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @returns The findings, with the matched atoms and bonds of every fragment.
+ * @throws {Error} When the idCode cannot be read.
+ */
+export function riskDetailOfIdCode(
+  value: string,
+  risk: RiskType,
+  predictors: OsirisPredictors,
+): RiskDetail {
+  return riskDetail(read(value, predictors), risk, predictors);
+}
+
+function read(value: string, predictors: OsirisPredictors) {
+  const { idCode, coordinates } = splitIdCode(value);
+  try {
+    return coordinates === undefined
+      ? predictors.Molecule.fromIDCode(idCode)
+      : predictors.Molecule.fromIDCode(idCode, coordinates);
+  } catch (error) {
+    throw new Error(UNREADABLE_ID_CODE_MESSAGE, { cause: error });
+  }
+}

package/src/osiris/core/predictProtocol.ts

@@ -0,0 +1,78 @@
+/**
+ * What the page asks a prediction worker, and what it answers.
+ *
+ * One molecule per request. Two of the three answers are ordinary results; the
+ * third, `unavailable`, is how a worker says its resource tables did not load.
+ * That one travels as a *successful* answer on purpose: a rejection would be
+ * indistinguishable from the ordinary failure of one unreadable structure,
+ * whereas this one means every answer from every worker is worthless and the
+ * run must stop and say so.
+ */
+
+import type { ResourceSource } from './predictors.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from './types.ts';
+
+/** What every request carries, whichever job it asks for. */
+interface BaseRequest {
+  /**
+   * Where the worker registers OpenChemLib's resources from. In a browser this
+   * is always the absolute URL of the site's own `openchemlib-resources.json`,
+   * resolved on the main thread: a worker has no `document`, so it cannot read
+   * the deployment's mount path itself. The parsed tables are accepted as well,
+   * for the in-process fallback where there is no worker to post them to.
+   */
+  resources: ResourceSource;
+}
+
+/** Predict everything the tool shows for one molecule. */
+export interface PropertiesRequest extends BaseRequest {
+  kind: 'properties';
+  /** The caller's key for the row, echoed back so answers can arrive in any order. */
+  key: string;
+  /** The idCode, with the editor's atom coordinates after a space or without. */
+  idCode: string;
+  /**
+   * The name the source carried.
+   * @default the canonical SMILES
+   */
+  label?: string;
+}
+
+/** Explain why one risk came back as it did. */
+export interface RiskDetailRequest extends BaseRequest {
+  kind: 'riskDetail';
+  /** The idCode, coordinates included or not. */
+  idCode: string;
+  /** Which of the four risks to explain. */
+  risk: RiskType;
+}
+
+/** One job for a prediction worker. */
+export type PredictRequest = PropertiesRequest | RiskDetailRequest;
+
+/** What a prediction worker answers. */
+export type PredictResponse =
+  | { kind: 'properties'; key: string; properties: OsirisProperties }
+  | { kind: 'riskDetail'; detail: RiskDetail }
+  | { kind: 'unavailable'; message: string };
+
+/**
+ * Whether a message is a job this worker handles, so anything else is refused
+ * rather than read as one.
+ * @param value - Whatever was posted.
+ * @returns True when it is a well-formed request.
+ */
+export function isPredictRequest(value: unknown): value is PredictRequest {
+  if (typeof value !== 'object' || value === null) return false;
+  const request = value as {
+    kind?: unknown;
+    resources?: unknown;
+    idCode?: unknown;
+    key?: unknown;
+    risk?: unknown;
+  };
+  if (typeof request.idCode !== 'string') return false;
+  if (request.resources === undefined) return false;
+  if (request.kind === 'properties') return typeof request.key === 'string';
+  return request.kind === 'riskDetail' && typeof request.risk === 'string';
+}

package/src/osiris/core/predictionPool.ts

@@ -0,0 +1,237 @@
+/**
+ * A pool of prediction workers, answering one molecule at a time each.
+ *
+ * `createWorkerChannel` from `react-cheminfo/core` does the per-worker half —
+ * request identifiers so answers match callers whatever order they arrive in,
+ * timeouts, cancellation, and the in-process fallback where a page has no
+ * `Worker` at all. What it does not do is spread work over several workers, so
+ * that is what this adds: one channel per worker, a queue the pool owns, and at
+ * most one outstanding job per channel, which is what makes reordering possible
+ * at all. A channel asked for everything at once would post everything at once,
+ * and the row the reader is looking at would be answered forty-eighth.
+ */
+
+import { errorMessage } from '../../error/core/toError.ts';
+import { CancelledRequestError } from '../../worker/core/errors.ts';
+import { createWorkerChannel } from '../../worker/core/workerChannel.ts';
+import type { WorkerChannel } from '../../worker/core/workerChannelTypes.ts';
+
+import { predictionPoolSize } from './poolSize.ts';
+import type {
+  PredictionInput,
+  PredictionPool,
+  PredictionPoolOptions,
+  PredictionProgress,
+} from './poolTypes.ts';
+import type { PredictRequest, PredictResponse } from './predictProtocol.ts';
+import { createPredictionQueue } from './predictionQueue.ts';
+import { PredictorsUnavailableError } from './predictors.ts';
+import { requestRiskDetail } from './riskDetailRequest.ts';
+import { runPredictionJob } from './runPredictionJob.ts';
+import type { RiskDetail, RiskType } from './types.ts';
+
+type Channel = WorkerChannel<PredictRequest, PredictResponse>;
+
+interface Slot {
+  channel: Channel;
+  busy: boolean;
+}
+
+/**
+ * Start a pool of prediction workers.
+ *
+ * Workers are created lazily by the channels, on their first job, so a page
+ * that never predicts anything never loads OpenChemLib.
+ * @param options - See {@link PredictionPoolOptions}.
+ * @returns The pool.
+ */
+export function createPredictionPool(
+  options: PredictionPoolOptions,
+): PredictionPool {
+  const {
+    resources,
+    onResult,
+    onProgress,
+    onUnavailable,
+    createWorker,
+    runInProcess,
+    timeoutMs = 60_000,
+  } = options;
+  const size = predictionPoolSize(options.size);
+  const run = runInProcess ?? runPredictionJob;
+
+  const slots: Slot[] = [];
+  for (let index = 0; index < size; index++) {
+    slots.push({
+      channel: createWorkerChannel<PredictRequest, PredictResponse>(
+        createWorker,
+        {
+          name: `osiris-prediction-${index}`,
+          defaultTimeoutMs: timeoutMs,
+          runInProcess: run,
+        },
+      ),
+      busy: false,
+    });
+  }
+
+  const queue = createPredictionQueue();
+  const inFlight = new Set<string>();
+  let generation = 0;
+  let done = 0;
+  let total = 0;
+  let running = false;
+  let terminated = false;
+  let unavailable: string | null = null;
+
+  function progress(): PredictionProgress {
+    return { done, total, pending: queue.size + inFlight.size, running };
+  }
+
+  function report(): void {
+    onProgress?.(progress());
+  }
+
+  function pump(): void {
+    if (unavailable !== null) return;
+    for (const slot of slots) {
+      if (slot.busy) continue;
+      const next = queue.take();
+      if (next === undefined) break;
+      dispatch(slot, next);
+    }
+  }
+
+  function dispatch(slot: Slot, input: PredictionInput): void {
+    const era = generation;
+    slot.busy = true;
+    inFlight.add(input.key);
+    const request: PredictRequest = {
+      kind: 'properties',
+      resources,
+      key: input.key,
+      idCode: input.idCode,
+      ...(input.label === undefined ? {} : { label: input.label }),
+    };
+    slot.channel.request(request).then(
+      (response) => {
+        settle(slot, input, era, response, null);
+      },
+      (error: unknown) => {
+        settle(slot, input, era, null, error);
+      },
+    );
+  }
+
+  function settle(
+    slot: Slot,
+    input: PredictionInput,
+    era: number,
+    response: PredictResponse | null,
+    error: unknown,
+  ): void {
+    slot.busy = false;
+    inFlight.delete(input.key);
+
+    // An answer from a cancelled run is not counted and not reported, but the
+    // slot it just freed is still dispatched from: a submit made in the same
+    // turn as the cancel found every slot busy and queued its molecules here.
+    if (era === generation) {
+      if (response?.kind === 'unavailable') {
+        stop(response.message);
+        return;
+      }
+      if (response?.kind === 'properties') {
+        done += 1;
+        onResult?.({
+          key: input.key,
+          ok: true,
+          properties: response.properties,
+        });
+      } else if (error !== null && !(error instanceof CancelledRequestError)) {
+        done += 1;
+        onResult?.({ key: input.key, ok: false, message: errorMessage(error) });
+      }
+    }
+
+    pump();
+    if (queue.size === 0 && inFlight.size === 0) running = false;
+    report();
+  }
+
+  function clear(): void {
+    generation += 1;
+    queue.clear();
+    inFlight.clear();
+    running = false;
+    for (const slot of slots) slot.channel.cancel();
+  }
+
+  function stop(message: string): void {
+    clear();
+    unavailable = message;
+    report();
+    onUnavailable?.(message);
+  }
+
+  function leastBusy(): Slot {
+    let best = slots[0] as Slot;
+    for (const slot of slots) {
+      if (slot.channel.pendingCount < best.channel.pendingCount) best = slot;
+    }
+    return best;
+  }
+
+  return {
+    size,
+    get progress() {
+      return progress();
+    },
+
+    submit(molecules) {
+      if (unavailable !== null) return;
+      if (!running && queue.size === 0 && inFlight.size === 0) {
+        done = 0;
+        total = 0;
+      }
+      for (const input of molecules) {
+        if (inFlight.has(input.key)) continue;
+        if (queue.add(input)) total += 1;
+      }
+      running = queue.size > 0 || inFlight.size > 0;
+      pump();
+      report();
+    },
+
+    prioritize(keys) {
+      queue.prioritize(keys);
+    },
+
+    async riskDetail(idCode: string, risk: RiskType): Promise<RiskDetail> {
+      const response = await requestRiskDetail(
+        () => leastBusy().channel,
+        { kind: 'riskDetail', resources, idCode, risk },
+        () => !terminated && unavailable === null,
+      );
+      if (response.kind === 'unavailable') {
+        stop(response.message);
+        throw new PredictorsUnavailableError(response.message);
+      }
+      if (response.kind !== 'riskDetail') {
+        throw new Error('The worker answered something other than a detail.');
+      }
+      return response.detail;
+    },
+
+    cancel() {
+      clear();
+      report();
+    },
+
+    terminate() {
+      terminated = true;
+      clear();
+      for (const slot of slots) slot.channel.terminate();
+    },
+  };
+}

package/src/osiris/core/predictionQueue.ts

@@ -0,0 +1,89 @@
+/**
+ * What is still to be predicted, in the order it will be.
+ *
+ * Arrival order by default, because that is the order the reader read the file
+ * in. On top of it sits a short list of keys to answer first — the rows
+ * actually on screen — which is re-laid every time the reader scrolls or
+ * focuses a row. A key named as wanted that has since been answered or removed
+ * is skipped rather than looked up again.
+ */
+
+import type { PredictionInput } from './poolTypes.ts';
+
+/** The molecules waiting, and which of them to take next. */
+export interface PredictionQueue {
+  /** How many are waiting. */
+  readonly size: number;
+  /**
+   * Whether one is waiting.
+   * @param key - The row's key.
+   * @returns True when it is still queued.
+   */
+  has: (key: string) => boolean;
+  /**
+   * Queue one molecule, unless its key is already waiting.
+   * @param input - The molecule.
+   * @returns True when it was added.
+   */
+  add: (input: PredictionInput) => boolean;
+  /**
+   * Take the next molecule to predict: the first still-queued key of the wanted
+   * list, else the one that has waited longest.
+   * @returns The molecule, or `undefined` when nothing is waiting.
+   */
+  take: () => PredictionInput | undefined;
+  /**
+   * Replace the list of keys to answer first.
+   * @param keys - The keys, most wanted first.
+   */
+  prioritize: (keys: readonly string[]) => void;
+  /** Forget everything waiting. */
+  clear: () => void;
+}
+
+/**
+ * A queue of molecules to predict.
+ * @returns The queue, empty.
+ */
+export function createPredictionQueue(): PredictionQueue {
+  const waiting = new Map<string, PredictionInput>();
+  let wanted: readonly string[] = [];
+  let cursor = 0;
+
+  return {
+    get size() {
+      return waiting.size;
+    },
+    has: (key) => waiting.has(key),
+    add(input) {
+      if (waiting.has(input.key)) return false;
+      waiting.set(input.key, input);
+      return true;
+    },
+    take() {
+      while (cursor < wanted.length) {
+        const key = wanted[cursor] as string;
+        cursor += 1;
+        const next = waiting.get(key);
+        if (next !== undefined) {
+          waiting.delete(key);
+          return next;
+        }
+      }
+      const first = waiting.keys().next();
+      if (first.done === true) return undefined;
+      const next = waiting.get(first.value) as PredictionInput;
+      waiting.delete(first.value);
+      return next;
+    },
+    prioritize(keys) {
+      wanted = [...keys];
+      cursor = 0;
+    },
+    clear() {
+      waiting.clear();
+      wanted = [];
+      cursor = 0;
+    },
+  };
+}