@jarenjs/linq 0.56.0 → 0.67.0

package/src/async.js

@@ -26,10 +26,13 @@
  *    refuses (`JL0005`) and `explain()` reports the split.
  *  - a PROVIDER origin (`fromAsync(store.entity('Post'))`) runs nothing
  *    here: everything up to the first `mapAsync` is ONE document the
- *    provider executes whole — the terminal's wrapper included, exactly
- *    as the synchronous surface pushes it — and `execute` may answer a
- *    promise (D8); the residual after the split streams locally, and a
- *    `join` exists on this surface only inside that pushed document.
+ *    provider executes — a terminal's wrapper included, exactly as the
+ *    synchronous surface pushes it, `execute` answering a promise if it
+ *    must (D8). Iteration hands that document to the provider's CURSOR
+ *    when it offers one, so a `for await` pulls one row at a time from
+ *    an open statement and a `break` releases it; the residual after
+ *    the split streams locally, and a `join` exists on this surface
+ *    only inside that pushed document.
  *
  * Early termination CLOSES the source: every consumer is a
  * `for await … break` chain, and async generators propagate `return()`
@@ -437,10 +440,11 @@ export class AsyncSequence {
   }
 
   /** Barriers, the split, the relation hops the callbacks navigated,
-   * and — when representable — the document. Stages are named by the
-   * OPERATOR the caller wrote (`selectMany`, `orderByDescending`), and a
-   * `thenBy` is part of the `$orderby` barrier it extends, not a barrier
-   * of its own. */
+   * and — when representable — the document; plus `streaming` and
+   * `barrier`, what this surface's own execution does. Stages are named
+   * by the OPERATOR the caller wrote (`selectMany`, `orderByDescending`),
+   * and a `thenBy` is part of the `$orderby` barrier it extends, not a
+   * barrier of its own. */
   explain() {
     const firstMap = this.#stages.findIndex((s) => s.kind === 'mapAsync');
     // over a provider nothing before the split materialises HERE — the
@@ -455,7 +459,19 @@ export class AsyncSequence {
         barriers.push({ operator: stage.name ?? stage.kind, reason: BARRIERS[stage.kind] });
       }
     }
-    const out = { barriers, hops: this.#hops(), bindings: this.#externals().values };
+    // what THIS surface does with the item stream: one item at a time,
+    // or a buffer at the first local barrier. Over a provider the pushed
+    // document's own class — a set residual, an unbindable external — is
+    // the provider's to report: `explain(document, { externals: bindings })`
+    // on the source answers it, and its cursor carries the same answer
+    const first = barriers[0];
+    const out = {
+      barriers,
+      streaming: first === undefined ? 'row' : 'buffered',
+      barrier: first === undefined ? null : { construct: first.operator, reason: first.reason },
+      hops: this.#hops(),
+      bindings: this.#externals().values,
+    };
     if (firstMap < 0) {
       out.document = this.toDocument();
     }
@@ -487,7 +503,7 @@ export class AsyncSequence {
       // runs whole; the residual continues locally over its rows
       const firstMap = stages.findIndex((s) => s.kind === 'mapAsync');
       i = firstMap < 0 ? stages.length : firstMap;
-      stream = arrayStream(await this.#pushWindow('toArray', undefined, stages.slice(0, i)));
+      stream = this.#providerStream(stages.slice(0, i), values);
     }
     else {
       stream = this.#origin.iterate();
@@ -522,6 +538,33 @@ export class AsyncSequence {
     yield* iterateAndClose(stream);
   }
 
+  /**
+   * The pushed window as a STREAM. A provider that offers the cursor
+   * protocol (`cursor(document, options)` — the store's entity sets and
+   * collections do) is handed the unwrapped document and answers one
+   * item per pull from an open statement; the generator's `for await`
+   * releases that statement on break, throw and exhaustion alike,
+   * exactly once. A provider without one keeps the element window it
+   * always had: the `toArray`-wrapped document run whole, its array
+   * iterated — a materialisation, which is what such a provider can do.
+   * @param {readonly any[]} stages - the stages up to the split
+   * @param {Record<string, any>} values - the bound externals
+   * @returns {AsyncIterator<any>}
+   */
+  #providerStream(stages, values) {
+    const source = this.#origin.source;
+    if (typeof source.cursor === 'function') {
+      return source.cursor(this.#documentOf(stages), { externals: values });
+    }
+    return this.#materializedWindow(stages);
+  }
+
+  /** The legacy element window, iterated: one `toArray` push, run whole.
+   * @param {readonly any[]} stages */
+  async* #materializedWindow(stages) {
+    yield* await this.#pushWindow('toArray', undefined, stages);
+  }
+
   /** @param {AsyncIterator<any>} stream @param {any} stage @param {any} values */
   #applyStreamStage(stream, stage, values) {
     const self = this;
@@ -614,7 +657,12 @@ export class AsyncSequence {
     }
   }
 
+  /** The whole result as one array. Over a provider with no `mapAsync`
+   * this is ONE pushed window — the terminal asked for the array, so the
+   * store answers it in one statement rather than one row at a time;
+   * everywhere else it drains the item stream. */
   async toArray() {
+    if (this.#pushable()) return this.#pushWindow('toArray');
     return collect(this[Symbol.asyncIterator]());
   }
 

package/src/concurrency.js

@@ -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)) {
@@ -122,14 +134,29 @@ export async function* applyMapAsync(items, fn, opts) {
     // 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(() => { rejected = true; controller.abort(); });
+      promise.catch(taskFailed);
       return { promise };
     };
     if (opts.ordered) {
@@ -153,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 {
@@ -179,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;
     }
   }
@@ -196,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

@@ -21,7 +21,7 @@
  * document means.
  */
 
-import { cloneJson, deepFreeze, setObjectMember } from '@jarenjs/core/object';
+import { cloneJson, deepFreeze, setObjectMember, isJsonObject } from '@jarenjs/core/object';
 
 import { LinqBuildError } from '../errors.js';
 import { describeValue, requireJson, requireNameMap } from '../json-boundary.js';
@@ -36,11 +36,6 @@ 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_-]*$/;
 
