react-cheminfo 0.64.0 → 0.65.0

package/src/moleculesClient/core/moleculesTypes.ts

@@ -0,0 +1,163 @@
+/** One molecule a source sends: its identifier, and exactly one notation. */
+export interface MoleculeInput {
+  /** The source's identifier for it, which its address is written with. */
+  id: string;
+  /**
+   * The structure as SMILES.
+   * @default undefined - another notation is given
+   */
+  smiles?: string;
+  /**
+   * The structure as a molfile.
+   * @default undefined - another notation is given
+   */
+  molfile?: string;
+  /**
+   * The structure as an OpenChemLib idCode.
+   * @default undefined - another notation is given
+   */
+  idCode?: string;
+}
+
+/** What molecules.cheminfo.org computed for a structure. */
+export interface MoleculeInfo {
+  mf: string;
+  mw: number;
+  em: number;
+  charge: number;
+  idCode: string;
+  noStereoID: string;
+  noStereoTautomerID: string;
+  failedTautomerID: number;
+  /** The 512-bit FragFp, sixteen signed 32-bit words. */
+  ssIndex: number[];
+  logS: number;
+  logP: number;
+  acceptorCount: number;
+  donorCount: number;
+  stereoCenterCount: number;
+  rotatableBondCount: number;
+  polarSurfaceArea: number;
+  nbFragments: number;
+  /**
+   * The degree of unsaturation, when the formula has one.
+   * @default undefined
+   */
+  unsaturation?: number;
+  atoms: Record<string, number>;
+  /** The hashes, as 16 hex digits: never JSON numbers, which would round them. */
+  idCodeHash: string;
+  noStereoHash: string;
+  noStereoTautomerHash: string;
+  createdAt: number | null;
+}
+
+/** What became of one molecule a source sent. */
+export interface SubmitResult {
+  id: string | null;
+  /**
+   * The structure it was read as.
+   * @default undefined - it could not be read
+   */
+  idCode?: string;
+  /**
+   * Whether molecules.cheminfo.org held the structure already.
+   * @default undefined - it could not be read
+   */
+  molecule?: 'created' | 'existing';
+  /**
+   * What became of the source's entry.
+   * @default undefined - it could not be read
+   */
+  link?: 'added' | 'unchanged' | 'moved';
+  /**
+   * The computed properties, when they were asked for.
+   * @default undefined
+   */
+  info?: MoleculeInfo;
+  /**
+   * Why the molecule was refused.
+   * @default undefined - it was taken
+   */
+  error?: string;
+}
+
+/** How a batch was taken. */
+export interface SubmitSummary {
+  total: number;
+  /** Molecules new to molecules.cheminfo.org. */
+  created: number;
+  /** Entries new to the source. */
+  added: number;
+  /** Identifiers moved to another structure. */
+  moved: number;
+  unchanged: number;
+  failed: number;
+}
+
+/** What `POST /v1/submit` answers: one result per molecule, in their order. */
+export interface SubmitResponse {
+  source: string;
+  results: SubmitResult[];
+  summary: SubmitSummary;
+}
+
+/** What `POST /v1/imports` answers: the start of a full import. */
+export interface ImportStarted {
+  source: string;
+  importKey: number;
+  importStartedAt: number;
+}
+
+/** What `GET /v1/imports` answers: where the source's import stands. */
+export interface ImportState {
+  source: string;
+  importKey: number;
+  importStartedAt: number | null;
+  updatedAt: number | null;
+  entries: number;
+  stale: number;
+}
+
+/** What a purge answers. */
+export interface PurgeResponse {
+  source: string;
+  importKey: number;
+  dryRun: boolean;
+  /** The entries the import did not send again, removed or to be removed. */
+  removed: number;
+  /** The entries the source holds after. */
+  remaining: number;
+}
+
+/** One answer of `POST /v1/batch`: the molecule a query reads as, or why not. */
+export interface LookupResult {
+  query: string;
+  result: MoleculeInfo | null;
+  /** Whether molecules.cheminfo.org lists it, rather than computing it now. */
+  cached: boolean;
+  /**
+   * Why the query could not be read.
+   * @default undefined - it was read
+   */
+  error?: string;
+}
+
+/** What `POST /v1/batch` answers: one result per query, in their order. */
+export interface LookupResponse {
+  results: LookupResult[];
+}
+
+/** Why a request is tried again, and when. */
+export interface RetryDetails {
+  method: string;
+  path: string;
+  attempt: number;
+  /**
+   * The status that was answered.
+   * @default undefined - nothing was answered
+   */
+  status?: number;
+  reason: string;
+  delayMs: number;
+}

