@kubun/graphql 0.14.0 → 0.14.1

package/lib/context.d.ts

@@ -1,6 +1,6 @@
 import { DocumentID } from '@kubun/id';
 import type { AggregateHaving, AggregateSpec, AggregateValues, DocumentData, DocumentFilter, DocumentNode, DocumentOrderBy, GroupedAggregateOrderTerm, GroupedAggregateValue } from '@kubun/protocol';
-import type { StoredAccessDefaultRow, ViewerReadAccess } from '@kubun/store-graph';
+import type { SearchDocumentResult, SearchDocumentsParams, StoredAccessDefaultRow, ViewerReadAccess } from '@kubun/store-graph';
 import type { Tracer } from '@sozai/otel';
 import type { GraphQLResolveInfo } from 'graphql';
 import type { Connection, Edge } from 'graphql-relay';
@@ -74,15 +74,7 @@ export type ReadContextDB = {
         limit?: number;
         readAccess?: ViewerReadAccess;
     }): Promise<Array<GroupedAggregateValue>>;
-    searchDocuments(params: {
-        query: string;
-        modelIDs: Array<string>;
-        first?: number;
-    }): Promise<Array<{
-        documentID: string;
-        modelID: string;
-        rank: number;
-    }>>;
+    searchDocuments(params: SearchDocumentsParams): Promise<Array<SearchDocumentResult>>;
     listUserModelAccessDefaults(ownerDID: string): Promise<Array<StoredAccessDefaultRow>>;
 };
 /**
@@ -144,11 +136,7 @@ export type QueryContext = {
     resolveList(modelIDs: Array<string>, ids: Array<string>): Promise<Array<DocumentNode>>;
     resolveAggregate(modelIDs: Array<string>, params: ResolveAggregateParams): Promise<AggregateValues>;
     resolveGroupedAggregate(modelIDs: Array<string>, params: ResolveGroupedAggregateParams): Promise<Array<GroupedAggregateValue>>;
-    searchDocuments(query: string, modelIDs: Array<string>, first?: number): Promise<Array<{
-        documentID: string;
-        modelID: string;
-        rank: number;
-    }>>;
+    searchDocuments(params: SearchDocumentsParams): Promise<Array<SearchDocumentResult>>;
     /**
      * The viewer's own stored model-access-default rows, across every model and
      * permission type. Scoped to the current viewer DID - not for cross-member

package/lib/context.js

@@ -228,12 +228,8 @@ export function createReadContext(params) {
             }
             return result;
         },
-        async searchDocuments (query, modelIDs, first) {
-            return await store.searchDocuments({
-                query,
-                modelIDs,
-                first
-            });
+        async searchDocuments (params) {
+            return await store.searchDocuments(params);
         },
         async listModelAccessDefaults () {
             return await store.listUserModelAccessDefaults(viewerDID);

package/lib/schema.js

@@ -6,6 +6,7 @@ import { connectionArgs, connectionDefinitions, mutationWithClientMutationId, no
 import { GraphQLDateTimeISO, GraphQLDID, GraphQLDuration, GraphQLEmailAddress, GraphQLJSON, GraphQLJSONObject } from 'graphql-scalars';
 import { GraphQLAttachmentID, GraphQLCredentialEntryID, GraphQLDocID } from './identifiers.js';
 import { GraphQLURL } from './scalars.js';
+import { decodeSearchCursor, encodeSearchCursor } from './search-cursor.js';
 import { getUniqueDocValue, validateAccessIdentifiers } from './utils.js';
 /**
  * Create a type-appropriate default value for stubbing extension field resolvers.
@@ -605,19 +606,32 @@ export class SchemaBuilder {
                     }
                 },
                 resolve: async (_root, args, ctx)=>{
-                    const { query, models, first } = args;
+                    const { query, models, first, after } = args;
                     if (query.trim() === '') {
                         throw new Error('Search query must not be empty');
                     }
+                    if (first != null && first < 0) {
+                        throw new Error('Search `first` must not be negative');
+                    }
+                    const pageSize = first ?? 20;
+                    const offset = decodeSearchCursor(after);
                     // Map model names to IDs
                     const modelIDs = models ? models.map((name)=>this._aliasToModelID[name] ?? name) : [
                         ...this._includedModelIDs
                     ];
-                    const results = await ctx.searchDocuments(query, modelIDs, first ?? 20);
-                    // Load documents
-                    const docIDs = results.map((r)=>r.documentID);
+                    // Over-fetch one hit past the page to detect a following page.
+                    const hits = await ctx.searchDocuments({
+                        query,
+                        modelIDs,
+                        first: pageSize + 1,
+                        offset
+                    });
+                    const hasNextPage = hits.length > pageSize;
+                    const page = hasNextPage ? hits.slice(0, pageSize) : hits;
+                    // Load documents (access control applied inside resolveList)
+                    const docIDs = page.map((r)=>r.documentID);
                     const allModelIDs = [
-                        ...new Set(results.map((r)=>r.modelID))
+                        ...new Set(page.map((r)=>r.modelID))
                     ];
                     const documents = docIDs.length > 0 ? await ctx.resolveList(allModelIDs, docIDs) : [];
                     const docMap = new Map(documents.map((d)=>[
@@ -625,23 +639,27 @@ export class SchemaBuilder {
                             d
                         ]));
                     const edges = [];
-                    for (const r of results){
+                    for(let j = 0; j < page.length; j++){
+                        const r = page[j];
                         const node = docMap.get(r.documentID);
                         if (node != null) {
+                            // Cursor = hits consumed through this position, so the next page
+                            // resumes correctly even when access control drops later docs.
                             edges.push({
-                                cursor: String(edges.length),
+                                cursor: encodeSearchCursor(offset + j + 1),
                                 node,
                                 rank: Math.abs(r.rank)
                             });
                         }
                     }
+                    const endOffset = offset + page.length;
                     return {
                         edges,
                         pageInfo: {
-                            hasNextPage: false,
-                            hasPreviousPage: false,
+                            hasNextPage,
+                            hasPreviousPage: offset > 0,
                             startCursor: edges.length > 0 ? edges[0].cursor : null,
-                            endCursor: edges.length > 0 ? edges[edges.length - 1].cursor : null
+                            endCursor: page.length > 0 ? encodeSearchCursor(endOffset) : null
                         }
                     };
                 }

package/lib/search-cursor.d.ts

@@ -0,0 +1,8 @@
+/** Opaque cursor for the top-level `search` query: base64 of `search:<offset>`. */
+export declare function encodeSearchCursor(offset: number): string;
+/**
+ * Decode a search cursor to its offset. A null/undefined/empty cursor means
+ * "start from the beginning" (offset 0). Anything that is not a cursor this
+ * codec produced throws, so a client cannot silently get a wrong page.
+ */
+export declare function decodeSearchCursor(cursor: string | null | undefined): number;

