@ultimat3/query 22.11.0 → 22.12.0

package/README.md

@@ -336,16 +336,19 @@ not exported, because a page is the read's own answer rather than an imported he
 ### The same page over HTTP — `?_first=` and `?_after=`
 
 The route reads two controls off the search string BEFORE the schema sees it, and with either
-present answers the `Page` envelope `.page()` answers a server caller with — `{ rows, endCursor,
-hasNextPage }`, the same names, so a cursor read off the wire and one read off a direct call are
-one string in one field. Without a control the answer is the bare array it has always been, so a
+present answers the `Page` envelope `.page()` answers a server caller with — `{ rows, nextCursor,
+hasMore, endCursor, hasNextPage }`, the same names, so a cursor read off the wire and one read off a
+direct call are one string in one field. **`nextCursor` and `hasMore` are the preferred names**
+(`As of 22.12`); `endCursor` and `hasNextPage` carry the same two values, always, as aliases — not
+deprecated, so a client reading them keeps working. `openapi.json` lists all five as required, the
+aliases described as such. Without a control the answer is the bare array it has always been, so a
 client written before the controls existed keeps reading rows. `As of 2026-09`; until then the
 route had no envelope, and a query over a paged external source carried its page marker on a row
 (an `olderCursor` column on the oldest message), which is a cursor on the wrong side of the shape.
 
 ```
-GET /_x/query/live-feed?orgId=…&_first=20             → { rows, endCursor, hasNextPage }
-GET /_x/query/live-feed?orgId=…&_first=20&_after=<c>  → the next page
+GET /_x/query/live-feed?orgId=…&_first=20             → { rows, nextCursor, hasMore, endCursor, hasNextPage }
+GET /_x/query/live-feed?orgId=…&_first=20&_after=<c>  → the next page (<c> = nextCursor)
 GET /_x/query/live-feed?orgId=…                       → [ …rows ]   (unchanged)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "22.11.0",
+  "version": "22.12.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -36,11 +36,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.11.0",
-    "@ultimat3/core": "22.11.0",
-    "@ultimat3/entity": "22.11.0",
-    "@ultimat3/http": "22.11.0",
-    "@ultimat3/policy": "22.11.0",
-    "@ultimat3/schema": "22.11.0"
+    "@ultimat3/cache": "22.12.0",
+    "@ultimat3/core": "22.12.0",
+    "@ultimat3/entity": "22.12.0",
+    "@ultimat3/http": "22.12.0",
+    "@ultimat3/policy": "22.12.0",
+    "@ultimat3/schema": "22.12.0"
   }
 }

package/src/http.ts

@@ -80,7 +80,8 @@ export function toQueryRoute(target: AnyQuery): Route {
       return answerRow(row);
     }
     // With a page control the answer is the `Page` envelope `query.page()` answers a server
-    // caller with — `{ rows, endCursor, hasNextPage }`, the same names, so a cursor read off the
+    // caller with — `{ rows, nextCursor, hasMore, endCursor, hasNextPage }`, the same names (the
+    // last two aliases of the first two), so a cursor read off the
     // wire and one read off a direct call are the same string in the same field. Without one the
     // answer is the bare array it has always been: every client written before the controls
     // existed keeps reading rows, and `hasNextPage` never rides on a row where a page marker

package/src/openapi.ts

@@ -48,11 +48,18 @@ const ANSWERS: readonly Record<string, unknown>[] = [
   { type: 'array', items: {} },
   {
     type: 'object',
-    required: ['rows', 'endCursor', 'hasNextPage'],
+    // `nextCursor`/`hasMore` are the preferred names; the other two are the same values, kept as
+    // aliases — documented as such, not deprecated — so every client written against them reads on.
+    required: ['rows', 'nextCursor', 'hasMore', 'endCursor', 'hasNextPage'],
     properties: {
       rows: { type: 'array', items: {} },
-      endCursor: { type: ['string', 'null'] },
-      hasNextPage: { type: 'boolean' },
+      nextCursor: {
+        type: ['string', 'null'],
+        description: `the signed cursor that continues this listing — send it as ${PAGE_AFTER_KEY}; null on an empty page`,
+      },
+      hasMore: { type: 'boolean', description: 'whether another page follows' },
+      endCursor: { type: ['string', 'null'], description: 'alias of nextCursor — the same value' },
+      hasNextPage: { type: 'boolean', description: 'alias of hasMore — the same value' },
     },
   },
 ];
@@ -170,7 +177,7 @@ const PAGE_PARAMETERS: readonly Record<string, unknown>[] = [
     name: PAGE_AFTER_KEY,
     in: 'query',
     required: false,
-    description: `the endCursor a previous page answered; needs ${PAGE_FIRST_KEY}`,
+    description: `the nextCursor (alias endCursor) a previous page answered; needs ${PAGE_FIRST_KEY}`,
     schema: { type: 'string' },
   },
 ];

package/src/page-controls.ts

@@ -90,7 +90,7 @@ export function pageControlsOf(name: string, values: SearchValues): SplitSearch
   if (cursor.length === 0) {
     throw new QueryInputInvalidError(
       name,
-      `${PAGE_AFTER_KEY} is empty — omit it for the first page, or send the endCursor the previous page answered`,
+      `${PAGE_AFTER_KEY} is empty — omit it for the first page, or send the nextCursor the previous page answered`,
     );
   }
   return { input, page: { first: Number(size), after: cursor } };

package/src/pagination.ts

@@ -20,12 +20,32 @@ import { compareRows, seekKeyOf, totalOrder } from './shape';
 import type { SqlSource } from './source';
 import { isAfterKey } from './source';
 
+/**
+ * One page. `nextCursor` / `hasMore` are the preferred names; `endCursor` / `hasNextPage` are the
+ * same two values under the names every client before 22.12 reads — aliases, both always present,
+ * never able to disagree because `pageOf` is the one place that writes them.
+ */
 export interface Page<TRow> {
   readonly rows: readonly TRow[];
+  /** The signed cursor that continues this listing; `null` on an empty page. */
+  readonly nextCursor: string | null;
+  /** Whether another page follows. */
+  readonly hasMore: boolean;
+  /** Alias of `nextCursor`. */
   readonly endCursor: string | null;
+  /** Alias of `hasMore`. */
   readonly hasNextPage: boolean;
 }
 
+/** Builds a `Page` from its two facts — the only constructor, so the aliases cannot drift. */
+export function pageOf<TRow>(
+  rows: readonly TRow[],
+  nextCursor: string | null,
+  hasMore: boolean,
+): Page<TRow> {
+  return { rows, nextCursor, hasMore, endCursor: nextCursor, hasNextPage: hasMore };
+}
+
 export interface PaginateArgs extends SourceOptions {
   readonly first: number;
   readonly after?: string;
@@ -70,20 +90,17 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
   const last = rows[rows.length - 1];
   const seek = last === undefined ? null : seekKeyOf(last, shape);
 
-  return {
-    rows,
-    endCursor:
-      seek === null
-        ? null
-        : 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,
-  };
+  const nextCursor =
+    seek === null
+      ? null
+      : 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),
+        });
+  return pageOf(rows, nextCursor, scoped.length > args.first);
 }
 
 /**