@jarenjs/linq 0.34.0

package/src/concurrency.js

@@ -0,0 +1,213 @@
+//@ts-check
+/**
+ * @file `mapAsync` — the ONE explicit bounded-concurrency boundary
+ * (LINQ-FORMAT.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.
+ *
+ * `concurrency` is REQUIRED — the unbounded default is how libraries
+ * like this take down a downstream service. `mode` reuses the
+ * `createTaskEffect` vocabulary (`parallel`/`concat`/`switch`/
+ * `exhaust`) so a reader who knows one knows the other. Failure is
+ * fail-closed: the first rejection aborts every in-flight callback and
+ * the source, the `compileDag` discipline.
+ */
+
+import { LinqBuildError } from './errors.js';
+
+const MODES = new Set(['parallel', 'concat', 'switch', 'exhaust']);
+
+/**
+ * Validate a mapAsync options bag at BUILD time.
+ * @param {any} options
+ * @returns {{ concurrency: number, mode: string, ordered: boolean }}
+ */
+export function normalizeMapAsyncOptions(options) {
+  if (options === null || typeof options !== 'object'
+    || !Number.isInteger(options.concurrency) || options.concurrency < 1) {
+    throw new LinqBuildError('JL0005',
+      'mapAsync requires { concurrency: <positive integer> } — an unbounded default is a denial of service waiting for a slow downstream');
+  }
+  const mode = options.mode ?? 'parallel';
+  if (!MODES.has(mode)) {
+    throw new LinqBuildError('JL0005',
+      `mapAsync mode must be one of parallel|concat|switch|exhaust, got '${mode}'`);
+  }
+  return { concurrency: options.concurrency, mode, ordered: options.ordered !== false };
+}
+
+/**
+ * Apply one mapAsync stage over an async item stream. The returned
+ * generator owns an AbortController: early termination (a downstream
+ * `break`/`return`) and the first rejection both abort every in-flight
+ * callback; the rejection then rethrows (fail closed, first failure
+ * wins).
+ * @param {AsyncIterator<any>} items
+ * @param {(item: any, signal: AbortSignal) => any} fn
+ * @param {{ concurrency: number, mode: string, ordered: boolean }} opts
+ * @returns {AsyncGenerator<any>}
+ */
+export async function* applyMapAsync(items, fn, opts) {
+  const controller = new AbortController();
+  const { signal } = controller;
+  /** The pipeline's own failure, so source cleanup cannot displace it.
+   * @type {{ reason: any } | null} */
+  let failure = null;
+
+  try {
+    if (opts.mode === 'concat' || (opts.mode === 'parallel' && opts.concurrency === 1)) {
+      // strictly sequential; `concat` ignores the window by definition,
+      // and parallel-of-one degenerates to it — but `switch`/`exhaust`
+      // keep their racing semantics even at one in-flight task
+      for (;;) {
+        const step = await items.next();
+        if (step.done) return;
+        yield await fn(step.value, signal);
+        if (signal.aborted) return;
+      }
+    }
+
+    if (opts.mode === 'switch' || opts.mode === 'exhaust') {
+      // one in-flight task, with the source pulled EAGERLY: the next
+      // item races the running work. `switch` supersedes the task when
+      // a newer item wins the race (the task's own signal aborts and
+      // its result is discarded); `exhaust` drops the newer item.
+      const PULL = Symbol('pull');
+      let pending = items.next().then((step) => ({ [PULL]: step }));
+      let task = null; // { promise, abort }
+      let exhausted = false;
+      while (!exhausted || task !== null) {
+        const race = task === null
+          ? [pending]
+          : [pending, task.promise.then((value) => ({ value }))];
+        const won = await Promise.race(exhausted && task !== null ? [race[1]] : race);
+        if (won !== undefined && PULL in won) {
+          const step = won[PULL];
+          if (step.done) {
+            exhausted = true;
+            pending = new Promise(() => {}); // never resolves again
+            continue;
+          }
+          pending = items.next().then((s) => ({ [PULL]: s }));
+          if (task !== null) {
+            if (opts.mode === 'exhaust') continue; // drop while busy
+            task.abort.abort(); // switch: supersede, discard
+            task.promise.catch(() => {}); // superseded rejections are moot
+            task = null;
+          }
+          const abort = new AbortController();
+          const onOuter = () => abort.abort();
+          signal.addEventListener('abort', onOuter, { once: true });
+          const current = {
+            abort,
+            promise: Promise.resolve(fn(step.value, abort.signal))
+              .finally(() => signal.removeEventListener('abort', onOuter)),
+          };
+          task = current;
+          continue;
+        }
+        // the task settled while still current
+        const { value } = /** @type {{ value: any }} */ (won);
+        task = null;
+        yield value;
+      }
+      return;
+    }
+
+    // parallel: a sliding window of `concurrency` in-flight tasks
+    const window = [];
+    let sourceDone = false;
+    const pull = async () => {
+      const step = await items.next();
+      if (step.done) { sourceDone = true; return null; }
+      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(() => {});
+      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) {
+        const task = await pull();
+        if (task !== null) window.push(task.promise);
+      }
+      while (window.length > 0) {
+        const value = await window.shift();
+        if (!sourceDone) {
+          const task = await pull();
+          if (task !== null) window.push(task.promise);
+        }
+        yield value;
+      }
+      return;
+    }
+    // unordered: yield on completion
+    let nextId = 0;
+    const inflight = new Map();
+    const start = async () => {
+      const step = await items.next();
+      if (step.done) { sourceDone = true; return; }
+      const id = nextId++;
+      inflight.set(id, 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); }));
+    };
+    while (!sourceDone && inflight.size < opts.concurrency) await start();
+    while (inflight.size > 0) {
+      let settled;
+      try {
+        settled = await Promise.race(inflight.values());
+      }
+      catch (err) {
+        if (err instanceof TaskFailure) {
+          inflight.delete(err.id);
+          throw err.reason; // the ORIGINAL value, unmodified
+        }
+        throw err;
+      }
+      inflight.delete(settled.id);
+      if (!sourceDone) await start();
+      yield settled.value;
+    }
+  }
+  catch (err) {
+    failure = { reason: err };
+    throw err;
+  }
+  finally {
+    controller.abort(); // early termination aborts in-flight work
+    if (typeof items.return === 'function') {
+      // The TASK's failure is the primary one — it is why the caller is
+      // here — so a failing close travels ALONGSIDE it as an aggregate
+      // rather than replacing it, and stands alone only when the pipeline
+      // 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,
+        (cleanupError) => Promise.reject(failure === null
+          ? cleanupError
+          : new AggregateError([failure.reason, cleanupError],
+            'mapAsync failed, and closing the source failed too')));
+    }
+  }
+}
+
+/**
+ * The internal envelope carrying which in-flight task rejected, so the
+ * rejection VALUE never has to be touched to find out.
+ */
+class TaskFailure {
+  /** @param {number} id @param {any} reason */
+  constructor(id, reason) {
+    this.id = id;
+    this.reason = reason;
+  }
+}

