react-cheminfo 0.69.0 → 0.71.0

package/src/host/core/hostOutputs.ts

@@ -0,0 +1,197 @@
+/**
+ * What a tool hands back: the values a `get` asks for, and the `output` it
+ * sends when a value the host accepted changes.
+ *
+ * An `output` carries only what changed, item by item, against what the host
+ * 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.
+ */
+
+import { kindAccepts } from './kinds.ts';
+import type {
+  GetRequest,
+  HostItem,
+  OutputMessage,
+  ResultMessage,
+  ToolInterface,
+} from './protocol.ts';
+
+/** Where a tool's outputs are read, and how their changes are heard. */
+export interface HostOutputs {
+  /**
+   * The value of every output now, one item each, carrying its `key` and the
+   * `id` of the item it was made from. It must already show a document once
+   * `load` has returned, or the host is sent back what it just loaded.
+   */
+  read: () => readonly HostItem[];
+  /** Be told whenever they may have changed; the returned function stops it. */
+  subscribe: (listener: () => void) => () => void;
+}
+
+/**
+ * How long the outputs must stay still before a change is sent, in
+ * milliseconds: a burst of edits is one message.
+ */
+export const OUTPUT_DELAY = 300;
+
+/**
+ * Answer a `get` with the values it asks for — every output when it names
+ * none.
+ * @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.
+ */
+export function answerGet(
+  request: GetRequest,
+  tool: ToolInterface,
+  outputs: HostOutputs | undefined,
+): ResultMessage {
+  const { id, keys } = request;
+  const declared = new Set<string>();
+  for (const output of tool.outputs) declared.add(output.key);
+  if (outputs === undefined || declared.size === 0) {
+    return noOutput(id, `${tool.name} has nothing to give back yet.`);
+  }
+  const wanted = keys.length === 0 ? declared : new Set<string>();
+  for (const key of keys) {
+    if (declared.has(key)) wanted.add(key);
+  }
+  if (wanted.size === 0) {
+    return noOutput(
+      id,
+      `${tool.name} has no output called ${LIST.format(keys)}.`,
+    );
+  }
+  const items: HostItem[] = [];
+  for (const item of outputs.read()) {
+    if (item.key !== undefined && wanted.has(item.key)) items.push(item);
+  }
+  return { type: 'result', id, ok: true, items };
+}
+
+/** 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. */
+  baseline: (document: string, accept: readonly string[]) => void;
+  /** The outputs may have changed. */
+  changed: () => void;
+  /**
+   * Send what changed now rather than once it settles: another document is
+   * about to replace what the outputs are read from.
+   */
+  flush: () => void;
+  /** Send nothing more. */
+  stop: () => void;
+}
+
+/**
+ * Send the host what changed of the outputs it accepted, once they settle.
+ * @param outputs - Where the values are read.
+ * @param send - Posts a message to the host, when there is one.
+ * @param delay - How long the values must stay still, in milliseconds.
+ * @returns The publisher.
+ */
+export function createOutputPublisher(
+  outputs: HostOutputs,
+  send: (message: OutputMessage) => void,
+  delay: number,
+): OutputPublisher {
+  let document: string | null = null;
+  let accepted = new Set<string>();
+  let known = new Map<string, string>();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  function flush(): void {
+    timer = undefined;
+    if (document === null) return;
+    const items: HostItem[] = [];
+    for (const [identity, entry] of readAccepted(outputs, accepted)) {
+      if (known.get(identity) === entry.text) continue;
+      known.set(identity, entry.text);
+      items.push(entry.item);
+    }
+    if (items.length > 0) send({ type: 'output', document, items });
+  }
+
+  function stop(): void {
+    clearTimeout(timer);
+    timer = undefined;
+  }
+
+  return {
+    baseline(next, accept) {
+      stop();
+      document = next;
+      accepted = new Set(accept);
+      known = new Map();
+      for (const [identity, entry] of readAccepted(outputs, accepted)) {
+        known.set(identity, entry.text);
+      }
+    },
+    changed() {
+      if (document === null || accepted.size === 0) return;
+      stop();
+      timer = setTimeout(flush, delay);
+    },
+    flush() {
+      stop();
+      flush();
+    },
+    stop,
+  };
+}
+
+/**
+ * The accepted items, each under an identity that survives a re-read: its
+ * key, the id of the item it was made from, and its rank among items sharing
+ * both.
+ * @param outputs - Where the values are read.
+ * @param accepted - The keys and kinds the host takes back.
+ * @returns Each item with its value as text, by identity.
+ */
+function readAccepted(
+  outputs: HostOutputs,
+  accepted: ReadonlySet<string>,
+): Map<string, { item: HostItem; text: string }> {
+  const entries = new Map<string, { item: HostItem; text: string }>();
+  if (accepted.size === 0) return entries;
+  for (const item of outputs.read()) {
+    if (!isAccepted(item, accepted)) continue;
+    const base = `${item.key ?? item.kind}\n${item.id ?? ''}`;
+    let rank = 0;
+    while (entries.has(`${base}\n${rank}`)) rank++;
+    entries.set(`${base}\n${rank}`, {
+      item,
+      text: JSON.stringify(item.value),
+    });
+  }
+  return entries;
+}
+
+/**
+ * Whether the host takes an item back: `accept` names its output's key, or
+ * its kind — a kind taking every kind under it, as an input's does.
+ * @param item - The item.
+ * @param accepted - What the host takes back.
+ * @returns Whether it goes back.
+ */
+function isAccepted(item: HostItem, accepted: ReadonlySet<string>): boolean {
+  if (item.key !== undefined && accepted.has(item.key)) return true;
+  for (const name of accepted) {
+    if (kindAccepts(name, item.kind)) return true;
+  }
+  return false;
+}
+
+function noOutput(id: string, message: string): ResultMessage {
+  return {
+    type: 'result',
+    id,
+    ok: false,
+    error: { code: 'no-output', message },
+  };
+}
+
+const LIST = new Intl.ListFormat('en', { type: 'disjunction' });

