react-cheminfo 0.50.0 → 0.52.0

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

package/src/host/core/protocol.ts

@@ -0,0 +1,197 @@
+/**
+ * The cheminfo host protocol, version 1: what a page that frames a tool — an
+ * electronic lab notebook, a course — and the tool say to each other.
+ *
+ * Two messages travel between the windows — `hello`, from the tool, and
+ * `connect`, the host's answer carrying a private `MessagePort` — and everything
+ * else goes through that port: the host's requests (`load`, `get`) and the
+ * tool's `result` for each. This module only spells the messages, and reads
+ * what arrives as the untrusted input it is.
+ */
+
+/** The version a tool speaks; a `connect` naming another is ignored. */
+export const PROTOCOL_VERSION = 1;
+
+/** Posted to the parent frame or the opener at start-up: who the tool is. */
+export const HELLO_TYPE = 'cheminfo:hello';
+
+/** The host's answer to `hello`, carrying the port the rest goes through. */
+export const CONNECT_TYPE = 'cheminfo:connect';
+
+/** How many items one request may carry; the rest are dropped. */
+export const MAX_ITEMS = 64;
+
+/** How long a label may be, in characters; a longer one is cut. */
+export const MAX_LABEL_LENGTH = 80;
+
+/** One typed value crossing the frame boundary. */
+export interface HostItem {
+  /** A kind name, e.g. `'chem.molfile.2d'`. */
+  kind: string;
+  /** Checked against the kind before anything reads it. */
+  value: unknown;
+  /**
+   * The host's name for it, opaque here, e.g. an attachment.
+   * @default undefined
+   */
+  id?: string;
+  /**
+   * The tool input it is meant for.
+   * @default undefined — any input that accepts its kind
+   */
+  key?: string;
+  /**
+   * What a notice calls it, e.g. `'Ethylbenzene'`.
+   * @default undefined
+   */
+  label?: string;
+}
+
+/** One value the tool takes. */
+export interface ToolInput {
+  key: string;
+  /** Kinds in order of preference; a category accepts every kind under it. */
+  kinds: readonly string[];
+}
+
+/** One value the tool can hand back. */
+export interface ToolOutput {
+  key: string;
+  kind: string;
+}
+
+/** What the tool is and takes, as `hello` announces it. */
+export interface ToolInterface {
+  name: string;
+  inputs: readonly ToolInput[];
+  outputs: readonly ToolOutput[];
+}
+
+/** What `hello` carries: public, readable by any origin. */
+export interface HelloMessage {
+  type: typeof HELLO_TYPE;
+  version: typeof PROTOCOL_VERSION;
+  tool: ToolInterface & {
+    /** The tool's origin, e.g. `'https://3d.cheminfo.org'`. */
+    origin: string;
+    /** The build that is running, as the About states it, or `null`. */
+    build: unknown;
+  };
+}
+
+/** `load`: the host's data, for one document. */
+export interface LoadRequest {
+  type: 'load';
+  id: string;
+  /** What the data belongs to; the same document twice is applied once. */
+  document: string;
+  items: HostItem[];
+}
+
+/** `get`: the current value of some outputs. */
+export interface GetRequest {
+  type: 'get';
+  id: string;
+  keys: string[];
+}
+
+/** A request the host sends through the port. */
+export type HostRequest = LoadRequest | GetRequest;
+
+/** Why a request could not be served. */
+export type HostErrorCode = 'invalid' | 'unreadable' | 'no-input' | 'no-output';
+
+/** What a failed request is answered with. */
+export interface HostError {
+  code: HostErrorCode;
+  /** One sentence, in English. */
+  message: string;
+  /**
+   * What the schema found, as `'chem.ocl.id /idCode: must be string'`.
+   * @default undefined
+   */
+  errors?: string[];
+}
+
+/** Which item an input took. */
+export interface UsedItem {
+  key: string;
+  kind: string;
+}
+
+/** The answer to one request, carrying its `id`. */
+export type ResultMessage =
+  | { type: 'result'; id: string; ok: true; used: UsedItem[] }
+  | { type: 'result'; id: string; ok: false; error: HostError };
+
+/**
+ * Read a message that arrived through the port.
+ *
+ * Anything that is not a well-formed `load` or `get` is `null`, and goes
+ * unanswered: an unknown request is a newer host talking, not an error. An item
+ * without a string `kind` is dropped, and a label is cut to
+ * {@link MAX_LABEL_LENGTH}.
+ * @param data - What the port delivered.
+ * @returns The request, or `null`.
+ */
+export function parseRequest(data: unknown): HostRequest | null {
+  if (!isRecord(data) || typeof data.id !== 'string') return null;
+  if (data.type === 'load') {
+    if (typeof data.document !== 'string' || !Array.isArray(data.items)) {
+      return null;
+    }
+    return {
+      type: 'load',
+      id: data.id,
+      document: data.document,
+      items: readItems(data.items),
+    };
+  }
+  if (data.type === 'get') {
+    return { type: 'get', id: data.id, keys: readStrings(data.keys) };
+  }
+  return null;
+}
+
+/**
+ * Whether a window message is the host's answer to `hello`, in this version.
+ * @param data - What the window delivered.
+ * @returns `true` for a `connect` of {@link PROTOCOL_VERSION}.
+ */
+export function isConnect(data: unknown): boolean {
+  return (
+    isRecord(data) &&
+    data.type === CONNECT_TYPE &&
+    data.version === PROTOCOL_VERSION
+  );
+}
+
+function readItems(values: readonly unknown[]): HostItem[] {
+  const items: HostItem[] = [];
+  const count = Math.min(values.length, MAX_ITEMS);
+  for (let index = 0; index < count; index++) {
+    const value = values[index];
+    if (!isRecord(value) || typeof value.kind !== 'string') continue;
+    const item: HostItem = { kind: value.kind, value: value.value };
+    if (typeof value.id === 'string') item.id = value.id;
+    if (typeof value.key === 'string') item.key = value.key;
+    if (typeof value.label === 'string') {
+      item.label = value.label.slice(0, MAX_LABEL_LENGTH);
+    }
+    items.push(item);
+  }
+  return items;
+}
+
+function readStrings(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const strings: string[] = [];
+  for (const entry of value) {
+    if (typeof entry === 'string') strings.push(entry);
+  }
+  return strings;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/host/testing/sciPeaks.ts

@@ -0,0 +1,66 @@
+/**
+ * What SciPeaks sends a tool, byte for byte: the `load` its tool tab —
+ * visualizer-helper's `eln/toolTab` — writes for the ethylbenzene sample its own
+ * tests read (`eln/__tests__/data/sample.json`). Both repositories pin this
+ * message, so a change on either side that the other does not expect fails a
+ * test rather than a notebook.
+ *
+ * The sample is a real one, and so are its quirks: its molfile is V2000 with
+ * every atom at the origin, its title is blank so the label is its first name,
+ * and its formula travels as a kind no structure input reads.
+ */
+
+import type { LoadRequest } from '../core/protocol.ts';
+
+/** How SciPeaks' tool tab introduces itself in `connect`. */
+export const SCIPEAKS_HOST_NAME = 'SciPeaks';
+
+/** The molfile SciPeaks stores for ethylbenzene: every atom at the origin. */
+export const SCIPEAKS_ETHYLBENZENE_MOLFILE = [
+  '',
+  'Actelion Java MolfileCreator 1.0',
+  '',
+  '  8  8  0  0  0  0  0  0  0  0999 V2000',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0',
+  '  1  2  1  0  0  0  0',
+  '  1  3  1  0  0  0  0',
+  '  2  4  2  0  0  0  0',
+  '  2  5  1  0  0  0  0',
+  '  4  6  1  0  0  0  0',
+  '  5  7  2  0  0  0  0',
+  '  6  8  2  0  0  0  0',
+  '  7  8  1  0  0  0  0',
+  'M  END',
+  '',
+].join('\n');
+
+/** The first `load` the tool tab sends for that sample, with `accept`. */
+export const SCIPEAKS_ETHYLBENZENE_LOAD: LoadRequest & { accept: string[] } = {
+  type: 'load',
+  id: 'load-1',
+  document: 'eln:1315a6d895f431497538cb6d834feab5',
+  items: [
+    {
+      kind: 'chem.molfile.2d',
+      value: { molfile: SCIPEAKS_ETHYLBENZENE_MOLFILE },
+      label: 'Ethylbenzene',
+    },
+    {
+      kind: 'chem.ocl.id',
+      value: {
+        idCode: 'daD@@DjUZxHH@@',
+        coordinates: String.raw`!BbOvw?_x@?g?~_{\Bm?t`,
+      },
+      label: 'Ethylbenzene',
+    },
+    { kind: 'chem.mf', value: { mf: 'C8H10' } },
+  ],
+  accept: [],
+};

package/src/host/testing/standInHost.ts

@@ -0,0 +1,116 @@
+/**
+ * A whole host, for a tool's end-to-end tests: a page on another origin that
+ * frames the tool, answers its `hello` with a private port, sends it requests,
+ * and records what comes back.
+ *
+ * It is written the way an electronic lab notebook would write one: it checks
+ * that `hello` came from its frame and from the tool's origin, and connects
+ * only then. A real server serves it on `127.0.0.1` while the tool runs on
+ * `localhost`, so every message crosses a real origin boundary — and it has to
+ * be a real server: Chrome takes a page that Playwright answers itself for a
+ * public one, and a public page may not frame a local site.
+ */
+
+import type { Server } from 'node:http';
+import { createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+import type { HelloMessage } from '../core/protocol.ts';
+
+/** A running stand-in host. */
+export interface StandInHost {
+  /** Where the host page is served, e.g. `http://127.0.0.1:53211`. */
+  origin: string;
+  /**
+   * The address of a host page that frames `toolUrl` in `#tool` and, once the
+   * tool has said `hello`, sends `requests` through the port it hands over.
+   * @param toolUrl - The tool's address, `?embed=1` included.
+   * @param requests - What to send on the port, in order.
+   * @returns The address to open.
+   */
+  pageUrl: (toolUrl: string, requests: readonly unknown[]) => string;
+  /** Stop serving. */
+  close: () => Promise<void>;
+}
+
+/** What the host page recorded, read with {@link readStandInHostLog}. */
+export interface StandInHostLog {
+  /** The tool's `hello`, or `null` before it came. */
+  hello: HelloMessage | null;
+  /** Every message the tool sent on the port, in order. */
+  results: unknown[];
+}
+
+/**
+ * Serve the host page on a free port of `127.0.0.1`.
+ * @returns The host; close it when the tests are done.
+ */
+export async function startStandInHost(): Promise<StandInHost> {
+  const server: Server = createServer((_request, response) => {
+    response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+    response.end(HOST_PAGE);
+  });
+  await new Promise<void>((resolve) => {
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const { port } = server.address() as AddressInfo;
+  const origin = `http://127.0.0.1:${port}`;
+
+  return {
+    origin,
+    pageUrl: (toolUrl, requests) => {
+      const setup = encodeURIComponent(JSON.stringify({ toolUrl, requests }));
+      return `${origin}/?setup=${setup}`;
+    },
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      }),
+  };
+}
+
+/**
+ * Read what the host page recorded. Runs in the page: hand it to Playwright's
+ * `page.evaluate`, as `page.evaluate(readStandInHostLog)`.
+ * @returns The log.
+ */
+export function readStandInHostLog(): StandInHostLog {
+  return (globalThis as unknown as { hostLog: StandInHostLog }).hostLog;
+}
+
+/**
+ * The page. Its setup is its own `?setup=`, so one page serves every test, and
+ * it listens before it frames, so the tool's `hello` cannot be missed.
+ */
+const HOST_PAGE = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Stand-in host</title></head>
+<body>
+<iframe id="tool" title="The framed tool" style="width: 1280px; height: 800px"></iframe>
+<script>
+const { toolUrl, requests } = JSON.parse(new URLSearchParams(location.search).get('setup'));
+const toolOrigin = new URL(toolUrl).origin;
+const frame = document.querySelector('#tool');
+globalThis.hostLog = { hello: null, results: [] };
+globalThis.addEventListener('message', (event) => {
+  if (event.source !== frame.contentWindow || event.origin !== toolOrigin) return;
+  if (event.data?.type !== 'cheminfo:hello') return;
+  globalThis.hostLog.hello = event.data;
+  const channel = new MessageChannel();
+  channel.port1.onmessage = (answer) => {
+    globalThis.hostLog.results.push(answer.data);
+  };
+  frame.contentWindow.postMessage(
+    { type: 'cheminfo:connect', version: 1, host: { name: 'Stand-in host' } },
+    toolOrigin,
+    [channel.port2],
+  );
+  for (const request of requests) channel.port1.postMessage(request);
+});
+frame.src = toolUrl;
+</script>
+</body>
+</html>`;

package/src/host/ui/index.ts

@@ -0,0 +1,2 @@
+export type { HostHandlers } from './useHostConnection.ts';
+export { useHostConnection } from './useHostConnection.ts';

package/src/host/ui/useHostConnection.ts

@@ -0,0 +1,85 @@
+/**
+ * Connect a tool to the page that frames it, when there is one.
+ *
+ * The protocol and its schemas are fetched only then, so a visitor on the site
+ * itself never downloads them.
+ */
+
+import { useEffect, useRef } from 'react';
+
+import type { LoadedInput } from '../core/connectHost.ts';
+import type { ToolInterface } from '../core/protocol.ts';
+
+/** What a tool does with what its host sends, and what it says about itself. */
+export interface HostHandlers {
+  /**
+   * Show the inputs of a new document. Throwing means they could not be read:
+   * the error's message goes back to the host, and nothing should have changed
+   * on screen.
+   */
+  load: (inputs: readonly LoadedInput[]) => void;
+  /**
+   * The build that is running — `BUILD_INFO` from `react-cheminfo/build-info`
+   * — so a host can record which version produced what it stores.
+   * @default null
+   */
+  build?: unknown;
+}
+
+/** Once per page: React may mount the caller twice, the host is greeted once. */
+let started = false;
+
+/**
+ * Introduce the tool to its parent frame, or to the window that opened it, and
+ * serve that host for the life of the page.
+ *
+ * Call it after the hook that applies the address: effects run in order, so
+ * the address has been applied by the time the host is greeted, and a host's
+ * structure replaces the one the frame's link named rather than the reverse.
+ * The latest `load` is always the one called, so it may close over state.
+ * @param tool - What the tool takes and gives.
+ * @param handlers - See {@link HostHandlers}.
+ */
+export function useHostConnection(
+  tool: ToolInterface,
+  handlers: HostHandlers,
+): void {
+  const latest = useRef(handlers);
+  useEffect(() => {
+    latest.current = handlers;
+  });
+
+  useEffect(() => {
+    if (started) return;
+    const host = hostWindow();
+    if (host === null) return;
+    started = true;
+    import('../core/connectHost.ts')
+      .then(({ connectHost }) => {
+        connectHost({
+          host,
+          listen: (listener) => {
+            globalThis.addEventListener('message', listener);
+            return () => {
+              globalThis.removeEventListener('message', listener);
+            };
+          },
+          tool,
+          origin: globalThis.location.origin,
+          build: latest.current.build ?? null,
+          load: (inputs) => {
+            latest.current.load(inputs);
+          },
+        });
+      })
+      .catch(() => {
+        started = false;
+      });
+  }, [tool]);
+}
+
+function hostWindow(): Window | null {
+  const { parent, opener } = globalThis.window;
+  if (parent !== globalThis.window) return parent;
+  return (opener as Window | null) ?? null;
+}

package/src/host-testing.ts

@@ -0,0 +1,18 @@
+/**
+ * A stand-in host for a tool's end-to-end tests, and the messages SciPeaks
+ * sends. Node only: it serves a page.
+ */
+
+export type {
+  StandInHost,
+  StandInHostLog,
+} from './host/testing/standInHost.ts';
+export {
+  readStandInHostLog,
+  startStandInHost,
+} from './host/testing/standInHost.ts';
+export {
+  SCIPEAKS_ETHYLBENZENE_LOAD,
+  SCIPEAKS_ETHYLBENZENE_MOLFILE,
+  SCIPEAKS_HOST_NAME,
+} from './host/testing/sciPeaks.ts';

package/src/host.ts

@@ -0,0 +1,11 @@
+/**
+ * The host protocol: a page that frames a tool — an electronic lab notebook, a
+ * course — hands it typed data, checked against pipeline.cheminfo.org's kinds.
+ *
+ * Its own door because the schemas are checked with ajv. `useHostConnection`
+ * fetches ajv and the connection only when the page is framed, so a site that
+ * calls it ships nothing extra to a visitor who opened it directly.
+ */
+
+export * from './host/core/index.ts';
+export * from './host/ui/index.ts';