package/src/document.js

@@ -0,0 +1,212 @@
+//@ts-check
+/**
+ * @file Chain → document emission: the stage list a `Sequence` carries
+ * folds into ONE Jaren query document (QUERY-FORMAT.md). The item
+ * binding is always named `it` — nested phrases shadow it legally, the
+ * emitted JSON stays hand-readable, and every captured expression
+ * references `$it…` regardless of chain depth.
+ *
+ * Folding rule: consecutive stages join one FLWOR phrase while their
+ * clause slots stay free AND the chain order agrees with the phrase's
+ * fixed semantic order (`$where` → `$groupby` → `$orderby` → `$return`,
+ * QUERY-FORMAT §6.1). A stage that would violate either closes the
+ * phrase (default `$return: "$it"`) and opens a new segment iterating
+ * the closed one — `orderBy().where()` really does sort first and
+ * filter second, exactly as written.
+ *
+ * Empty clause slots carry {@link EMPTY}, never `null`. `null` is a
+ * legal query expression — `where(() => null)` filters everything out,
+ * `select(() => null)` projects nulls, `groupBy(() => null)` is one
+ * null-keyed group — so a slot that used `null` for "nothing here" could
+ * not tell an absent clause from a null-valued one, and silently emitted
+ * the document WITHOUT the clause. Every such query then returned its
+ * unfiltered, unprojected source.
+ */
+
+import { LinqBuildError } from './errors.js';
+
+/** The fixed clause order a phrase may fill left-to-right. */
+const SLOT_ORDER = ['where', 'groupby', 'orderby', 'return'];
+
+/** The "this clause slot is unfilled" sentinel: a fresh object, so no
+ * value a caller can express is ever mistaken for it. */
+const EMPTY = Symbol('linq.emptySlot');
+
+/** An open FLWOR phrase under construction. */
+function openPhrase(source) {
+  return {
+    source, fold: EMPTY, where: EMPTY, groupby: EMPTY, orderby: EMPTY, ret: EMPTY,
+  };
+}
+
+/** Whether every slot AFTER `slot` is still empty — chain order must
+ * agree with the phrase's fixed semantic order. */
+function laterSlotsFree(phrase, slot) {
+  for (let i = SLOT_ORDER.indexOf(slot) + 1; i < SLOT_ORDER.length; i++) {
+    const later = SLOT_ORDER[i];
+    if (phrase[later === 'return' ? 'ret' : later] !== EMPTY) return false;
+  }
+  return true;
+}
+
+/** Whether `slot` may be filled fresh (itself empty, order respected). */
+function slotFree(phrase, slot) {
+  return phrase[slot === 'return' ? 'ret' : slot] === EMPTY
+    && laterSlotsFree(phrase, slot);
+}
+
+/** Close a phrase into a query expression. */
+function closePhrase(phrase) {
+  const untouched = phrase.fold === EMPTY && phrase.where === EMPTY
+    && phrase.groupby === EMPTY && phrase.orderby === EMPTY && phrase.ret === EMPTY;
+  if (untouched) return phrase.source;
+  const doc = {};
+  if (phrase.fold !== EMPTY) doc.$fold = { acc: phrase.fold };
+  doc.$for = { it: phrase.source };
+  if (phrase.where !== EMPTY) doc.$where = phrase.where;
+  if (phrase.groupby !== EMPTY) doc.$groupby = { g: phrase.groupby };
+  if (phrase.orderby !== EMPTY) {
+    doc.$orderby = phrase.orderby.length === 1 ? phrase.orderby[0] : phrase.orderby;
+  }
+  // the default group shape: an object member takes exactly one item,
+  // so the member sequence packs into an array constructor and an
+  // empty grouping key reads as null
+  doc.$return = phrase.ret !== EMPTY ? phrase.ret : (phrase.groupby !== EMPTY
+    ? { key: { $default: ['$g', null] }, items: ['$it'] }
+    : '$it');
+  return doc;
+}
+
+/** Combine two predicates. */
+const andJoin = (a, b) => (a === EMPTY ? b : { $and: [a, b] });
+
+/**
+ * Emit the query document for a stage list.
+ * @param {any} root - the root expression the items come from
+ *   (`'$[*]'` for a plain source; a stripped document for
+ *   `fromDocument`)
+ * @param {readonly any[]} stages
+ * @returns {any} the emitted query document (plain JSON)
+ */
+export function emitDocument(root, stages) {
+  let phrase = openPhrase(root);
+  /** Close the open phrase and reopen over its result. */
+  const reseat = () => { phrase = openPhrase(closePhrase(phrase)); };
+
+  for (const stage of stages) {
+    switch (stage.kind) {
+      case 'where':
+        // a second where in the same phrase COMBINES ($and); only a
+        // later-slot occupant (orderby/groupby/return) forces a segment
+        if (!laterSlotsFree(phrase, 'where')) reseat();
+        phrase.where = andJoin(phrase.where, stage.predicate);
+        break;
+      case 'select': // also selectMany: a multi-item projection flattens
+        if (!slotFree(phrase, 'return')) reseat();
+        phrase.ret = stage.projection;
+        reseat(); // later operators see projected items
+        break;
+      case 'orderBy':
+        if (!slotFree(phrase, 'orderby')) reseat();
+        phrase.orderby = [stage.spec];
+        break;
+      case 'thenBy': {
+        if (phrase.orderby === EMPTY || phrase.ret !== EMPTY) {
+          throw new LinqBuildError('JL0005',
+            'thenBy/thenByDescending must directly follow orderBy/orderByDescending');
+        }
+        phrase.orderby = [...phrase.orderby, stage.spec];
+        break;
+      }
+      case 'groupBy':
+        if (!slotFree(phrase, 'groupby')) reseat();
+        phrase.groupby = stage.key;
+        reseat(); // later operators see { key, items } groups
+        break;
+      case 'join':
+        // the hash-join shape: nested bindings + equality (the engine's
+        // compile-time rewrite turns exactly this into a hash probe)
+        phrase = openPhrase({
+          $for: { it: closePhrase(phrase), it2: stage.inner },
+          $where: stage.on,
+          $return: stage.result,
+        });
+        break;
+      case 'aggregate': {
+        // the seeded fold: its own phrase, closed immediately — the
+        // result is one accumulated value, not a tuple stream
+        if (phrase.fold !== EMPTY || phrase.where !== EMPTY || phrase.groupby !== EMPTY
+          || phrase.orderby !== EMPTY || phrase.ret !== EMPTY) reseat();
+        phrase.fold = stage.seed;
+        phrase.ret = stage.step;
+        reseat();
+        break;
+      }
+      case 'skip':
+        phrase = openPhrase({ $subsequence: [closePhrase(phrase), stage.count] });
+        break;
+      case 'take':
+        phrase = openPhrase({ $subsequence: [closePhrase(phrase), 0, stage.count] });
+        break;
+      case 'distinct':
+        phrase = openPhrase({ $distinct: closePhrase(phrase) });
+        break;
+      case 'reverse':
+        phrase = openPhrase({ $reverse: closePhrase(phrase) });
+        break;
+      case 'concat':
+        phrase = openPhrase({ $seq: [closePhrase(phrase), stage.other] });
+        break;
+      case 'defaultIfEmpty':
+        phrase = openPhrase({ $default: [closePhrase(phrase), stage.fallback] });
+        break;
+      case 'ofType': // keep only items the schema accepts
+        // the second $valid argument is a SCHEMA literal — verbatim by
+        // the registry's `schema` parameter kind, never an expression
+        phrase = openPhrase(closePhrase(phrase));
+        phrase.where = { $valid: ['$it', stage.schema] };
+        break;
+      case 'cast': // assert every item against the schema
+        phrase = openPhrase(closePhrase(phrase));
+        phrase.ret = { $assert: ['$it', stage.schema] };
+        break;
+      /* c8 ignore next 2 -- stages are produced by Sequence alone */
+      default:
+        throw new LinqBuildError('JL0005', `unknown stage kind '${stage.kind}'`);
+    }
+  }
+  return closePhrase(phrase);
+}
+
+/**
+ * Wrap the emitted expression per terminal so results extract without
+ * ambiguity: the engine maps a result to `undefined | item | array of
+ * items`, and a SINGLE item that is itself an array would be
+ * indistinguishable from two items — so every element-window terminal
+ * emits `[window]` (one array item, Rule 3 constructor: elements
+ * flatten) and reads its elements.
+ * @param {any} expr - the emitted chain expression
+ * @param {string} terminal
+ * @param {readonly any[]} [args]
+ * @returns {any}
+ */
+export function wrapTerminal(expr, terminal, args = []) {
+  switch (terminal) {
+    case 'toArray': return [expr];
+    case 'first': return [{ $subsequence: [expr, 0, 1] }];
+    case 'single': return [{ $subsequence: [expr, 0, 2] }];
+    case 'last': return [{ $subsequence: [{ $reverse: expr }, 0, 1] }];
+    case 'elementAt': return [{ $subsequence: [expr, args[0], 1] }];
+    case 'count': return { $count: expr };
+    case 'sum': return { $sum: expr };
+    case 'average': return { $avg: expr };
+    case 'min': return { $min: expr };
+    case 'max': return { $max: expr };
+    case 'exists': return { $exists: expr };
+    case 'some': return { $some: { it: expr }, $satisfies: args[0] };
+    case 'every': return { $every: { it: expr }, $satisfies: args[0] };
+    /* c8 ignore next 2 -- terminals are produced by Sequence alone */
+    default:
+      throw new LinqBuildError('JL0005', `unknown terminal '${terminal}'`);
+  }
+}

