react-cheminfo 0.51.0 → 0.53.0

package/src/host/core/connectHost.ts

@@ -0,0 +1,240 @@
+/**
+ * A tool's side of the host protocol: introduce itself to the page that
+ * frames it, take the private port that page answers with, and serve what
+ * arrives through it.
+ *
+ * Free of React and of the DOM — the window is handed in — so a test drives the
+ * whole exchange with a fake host and a real `MessageChannel`.
+ */
+
+import type { CheckedValue, KnownKind } from './kinds.ts';
+import { checkValue, isKnownKind, kindAccepts } from './kinds.ts';
+import type {
+  GetRequest,
+  HelloMessage,
+  HostError,
+  HostItem,
+  LoadRequest,
+  ResultMessage,
+  ToolInput,
+  ToolInterface,
+  UsedItem,
+} from './protocol.ts';
+import {
+  HELLO_TYPE,
+  PROTOCOL_VERSION,
+  isConnect,
+  parseRequest,
+} from './protocol.ts';
+
+/** The item an input took, and its value as the input's kind reads it. */
+export interface LoadedInput {
+  key: string;
+  item: HostItem;
+  checked: CheckedValue;
+}
+
+/** What a window `message` event carries, as far as the protocol reads it. */
+export interface HostMessageEvent {
+  data: unknown;
+  source: unknown;
+  ports: readonly MessagePort[];
+}
+
+/** Where the connection runs, and what it serves. */
+export interface HostConnectionOptions {
+  /** The page to introduce the tool to: the parent frame, or the opener. */
+  host: { postMessage: (message: unknown, targetOrigin: string) => void };
+  /** Subscribe to this window's messages; the returned function unsubscribes. */
+  listen: (listener: (event: HostMessageEvent) => void) => () => void;
+  /** What the tool takes and gives, as `hello` announces it. */
+  tool: ToolInterface;
+  /** The tool's origin, as `hello` states it. */
+  origin: string;
+  /** The build that is running, as the About states it, or `null`. */
+  build: unknown;
+  /**
+   * Show the inputs of a new document. Throwing means they could not be read:
+   * the error's message goes back to the host, and the document is not marked
+   * as applied.
+   */
+  load: (inputs: readonly LoadedInput[]) => void;
+}
+
+/** What choosing the items of a request gave. */
+export type InputSelection =
+  { ok: true; inputs: LoadedInput[] } | { ok: false; error: HostError };
+
+/**
+ * Say `hello` to the host, and serve its requests once it connects.
+ *
+ * A `connect` is accepted only from the window `hello` went to, and a second
+ * one replaces the first — a host that reloads its own script connects again.
+ * A document is applied once: the same one again is answered as before and
+ * changes nothing, so a host re-sending it never overwrites the user's work.
+ * @param options - The window, the tool, and its load function.
+ * @returns The function that stops listening and closes the port.
+ */
+export function connectHost(options: HostConnectionOptions): () => void {
+  const { host, listen, tool, origin, build, load } = options;
+  let port: MessagePort | null = null;
+  let appliedDocument: string | null = null;
+  let appliedUsed: UsedItem[] = [];
+
+  function serve(data: unknown): void {
+    const request = parseRequest(data);
+    if (request === null) return;
+    const result =
+      request.type === 'load' ? applyLoad(request) : answerGet(request, tool);
+    port?.postMessage(result);
+  }
+
+  function applyLoad(request: LoadRequest): ResultMessage {
+    const { id, document, items } = request;
+    if (document === appliedDocument) {
+      return { type: 'result', id, ok: true, used: appliedUsed };
+    }
+    const selection = selectInputs(tool, items);
+    if (!selection.ok) {
+      return { type: 'result', id, ok: false, error: selection.error };
+    }
+    try {
+      load(selection.inputs);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        type: 'result',
+        id,
+        ok: false,
+        error: { code: 'unreadable', message },
+      };
+    }
+    appliedDocument = document;
+    appliedUsed = selection.inputs.map(({ key, item }) => ({
+      key,
+      kind: item.kind,
+    }));
+    return { type: 'result', id, ok: true, used: appliedUsed };
+  }
+
+  const stopListening = listen((event) => {
+    if (event.source !== host || !isConnect(event.data)) return;
+    const received = event.ports[0];
+    if (received === undefined) return;
+    port?.close();
+    port = received;
+    port.addEventListener('message', (message) => {
+      serve(message.data);
+    });
+    port.start();
+  });
+
+  const hello: HelloMessage = {
+    type: HELLO_TYPE,
+    version: PROTOCOL_VERSION,
+    tool: {
+      name: tool.name,
+      origin,
+      build,
+      inputs: tool.inputs,
+      outputs: tool.outputs,
+    },
+  };
+  // `hello` says nothing a stranger may not read, and the parent's origin is
+  // not knowable until it answers.
+  host.postMessage(hello, '*');
+
+  return () => {
+    stopListening();
+    port?.close();
+    port = null;
+  };
+}
+
+/**
+ * Give each input of the tool one item of a request.
+ *
+ * Each input tries its kinds in its own order of preference, and takes the
+ * first item that falls under one and passes that kind's schema: the tool
+ * knows which notation serves it best, whatever order the host listed them in.
+ * An item naming another input's `key` is left to that input.
+ * @param tool - What the tool takes.
+ * @param items - What the host sent.
+ * @returns One item per input, or why an input got none.
+ */
+export function selectInputs(
+  tool: ToolInterface,
+  items: readonly HostItem[],
+): InputSelection {
+  const inputs: LoadedInput[] = [];
+  for (const input of tool.inputs) {
+    const errors: string[] = [];
+    const loaded = selectInput(input, items, errors);
+    if (loaded !== null) {
+      inputs.push(loaded);
+      continue;
+    }
+    if (errors.length > 0) {
+      return {
+        ok: false,
+        error: {
+          code: 'invalid',
+          message: `No item for ${input.key} has the shape its kind requires, so ${tool.name} loaded nothing.`,
+          errors,
+        },
+      };
+    }
+    return {
+      ok: false,
+      error: {
+        code: 'no-input',
+        message: `No item is a ${KIND_LIST.format(input.kinds)}, so ${tool.name} loaded nothing.`,
+      },
+    };
+  }
+  return { ok: true, inputs };
+}
+
+function selectInput(
+  input: ToolInput,
+  items: readonly HostItem[],
+  errors: string[],
+): LoadedInput | null {
+  for (const accepted of input.kinds) {
+    if (!isKnownKind(accepted)) continue;
+    for (const item of items) {
+      if (item.key !== undefined && item.key !== input.key) continue;
+      if (!kindAccepts(accepted, item.kind)) continue;
+      const loaded = checkItem(input.key, accepted, item, errors);
+      if (loaded !== null) return loaded;
+    }
+  }
+  return null;
+}
+
+function checkItem(
+  key: string,
+  accepted: KnownKind,
+  item: HostItem,
+  errors: string[],
+): LoadedInput | null {
+  const outcome = checkValue(accepted, item.value);
+  if (outcome.valid) return { key, item, checked: outcome.checked };
+  for (const error of outcome.errors) errors.push(`${item.kind} ${error}`);
+  return null;
+}
+
+function answerGet(request: GetRequest, tool: ToolInterface): ResultMessage {
+  // Nothing goes back yet: no tool declares an output.
+  return {
+    type: 'result',
+    id: request.id,
+    ok: false,
+    error: {
+      code: 'no-output',
+      message: `${tool.name} has nothing to give back yet.`,
+    },
+  };
+}
+
+const KIND_LIST = new Intl.ListFormat('en', { type: 'disjunction' });

