@jarenjs/contract 0.43.1

package/src/app/effect.js

@@ -0,0 +1,190 @@
+//@ts-check
+/**
+ * @file `createContractEffect(client, options)`: ONE `@jarenjs/app`
+ * effect handler (`run: "contract"`) that calls any operation of a
+ * client and settles every descriptor with a D6 outcome
+ * (docs/CONTRACT-FORMAT.md §11). It owns one task effect per distinct
+ * `policy.task` mode the contract uses — built lazily through the
+ * `createTaskEffect` factory the host hands in from `@jarenjs/app` —
+ * and routes each descriptor `{ op, input, id, done, fail?, slot? }` to
+ * the mode's inner effect, so the per-operation concurrency semantics
+ * come from the contract's policy and never appear in the app document.
+ * This package imports nothing from `@jarenjs/app`; the factory crosses
+ * as a function, the documents as JSON.
+ *
+ * Settlement: the inner effect's `run` invokes the client with the
+ * slot's signal and the descriptor's `id` as the attempt; an outcome of
+ * `kind: "cancelled"` is turned into an `AbortError` so the task effect
+ * dispatches nothing (a superseded task is dead by design); every other
+ * outcome resolves and lands as `{ id, result: outcome }`; a host throw
+ * is projected — never flattened to a string — into a `JC2058` outcome
+ * that lands as `{ id, error: outcome }`.
+ */
+
+import { ContractHostError } from '../errors.js';
+import { isOutcome, hostFailureOutcome } from '../client/outcome.js';
+
+/**
+ * @typedef {import('../compile.js').Contract} Contract
+ * @typedef {import('../client/outcome.js').Outcome} Outcome
+ */
+
+/**
+ * A client binding: what every `open*` returns. The effect reads
+ * `invoke` and `contract` (for the task mode of each operation).
+ * @typedef {{ invoke: (op: string, input: unknown, ctx: { signal: AbortSignal, attempt: unknown }) => Promise<Outcome> | Outcome, contract: Contract }} ClientLike
+ */
+
+/**
+ * The `createTaskEffect` factory of `@jarenjs/app`, as the host hands it in.
+ * @typedef {(run: (props: any, signal: AbortSignal) => any, options: { mode: string, projectError: (err: unknown, props: any) => any }) => TaskEffectLike} TaskEffectFactory
+ */
+
+/**
+ * What a task effect exposes.
+ * @typedef {((props: any, dispatch: (name: string, payload?: any) => void) => void) & { cancel: (slot?: string) => void, cancelAll: () => void, dispose: () => void }} TaskEffectLike
+ */
+
+/**
+ * @typedef {Object} ContractEffectOptions
+ * @property {TaskEffectFactory} createTaskEffect - `createTaskEffect` from `@jarenjs/app` (required)
+ * @property {(err: unknown, props: any) => any} [projectError] - consulted
+ *   first when the host throws; a result that is not an outcome falls
+ *   back to the `JC2058` outcome
+ * @property {Record<string, (params: object) => string> | null} [catalog] - compiled catalog for the `JC2058` message
+ */
+
+/**
+ * The contract effect: an effect handler with the task-effect controls.
+ * @typedef {((props: any, dispatch: (name: string, payload?: any) => void) => void) & {
+ *   cancel: (slot?: string) => void, cancelAll: () => void, dispose: () => void }} ContractEffect
+ */
+
+/**
+ * @param {string} code
+ * @param {string} reason
+ * @returns {ContractHostError}
+ */
+function host(code, reason) {
+  return new ContractHostError(code, `createContractEffect: ${reason}`);
+}
+
+/**
+ * An `AbortError`-named error: what `run` throws for a cancelled outcome
+ * so the task effect dispatches nothing.
+ * @returns {Error}
+ */
+function abortError() {
+  const err = new Error('the operation was cancelled');
+  err.name = 'AbortError';
+  return err;
+}
+
+/**
+ * Make the `contract` effect of an app over a client. Register it as
+ * `effects: { contract: createContractEffect(client, { createTaskEffect }) }`;
+ * the generated actions of `contractAppBinding` invoke it.
+ *
+ * @param {ClientLike} client - an open client (`openHttpClient`, …)
+ * @param {ContractEffectOptions} options
+ * @returns {ContractEffect}
+ * @throws {ContractHostError} `JC1008` for a malformed client or option
+ * @example
+ * // createApp and createTaskEffect are the host's, imported from @jarenjs/app;
+ * // openHttpClient from '@jarenjs/contract/client', createContractEffect from '@jarenjs/contract/app'
+ * const client = openHttpClient(contract, { baseUrl });
+ * const effect = createContractEffect(client, { createTaskEffect });
+ * createApp(doc, { effects: { contract: effect } });
+ */
+export function createContractEffect(client, options) {
+  if (client === null || typeof client !== 'object' || typeof client.invoke !== 'function'
+    || client.contract === null || typeof client.contract !== 'object' || client.contract.operations === null
+    || typeof client.contract.operations !== 'object') {
+    throw host('JC1008', 'the first argument must be an open client ({ invoke, contract })');
+  }
+  if (options === null || typeof options !== 'object' || typeof options.createTaskEffect !== 'function') {
+    throw host('JC1008', 'options.createTaskEffect is required — pass createTaskEffect from @jarenjs/app (this package does not import it)');
+  }
+  const factory = options.createTaskEffect;
+  const userProject = options.projectError === undefined ? null : options.projectError;
+  if (userProject !== null && typeof userProject !== 'function') throw host('JC1008', 'options.projectError must be a function');
+  const catalog = options.catalog === undefined ? null : options.catalog;
+  const operations = client.contract.operations;
+
+  /**
+   * The inner `run`: invoke with the slot's signal and the descriptor's
+   * id as the attempt; a cancelled outcome becomes an abort; a value that
+   * is not an outcome (a foreign client) becomes a `JC2058` outcome.
+   * @param {any} props
+   * @param {AbortSignal} signal
+   * @returns {Promise<Outcome>}
+   */
+  function run(props, signal) {
+    return Promise.resolve(client.invoke(props.op, props.input, { signal, attempt: props.id })).then((outcome) => {
+      if (!isOutcome(outcome)) return hostFailureOutcome(props.op, props.id, catalog);
+      if (!outcome.ok && outcome.kind === 'cancelled') throw abortError();
+      return outcome;
+    });
+  }
+
+  /**
+   * The settlement projector: a thrown host value becomes an outcome —
+   * the host's own projector first, the `JC2058` outcome otherwise — so
+   * the completion action always reads an outcome.
+   * @param {unknown} err
+   * @param {any} props
+   * @returns {Outcome}
+   */
+  function projectError(err, props) {
+    if (userProject !== null) {
+      try {
+        const projected = userProject(err, props);
+        if (isOutcome(projected)) return projected;
+      }
+      catch {
+        // fall through to the default projection
+      }
+    }
+    return hostFailureOutcome(typeof props?.op === 'string' ? props.op : '', props?.id, catalog);
+  }
+
+  /** @type {Map<string, TaskEffectLike>} */
+  const modes = new Map();
+
+  /**
+   * @param {string} mode
+   * @returns {TaskEffectLike}
+   */
+  function inner(mode) {
+    let effect = modes.get(mode);
+    if (effect === undefined) {
+      effect = factory(run, { mode, projectError });
+      modes.set(mode, effect);
+    }
+    return effect;
+  }
+
+  /** @type {any} */
+  const contractEffect = function contractEffect(/** @type {any} */ props, /** @type {(name: string, payload?: any) => void} */ dispatch) {
+    const op = props === null || typeof props !== 'object' ? undefined : props.op;
+    if (typeof op !== 'string' || !Object.hasOwn(operations, op)) {
+      throw new ContractHostError('JC1005', `createContractEffect: the effect props must name an operation of the contract in 'op', got ${JSON.stringify(op)}`);
+    }
+    inner(operations[op].policy.task)(props, dispatch);
+  };
+
+  /** @param {string} [slot] */
+  contractEffect.cancel = function cancel(slot) {
+    for (const effect of modes.values()) effect.cancel(slot);
+  };
+
+  contractEffect.cancelAll = function cancelAll() {
+    for (const effect of modes.values()) effect.cancelAll();
+  };
+
+  contractEffect.dispose = function dispose() {
+    for (const effect of modes.values()) effect.dispose();
+  };
+
+  return contractEffect;
+}