package/src/errors.js

@@ -0,0 +1,94 @@
+//@ts-check
+/**
+ * @file Error types for @jarenjs/linq, built on `@jarenjs/core`'s coded
+ * contract: every failure carries a stable `code` (JL0xxx build, JL2xxx
+ * runtime), a bare `reason`, a composed `message`, and — where a
+ * document position exists — a `docPath`. The normative table lives in
+ * docs/LINQ-FORMAT.md §9, proven in sync with `LINQ_CODES` below by a
+ * test.
+ */
+
+import { CodedError } from '@jarenjs/core/errors';
+
+/**
+ * The runtime code table (the `CSV_CODES` shape): one entry per code
+ * this package can raise, proven in sync with LINQ-FORMAT.md §9's
+ * normative table by a test.
+ */
+export const LINQ_CODES = Object.freeze({
+  JL0001: 'from() received neither an iterable nor a provider',
+  JL0002: 'an expression proxy escaped its capture callback',
+  JL0003: 'ofType/cast need an injected compileTypeTest',
+  JL0004: 'an undeclared or reserved parameter name was used',
+  JL0005: 'an operator was used invalidly at build time',
+  JL0006: 'an unsupported operator was invoked',
+  JL2001: 'first/single found no element',
+  JL2002: 'single found more than one element',
+  JL2003: 'elementAt is out of range',
+  JL2004: 'an asynchronous provider cannot back the synchronous surface',
+});
+
+/**
+ * A defect in how the query was BUILT — raised while capturing
+ * expressions or emitting the document, before anything runs. Codes:
+ *
+ *  - `JL0001` — `from()`/`fromDocument()` received a source that is
+ *    neither an iterable nor a provider (`execute` duck)
+ *  - `JL0002` — an expression proxy escaped the callback it was handed
+ *    to (stored and reused across captures); the emitted document
+ *    would be nonsense, so the build fails instead
+ *  - `JL0003` — `ofType`/`cast` compile schema operators, which need
+ *    the injected `compileTypeTest` hook (`from(src, {
+ *    compileTypeTest })`, e.g. `createTypeTestCompiler()` from
+ *    `@jarenjs/validate/query`)
+ *  - `JL0004` — a parameter was referenced without being declared via
+ *    `.params({...})`, or a declared name is reserved (`it`, `acc`,
+ *    `g` — the document's own binding names)
+ *  - `JL0005` — an operator was used invalidly at build time (`thenBy`
+ *    without `orderBy`, `all()` off a plain path, a negative
+ *    `skip`/`take`, a value that cannot embed in a document)
+ *  - `JL0006` — an operator the mapping table records as
+ *    `unsupported` was invoked (`zip`); the table names the reason
+ */
+export class LinqBuildError extends CodedError {
+  /**
+   * @param {string} code
+   * @param {string} reason - The bare reason; `message` is composed per
+   *   the coded contract.
+   * @param {string} [docPath] - JSON Pointer into the emitted query
+   *   document, where one exists.
+   * @param {Error} [cause]
+   */
+  constructor(code, reason, docPath, cause) {
+    super('LinqBuildError', code, reason, docPath,
+      cause !== undefined ? { cause } : undefined);
+  }
+}
+
+/**
+ * A failure while a terminal operation ran. Codes:
+ *
+ *  - `JL2001` — `first()`/`single()` over an empty sequence (the
+ *    `OrDefault` variants return the default instead)
+ *  - `JL2002` — `single()`/`singleOrDefault()` over two or more
+ *    elements
+ *  - `JL2003` — `elementAt(i)` with no element at position `i`
+ *  - `JL2004` — a provider's `execute()` answered a promise. A
+ *    `Sequence` terminal is a value (`toArray(): T[]`), so a promise
+ *    cannot be returned under that type; emit `toDocument()` and await
+ *    the provider directly instead.
+ */
+export class LinqRuntimeError extends CodedError {
+  /**
+   * @param {string} code
+   * @param {string} reason - The bare reason; `message` is composed per
+   *   the coded contract.
+   * @param {string} [docPath] - JSON Pointer into the emitted query
+   *   document, where one exists.
+   * @param {Error} [cause]
+   */
+  constructor(code, reason, docPath, cause) {
+    super('LinqRuntimeError', code, reason, docPath,
+      cause !== undefined ? { cause } : undefined);
+  }
+}