@jarenjs/linq 0.49.2 → 0.56.0

package/src/document.js

@@ -21,24 +21,142 @@
  * 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.
+ *
+ * An item is an item. The engine's `$for` unpacks an item that is an
+ * array into its members, one level (QUERY-FORMAT §6.2, D4) — the
+ * ergonomic default for a path like `$.tags`, and the wrong default for
+ * a chain, where an array-valued ROW (a CSV record, a pair) is one item
+ * the C# contract never splits. So every source a phrase iterates is
+ * bound through an ARRAY CONSTRUCTOR — `{ "$for": { "it": ["$[*]"] } }`
+ * — whose one array item is unpacked exactly once, into the rows as
+ * they are; a reseated phrase is packed the same way, because a `$for`
+ * over an inner phrase's result would unpack again. The one source left
+ * bare is a PROVIDER's own root (`'$.Post[*]'`): a stored document is an
+ * object, so D4 never applies there, and the bare root is the shape the
+ * provider's planner pushes. The streaming async surface keeps items by
+ * construction, so the two surfaces agree on every row shape.
  */
 
 import { LinqBuildError } from './errors.js';
 
+/** The binding names the emitted documents own (QUERY-PEN §7): the
+ * item bindings, the accumulator and the group — and the relation-hop
+ * bindings `r1`, `r2`, … a capture allocates (expression.js). A
+ * parameter may shadow none of them. */
+export const RESERVED_BINDINGS = Object.freeze(['it', 'it2', 'acc', 'g']);
+const HOP_BINDING_RE = /^r[1-9][0-9]*$/;
+
+/**
+ * Whether a parameter name collides with a binding the document owns.
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isReservedBinding(name) {
+  return RESERVED_BINDINGS.includes(name) || HOP_BINDING_RE.test(name);
+}
+
+/** The reserved names, for a refusal's message. */
+export const RESERVED_BINDINGS_TEXT = 'it, it2, acc, g, and r1, r2, … for relation hops';
+
+/** The member a `groupBy`'s items carry the group's rows in. Spelled
+ * once: the emitter writes it here and `expression.js` gives that member
+ * its fan, so `g.items.count()` counts the ROWS the way a group-join's
+ * `g.count()` already does. */
+export const GROUP_ITEMS = 'items';
+
+/** The stage kinds after which the items are no longer the source's
+ * rows: a relation name on them is an ordinary member (QUERY-PEN §3).
+ * The async surface adds its host boundary, `mapAsync`. */
+export const PROJECTING_STAGES = new Set(['select', 'groupBy', 'join', 'groupJoin', 'aggregate']);
+
 /** The fixed clause order a phrase may fill left-to-right. */
