@ultimat3/query 20.2.1 → 22.0.0

package/src/openapi.ts

@@ -16,6 +16,7 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
+import { RECORDS_OPENAPI_HEADER, recordEnvelopeSchema } from '@ultimat3/core';
 import type { SchemaNode } from '@ultimat3/schema';
 import { nodeToJsonSchema, tryIntrospect } from '@ultimat3/schema';
 import { isExposed } from './mcp-tool';
@@ -24,6 +25,7 @@ import { MAX_PAGE_SIZE, PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
 import { policyCapability } from './policy-gate';
 import type { AnyQuery } from './query';
 import { queryName } from './read';
+import { answersRecords } from './record-answer';
 import { listQueries } from './registry';
 
 /**
@@ -37,6 +39,24 @@ const QUERY_TAG = 'query';
 
 export type OpenApiPathItem = Record<string, unknown>;
 
+/**
+ * Two shapes, decided by the request: the bare rows every client read before the controls
+ * existed, and the page envelope when `_first` is sent. `oneOf` and not a second operation — it is
+ * one route, one policy evaluation, one URL prefix.
+ */
+const ANSWERS: readonly Record<string, unknown>[] = [
+  { type: 'array', items: {} },
+  {
+    type: 'object',
+    required: ['rows', 'endCursor', 'hasNextPage'],
+    properties: {
+      rows: { type: 'array', items: {} },
+      endCursor: { type: ['string', 'null'] },
+      hasNextPage: { type: 'boolean' },
+    },
+  },
+];
+
 /** `{ [path]: { get: operation } }` for every registered read, name-sorted like the actions. */
 export function queryOpenApiPaths(
   queries: readonly AnyQuery[] = listQueries(),
@@ -70,22 +90,14 @@ export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknow
             // Two shapes, decided by the request: the bare rows every client read before the
             // controls existed, and the page envelope when `_first` is sent. `oneOf` and not a
             // second operation — it is one route, one policy evaluation, one URL prefix.
-            schema: {
-              oneOf: [
-                { type: 'array', items: {} },
-                {
-                  type: 'object',
-                  required: ['rows', 'endCursor', 'hasNextPage'],
-                  properties: {
-                    rows: { type: 'array', items: {} },
-                    endCursor: { type: ['string', 'null'] },
-                    hasNextPage: { type: 'boolean' },
-                  },
-                },
-              ],
-            },
+            // A read declaring an entity's `rows:` ALWAYS answers the envelope, with the same two
+            // shapes under `data` — core's one description, shared with the action projection.
+            schema: answersRecords(target.rows)
+              ? recordEnvelopeSchema({ oneOf: ANSWERS })
+              : { oneOf: ANSWERS },
           },
         },
+        ...(answersRecords(target.rows) ? { headers: RECORDS_OPENAPI_HEADER } : {}),
       },
       // `X_INPUT_INVALID` is the search string failing the read's own schema, or a page control
       // outside its bound; `X_CURSOR_INVALID` is an `_after` that is not one of this read's. Both

package/src/page-controls.ts

@@ -12,11 +12,9 @@
 // `input-shape.ts` refuses a declaration that reaches for it, so the two names can never collide.
 
 import { QueryInputInvalidError } from './errors';
+import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
 
-/** `?_first=20` — the page size. Present is what makes the route answer a `Page`. */
-export const PAGE_FIRST_KEY = '_first';
-/** `?_after=<cursor>` — the signed cursor the previous page's `endCursor` carried. */
-export const PAGE_AFTER_KEY = '_after';
+export { PAGE_AFTER_KEY, PAGE_FIRST_KEY };
 export const PAGE_CONTROL_KEYS: readonly string[] = [PAGE_FIRST_KEY, PAGE_AFTER_KEY];
 
 /**

package/src/page-keys.ts

@@ -0,0 +1,9 @@
+// The two search-string keys that turn `GET /_x/query/<name>` into a page — and nothing else. A
+// leaf apart from `page-controls.ts` because that module refuses a bad value, which means it imports
+// this package's `errors.ts`, which registers the whole code table at import: the browser client
+// that only SPELLS the keys must not carry it. `page-controls.ts` re-exports both names.
+
+/** `?_first=20` — the page size. Present is what makes the route answer a `Page`. */
+export const PAGE_FIRST_KEY = '_first';
+/** `?_after=<cursor>` — the signed cursor the previous page's `endCursor` carried. */
+export const PAGE_AFTER_KEY = '_after';