package/src/app/index.js

@@ -0,0 +1,26 @@
+//@ts-check
+/**
+ * @file The `@jarenjs/app` binding of a contract (docs/CONTRACT-FORMAT.md
+ * §11): `contractAppBinding` generates the state slice, the
+ * start/done/reset actions and the slice schema as pure JSON (the
+ * state-side guards derived from `policy.task`, the mode never named);
+ * `createContractEffect`
+ * makes the one `contract` effect those actions invoke, over any open
+ * client. Neither imports `@jarenjs/app` — the documents cross as JSON
+ * and the task-effect factory crosses as a function the host passes in.
+ */
+
+export { contractAppBinding } from './binding.js';
+export { createContractEffect } from './effect.js';
+export { createContractSubscription } from './subscription.js';
+
+/**
+ * @typedef {import('./binding.js').ContractAppBinding} ContractAppBinding
+ * @typedef {import('./binding.js').ContractAppBindingOptions} ContractAppBindingOptions
+ * @typedef {import('./binding.js').TaskSlot} TaskSlot
+ * @typedef {import('./binding.js').StreamSlot} StreamSlot
+ * @typedef {import('./effect.js').ContractEffect} ContractEffect
+ * @typedef {import('./effect.js').ContractEffectOptions} ContractEffectOptions
+ * @typedef {import('./effect.js').ClientLike} ClientLike
+ * @typedef {import('./subscription.js').StreamClientLike} StreamClientLike
+ */

