@ultimat3/query 1.1.0 → 2.0.0

package/src/source.ts

@@ -5,9 +5,15 @@
  * answer these four questions.
  */
 import type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
-import { compareRows, compareValues, matchesFilters } from './shape';
+import { compareRows, compareValues, isNull, matchesFilters, totalOrder } from './shape';
 import { columnOf } from './stable';
 
+/** Nothing matches. `in ()` is a syntax error in Postgres, so an empty set needs a constant. */
+const NEVER = '1 = 0';
+
+/** Binds a value and answers the `$n` that reads it. Nothing here interpolates a value. */
+type Slot = (value: unknown) => string;
+
 export interface SqlText {
   readonly sql: string;
   readonly params: readonly unknown[];
@@ -19,6 +25,12 @@ export interface SqlSource<TRow> {
   execute(): Promise<readonly TRow[]>;
   /** Required for `live: true`: the matcher patches from the shape, not from SQL. */
   shape(): QueryShape;
+  /**
+   * The same read served in `totalOrder` — the declared keys, then `id`. A live read is built
+   * through this, because the matcher places a patched row by that order and a reconnect resumes
+   * by it. Absent means the source already serves one order it can be resumed in.
+   */
+  total?(): SqlSource<TRow>;
   /** Cursor push-down. Absent means pagination slices after execution. */
   seek?(after: SeekKey | null, limit: number): SqlSource<TRow>;
 }
@@ -42,10 +54,16 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
     private readonly rowLimit: number | null,
     private readonly after: SeekKey | null,
     private readonly unsupported: readonly string[],
-    /** Set by `seek()`. Only a paged read pays for the id tiebreak — see `pageOrder()`. */
-    private readonly paged: boolean = false,
+    /** Set by `seek()` and `total()` — the only reads that pay for the id tiebreak. */
+    private readonly totalized: boolean = false,
   ) {}
 
