@jarenjs/linq 0.49.2 → 0.56.0

package/src/db/include.js

@@ -0,0 +1,316 @@
+//@ts-check
+/**
+ * @file The graph builder: `include(pick, spec)` and the root clauses
+ * accumulate a `load` specification (MODEL-FORMAT §10.4, §10.5) — the
+ * client EMITS the spec the store already runs and runs nothing itself.
+ * The relation member is captured to its NAME; every callback is
+ * captured to a query expression over `$it` through the chain's own
+ * recording proxy — with no parameters, since a load clause binds no
+ * externals — and `toArray()` is `load(spec)`, `explain()` is
+ * `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.
+ */
+
+import { deepFreeze, setObjectMember } from '@jarenjs/core/object';
+
+import { captureExpression } from '../expression.js';
+import { LinqBuildError } from '../errors.js';
+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'];
+/** A member path over the row: the shorthand or the bracketed spelling. */
+const MEMBER_PATH = /^\$it(?:\.([A-Za-z_$][\w$]*)|\['((?:[^'\\]|\\.)*)'\])$/;
+
+/**
+ * Capture one callback over the row bound as `it`.
+ * @param {any} fn
+ * @param {string} what - for the message
+ * @returns {any} the query expression
+ */
+function captureOver(fn, what) {
+  if (typeof fn !== 'function') {
+    throw new LinqBuildError('JL0101', `${what} takes a callback over the row, got ${describeValue(fn)}`);
+  }
+  return captureExpression(fn, ['it'], NO_PARAMS);
+}
+
+/**
+ * The relation entry a member names, or the refusal naming the table.
+ * @param {Record<string, any>} relations
+ * @param {string} entityName
+ * @param {string} member
+ * @param {string} what
+ * @returns {{ member: string, entry: any }}
+ */
+function requireRelation(relations, entityName, member, what) {
+  const entry = relations[member];
+  if (entry === undefined) {
+    const declared = Object.keys(relations);
+    throw new LinqBuildError('JL0107',
+      `'${member}' is not a relation member of '${entityName}' — ${what} loads a declared relation`
+      + (declared.length === 0 ? `, and '${entityName}' declares none`
+        : ` (${declared.map((name) => `'${name}'`).join(', ')})`));
+  }
+  return { member, entry };
+}
+
+/**
+ * The relation member a pick names: `(u) => u.posts` — or `u.get('posts')`
+ * for a name that collides with a method — captured to `$it.posts` and
+ * looked up in the relation table.
+ * @param {any} pick
+ * @param {Record<string, any>} relations
+ * @param {string} entityName
+ * @returns {{ member: string, entry: any }}
+ */
+function pickMember(pick, relations, entityName) {
+  const captured = captureOver(pick, 'include()');
+  const match = typeof captured === 'string' ? MEMBER_PATH.exec(captured) : null;
+  if (match === null) {
+    throw new LinqBuildError('JL0107',
+      `include() picks one relation member of '${entityName}' by name ((u) => u.posts); got `
+      + (typeof captured === 'string' ? captured : 'an operator result'));
+  }
+  const member = match[1] ?? match[2].replace(/\\(.)/g, '$1');
+  return requireRelation(relations, entityName, member, 'include()');
+}
+
+/**
+ * One `$orderby` term: a bare key for a plain ascending order, else the
+ * `{ $key, $dir, $empty, $collation }` spec — as the chain spells it.
+ * @param {any} key - the key callback
+ * @param {boolean} desc
+ * @param {{ empty?: string, collation?: string } | undefined} options
+ * @param {string} what
+ * @returns {any}
+ */
+function orderTerm(key, desc, options, what) {
+  const expression = captureOver(key, what);
+  const spec = { $key: expression };
+  if (desc) spec.$dir = 'desc';
+  if (options !== undefined && options !== null) {
+    if (options.empty !== undefined) spec.$empty = requireJson(options.empty, `${what} empty`);
+    if (options.collation !== undefined) spec.$collation = requireJson(options.collation, `${what} collation`);
+  }
+  return Object.keys(spec).length === 1 ? expression : spec;
+}
+
+/**
+ * An include spec's `orderBy`: a key callback, `{ key, desc?, empty?,
+ * collation? }`, or an array of either.
+ * @param {any} orderBy
+ * @param {string} what
+ * @returns {any}
+ */
+function lowerOrder(orderBy, what) {
+  const one = (term, at) => {
+    if (typeof term === 'function') return orderTerm(term, false, undefined, at);
+    if (term !== null && typeof term === 'object' && !Array.isArray(term) && typeof term.key === 'function') {
+      return orderTerm(term.key, term.desc === true, term, at);
+    }
+    throw new LinqBuildError('JL0101',
+      `${at} takes a key callback ((p) => p.stars) or { key, desc?, empty?, collation? }, got ${describeValue(term)}`);
+  };
+  return Array.isArray(orderBy) ? orderBy.map((term, i) => one(term, `${what}[${i}]`)) : one(orderBy, what);
+}
+
+/**
+ * Lower one include: `true` (or nothing) includes the rows; an object
+ * carries the clauses the store's `load` reads, each callback captured,
+ * nested includes resolved against the TARGET's relation table.
+ * @param {any} spec
+ * @param {string} entityName - the target entity
+ * @param {(name: string) => Record<string, any> | undefined} relationsOf
+ * @param {string[]} path
+ * @returns {any}
+ */
+function lowerInclude(spec, entityName, relationsOf, path) {
+  if (spec === undefined || spec === true) return true;
+  const at = path.join('.');
+  if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+    // the member list is DERIVED from the same constant the check below
+    // reads: typed out, it named `after` — a member that check refuses —
+    // and a reader who believed the first message met the second
+    throw new LinqBuildError('JL0101',
+      `the include spec at ${at} is true or `
+      + `{ ${INCLUDE_KEYS.map((key) => `${key}?`).join(', ')} }, got ${describeValue(spec)}`);
+  }
+  for (const key of Object.keys(spec)) {
+    if (!INCLUDE_KEYS.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `the include spec at ${at} does not take '${key}' — the members are ${INCLUDE_KEYS.join(', ')}`
+        + (key === 'after' ? '; a keyset cursor paginates the root: after() on the graph' : ''));
+    }
+  }
+  const out = {};
+  if (spec.where !== undefined) out.where = captureOver(spec.where, `${at} where`);
+  if (spec.orderBy !== undefined) out.orderBy = lowerOrder(spec.orderBy, `${at} orderBy`);
+  for (const key of ['take', 'skip']) {
+    if (spec[key] !== undefined) out[key] = requireJson(spec[key], `${at} ${key}`);
+  }
+  if (spec.count !== undefined) {
+    if (spec.count !== true) throw new LinqBuildError('JL0101', `the include spec at ${at}: count takes true`);
+    out.count = true;
+  }
+  if (spec.include !== undefined) out.include = lowerIncludes(spec.include, entityName, relationsOf, path);
+  return out;
+}
+
+/**
+ * A nested include record — member → `true` | spec — over the target's
+ * relation table.
+ * @param {any} includes
+ * @param {string} entityName
+ * @param {(name: string) => Record<string, any> | undefined} relationsOf
+ * @param {string[]} path
+ * @returns {Record<string, any>}
+ */
+function lowerIncludes(includes, entityName, relationsOf, path) {
+  if (includes === null || typeof includes !== 'object' || Array.isArray(includes)) {
+    throw new LinqBuildError('JL0101',
+      `include at ${path.join('.')} is a record of relation members, got ${describeValue(includes)}`);
+  }
+  const relations = relationsOf(entityName) ?? {};
+  const out = {};
+  for (const member of Object.keys(includes)) {
+    const { entry } = requireRelation(relations, entityName, member, 'a nested include');
+    setObjectMember(out, member, lowerInclude(includes[member], entry.to, relationsOf, [...path, member]));
+  }
+  return out;
+}
+
+/** The graph over one entity set: an immutable builder of a `load` spec. */
+export class Graph {
+  #set;
+  #entity;
+  #spec;
+  #tracking;
+
+  /**
+   * @param {any} set - the store's entity set
+   * @param {string} entity - its name
+   * @param {Record<string, any>} [spec] - the spec so far (`orderBy` as a list)
+   * @param {boolean} [tracking] - whether `toArray()` registers snapshots
+   */
+  constructor(set, entity, spec = {}, tracking = true) {
+    this.#set = set;
+    this.#entity = entity;
+    this.#spec = spec;
+    this.#tracking = tracking;
+  }
+
+  /** @param {Record<string, any>} patch */
+  #with(patch) {
+    return new Graph(this.#set, this.#entity, { ...this.#spec, ...patch }, this.#tracking);
+  }
+
+  /** The other roots' tables, where a nested include finds its target's. */
+  #relationsOf() {
+    const scoped = this.#set.scope?.relations;
+    return (name) => (scoped !== null && typeof scoped === 'object' ? scoped[name] : undefined);
+  }
+
+  /**
+   * Include one relation member, with an optional spec over its rows.
+   * @param {(u: any) => any} pick - `(u) => u.posts`
+   * @param {any} [spec] - `{ where?, orderBy?, take?, skip?, after?, count?, include? }`
+   * @returns {Graph}
+   */
+  include(pick, spec) {
+    const { member, entry } = pickMember(pick, this.#set.relations, this.#entity);
+    const lowered = lowerInclude(spec, entry.to, this.#relationsOf(), [member]);
+    const include = { ...(this.#spec.include ?? {}) };
+    setObjectMember(include, member, lowered);
+    return this.#with({ include });
+  }
+
+  /** Filter the root rows; consecutive calls conjoin. @param {(it: any) => any} predicate */
+  where(predicate) {
+    const expression = captureOver(predicate, 'where()');
+    const previous = this.#spec.where;
+    if (previous === undefined) return this.#with({ where: expression });
+    const conjoined = previous !== null && typeof previous === 'object'
+      && Object.keys(previous).length === 1 && Array.isArray(previous.$and)
+      ? [...previous.$and, expression] : [previous, expression];
+    return this.#with({ where: { $and: conjoined } });
+  }
+
+  /** @param {(it: any) => any} key @param {{ empty?: string, collation?: string }} [options] */
+  orderBy(key, options) {
+    return this.#with({ orderBy: [orderTerm(key, false, options, 'orderBy()')] });
+  }
+
+  /** @param {(it: any) => any} key @param {{ empty?: string, collation?: string }} [options] */
+  orderByDescending(key, options) {
+    return this.#with({ orderBy: [orderTerm(key, true, options, 'orderByDescending()')] });
+  }
+
+  /** @param {(it: any) => any} key @param {{ empty?: string, collation?: string }} [options] */
+  thenBy(key, options) {
+    return this.#then(orderTerm(key, false, options, 'thenBy()'), 'thenBy');
+  }
+
+  /** @param {(it: any) => any} key @param {{ empty?: string, collation?: string }} [options] */
+  thenByDescending(key, options) {
+    return this.#then(orderTerm(key, true, options, 'thenByDescending()'), 'thenByDescending');
+  }
+
+  /** @param {any} term @param {string} what */
+  #then(term, what) {
+    if (this.#spec.orderBy === undefined) {
+      throw new LinqBuildError('JL0005',
+        `${what}() extends an orderBy()/orderByDescending() — none precedes it`);
+    }
+    return this.#with({ orderBy: [...this.#spec.orderBy, term] });
+  }
+
+  /** @param {number} count */
+  take(count) { return this.#with({ take: requireJson(count, 'take()') }); }
+
+  /** @param {number} count */
+  skip(count) { return this.#with({ skip: requireJson(count, 'skip()') }); }
+
+  /** The keyset cursor (§10.5). @param {string | number} cursor */
+  after(cursor) { return this.#with({ after: requireJson(cursor, 'after()') }); }
+
+  /** The include depth bound (§10.4). @param {number} depth */
+  maxDepth(depth) { return this.#with({ maxDepth: requireJson(depth, 'maxDepth()') }); }
+
+  /** The same graph, loaded without registering snapshots. */
+  asNoTracking() {
+    return new Graph(this.#set, this.#entity, this.#spec, false);
+  }
+
+  /** The document, as every pen answers it: the emitted spec. */
+  toJSON() {
+    return this.toSpec();
+  }
+
+  /** The emitted `load` spec: plain frozen JSON, a snapshot. */
+  toSpec() {
+    const out = {};
+    for (const key of ROOT_KEYS) {
+      const value = this.#spec[key];
+      if (value === undefined) continue;
+      out[key] = key === 'orderBy' && value.length === 1 ? value[0] : value;
+    }
+    return deepFreeze(structuredClone(out));
+  }
+
+  /** `load(spec)` — the store's one statement. */
+  toArray() {
+    const spec = this.toSpec();
+    return this.#tracking ? this.#set.load(spec) : this.#set.asNoTracking().load(spec);
+  }
+
+  /** `explainLoad(spec)` — the SQL, the includes, the pagination strategy. */
+  explain() {
+    return this.#set.explainLoad(this.toSpec());
+  }
+}

package/src/db/index.js

@@ -0,0 +1,19 @@
+//@ts-check
+/**
+ * @file `@jarenjs/linq/db` — the store's front door. `open(model,
+ * options)` returns a client typed from the model pen whose entity
+ * handles chain (`client.entities.Post.where(…)` is `fromAsync(handle)
+ * .where(…)`, so every read is the chain's document and pushes down),
+ * load graphs from an EMITTED `load` spec (`include`), track and save
+ * changes, link and unlink many-to-many members and maintain live
+ * results — over exactly one runtime edge: this subpath imports
+ * `@jarenjs/db`, `@jarenjs/validate` and `@jarenjs/formats`, declared as
+ * optional peers; no other subpath of the package does, and the store
+ * never imports this package (the edge suite in the tests holds both).
+ * The store stays the engine: the client adds no storage semantics and
+ * 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.
+ */
+
+export { open, defaultValidator } from './open.js';

package/src/db/live.js

@@ -0,0 +1,43 @@
+//@ts-check
+/**
+ * @file `live(source, options)`: a chain's document and bound externals —
+ * or a hand-written document — handed to the store's own registration
+ * (`store.live` for an entity-root chain, `collection.live` for a
+ * collection's), so the mode, the reason and the maintenance are the
+ * store's (LIVE-FORMAT §7): an entity document re-runs on invalidation,
+ * declared, and a store opened without capture refuses (`JD0050`)
+ * exactly as it does for a document. The chain's `params()` bindings are
+ * the externals, fixed at registration; `options.externals` adds to them.
+ */
+
+/** Whether a source is a chain: a document and an explanation to give. */
+const isChain = (source) => source !== null && typeof source === 'object'
+  && typeof source.toDocument === 'function' && typeof source.explain === 'function';
+
+/**
+ * The document a source stands for, with the values it bound.
+ * @param {any} source - a chain (either surface) or a query document
+ * @returns {{ document: any, bindings: Record<string, unknown> }}
+ */
+function documentOf(source) {
+  if (!isChain(source)) return { document: source, bindings: {} };
+  const explained = source.explain();
+  // a chain split by a host callback has no document; its own refusal
+  // (`JL0005`) names why
+  if (explained.document === undefined) source.toDocument();
+  return { document: explained.document, bindings: explained.bindings };
+}
+
+/**
+ * Register a live query through the store's own registration.
+ * @param {(document: any, options: any) => Promise<any>} register - the
+ *   store's `live` (entity roots) or a collection's
+ * @param {any} source - a chain or a document
+ * @param {any} [options] - LIVE-FORMAT §7 options; `externals` merge over
+ *   the chain's bindings
+ * @returns {Promise<any>} the store's live query
+ */
+export function registerLive(register, source, options = {}) {
+  const { document, bindings } = documentOf(source);
+  return register(document, { ...options, externals: { ...bindings, ...(options.externals ?? {}) } });
+}

package/src/db/membership.js

@@ -0,0 +1,37 @@
+//@ts-check
+/**
+ * @file `link`/`unlink` on a handle: the relation table decides. The
+ * member must be a many-to-many relation of the entity — `JL0107`
+ * otherwise, naming the kind it is or the members that are declared —
+ * and then the store's own `link`/`unlink` record the change
+ * (MODEL-FORMAT §11.7) for `saveChanges()` to write. The store would
+ * refuse the same members itself (`JD2003`); the client sees it earlier
+ * from the table it already reads, mirrored, never invented.
+ */
+
+import { LinqBuildError } from '../errors.js';
+
+/**
+ * The many-to-many relation entry a membership operation names.
+ * @param {Record<string, any>} relations - the handle's relation table
+ * @param {string} entityName
+ * @param {string} member
+ * @param {string} verb - `link` or `unlink`, for the message
+ * @returns {any} the relation entry
+ */
+export function requireMembership(relations, entityName, member, verb) {
+  const entry = relations[member];
+  if (entry === undefined) {
+    const declared = Object.keys(relations).filter((name) => relations[name].kind === 'manyToMany');
+    throw new LinqBuildError('JL0107',
+      `'${member}' is not a relation member of '${entityName}' — ${verb}() attaches a many-to-many `
+      + `membership${declared.length === 0 ? `, and '${entityName}' declares none`
+        : ` (${declared.map((name) => `'${name}'`).join(', ')})`}`);
+  }
+  if (entry.kind !== 'manyToMany') {
+    throw new LinqBuildError('JL0107',
+      `'${member}' is a ${entry.kind} relation of '${entityName}' — ${verb}() attaches many-to-many `
+      + "memberships only; write the related entity's foreign key instead");
+  }
+  return entry;
+}

package/src/db/open.js

@@ -0,0 +1,82 @@
+//@ts-check
+/**
+ * @file `open(model, options)`: `openStore` with every option forwarded
+ * verbatim, plus `validator` — a `JarenValidator` wired as the store's
+ * `compileSchema`. The default validator reproduces the configuration
+ * MIGRATING-FROM-ZOD's recipe uses (`collectErrors`, the string and
+ * date-time formats registered), so `s.string().email()` asserts out
+ * of the box; a host that already has a `compileSchema` passes it and
+ * wins; `validator: null` opens the store unvalidated — the store's own
+ * declared downgrade (`capabilities.validated === false`), chosen by
+ * name, never by omission. The client is a frozen record of handles built ONCE at open
+ * from the names the store declares — no Proxy anywhere: an unknown
+ * name is `undefined`, and for a pen model a compile error.
+ */
+
+import { openStore } from '@jarenjs/db';
+import { JarenValidator } from '@jarenjs/validate';
+import { stringFormats, dateTimeFormats } from '@jarenjs/formats';
+import { setObjectMember } from '@jarenjs/core/object';
+
+import { createEntityHandle, createCollectionHandle } from './handle.js';
+import { registerLive } from './live.js';
+
+/**
+ * The validator the client compiles entity and collection schemas with
+ * when none is given: every issue collected, formats asserting.
+ * @returns {JarenValidator}
+ */
+export function defaultValidator() {
+  return new JarenValidator({ collectErrors: true })
+    .addFormats(stringFormats)
+    .addFormats(dateTimeFormats);
+}
+
+/**
+ * Open a store and front it.
+ * @param {any} model - a `$model` document: the model pen's, or JSON
+ * @param {any} options - `openStore`'s options (`driver` required), plus
+ *   `validator?` (a `JarenValidator`, wired as `compileSchema` unless an
+ *   explicit `compileSchema` is given; `null` for an unvalidated store)
+ * @returns {Promise<any>} the client
+ */
+export async function open(model, options) {
+  if (options === null || typeof options !== 'object') {
+    throw new TypeError('open needs { driver } from @jarenjs/db/node, /bun or /wasm');
+  }
+  const { validator, ...storeOptions } = options;
+  if (validator !== undefined && validator !== null
+    && (typeof validator !== 'object' || typeof validator.compile !== 'function')) {
+    throw new TypeError('open: validator must be a JarenValidator (an object with compile(schema)), '
+      + 'or null for an unvalidated store');
+  }
+  if (storeOptions.compileSchema === undefined && validator !== null) {
+    const jaren = validator ?? defaultValidator();
+    storeOptions.compileSchema = (schema) => jaren.compile(schema);
+  }
+  const store = await openStore(model, storeOptions);
+  const entities = {};
+  for (const name of store.roots ?? []) {
+    setObjectMember(entities, name, createEntityHandle(store, name));
+  }
+  const collections = {};
+  for (const name of Object.keys(model.collections ?? {})) {
+    setObjectMember(collections, name, createCollectionHandle(store, name));
+  }
+  /** @type {Record<string, any>} */
+  const client = {
+    store,
+    capabilities: store.capabilities,
+    entities: Object.freeze(entities),
+    collections: Object.freeze(collections),
+    transaction: (fn) => store.transaction(fn),
+    close: (closeOptions) => store.close(closeOptions),
+  };
+  // the unit of work and entity live queries exist exactly when the
+  // model declares entities — as on the store
+  if (store.saveChanges !== undefined) {
+    client.saveChanges = () => store.saveChanges();
+    client.live = (source, liveOptions) => registerLive(store.live, source, liveOptions);
+  }
+  return Object.freeze(client);
+}