package/src/app/subscription.js

@@ -0,0 +1,130 @@
+//@ts-check
+/**
+ * @file `createContractSubscription(client)`: the ONE `contract-stream`
+ * subscription handler the generated subs entries of
+ * `contractAppBinding` run (docs/CONTRACT-FORMAT.md §11.4). A handler is
+ * `(props, dispatch) => cleanup` — the `@jarenjs/app` subscription
+ * shape — so no task-effect factory is needed and this package still
+ * imports nothing from `@jarenjs/app`: the entry documents cross as
+ * JSON and the handler crosses as a function over a client.
+ *
+ * The handler subscribes through `client.subscribe`, maintains the
+ * document HOST-SIDE by applying each `{ patch, seq }` emission with
+ * `@jarenjs/json/patch` (copy-on-write — structural sharing is
+ * preserved end to end, which is what keeps the O(k) renderer's fast
+ * paths alive), and dispatches the named actions with `{ id, … }`
+ * payloads — the generated actions guard on the id (and, for `patch`,
+ * on a strictly greater `seq`), so a stale instance's dispatch is a
+ * provable no-op in state. An `onError` outcome lands in the error
+ * action as-is; a server `end` lands there too, as a `network`-kind
+ * outcome with the channel-closed code — the stream is gone and the
+ * slot must say so, so a view can offer a reconnect (a new `start`).
+ */
+
+import { compileJSONPatch } from '@jarenjs/json/patch';
+
+import { ContractHostError } from '../errors.js';
+import { renderMessage } from '../http/wire.js';
+import { CLIENT_ERRORS, makeMeta, failedOutcome, outcomeError, clientError } from '../client/outcome.js';
+import { PORT_LOCAL_ERRORS } from '../pipeline.js';
+
+/**
+ * @typedef {import('../compile.js').Contract} Contract
+ * @typedef {import('../client/outcome.js').Outcome} Outcome
+ * @typedef {import('../http/wire.js').Catalog} Catalog
+ */
+
+/**
+ * A client binding that carries streams: what `openHttpClient` and
+ * `openPortClient` return. The handler reads `subscribe` only.
+ * @typedef {{ subscribe: (op: string, input: unknown, options: object) => { stop: () => void }, contract: Contract }} StreamClientLike
+ */
+
+/**
+ * @typedef {Object} ContractSubscriptionOptions
+ * @property {Catalog | null} [catalog] - compiled catalog for the end/apply messages
+ */
+
+/**
+ * The props of one generated subs entry: the operation, the slot id and
+ * input resolved from state, and the action names to dispatch.
+ * @typedef {{ op: string, id: number, input: unknown, snapshot: string, patch: string, error: string }} StreamProps
+ */
+
+/**
+ * Make the `contract-stream` subscription handler of an app over a
+ * client. Register it as `subs: { 'contract-stream':
+ * createContractSubscription(client) }`; the generated entries of
+ * `contractAppBinding` run it.
+ *
+ * @param {StreamClientLike} client - an open client whose `capabilities.stream` is true
+ * @param {ContractSubscriptionOptions} [options]
+ * @returns {(props: StreamProps, dispatch: (name: string, payload?: any) => void) => (() => void)}
+ * @throws {ContractHostError} `JC1008` for a malformed client or option
+ * @example
+ * createApp({ ...doc, subs: [...binding.subs] }, {
+ *   effects: { contract: createContractEffect(client, { createTaskEffect }) },
+ *   subs: { 'contract-stream': createContractSubscription(client) },
+ * });
+ */
+export function createContractSubscription(client, options = {}) {
+  if (client === null || typeof client !== 'object' || typeof client.subscribe !== 'function'
+    || client.contract === null || typeof client.contract !== 'object') {
+    throw new ContractHostError('JC1008', 'createContractSubscription: the first argument must be an open client with subscribe ({ subscribe, contract })');
+  }
+  if (options === null || typeof options !== 'object') {
+    throw new ContractHostError('JC1008', 'createContractSubscription: options must be an object');
+  }
+  const catalog = options.catalog === undefined ? null : options.catalog;
+
+  return function contractStream(props, dispatch) {
+    const p = /** @type {any} */ (props);
+    if (p === null || typeof p !== 'object' || typeof p.op !== 'string'
+      || typeof p.snapshot !== 'string' || typeof p.patch !== 'string' || typeof p.error !== 'string') {
+      throw new ContractHostError('JC1008', 'contract-stream: props must carry op and the snapshot/patch/error action names (a contractAppBinding subs entry)');
+    }
+    const { op, id } = p;
+    /** @type {unknown} */
+    let doc = null;
+    const sub = client.subscribe(op, p.input === undefined ? null : p.input, {
+      onSnapshot: (/** @type {unknown} */ value, /** @type {{ seq: number }} */ info) => {
+        doc = value;
+        dispatch(p.snapshot, { id, value, seq: info.seq });
+      },
+      onPatch: (/** @type {{ patch: any[], seq: number }} */ emission) => {
+        try {
+          doc = compileJSONPatch(/** @type {any} */ (emission.patch))(doc);
+        }
+        catch {
+          // the emission does not apply to the document the stream built —
+          // one end broke the patch contract; the error dispatch flips the
+          // slot off 'live' and the app's own reconciliation runs the
+          // cleanup, so the client's stop() still runs exactly once
+          dispatch(p.error, {
+            id,
+            outcome: failedOutcome('contract',
+              clientError(catalog, 'JC2053', { op }, null, [{ path: '', keyword: 'patch' }]), makeMeta(op, null, null)),
+          });
+          return;
+        }
+        dispatch(p.patch, { id, value: doc, seq: emission.seq });
+      },
+      onError: (/** @type {Outcome} */ outcome) => dispatch(p.error, { id, outcome }),
+      onEnd: () => {
+        // the server ended the stream: the slot must say the channel is
+        // gone, so a view can offer a reconnect (a fresh start)
+        dispatch(p.error, {
+          id,
+          outcome: failedOutcome('network',
+            outcomeError('JC2074', renderMessage(catalog, PORT_LOCAL_ERRORS.JC2074.msgid, { op }), null, null, false),
+            makeMeta(op, null, null)),
+        });
+      },
+    });
+    return () => sub.stop();
+  };
+}
+
+// re-exported so a host settling its own outcomes beside the handler
+// needs no second import path
+export { CLIENT_ERRORS };