package/src/moleculesClient/core/requestRetry.ts

@@ -0,0 +1,118 @@
+import { toError } from '../../error/core/toError.ts';
+
+/**
+ * The pieces of a request that is tried again: its deadline, the pause the
+ * server asks for, what an error answer says, and what a failed fetch says.
+ * Browser-safe: no Node module is read.
+ */
+
+/**
+ * The signal one attempt runs under: the caller's, and its own deadline.
+ * @param signal - The caller's, if any.
+ * @param timeoutMs - How long the attempt may take.
+ * @returns The signal.
+ */
+export function requestSignal(
+  signal: AbortSignal | undefined,
+  timeoutMs: number,
+): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  return signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+}
+
+/**
+ * How long a `Retry-After` header asks to wait.
+ * @param header - Its value: seconds, or an HTTP date.
+ * @param now - The current instant, in epoch milliseconds.
+ * @returns The pause in milliseconds, or `undefined` when there is none to read.
+ */
+export function retryAfter(
+  header: string | null,
+  now: number,
+): number | undefined {
+  if (header === null || header.trim() === '') return undefined;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const date = Date.parse(header);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - now);
+}
+
+/**
+ * The message of an error body Fastify wrote, or the body itself.
+ * @param text - The body.
+ * @returns The message, or `undefined` when the body is empty.
+ */
+export function messageOf(text: string): string | undefined {
+  if (text.trim() === '') return undefined;
+  try {
+    const body = JSON.parse(text) as { message?: unknown } | null;
+    if (typeof body?.message === 'string') return body.message;
+  } catch {
+    return text.slice(0, 500);
+  }
+  return text.slice(0, 500);
+}
+
+/**
+ * What a failed fetch says, its cause included: undici reports a refused
+ * connection as `fetch failed` with the reason in `cause` — and when several
+ * addresses were tried, in the first error of an AggregateError whose own
+ * message is empty.
+ * @param error - What was thrown.
+ * @returns The message, e.g. `fetch failed: connect ECONNREFUSED 127.0.0.1:11980`.
+ */
+export function causeOf(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+  const { cause, message } = error;
+  if (!(cause instanceof Error)) return message;
+  const first: unknown =
+    cause instanceof AggregateError ? cause.errors[0] : undefined;
+  const code = (cause as { code?: unknown }).code;
+  const detail =
+    cause.message ||
+    (first instanceof Error ? first.message : '') ||
+    (typeof code === 'string' ? code : '') ||
+    cause.name;
+  return `${message}: ${detail}`;
+}
+
+/**
+ * A request body gzipped, as HTTP's `Content-Encoding: gzip` carries it: a
+ * batch of molfiles shrinks several times over.
+ * @param text - The body, written out.
+ * @returns The gzipped bytes.
+ */
+export async function gzipBody(text: string): Promise<Uint8Array<ArrayBuffer>> {
+  const stream = new Blob([text])
+    .stream()
+    .pipeThrough(new CompressionStream('gzip'));
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+/**
+ * Wait, unless the signal stops the wait first.
+ * @param milliseconds - How long.
+ * @param signal - What stops it, if anything.
+ * @returns When the time has passed.
+ * @throws {unknown} The signal's reason, when it aborts first.
+ */
+export function pause(
+  milliseconds: number,
+  signal: AbortSignal | undefined,
+): Promise<void> {
+  return new Promise((done, fail) => {
+    if (signal?.aborted) {
+      fail(toError(signal.reason));
+      return;
+    }
+    const abort = () => {
+      clearTimeout(timer);
+      fail(toError(signal?.reason));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', abort);
+      done();
+    }, milliseconds);
+    signal?.addEventListener('abort', abort, { once: true });
+  });
+}

package/src/molstar/core/camera.ts

@@ -34,10 +34,11 @@ const SPIN_AXIS = Vec3.create(0, 1, 0);
  * measured against — so reading a camera and applying it are the same move in
  * opposite directions.
  * @param radius - Radius of the scene's visible bounding sphere.
+ * @param margin - Fraction of the radius kept as breathing room.
  * @returns The framed radius.
  */