package/src/host/core/hostStructure.ts

@@ -0,0 +1,129 @@
+/**
+ * A structure a host handed over, read into the molecule a tool works on.
+ *
+ * Every tool of the family that takes a structure takes it the same way — in
+ * the three notations a notebook keeps, the one that says the most first — so
+ * the kinds, the parsing and the sentence a host reads when it fails are
+ * written once, here.
+ */
+
+import type { Molecule } from 'openchemlib';
+
+import { sourceMolecule } from '../../structure/core/sourceMolecule.ts';
+import { structureError } from '../../structure/core/structureError.ts';
+import type { StructureSource } from '../../structure/core/structureSource.ts';
+
+import type { LoadedInput } from './connectHost.ts';
+import type { CheckedValue } from './kinds.ts';
+
+/**
+ * The kinds a structure input accepts, in order of preference: a molfile
+ * carries the layout its author drew, an idcode the exact structure, a SMILES
+ * only the connectivity.
+ */
+export const STRUCTURE_KINDS = [
+  'chem.molfile',
+  'chem.ocl.id',
+  'chem.smiles',
+] as const;
+
+/** A checked value holding a structure. */
+export type StructureValue = Extract<
+  CheckedValue,
+  { kind: (typeof STRUCTURE_KINDS)[number] }
+>;
+
+/**
+ * The function a tool hands `useHostConnection` as `load` when its input is a
+ * structure.
+ *
+ * The structure is parsed before `show` is called, so one that cannot be read
+ * is answered `unreadable` with a sentence the host can show, and nothing on
+ * the tool's screen changes.
+ * @param show - Puts the molecule on screen, under the host's label for it.
+ * @param key - The input the structure arrives on.
+ * @returns The `load` function.
+ */
+export function hostStructureLoader(
+  show: (molecule: Molecule, label: string | undefined) => void,
+  key = 'structure',
+): (inputs: readonly LoadedInput[]) => void {
+  return (inputs) => {
+    for (const { key: inputKey, item, checked } of inputs) {
+      if (inputKey !== key || !isStructureValue(checked)) continue;
+      show(readHostMolecule(checked), item.label);
+    }
+  };
+}
+
+/**
+ * Read a structure a host sent.
+ *
+ * A molfile whose atoms all sit on one point — SciPeaks stores some that way —
+ * is laid out again, so a tool that draws it does not draw one dot.
+ * @param checked - The value, already checked against its kind.
+ * @returns A molecule with at least one atom.
+ * @throws {Error} When the notation does not parse or describes no atoms; the
+ * message is the sentence the host is answered with.
+ */
+export function readHostMolecule(checked: StructureValue): Molecule {
+  const notation = NOTATIONS[checked.kind];
+  let molecule: Molecule;
+  try {
+    molecule = sourceMolecule(hostStructureSource(checked));
+  } catch (error) {
+    const { message } = structureError(error);
+    throw new Error(
+      `The ${notation} could not be read, so nothing was loaded: ${message}`,
+      { cause: error },
+    );
+  }
+  if (molecule.getAllAtoms() === 0) {
+    throw new Error(
+      `The ${notation} describes no atoms, so nothing was loaded.`,
+    );
+  }
+  if (atomsCoincide(molecule)) molecule.inventCoordinates();
+  return molecule;
+}
+
+/**
+ * A structure a host sent, as the notation a depiction is drawn from.
+ * @param checked - The value, already checked against its kind.
+ * @returns The notation and its text; an idcode keeps its coordinates.
+ */
+export function hostStructureSource(checked: StructureValue): StructureSource {
+  if (checked.kind === 'chem.molfile') {
+    return { kind: 'molfile', value: checked.value.molfile };
+  }
+  if (checked.kind === 'chem.ocl.id') {
+    const { idCode, coordinates } = checked.value;
+    return coordinates === ''
+      ? { kind: 'idcode', value: idCode }
+      : { kind: 'idcode', value: idCode, coordinates };
+  }
+  return { kind: 'smiles', value: checked.value.smiles.trim() };
+}
+
+const NOTATIONS: Record<StructureValue['kind'], string> = {
+  'chem.molfile': 'molfile',
+  'chem.ocl.id': 'idcode',
+  'chem.smiles': 'SMILES',
+};
+
+function atomsCoincide(molecule: Molecule): boolean {
+  const atoms = molecule.getAllAtoms();
+  if (atoms < 2) return false;
+  const x = molecule.getAtomX(0);
+  const y = molecule.getAtomY(0);
+  for (let atom = 1; atom < atoms; atom++) {
+    if (molecule.getAtomX(atom) !== x || molecule.getAtomY(atom) !== y) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function isStructureValue(checked: CheckedValue): checked is StructureValue {
+  return Object.hasOwn(NOTATIONS, checked.kind);
+}

package/src/host/core/index.ts

@@ -0,0 +1,46 @@
+export type {
+  HostConnectionOptions,
+  HostMessageEvent,
+  InputSelection,
+  LoadedInput,
+} from './connectHost.ts';
+export { connectHost, selectInputs } from './connectHost.ts';
+export type { StructureValue } from './hostStructure.ts';
+export {
+  STRUCTURE_KINDS,
+  hostStructureLoader,
+  hostStructureSource,
+  readHostMolecule,
+} from './hostStructure.ts';
+export type {
+  CheckOutcome,
+  CheckedValue,
+  KnownKind,
+  MolfileValue,
+  OclIdValue,
+  SmilesValue,
+} from './kinds.ts';
+export { checkValue, isKnownKind, kindAccepts } from './kinds.ts';
+export type {
+  GetRequest,
+  HelloMessage,
+  HostError,
+  HostErrorCode,
+  HostItem,
+  HostRequest,
+  LoadRequest,
+  ResultMessage,
+  ToolInput,
+  ToolInterface,
+  ToolOutput,
+  UsedItem,
+} from './protocol.ts';
+export {
+  CONNECT_TYPE,
+  HELLO_TYPE,
+  MAX_ITEMS,
+  MAX_LABEL_LENGTH,
+  PROTOCOL_VERSION,
+  isConnect,
+  parseRequest,
+} from './protocol.ts';

package/src/host/core/kinds.ts

@@ -0,0 +1,128 @@
+/**
+ * The kinds of data a tool takes from a host, checked the way
+ * pipeline.cheminfo.org checks what its workers pass to each other: a dotted
+ * name, a JSON Schema, and ajv.
+ *
+ * The names are pipeline's (`chem.molfile.2d`, `chem.ocl.id`…), plus
+ * `chem.smiles`, which pipeline lists among its future schemas. A name with
+ * children is a category whose schema every child satisfies, so `chem.molfile`
+ * reads `chem.molfile.2d` and `chem.molfile.3d.h.energy` alike; the fields a
+ * tool does not read are stripped rather than refused, so a host sending more
+ * than it needs to is never turned away.
+ */
+
+import type { JSONSchemaType, ValidateFunction } from 'ajv';
+import { Ajv } from 'ajv';
+
+/** A molfile, V2000 or V3000. */
+export interface MolfileValue {
+  molfile: string;
+}
+
+/** An OpenChemLib idcode and its 2D coordinates. */
+export interface OclIdValue {
+  idCode: string;
+  coordinates: string;
+}
+
+/** A SMILES. */
+export interface SmilesValue {
+  smiles: string;
+}
+
+/** A value that passed its kind's schema, tagged with that kind. */
+export type CheckedValue =
+  | { kind: 'chem.molfile'; value: MolfileValue }
+  | { kind: 'chem.ocl.id'; value: OclIdValue }
+  | { kind: 'chem.smiles'; value: SmilesValue };
+
+/** The name of a kind a tool can read. */
+export type KnownKind = CheckedValue['kind'];
+
+/** The value a kind a tool can read carries. */
+type ValueOf<K extends KnownKind> = Extract<CheckedValue, { kind: K }>['value'];
+
+/** What checking a value gave. */
+export type CheckOutcome =
+  { valid: true; checked: CheckedValue } | { valid: false; errors: string[] };
+
+/**
+ * Whether a kind falls under another: the same name, or a name under it on a
+ * segment boundary. A list (`…[]`) never stands for one value, nor one value
+ * for a list.
+ * @param accepted - The kind a tool declares, e.g. `'chem.molfile'`.
+ * @param offered - The kind an item carries, e.g. `'chem.molfile.2d'`.
+ * @returns `true` when an item of `offered` can be read as `accepted`.
+ */
+export function kindAccepts(accepted: string, offered: string): boolean {
+  const list = accepted.endsWith('[]');
+  if (offered.endsWith('[]') !== list) return false;
+  const base = list ? accepted.slice(0, -2) : accepted;
+  const name = list ? offered.slice(0, -2) : offered;
+  return name === base || name.startsWith(`${base}.`);
+}
+
+/**
+ * Whether there is a schema for a kind.
+ * @param kind - A kind name.
+ * @returns `true` for a {@link KnownKind}.
+ */
+export function isKnownKind(kind: string): kind is KnownKind {
+  return Object.hasOwn(VALIDATORS, kind);
+}
+
+/**
+ * Check a value against a kind's schema.
+ *
+ * Fields the schema does not name are removed from `value` itself, so what the
+ * site reads afterwards is exactly what the kind promises.
+ * @param kind - The kind to read the value as.
+ * @param value - The value, as received.
+ * @returns The value tagged with its kind, or the errors as pipeline writes
+ * them, `'/idCode: must be string'`.
+ */
+export function checkValue(kind: KnownKind, value: unknown): CheckOutcome {
+  const validate: ValidateFunction = VALIDATORS[kind];
+  if (validate(value)) {
+    // The validator of `kind` just vouched for the shape of `value`.
+    return { valid: true, checked: { kind, value } as CheckedValue };
+  }
+  const errors: string[] = [];
+  for (const error of validate.errors ?? []) {
+    errors.push(`${error.instancePath || '/'}: ${error.message ?? 'invalid'}`);
+  }
+  return { valid: false, errors };
+}
+
+const MOLFILE_SCHEMA: JSONSchemaType<MolfileValue> = {
+  type: 'object',
+  properties: { molfile: { type: 'string' } },
+  required: ['molfile'],
+  additionalProperties: false,
+};
+
+const OCL_ID_SCHEMA: JSONSchemaType<OclIdValue> = {
+  type: 'object',
+  properties: {
+    idCode: { type: 'string' },
+    coordinates: { type: 'string' },
+  },
+  required: ['idCode', 'coordinates'],
+  additionalProperties: false,
+};
+
+const SMILES_SCHEMA: JSONSchemaType<SmilesValue> = {
+  type: 'object',
+  properties: { smiles: { type: 'string' } },
+  required: ['smiles'],
+  additionalProperties: false,
+};
+
+// `removeAdditional` strips what `additionalProperties: false` would refuse.
+const ajv = new Ajv({ removeAdditional: true });
+
+const VALIDATORS: { [K in KnownKind]: ValidateFunction<ValueOf<K>> } = {
+  'chem.molfile': ajv.compile(MOLFILE_SCHEMA),
+  'chem.ocl.id': ajv.compile(OCL_ID_SCHEMA),
+  'chem.smiles': ajv.compile(SMILES_SCHEMA),
+};