@jarenjs/linq 0.56.0 → 0.66.1

package/src/db/ledger.js

@@ -0,0 +1,195 @@
+//@ts-check
+/**
+ * @file `createDbLedger(client, options)`: the contract ledger
+ * (`@jarenjs/contract` docs/CONTRACT-FORMAT.md §8) over a declared
+ * collection of the client's store — every claim state, the persisted
+ * generation fence, expiry, `sweep` — through the client's collection
+ * and transaction surface alone. Nothing here imports the contract
+ * package or a driver: the ledger SHAPE is structural (the
+ * `claim`/`commit`/`fail`/`lookup` the http binding calls), the record
+ * is exactly `idempotencyLedgerModel`'s, and the id is the same
+ * versioned JSON tuple the memory ledger spells. A root client claims
+ * inside `transaction(…, { mode: 'immediate' })` — one writer, so two
+ * processes never both hold `new`; a transaction client claims and
+ * settles inside the transaction it was handed, which is the ledger a
+ * lifecycle settlement lease carries: a domain write and the settlement
+ * then commit together or not at all.
+ */
+
+import { resolveRuntime } from '@jarenjs/core/runtime';
+
+import { LinqRuntimeError } from '../errors.js';
+
+/** One day, the default retention of a key — the memory ledger's. */
+const DEFAULT_TTL_MS = 86_400_000;
+
+/** The collection `idempotencyLedgerModel` declares. */
+const DEFAULT_COLLECTION = 'ledger';
+
+/**
+ * The id of one `(op, scope, key)` tuple — the version `1`, a colon, the
+ * JSON array of the three: the spelling `@jarenjs/contract/ledger`'s
+ * `ledgerId` writes, so a store's records and a memory ledger's agree.
+ * A record written under the legacy `"<op>|<scope>|<key>"` spelling is
+ * matched by no claim again; it expires by its own `expiresAt` (`sweep`)
+ * or a host rewrites it once (DB-CLIENT.md §2.6).
+ * @param {string} op
+ * @param {string} scope
+ * @param {string} key
+ * @returns {string}
+ */
+function ledgerId(op, scope, key) {
+  return `1:${JSON.stringify([op, scope, key])}`;
+}
+
+/**
+ * @typedef {Object} DbLedgerOptions
+ * @property {string} [collection] - the declared collection, `'ledger'` by default
+ * @property {number} [ttlMs] - the retention of a key, 86,400,000 ms by default
+ * @property {Partial<import('@jarenjs/core/runtime').Runtime>} [runtime] -
+ *   the host's runtime record: its `now` is the clock, its `uuid` mints
+ *   every generation
+ * @property {() => number} [now] - the clock; wins over the runtime's
+ */
+
+/**
+ * @param {unknown} ref
+ * @param {string} reason
+ * @returns {LinqRuntimeError}
+ */
+function stale(ref, reason) {
+  const r = /** @type {any} */ (ref);
+  const named = r !== null && typeof r === 'object' && typeof r.id === 'string' ? r.id : 'a ref this ledger did not issue';
+  return new LinqRuntimeError('JL2007', `${named} settles no started record: ${reason}`);
+}
+
+/**
+ * The durable ledger over a client's declared collection.
+ * @param {any} client - a `@jarenjs/linq/db` client: the root one, or
+ *   the one a transaction callback received
+ * @param {DbLedgerOptions} [options]
+ * @returns {{ claim: (claim: { op: string, scope: string, key: string, hash: string, now?: number }) => Promise<any>,
+ *   commit: (ref: unknown, response: unknown, now?: number) => Promise<void>,
+ *   fail: (ref: unknown, retryable: boolean, response?: unknown, now?: number) => Promise<void>,
+ *   lookup: (key: { op: string, scope: string, key: string, now?: number }) => Promise<any>,
+ *   sweep: (now?: number) => Promise<number> }}
+ */
+export function createDbLedger(client, options = {}) {
+  if (client === null || typeof client !== 'object' || client.collections === null
+    || typeof client.collections !== 'object' || typeof client.transaction !== 'function') {
+    throw new TypeError('createDbLedger: client must be a @jarenjs/linq/db client — the root client, or the one a transaction callback received');
+  }
+  const name = options.collection === undefined ? DEFAULT_COLLECTION : options.collection;
+  if (typeof name !== 'string' || name === '') throw new TypeError('createDbLedger: collection must be a non-empty collection name');
+  if (!Object.hasOwn(client.collections, name)) {
+    throw new TypeError(`createDbLedger: the client declares no collection '${name}' — open the store with idempotencyLedgerModel, or a model that declares it`);
+  }
+  const ttlMs = options.ttlMs === undefined ? DEFAULT_TTL_MS : options.ttlMs;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new TypeError('createDbLedger: ttlMs must be a positive number');
+  let runtime;
+  try {
+    runtime = resolveRuntime(options.runtime);
+  }
+  catch (error) {
+    throw new TypeError(`createDbLedger: runtime: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const clock = options.now === undefined ? runtime.now : options.now;
+  if (typeof clock !== 'function') throw new TypeError('createDbLedger: now must be a function');
+  // the memory ledger's clock discipline: one clock judges a record from
+  // claim to expiry — its own when given, else the binding's instants
+  const ownClock = options.now !== undefined || options.runtime !== undefined;
+  /** @type {number | null} */
+  let latest = null;
+  /** @param {number | undefined} given */
+  const instant = (given) => {
+    if (typeof given === 'number') {
+      if (!ownClock) latest = latest === null ? given : Math.max(latest, given);
+      return given;
+    }
+    return ownClock || latest === null ? clock() : latest;
+  };
+  // a root client owns a connection and takes the write lock up front; a
+  // transaction client is inside one already and nests a savepoint, so
+  // the settlement commits with the host's own writes
+  const root = typeof client.close === 'function';
+  /** @param {(tx: any) => Promise<any>} fn */
+  const inside = (fn) => (root ? client.transaction(fn, { mode: 'immediate' }) : client.transaction(fn));
+  /** @param {any} tx */
+  const rows = (tx) => tx.collections[name];
+
+  /**
+   * Settle the started record a ref names, or refuse (`JL2007`).
+   * @param {unknown} ref
+   * @param {{ status: 'committed' | 'failed', response: unknown, retryable: boolean | null }} changes
+   * @param {number | undefined} now
+   */
+  function settle(ref, changes, now) {
+    const r = /** @type {any} */ (ref);
+    if (r === null || typeof r !== 'object' || typeof r.id !== 'string' || typeof r.generation !== 'string') {
+      return Promise.reject(stale(ref, 'a ref is { id, generation } as this ledger issued it'));
+    }
+    const at = instant(now);
+    return inside(async (tx) => {
+      const c = rows(tx);
+      const record = await c.get(r.id);
+      if (record === undefined || record.generation !== r.generation || record.status !== 'started') {
+        throw stale(ref, 'the key expired, was reclaimed under a newer generation, or was settled already');
+      }
+      await c.put({ ...record, ...changes, updatedAt: at }, r.id);
+    });
+  }
+
+  return Object.freeze({
+    claim({ op, scope, key, hash, now }) {
+      const at = instant(now);
+      const id = ledgerId(op, scope, key);
+      return inside(async (tx) => {
+        const c = rows(tx);
+        const existing = await c.get(id);
+        if (existing !== undefined) {
+          if (existing.expiresAt <= at) await c.delete(id);
+          else if (existing.hash !== hash) return { state: 'mismatch' };
+          else if (existing.status === 'started') return { state: 'in-progress' };
+          else if (existing.status === 'committed') return { state: 'replay', response: existing.response };
+          else if (existing.retryable !== true && existing.response !== null) return { state: 'replay', response: existing.response };
+          else await c.delete(id); // a retryable failure: the key runs again
+        }
+        const generation = runtime.uuid();
+        await c.insert({
+          id, generation, op, scope, key, hash, status: 'started', response: null, retryable: null,
+          createdAt: at, updatedAt: at, expiresAt: at + ttlMs,
+        });
+        return { state: 'new', ref: Object.freeze({ id, generation }) };
+      });
+    },
+    commit(ref, response, now = undefined) {
+      return settle(ref, { status: 'committed', response, retryable: null }, now);
+    },
+    fail(ref, retryable, response = undefined, now = undefined) {
+      return settle(ref, { status: 'failed', response: response === undefined ? null : response, retryable: retryable === true }, now);
+    },
+    lookup({ op, scope, key, now = undefined }) {
+      const at = instant(now);
+      const id = ledgerId(op, scope, key);
+      return inside(async (tx) => {
+        const c = rows(tx);
+        const record = await c.get(id);
+        if (record === undefined) return null;
+        if (record.expiresAt <= at) {
+          await c.delete(id);
+          return null;
+        }
+        return record; // the store's fresh document: nothing of the ledger's own
+      });
+    },
+    sweep(now = undefined) {
+      const at = instant(now);
+      return inside(async (tx) => {
+        const c = rows(tx);
+        const expired = await c.where((/** @type {any} */ r) => r.expiresAt.le(at)).select((/** @type {any} */ r) => r.id).toArray();
+        for (const id of expired) await c.delete(id);
+        return expired.length;
+      });
+    },
+  });
+}

package/src/db/open.js

@@ -55,21 +55,69 @@ export async function open(model, options) {
     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));
-  }
+
+  /**
+   * The typed handles over ONE store view — the root store, or the one
+   * a transaction callback received. Building them from the same two
+   * constructors is what keeps a transaction's `entities.X` the same
+   * surface, with the same inference, as the client's own.
+   * @param {any} over
+   */
+  const handlesOf = (over) => {
+    const entities = {};
+    for (const name of over.roots ?? []) {
+      setObjectMember(entities, name, createEntityHandle(over, name));
+    }
+    const collections = {};
+    for (const name of Object.keys(model.collections ?? {})) {
+      setObjectMember(collections, name, createCollectionHandle(over, name));
+    }
+    return { entities: Object.freeze(entities), collections: Object.freeze(collections) };
+  };
+
+  /**
+   * The client a transaction callback receives: the same shape as the
+   * root client, over the store that is INSIDE the transaction. Its
+   * handles run as the transaction's owner rather than waiting for a
+   * commit they are part of, and its `transaction` nests.
+   *
+   * Built per transaction, because the handles bind to the store view —
+   * and the whole point of a transaction's own unit of work is that two
+   * handlers do not share one.
+   * @param {any} tx - the store the callback received
+   */
+  const transactionClient = (tx) => {
+    /** @type {Record<string, any>} */
+    const inner = {
+      store: tx,
+      capabilities: tx.capabilities,
+      ...handlesOf(tx),
+      transaction: (fn) => tx.transaction((nested) => fn(transactionClient(nested))),
+      // the named-savepoint group (MODEL-FORMAT §5.2), forwarded as it
+      // is: partial rollback belongs to the transaction that owns the
+      // connection, so the root client deliberately has no twin
+      savepoints: tx.savepoints,
+    };
+    if (tx.saveChanges !== undefined) {
+      inner.saveChanges = () => tx.saveChanges();
+      inner.live = (source, liveOptions) => registerLive(tx.live, source, liveOptions);
+    }
+    return Object.freeze(inner);
+  };
+
   /** @type {Record<string, any>} */
   const client = {
     store,
     capabilities: store.capabilities,
-    entities: Object.freeze(entities),
-    collections: Object.freeze(collections),
-    transaction: (fn) => store.transaction(fn),
+    ...handlesOf(store),
+    // A transaction gets its own unit of work by default: two handlers
+    // on one client then hold two records for the same entity key and
+    // neither can see the other's pending state. `unitOfWork: 'shared'`
+    // opts back into the store's, for a caller who staged changes
+    // outside the transaction and means to save them inside it.
+    transaction: (fn, transactionOptions) => store.transaction(
+      (tx) => fn(transactionClient(tx)),
+      { unitOfWork: 'own', ...transactionOptions }),
     close: (closeOptions) => store.close(closeOptions),
   };
   // the unit of work and entity live queries exist exactly when the

package/src/errors.js

@@ -27,7 +27,7 @@ export const LINQ_CODES = Object.freeze({
   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',
+  JL0105: 'a relation hop cannot lower: a composite or undeclared key, an incomplete many-to-many entry, or a malformed relation record',
   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',
@@ -36,6 +36,8 @@ export const LINQ_CODES = Object.freeze({
   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',
+  JL2007: 'a ledger settlement named a ref that settles no started record',
+  JL2008: 'a federated fetch reached its row or byte budget',
 });
 
 /**
@@ -136,10 +138,17 @@ export class LinqBuildError extends CodedError {
  *    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)
+ *  - `JL2007` — `createDbLedger`'s `commit`/`fail` named a ref that
+ *    settles no started record: the key expired, was reclaimed under a
+ *    newer generation, or was settled already (DB-CLIENT.md §2.6)
  *  - `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
+ *  - `JL2008` — a `federate()` fetch reached one side's row or byte
+ *    budget. A budget is a REFUSAL, not a spill: the fetch stops at the
+ *    row that would have broken it, every cursor it opened is closed,
+ *    and the reason names the side and the bound (QUERY-PEN.md §13)
  */
 export class LinqRuntimeError extends CodedError {
   /**

package/src/expression.js

@@ -512,10 +512,18 @@ function checkRelation(relation, member) {
       + '({ to, kind, via, fkEntity, fkTargets, targetKey } — MODEL-FORMAT §10.1)');
   }
   if (relation.kind === 'manyToMany') {
-    throw new LinqBuildError('JL0105',
-      `'${member}' is a many-to-many relation: the join table '${relation.joinTable}' is not a `
-      + 'queryable root in this version, so the hop has no phrase to lower to — read the '
-      + `memberships with load({ include: { ${member}: true } })`);
+    // the join table is a read-only query root (MODEL-FORMAT §10.7), so
+    // the hop lowers through it — provided the relation record names
+    // the row's two columns and the key each references
+    if (typeof relation.joinTable !== 'string' || typeof relation.ownColumn !== 'string'
+      || typeof relation.ownKey !== 'string' || typeof relation.targetColumn !== 'string'
+      || typeof relation.targetKey !== 'string') {
+      throw new LinqBuildError('JL0105',
+        `'${member}' is a many-to-many relation whose entry does not name its join row's `
+        + 'columns ({ joinTable, ownColumn, ownKey, targetColumn, targetKey } — '
+        + 'MODEL-FORMAT §10.1), so the hop has no phrase to lower to');
+    }
+    return;
   }
   if (relation.kind !== 'oneToOne' && relation.kind !== 'oneToMany') {
     throw new LinqBuildError('JL0105',
@@ -599,6 +607,24 @@ function startHop(target, member) {
     many = true;
     fan = true;
   }
+  if (relation.kind === 'manyToMany') {
+    // TWO links, numbered in chain order: the join row that names the
+    // membership, then the target row it names. The join table is a
+    // query root of its own, carrying exactly the two key columns (§10.7)
+    const joinBinding = `r${sink.next++}`;
+    const binding = `r${sink.next++}`;
+    chain.push({ binding: joinBinding, source: entityRootOf(relation.joinTable),
+      where: { $eq: [`$${joinBinding}${memberSegment(relation.ownColumn)}`,
+        `${subject}${memberSegment(relation.ownKey)}`] } });
+    chain.push({ binding, source: entityRootOf(relation.to),
+      where: { $eq: [`$${binding}${memberSegment(relation.targetKey)}`,
+        `$${joinBinding}${memberSegment(relation.targetColumn)}`] } });
+    sink.hops.push({ member, kind: relation.kind, binding });
+    const manyTarget = resolve(relation.to);
+    return makeHop({ chain, ret: '$' + binding, many: true, fan },
+      target.epoch,
+      manyTarget === undefined ? undefined : { table: manyTarget, resolve, sink });
+  }
   const binding = `r${sink.next++}`;
   const where = relation.kind === 'oneToMany'
     ? { $eq: [`$${binding}${memberSegment(relation.via)}`, `${subject}${memberSegment(relation.targetKey)}`] }