-/** @param {any} value */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /**
  * One schema position — `input`, `output`, an error's `schema` — as the
  * document carries it: a builder emitted into the shared `$defs`
@@ -53,7 +48,7 @@ function isPlainObject(value) {
 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' && !isPlainObject(json)) {
+  if (typeof json !== 'boolean' && !isJsonObject(json)) {
     throw new LinqBuildError('JL0101',
       `a schema is an object, true or false — got ${describeValue(value)}`, at);
   }
@@ -78,7 +73,7 @@ function schemaAt(value, ctx, at) {
  */
 function declarationOf(declared, at) {
   if (isOperation(declared)) return declared;
-  if (!isPlainObject(declared)) {
+  if (!isJsonObject(declared)) {
     throw new LinqBuildError('JL0101',
       `an operation is read(), command() or subscribe() — got ${describeValue(declared)}`, at);
   }
@@ -166,7 +161,7 @@ export class Contract {
  * compileContract(shop.document).ids;   // ['catalog.load']
  */
 export function defineContract(meta, operations) {
-  if (!isPlainObject(meta)) {
+  if (!isJsonObject(meta)) {
     throw new LinqBuildError('JL0101',
       `defineContract() takes ({ id?, version?, compat? }, operations), got `
       + `${describeValue(meta)} as its first argument`);
@@ -191,7 +186,7 @@ export function defineContract(meta, operations) {
     throw new LinqBuildError('JL0101',
       'defineContract() compat is an array of peer version strings', '/compat');
   }
-  if (!isPlainObject(operations)) {
+  if (!isJsonObject(operations)) {
     throw new LinqBuildError('JL0101',
       `defineContract() operations is a plain object of id → operation, got `
       + `${describeValue(operations)}`, '/operations');
@@ -235,6 +230,24 @@ export function typedClient(client, 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

package/src/contract/index.js

@@ -11,13 +11,13 @@
  * earlier than the compiler's `JC0008`), `error()` one entry of an
  * operation's `errors`.
  *
- * The three identity wrappers — `typedClient`, `typedHandlers`,
- * `typedTools` — carry the inferred `Operations` type onto a client, a
- * handler table and an AI toolbox without running the TypeScript
- * projection. The document is the deliverable; nothing here imports
+ * The identity wrappers — `typedClient`, `typedHttpClient`,
+ * `typedHandlers`, `typedTools` — carry the inferred `Operations` type
+ * onto a client (an HTTP one with its byte method), a handler table and
+ * an AI toolbox without running the TypeScript projection. The document is the deliverable; nothing here imports
  * `@jarenjs/contract` or an engine.
  */
 
-export { defineContract, typedClient, typedHandlers, typedTools, Contract } from './define.js';
+export { defineContract, typedClient, typedHttpClient, typedHandlers, typedTools, Contract } from './define.js';
 export { read, command, subscribe, error } from './operation.js';
 export { http } from './http.js';

package/src/contract/operation.js

@@ -20,6 +20,7 @@
  * nothing.
  */
 
+import { isJsonObject } from '@jarenjs/core/object';
 import { LinqBuildError } from '../errors.js';
 import { describeValue } from '../json-boundary.js';
 
@@ -57,11 +58,6 @@ export const POLICY_VALUES = Object.freeze({
 /** An error code: `^[a-z][a-z0-9-]*$` (§3's table). */
 const CODE = /^[a-z][a-z0-9-]*$/;
 
-/** @param {any} value */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /**
  * A member set the pen knows, or `JL0101` naming the one it does not.
  * @param {any} spec
@@ -104,7 +100,7 @@ function policyMember(member, value, at) {
     return value;
   }
   if (member === 'limits') {
-    if (!isPlainObject(value)) {
+    if (!isJsonObject(value)) {
       throw new LinqBuildError('JL0101', 'policy.limits is { maxBodyBytes }', at);
     }
     closedTo(value, ['maxBodyBytes'], 'policy.limits', at);
@@ -116,7 +112,7 @@ function policyMember(member, value, at) {
     return { maxBodyBytes: value.maxBodyBytes };
   }
   if (member === 'errors') {
-    if (!isPlainObject(value)) {
+    if (!isJsonObject(value)) {
       throw new LinqBuildError('JL0101', 'policy.errors is { details }', at);
     }
     closedTo(value, ['details'], 'policy.errors', at);
@@ -128,7 +124,7 @@ function policyMember(member, value, at) {
     return { details: value.details };
   }
   if (member === 'retry') {
-    if (!isPlainObject(value)) {
+    if (!isJsonObject(value)) {
       throw new LinqBuildError('JL0101', 'policy.retry is { max, on }', at);
     }
     closedTo(value, ['max', 'on'], 'policy.retry', at);
@@ -144,7 +140,7 @@ function policyMember(member, value, at) {
     return { max: value.max, on: value.on.slice() };
   }
   // stream
-  if (!isPlainObject(value)) {
+  if (!isJsonObject(value)) {
     throw new LinqBuildError('JL0101', 'policy.stream is { resume?, heartbeatMs?, maxPatchBytes? }', at);
   }
   closedTo(value, ['resume', 'heartbeatMs', 'maxPatchBytes'], 'policy.stream', at);
@@ -184,7 +180,7 @@ function policyMember(member, value, at) {
  * @returns {any}
  */
 export function emitPolicy(policy, at) {
-  if (!isPlainObject(policy)) {
+  if (!isJsonObject(policy)) {
     throw new LinqBuildError('JL0101',
       `policy is a plain object of the members CONTRACT-FORMAT §3.1 declares, got `
       + `${describeValue(policy)}`, at);
@@ -210,7 +206,7 @@ export function emitPolicy(policy, at) {
  * error({ status: 409, schema: Conflict });
  */
 export function error(spec = {}) {
-  if (!isPlainObject(spec)) {
+  if (!isJsonObject(spec)) {
     throw new LinqBuildError('JL0101',
       `error() takes { status?, schema? }, got ${describeValue(spec)}`);
   }
@@ -235,7 +231,7 @@ export function error(spec = {}) {
  * @returns {[string, any][]} code → `{ status?, schema? }`, in declaration order
  */
 export function readErrors(errors, at) {
-  if (!isPlainObject(errors)) {
+  if (!isJsonObject(errors)) {
     throw new LinqBuildError('JL0101',
       `errors is a plain object of code → error(), got ${describeValue(errors)}`, at);
   }
@@ -245,7 +241,7 @@ export function readErrors(errors, at) {
         `an error code matches ^[a-z][a-z0-9-]*$, got '${code}'`, `${at}/${code}`);
     }
     const declared = errors[code];
-    if (!isPlainObject(declared)) {
+    if (!isJsonObject(declared)) {
       throw new LinqBuildError('JL0101',
         `errors.${code} is error({ status?, schema? }), got ${describeValue(declared)}`,
         `${at}/${code}`);
@@ -270,7 +266,7 @@ export function readErrors(errors, at) {
  */
 export function checkOperation(kind, spec, at) {
   const base = at ?? '';
-  if (!isPlainObject(spec)) {
+  if (!isJsonObject(spec)) {
     throw new LinqBuildError('JL0101',
       `${kind}() takes { input?, output, errors?, policy?, http?, doc? }, got `
       + `${describeValue(spec)}`, at);

package/src/db/handle.js

@@ -56,6 +56,9 @@ export function createEntityHandle(store, name) {
   const members = { ...set };
   chainStart(set, members);
   members.include = (pick, spec) => new Graph(set, name).include(pick, spec);
+  // the graph with nothing included: the root clauses, the keyset and
+  // the page over the rows alone
+  members.graph = () => new Graph(set, name);
   members.link = (own, member, target) => {
     requireMembership(set.relations, name, member, 'link');
     set.link(own, member, target);

package/src/db/include.js

@@ -10,9 +10,10 @@
  * `explainLoad(spec)`: the one-statement guarantee is the store's. A
  * spec is plain JSON in a fixed member order (`where, orderBy, take,
  * skip, after, maxDepth, include` at the root; `where, orderBy, take,
- * skip, count, include` in an include — a keyset cursor paginates the
- * root alone), so one graph is one document; `toJSON()` is that
- * document, as a pen's is.
+ * skip, count, maxRows, maxBytes, include` in an include — a keyset
+ * cursor paginates the root alone), so one graph is one document;
+ * `toJSON()` is that document, as a pen's is. `cursor()` is
+ * `loadCursor(spec)`: one root graph per pull.
  */
 
 import { deepFreeze, setObjectMember } from '@jarenjs/core/object';
@@ -23,7 +24,7 @@ import { requireJson, describeValue } from '../json-boundary.js';
 
 const NO_PARAMS = new Set();
 const ROOT_KEYS = ['where', 'orderBy', 'take', 'skip', 'after', 'maxDepth', 'include'];
-const INCLUDE_KEYS = ['where', 'orderBy', 'take', 'skip', 'count', 'include'];
+const INCLUDE_KEYS = ['where', 'orderBy', 'take', 'skip', 'count', 'maxRows', 'maxBytes', 'include'];
 /** A member path over the row: the shorthand or the bracketed spelling. */
 const MEMBER_PATH = /^\$it(?:\.([A-Za-z_$][\w$]*)|\['((?:[^'\\]|\\.)*)'\])$/;
 
@@ -158,6 +159,12 @@ function lowerInclude(spec, entityName, relationsOf, path) {
     if (spec.count !== true) throw new LinqBuildError('JL0101', `the include spec at ${at}: count takes true`);
     out.count = true;
   }
+  for (const key of ['maxRows', 'maxBytes']) {
+    // the per-root bound (MODEL-FORMAT §10.4); `Infinity` is the spelled
+    // unbounded case, and its JSON form is `null`
+    if (spec[key] === undefined) continue;
+    out[key] = spec[key] === Infinity ? null : requireJson(spec[key], `${at} ${key}`);
+  }
   if (spec.include !== undefined) out.include = lowerIncludes(spec.include, entityName, relationsOf, path);
   return out;
 }
@@ -276,7 +283,9 @@ export class Graph {
   /** @param {number} count */
   skip(count) { return this.#with({ skip: requireJson(count, 'skip()') }); }
 
-  /** The keyset cursor (§10.5). @param {string | number} cursor */
+  /** The keyset continuation (§10.5): the `{ order, keys, key }` value a
+   * page emitted — a bare unique-column value is the single-column form.
+   * @param {any} cursor */
   after(cursor) { return this.#with({ after: requireJson(cursor, 'after()') }); }
 
   /** The include depth bound (§10.4). @param {number} depth */
@@ -309,6 +318,32 @@ export class Graph {
     return this.#tracking ? this.#set.load(spec) : this.#set.asNoTracking().load(spec);
   }
 
+  /**
+   * `loadCursor(spec, options)` — the store's graph cursor: one root
+   * graph per pull, its includes attached and bounded, from the same one
+   * statement; `return()` releases it. Untracked unless `tracking: true`
+   * is spelled per call — a snapshot per yielded root is a unit of work
+   * that grows with the result.
+   * @param {{ signal?: AbortSignal, tracking?: boolean }} [options]
+   */
+  cursor(options) {
+    return this.#set.loadCursor(this.toSpec(), options);
+  }
+
+  /**
+   * `page(spec, options)` — the store's bounded page over the composite
+   * keyset (§10.5): `{ items, continuation, hasMore, snapshot }`, never
+   * more than `limit` roots or `maxBytes` serialised bytes, the
+   * continuation unsigned and structural. Untracked unless `tracking:
+   * true`.
+   * @param {{ limit?: number, after?: any, maxBytes?: number,
+   *   consistency?: 'live' | 'snapshot', signal?: AbortSignal,
+   *   tracking?: boolean }} [options]
+   */
+  page(options) {
+    return this.#set.page(this.toSpec(), options);
+  }
+
   /** `explainLoad(spec)` — the SQL, the includes, the pagination strategy. */
   explain() {
     return this.#set.explainLoad(this.toSpec());

package/src/db/index.js

@@ -14,6 +14,12 @@
  * duplicates no algorithm — `include` emits the spec the store runs,
  * membership is the store's own `link`/`unlink`, `live` is the store's
  * registration — and every read is one an `explain()` can name.
+ * `createDbLedger` is the contract ledger over a declared collection of
+ * the client's store, through that same surface: the durable idempotency
+ * ledger a host was left to write, with no edge from `@jarenjs/contract`
+ * to a store (DB-CLIENT.md §2.6).
  */
 
 export { open, defaultValidator } from './open.js';
+export { createDbLedger } from './ledger.js';
+export { defineReplication } from './replication.js';