@jarenjs/linq 0.56.0 → 0.67.0

package/types/db.d.ts

@@ -13,16 +13,18 @@
  * subpath has them; no other subpath of the package refers to them.
  */
 
-import type { AsyncSequence, AsyncExplanation, Expr, BoolExpr, OrderOptions } from './index.js';
+import type { AsyncSequence, AsyncExplanation, Expr, ExprBase, BoolExpr, OrderOptions } from './index.js';
 import type { ModelDocument, CollectionSpec, InferMeta } from './model.js';
 import type {
   EntityMeta, MetaMap, TypedEntitySet, TypedStore, TypedLoadSpec, Loaded,
 } from '@jarenjs/db/typed';
 import type {
   Collection, ExecuteOptions, LiveOptions, LiveQuery, LoadExplanation, OpenStoreOptions,
-  SaveReport, Store, StoreCapabilities,
+  SavepointController, SaveReport, StoreCapabilities, TransactionStore,
+  EntityCursorOptions, QueryCursor, LoadContinuation, Page,
 } from '@jarenjs/db';
 import type { JarenValidator } from '@jarenjs/validate';
+import type { Runtime } from '@jarenjs/core/runtime';
 
 // ————— open —————
 
@@ -110,6 +112,12 @@ export type IncludeSpec<E extends MetaMap<E>, M extends EntityMeta> =
     readonly orderBy?: OrderKey<M['doc']> | readonly OrderKey<M['doc']>[];
     readonly take?: number;
     readonly skip?: number;
+    /** The per-root bounds (MODEL-FORMAT §10.4): rows of this relation
+     * per parent and serialised bytes per parent; crossing one is the
+     * store's `JD2073`, never a truncated graph. `Infinity` spells the
+     * unbounded case (emitted as `null`). */
+    readonly maxRows?: number;
+    readonly maxBytes?: number;
     readonly include?: Includes<E, M>;
   };
 
@@ -118,9 +126,35 @@ export type Includes<E extends MetaMap<E>, M extends EntityMeta> = {
   readonly [K in keyof M['relations'] & string]?: IncludeSpec<E, TargetMeta<E, M, K>>;
 };
 