package/src/bundle.js

@@ -0,0 +1,168 @@
+//@ts-check
+/**
+ * @file Same-document schema reachability and bundling — the one place in
+ * the suite that answers "which `$defs` does this schema need?" and
+ * "make this schema stand alone". The public projection keeps exactly
+ * the reachable `$defs` of the retained operations (05 hashes that); a
+ * tool definition carries its input schema with the reachable `$defs`
+ * inlined under the schema's own `$defs`, because a tool schema must be
+ * self-contained.
+ *
+ * Reachability follows same-document `$ref`s (`#`, `#/…` pointers,
+ * `#anchor`) with the resolver `compileContract` itself uses
+ * (`@jarenjs/validate/normalize`), so a reference the compiler accepted
+ * resolves here by the same rules. A target is attributed to the `$defs`
+ * entry that CONTAINS it — `#/$defs/Product/properties/id` needs
+ * `Product` — and the entry is walked in turn. References that do not
+ * land inside `$defs` (`#`, a pointer into another operation's schema,
+ * an absolute `$id`) are left as written: the document states where
+ * shared schemas live, and that is `$defs`.
+ */
+
+import { isJsonObject, setObjectMember } from '@jarenjs/core/object';
+import { collectSameDocumentAnchors, resolveSameDocumentRef } from '@jarenjs/validate/normalize';
+import { parseJSONPointer } from '@jarenjs/json/pointer';
+
+/** JSON-value keywords whose content is data, not schema — not walked for `$ref`. */
+const DATA_KEYWORDS = new Set(['const', 'enum', 'default', 'examples']);
+
+/**
+ * The containment map of a document's `$defs`: every object or array node
+ * inside a `$defs` entry → the entry's name (the entry's own node
+ * included). First entry wins for a node shared by two entries (a
+ * snapshot never shares, but a hand-built document may).
+ * @param {any} defs
+ * @returns {Map<object, string>}
+ */
+function containment(defs) {
+  /** @type {Map<object, string>} */
+  const owner = new Map();
+  if (!isJsonObject(defs)) return owner;
+  const names = Object.keys(defs);
+  for (let i = 0; i < names.length; i++) {
+    const name = names[i];
+    /** @param {any} node */
+    const mark = (node) => {
+      if (node === null || typeof node !== 'object' || owner.has(node)) return;
+      owner.set(node, name);
+      if (Array.isArray(node)) {
+        for (let j = 0; j < node.length; j++) mark(node[j]);
+        return;
+      }
+      const keys = Object.keys(node);
+      for (let j = 0; j < keys.length; j++) mark(node[keys[j]]);
+    };
+    mark(defs[name]);
+  }
+  return owner;
+}
+
+/**
+ * The `$defs` entry a same-document reference lands in, or `undefined`
+ * when it lands elsewhere (the root, an operation, nowhere). A pointer
+ * under `#/$defs/` names its entry directly (so a boolean entry, which
+ * has no identity to look up, is found too); anything else — an anchor,
+ * a pointer that reaches a `$defs` node by another route — is attributed
+ * by containment.
+ * @param {string} ref
+ * @param {Record<string, any>} defs
+ * @param {Map<object, string>} owner
+ * @param {any} doc
+ * @param {Map<string, object>} anchors
+ * @returns {string | undefined}
+ */
+function defOf(ref, defs, owner, doc, anchors) {
+  if (ref.startsWith('#/$defs/')) {
+    let tokens;
+    try {
+      tokens = parseJSONPointer(ref.slice(1));
+    }
+    catch {
+      return undefined;
+    }
+    const name = String(tokens[1]);
+    if (Object.hasOwn(defs, name) && resolveSameDocumentRef(ref, doc, anchors) !== undefined) return name;
+    return undefined;
+  }
+  const target = resolveSameDocumentRef(ref, doc, anchors);
+  return target !== null && typeof target === 'object' ? owner.get(target) : undefined;
+}
+
+/**
+ * The names of the document's `$defs` reachable from `roots` by
+ * same-document `$ref`, transitively, in first-reference order: the
+ * roots are walked in the order given, depth-first in member order, and
+ * a `$defs` entry is walked at the moment it is first reached. Data
+ * keywords (`const`, `enum`, `default`, `examples`) are not walked.
+ * @param {readonly unknown[]} roots - schemas (objects or booleans) rooted in `doc`
+ * @param {any} doc - the document holding `$defs` (a contract document, or any schema root)
+ * @returns {string[]}
+ */
+export function reachableDefs(roots, doc) {
+  const defs = isJsonObject(doc) && isJsonObject(doc.$defs) ? doc.$defs : null;
+  if (defs === null) return [];
+  const owner = containment(defs);
+  const anchors = collectSameDocumentAnchors(doc);
+  /** @type {string[]} */
+  const names = [];
+  const seenNames = new Set();
+  /** @type {Set<object>} */
+  const visited = new Set();
+  /** @param {any} node */
+  const walk = (node) => {
+    if (node === null || typeof node !== 'object' || visited.has(node)) return;
+    visited.add(node);
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i++) walk(node[i]);
+      return;
+    }
+    if (typeof node.$ref === 'string' && node.$ref.startsWith('#')) {
+      const name = defOf(node.$ref, defs, owner, doc, anchors);
+      if (name !== undefined) {
+        if (!seenNames.has(name)) {
+          seenNames.add(name);
+          names.push(name);
+        }
+        walk(defs[name]);
+      }
+    }
+    const keys = Object.keys(node);
+    for (let i = 0; i < keys.length; i++) {
+      if (DATA_KEYWORDS.has(keys[i])) continue;
+      walk(node[keys[i]]);
+    }
+  };
+  for (let i = 0; i < roots.length; i++) walk(roots[i]);
+  return names;
+}
+
+/**
+ * Make a schema stand alone: the schema with the `$defs` it reaches
+ * (transitively, first-reference order) copied under its own `$defs`, so
+ * every `#/$defs/X` it carries resolves inside the returned document. A
+ * boolean schema is returned as is; a schema that reaches nothing gains no
+ * `$defs`. A schema that declared its own `$defs` member loses it — at the
+ * new root that member would shadow the document's, and its entries were
+ * only addressable by a pointer through the operation anyway.
+ * @param {any} schema - a schema rooted in `doc`
+ * @param {any} doc - the document holding `$defs`
+ * @returns {any} a fresh top-level object sharing the schema's subtrees
+ */
+export function bundleSameDocument(schema, doc) {
+  if (!isJsonObject(schema)) return schema;
+  const names = reachableDefs([schema], doc);
+  /** @type {Record<string, any>} */
+  const out = {};
+  const keys = Object.keys(schema);
+  for (let i = 0; i < keys.length; i++) {
+    if (keys[i] === '$defs') continue;
+    setObjectMember(out, keys[i], schema[keys[i]]);
+  }
+  if (names.length > 0) {
+    /** @type {Record<string, any>} */
+    const defs = {};
+    for (let i = 0; i < names.length; i++) setObjectMember(defs, names[i], doc.$defs[names[i]]);
+    out.$defs = defs;
+  }
+  return out;
+}