package/src/host/core/index.ts

@@ -1,10 +1,11 @@
-export type {
-  HostConnectionOptions,
-  HostMessageEvent,
-  InputSelection,
-  LoadedInput,
-} from './connectHost.ts';
-export { connectHost, selectInputs } from './connectHost.ts';
+export type { HostConnectionOptions, HostMessageEvent } from './connectHost.ts';
+export { connectHost } from './connectHost.ts';
+export type { HostOutputs, OutputPublisher } from './hostOutputs.ts';
+export {
+  OUTPUT_DELAY,
+  answerGet,
+  createOutputPublisher,
+} from './hostOutputs.ts';
 export type { StructureValue } from './hostStructure.ts';
 export {
   STRUCTURE_KINDS,
@@ -12,6 +13,8 @@ export {
   hostStructureSource,
   readHostMolecule,
 } from './hostStructure.ts';
+export type { IrJdxValue, IrPeakValue, IrPeaksValue } from './irKinds.ts';
+export { IR_JDX_SCHEMA, IR_PEAKS_SCHEMA } from './irKinds.ts';
 export type {
   CheckOutcome,
   CheckedValue,
@@ -29,6 +32,7 @@ export type {
   HostItem,
   HostRequest,
   LoadRequest,
+  OutputMessage,
   ResultMessage,
   ToolInput,
   ToolInterface,
@@ -44,3 +48,5 @@ export {
   isConnect,
   parseRequest,
 } from './protocol.ts';
+export type { InputSelection, LoadedInput } from './selectInputs.ts';
+export { selectInputs } from './selectInputs.ts';

package/src/host/core/irKinds.ts

@@ -0,0 +1,92 @@
+/**
+ * The kinds a measured infrared spectrum travels as: the JCAMP-DX a notebook
+ * keeps with the bands picked on it, and those bands alone, which is what a
+ * tool hands back.
+ *
+ * Shaped on what SciPeaks keeps for a sample's infrared spectrum — a JCAMP-DX
+ * attachment and a `peak` list beside it — with the text of the attachment in
+ * place of its address, since a tool framed from another origin cannot fetch
+ * what the notebook serves its own pages. A band is written the way SciPeaks
+ * and `ir-spectrum` write one, so what a tool hands back can be stored as it
+ * arrives.
+ *
+ * Named after pipeline's `spectra.nmr.1d.jdx`. Pipeline's own `spectra.ir` is
+ * a computed spectrum — normal modes, not a measurement — and is not one of the
+ * kinds read here.
+ */
+
+/** One band of an infrared spectrum, as SciPeaks and `ir-spectrum` write it. */
+export interface IrPeakValue {
+  /** Where it sits, in cm⁻¹. */
+  wavenumber: number;
+  /**
+   * Its absorbance.
+   * @default read off the spectrum
+   */
+  absorbance?: number;
+  /**
+   * Its transmittance, as a fraction between 0 and 1 — not a percentage.
+   * @default read off the spectrum
+   */
+  transmittance?: number;
+  /**
+   * How strong it is: `w` weak, `m` medium, `S` strong. Any other letter is
+   * worked out again from the spectrum.
+   * @default worked out from the spectrum
+   */
+  kind?: string;
+}
+
+/** `spectra.ir.jdx`: a measured infrared spectrum and the bands picked on it. */
+export interface IrJdxValue {
+  /** The JCAMP-DX, as text. */
+  jdx: string;
+  /**
+   * The name the notebook keeps it under, e.g. `spectra/ir/sample.jdx`.
+   * @default undefined
+   */
+  filename?: string;
+  /**
+   * The bands picked on it. Absent or empty, the tool picks them itself.
+   * @default undefined
+   */
+  peaks?: IrPeakValue[];
+}
+
+/** `spectra.ir.peaks`: the bands picked on an infrared spectrum, alone. */
+export interface IrPeaksValue {
+  /** The bands, ascending by wavenumber. */
+  peaks: IrPeakValue[];
+}
+
+const IR_PEAK_SCHEMA = {
+  type: 'object',
+  properties: {
+    wavenumber: { type: 'number' },
+    absorbance: { type: 'number' },
+    transmittance: { type: 'number' },
+    kind: { type: 'string' },
+  },
+  required: ['wavenumber'],
+  additionalProperties: false,
+} as const;
+
+/** The schema of `spectra.ir.jdx`. */
+export const IR_JDX_SCHEMA = {
+  type: 'object',
+  properties: {
+    jdx: { type: 'string' },
+    filename: { type: 'string' },
+    peaks: { type: 'array', items: IR_PEAK_SCHEMA },
+  },
+  required: ['jdx'],
+  additionalProperties: false,
+} as const;
+
+/** The schema of `spectra.ir.peaks`. */
+export const IR_PEAKS_SCHEMA = {
+  type: 'object',
+  properties: { peaks: { type: 'array', items: IR_PEAK_SCHEMA } },
+  required: ['peaks'],
+  additionalProperties: false,
+} as const;

package/src/host/core/kinds.ts

@@ -4,16 +4,20 @@
  * 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.
+ * `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
+ * 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';
 
+import type { IrJdxValue, IrPeaksValue } from './irKinds.ts';
+import { IR_JDX_SCHEMA, IR_PEAKS_SCHEMA } from './irKinds.ts';
+
 /** A molfile, V2000 or V3000. */
 export interface MolfileValue {
   molfile: string;
@@ -34,7 +38,9 @@ export interface SmilesValue {
 export type CheckedValue =
   | { kind: 'chem.molfile'; value: MolfileValue }
   | { kind: 'chem.ocl.id'; value: OclIdValue }
-  | { kind: 'chem.smiles'; value: SmilesValue };
+  | { kind: 'chem.smiles'; value: SmilesValue }
+  | { kind: 'spectra.ir.jdx'; value: IrJdxValue }
+  | { kind: 'spectra.ir.peaks'; value: IrPeaksValue };
 
 /** The name of a kind a tool can read. */
 export type KnownKind = CheckedValue['kind'];
@@ -125,4 +131,8 @@ 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),
+  // Written as plain schemas rather than `JSONSchemaType`, which would demand
+  // `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),
 };

package/src/host/core/protocol.ts

@@ -4,9 +4,10 @@
  *
  * 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.
+ * else goes through that port: the host's requests (`load`, `get`), the tool's
+ * `result` for each, and the `output` the tool sends when a value the host
+ * takes back changes. 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. */
@@ -52,9 +53,24 @@ export interface ToolInput {
   key: string;
   /** Kinds in order of preference; a category accepts every kind under it. */
   kinds: readonly string[];
+  /**
+   * Whether it takes every item of its kinds, in the host's order, rather than
+   * the one it prefers — every spectrum of a sample.
+   * @default false
+   */
+  many?: boolean;
+  /**
+   * Whether a request may leave it without an item. A request is still
+   * refused when no input at all gets one.
+   * @default false
+   */
+  optional?: boolean;
 }
 
-/** One value the tool can hand back. */
+/**
+ * One value the tool can hand back: answered to `get`, and sent as `output`
+ * whenever it changes, when the host accepted it.
+ */
 export interface ToolOutput {
   key: string;
   kind: string;
@@ -86,6 +102,13 @@ export interface LoadRequest {
   /** What the data belongs to; the same document twice is applied once. */
   document: string;
   items: HostItem[];
+  /**
+   * The outputs the host takes back for this document, by key or by kind — a
+   * kind taking every kind under it: the tool sends an `output` whenever one
+   * of their values changes.
+   * @default undefined — nothing is sent unasked
+   */
+  accept?: string[];
 }
 
 /** `get`: the current value of some outputs. */
@@ -119,18 +142,35 @@ export interface UsedItem {
   kind: string;
 }
 
-/** The answer to one request, carrying its `id`. */
+/**
+ * The answer to one request, carrying its `id`: which items a `load` used, or
+ * the values a `get` asked for.
+ */
 export type ResultMessage =
   | { type: 'result'; id: string; ok: true; used: UsedItem[] }
+  | { type: 'result'; id: string; ok: true; items: HostItem[] }
   | { type: 'result'; id: string; ok: false; error: HostError };
 
+/**
+ * Sent by the tool, unasked, when values the host accepted have changed — the
+ * user picked a band. It carries only the items that changed: one missing is
+ * unchanged, never deleted.
+ */
+export interface OutputMessage {
+  type: 'output';
+  /** The document the values belong to, as the host's `load` named it. */
+  document: string;
+  /** Each with its `key`, and the `id` of the item it was made from. */
+  items: HostItem[];
+}
+
 /**
  * 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}.
+ * without a string `kind` is dropped, a label is cut to
+ * {@link MAX_LABEL_LENGTH}, and a `load` without `accept` takes nothing back.
  * @param data - What the port delivered.
  * @returns The request, or `null`.
  */
@@ -140,12 +180,14 @@ export function parseRequest(data: unknown): HostRequest | null {
     if (typeof data.document !== 'string' || !Array.isArray(data.items)) {
       return null;
     }
-    return {
+    const load: LoadRequest = {
       type: 'load',
       id: data.id,
       document: data.document,
       items: readItems(data.items),
     };
+    if (Array.isArray(data.accept)) load.accept = readStrings(data.accept);
+    return load;
   }
   if (data.type === 'get') {
     return { type: 'get', id: data.id, keys: readStrings(data.keys) };

package/src/host/core/selectInputs.ts

@@ -0,0 +1,145 @@
+/**
+ * Which items of a request each input of a tool takes, and the sentence a
+ * host is answered with when the request loads nothing.
+ */
+
+import type { CheckedValue, KnownKind } from './kinds.ts';
+import { checkValue, isKnownKind, kindAccepts } from './kinds.ts';
+import type {
+  HostError,
+  HostItem,
+  ToolInput,
+  ToolInterface,
+} 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 choosing the items of a request gave. */
+export type InputSelection =
+  { ok: true; inputs: LoadedInput[] } | { ok: false; error: HostError };
+
+/**
+ * Give each input of the tool the items of a request it takes.
+ *
+ * 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 input taking `many` takes every such item instead, in the host's order.
+ * An item naming another input's `key` is left to that input.
+ *
+ * A required input left without an item refuses the request. An optional one
+ * is passed over, unless no input got an item at all.
+ * @param tool - What the tool takes.
+ * @param items - What the host sent.
+ * @returns The items the inputs took, or why the request loads nothing.
+ */
+export function selectInputs(
+  tool: ToolInterface,
+  items: readonly HostItem[],
+): InputSelection {
+  const inputs: LoadedInput[] = [];
+  const passedOver: string[] = [];
+  for (const input of tool.inputs) {
+    const errors: string[] = [];
+    const taken = input.many
+      ? selectEvery(input, items, errors)
+      : selectFirst(input, items, errors);
+    if (taken.length > 0) {
+      inputs.push(...taken);
+    } else if (input.optional) {
+      passedOver.push(...errors);
+    } else {
+      return { ok: false, error: refusal(tool, [input], errors) };
+    }
+  }
+  if (inputs.length > 0 || tool.inputs.length === 0) {
+    return { ok: true, inputs };
+  }
+  return { ok: false, error: refusal(tool, tool.inputs, passedOver) };
+}
+
+function selectFirst(
+  input: ToolInput,
+  items: readonly HostItem[],
+  errors: string[],
+): LoadedInput[] {
+  for (const accepted of input.kinds) {
+    if (!isKnownKind(accepted)) continue;
+    for (const item of items) {
+      if (!isFor(input, accepted, item)) continue;
+      const loaded = checkItem(input.key, accepted, item, errors);
+      if (loaded !== null) return [loaded];
+    }
+  }
+  return [];
+}
+
+function selectEvery(
+  input: ToolInput,
+  items: readonly HostItem[],
+  errors: string[],
+): LoadedInput[] {
+  const taken: LoadedInput[] = [];
+  for (const item of items) {
+    for (const accepted of input.kinds) {
+      if (!isKnownKind(accepted) || !isFor(input, accepted, item)) continue;
+      const loaded = checkItem(input.key, accepted, item, errors);
+      if (loaded === null) continue;
+      taken.push(loaded);
+      break;
+    }
+  }
+  return taken;
+}
+
+function isFor(input: ToolInput, accepted: KnownKind, item: HostItem): boolean {
+  if (item.key !== undefined && item.key !== input.key) return false;
+  return kindAccepts(accepted, item.kind);
+}
+
+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;
+}
+
+/**
+ * Why a request loads nothing: some item had the wrong shape, or no item was
+ * of a kind the inputs take.
+ * @param tool - What the tool takes.
+ * @param inputs - The inputs left without an item.
+ * @param errors - What the schemas found.
+ * @returns The error the host is answered with.
+ */
+function refusal(
+  tool: ToolInterface,
+  inputs: readonly ToolInput[],
+  errors: string[],
+): HostError {
+  if (errors.length > 0) {
+    const keys = inputs.map((input) => input.key);
+    return {
+      code: 'invalid',
+      message: `No item for ${LIST.format(keys)} has the shape its kind requires, so ${tool.name} loaded nothing.`,
+      errors,
+    };
+  }
+  const kinds = inputs.flatMap((input) => input.kinds);
+  return {
+    code: 'no-input',
+    message: `No item is a ${LIST.format(kinds)}, so ${tool.name} loaded nothing.`,
+  };
+}
+
+const LIST = new Intl.ListFormat('en', { type: 'disjunction' });