-const SLOT_ORDER = ['where', 'groupby', 'orderby', 'return'];
+const SLOT_ORDER = ['bindings', '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) {
+/**
+ * An open FLWOR phrase under construction. `bare` marks a source the
+ * phrase iterates WITHOUT packing (a provider's root); every other
+ * source is packed so an array item stays one item.
+ * @param {any} source
+ * @param {boolean} [bare]
+ */
+function openPhrase(source, bare = false) {
   return {
-    source, fold: EMPTY, where: EMPTY, groupby: EMPTY, orderby: EMPTY, ret: EMPTY,
+    source, bare,
+    fold: EMPTY, bindings: EMPTY, where: EMPTY, groupby: EMPTY, orderby: EMPTY, ret: EMPTY,
   };
 }
 
+/** Whether no clause of the phrase has been filled. */
+function untouched(phrase) {
+  return phrase.fold === EMPTY && phrase.bindings === EMPTY && phrase.where === EMPTY
+    && phrase.groupby === EMPTY && phrase.orderby === EMPTY && phrase.ret === EMPTY;
+}
+
+/**
+ * The expression a phrase's items come from, as a `$for` source: packed
+ * (D4 unpacks the one array item back into the rows) unless the source
+ * is a bare provider root.
+ * @param {any} phrase
+ */
+function iterated(phrase) {
+  return phrase.bare ? phrase.source : [phrase.source];
+}
+
+/**
+ * A closed phrase as the SOURCE of another `$for` (a join side): a bare
+ * untouched root stays bare; anything else is packed.
+ * @param {any} phrase
+ */
+function packed(phrase) {
+  return phrase.bare && untouched(phrase) ? phrase.source : [closePhrase(phrase)];
+}
+
+/**
+ * A `selectMany` projection: the projected value iterated one level —
+ * an array member's elements, a constructed array's members, a scalar
+ * as itself — so `Seq<R[]>` really flattens to `Seq<R>`. The nested
+ * phrase rebinds `it` legally: its source is evaluated in the enclosing
+ * scope (the row), its body sees the element.
+ * @param {any} projection - a captured expression
+ * @returns {any}
+ */
+export function fanProjection(projection) {
+  return { $for: { it: projection }, $return: '$it' };
+}
+
+/**
+ * A deep, independent copy of an emitted query document. Plain data
+ * only, which is exactly what a document is — every captured expression
+ * has already passed the JSON-domain boundary in `expression.js`, so
+ * there is nothing here a structural copy would lose.
+ * @param {any} node
+ * @returns {any}
+ */
+export function snapshot(node) {
+  if (node === null || typeof node !== 'object') return node;
+  if (Array.isArray(node)) return node.map(snapshot);
+  /** @type {Record<string, any>} */
+  const out = {};
+  for (const key of Object.keys(node)) defineOwn(out, key, snapshot(node[key]));
+  return out;
+}
+
+/**
+ * Assign an OWN property, so a `__proto__` member stays a member instead
+ * of silently replacing the object's prototype and vanishing.
+ * @param {Record<string, any>} target
+ * @param {string} key
+ * @param {any} value
+ */
+function defineOwn(target, key, value) {
+  Object.defineProperty(target, key,
+    { value, writable: true, enumerable: true, configurable: true });
+}
+
 /** Whether every slot AFTER `slot` is still empty — chain order must
  * agree with the phrase's fixed semantic order. */
 function laterSlotsFree(phrase, slot) {
@@ -57,12 +175,11 @@ function slotFree(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;
+  if (untouched(phrase)) return phrase.source;
   const doc = {};
   if (phrase.fold !== EMPTY) doc.$fold = { acc: phrase.fold };
-  doc.$for = { it: phrase.source };
+  doc.$for = { it: iterated(phrase) };
+  if (phrase.bindings !== EMPTY) doc.$let = phrase.bindings;
   if (phrase.where !== EMPTY) doc.$where = phrase.where;
   if (phrase.groupby !== EMPTY) doc.$groupby = { g: phrase.groupby };
   if (phrase.orderby !== EMPTY) {
@@ -72,7 +189,7 @@ function closePhrase(phrase) {
   // 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'] }
+    ? { key: { $default: ['$g', null] }, [GROUP_ITEMS]: ['$it'] }
     : '$it');
   return doc;
 }
@@ -86,10 +203,12 @@ const andJoin = (a, b) => (a === EMPTY ? b : { $and: [a, b] });
  *   (`'$[*]'` for a plain source; a stripped document for
  *   `fromDocument`)
  * @param {readonly any[]} stages
+ * @param {{ bareRoot?: boolean }} [options] - `bareRoot` iterates the
+ *   root without packing (a provider's own root; see the header)
  * @returns {any} the emitted query document (plain JSON)
  */
-export function emitDocument(root, stages) {
-  let phrase = openPhrase(root);
+export function emitDocument(root, stages, options = undefined) {
+  let phrase = openPhrase(root, options?.bareRoot === true);
   /** Close the open phrase and reopen over its result. */
   const reseat = () => { phrase = openPhrase(closePhrase(phrase)); };
 
@@ -125,13 +244,24 @@ export function emitDocument(root, stages) {
         break;
       case 'join':
         // the hash-join shape: nested bindings + equality (the engine's
-        // compile-time rewrite turns exactly this into a hash probe)
+        // compile-time rewrite turns exactly this into a hash probe;
+        // packed sources keep it — the probe is keyed on the bindings,
+        // not on the sources' spelling)
         phrase = openPhrase({
-          $for: { it: closePhrase(phrase), it2: stage.inner },
+          $for: { it: packed(phrase), it2: stage.innerBare ? stage.inner : [stage.inner] },
           $where: stage.on,
           $return: stage.result,
         });
         break;
+      case 'groupJoin':
+        // the matching group bound as an ARRAY value (`$let`, one item)
+        // so the projection can index it, fan it and place it in a
+        // member; its aggregates fan over the members (expression.js)
+        if (!slotFree(phrase, 'bindings')) reseat();
+        phrase.bindings = { g: [stage.group] };
+        phrase.ret = stage.projection;
+        reseat();
+        break;
       case 'aggregate': {
         // the seeded fold: its own phrase, closed immediately — the
         // result is one accumulated value, not a tuple stream

package/src/effect.js

@@ -0,0 +1,65 @@
+//@ts-check
+/**
+ * @file The effect descriptor two formats spell identically —
+ * `{ run, with? }` — under a machine's `entry`/`exit`/`effects`
+ * (FLOW-FORMAT §2) and under an app transition's `effects`
+ * (APP-FORMAT §5.1). One shape, one brand, one reader; what differs is
+ * only where the props come from, which each pen passes in: the flow
+ * pen captures them over the step scope, the app pen leaves them to the
+ * action capture already in progress.
+ *
+ * `run` is a name the pen writes and never resolves — the host's
+ * registry owns the handler. What an unregistered name costs differs by
+ * engine and neither cost is the pen's: an app document's action loop
+ * refuses it (`JA2006`), while `compileFsm` never looks one up at all,
+ * because FLOW-FORMAT §1.1 makes effect EXECUTION a non-goal — the
+ * descriptor comes back as data and the host decides what to do with it.
+ */
+
+import { LinqBuildError } from './errors.js';
+import { describeValue } from './json-boundary.js';
+
+/** The descriptor brand: how a pen tells `effect()`'s result apart. */
+export const EFFECT = Symbol.for('@jarenjs/linq/effect-descriptor');
+
+/**
+ * One `{ run, with? }` descriptor, branded and frozen.
+ * @param {string} run - the host-registered handler name
+ * @param {any} props - the `with` member, or `undefined`
+ * @param {(props: any) => any} readProps - how this pen spells the props
+ * @returns {any} the effect declaration
+ */
+export function effectDescriptor(run, props, readProps) {
+  if (typeof run !== 'string' || run === '') {
+    throw new LinqBuildError('JL0101',
+      `effect() takes the handler name as a non-empty string, got ${describeValue(run)}`, '/run');
+  }
+  const out = { run };
+  if (props !== undefined) out.with = readProps(props);
+  Object.defineProperty(out, EFFECT, { value: true, enumerable: false });
+  return Object.freeze(out);
+}
+
+/**
+ * An effects list, as a document carries it: plain `{ run, with? }`
+ * objects, the brand dropped.
+ * @param {any} list
+ * @param {string} what - the member, for the message
+ * @returns {any[]}
+ */
+export function readEffects(list, what) {
+  if (!Array.isArray(list)) {
+    throw new LinqBuildError('JL0101',
+      `${what} is an array of effect() descriptors, got ${describeValue(list)}`);
+  }
+  return list.map((declared, i) => {
+    if (declared === null || typeof declared !== 'object' || Array.isArray(declared)
+      || declared[EFFECT] !== true) {
+      throw new LinqBuildError('JL0101',
+        `${what}[${i}] is effect(run, with?), got ${describeValue(declared)}`);
+    }
+    const out = { run: declared.run };
+    if (declared.with !== undefined) out.with = declared.with;
+    return out;
+  });
+}

package/src/errors.js

@@ -4,7 +4,7 @@
  * 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
+ * docs/QUERY-PEN.md §9, proven in sync with `LINQ_CODES` below by a
  * test.
  */
 
@@ -12,7 +12,7 @@ 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
+ * this package can raise, proven in sync with QUERY-PEN.md §9's
  * normative table by a test.
  */
 export const LINQ_CODES = Object.freeze({
@@ -22,10 +22,20 @@ export const LINQ_CODES = Object.freeze({
   JL0004: 'an undeclared or reserved parameter name was used',
   JL0005: 'an operator was used invalidly at build time',
   JL0006: 'an unsupported operator was invoked',
+  JL0007: 'a provider serves several entity roots and has no root of its own',
+  JL0101: 'a pen received a value it cannot spell: not JSON, or not what the keyword takes',
+  JL0102: 'a pen was asked for a construct the format cannot carry',
+  JL0103: 'a $defs name collision, a dangling ref, or an unnamed recursion',
+  JL0104: 'a pen-owned keyword through meta(), or an external a captured rule did not declare',
+  JL0105: 'a relation hop cannot lower: a many-to-many member, a composite or undeclared key, or a malformed relation entry',
+  JL0106: 'a migration step names a table the target model does not declare, or a draft it cannot match',
+  JL0107: 'a client operation named a member that is not the relation kind it needs',
   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',
+  JL2005: 'a push queue was fed after it ended',
+  JL2006: 'a provider answered an element terminal with something other than one array',
 });
 
 /**
@@ -42,13 +52,60 @@ export const LINQ_CODES = Object.freeze({
  *    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)
+ *    `.params({...})`, a declared name is reserved (`it`, `it2`, `acc`,
+ *    `g`, and the relation-hop bindings `r1`, `r2`, … — the document's
+ *    own binding names), a binding is not query data, or the two sides
+ *    of a `join`/`groupJoin`/`concat` bind one name to different values
  *  - `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)
+ *    without `orderBy`, `all()` off an operator result rather than a
+ *    path, a member read off a to-many relation before `all()`, 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
+ *  - `JL0007` — `from()`/`fromAsync()` received a provider that serves
+ *    several entity roots (`roots`) and has no `root` of its own — a
+ *    store with entities; chain over one of them (`store.entity(name)`)
+ *
+ * The pens (`@jarenjs/linq/schema`, `/model`, `/jslt`, `/migration`,
+ * `/contract`, `/flow`) and the client (`/db`; LINQ-FORMAT.md §1.3)
+ * refuse with the `JL01xx` codes:
+ *
+ *  - `JL0101` — a pen received a value it cannot spell: a function,
+ *    symbol, bigint, `NaN`, `±Infinity`, `-0`, a class instance or a
+ *    cycle where JSON was needed, or a value that is not what the
+ *    keyword takes (`min('x')`, a non-builder member)
+ *  - `JL0102` — a construct the format cannot carry: a function
+ *    `refine`/`transform`, a coercion the normalizer would never run,
+ *    closed objects under `allOf`, an annotation on `never()`, an
+ *    `apply()` as a bare object member, a `match` of `{}`, a path
+ *    template form CONTRACT-FORMAT §4.2 reserves, an operation `kind`
+ *    outside the three, a flow guard given as a plain string
+ *    (FLOW-FORMAT §3 makes a non-`$` literal vacuously true), a state
+ *    or node id no declaration carries
+ *  - `JL0103` — two distinct builders under one `$defs` name, a
+ *    `ref()` no definition answers, or a `lazy()` that is not named
+ *  - `JL0104` — a pen-owned keyword written through `meta()`, or a
+ *    captured rule naming an external it did not declare (a `check()`
+ *    or `body()` external other than `root`/`path` and, for a body,
+ *    its declared parameters; a `compute()` external at all, or a flow
+ *    guard/`with`/node-query/`select` external at all — both flow
+ *    engines evaluate with one `$` and nothing else)
+ *  - `JL0105` — a relation hop on the chain (the query pen) cannot
+ *    lower: the member is a many-to-many relation, whose join table is
+ *    not a queryable root in this version (`load({ include })` reads the
+ *    memberships); or the relation's key column or the key it references
+ *    is composite or undeclared; or the provider's relation table holds
+ *    something that is not a relation record
+ *  - `JL0106` — a migration step names an entity or collection the
+ *    target model does not declare (`transform`, `assert`, `derive`),
+ *    or a `transform` over a planned document finds no draft to
+ *    replace, or two drafts for one name
+ *  - `JL0107` — the client was handed a member that is not the relation
+ *    kind the operation needs: `include()` picks a declared relation
+ *    member (a scalar member, or a name the model does not declare, is
+ *    refused naming the declared ones); `link()`/`unlink()` attach
+ *    many-to-many memberships only (a to-one or to-many relation is
+ *    refused naming its kind)
  */
 export class LinqBuildError extends CodedError {
   /**
@@ -77,6 +134,12 @@ export class LinqBuildError extends CodedError {
  *    `Sequence` terminal is a value (`toArray(): T[]`), so a promise
  *    cannot be returned under that type; emit `toDocument()` and await
  *    the provider directly instead.
+ *  - `JL2005` — `feed()` was called on a push queue after `end()`
+ *    closed it (a condition of the running stream, not of the build)
+ *  - `JL2006` — a provider answered an element terminal (`toArray`,
+ *    `first`, …) with something other than exactly one array; the
+ *    emitted document is an array constructor, so a conforming
+ *    `execute()` never answers `undefined` there
  */
 export class LinqRuntimeError extends CodedError {
   /**