package/lib/search-cursor.js

@@ -0,0 +1,38 @@
+import { b64uFromUTF, b64uToUTF } from '@sozai/codec';
+const PREFIX = 'search:';
+/** Opaque cursor for the top-level `search` query: base64 of `search:<offset>`. */ export function encodeSearchCursor(offset) {
+    return b64uFromUTF(`${PREFIX}${offset}`);
+}
+/**
+ * Decode a search cursor to its offset. A null/undefined/empty cursor means
+ * "start from the beginning" (offset 0). Anything that is not a cursor this
+ * codec produced throws, so a client cannot silently get a wrong page.
+ */ export function decodeSearchCursor(cursor) {
+    if (cursor == null || cursor === '') {
+        return 0;
+    }
+    let decoded;
+    try {
+        decoded = b64uToUTF(cursor);
+    } catch (e) {
+        throw new Error('Invalid search cursor', {
+            cause: e
+        });
+    }
+    if (!decoded.startsWith(PREFIX)) {
+        throw new Error('Invalid search cursor');
+    }
+    const raw = decoded.slice(PREFIX.length);
+    // Canonical non-negative integer only: no leading zeros, sign, whitespace,
+    // or scientific/hex notation — the encoder only ever emits `${offset}`.
+    if (!/^(0|[1-9]\d*)$/.test(raw)) {
+        throw new Error('Invalid search cursor');
+    }
+    const offset = Number(raw);
+    // Keep `offset + first + 1` (first is bounded by GraphQL's 32-bit Int) within
+    // safe-integer range so the downstream LIMIT arithmetic can't lose precision.
+    if (offset > Number.MAX_SAFE_INTEGER - 0x80000000) {
+        throw new Error('Invalid search cursor');
+    }
+    return offset;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/graphql",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -18,7 +18,7 @@
     "@kubun/hlc": "^0.14.0",
     "@kubun/id": "^0.14.0",
     "@kubun/logger": "^0.14.0",
-    "@kubun/protocol": "^0.14.0",
+    "@kubun/protocol": "^0.14.1",
     "@sozai/async": "^0.2.1",
     "@sozai/codec": "^0.4.0",
     "@sozai/event": "^0.1.3",
@@ -35,7 +35,7 @@
     "@kubun/db": "^0.14.0",
     "@kubun/db-better-sqlite": "^0.14.0",
     "@kubun/scalars": "^0.14.0",
-    "@kubun/store-graph": "^0.14.0",
+    "@kubun/store-graph": "^0.14.1",
     "@kubun/test-utils": "^0.13.0"
   },
   "publishConfig": {