-export function framedRadius(radius: number): number {
-  return Math.max(radius * (1 + FRAMING_MARGIN), MINIMUM_FRAMING_RADIUS);
+export function framedRadius(radius: number, margin = FRAMING_MARGIN): number {
+  return Math.max(radius * (1 + margin), MINIMUM_FRAMING_RADIUS);
 }
 
 /**

package/src/molstar/core/framing.ts

@@ -0,0 +1,200 @@
+/**
+ * Framing a scene: the sphere everything on screen fits in, the camera moved
+ * to show it whole, and the zoom onto one point of it.
+ *
+ * What is on screen is measured rather than read off molstar: a canvas's own
+ * `boundingSphereVisible` is read once when the canvas is built, a
+ * ball-and-stick representation pads its sphere by the largest ball it could
+ * ever draw, and an isosurface reports the whole sampled box. So a site hands
+ * the spheres it measured itself, and names which render objects are worth
+ * their own sphere — a mesh it built, whose sphere is exactly its vertices.
+ */
+
+import type { GraphicsRenderObject } from 'molstar/lib/mol-gl/render-object.js';
+import { BoundaryHelper } from 'molstar/lib/mol-math/geometry/boundary-helper.js';
+import { Sphere3D } from 'molstar/lib/mol-math/geometry.js';
+import { Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+
+import {
+  DEFAULT_CAMERA_DURATION,
+  FRAMING_MARGIN,
+  MINIMUM_FRAMING_RADIUS,
+  framedRadius,
+} from './camera.ts';
+
+/**
+ * Frame everything on screen.
+ *
+ * Without an orientation the camera keeps the direction it already points in,
+ * which is what a reframe after a reader turned the scene must do. A scene with
+ * nothing measured is framed by molstar's own reset.
+ * @param plugin - The molstar context.
+ * @param options - What to frame, from where, and how fast.
+ */
+export function resetCamera(
+  plugin: PluginContext,
+  options: ResetCameraOptions = {},
+): void {
+  const { durationMs = DEFAULT_CAMERA_DURATION, margin = FRAMING_MARGIN } =
+    options;
+  const { sphere, orientation } = options;
+  plugin.canvas3d?.commit(true);
+  const scene = sphere === undefined ? sceneSphere(plugin, options) : sphere;
+  if (scene === null || scene.radius <= 0) {
+    plugin.managers.camera.reset(undefined, durationMs);
+    return;
+  }
+  const { center, radius } = scene;
+  const [x = 0, y = 0, z = 0] = center;
+  focusPoint(plugin, [x, y, z], framedRadius(radius, margin), {
+    durationMs,
+    orientation,
+  });
+}
+
+/**
+ * Frame one ball of the scene: an atom picked, the centre of a bond, the
+ * whole scene.
+ *
+ * The canvas is committed first — `add()` only queues, and a queued object
+ * belongs to no bounding sphere yet — and the ball is framed with no padding
+ * of molstar's own, whose 4 Å default leaves water a twentieth of the canvas.
+ * @param plugin - The molstar context.
+ * @param centre - What to frame, Cartesian ångström.
+ * @param radius - Radius of the ball to fit, ångström.
+ * @param options - From where, and how fast.
+ */
+export function focusPoint(
+  plugin: PluginContext,
+  centre: Point3,
+  radius: number,
+  options: FocusOptions = {},
+): void {
+  const { durationMs = DEFAULT_CAMERA_DURATION, orientation } = options;
+  plugin.canvas3d?.commit(true);
+  const target = Vec3.create(centre[0], centre[1], centre[2]);
+  const camera = plugin.canvas3d?.camera;
+  if (orientation !== undefined && camera !== undefined) {
+    // `getFocus` only matches the sign of a direction against the current
+    // camera; `getInvariantFocus` takes the direction and the up as given.
+    const { eye, up } = orientation;
+    plugin.managers.camera.setSnapshot(
+      camera.getInvariantFocus(
+        target,
+        Math.max(radius, MINIMUM_FRAMING_RADIUS),
+        Vec3.create(up[0], up[1], up[2]),
+        Vec3.create(-eye[0], -eye[1], -eye[2]),
+      ),
+      durationMs,
+    );
+    return;
+  }
+  plugin.managers.camera.focusSphere(Sphere3D.create(target, radius), {
+    extraRadius: 0,
+    minRadius: MINIMUM_FRAMING_RADIUS,
+    durationMs,
+  });
+}
+
+/**
+ * The one sphere everything worth framing fits in: the spheres a site
+ * measured itself, and those of the render objects it names.
+ * @param plugin - The molstar context.
+ * @param options - The measured spheres, and which render objects count.
+ * @returns The sphere, or `null` when nothing was measured.
+ */
+export function sceneSphere(
+  plugin: PluginContext,
+  options: SceneSphereOptions = {},
+): Sphere3D | null {
+  const spheres: Sphere3D[] = [];
+  for (const sphere of options.spheres ?? []) {
+    if (sphere.radius > 0) spheres.push(sphere);
+  }
+  const { include } = options;
+  const canvas3d = plugin.canvas3d;
+  if (include !== undefined && canvas3d !== undefined) {
+    canvas3d.commit(true);
+    for (const object of canvas3d.getRenderObjects()) {
+      if (!include(object)) continue;
+      const sphere = object.values.boundingSphere.ref.value;
+      if (sphere.radius > 0) spheres.push(sphere);
+    }
+  }
+  return unionSphere(spheres);
+}
+
+/**
+ * The smallest sphere holding a set of spheres, as molstar's own camera
+ * manager computes it.
+ * @param spheres - The spheres to hold.
+ * @returns It, the one sphere itself when there is one, `null` when there is none.
+ */
+export function unionSphere(spheres: readonly Sphere3D[]): Sphere3D | null {
+  const first = spheres[0];
+  if (first === undefined) return null;
+  if (spheres.length === 1) return first;
+  boundary.reset();
+  for (const sphere of spheres) boundary.includeSphere(sphere);
+  boundary.finishedIncludeStep();
+  for (const sphere of spheres) boundary.radiusSphere(sphere);
+  return boundary.getSphere();
+}
+
+/** A point in Cartesian ångström. */
+export type Point3 = readonly [x: number, y: number, z: number];
+
+/** Where the camera stands to look at a scene. */
+export interface ViewOrientation {
+  /** The direction from what is looked at to the eye. */
+  eye: Point3;
+  /** The direction that is up on screen. */
+  up: Point3;
+}
+
+/** How {@link focusPoint} moves the camera. */
+export interface FocusOptions {
+  /**
+   * Transition length, in milliseconds; 0 jumps.
+   * @default 250
+   */
+  durationMs?: number;
+  /**
+   * Where to look from.
+   * @default undefined — the direction the camera already points in
+   */
+  orientation?: ViewOrientation;
+}
+
+/** What {@link sceneSphere} measures. */
+export interface SceneSphereOptions {
+  /**
+   * Spheres the site measured itself: a model from its own atoms, a part of
+   * the scene registered as it was drawn.
+   * @default []
+   */
+  spheres?: readonly Sphere3D[];
+  /**
+   * Which render objects of the canvas count with their own sphere.
+   * @default undefined — none does
+   */
+  include?: (object: GraphicsRenderObject) => boolean;
+}
+
+/** What {@link resetCamera} frames, and how. */
+export interface ResetCameraOptions extends SceneSphereOptions, FocusOptions {
+  /**
+   * The sphere to frame, measured by the caller, instead of the scene's.
+   * @default undefined — the sphere `sceneSphere` measures
+   */
+  sphere?: Sphere3D | null;
+  /**
+   * Fraction of the radius kept as breathing room around the scene.
+   * @default 0.08
+   */
+  margin?: number;
+}
+
+// Reused across calls, as molstar's own camera manager does.
+const boundary = new BoundaryHelper('98');

package/src/molstar/core/hover.ts

@@ -38,6 +38,32 @@ export function subscribeHover(
   };
 }
 
+/** What the pointer rests on, in a line, and the loci it names. */
+export interface HoverLabel {
+  /** `O 1`, `Si 4 — O 8`, or the label a drawing of the site carries. */
+  label: string;
+  /** The loci, for a site that wants more of it — the atom it holds, say. */
+  loci: Loci;
+}
+
+/**
+ * Report the label of whatever the pointer rests on: an atom named as a
+ * reader would name it, anything else by the label it was drawn with.
+ * @param plugin - The molstar context.
+ * @param listener - Called with the label and its loci, or `null` when the
+ * pointer leaves everything or rests on something with nothing to say.
+ * @returns The unsubscribe function.
+ */
+export function subscribeHoverLabel(
+  plugin: PluginContext,
+  listener: (hover: HoverLabel | null) => void,
+): () => void {
+  return subscribeHover(plugin, (loci) => {
+    const label = loci === null ? null : (atomText(loci) ?? lociText(loci));
+    listener(label === null || loci === null ? null : { label, loci });
+  });
+}
+
 /**
  * The one line a loci is worth, in molstar's own words.
  * @param loci - What the pointer is over.

package/src/molstar/core/index.ts

@@ -25,8 +25,28 @@ export {
   framedRadius,
   setSpin,
 } from './camera.ts';
+export type {
+  FocusOptions,
+  Point3,
+  ResetCameraOptions,
+  SceneSphereOptions,
+  ViewOrientation,
+} from './framing.ts';
+export {
+  focusPoint,
+  resetCamera,
+  sceneSphere,
+  unionSphere,
+} from './framing.ts';
 export { HighlightPainter, highlightOverpaint } from './highlights.ts';
-export { atomName, atomText, lociText, subscribeHover } from './hover.ts';
+export type { HoverLabel } from './hover.ts';
+export {
+  atomName,
+  atomText,
+  lociText,
+  subscribeHover,
+  subscribeHoverLabel,
+} from './hover.ts';
 export type { MolstarPluginOptions } from './plugin.ts';
 export { MolstarPlugin } from './plugin.ts';
 export { captureScene } from './captureScene.ts';

package/src/pedagogy/core/answers.ts

@@ -0,0 +1,94 @@
+/**
+ * Reading what a student typed into an answer box, and the verdicts a grader
+ * gives a box it cannot grade.
+ */
+
+import { CHROME_CATALOG } from '../../i18n/core/chromeCatalog.ts';
+import type { Language } from '../../i18n/core/languages.ts';
+import { DEFAULT_LANGUAGE } from '../../i18n/core/languages.ts';
+import { catalogTranslate } from '../../i18n/core/translate.ts';
+import { readNumber } from '../../number/core/numberText.ts';
+
+import type { FieldCase } from './series.ts';
+
+/**
+ * Read a number the way a student types it: `42`, `+5`, `−3` with a real minus
+ * sign, `1,5` with a decimal comma, `75.8 %`, `1 000`.
+ *
+ * What a typed answer carries beyond a number box — a typographic minus, a
+ * percent sign, a space between thousands — is taken off first; the number
+ * itself is read by `readNumber`, as every box of the family reads one.
+ * @param text - What was typed.
+ * @param integer - Whether only a whole number is an answer.
+ * @default integer false
+ * @returns The number, or undefined when the text is not one.
+ */
+export function readAnswerNumber(
+  text: string,
+  integer = false,
+): number | undefined {
+  const cleaned = text
+    .trim()
+    .replaceAll(/[−–]/gu, '-')
+    .replace(/\s*%$/u, '')
+    .replaceAll(/\s/gu, '');
+  return readNumber(cleaned, integer);
+}
+
+/**
+ * Write a signed whole number the way an oxidation state or a charge is
+ * written: `+5`, `−2`, `0`.
+ * @param value - The number.
+ * @returns The number with its sign, and a true minus sign.
+ */
+export function formatSigned(value: number): string {
+  if (value > 0) return `+${value}`;
+  if (value < 0) return `−${-value}`;
+  return '0';
+}
+
+/**
+ * The verdict on a field left empty.
+ * @param label - The field, as its box labels it.
+ * @param what - What the box asks for, e.g. `a number of electrons`.
+ * @param language - The language the reason is written in.
+ * @default language 'en'
+ * @returns A failed case that says what to type.
+ */
+export function emptyCase(
+  label: string,
+  what: string,
+  language: Language = DEFAULT_LANGUAGE,
+): FieldCase {
+  const t = catalogTranslate(CHROME_CATALOG, language);
+  return {
+    label,
+    passed: false,
+    reason: t('pedagogy.answerEmpty', { what }),
+    actual: null,
+  };
+}
+
+/**
+ * The verdict on a field that does not read as the kind of value it asks for.
+ * @param label - The field, as its box labels it.
+ * @param typed - What was typed.
+ * @param what - What the box asks for, e.g. `a whole number`.
+ * @param language - The language the reason is written in.
+ * @default language 'en'
+ * @returns A failed case quoting what was typed.
+ */
+export function unreadableCase(
+  label: string,
+  typed: string,
+  what: string,
+  language: Language = DEFAULT_LANGUAGE,
+): FieldCase {
+  const t = catalogTranslate(CHROME_CATALOG, language);
+  return {
+    label,
+    passed: false,
+    reason: t('pedagogy.answerUnreadable', { typed: typed.trim(), what }),
+    actual: typed,
+  };
+}