@jarenjs/linq 0.49.2 → 0.66.1

package/src/capture-root.js

@@ -0,0 +1,82 @@
+//@ts-check
+/**
+ * @file One capture over a value rooted at `$` with named externals —
+ * the shared piece under every pen's query-valued member: a schema
+ * `check()` rule (`root`, `path`), a model `compute()` default (no
+ * externals), a JSLT rule body (`root`, `path` and the parameters the
+ * body declares). The value proxy is rooted at `$`, the instance the
+ * query is evaluated at; the externals proxy answers exactly the named
+ * expressions and refuses any other name at build time (`JL0104`),
+ * earlier than the engine's own error and with the same meaning. One
+ * implementation: a pen adds an externals list, never a capture entry
+ * point.
+ */
+
+import { captureExpression } from './expression.js';
+import { LinqBuildError } from './errors.js';
+
+/** No parameters are declared for a rule: `p.x` cannot appear. */
+const NO_PARAMS = new Set();
+
+/** The indefinite article for a method name (`edge() select` → `an`). */
+const article = (/** @type {string} */ what) =>
+  ('aeiou'.includes(what.charAt(0).toLowerCase()) ? 'an' : 'a');
+
+/**
+ * The externals proxy: exactly the named expressions the capture handed
+ * us; anything else has nothing to bind to.
+ *
+ * The message states only what this file KNOWS — how many externals the
+ * evaluator binds and which — because that is all it can know: WHERE the
+ * query is evaluated differs per pen (a schema rule over the instance, a
+ * model default over the document being written, a flow guard over the
+ * step scope at step time), and naming one pen's answer here made the
+ * message contradict its own advice for every other pen. A caller that
+ * has a scope to name passes it as `advice`.
+ * @param {string} what - the method, for the message
+ * @param {readonly string[]} names - the externals bound
+ * @param {readonly any[]} proxies - one expression proxy per name
+ * @param {((name: string) => string) | undefined} advice - the fix, when one exists
+ * @param {string} noun - what this pen calls the callback
+ */
+function externalsProxy(what, names, proxies, advice, noun) {
+  return new Proxy(Object.freeze({}), {
+    get(_target, prop) {
+      if (typeof prop === 'symbol') return undefined;
+      const index = names.indexOf(/** @type {string} */ (prop));
+      if (index !== -1) return proxies[index];
+      const bound = names.length === 0
+        ? 'no externals at all'
+        : `exactly ${names.length === 1 ? 'one external' : `${names.length} externals`}, `
+          + `${names.map((n) => `'${n}'`).join(' and ')}`;
+      throw new LinqBuildError('JL0104',
+        `${article(what)} ${what} ${noun} cannot bind '${prop}' — its query evaluates with `
+        + `${bound}; anything else has nothing to bind to`
+        + (advice === undefined ? '' : advice(prop)));
+    },
+  });
+}
+
+/**
+ * Capture one rule into a query document over a value rooted at `$`,
+ * with the named externals as the second argument.
+ * @param {string} what - the method, for the message
+ * @param {readonly string[]} externals - the externals the evaluator binds
+ * @param {(value: any, externals: any) => any} rule
+ * @param {{ advice?: (name: string) => string, fold?: boolean, noun?: string }} [options] -
+ *   `advice`: appended to the `JL0104` message — how an unbound name could
+ *   be declared where it can, or what the callback's own argument already
+ *   is; `fold`: whether a pure data tree folds into one `$const` (the
+ *   default) or is spelled as a constructor tree; `noun`: what this pen
+ *   calls the callback (`'rule'` by default; a pen with no rules passes
+ *   its own word)
+ * @returns {any} the captured query expression (plain JSON)
+ */
+export function captureQuery(what, externals, rule, options = {}) {
+  const noun = options.noun ?? 'rule';
+  return captureExpression(
+    (value, ...bound) => rule(value, externalsProxy(what, externals, bound, options.advice, noun)),
+    [{ doc: '$', pathable: true }, ...externals],
+    NO_PARAMS,
+    options.fold !== false);
+}

package/src/concurrency.js

