react-cheminfo 0.64.1 → 0.65.0

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;
+  }
+}

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);
 }
 
 /**