react-cheminfo 0.64.0 → 0.65.0

package/src/molecule3d/ui/drawScene.ts

@@ -4,8 +4,19 @@ import { normalizeMolecule3DSettings } from '../core/settings.ts';
 
 import type { Molecule3DViewer } from './viewer.ts';
 
+/** The operations of the viewer a scene is drawn with. */
+export type SceneViewer = Pick<
+  Molecule3DViewer,
+  | 'showMolecule'
+  | 'hideMolecule'
+  | 'showSurface'
+  | 'showMeasurements'
+  | 'resetCamera'
+  | 'setCamera'
+>;
+
 /**
- * Draw the scene. `showMolecule` empties it, so the surface and the
+ * Draw the whole scene. `showMolecule` empties it, so the surface and the
  * measurements are added after the model, and the camera is framed last.
  * @param viewer - The viewer holding the canvas.
  * @param molfile - What to draw, or `null` to empty the scene.
@@ -17,7 +28,7 @@ import type { Molecule3DViewer } from './viewer.ts';
  * @returns Nothing; resolves once the scene is complete.
  */
 export async function drawScene(
-  viewer: Molecule3DViewer,
+  viewer: SceneViewer,
   molfile: Molecule3DFile | null,
   settings: Molecule3DSettings,
   measurements: readonly Measurement[],

package/src/molecule3d/ui/moleculeViewer3DProps.ts

@@ -72,7 +72,9 @@ export interface MoleculeViewer3DProps {
   /**
    * The measurements drawn over the model, when the site owns them. They name
    * atoms by position, so they carry over to another conformer of the same
-   * molecule; a site showing an unrelated molecule should clear them.
+   * molecule; a site showing an unrelated molecule should clear them. Changing
+   * them redraws the measurements and nothing else: the model, its highlights
+   * and the camera are left as they are.
    * @default undefined
    */
   measurements?: readonly Measurement[];

package/src/molecule3d/ui/sceneDrawer.ts

@@ -0,0 +1,132 @@
+/**
+ * What one canvas shows, what it is asked to show next, and the least work
+ * between the two.
+ *
+ * The measurements are drawn over the model, not into it: a change of them
+ * alone replaces their own representations and leaves the model, its surface,
+ * its highlights and the camera as they are. Only another molecule, or another
+ * style for it, draws the scene again, and only another molecule frames the
+ * camera. Draws run one after another, so a measurement never lands on a model
+ * that is half built, and the last request asked is the one drawn.
+ */
+
+import type { Molecule3DCamera } from '../core/camera.ts';
+import type { Measurement } from '../core/measurement.ts';
+import { sameMeasurements } from '../core/measurement.ts';
+import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
+import { sameMolecule3DSettings } from '../core/settings.ts';
+
+import type { SceneViewer } from './drawScene.ts';
+import { drawScene } from './drawScene.ts';
+
+/** What the canvas is asked to show. */
+export interface SceneRequest {
+  /** What to draw, or `null` to empty the scene. */
+  molfile: Molecule3DFile | null;
+  /** How the model is drawn. */
+  settings: Molecule3DSettings;
+  /** What is drawn over it. */
+  measurements: readonly Measurement[];
+  /** How the camera meets a molecule it has not shown before. */
+  frameNewMolecule: 'front' | 'keep';
+}
+
+/** Keeps one viewer showing the last scene it was asked for. */
+export class SceneDrawer {
+  /** The viewer drawn on. */
+  readonly viewer: SceneViewer;
+  readonly #takeLinkedCamera: () => Molecule3DCamera | null;
+  #asked: SceneRequest | null = null;
+  // The model on screen, or `null` when the next request must draw it again.
+  #drawn: Pick<SceneRequest, 'molfile' | 'settings'> | null = null;
+  // The measurements on screen, or `null` when the next request must draw them.
+  #measured: readonly Measurement[] | null = [];
+  // The molecule the camera was last framed on, so another one is told apart.
+  #framed: Molecule3DFile | null = null;
+  #queue: Promise<void> = Promise.resolve();
+
+  /**
+   * Start drawing on `viewer`, whose scene is empty.
+   * @param viewer - The viewer to draw on.
+   * @param takeLinkedCamera - Asked when a molecule is new: a camera to stand
+   * at instead of framing it, or `null`.
+   */
+  constructor(
+    viewer: SceneViewer,
+    takeLinkedCamera: () => Molecule3DCamera | null,
+  ) {
+    this.viewer = viewer;
+    this.#takeLinkedCamera = takeLinkedCamera;
+  }
+
+  /**
+   * Bring the canvas to `request`, once whatever was asked before is drawn.
+   * @param request - The scene to show; replaces any request still waiting.
+   * @returns Nothing; resolves once the canvas shows the last request asked,
+   * and rejects with what stopped it from being drawn.
+   */
+  draw(request: SceneRequest): Promise<void> {
+    this.#asked = request;
+    const drawn = this.#queue.then(() => this.#catchUp());
+    this.#queue = drawn.catch(ignore);
+    return drawn;
+  }
+
+  async #catchUp(): Promise<void> {
+    const request = this.#asked;
+    if (request === null) return;
+    const drawn = this.#drawn;
+    if (
+      drawn !== null &&
+      sameFile(drawn.molfile, request.molfile) &&
+      sameMolecule3DSettings(drawn.settings, request.settings)
+    ) {
+      await this.#measure(request);
+      return;
+    }
+    await this.#redraw(request);
+  }
+
+  // The model stays: only the measurements over it can have changed.
+  async #measure(request: SceneRequest): Promise<void> {
+    const { molfile, measurements } = request;
+    const measured = this.#measured;
+    if (measured !== null && sameMeasurements(measured, measurements)) return;
+    // As for the model: a list that fails partway is drawn again next time.
+    this.#measured = null;
+    // An empty scene has nothing to measure; the list waits for a molecule.
+    if (molfile !== null) await this.viewer.showMeasurements(measurements);
+    this.#measured = measurements;
+  }
+
+  async #redraw(request: SceneRequest): Promise<void> {
+    const { molfile, settings, measurements, frameNewMolecule } = request;
+    const isNew =
+      molfile !== null &&
+      (this.#framed === null || !sameFile(this.#framed, molfile));
+    this.#framed = molfile;
+    // A link's camera is spent on the first molecule framed; afterwards the
+    // camera is the reader's and a new molecule is framed as usual.
+    const linked = isNew ? this.#takeLinkedCamera() : null;
+    const frameCamera = isNew && linked === null ? frameNewMolecule : 'none';
+    // Kept only once drawn: a draw that fails is drawn again by the next
+    // request, whatever that one changes.
+    this.#drawn = null;
+    await drawScene(this.viewer, molfile, settings, measurements, frameCamera);
+    this.#drawn = { molfile, settings };
+    this.#measured = measurements;
+    if (linked !== null) await this.viewer.setCamera(linked);
+  }
+}
+
+function sameFile(
+  first: Molecule3DFile | null,
+  second: Molecule3DFile | null,
+): boolean {
+  if (first === null || second === null) return first === second;
+  return first.format === second.format && first.data === second.data;
+}
+
+function ignore(): void {
+  // A failure reached the caller of `draw`; the next draw still runs.
+}

