@jarenjs/linq 0.34.0

package/src/expression.js

@@ -0,0 +1,320 @@
+//@ts-check
+/**
+ * @file Expression capture (D4): a predicate or projection callback
+ * receives a RECORDING PROXY, never a stringified function. Member
+ * access records a path segment; a method call records an operator; the
+ * output is a plain Jaren query expression (QUERY-FORMAT.md §§3–8) —
+ * hand-readable JSON, nothing else.
+ *
+ * Capture is epoch-scoped: every proxy belongs to exactly one `capture`
+ * call, and using one outside it (stored and replayed into a later
+ * chain) is `JL0002` — a proxy that escaped would otherwise emit a
+ * document that silently refers to the wrong binding. (`===` between
+ * proxies is untrappable and therefore undetectable; the format doc
+ * says so.)
+ *
+ * Method names shadow member access: `u.eq` is the operator, never the
+ * data member — reach a colliding member with `u.get('eq')`.
+ */
+
+import { LinqBuildError } from './errors.js';
+
+/** The unwrap key: proxy → its internal record. */
+const NODE = Symbol('jaren-linq-node');
+
+/** RFC 9535 shorthand member names travel as `.name`; everything else
+ * goes through a bracketed, single-quoted selector. */
+const SHORTHAND_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+let activeEpoch = 0;
+
+/** @param {any} record */
+function assertLive(record) {
+  if (record.epoch !== activeEpoch) {
+    throw new LinqBuildError('JL0002',
+      'an expression proxy escaped its capture callback; expressions cannot be stored and replayed across operators');
+  }
+}
+
+/**
+ * Embed a literal string as a query expression: plain strings are
+ * literals by Rule 2, and a string starting `$` needs the `$$` escape
+ * so it stays data.
+ * @param {string} s
+ */
+function embedString(s) {
+  return s.charCodeAt(0) === 0x24 ? '$' + s : s;
+}
+
+/**
+ * True when `value` is a plain JSON tree (no proxies) that can embed
+ * verbatim.
+ *
+ * "Plain JSON" is checked, not assumed. Walking `Object.keys` alone
+ * accepted every value whose own enumerable keys happen to be JSON —
+ * which a `Date`, a `Map`, a `RegExp`, a `Set` and every class instance
+ * satisfy vacuously, because `Object.keys` reports nothing for them. Each
+ * one then embedded as `{}` and the query filtered on an empty object.
+ * The numeric domain matters just as much: `NaN` and `±Infinity` are not
+ * JSON numbers, and `-0` is a legal number that shares JSON text with
+ * `0` while dividing to the opposite infinity. So the prototype is
+ * required to be plain and the numeric domain is required to be finite,
+ * and a captured constant outside that boundary is refused at capture —
+ * where the caller can see which value it was.
+ * @param {any} value
+ */
+function isPlainJson(value) {
+  if (value === null) return true;
+  const type = typeof value;
+  if (type === 'string' || type === 'boolean') return true;
+  if (type === 'number') return Number.isFinite(value) && !Object.is(value, -0);
+  if (type !== 'object') return false; // undefined, function, symbol, bigint
+  if (value[NODE] !== undefined) return false;
+  const proto = Object.getPrototypeOf(value);
+  if (Array.isArray(value)) {
+    return proto === Array.prototype && value.every(isPlainJson);
+  }
+  if (proto !== Object.prototype && proto !== null) return false;
+  for (const key of Object.keys(value)) {
+    if (!isPlainJson(value[key])) return false;
+  }
+  return true;
+}
+
+/**
+ * Turn a captured callback result — a proxy, a literal, or a plain
+ * object/array tree containing proxies — into a query expression.
+ * Objects without `$`-prefixed keys become Rule 1 constructors; a
+ * `$`-keyed data object embeds through `$map` so it stays a
+ * constructor rather than colliding with the operator vocabulary;
+ * pure data trees embed as `$const`.
+ * @param {any} value
+ * @returns {any} a query expression (plain JSON)
+ */
+export function toExpression(value) {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === 'string') return embedString(value);
+  if (t === 'boolean') return value;
+  if (t === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new LinqBuildError('JL0005',
+        `a captured expression cannot embed ${String(value)} — the query data model is `
+        + 'JSON, which has no NaN or Infinity, and lenient serialization would fold it '
+        + 'into null');
+    }
+    if (Object.is(value, -0)) {
+      throw new LinqBuildError('JL0005',
+        'a captured expression cannot embed -0 — it shares its JSON text with 0 while '
+        + 'dividing to the opposite infinity, so a document holding it cannot be '
+        + 'keyed, stored or compared faithfully; use 0, or negate at query time');
+    }
+    return value;
+  }
+  if (t === 'object') {
+    const record = value[NODE];
+    if (record !== undefined) {
+      assertLive(record);
+      return record.doc;
+    }
+    if (isPlainJson(value)) {
+      // verbatim data: cheaper and clearer than a constructor tree
+      return { $const: value };
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (Array.isArray(value)) {
+      if (proto !== Array.prototype) {
+        throw new LinqBuildError('JL0005',
+          'a captured expression cannot embed an Array subclass instance — its behaviour '
+          + 'is not expressible as query data');
+      }
+      return value.map(toExpression);
+    }
+    if (proto !== Object.prototype && proto !== null) {
+      // a Date, Map, Set, RegExp or class instance: `Object.keys` reports
+      // nothing for it, so embedding it verbatim produced `{}` and the
+      // query silently compared against an empty object
+      throw new LinqBuildError('JL0005',
+        `a captured expression cannot embed a ${value.constructor?.name ?? 'non-plain'} `
+        + 'instance — it carries no own enumerable members, so it would embed as {}. '
+        + 'Convert it to query data first (a Date to its ISO string or epoch number, a '
+        + 'Map to an object), or bind it through params().');
+    }
+    const keys = Object.keys(value);
+    if (keys.some((k) => k.charCodeAt(0) === 0x24)) {
+      return { $map: keys.map((k) => [embedString(k), toExpression(value[k])]) };
+    }
+    const out = {};
+    // an own `__proto__` member is DATA here; plain assignment would set
+    // the builder's prototype and drop the member
+    for (const key of keys) {
+      Object.defineProperty(out, key, {
+        value: toExpression(value[key]),
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+    }
+    return out;
+  }
+  throw new LinqBuildError('JL0005',
+    `a captured expression cannot embed a ${t === 'undefined' ? 'undefined' : t} value`);
+}
+
+/** Binary operator helper. @param {string} op */
+const binary = (op) => function (/** @type {any} */ record, /** @type {any} */ operand) {
+  return makeExpr({ [op]: [record.doc, toExpression(operand)] }, record.epoch, false);
+};
+
+/** Unary operator helper. @param {string} op */
+const unary = (op) => function (/** @type {any} */ record) {
+  return makeExpr({ [op]: record.doc }, record.epoch, false);
+};
+
+/**
+ * The operator methods, name → builder(record, ...args). One table so
+ * the mapping in LINQ-FORMAT.md §4 has exactly one code counterpart.
+ * Null prototype: `constructor`/`toString` must read as member access,
+ * never as inherited "methods".
+ */
+const METHODS = {
+  __proto__: null,
+  // §8.4 comparisons
+  eq: binary('$eq'), ne: binary('$ne'),
+  lt: binary('$lt'), le: binary('$le'),
+  gt: binary('$gt'), ge: binary('$ge'),
+  // §8.6 logic
+  and: binary('$and'), or: binary('$or'), not: unary('$not'),
+  // §8.5 arithmetic
+  add: binary('$add'), sub: binary('$sub'), mul: binary('$mul'),
+  div: binary('$div'), idiv: binary('$idiv'), mod: binary('$mod'),
+  neg: unary('$neg'),
+  // §8.2 existence
+  exists: unary('$exists'), isEmpty: unary('$empty'),
+  // §8.7 strings
+  startsWith: binary('$starts-with'), endsWith: binary('$ends-with'),
+  contains: binary('$contains'), matches: binary('$match'),
+  upper: unary('$upper'), lower: unary('$lower'),
+  length: unary('$string-length'),
+  concat: binary('$concat'),
+  substring(record, start, len) {
+    const args = len === undefined
+      ? [record.doc, toExpression(start)]
+      : [record.doc, toExpression(start), toExpression(len)];
+    return makeExpr({ $substring: args }, record.epoch, false);
+  },
+  replace(record, pattern, replacement) {
+    return makeExpr(
+      { $replace: [record.doc, toExpression(pattern), toExpression(replacement)] },
+      record.epoch, false);
+  },
+  // §8.8 aggregates as EXPRESSIONS (a group inside a projection:
+  // `(u, g) => ({ n: g.count() })`)
+  count: unary('$count'), sum: unary('$sum'), avg: unary('$avg'),
+  min: unary('$min'), max: unary('$max'),
+  // §8.13 dates (the scalar component family; the full date surface
+  // arrives with the relational order)
+  year: unary('$year'), month: unary('$month'), day: unary('$day'),
+  epoch: unary('$epoch'),
+  // path navigation
+  at(record, index) {
+    if (record.pathable && Number.isInteger(index)) {
+      return makeExpr(`${record.doc}[${index}]`, record.epoch, true);
+    }
+    return makeExpr({ $get: [record.doc, toExpression(index)] }, record.epoch, false);
+  },
+  all(record) {
+    if (!record.pathable) {
+      throw new LinqBuildError('JL0005',
+        "all() fans out a PATH ('$it.tags[*]'); it cannot follow an operator result");
+    }
+    return makeExpr(`${record.doc}[*]`, record.epoch, true);
+  },
+  get(record, name) {
+    if (typeof name === 'string' && record.pathable) {
+      return makeExpr(`${record.doc}['${name.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}']`,
+        record.epoch, true);
+    }
+    return makeExpr({ $get: [record.doc, toExpression(name)] }, record.epoch, false);
+  },
+};
+
+/**
+ * Build one expression proxy.
+ * @param {any} doc - the expression JSON so far
+ * @param {number} epoch - the owning capture
+ * @param {boolean} pathable - whether `doc` is a pure path string that
+ *   member access may extend
+ * @returns {any}
+ */
+function makeExpr(doc, epoch, pathable) {
+  const record = { doc, epoch, pathable };
+  return new Proxy(record, {
+    get(target, prop) {
+      if (prop === NODE) return target;
+      if (typeof prop === 'symbol') return undefined;
+      const method = METHODS[prop];
+      if (method !== undefined) {
+        return (...args) => {
+          assertLive(target);
+          return method(target, ...args);
+        };
+      }
+      assertLive(target);
+      if (target.pathable) {
+        const step = SHORTHAND_RE.test(prop)
+          ? `${target.doc}.${prop}`
+          : `${target.doc}['${prop.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}']`;
+        return makeExpr(step, target.epoch, true);
+      }
+      return makeExpr({ $get: [target.doc, prop] }, target.epoch, false);
+    },
+  });
+}
+
+/**
+ * The parameters proxy: `p.tenantId` emits the external `$tenantId` —
+ * when the name was declared via `.params({...})`. Undeclared use is
+ * `JL0004` at BUILD time, with the fix in the message (the engine
+ * would say JQ0005 at compile time; earlier and clearer beats later).
+ * @param {Set<string>} declared
+ * @param {number} epoch
+ */
+function makeParams(declared, epoch) {
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (typeof prop === 'symbol') return undefined;
+      if (!declared.has(prop)) {
+        throw new LinqBuildError('JL0004',
+          `parameter '${prop}' is not declared — declare it first: .params({ ${prop}: value })`);
+      }
+      return makeExpr('$' + prop, epoch, true);
+    },
+  });
+}
+
+/**
+ * Run one capture: `fn` receives a proxy per root (plus the parameters
+ * proxy last) and its result becomes an expression via
+ * {@link toExpression}. A root is a binding NAME (`'it'` → the pathable
+ * `$it`) or a `{ doc, pathable }` record for an expression-valued root
+ * (groupJoin's inner group). Proxies die with the capture — reuse is
+ * `JL0002`.
+ * @param {(...roots: any[]) => any} fn - the user callback
+ * @param {readonly (string | { doc: any, pathable: boolean })[]} roots
+ * @param {Set<string>} declaredParams
+ * @returns {any} the captured expression (plain JSON)
+ */
+export function captureExpression(fn, roots, declaredParams) {
+  const epoch = ++activeEpoch;
+  const proxies = roots.map((root) => (typeof root === 'string'
+    ? makeExpr('$' + root, epoch, true)
+    : makeExpr(root.doc, epoch, root.pathable)));
+  proxies.push(makeParams(declaredParams, epoch));
+  try {
+    return toExpression(fn(...proxies));
+  }
+  finally {
+    activeEpoch++; // every proxy of this capture is now dead
+  }
+}