package/src/pagination.ts

@@ -50,13 +50,13 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
   // The scope is this read plus these arguments: a cursor from anywhere else is
   // already `X_CURSOR_INVALID` by the time it gets here.
   const decoded = args.after === undefined ? null : decodeCursor(args.after, hash);
+  const base = await sourceFor(target, input, args);
+  const shape = base.shape();
   // Revived to the types the columns hold, never left as the strings JSON handed back: a `Date`
   // key decoded as an ISO string reaches `compareValues` as text and is compared against the
   // row's own millisecond number, so page two matched nothing at all. See `cursor-value.ts`.
   const after: SeekKey | null =
-    decoded === null ? null : { key: reviveSortKey(decoded.key), id: decoded.id };
-  const base = await sourceFor(target, input, args);
-  const shape = base.shape();
+    decoded === null ? null : seekFromCursor(decoded, shape.orderBy.length);
 
   // `MAX_PAGE_SIZE` lives in `page-controls.ts`: the route checks the same bound at the wire, as
   // a 400, before this `assert` — which is a 500 — can see the number.
@@ -75,7 +75,13 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
     endCursor:
       seek === null
         ? null
-        : encodeCursor({ scope: hash, key: seek.key.map(serializeSortValue), id: seek.id }),
+        : encodeCursor({
+            scope: hash,
+            // The id rides TYPED at the tail of the key — core's `id` slot is a string — so a
+            // numeric or bigint tiebreak compares as a number on the next page, not lexically.
+            key: [...seek.key, seek.id].map(serializeSortValue),
+            id: String(seek.id),
+          }),
     hasNextPage: scoped.length > args.first,
   };
 }
@@ -109,3 +115,16 @@ function inTotalOrder(
   if (after === null) return ordered;
   return ordered.filter((row) => isAfterKey(row, after, shape.orderBy));
 }
+
+/**
+ * The seek a decoded cursor names. A cursor carrying one more key than the ordering has its typed
+ * id at the tail; an older cursor, minted before the id rode there, falls back to the string slot.
+ */
+function seekFromCursor(
+  decoded: { readonly key: readonly unknown[]; readonly id: string },
+  width: number,
+): SeekKey {
+  const key = reviveSortKey(decoded.key);
+  if (key.length !== width + 1) return { key, id: decoded.id };
+  return { key: key.slice(0, width), id: key[width] };
+}

package/src/query.ts

@@ -89,6 +89,15 @@ export interface QueryDef<TInput extends StandardSchemaV1, TRow extends object>
    * is legal — a join reads relations the shape's single `entity` cannot name.
    */
   readonly subscribes?: readonly string[];
+  /**
+   * The row schema, when every row IS an entity's row — `rows: Post.$schema`. Typed against the
+   * row `sql:` answers, so a projection (`from<PostSummary>`) cannot claim a full entity's schema.
+   * It is what the route reads to answer the record envelope (`x-ultimate-records: 1`) so the
+   * page's one store adopts the rows; absent, or unbranded, the wire is the bare rows it has
+   * always been. `sql:` names a table as a STRING, so nothing else carries the schema to derive
+   * from — this key is that carrier, never a `records:` switch.
+   */
+  readonly rows?: StandardSchemaV1<unknown, TRow>;
   sql(input: InferOutput<TInput>, ctx: Ctx): SqlSource<TRow>;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