+/** The order-key VALUE types a graph declared, in order: `orderBy` starts
+ * the tuple, every `thenBy` appends to it. */
+export type OrderOf<S> = S extends { order: infer O extends readonly unknown[] } ? O : [];
+type WithOrder<S, O extends readonly unknown[]> = Omit<S, 'order'> & { order: O };
+
+/** The continuation a page over this graph emits, and `after()` takes:
+ * the declared order-key values as a tuple whose shape follows
+ * `orderBy`/`thenBy` — a two-key ordering needs a two-value `keys` —
+ * plus the row's primary key, the tie-breaker the store appends, and
+ * the ordering's identity. Unsigned and structural (MODEL-FORMAT §10.5):
+ * signing, scoping and expiry are the host's. */
+export type Continuation<S, M extends EntityMeta> = LoadContinuation & {
+  readonly keys: OrderOf<S>;
+  readonly key: M['key'];
+};
+
+/** A page's options over this graph (the store's `PageOptions`, the
+ * continuation typed by the declared ordering). */
+export interface GraphPageOptions<S, M extends EntityMeta> extends EntityCursorOptions {
+  limit?: number;
+  after?: Continuation<S, M>;
+  maxBytes?: number;
+  consistency?: 'live' | 'snapshot';
+}
+
 /** The graph over one entity set: an immutable builder of the `load`
- * spec, typed by what it included. `S` accumulates the include
- * specification `Loaded<>` reads. */
+ * spec, typed by what it included and by what it ordered by. `S`
+ * accumulates the include specification `Loaded<>` reads and the
+ * `order` tuple `after()`/`page()` are typed by. */
 export interface Graph<E extends MetaMap<E>, M extends EntityMeta, S> {
   /** Include one more relation member. (`NoInfer` keeps the spec's
    * callbacks contextually typed while `I` is inferred from the literal —
@@ -130,14 +164,24 @@ export interface Graph<E extends MetaMap<E>, M extends EntityMeta, S> {
   ): Graph<E, M, S & { include: { [P in K]: I } }>;
   /** Filter the root rows; consecutive calls conjoin. */
   where(predicate: (it: Expr<M['doc']>) => BoolExpr | boolean): Graph<E, M, S>;
-  orderBy(key: (it: Expr<M['doc']>) => unknown, options?: OrderOptions): Graph<E, M, S>;
-  orderByDescending(key: (it: Expr<M['doc']>) => unknown, options?: OrderOptions): Graph<E, M, S>;
-  thenBy(key: (it: Expr<M['doc']>) => unknown, options?: OrderOptions): Graph<E, M, S>;
-  thenByDescending(key: (it: Expr<M['doc']>) => unknown, options?: OrderOptions): Graph<E, M, S>;
+  /** Start the ordering: the key's value type opens the `order` tuple. */
+  orderBy<V>(key: (it: Expr<M['doc']>) => ExprBase<V>, options?: OrderOptions): Graph<E, M, WithOrder<S, [V]>>;
+  orderByDescending<V>(key: (it: Expr<M['doc']>) => ExprBase<V>, options?: OrderOptions): Graph<E, M, WithOrder<S, [V]>>;
+  /** Extend the ordering: the key's value type is appended to the tuple. */
+  thenBy<V>(key: (it: Expr<M['doc']>) => ExprBase<V>, options?: OrderOptions): Graph<E, M, WithOrder<S, [...OrderOf<S>, V]>>;
+  thenByDescending<V>(key: (it: Expr<M['doc']>) => ExprBase<V>, options?: OrderOptions): Graph<E, M, WithOrder<S, [...OrderOf<S>, V]>>;
   take(count: number): Graph<E, M, S>;
   skip(count: number): Graph<E, M, S>;
-  /** The keyset cursor (§10.5): the key of the last row of the previous page. */
-  after(cursor: M['key']): Graph<E, M, S>;
+  /** Resume after a continuation (§10.5): the value a `page()` over this
+   * ordering emitted — its `keys` tuple follows the declared ordering,
+   * its `key` is the row's primary key. A bare key is not a continuation. */
+  after(cursor: Continuation<S, M>): Graph<E, M, S>;
+  /** One bounded page over the composite keyset: `{ items, continuation,
+   * hasMore, snapshot }`, never more than `limit` roots or `maxBytes`
+   * serialised bytes; `snapshot` is true only over an immutable ordering
+   * (the primary key), and `consistency: 'snapshot'` over any other is
+   * the store's `JD0036`. Untracked unless `tracking: true`. */
+  page(options?: GraphPageOptions<S, M>): Promise<Page<Loaded<E, M, S>, Continuation<S, M>>>;
   /** The include depth bound (§10.4, default 3). */
   maxDepth(depth: number): Graph<E, M, S>;
   /** The same graph, loaded without registering snapshots. */
@@ -148,6 +192,10 @@ export interface Graph<E extends MetaMap<E>, M extends EntityMeta, S> {
   toJSON(): TypedLoadSpec<E, M>;
   /** `load(spec)`: the store's one statement, typed by the includes. */
   toArray(): Promise<Array<Loaded<E, M, S>>>;
+  /** `loadCursor(spec, options)`: one root graph per pull, its includes
+   * attached and bounded, from the same one statement; `return()`
+   * releases it. Untracked unless `tracking: true` is spelled per call. */
+  cursor(options?: EntityCursorOptions): QueryCursor<Loaded<E, M, S>>;
   /** `explainLoad(spec)`: the SQL, the includes, the pagination strategy. */
   explain(): LoadExplanation;
 }
@@ -161,6 +209,9 @@ export type EntityHandle<E extends MetaMap<E>, M extends EntityMeta> =
     include<K extends keyof M['relations'] & string, const I extends IncludeSpec<E, TargetMeta<E, M, K>> = true>(
       pick: (u: RelationPicker<M>) => Picked<K>, spec?: I | NoInfer<IncludeSpec<E, TargetMeta<E, M, K>>>,
     ): Graph<E, M, { include: { [P in K]: I } }>;
+    /** Open a graph with nothing included: the root clauses, the keyset
+     * continuation and the page over the rows alone. */
+    graph(): Graph<E, M, {}>;
     /** A live query over a chain of this set (the whole set when none
      * is given), through the store's entity-root registration. */
     live<T = M['doc']>(source?: AsyncSequence<T, any> | object, options?: LiveOptions): Promise<TypedLiveQuery<T>>;
@@ -175,6 +226,124 @@ export interface EntityClientMembers {
   live<T>(source: AsyncSequence<T, any> | object, options?: LiveOptions): Promise<TypedLiveQuery<T>>;
 }
 
+// ————— the ledger —————
+
+/** The record `createDbLedger` keeps per `(op, scope, key)`: exactly
+ * `idempotencyLedgerModel`'s (`@jarenjs/contract/ledger`), the
+ * `generation` the fence verifies included. */
+export interface DbLedgerRecord {
+  id: string;
+  generation: string;
+  op: string;
+  scope: string;
+  key: string;
+  hash: string;
+  status: 'started' | 'committed' | 'failed';
+  response: unknown;
+  retryable: boolean | null;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt: number;
+}
+
+/** The ref a `new` claim hands back: the record's id and the generation
+ * the claim minted — portable across processes, stale once the key
+ * expires or is reclaimed. */
+export interface DbLedgerRef {
+  readonly id: string;
+  readonly generation: string;
+}
+
+export type DbClaimResult =
+  | { state: 'new'; ref: DbLedgerRef }
+  | { state: 'replay'; response: unknown }
+  | { state: 'in-progress' }
+  | { state: 'mismatch' };
+
+export interface DbLedgerOptions {
+  /** The declared collection; `'ledger'` (the model's) by default. */
+  collection?: string;
+  /** The retention of a key; 86,400,000 ms by default. */
+  ttlMs?: number;
+  /** The host's runtime record: its `now` is the clock, its `uuid`
+   * mints every generation. */
+  runtime?: Partial<Runtime>;
+  /** The clock; wins over the runtime's. Given neither, the ledger
+   * follows the instants the binding passes. */
+  now?: () => number;
+}
+
+/** The ledger the http binding calls, over the store: structurally the
+ * contract package's `Ledger`, every method asynchronous. A `commit` or
+ * `fail` whose ref settles no started record rejects `JL2007`. */
+export interface DbLedger {
+  claim(claim: { op: string; scope: string; key: string; hash: string; now?: number }): Promise<DbClaimResult>;
+  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<DbLedgerRecord | null>;
+  /** Drop every expired record; answers how many. */
+  sweep(now?: number): Promise<number>;
+}
+
+/** What `createDbLedger` needs of a client: the declared collections
+ * and a transaction — the root client (claims take the write lock up
+ * front, `mode: 'immediate'`) or the one a transaction callback
+ * received (claims and settlements nest in that transaction). */
+export type LedgerClient =
+  | Pick<Client<any, any>, 'collections' | 'transaction' | 'close'>
+  | Pick<TransactionClientOf<any, any>, 'collections' | 'transaction'>;
+
+/** The contract ledger over a declared collection of the client's
+ * store — no import of `@jarenjs/contract`, no driver, the client's
+ * own surface only (DB-CLIENT.md §2.6). A `TypeError` names a client
+ * that is not one, a collection the model does not declare, a bad
+ * `ttlMs` or `now`. */
+export function createDbLedger(client: LedgerClient, options?: DbLedgerOptions): DbLedger;
+
+/** How a transaction relates to the client's unit of work: `'own'` (the
+ * default) gives the callback a tracker of its own, so two handlers on
+ * one client hold two records for the same entity key; `'shared'` opts
+ * back into the client's, for a caller who staged changes outside the
+ * transaction and means to save them inside it. */
+export interface TransactionOptions {
+  readonly unitOfWork?: 'own' | 'shared';
+  /** `'immediate'` takes the write lock up front (`BEGIN IMMEDIATE`),
+   * so a body that reads before it writes never meets the read→write
+   * upgrade busy the handler cannot retry; `'deferred'` (the default)
+   * is the savepoint as always. A nested `tx.transaction()` is a
+   * savepoint whichever mode the root chose. */
+  readonly mode?: 'deferred' | 'immediate';
+  /** Abandons the call while it is still QUEUED: the callback never
+   * runs and no statement is issued (`JD2064`). */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * The client a transaction callback receives: the same handles, the
+ * same inference, over the store that is INSIDE the transaction.
+ *
+ * `tx.entities.X` and `tx.collections.Y` run as the transaction's owner
+ * and `tx.transaction(...)` nests, while the outer client's handles are
+ * an unrelated caller — one awaited from in here waits for the commit it
+ * is part of, which `JD0012` names rather than hangs on.
+ */
+export type TransactionClientOf<E extends MetaMap<E>, C = Record<string, unknown>> = {
+  /** The scope-bound store — the escape hatch, still inside. It carries
+   * no `close`: a transaction never owns the connection's lifetime. */
+  readonly store: TransactionStore;
+  readonly capabilities: StoreCapabilities;
+  readonly entities: { readonly [K in keyof E & string]: EntityHandle<E, E[K]> };
+  readonly collections: { readonly [K in keyof C & string]: CollectionHandle<C[K]> };
+  /** Nest through this transaction's savepoint. */
+  transaction<R>(fn: (tx: TransactionClientOf<E, C>) => R | Promise<R>): Promise<Awaited<R>>;
+  /** Named partial rollback (MODEL-FORMAT §5.2) — the store's
+   * `tx.savepoints`, forwarded unchanged: create, roll back to and
+   * release a checkpoint by label without a sentinel exception. Only a
+   * live transaction has it; the root client deliberately has no twin,
+   * and a handle kept past its callback is `JD2070`. */
+  readonly savepoints: SavepointController;
+} & ([keyof E] extends [never] ? {} : EntityClientMembers);
+
 /** The client: one frozen record of handles per declared name, the
  * store beneath it, and the pass-throughs. */
 export type Client<E extends MetaMap<E>, C = Record<string, unknown>> = {
@@ -183,6 +352,15 @@ export type Client<E extends MetaMap<E>, C = Record<string, unknown>> = {
   readonly capabilities: StoreCapabilities;
   readonly entities: { readonly [K in keyof E & string]: EntityHandle<E, E[K]> };
   readonly collections: { readonly [K in keyof C & string]: CollectionHandle<C[K]> };
-  transaction<R>(fn: (store: Store) => R | Promise<R>): Promise<Awaited<R>>;
+  /** A transaction, with a typed client of its own. */
+  transaction<R>(fn: (tx: TransactionClientOf<E, C>) => R | Promise<R>,
+    options?: TransactionOptions): Promise<Awaited<R>>;
   close(options?: { graceMs?: number }): Promise<void>;
 } & ([keyof E] extends [never] ? {} : EntityClientMembers);
+
+/** Author a logical envelope using the DB's canonical format validator. */
+export function defineReplication(header: Omit<import('@jarenjs/db').ReplicationEnvelope, '$replication' | 'operations'>): {
+  change(table: string, key: string, before: Record<string, unknown> | null, after: Record<string, unknown> | null): ReturnType<typeof defineReplication>;
+  toDocument(): import('@jarenjs/db').ReplicationEnvelope;
+  toJSON(): import('@jarenjs/db').ReplicationEnvelope;
+};

package/types/index.d.ts

@@ -475,6 +475,13 @@ export interface Provider<T = unknown> {
 export interface AsyncProvider<T = unknown> {
   readonly __item?: T;
   execute(document: unknown, options: { externals: Record<string, unknown> }): unknown | Promise<unknown>;
+  /** The cursor protocol, optional: the same document as an item
+   * cursor, one item per pull, `return()` releasing whatever it holds.
+   * A `for await` over the chain hands its pushed document here when
+   * the provider offers it, so iteration never materialises what the
+   * provider can stream; a provider without it is run whole. */
+  cursor?(document: unknown, options: { externals: Record<string, unknown> }):
+    AsyncIterator<unknown> & { return(): Promise<unknown> };
   readonly root?: string;
   readonly roots?: readonly string[];
   readonly scope?: unknown;
@@ -657,6 +664,13 @@ export interface MapAsyncOptions {
 
 export interface AsyncExplanation {
   barriers: { operator: string, reason: string }[];
+  /** What THIS surface does with the item stream: one item at a time, or
+   * a buffer at its first local barrier. Over a provider the pushed
+   * document's own class — a set residual, an external the database
+   * cannot bind — is the provider's `explain(document, { externals:
+   * bindings })` to report, and its cursor carries the same answer. */
+  streaming: 'row' | 'buffered';
+  barrier: { construct: string, reason: string } | null;
   /** The relation hops the chain's callbacks navigated (as `Explanation`). */
   hops: Hop[];
   /** The values `params()` bound, by name (as `Explanation`). */
@@ -770,6 +784,57 @@ export function fromAsync<T>(
   options?: LinqOptions,
 ): AsyncSequence<T, {}>;
 
+/** One side of a federation, as `explain()` reports it (§12.1). */
+export interface FederatedSide {
+  readonly source: string;
+  readonly root: string;
+  readonly estimatedRows: number | null;
+  /** The join key on this side, as the document spells it. */
+  readonly key: string;
+  /** The document this side's own source is asked. */
+  readonly document: unknown;
+  /** Whether this side is pulled row by row, or answered whole. */
+  readonly streaming: 'row' | 'buffered';
+}
+
+/** What a federated document will do, without doing any of it (§12.1). */
+export interface FederationPlan {
+  readonly strategy: 'hash';
+  readonly budget: { readonly maxRows: number; readonly maxBytes: number };
+  readonly build: FederatedSide;
+  readonly probe: FederatedSide;
+  /** The join itself is the engine's, over the two reduced sides. */
+  readonly resident: { readonly document: unknown };
+}
+
+/** One named source of a federation: an ordinary provider source whose
+ * root is `$.<name>[*]`, sharing one scope with its siblings — which is
+ * what admits the join the federation then executes. */
+export interface FederatedSource<T = unknown> extends AsyncProvider<T> {
+  explain(document: unknown): FederationPlan;
+  readonly root: string;
+}
+
+/** The explicit cross-source boundary (§12.1).
+ *
+ * A query document reads one input, and an ordinary join across two
+ * unrelated sources stays `JL0005`. `federate()` is the one way to opt
+ * out of that, by naming the sources and the bounds together: each
+ * side's own filters and projection run at its source, the smaller side
+ * fills a bounded hash table, the other is probed against it, and the
+ * caller's own document decides over the two reduced sets. A side that
+ * reaches `maxRows` or `maxBytes` raises `JL2008` at the row that would
+ * have broken the bound. */
+export function federate(spec: {
+  sources: Record<string, AsyncProvider | { provider: AsyncProvider; estimatedRows?: number }>;
+  maxRows: number;
+  maxBytes: number;
+  strategy?: 'hash';
+}): {
+  source<T = unknown>(name: string): FederatedSource<T>;
+  readonly names: readonly string[];
+};
+
 /** The push→pull adapter for feed/end readers (§12). */
 export function createPushQueue<T = unknown>(options?: { highWaterMark?: number }): {
   feed(value: T): boolean;

package/types/model.d.ts

@@ -328,11 +328,44 @@ export type IndexPath<D> = ((doc: Expr<D>) => unknown) | string | readonly (((do
  * a composite, or a JSONPath string; default name `by_<segments>`. */
 export function index<D = unknown>(path: IndexPath<D>, options?: IndexOptions): IndexSpec<D>;
 
+/** One node of an index expression: a member (a lambda or a JSONPath
+ * string), a JSON scalar, or a call to a function the HOST declares. */
+export type ExpressionNode<D = unknown> =
+  | ((doc: Expr<D>) => unknown)
+  | string
+  | number
+  | boolean
+  | { member: ((doc: Expr<D>) => unknown) | string }
+  | { value: string | number | boolean }
+  | { call: string; args?: readonly ExpressionNode<D>[] };
+
+/** One index over a COMPUTED value. */
+export interface ExpressionIndexSpec<D = unknown> {
+  readonly __doc?: D;
+  readonly name: string;
+  readonly expression: unknown;
+  readonly unique?: boolean;
+}
+
+/**
+ * An index over a computed value: a closed expression over declared
+ * members, JSON scalars and functions the host declares deterministic.
+ *
+ * The function is resolved where the declarations are —
+ * `openStore({ expressions })` — so a name this pen has never heard of
+ * is not an error here; a wrong arity and a missing declaration are
+ * `JD0004` at open, before any DDL. Default name `by_<call>_<members>`.
+ */
+export function expressionIndex<D = unknown>(
+  expression: ExpressionNode<D>,
+  options?: { name?: string; unique?: boolean },
+): ExpressionIndexSpec<D>;
+
 export interface CollectionOptions<D> {
   /** An RFC 6901 pointer, a captured member path (`(d) => d.id` → `/id`), or `null` (the store allocates). */
   key?: string | ((doc: Expr<D>) => unknown) | null;
   identity?: 'caller' | 'uuid' | 'integer';
-  indexes?: readonly IndexSpec<D>[];
+  indexes?: readonly (IndexSpec<D> | ExpressionIndexSpec<D>)[];
   renamedFrom?: string;
 }