package/src/index.js

@@ -0,0 +1,14 @@
+//@ts-check
+/**
+ * @file @jarenjs/linq — a C#-familiar fluent surface that captures
+ * expressions as plain Jaren query documents (QUERY-FORMAT.md),
+ * executes deferred over any iterable, and hands the SAME document
+ * whole to any provider exposing `execute(document, options)` (D2:
+ * contract-level coupling, never an import edge). The normative
+ * surface, mapping table and error codes live in docs/LINQ-FORMAT.md.
+ */
+
+export { from, fromDocument, Sequence } from './sequence.js';
+export { fromAsync, AsyncSequence } from './async.js';
+export { createPushQueue } from './sources.js';
+export { LinqBuildError, LinqRuntimeError, LINQ_CODES } from './errors.js';

package/src/provider.js

@@ -0,0 +1,166 @@
+//@ts-check
+/**
+ * @file The provider seam (D2): a provider is any object exposing
+ * `execute(queryDocument, options)` — contract-level coupling, never an
+ * import edge. `@jarenjs/db` will implement this interface without
+ * either package importing the other. The in-memory runner implements
+ * the SAME interface over an iterable, so it is both the reference
+ * semantics every other provider must match and the proof the seam is
+ * real.
+ *
+ * Compiled documents are shared through a bounded LRU keyed by the
+ * document's COLLISION-FREE structural identity, one cache per REGISTRY
+ * identity — the hooks change what compiles, so two different registries
+ * must not share compiled programs.
+ * A fingerprint would not do: a 32-bit content hash collides after tens
+ * of thousands of documents, and a collision here runs one query's
+ * compiled program for another query's document — silently wrong rows.
+ */
+
+import { compileJsonQuery, JsonQueryCompileError } from '@jarenjs/json/query';
+import { createSemanticCache, createWeakCache } from '@jarenjs/core/cache';
+import { LinqBuildError } from './errors.js';
+
+/** Stands in for an absent hook while walking the identity chain. */
+const NO_HOOK = Object.freeze({});
+
+const CACHES = createWeakCache();
+const cacheFor = () => createSemanticCache(512);
+
+/** The root of the hook-identity chain. */
+const REGISTRY_IDS = createWeakCache();
+/** The token minted for each distinct COMBINATION of hook identities. */
+const REGISTRY_TOKEN = Symbol('linq.registryToken');
+
+/**
+ * The compile options a sequence forwards to the engine, beyond the
+ * document itself. `orderBy(..., {collation})` and `$call` emit perfectly
+ * good documents, and without the matching registry the in-memory
+ * compiler could only answer `JQ0010` — so a Dutch sort was expressible
+ * and not executable. These are the registries that close that gap; the
+ * engine's own option names, deliberately, so there is one vocabulary.
+ */
+export const COMPILE_OPTION_KEYS = Object.freeze([
+  'compileTypeTest', 'functions', 'collations', 'pathFunctions', 'limits',
+]);
+
+/**
+ * Pick the forwarded compile options out of a sequence's options bag.
+ * @param {Record<string, any>} options
+ * @returns {Record<string, any>}
+ */
+export function compileOptionsOf(options) {
+  /** @type {Record<string, any>} */
+  const out = {};
+  for (const key of COMPILE_OPTION_KEYS) {
+    if (options[key] !== undefined) out[key] = options[key];
+  }
+  return out;
+}
+
+/**
+ * A stable token for one COMBINATION of hook identities, so compiled
+ * programs are shared exactly among callers whose hooks agree.
+ *
+ * Partitioning on one hook is not enough: a document naming a `nl`
+ * collation compiles to different code with and without that registry,
+ * and a shared partition would serve the compiled-with version to a
+ * caller who passed no collations at all — which is a wrong answer, not
+ * a missing error. The chain walks every hook slot in a fixed order
+ * through WeakMaps, so a token lives exactly as long as the registries
+ * that produced it. `limits` is plain data and rides in the cache key
+ * instead of here, so a fresh `{ steps: 1000 }` literal per call does
+ * not mint a fresh partition every time.
+ * @param {Record<string, any>} options
+ * @returns {object} the partition key
+ */
+function registryIdentity(options) {
+  if (options.registry !== undefined) return options.registry;
+  let node = /** @type {any} */ (REGISTRY_IDS);
+  for (const key of ['compileTypeTest', 'functions', 'collations', 'pathFunctions']) {
+    const hook = options[key];
+    const slot = hook === undefined || hook === null ? NO_HOOK : hook;
+    node = node.getOrCreate(slot, () => {
+      const next = createWeakCache();
+      /** @type {any} */ (next)[REGISTRY_TOKEN] = Object.freeze({});
+      return next;
+    });
+  }
+  return /** @type {any} */ (node)[REGISTRY_TOKEN];
+}
+
+/**
+ * Compile a query document, shared across equal documents.
+ * @param {any} document - the emitted (or hand-written) query document
+ * @param {{ compileTypeTest?: any, functions?: any, collations?: any,
+ *   pathFunctions?: any, limits?: any, registry?: object,
+ *   externals: readonly string[] }} options - `registry` is the cache
+ *   partition key: one object identity per distinct set of hooks, since
+ *   the hooks decide what a document compiles to
+ * @returns {any} the compiled query
+ * @throws {LinqBuildError} `JL0003` when a schema operator needs the
+ *   missing `compileTypeTest` hook
+ */
+export function compileDocument(document, options) {
+  const cache = /** @type {any} */ (CACHES.getOrCreate(registryIdentity(options), cacheFor));
+  // the externals and the limits are part of the identity: the same
+  // document compiles differently against a different set of declared
+  // names, and differently again under a step or result bound
+  return cache.getOrCreate([document, options.externals, options.limits ?? null], () => {
+    try {
+      return compileJsonQuery(document, {
+        ...compileOptionsOf(options),
+        externals: options.externals,
+      });
+    }
+    catch (err) {
+      if (err instanceof JsonQueryCompileError && err.code === 'JQ0008') {
+        throw new LinqBuildError('JL0003',
+          'ofType/cast compile schema operators, which need a type-test compiler — '
+          + 'pass options.compileTypeTest to from()/fromDocument() '
+          + '(e.g. createTypeTestCompiler() from @jarenjs/validate/query)',
+          err.docPath, err);
+      }
+      throw err;
+    }
+  });
+}
+
+/**
+ * Classify a `from()` source: an `execute` duck is a PROVIDER (the
+ * document is handed over whole; nothing is enumerated locally);
+ * any iterable is in-memory. Anything else is `JL0001` — at `from()`
+ * time, not at enumeration time.
+ * @param {any} source
+ * @returns {'provider' | 'iterable'}
+ */
+export function classifySource(source) {
+  if (source !== null && typeof source === 'object'
+    && typeof (/** @type {any} */ (source).execute) === 'function') {
+    return 'provider';
+  }
+  if (source != null && (typeof source === 'string'
+    || typeof (/** @type {any} */ (source))[Symbol.iterator] === 'function')) {
+    return 'iterable';
+  }
+  throw new LinqBuildError('JL0001',
+    'from() needs an iterable or a provider exposing execute(document, options)');
+}
+
+/**
+ * The in-memory execution of one document over an iterable source:
+ * materialise (each execution re-reads the source — the deferred
+ * re-enumeration contract), compile shared, run. The signature IS the
+ * provider contract, deliberately.
+ * @param {any} source - the iterable
+ * @param {any} document
+ * @param {{ compileTypeTest?: any, externalNames: readonly string[],
+ *   externals: Record<string, any> }} options
+ * @returns {any} the engine-shaped result (`undefined | item | items[]`)
+ */
+export function executeInMemory(source, document, options) {
+  const compiled = compileDocument(document,
+    { ...options, externals: options.externalNames });
+  const data = Array.isArray(source) ? source : [...source];
+  return compiled(data, options.externals);
+}