react-cheminfo 0.76.0 → 0.78.0

package/src/host/core/connectTool.ts

@@ -0,0 +1,285 @@
+/**
+ * A host's side of the host protocol: answer the `hello` of the tool in a
+ * frame with a private port, hand it documents, hear the values it sends back,
+ * and ask it for others.
+ *
+ * Free of React and of the DOM — the frame and the window are handed in — so a
+ * test drives the whole exchange against a real tool side and a real
+ * `MessageChannel`.
+ */
+
+import type {
+  HostError,
+  HostItem,
+  OutputMessage,
+  ResultMessage,
+  UsedItem,
+} from './protocol.ts';
+import { CONNECT_TYPE, PROTOCOL_VERSION } from './protocol.ts';
+import type { ToolHello } from './toolMessages.ts';
+import { readHello, readToolMessage } from './toolMessages.ts';
+
+/** A message posted to this window, as far as a host reads it. */
+export interface ToolWindowEvent {
+  data: unknown;
+  source: unknown;
+  origin: string;
+}
+
+/** The window of the frame the tool runs in. */
+export interface ToolFrameWindow {
+  postMessage: (
+    message: unknown,
+    targetOrigin: string,
+    transfer: Transferable[],
+  ) => void;
+}
+
+/** A document handed to a tool: what it shows, and what it sends back unasked. */
+export interface ToolDocument {
+  /** What the data belongs to; the tool applies the same document once. */
+  document: string;
+  /** The values, each with its kind. */
+  items: HostItem[];
+  /**
+   * The outputs the tool sends whenever they change, by key or by kind.
+   * @default undefined — nothing is sent unasked
+   */
+  accept?: string[];
+}
+
+/**
+ * What became of a document: shown, refused with the tool's reason, or never
+ * answered — another document took its place, the connection was closed, or
+ * the tool took too long.
+ */
+export type LoadOutcome =
+  | { status: 'loaded'; used: UsedItem[] }
+  | { status: 'refused'; error: HostError }
+  | { status: 'dropped' };
+
+/** Where the connection runs, and whom it talks to. */
+export interface ToolConnectionOptions {
+  /** The window of the frame, once there is one: `hello` is taken from it alone. */
+  frame: () => ToolFrameWindow | null;
+  /** Where the tool is served from: a message from any other origin is ignored. */
+  origin: string;
+  /** How the host introduces itself in `connect`. */
+  host: { name: string };
+  /** Subscribe to this window's messages; the returned function unsubscribes. */
+  listen: (listener: (event: ToolWindowEvent) => void) => () => void;
+  /**
+   * Told each time the tool says `hello` — once per load of the frame — with
+   * what it takes and gives.
+   * @default undefined
+   */
+  onHello?: (tool: ToolHello) => void;
+  /**
+   * Told of every `output` the tool sends.
+   * @default undefined
+   */
+  onOutput?: (message: OutputMessage) => void;
+  /**
+   * How long a request may go unanswered, in milliseconds.
+   * @default REQUEST_TIMEOUT
+   */
+  timeout?: number;
+}
+
+/** A connection to a framed tool. */
+export interface ToolConnection {
+  /**
+   * Show a document. One handed over before the tool has connected waits for
+   * it, and the latest is handed over again whenever the tool connects anew —
+   * after a reload of its frame.
+   */
+  load: (document: ToolDocument) => Promise<LoadOutcome>;
+  /** The current values of some outputs; rejects with the tool's reason. */
+  get: (keys: readonly string[]) => Promise<HostItem[]>;
+  /** Stop listening and close the port; what is pending is dropped. */
+  close: () => void;
+}
+
+/** How long a request may go unanswered, in milliseconds. */
+export const REQUEST_TIMEOUT = 20_000;
+
+type Abandon = 'timeout' | 'reconnected' | 'closed';
+
+const ABANDONED: Record<Abandon, string> = {
+  timeout: 'The tool did not answer in time.',
+  reconnected: 'The tool was reloaded before it answered.',
+  closed: 'The tool is no longer connected.',
+};
+
+interface Waiting {
+  answer: (message: ResultMessage) => void;
+  abandon: (reason: Abandon) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+interface Shown {
+  document: ToolDocument;
+  /** Who waits for its first answer; `null` once told. */
+  settle: ((outcome: LoadOutcome) => void) | null;
+}
+
+/**
+ * Listen for the framed tool's `hello`, and talk to it once it has said it.
+ *
+ * A `hello` counts only from the frame's window and from the tool's origin —
+ * a frame that navigated elsewhere keeps its window — and `connect` is posted
+ * to that origin alone, so a page the frame later shows never receives the
+ * port, nor anything sent through it.
+ * @param options - The frame, the tool's origin, and what to tell.
+ * @returns The connection.
+ */
+export function connectTool(options: ToolConnectionOptions): ToolConnection {
+  const { frame, origin, host, listen, onHello, onOutput } = options;
+  const { timeout = REQUEST_TIMEOUT } = options;
+  const waiting = new Map<string, Waiting>();
+  let port: MessagePort | null = null;
+  let shown: Shown | null = null;
+  let count = 0;
+  let closed = false;
+
+  function post(
+    body: Record<string, unknown>,
+    handlers: Omit<Waiting, 'timer'>,
+  ): void {
+    if (port === null) return;
+    count += 1;
+    const id = `h${count}`;
+    const timer = setTimeout(() => {
+      waiting.delete(id);
+      handlers.abandon('timeout');
+    }, timeout);
+    waiting.set(id, { ...handlers, timer });
+    port.postMessage({ ...body, id });
+  }
+
+  function abandonAll(reason: Abandon): void {
+    for (const entry of waiting.values()) {
+      clearTimeout(entry.timer);
+      entry.abandon(reason);
+    }
+    waiting.clear();
+  }
+
+  function settle(entry: Shown, outcome: LoadOutcome): void {
+    entry.settle?.(outcome);
+    entry.settle = null;
+  }
+
+  function send(entry: Shown): void {
+    const { document, items, accept } = entry.document;
+    post(
+      {
+        type: 'load',
+        document,
+        items,
+        ...(accept === undefined ? {} : { accept }),
+      },
+      {
+        answer: (message) => {
+          settle(entry, outcomeOf(message));
+        },
+        // Sent again to the reloaded tool, which answers then.
+        abandon: (reason) => {
+          if (reason !== 'reconnected') settle(entry, { status: 'dropped' });
+        },
+      },
+    );
+  }
+
+  function receive(data: unknown): void {
+    const message = readToolMessage(data);
+    if (message === null) return;
+    if (message.type === 'output') {
+      onOutput?.(message);
+      return;
+    }
+    const entry = waiting.get(message.id);
+    if (entry === undefined) return;
+    waiting.delete(message.id);
+    clearTimeout(entry.timer);
+    entry.answer(message);
+  }
+
+  const stopListening = listen((event) => {
+    if (closed || event.origin !== origin) return;
+    const target = frame();
+    if (target === null || event.source !== target) return;
+    const tool = readHello(event.data);
+    if (tool === null) return;
+    abandonAll('reconnected');
+    port?.close();
+    const channel = new MessageChannel();
+    port = channel.port1;
+    port.addEventListener('message', (message) => {
+      receive(message.data);
+    });
+    port.start();
+    target.postMessage(
+      { type: CONNECT_TYPE, version: PROTOCOL_VERSION, host },
+      origin,
+      [channel.port2],
+    );
+    onHello?.(tool);
+    if (shown !== null) send(shown);
+  });
+
+  return {
+    load(document) {
+      return new Promise((resolve) => {
+        if (shown !== null) settle(shown, { status: 'dropped' });
+        const entry: Shown = { document, settle: resolve };
+        shown = entry;
+        if (closed) settle(entry, { status: 'dropped' });
+        else send(entry);
+      });
+    },
+    get(keys) {
+      return new Promise((resolve, reject) => {
+        if (port === null) {
+          reject(
+            new Error(
+              closed
+                ? ABANDONED.closed
+                : 'The tool has not connected yet, so it has nothing to give.',
+            ),
+          );
+          return;
+        }
+        post(
+          { type: 'get', keys: [...keys] },
+          {
+            answer: (message) => {
+              if (!message.ok) {
+                reject(new Error(message.error.message, { cause: message }));
+              } else {
+                resolve('items' in message ? message.items : []);
+              }
+            },
+            abandon: (reason) => {
+              reject(new Error(ABANDONED[reason]));
+            },
+          },
+        );
+      });
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      stopListening();
+      abandonAll('closed');
+      if (shown !== null) settle(shown, { status: 'dropped' });
+      port?.close();
+      port = null;
+    },
+  };
+}
+
+function outcomeOf(message: ResultMessage): LoadOutcome {
+  if (!message.ok) return { status: 'refused', error: message.error };
+  return { status: 'loaded', used: 'used' in message ? message.used : [] };
+}

package/src/host/core/hostOutputs.ts

@@ -6,6 +6,10 @@
  * already has: the values as they stood once its document was applied, then
  * every value sent since. Opening a document therefore never writes it back,
  * and a band picked on one spectrum of a sample leaves the others alone.
+ *
+ * A value that costs something to make — a picture rendered from the scene on
+ * screen — is not read with the others: it is rendered when a `get` names it,
+ * and never sent unasked.
  */
 
 import { kindAccepts } from './kinds.ts';
@@ -27,6 +31,14 @@ export interface HostOutputs {
   read: () => readonly HostItem[];
   /** Be told whenever they may have changed; the returned function stops it. */
   subscribe: (listener: () => void) => () => void;
+  /**
+   * The outputs made only when a host asks for them, by key: a `get` naming one
+   * waits for its value, which is never sent unasked. A function resolving to
+   * `undefined` has nothing to give yet; one that rejects answers the `get`
+   * with its error's message.
+   * @default undefined — every output is read by `read`
+   */
+  render?: Readonly<Record<string, () => Promise<HostItem | undefined>>>;
 }
 
 /**
@@ -37,17 +49,18 @@ export const OUTPUT_DELAY = 300;
 
 /**
  * Answer a `get` with the values it asks for — every output when it names
- * none.
+ * none — rendering those made on request.
  * @param request - The request.
  * @param tool - What the tool hands back.
  * @param outputs - Where the values are read, if anywhere.
- * @returns The values, or `no-output` when the tool has none of those asked.
+ * @returns The values, or `no-output` when the tool has none of those asked,
+ * or one could not be made.
  */
-export function answerGet(
+export async function answerGet(
   request: GetRequest,
   tool: ToolInterface,
   outputs: HostOutputs | undefined,
-): ResultMessage {
+): Promise<ResultMessage> {
   const { id, keys } = request;
   const declared = new Set<string>();
   for (const output of tool.outputs) declared.add(output.key);
@@ -66,11 +79,40 @@ export function answerGet(
   }
   const items: HostItem[] = [];
   for (const item of outputs.read()) {
-    if (item.key !== undefined && wanted.has(item.key)) items.push(item);
+    if (item.key === undefined || !wanted.has(item.key)) continue;
+    if (renderOf(outputs, item.key) === undefined) items.push(item);
+  }
+  const renders: Array<() => Promise<HostItem | undefined>> = [];
+  const renderedKeys: string[] = [];
+  for (const key of wanted) {
+    const render = renderOf(outputs, key);
+    if (render === undefined) continue;
+    renders.push(render);
+    renderedKeys.push(key);
+  }
+  try {
+    const made = await Promise.all(renders.map((render) => render()));
+    for (let index = 0; index < made.length; index++) {
+      const item = made[index];
+      const key = renderedKeys[index];
+      if (item !== undefined && key !== undefined) items.push({ ...item, key });
+    }
+  } catch (error) {
+    return noOutput(id, error instanceof Error ? error.message : String(error));
   }
   return { type: 'result', id, ok: true, items };
 }
 
+function renderOf(
+  outputs: HostOutputs,
+  key: string,
+): (() => Promise<HostItem | undefined>) | undefined {
+  const { render } = outputs;
+  return render !== undefined && Object.hasOwn(render, key)
+    ? render[key]
+    : undefined;
+}
+
 /** What the connection tells the publisher, and the means to stop it. */
 export interface OutputPublisher {
   /** A document was applied: what the host has is what the tool now shows. */

package/src/host/core/index.ts

@@ -1,5 +1,14 @@
 export type { HostConnectionOptions, HostMessageEvent } from './connectHost.ts';
 export { connectHost } from './connectHost.ts';
+export type {
+  LoadOutcome,
+  ToolConnection,
+  ToolConnectionOptions,
+  ToolDocument,
+  ToolFrameWindow,
+  ToolWindowEvent,
+} from './connectTool.ts';
+export { REQUEST_TIMEOUT, connectTool } from './connectTool.ts';
 export type { HostOutputs, OutputPublisher } from './hostOutputs.ts';
 export {
   OUTPUT_DELAY,
@@ -17,13 +26,14 @@ export type { IrJdxValue, IrPeakValue, IrPeaksValue } from './irKinds.ts';
 export { IR_JDX_SCHEMA, IR_PEAKS_SCHEMA } from './irKinds.ts';
 export type {
   CheckOutcome,
+  CheckedOf,
   CheckedValue,
   KnownKind,
   MolfileValue,
   OclIdValue,
   SmilesValue,
 } from './kinds.ts';
-export { checkValue, isKnownKind, kindAccepts } from './kinds.ts';
+export { checkValue, isKnownKind, kindAccepts, readOutput } from './kinds.ts';
 export type {
   GetRequest,
   HelloMessage,
@@ -48,5 +58,14 @@ export {
   isConnect,
   parseRequest,
 } from './protocol.ts';
+export type {
+  NameValue,
+  SvgImageValue,
+  TableCell,
+  TableValue,
+} from './resultKinds.ts';
+export { NAME_SCHEMA, SVG_IMAGE_SCHEMA, TABLE_SCHEMA } from './resultKinds.ts';
 export type { InputSelection, LoadedInput } from './selectInputs.ts';
 export { selectInputs } from './selectInputs.ts';
+export type { ToolHello } from './toolMessages.ts';
+export { readHello, readToolMessage } from './toolMessages.ts';

package/src/host/core/kinds.ts

@@ -4,8 +4,9 @@
  * 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, and the two
- * infrared kinds of `./irKinds.ts`. A name with children is a category whose
+ * `chem.smiles`, which pipeline lists among its future schemas, the two
+ * infrared kinds of `./irKinds.ts`, and the kinds a tool hands back, of
+ * `./resultKinds.ts`. 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
@@ -17,6 +18,9 @@ import { Ajv } from 'ajv';
 
 import type { IrJdxValue, IrPeaksValue } from './irKinds.ts';
 import { IR_JDX_SCHEMA, IR_PEAKS_SCHEMA } from './irKinds.ts';
+import type { HostItem } from './protocol.ts';
+import type { NameValue, SvgImageValue, TableValue } from './resultKinds.ts';
+import { NAME_SCHEMA, SVG_IMAGE_SCHEMA, TABLE_SCHEMA } from './resultKinds.ts';
 
 /** A molfile, V2000 or V3000. */
 export interface MolfileValue {
@@ -40,13 +44,19 @@ export type CheckedValue =
   | { kind: 'chem.ocl.id'; value: OclIdValue }
   | { kind: 'chem.smiles'; value: SmilesValue }
   | { kind: 'spectra.ir.jdx'; value: IrJdxValue }
-  | { kind: 'spectra.ir.peaks'; value: IrPeaksValue };
+  | { kind: 'spectra.ir.peaks'; value: IrPeaksValue }
+  | { kind: 'image.svg'; value: SvgImageValue }
+  | { kind: 'chem.name'; value: NameValue }
+  | { kind: 'data.table'; value: TableValue };
 
-/** The name of a kind a tool can read. */
+/** The name of a kind there is a schema for: one a tool reads, or one it hands back. */
 export type KnownKind = CheckedValue['kind'];
 
-/** The value a kind a tool can read carries. */
-type ValueOf<K extends KnownKind> = Extract<CheckedValue, { kind: K }>['value'];
+/** A checked value of one kind. */
+export type CheckedOf<K extends KnownKind> = Extract<CheckedValue, { kind: K }>;
+
+/** The value a kind with a schema carries. */
+type ValueOf<K extends KnownKind> = CheckedOf<K>['value'];
 
 /** What checking a value gave. */
 export type CheckOutcome =
@@ -100,6 +110,37 @@ export function checkValue(kind: KnownKind, value: unknown): CheckOutcome {
   return { valid: false, errors };
 }
 
+/**
+ * Read the value a tool handed back under an output, as the kind the host
+ * asked for: the item must be of that kind or one under it, and pass that
+ * kind's schema.
+ * @param items - What the tool handed back.
+ * @param key - The output.
+ * @param kind - The kind it is read as.
+ * @returns The value tagged with the kind, or `undefined` when the tool handed
+ * nothing back under that key.
+ * @throws {Error} When the item is of another kind, or not of its shape.
+ */
+export function readOutput<K extends KnownKind>(
+  items: readonly HostItem[],
+  key: string,
+  kind: K,
+): CheckedOf<K> | undefined {
+  const item = items.find((entry) => entry.key === key);
+  if (item === undefined) return undefined;
+  if (!kindAccepts(kind, item.kind)) {
+    throw new Error(`The ${key} handed back is a ${item.kind}, not a ${kind}.`);
+  }
+  const outcome = checkValue(kind, item.value);
+  if (!outcome.valid) {
+    throw new Error(
+      `The ${key} handed back is not shaped as a ${kind}: ${outcome.errors.join('; ')}.`,
+    );
+  }
+  // The validator of `kind` just vouched for the shape of the value.
+  return outcome.checked as CheckedOf<K>;
+}
+
 const MOLFILE_SCHEMA: JSONSchemaType<MolfileValue> = {
   type: 'object',
   properties: { molfile: { type: 'string' } },
@@ -124,8 +165,9 @@ const SMILES_SCHEMA: JSONSchemaType<SmilesValue> = {
   additionalProperties: false,
 };
 
-// `removeAdditional` strips what `additionalProperties: false` would refuse.
-const ajv = new Ajv({ removeAdditional: true });
+// `removeAdditional` strips what `additionalProperties: false` would refuse;
+// a table's cell is a string, a number or null, which is a union of types.
+const ajv = new Ajv({ removeAdditional: true, allowUnionTypes: true });
 
 const VALIDATORS: { [K in KnownKind]: ValidateFunction<ValueOf<K>> } = {
   'chem.molfile': ajv.compile(MOLFILE_SCHEMA),
@@ -135,4 +177,7 @@ const VALIDATORS: { [K in KnownKind]: ValidateFunction<ValueOf<K>> } = {
   // `nullable` on every optional field and so let a `null` band through.
   'spectra.ir.jdx': ajv.compile<IrJdxValue>(IR_JDX_SCHEMA),
   'spectra.ir.peaks': ajv.compile<IrPeaksValue>(IR_PEAKS_SCHEMA),
+  'image.svg': ajv.compile<SvgImageValue>(SVG_IMAGE_SCHEMA),
+  'chem.name': ajv.compile<NameValue>(NAME_SCHEMA),
+  'data.table': ajv.compile<TableValue>(TABLE_SCHEMA),
 };

package/src/host/core/messageValues.ts

@@ -0,0 +1,58 @@
+/**
+ * The values inside a protocol message, read as the untrusted input they are,
+ * on either side of the frame boundary.
+ */
+
+import type { HostItem } from './protocol.ts';
+
+/** How many items one message 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;
+
+/**
+ * Read the items of a message, dropping those without a string `kind`, at
+ * most {@link MAX_ITEMS} of them, each label cut to {@link MAX_LABEL_LENGTH}.
+ * @param values - The items as they arrived.
+ * @returns The items.
+ */
+export 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;
+}
+
+/**
+ * Read a list of strings, dropping anything else.
+ * @param value - The list as it arrived.
+ * @returns Its strings, or none when it is not a list.
+ */
+export 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;
+}
+
+/**
+ * Whether a value is a plain object, as every message is.
+ * @param value - The value.
+ * @returns `true` for an object that is not an array.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/host/core/protocol.ts

@@ -10,6 +10,10 @@
  * arrives as the untrusted input it is.
  */
 
+import { isRecord, readItems, readStrings } from './messageValues.ts';
+
+export { MAX_ITEMS, MAX_LABEL_LENGTH } from './messageValues.ts';
+
 /** The version a tool speaks; a `connect` naming another is ignored. */
 export const PROTOCOL_VERSION = 1;
 
@@ -19,12 +23,6 @@ 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'`. */
@@ -170,7 +168,7 @@ export interface OutputMessage {
  * 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, a label is cut to
- * {@link MAX_LABEL_LENGTH}, and a `load` without `accept` takes nothing back.
+ * `MAX_LABEL_LENGTH`, and a `load` without `accept` takes nothing back.
  * @param data - What the port delivered.
  * @returns The request, or `null`.
  */
@@ -207,33 +205,3 @@ export function isConnect(data: unknown): boolean {
     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);
-}