package/src/molecule3d/ui/useMoleculeScene.ts

@@ -5,18 +5,18 @@
  * The draw is coalesced into one animation frame, so dragging a slider costs
  * one rebuild rather than one per pixel, and the camera is framed only when the
  * molecule is new — a restyle that snapped the view back would undo the
- * reader's orientation.
+ * reader's orientation. What each draw rebuilds is the scene drawer's call: a
+ * change of the measurements alone redraws them and nothing else.
  */
 
 import type { RefObject } from 'react';
 import { useCallback, useEffect, useRef } from 'react';
 
-import type { Molecule3DCamera } from '../core/camera.ts';
 import type { Measurement } from '../core/measurement.ts';
 import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
 
-import { drawScene } from './drawScene.ts';
 import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+import { SceneDrawer } from './sceneDrawer.ts';
 import {
   DEFAULT_CAMERA_SETTLE_DELAY,
   useSharedCamera,
@@ -71,10 +71,7 @@ export function useMoleculeScene(options: MoleculeSceneOptions): MoleculeScene {
     onFailureChange,
     camera: cameraProps,
   } = options;
-  const framedRef = useRef<{
-    molfile: Molecule3DFile;
-    viewer: Molecule3DViewer;
-  } | null>(null);
+  const drawerRef = useRef<SceneDrawer | null>(null);
   const reportFailure = useRef(onFailureChange);
   useEffect(() => {
     reportFailure.current = onFailureChange;
@@ -92,31 +89,24 @@ export function useMoleculeScene(options: MoleculeSceneOptions): MoleculeScene {
   useEffect(() => {
     const viewer = viewerRef.current;
     if (container === null || viewer === null) return;
+    // A new viewer starts from an empty scene, so it gets a drawer of its own.
+    if (drawerRef.current?.viewer !== viewer) {
+      drawerRef.current = new SceneDrawer(viewer, camera.takeLinkedCamera);
+    }
+    const drawer = drawerRef.current;
     let cancelled = false;
     const frame = requestAnimationFrame(() => {
-      const framed = framedRef.current;
-      const isNew =
-        molfile !== null &&
-        (framed?.molfile !== molfile || framed.viewer !== viewer);
-      framedRef.current = molfile === null ? null : { molfile, viewer };
-      // The link's camera is spent on the first molecule framed; afterwards the
-      // camera is the reader's and a new molecule is framed as usual.
-      const linked: Molecule3DCamera | null = isNew
-        ? camera.takeLinkedCamera()
-        : null;
-      const frameCamera = isNew && linked === null ? frameNewMolecule : 'none';
-      void drawScene(viewer, molfile, settings, measurements, frameCamera)
-        .then(() => {
-          if (cancelled) return;
-          if (linked !== null) void viewer.setCamera(linked);
-          reportFailure.current(null);
-        })
-        .catch((error: unknown) => {
+      drawer.draw({ molfile, settings, measurements, frameNewMolecule }).then(
+        () => {
+          if (!cancelled) reportFailure.current(null);
+        },
+        (error: unknown) => {
           if (cancelled) return;
           reportFailure.current(
             error instanceof Error ? error.message : String(error),
           );
-        });
+        },
+      );
     });
     return () => {
       cancelled = true;

package/src/molecule3d/ui/useSharedCamera.ts

@@ -37,9 +37,7 @@ export interface SharedCameraOptions {
 
 /**
  * What {@link useSharedCamera} answers. The same object on every render: the
- * draw effect keys on it, and a fresh one would tear the scene down and build
- * it again — which makes molstar frame the model afresh and loses the camera a
- * link had just restored.
+ * draw effect keys on it, and a fresh one would run it again for nothing.
  */
 export interface SharedCamera {
   /**

package/src/moleculesClient/core/index.ts

@@ -0,0 +1,19 @@
+export { createMoleculesClient } from './moleculesClient.ts';
+export type {
+  MoleculesClient,
+  MoleculesClientOptions,
+} from './moleculesClientApi.ts';
+export { MoleculesError } from './moleculesClientApi.ts';
+export type {
+  ImportStarted,
+  ImportState,
+  LookupResponse,
+  LookupResult,
+  MoleculeInfo,
+  MoleculeInput,
+  PurgeResponse,
+  RetryDetails,
+  SubmitResponse,
+  SubmitResult,
+  SubmitSummary,
+} from './moleculesTypes.ts';

package/src/moleculesClient/core/moleculesClient.ts

@@ -0,0 +1,175 @@
+import { XSadd } from 'ml-xsadd';
+
+import { trimTrailingSlash } from '../../router/core/address.ts';
+
+import type {
+  MoleculesClient,
+  MoleculesClientOptions,
+} from './moleculesClientApi.ts';
+import { MoleculesError } from './moleculesClientApi.ts';
+import type {
+  ImportStarted,
+  ImportState,
+  LookupResponse,
+  PurgeResponse,
+  SubmitResponse,
+} from './moleculesTypes.ts';
+import {
+  causeOf,
+  gzipBody,
+  messageOf,
+  pause,
+  requestSignal,
+  retryAfter,
+} from './requestRetry.ts';
+
+/** Statuses a request is tried again on: the server is busy or in between. */
+const RETRIED_STATUSES = new Set([429, 502, 503, 504]);
+
+/** The doublings of the pause, after which it stays where it is. */
+const MAX_DOUBLINGS = 20;
+
+/** One request, as it is tried again. */
+interface Call {
+  method: 'GET' | 'POST';
+  path: string;
+  payload: Uint8Array<ArrayBuffer> | undefined;
+  started: number;
+}
+
+/** What one attempt came to: the answer, or why another is worth it. */
+type Outcome<T> =
+  | { answered: true; value: T }
+  | {
+      answered: false;
+      status: number | undefined;
+      reason: string;
+      retryAfterMs: number | undefined;
+    };
+
+/**
+ * A client of the routes a source writes through on molecules.cheminfo.org,
+ * retrying while the server is busy (503), throttling (429), being restarted
+ * (502, 504) or out of reach. Each attempt has its own deadline, the pauses
+ * double with a spread and honour `Retry-After`, and bodies travel gzipped.
+ * Browser-safe: it reads no Node module.
+ * @param options - Where it answers, the token, and how hard to insist.
+ * @returns The client.
+ */
+export function createMoleculesClient(
+  options: MoleculesClientOptions,
+): MoleculesClient {
+  const {
+    token,
+    maxRetryMs = 1_800_000,
+    initialDelayMs = 1000,
+    maxDelayMs = 60_000,
+    requestTimeoutMs = 600_000,
+    signal,
+    onRetry,
+    fetch: fetchImplementation = globalThis.fetch,
+    random = new XSadd().random,
+  } = options;
+  const baseUrl = trimTrailingSlash(options.baseUrl);
+
+  async function attemptOnce<T>(call: Call): Promise<Outcome<T>> {
+    let response: Response;
+    try {
+      response = await fetchImplementation(`${baseUrl}${call.path}`, {
+        method: call.method,
+        headers: {
+          authorization: `Bearer ${token}`,
+          ...(call.payload === undefined
+            ? {}
+            : {
+                'content-type': 'application/json',
+                'content-encoding': 'gzip',
+              }),
+        },
+        body: call.payload,
+        signal: requestSignal(signal, requestTimeoutMs),
+      });
+      if (response.ok) {
+        return { answered: true, value: (await response.json()) as T };
+      }
+    } catch (error: unknown) {
+      if (signal?.aborted) throw signal.reason;
+      return {
+        answered: false,
+        status: undefined,
+        reason: causeOf(error),
+        retryAfterMs: undefined,
+      };
+    }
+    const text = await response.text();
+    const reason = messageOf(text) ?? response.statusText;
+    if (!RETRIED_STATUSES.has(response.status)) {
+      throw new MoleculesError(
+        `${call.method} ${call.path} answered ${response.status}: ${reason}`,
+        response.status,
+        text,
+      );
+    }
+    const asked = retryAfter(response.headers.get('retry-after'), Date.now());
+    return {
+      answered: false,
+      status: response.status,
+      reason,
+      retryAfterMs: asked,
+    };
+  }
+
+  async function attempt<T>(call: Call, number: number): Promise<T> {
+    signal?.throwIfAborted();
+    const outcome = await attemptOnce<T>(call);
+    if (outcome.answered) return outcome.value;
+    const backoff =
+      initialDelayMs *
+      2 ** Math.min(number - 1, MAX_DOUBLINGS) *
+      (0.5 + random() * 0.5);
+    const delayMs = Math.min(maxDelayMs, outcome.retryAfterMs ?? backoff);
+    const elapsed = Date.now() - call.started;
+    if (elapsed + delayMs > maxRetryMs) {
+      throw new MoleculesError(
+        `${call.method} ${call.path} kept failing for ${Math.round(elapsed / 1000)} s: ${outcome.reason}`,
+        outcome.status ?? 0,
+        outcome.reason,
+      );
+    }
+    onRetry?.({
+      method: call.method,
+      path: call.path,
+      attempt: number,
+      status: outcome.status,
+      reason: outcome.reason,
+      delayMs,
+    });
+    await pause(delayMs, signal);
+    return attempt<T>(call, number + 1);
+  }
+
+  async function request<T>(
+    method: 'GET' | 'POST',
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const started = Date.now();
+    const payload =
+      body === undefined ? undefined : await gzipBody(JSON.stringify(body));
+    return attempt<T>({ method, path, payload, started }, 1);
+  }
+
+  return {
+    startImport: () => request<ImportStarted>('POST', '/v1/imports'),
+    importState: () => request<ImportState>('GET', '/v1/imports'),
+    submit: (molecules, { returnInfo = false } = {}) =>
+      request<SubmitResponse>('POST', '/v1/submit', { molecules, returnInfo }),
+    lookup: (queries, kind) =>
+      request<LookupResponse>('POST', '/v1/batch', { queries, kind }),
+    purge: (importKey, { dryRun = false, force = false } = {}) =>
+      request<PurgeResponse>('POST', `/v1/imports/${importKey}/purge`, {
+        dryRun,
+        force,
+      }),
+  };
+}

package/src/moleculesClient/core/moleculesClientApi.ts

@@ -0,0 +1,120 @@
+import type {
+  ImportStarted,
+  ImportState,
+  LookupResponse,
+  MoleculeInput,
+  PurgeResponse,
+  RetryDetails,
+  SubmitResponse,
+} from './moleculesTypes.ts';
+
+/** How a client reaches molecules.cheminfo.org, and how hard it insists. */
+export interface MoleculesClientOptions {
+  /** Where molecules.cheminfo.org answers, e.g. `https://molecules.cheminfo.org`. */
+  baseUrl: string;
+  /** The token issued for the source the client writes for. */
+  token: string;
+  /**
+   * How long one request may keep being retried while the server is busy or
+   * unreachable, in milliseconds.
+   * @default 1_800_000 - half an hour
+   */
+  maxRetryMs?: number;
+  /**
+   * The first pause before a retry; each next one doubles, up to `maxDelayMs`.
+   * @default 1000
+   */
+  initialDelayMs?: number;
+  /**
+   * The longest pause between two attempts, a `Retry-After` included.
+   * @default 60_000
+   */
+  maxDelayMs?: number;
+  /**
+   * How long one attempt may take before it is given up and retried.
+   * @default 600_000
+   */
+  requestTimeoutMs?: number;
+  /**
+   * Stops every request, and every pause between two attempts.
+   * @default undefined - nothing stops them
+   */
+  signal?: AbortSignal;
+  /**
+   * Told about every retry, e.g. to log it.
+   * @default undefined - retries are silent
+   */
+  onRetry?: (details: RetryDetails) => void;
+  /**
+   * The fetch to use, for tests.
+   * @default globalThis.fetch
+   */
+  fetch?: typeof fetch;
+  /**
+   * A number from 0 to 1 that spreads the pauses, so clients that failed
+   * together do not all come back at the same instant.
+   * @default an unseeded `XSadd`
+   */
+  random?: () => number;
+}
+
+/** The routes a source writes through on molecules.cheminfo.org. */
+export interface MoleculesClient {
+  /** Take the source's next import key: the start of a full import. */
+  startImport: () => Promise<ImportStarted>;
+  /** Where the source's import stands. */
+  importState: () => Promise<ImportState>;
+  /**
+   * Send up to 1000 molecules for the source, under its current import key.
+   * @param molecules - Each with its identifier and exactly one notation.
+   * @param options - Whether every answer carries the molecule's properties.
+   * @param options.returnInfo - Ask for them; `false` by default.
+   */
+  submit: (
+    molecules: MoleculeInput[],
+    options?: { returnInfo?: boolean },
+  ) => Promise<SubmitResponse>;
+  /**
+   * Compute up to 1000 molecules without storing anything, for a source
+   * molecules.cheminfo.org imports itself.
+   * @param queries - The structures, all in one notation.
+   * @param kind - The notation.
+   */
+  lookup: (
+    queries: string[],
+    kind: 'smiles' | 'molfile' | 'idCode',
+  ) => Promise<LookupResponse>;
+  /**
+   * Remove the entries an import did not send again.
+   * @param importKey - The key the import took.
+   * @param options - Only count, or remove even more than half.
+   * @param options.dryRun - Only count; `false` by default.
+   * @param options.force - Remove even when that is more than half; `false` by
+   * default.
+   */
+  purge: (
+    importKey: number,
+    options?: { dryRun?: boolean; force?: boolean },
+  ) => Promise<PurgeResponse>;
+}
+
+/** A request molecules.cheminfo.org refused, or that kept failing. */
+export class MoleculesError extends Error {
+  /** The status answered, or 0 when nothing was. */
+  readonly status: number;
+  /** What the server said, as text. */
+  readonly body: string;
+
+  /**
+   * A failed request, with what the server answered.
+   * @param message - What failed, and why.
+   * @param status - The status answered, or 0 when nothing was.
+   * @param body - What the server said.
+   */
+  constructor(message: string, status: number, body: string) {
+    super(message);
+    this.name = 'MoleculesError';
+    this.status = status;
+    this.body = body;
+  }
+}