+  /**
+   * One equality filter per key, and the clauses come out in **lexical key order** — not the order
+   * the object literal was typed in. The generated text is something callers compare across runs:
+   * `explain()` prints it, `LiveQuery.sqlText` caches it, and tests pin it. Reordering two keys in
+   * a call site must not rewrite the statement.
+   */
   where(equals: Readonly<Record<string, unknown>>): Builder<TRow> {
     const added = Object.keys(equals)
       .sort()
@@ -71,7 +89,15 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   }
 
   seek(after: SeekKey | null, limit: number): Builder<TRow> {
-    return this.derive({ after, rowLimit: limit, paged: true });
+    return this.derive({ after, rowLimit: limit, totalized: true });
+  }
+
+  /**
+   * The declared keys plus the `id` tiebreak, with no cursor and no window — page one of the
+   * ordering a paged read already serves. `seek()` implies it; a live read asks for it directly.
+   */
+  total(): Builder<TRow> {
+    return this.derive({ totalized: true });
   }
 
   shape(): QueryShape {
@@ -86,24 +112,12 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
 
   toSQL(): SqlText {
     const params: unknown[] = [];
-    const clauses = this.filters.map((filter) => {
-      if (filter.op === 'in' && Array.isArray(filter.value)) {
-        const slots = filter.value.map((item) => {
-          params.push(item);
-          return `$${params.length}`;
-        });
-        return `"${filter.column}" in (${slots.join(', ')})`;
-      }
-      params.push(filter.value);
-      return `"${filter.column}" ${filter.op} $${params.length}`;
-    });
-    if (this.after !== null) clauses.push(this.seekClause(this.after, params));
+    const slot = slotter(params);
+    const clauses = this.filters.map((filter) => filterClause(filter, slot));
+    if (this.after !== null) clauses.push(this.seekClause(this.after, slot));
     const where = clauses.length > 0 ? ` where ${clauses.join(' and ')}` : '';
-    const keys = this.pageOrder();
-    const order =
-      keys.length > 0
-        ? ` order by ${keys.map((key) => `"${key.column}" ${key.direction}`).join(', ')}`
-        : '';
+    const keys = this.servedOrder();
+    const order = keys.length > 0 ? ` order by ${keys.map(orderTerm).join(', ')}` : '';
     const limit = this.rowLimit === null ? '' : ` limit ${this.rowLimit}`;
     return { sql: `select * from "${this.entity}"${where}${order}${limit}`, params };
   }
@@ -111,7 +125,7 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   async execute(): Promise<readonly TRow[]> {
     const source = typeof this.rows === 'function' ? await this.rows() : this.rows;
     let result = source.filter((row) => matchesFilters(row, this.filters));
-    const keys = this.pageOrder();
+    const keys = this.servedOrder();
     if (keys.length > 0) {
       result = [...result].sort((a, b) => compareRows(a, b, keys));
     }
@@ -128,20 +142,14 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   }
 
   /**
-   * The ordering a page is actually served in: the declared keys, then `id` to make it total.
+   * The ordering this read is actually served in — `totalOrder`, so the SQL, the in-memory sort,
+   * `seekClause()` and the matcher all read one list.
    *
-   * Without the tiebreak the database is free to return two rows with the same sort value in
-   * either order, while `seekClause()` decides the next page as if they had been ordered by id —
-   * so one of the pair comes back twice and the other never does. `execute()` had the same split,
-   * sorting by the declared keys and then filtering with the id-aware predicate. One order, read
-   * by the SQL, the in-memory sort and the predicate alike, is what closes it.
-   *
-   * Only a paged read pays for it: an unpaginated `from()` over rows that have no `id` must keep
-   * generating exactly the SQL it was asked for.
+   * Only a read that asked for it pays: `seek()` for a page, `total()` for a live window. A plain
+   * `from()` over rows that have no `id` must keep generating exactly the SQL it was asked for.
    */
-  private pageOrder(): readonly OrderKey[] {
-    if (!this.paged || this.ordersById) return this.order;
-    return [...this.order, { column: 'id', direction: 'asc' }];
+  private servedOrder(): readonly OrderKey[] {
+    return this.totalized ? totalOrder(this.order) : this.order;
   }
 
   /**
@@ -152,25 +160,28 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
    * a mixed listing repeated and skipped rows while `execute()` did the right
    * thing. Same shape as `@ultimat3/entity`'s `seekSql`: one meaning, two drivers.
    */
-  private seekClause(after: SeekKey, params: unknown[]): string {
-    const slot = (value: unknown): string => {
-      params.push(value);
-      return `$${params.length}`;
-    };
-    // The same `pageOrder()` the ORDER BY is built from, so the predicate can only ever describe
+  private seekClause(after: SeekKey, slot: Slot): string {
+    // The same `servedOrder()` the ORDER BY is built from, so the predicate can only ever describe
     // the order the rows actually arrive in. The tiebreak is absent when the ordering already
     // named `id`: a second `id` term compares the key to itself, can never be true, and is dead
     // SQL an agent then has to reason about.
-    const keys = this.pageOrder();
+    const keys = this.servedOrder();
     const values = this.ordersById ? [...after.key] : [...after.key, after.id];
-    const terms = keys.map((key, index) => {
+    const terms: string[] = [];
+    for (const [index, key] of keys.entries()) {
+      const value = values[index];
+      // Under `nulls last` nothing sorts after a NULL, so this key's term is dead SQL — dropped
+      // rather than emitted, exactly as the doubled id tiebreak is. The remaining keys still
+      // carry the page: the equality prefix below reaches them as `"col" is null`.
+      if (isNull(value) && key.direction === 'asc') continue;
       const equal = keys
         .slice(0, index)
-        .map((earlier, position) => `"${earlier.column}" = ${slot(values[position])}`);
-      const compare = `"${key.column}" ${key.direction === 'desc' ? '<' : '>'} ${slot(values[index])}`;
-      return `(${[...equal, compare].join(' and ')})`;
-    });
-    return `(${terms.join(' or ')})`;
+        .map((earlier, position) => equalTerm(earlier.column, values[position], slot));
+      terms.push(`(${[...equal, afterTerm(key, value, slot)].join(' and ')})`);
+    }
+    // Every key null under an ascending order is the very end of the listing. Only reachable
+    // from a hand-built cursor — `seekKeyOf` refuses a row with no id — but `()` is a syntax error.
+    return terms.length === 0 ? NEVER : `(${terms.join(' or ')})`;
   }
 
   private derive(patch: Partial<BuilderState>): Builder<TRow> {
@@ -182,18 +193,95 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
       patch.rowLimit === undefined ? this.rowLimit : patch.rowLimit,
       patch.after === undefined ? this.after : patch.after,
       patch.unsupported ?? this.unsupported,
-      patch.paged ?? this.paged,
+      patch.totalized ?? this.totalized,
     );
   }
 }
 
+const slotter =
+  (params: unknown[]): Slot =>
+  (value) => {
+    params.push(value);
+    return `$${params.length}`;
+  };
+
+/**
+ * One filter, in SQL that means what `matchesFilter` means.
+ *
+ * `= $n` with a NULL parameter is unknown in Postgres and unknown is never true, so
+ * `where({ deletedAt: null })` matched every live row in memory and no row at all in the
+ * database. `is null` / `is distinct from` is the pair `@ultimat3/entity`'s `predicateSql`
+ * already emits — one meaning, two sources. An ordering operator needs no case: `"col" > $n`
+ * against a NULL matches nothing, which is what `ordered()` now answers too.
+ */
+function filterClause(filter: Filter, slot: Slot): string {
+  const column = `"${filter.column}"`;
+  if (filter.op === 'in') {
+    // `in` reads a list or nothing. A non-array operand matches no row in memory, so the SQL says
+    // the same constant — the fallback below would emit `"col" in $n`, which is a syntax error a
+    // driver reports instead of the empty result the two sources agree on.
+    if (!Array.isArray(filter.value)) return NEVER;
+    const present = filter.value.filter((item) => !isNull(item));
+    const list =
+      present.length === 0
+        ? null
+        : `${column} in (${present.map((item) => slot(item)).join(', ')})`;
+    const nulls = present.length === filter.value.length ? null : `${column} is null`;
+    if (list === null) return nulls ?? NEVER;
+    return nulls === null ? list : `(${list} or ${nulls})`;
+  }
+  if (filter.op === '=') return equalTerm(filter.column, filter.value, slot);
+  if (filter.op === '!=') {
+    return isNull(filter.value)
+      ? `${column} is not null`
+      : `${column} is distinct from ${slot(filter.value)}`;
+  }
+  return `${column} ${filter.op} ${slot(filter.value)}`;
+}
+
+/**
+ * NULL's place in the ordering, written down rather than inherited. Postgres already defaults
+ * to `nulls last` under `asc` and `nulls first` under `desc` — that is the rule `compareValues`
+ * implements, so the in-memory sort, the live matcher and `seekClause` below can only agree
+ * with it. Saying it out loud is what keeps a driver whose default differs from re-opening the
+ * divergence, and it is what an agent reads when a nullable sort key surprises it.
+ */
+function orderTerm(key: OrderKey): string {
+  const nulls = key.direction === 'desc' ? 'nulls first' : 'nulls last';
+  return `"${key.column}" ${key.direction} ${nulls}`;
+}
+
+/** `= $n` never matches a NULL — the same defect as a filter, one page later. */
+function equalTerm(column: string, value: unknown, slot: Slot): string {
+  return isNull(value) ? `"${column}" is null` : `"${column}" = ${slot(value)}`;
+}
+
+/**
+ * Strictly past this key's value, under the ordering `orderTerm` writes.
+ *
+ * `desc` is `nulls first`: every non-null row follows a NULL cursor, and no NULL row follows a
+ * value — which `"col" < $n` already excludes. `asc` is `nulls last`: the NULLs follow every
+ * value, so a value cursor has to reach them explicitly or page two ends at the first NULL.
+ */
+function afterTerm(key: OrderKey, value: unknown, slot: Slot): string {
+  const column = `"${key.column}"`;
+  if (key.direction === 'desc') {
+    return isNull(value) ? `${column} is not null` : `${column} < ${slot(value)}`;
+  }
+  const after = `${column} > ${slot(value)}`;
+  // `id` is the tiebreak that makes the order total and `seekKeyOf` refuses a row without one,
+  // so `"id" is null` is unsatisfiable: reaching for it would be dead SQL on every paged read,
+  // and an `or` the planner has to defeat before it can seek the index.
+  return key.column === 'id' ? after : `(${after} or ${column} is null)`;
+}
+
 interface BuilderState {
   readonly filters: readonly Filter[];
   readonly order: readonly OrderKey[];
   readonly rowLimit: number | null;
   readonly after: SeekKey | null;
   readonly unsupported: readonly string[];
-  readonly paged: boolean;
+  readonly totalized: boolean;
 }
 
 /**

package/src/sql.ts

@@ -27,7 +27,7 @@ export async function explain<TInput extends StandardSchemaV1, TRow extends obje
   ctx?: Ctx,
 ): Promise<ExplainResult> {
   const source = await sourceFor(target, input, {
-    enforce: false,
+    unenforced: 'explain returns the statement and never a row, and its surfaces are admin-gated',
     ...(ctx === undefined ? {} : { ctx }),
   });
   const text = source.toSQL();
@@ -65,7 +65,7 @@ export async function describeSql(
       continue;
     }
     const source = await sourceFor(target, sample, {
-      enforce: false,
+      unenforced: 'the dashboard listing renders SQL text for a sample input and reads no rows',
       ...(ctx === undefined ? {} : { ctx }),
     });
     entries.push({ query: name, live: target.isLive, sql: source.toSQL().sql });

package/src/stable.ts

@@ -13,8 +13,15 @@ export function stableStringify(value: unknown): string {
   switch (typeof value) {
     case 'string':
       return JSON.stringify(value);
+    // A bare token, never `'null'` and never a quoted string: this output is only ever hashed, so
+    // an unquoted word cannot collide with the `string` branch (which always quotes) while
+    // `'null'` collided with JSON `null` itself — `{ n: NaN }`, `{ n: Infinity }` and `{ n: null }`
+    // fingerprinted identically and shared one cache entry and one cursor scope. `-0` is spelled
+    // out for the same reason: `String(-0)` is `"0"`, so `-0` and `0` were one key too.
     case 'number':
-      return Number.isFinite(value) ? String(value) : 'null';
+      if (Number.isNaN(value)) return 'NaN';
+      if (!Number.isFinite(value)) return value > 0 ? 'Infinity' : '-Infinity';
+      return Object.is(value, -0) ? '-0' : String(value);
     case 'boolean':
       return String(value);
     case 'bigint':
@@ -35,18 +42,22 @@ export function stableStringify(value: unknown): string {
   return `{${entries.join(',')}}`;
 }
 
-/** FNV-1a/32 as hex. Identity of a query shape, never a security boundary. */
-export function fnv1a(input: string): string {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < input.length; i += 1) {
-    hash ^= input.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash.toString(16).padStart(8, '0');
-}
-
+/**
+ * SHA-256, first 16 hex characters — the same primitive and the same width `@ultimat3/realtime`'s
+ * `stableDigest` and `@ultimat3/entity`'s `planScope` already chose, and for the same reason.
+ *
+ * A fingerprint is a SHARING key, not a checksum: it decides which read-cache entry two callers
+ * are served from and which scope a cursor is bound to, over input a client chooses. FNV-1a/32 —
+ * what this was — is 4x10^9 values, brute-forceable offline in seconds, so an attacker could mint
+ * an input that lands on another read's entry or another page's scope. It identifies, and here
+ * identifying IS the boundary.
+ *
+ * The canonical form above is unchanged, so the only thing that moved is the hash: a cursor issued
+ * before this fails its scope check as `X_CURSOR_INVALID` — cleanly, with "request the first page
+ * again" as its fix — and a warm read cache is cold once.
+ */
 export function fingerprint(value: unknown): string {
-  return fnv1a(stableStringify(value));
+  return new Bun.CryptoHasher('sha256').update(stableStringify(value)).digest('hex').slice(0, 16);
 }
 
 /** Column read that works for interfaces without an index signature. */

package/src/tags.ts

@@ -1,17 +0,0 @@
-/**
- * Cache tags stay opaque here — they belong to @ultimat3/cache. This package only
- * needs the wire string per tag so a read's key can be found by the invalidation
- * graph an action's `invalidates` drives.
- */
-
-import type { CacheTag } from '@ultimat3/cache';
-import { serializeTag } from '@ultimat3/cache';
-
-export function tagKey(value: CacheTag): string {
-  return serializeTag(value);
-}
-
-/** Sorted + de-duplicated: descriptor output must not depend on declaration order. */
-export function tagKeys(tags: readonly CacheTag[]): readonly string[] {
-  return [...new Set(tags.map(tagKey))].sort();
-}