@@ -179,6 +188,7 @@ export interface AnyQueryDef {
   readonly policy: QueryPolicy;
   readonly live?: boolean;
   readonly subscribes?: readonly string[];
+  readonly rows?: StandardSchemaV1;
   sql(input: unknown, ctx: Ctx): SqlSource<object>;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
@@ -196,6 +206,8 @@ export interface AnyQuery {
   readonly policy: QueryPolicy;
   /** Lifted for the same reason `rateLimit` is: `toLiveQuery` cross-checks it without `defOf`. */
   readonly subscribes?: readonly string[];
+  /** Lifted for the route: whether an answer is a record envelope is decided at projection. */
+  readonly rows?: StandardSchemaV1;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
   /** Lifted so `toQueryRoute` reads the declaration without reaching through `defOf`. */
@@ -240,6 +252,7 @@ export type QueryFacade<TInput extends StandardSchemaV1, TRow extends object> =
   | 'input'
   | 'policy'
   | 'subscribes'
+  | 'rows'
   | 'cache'
   | 'mcp'
   | 'rateLimit'

package/src/record-answer.ts

@@ -0,0 +1,68 @@
+/**
+ * A read's HTTP answer. Decided ONCE per query, at projection, from its `rows:` schema — the rule
+ * `@ultimat3/action`'s `record-wire.ts` already follows: a query whose `rows:` is an entity row
+ * schema ALWAYS answers `{ data, records }` behind `x-ultimate-records: 1` (records may be `{}`),
+ * and every other query answers the bare rows (or `Page`) it always did. One body shape per
+ * operation — until 21.0.0 a read sent the envelope only when a row came back, so its OpenAPI was a
+ * `oneOf` over "sometimes" and a generated client had to branch on the data.
+ */
+
+import type { RecordRows, Row } from '@ultimat3/core';
+import { encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core';
+import { hasEntityRows, rowsOf } from '@ultimat3/entity';
+import { json } from '@ultimat3/http';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { Page } from './pagination';
+
+/** Turns one read's answer into its response. Built once per route, never per request. */
+export type RecordAnswer = (answer: readonly object[] | Page<object>) => Response;
+
+/**
+ * `undefined` or an unbranded schema answers the plain `json()` it always did. The rows are
+ * collected one at a time against the ROW schema, since the answer's own shape — an array or a
+ * `Page` — is the route's, not the declaration's.
+ */
+export function recordAnswerFor(rows: StandardSchemaV1 | undefined): RecordAnswer {
+  if (!answersRecords(rows)) return (answer) => json(answer);
+  return (answer) => {
+    const records = collect(rows, isPage(answer) ? answer.rows : answer);
+    return json(encodeRecordEnvelope(answer, records), { headers: { [RECORDS_HEADER]: '1' } });
+  };
+}
+
+/** The one predicate the route and the OpenAPI projection both ask: can this read answer records? */
+export function answersRecords(rows: StandardSchemaV1 | undefined): rows is StandardSchemaV1 {
+  return rows !== undefined && hasEntityRows(rows);
+}
+
+/** `Array.isArray` does not narrow a `readonly` array out of a union, so this says it once. */
+function isPage(answer: readonly object[] | Page<object>): answer is Page<object> {
+  return !Array.isArray(answer);
+}
+
+/**
+ * Every entity row across the answer's rows: record type -> record key -> row. First sighting wins,
+ * `rowsOf`'s own rule — one record shown twice is one record. Built in `Map`s and handed out as
+ * null-prototype objects: a record type and a record key are data, and `__proto__` must stay a key.
+ */
+function collect(
+  schema: StandardSchemaV1,
+  list: readonly object[],
+): Readonly<Record<string, RecordRows>> {
+  const out = new Map<string, Map<string, Row>>();
+  for (const row of list) {
+    for (const [type, byKey] of Object.entries(rowsOf(schema, row))) {
+      const bucket = out.get(type) ?? new Map<string, Row>();
+      out.set(type, bucket);
+      for (const [key, found] of Object.entries(byKey))
+        if (!bucket.has(key)) bucket.set(key, found);
+    }
+  }
+  return nullProto([...out].map(([type, bucket]) => [type, nullProto(bucket)] as const));
+}
+
+function nullProto<V>(entries: Iterable<readonly [string, V]>): Readonly<Record<string, V>> {
+  const target = Object.create(null) as Record<string, V>;
+  for (const [key, value] of entries) target[key] = value;
+  return target;
+}

package/src/shape.ts

@@ -31,10 +31,14 @@ export interface QueryShape {
   readonly unsupported: readonly string[];
 }
 
-/** Where a page resumes: the sort-key values of the last row plus its id tiebreak. */
+/**
+ * Where a page resumes: the sort-key values of the last row plus its id tiebreak. `id` keeps the
+ * row's own TYPE: a stringified numeric id compared lexically against the next page's rows, so
+ * `"10" < "7"` and a row tied on the sort key after id 7 was never served.
+ */
 export interface SeekKey {
   readonly key: readonly unknown[];
-  readonly id: string;
+  readonly id: unknown;
 }
 
 /**
@@ -53,7 +57,7 @@ export function seekKeyOf(
   if (id === undefined || id === null) throw new QueryNotPageableError(shape.entity);
   return {
     key: shape.orderBy.map((order) => columnOf(row, order.column)),
-    id: typeof id === 'string' ? id : String(id),
+    id,
   };
 }
 
@@ -193,11 +197,18 @@ function normalize(value: unknown): unknown {
   return value instanceof Date ? value.getTime() : value;
 }
 
+/**
+ * Equality as Postgres answers it. A number and a bigint are ONE family — an `int8` arrives as a
+ * `bigint` from one driver while a filter value is usually a `number` literal, and `5n = 5` is
+ * true there — so the type check that keeps `'5'` from equalling `5` treats them as one.
+ */
 function same(a: unknown, b: unknown): boolean {
   if (isNull(a) || isNull(b)) return isNull(a) && isNull(b);
-  return compareValues(a, b) === 0 && typeof normalize(a) === typeof normalize(b);
+  return compareValues(a, b) === 0 && family(normalize(a)) === family(normalize(b));
 }
 
+const family = (value: unknown): string => (isNumeric(value) ? 'numeric' : typeof value);
+
 /** Row ordering under an `orderBy` list. Stable, and total when an id key is last. */
 export function compareRows(a: object, b: object, orderBy: readonly OrderKey[]): number {
   for (const key of orderBy) {

package/src/source.ts

@@ -4,6 +4,7 @@
  * app's `sql:` returns `from()` over an `@ultimat3/entity` repo, and a source only has to
  * answer these four questions.
  */
+import { QueryColumnUnselectedError } from './errors';
 import type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
 import { compareRows, compareValues, isNull, matchesFilters, totalOrder } from './shape';
 import { columnOf } from './stable';
@@ -132,6 +133,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;
+    this.assertCarried(source);
     let result = source.filter((row) => matchesFilters(row, this.filters));
     const keys = this.servedOrder();
     if (keys.length > 0) {
@@ -144,6 +146,19 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
     return this.rowLimit === null ? result : result.slice(0, this.rowLimit);
   }
 
+  /**
+   * Every column a filter or the declared ordering reads must be ON the rows. Only the declared
+   * keys: the `id` tiebreak `servedOrder()` adds is `seek()`'s concern, refused there by name.
+   */
+  private assertCarried(rows: readonly TRow[]): void {
+    const read = new Set([...this.filters, ...this.order].map((entry) => entry.column));
+    for (const row of rows) {
+      for (const column of read) {
+        if (!(column in row)) throw new QueryColumnUnselectedError(this.entity, column);
+      }
+    }
+  }
+
   /** True when the ordering already names `id`, so the tiebreak is neither added nor doubled. */
   private get ordersById(): boolean {
     return this.order.some((key) => key.column === 'id');