@@ -1,7 +1,7 @@
 //@ts-check
 /**
  * @file `mapAsync` — the ONE explicit bounded-concurrency boundary
- * (LINQ-FORMAT.md §11). Element-wise asynchronous work (an HTTP call, a
+ * (QUERY-PEN.md §11). Element-wise asynchronous work (an HTTP call, a
  * model call, a file read per row) happens here and nowhere else: there
  * is no parallel universe of `selectAwait`-shaped operators, and a
  * per-element async *predicate* is `mapAsync` then `where`, by design.
@@ -54,6 +54,18 @@ export async function* applyMapAsync(items, fn, opts) {
   /** The pipeline's own failure, so source cleanup cannot displace it.
    * @type {{ reason: any } | null} */
   let failure = null;
+  /** A callback failure may close while a pull is pending; finally awaits
+   * that same close, so cancellation reaches the producer exactly once.
+   * @type {Promise<any> | null} */
+  let closing = null;
+  const closeSource = () => {
+    if (closing === null) {
+      closing = Promise.resolve().then(() => typeof items.return === 'function'
+        ? items.return(undefined) : undefined);
+      closing.catch(() => {}); // the finally block reports cleanup failures
+    }
+    return closing;
+  };
 
   try {
     if (opts.mode === 'concat' || (opts.mode === 'parallel' && opts.concurrency === 1)) {
@@ -118,25 +130,45 @@ export async function* applyMapAsync(items, fn, opts) {
     // parallel: a sliding window of `concurrency` in-flight tasks
     const window = [];
     let sourceDone = false;
+    // the first rejection anywhere in the window aborts every sibling
+    // and stops the pull, at once — not when it reaches the head of the
+    // ordered window: the rejection itself still surfaces in order
+    let rejected = false;
+    let stopPull;
+    /** @type {Promise<IteratorResult<any>>} */
+    const stoppedPull = new Promise((resolve) => {
+      stopPull = () => resolve({ done: true, value: undefined });
+    });
+    const taskFailed = () => {
+      if (rejected) return;
+      rejected = true;
+      stopPull();
+      controller.abort();
+      closeSource();
+    };
+    // An idle producer must not hide a callback's failure. The race also
+    // observes a pending next() that rejects after cancellation won.
+    const next = () => Promise.race([items.next(), stoppedPull]);
     const pull = async () => {
-      const step = await items.next();
+      const step = await next();
       if (step.done) { sourceDone = true; return null; }
+      if (rejected) return null; // a sibling failed while this pull awaited
       const promise = Promise.resolve(fn(step.value, signal));
       // a rejection must wait its turn in the ordered window without
       // firing unhandledRejection while an earlier task is in flight
-      promise.catch(() => {});
+      promise.catch(taskFailed);
       return { promise };
     };
     if (opts.ordered) {
       // completion order = source order; the window buffers at most
       // `concurrency` results (the documented buffering cost)
-      while (!sourceDone && window.length < opts.concurrency) {
+      while (!sourceDone && !rejected && window.length < opts.concurrency) {
         const task = await pull();
         if (task !== null) window.push(task.promise);
       }
       while (window.length > 0) {
         const value = await window.shift();
-        if (!sourceDone) {
+        if (!sourceDone && !rejected) {
           const task = await pull();
           if (task !== null) window.push(task.promise);
         }
@@ -148,19 +180,24 @@ export async function* applyMapAsync(items, fn, opts) {
     let nextId = 0;
     const inflight = new Map();
     const start = async () => {
-      const step = await items.next();
+      const step = await next();
       if (step.done) { sourceDone = true; return; }
+      if (rejected) return; // a task failed while this source pull awaited
       const id = nextId++;
-      inflight.set(id, Promise.resolve(fn(step.value, signal)).then(
+      const promise = Promise.resolve(fn(step.value, signal)).then(
         (value) => ({ id, value }),
         // the task's identity rides in an internal ENVELOPE, never on the
         // rejection value. Stamping the value mutated whatever the handler
         // threw: a frozen error became a different TypeError, a thrown
         // string came back boxed, an ordinary error grew a private
         // property, and a hostile proxy could break normalization outright.
-        (error) => { throw new TaskFailure(id, error); }));
+        (error) => { throw new TaskFailure(id, error); });
+      // Observe failures immediately, including while the next source
+      // pull is pending or downstream has stopped consuming the window.
+      promise.catch(taskFailed);
+      inflight.set(id, promise);
     };
-    while (!sourceDone && inflight.size < opts.concurrency) await start();
+    while (!sourceDone && !rejected && inflight.size < opts.concurrency) await start();
     while (inflight.size > 0) {
       let settled;
       try {
@@ -174,7 +211,7 @@ export async function* applyMapAsync(items, fn, opts) {
         throw err;
       }
       inflight.delete(settled.id);
-      if (!sourceDone) await start();
+      if (!sourceDone && !rejected) await start();
       yield settled.value;
     }
   }
@@ -191,7 +228,7 @@ export async function* applyMapAsync(items, fn, opts) {
       // itself succeeded. Composed as a rejection the `await` adopts,
       // because a `throw` here would be the very substitution this
       // avoids: it discards whatever completion the block was carrying.
-      await Promise.resolve(items.return(undefined)).then(undefined,
+      await closeSource().then(undefined,
         (cleanupError) => Promise.reject(failure === null
           ? cleanupError
           : new AggregateError([failure.reason, cleanupError],

package/src/contract/define.js

@@ -0,0 +1,282 @@
+//@ts-check
+/**
+ * @file `defineContract({ id?, version?, compat? }, operations)` — one
+ * `$contract` 0.1 document, deep-frozen, that `compileContract` takes
+ * unchanged.
+ *
+ * Two rules make the pen's document and its own public projection
+ * comparable member for member. First, the member ORDER is §12.1's, the
+ * normative one the revision hashes: root `$contract, id, version,
+ * compat, $defs, operations`; operation `kind, input, output, errors,
+ * policy, http, doc`; error `status, schema`; http `method, path, in,
+ * body, status, media`; `$defs` in first-reference order. Second, no
+ * DEFAULT is written: `describe()` marks a default inferred, and a pen
+ * that wrote them would turn every default into a declaration and move
+ * the revision for nothing.
+ *
+ * Every `named()` builder any operation reaches becomes one entry of the
+ * contract's own `$defs`, referenced `#/$defs/<name>` — the schema pen's
+ * hoisting walk over several roots instead of one. Nothing here imports
+ * `@jarenjs/contract`: the compiler stays the only judge of what the
+ * document means.
+ */
+
+import { cloneJson, deepFreeze, setObjectMember, isJsonObject } from '@jarenjs/core/object';
+
+import { LinqBuildError } from '../errors.js';
+import { describeValue, requireJson, requireNameMap } from '../json-boundary.js';
+import { isSchemaBuilder } from '../schema/brand.js';
+import { createHoist, emitInto, hoistedDefs } from '../schema/emit.js';
+import { http as httpBinding, isHttpBinding } from './http.js';
+import { checkOperation, emitPolicy, isOperation, KINDS, readErrors } from './operation.js';
+
+const CONTRACT_VERSION = '0.1';
+const HEAD_MEMBERS = ['id', 'version', 'compat'];
+
+/** `[A-Za-z_][A-Za-z0-9_-]*` — a contract id (§2.1). */
+const ID = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+/**
+ * One schema position — `input`, `output`, an error's `schema` — as the
+ * document carries it: a builder emitted into the shared `$defs`
+ * context, or a JSON Schema written by hand, copied.
+ * @param {any} value
+ * @param {any} ctx - the hoisting context
+ * @param {string} at
+ * @returns {any}
+ */
+function schemaAt(value, ctx, at) {
+  if (isSchemaBuilder(value)) return emitInto(value, ctx, at);
+  const json = requireJson(value, `the schema at ${at}`);
+  if (typeof json !== 'boolean' && !isJsonObject(json)) {
+    throw new LinqBuildError('JL0101',
+      `a schema is an object, true or false — got ${describeValue(value)}`, at);
+  }
+  return cloneJson(json);
+}
+
+/**
+ * The kind and spec of one declared operation: a `read()`/`command()`/
+ * `subscribe()` declaration, or the same members written by hand with a
+ * `kind`.
+ *
+ * The hand-written form is checked HERE by the same predicate the three
+ * declaration functions run, against its own position in the document.
+ * It is a second door into one emitter, and a door with no check behind
+ * it is worse than no door: an unknown member would be dropped in
+ * silence (the pen never sees it again, and the compiler never sees it
+ * at all), and a non-string `doc` would be written into a document
+ * `jaren-contract` refuses.
+ * @param {any} declared
+ * @param {string} at
+ * @returns {{ kind: string, spec: any }}
+ */
+function declarationOf(declared, at) {
+  if (isOperation(declared)) return declared;
+  if (!isJsonObject(declared)) {
+    throw new LinqBuildError('JL0101',
+      `an operation is read(), command() or subscribe() — got ${describeValue(declared)}`, at);
+  }
+  if (!KINDS.includes(declared.kind)) {
+    throw new LinqBuildError('JL0102',
+      `an operation kind is one of ${KINDS.join(', ')} — got ${describeValue(declared.kind)}`,
+      `${at}/kind`);
+  }
+  const { kind, ...spec } = declared;
+  checkOperation(kind, spec, at);
+  return { kind, spec };
+}
+
+/**
+ * Emit one operation, in §12.1's member order, declared members only.
+ * @param {string} id
+ * @param {any} declared
+ * @param {any} ctx - the hoisting context
+ * @returns {any}
+ */
+function emitOperation(id, declared, ctx) {
+  const at = `/operations/${id}`;
+  const { kind, spec } = declarationOf(declared, at);
+  const out = { kind };
+  if (spec.input !== undefined) out.input = schemaAt(spec.input, ctx, `${at}/input`);
+  out.output = schemaAt(spec.output, ctx, `${at}/output`);
+  if (spec.errors !== undefined) {
+    const declaredErrors = readErrors(spec.errors, `${at}/errors`);
+    const errors = {};
+    for (const [code, entry] of declaredErrors) {
+      const e = {};
+      if (entry.status !== undefined) e.status = entry.status;
+      if (entry.schema !== undefined) {
+        e.schema = schemaAt(entry.schema, ctx, `${at}/errors/${code}/schema`);
+      }
+      setObjectMember(errors, code, e);
+    }
+    out.errors = errors;
+  }
+  if (spec.policy !== undefined) out.policy = emitPolicy(spec.policy, `${at}/policy`);
+  if (spec.http !== undefined) {
+    out.http = isHttpBinding(spec.http) ? { ...spec.http } : { ...httpBinding(spec.http) };
+  }
+  if (spec.doc !== undefined) out.doc = spec.doc;
+  return out;
+}
+
+/**
+ * The contract under construction: frozen on creation, its document
+ * assembled once. `document` and `toJSON()` are the same deep-frozen
+ * `$contract` 0.1 JSON; the phantom the declarations carry is what
+ * `ContractOf<>` reads.
+ */
+export class Contract {
+  #document;
+
+  /**
+   * @param {any} document - the assembled document
+   */
+  constructor(document) {
+    this.#document = document;
+    Object.freeze(this);
+  }
+
+  /** The deep-frozen `$contract` 0.1 document. */
+  get document() { return this.#document; }
+
+  /** The document — what `JSON.stringify` writes. @returns {any} */
+  toJSON() { return this.#document; }
+}
+
+/**
+ * Write a `$contract` 0.1 document.
+ *
+ * @param {any} meta - `{ id?, version?, compat? }` (§2.1)
+ * @param {any} operations - operation id → `read()` / `command()` / `subscribe()`
+ * @returns {Contract} the contract, its `document` deep-frozen JSON
+ * @throws {LinqBuildError} `JL0101` a value the pen cannot spell;
+ *   `JL0102` a kind or path template the format reserves; `JL0103` two
+ *   distinct builders under one `$defs` name, or a `ref()` nothing defines
+ * @example
+ * const shop = defineContract({ id: 'shop', version: '5' }, {
+ *   'catalog.load': read({ output: Catalog, http: http({ method: 'GET', path: '/api/catalog' }) }),
+ * });
+ * compileContract(shop.document).ids;   // ['catalog.load']
+ */
+export function defineContract(meta, operations) {
+  if (!isJsonObject(meta)) {
+    throw new LinqBuildError('JL0101',
+      `defineContract() takes ({ id?, version?, compat? }, operations), got `
+      + `${describeValue(meta)} as its first argument`);
+  }
+  for (const key of Object.keys(meta)) {
+    if (!HEAD_MEMBERS.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `defineContract() does not take '${key}' — the head is ${HEAD_MEMBERS.join(', ')}; `
+        + 'everything else is an operation', `/${key}`);
+    }
+  }
+  if (meta.id !== undefined && (typeof meta.id !== 'string' || !ID.test(meta.id))) {
+    throw new LinqBuildError('JL0101',
+      `defineContract() id matches [A-Za-z_][A-Za-z0-9_-]*, got ${describeValue(meta.id)}`, '/id');
+  }
+  if (meta.version !== undefined && typeof meta.version !== 'string') {
+    throw new LinqBuildError('JL0101',
+      `defineContract() version is a string, got ${describeValue(meta.version)}`, '/version');
+  }
+  if (meta.compat !== undefined
+    && (!Array.isArray(meta.compat) || meta.compat.some((v) => typeof v !== 'string'))) {
+    throw new LinqBuildError('JL0101',
+      'defineContract() compat is an array of peer version strings', '/compat');
+  }
+  if (!isJsonObject(operations)) {
+    throw new LinqBuildError('JL0101',
+      `defineContract() operations is a plain object of id → operation, got `
+      + `${describeValue(operations)}`, '/operations');
+  }
+  requireNameMap(operations, 'defineContract() operations', '/operations');
+  const ids = Object.keys(operations);
+  if (ids.length === 0) {
+    throw new LinqBuildError('JL0101',
+      'defineContract() needs at least one operation', '/operations');
+  }
+
+  const ctx = createHoist();
+  const emitted = ids.map((id) => [id, emitOperation(id, operations[id], ctx)]);
+  const defs = hoistedDefs(ctx);
+
+  const out = { $contract: CONTRACT_VERSION };
+  if (meta.id !== undefined) out.id = meta.id;
+  if (meta.version !== undefined) out.version = meta.version;
+  if (meta.compat !== undefined) out.compat = meta.compat.slice();
+  if (defs !== null) out.$defs = defs;
+  const ops = {};
+  for (const [id, op] of emitted) setObjectMember(ops, id, op);
+  out.operations = ops;
+  return new Contract(deepFreeze(out));
+}
+
+/**
+ * Bind a contract client to the contract that types it. Identity at
+ * runtime: `invoke`, `url` and `subscribe` are narrowed by the pen's
+ * phantoms, and nothing is added to the binding.
+ * @template C
+ * @param {any} client - any contract client (local, http, port)
+ * @param {C} contract - the pen's contract; the type argument only
+ * @returns {any}
+ * @example
+ * const api = typedClient(openLocalClient(compileContract(shop.document), handlers), shop);
+ * const outcome = await api.invoke('product.save', { id: 1, revision: 4, product });
+ */
+export function typedClient(client, contract) {
+  void contract;
+  return client;
+}
+
+/**
+ * Bind an HTTP client to the contract that types it: `typedClient` plus
+ * `bytes` over the opaque operations. Identity at runtime — a local or
+ * port client carries no `bytes` and takes `typedClient`.
+ * @template C
+ * @template T
+ * @param {T} client - an `openHttpClient` client
+ * @param {C} contract - the pen's contract; the type argument only
+ * @returns {T}
+ * @example
+ * const api = typedHttpClient(openHttpClient(compileContract(shop.document), { baseUrl }), shop);
+ * const outcome = await api.bytes('image.bytes', { id: 3 });   // ok: { status, headers, media, body: ReadableStream }
+ */
+export function typedHttpClient(client, contract) {
+  void contract;
+  return client;
+}
+
+/**
+ * Bind a handler table to the contract it serves. Identity at runtime:
+ * the table is checked against the operation ids and each handler's
+ * input and output typed by the pen's phantoms.
+ * @template C
+ * @template H
+ * @param {C} contract - the pen's contract; the type argument only
+ * @param {H} handlers - operation id → handler
+ * @returns {H}
+ * @example
+ * serveHttp(compiled, typedHandlers(shop, { 'catalog.load': () => catalog }));
+ */
+export function typedHandlers(contract, handlers) {
+  void contract;
+  return handlers;
+}
+
+/**
+ * Bind `contractTools`' output to the contract that types it. Identity
+ * at runtime: each tool's `name` and `execute` argument are narrowed by
+ * the pen's phantoms.
+ * @template C
+ * @param {any} tools - what `contractTools(compiled, client)` answered
+ * @param {C} contract - the pen's contract; the type argument only
+ * @returns {any}
+ * @example
+ * for (const tool of typedTools(contractTools(compiled, client), shop)) toolbox.add(tool);
+ */
+export function typedTools(tools, contract) {
+  void contract;
+  return tools;
+}