@spine-event-engine/storage-datastore 2.0.0-snapshot.2 → 2.0.0-snapshot.21

package/dist/datastore/record-storage.js

@@ -14,8 +14,9 @@
 import { fromBinary, toBinary } from "@bufbuild/protobuf";
 import { and, Datastore, or, PropertyFilter } from "@google-cloud/datastore";
 import { StringifierRegistry } from "@spine-event-engine/core";
-import { ColumnMappings, defaultQueryCandidateLimit, RecordStorage, TenantBoundary, } from "@spine-event-engine/storage";
-import { StorageQueryValues } from "@spine-event-engine/storage/internal/query-values";
+import { ColumnMappings, defaultQueryCandidateLimit, RecordStorage, } from "@spine-event-engine/storage";
+import { TenantBoundary } from "@spine-event-engine/storage/provider";
+import { StorageQueryValues } from "@spine-event-engine/storage/provider";
 import { DatastoreColumnMapping } from "./column-mapping.js";
 import { DatastoreIdColumn } from "./id-column.js";
 import { DefaultNamespaceConverter, NamespaceAssignments, } from "./namespace.js";
@@ -26,6 +27,9 @@ const casRetryDelayMs = 100;
 const wrappedReadOptions = { wrapNumbers: true };
 /**
  * Private flat Datastore-entity codec for one record storage handle.
+ *
+ * @typeParam I Identifier type encoded in Datastore keys.
+ * @typeParam R Generated record message type encoded as payload bytes.
  */
 class FlatEntityCodec {
     recordSpec;
@@ -35,6 +39,18 @@ class FlatEntityCodec {
     #namespace;
     #idColumn;
     #columnMapping;
+    /**
+     * Initializes the Datastore kind, tenant namespace, ID codec, and column mapping.
+     *
+     * @param context Storage tenant context.
+     * @param recordSpec Generated record and column contract.
+     * @param client Datastore client supplying the default namespace.
+     * @param maxClientSideScan Maximum local materialization budget.
+     * @param group Optional storage group used in the physical kind.
+     * @param kind Optional explicit physical kind.
+     * @param namespaceConverter Converts tenant IDs to Datastore namespaces.
+     * @param stringifiers Converts message-valued IDs and columns.
+     */
     constructor(context, recordSpec, client, maxClientSideScan, group, kind, namespaceConverter, stringifiers) {
         this.recordSpec = recordSpec;
         this.maxClientSideScan = maxClientSideScan;
@@ -53,12 +69,34 @@ class FlatEntityCodec {
         this.#idColumn = new DatastoreIdColumn(recordSpec.idType, stringifiers);
         this.#columnMapping = new DatastoreColumnMapping(stringifiers);
     }
+    /**
+     * Builds a namespaced Datastore key for a record identifier.
+     *
+     * @param client Datastore client that creates keys.
+     * @param id Typed record identifier.
+     * @returns Physical key for this kind and namespace.
+     */
     key(client, id) {
         return client.key({
-            path: [this.#kind, this.#idColumn.value(id)],
+            path: [this.#kind, this.idName(id)],
             ...(this.#namespace === undefined ? {} : { namespace: this.#namespace }),
         });
     }
+    /**
+     * Returns the canonical Datastore key name for a logical record ID.
+     * @param id Typed record identifier.
+     * @returns Key name shared by equivalent logical IDs.
+     */
+    idName(id) {
+        return this.#idColumn.value(id);
+    }
+    /**
+     * Encodes record bytes and declared materialized columns as entity properties.
+     *
+     * @param record Generated record to serialize.
+     * @param columns Materialized column values by declared name.
+     * @returns Datastore property map including the binary payload.
+     */
     encode(record, columns) {
         const data = {
             [payloadProperty]: Buffer.from(toBinary(this.recordSpec.recordType, record, { writeUnknownFields: false })),
@@ -68,6 +106,13 @@ class FlatEntityCodec {
         }
         return data;
     }
+    /**
+     * Decodes a record ID from an entity's physical key.
+     *
+     * @param entity Raw Datastore entity.
+     * @param client Client whose key symbol identifies the entity key.
+     * @returns Typed record identifier.
+     */
     id(entity, client) {
         const key = datastoreKey(entity, client.KEY);
         const name = datastoreKeyName(key);
@@ -76,36 +121,85 @@ class FlatEntityCodec {
         }
         return this.#idColumn.read(name);
     }
+    /**
+     * Reads declared column values from a decoded entity record.
+     *
+     * @param entity Raw Datastore entity.
+     * @returns Declared column values by name.
+     */
     columns(entity) {
         return new Map(this.recordSpec.columns.map((column) => [column.name, column.valueIn(this.decode(entity))]));
     }
+    /**
+     * Marks the binary record payload as excluded from Datastore indexes.
+     *
+     * @param data Entity property map being saved.
+     * @returns Payload property name to leave unindexed.
+     */
     unindexedProperties(data) {
         void data;
         return [payloadProperty];
     }
+    /**
+     * Creates a provider query for this handle's kind and namespace.
+     *
+     * @param client Datastore client that creates queries.
+     * @returns Query scoped to this record family.
+     */
     createQuery(client) {
         return this.#namespace === undefined
             ? client.createQuery(this.#kind)
             : client.createQuery(this.#namespace, this.#kind);
     }
+    /**
+     * Validates a declared column and returns its Datastore property name.
+     *
+     * @param column Requested record column name.
+     * @returns Datastore property name for the column.
+     */
     columnProperty(column) {
         if (!this.recordSpec.columns.some((candidate) => candidate.name === column)) {
             throw new Error(`Datastore record column "${column}" is not declared.`);
         }
         return column;
     }
+    /**
+     * Returns a row limit with one sentinel beyond the local scan budget.
+     *
+     * @returns Provider row limit used to detect budget overflow.
+     */
     queryLimit() {
         return this.maxClientSideScan + 1;
     }
+    /**
+     * Returns the tenant namespace selected for this handle.
+     *
+     * @returns Datastore namespace, if tenant scoping requires one.
+     */
     namespace() {
         return this.#namespace;
     }
+    /**
+     * Converts a declared record column value to its provider representation.
+     *
+     * @param column Declared record column name.
+     * @param value Runtime column value.
+     * @returns Datastore-compatible column value.
+     */
     columnValue(column, value) {
         const declared = this.recordSpec.columns.find((candidate) => candidate.name === column);
         if (declared === undefined)
             throw new Error(`Datastore record column "${column}" is not declared.`);
         return ColumnMappings.value(this.#columnMapping, declared.type, value);
     }
+    /**
+     * Captures ordered values and the physical key from the final page entity.
+     *
+     * @param entity Last raw Datastore entity in a page.
+     * @param order Provider ordering used for the page.
+     * @param keySymbol Client symbol for the physical entity key.
+     * @returns Stable keyset continuation for the next page.
+     */
     pageCursor(entity, order, keySymbol) {
         const key = datastoreKey(entity, keySymbol);
         const record = this.decode(entity);
@@ -121,6 +215,12 @@ class FlatEntityCodec {
             throw new Error("Datastore provider page continuation is malformed.");
         return { values, key };
     }
+    /**
+     * Decodes a generated record from an entity's binary payload.
+     *
+     * @param entity Raw Datastore entity containing the payload.
+     * @returns Generated record without unknown fields.
+     */
     decode(entity) {
         const payload = entity[payloadProperty];
         if (!(payload instanceof Uint8Array)) {
@@ -168,6 +268,9 @@ function cursorJson(_key, value) {
 }
 /**
  * Provides one Datastore-backed storage handle for a record family.
+ *
+ * @typeParam I Record identifier type used by this handle.
+ * @typeParam R Generated record message type stored by this handle.
  */
 export class DatastoreRecordStorage extends RecordStorage {
     client;
@@ -339,7 +442,7 @@ export class DatastoreRecordStorage extends RecordStorage {
     queryCapabilities() {
         return {
             comparisons: ["equal", "greaterThan", "lessThan", "greaterOrEqual", "lessOrEqual"],
-            features: ["order", "mask", "limit"],
+            features: ["order", "limit"],
         };
     }
     /**
@@ -348,12 +451,79 @@ export class DatastoreRecordStorage extends RecordStorage {
      * @returns The candidate storage entries.
      */
     async queryPlanRecordEntries(plan) {
-        if (plan.predicate !== undefined && DatastoreQueryPushdown.legal(plan) === undefined)
+        const legal = DatastoreQueryPushdown.legal(plan);
+        const largeIds = plan.exhaustive && plan.predicate !== undefined
+            ? DatastoreQueryPushdown.largeIdSet(plan.predicate, plan.order)
+            : undefined;
+        if (plan.predicate !== undefined && legal === undefined && largeIds === undefined)
             throw new TypeError("Datastore normalized query has an illegal predicate or inequality ordering.");
         for (const order of plan.order ?? [])
             this.#codec.columnProperty(order.column);
-        const query = this.#codec.createQuery(this.client);
-        DatastoreQueryPushdown.plan(query, plan, (id) => this.#codec.key(this.client, id), (column) => this.#codec.columnProperty(column), (column, value) => this.#codec.columnValue(column, value));
+        if (plan.exhaustive) {
+            if (largeIds !== undefined)
+                return this.largeIdPlanEntries(largeIds);
+            return this.exhaustivePlanEntries(plan, true);
+        }
+        return this.boundedPlanEntries(plan);
+    }
+    /**
+     * Reads a mandatory large ID set through provider-legal key batches.
+     *
+     * @param ids Explicit IDs that every matching record must have.
+     * @returns Unique candidates for global predicate and ordering evaluation.
+     */
+    async largeIdPlanEntries(ids) {
+        const unique = new Map();
+        for (const id of ids)
+            unique.set(this.#codec.idName(id), id);
+        const selected = [...unique.values()];
+        const entries = [];
+        for (let start = 0; start < selected.length; start += 30) {
+            const batch = selected.slice(start, start + 30);
+            entries.push(...(await this.exhaustivePlanEntries({ exhaustive: true, predicate: { kind: "ids", ids: batch } }, true)));
+        }
+        return entries;
+    }
+    /**
+     * Reads every provider page before storage applies the global query semantics.
+     *
+     * @param plan Validated normalized query plan.
+     * @param pushdown Whether the provider can apply the predicate and ordering.
+     * @returns Every candidate entry in provider page order.
+     */
+    async exhaustivePlanEntries(plan, pushdown) {
+        const entries = [];
+        let cursor;
+        const seen = new Set();
+        for (;;) {
+            const query = this.planQuery(plan, pushdown);
+            query.limit(128);
+            if (cursor !== undefined)
+                query.start(cursor);
+            const response = await this.provider(() => this.client.runQuery(query, wrappedReadOptions));
+            entries.push(...DatastoreResults.entities(response).map((entity) => ({
+                id: this.#codec.id(entity, this.client),
+                record: this.#codec.decode(entity),
+            })));
+            const info = DatastoreResults.queryInfo(response);
+            if (!info.more)
+                return entries;
+            const next = info.cursor;
+            const key = typeof next === "string" ? next : next.toString("base64");
+            if (seen.has(key))
+                throw new Error("Datastore query continuation did not advance.");
+            seen.add(key);
+            cursor = next;
+        }
+    }
+    /**
+     * Reads one bounded provider result for public and Process Manager plans.
+     *
+     * @param plan Validated normalized query plan.
+     * @returns Candidate entries within the provider's configured bound.
+     */
+    async boundedPlanEntries(plan) {
+        const query = this.planQuery(plan, true);
         const providerLimit = Math.min(this.#codec.queryLimit(), plan.limit ?? Number.POSITIVE_INFINITY, (plan.candidateLimit ?? defaultQueryCandidateLimit) + 1);
         query.limit(providerLimit);
         const entities = DatastoreResults.entities(await this.provider(() => this.client.runQuery(query, wrappedReadOptions)));
@@ -365,6 +535,21 @@ export class DatastoreRecordStorage extends RecordStorage {
             record: this.#codec.decode(entity),
         }));
     }
+    /**
+     * Builds one Datastore query with safe predicate and order pushdown.
+     *
+     * @param plan Normalized query plan to translate.
+     * @param pushdown Whether the plan is legal for provider filtering.
+     * @returns Query without a page bound or cursor.
+     */
+    planQuery(plan, pushdown) {
+        const query = this.#codec.createQuery(this.client);
+        if (pushdown)
+            DatastoreQueryPushdown.plan(query, plan, (id) => this.#codec.key(this.client, id), (column) => this.#codec.columnProperty(column), (column, value) => this.#codec.columnValue(column, value));
+        if (plan.exhaustive && (!pushdown || (plan.order?.length ?? 0) === 0))
+            query.order("__key__");
+        return query;
+    }
     /**
      * Reads the record at one storage slot.
      * @param id The storage slot identifier.
@@ -396,6 +581,14 @@ export class DatastoreRecordStorage extends RecordStorage {
         }
         throw new Error("Datastore compare-and-set retry limit was reached.");
     }
+    /**
+     * Executes one transactional compare-and-set attempt against the stored payload.
+     *
+     * @param id Record slot selected for mutation.
+     * @param expected Required prior materialized record, or absence.
+     * @param next Replacement materialized record, or deletion.
+     * @returns True when the expected payload matched and commit completed.
+     */
     async attemptCompareAndSet(id, expected, next) {
         const key = this.#codec.key(this.client, id);
         const transaction = this.transaction();
@@ -457,6 +650,13 @@ export class DatastoreRecordStorage extends RecordStorage {
             excludeFromIndexes: this.#codec.unindexedProperties(data),
         }));
     }
+    /**
+     * Executes a provider operation and hides provider error details from callers.
+     *
+     * @typeParam T Result produced by the provider operation.
+     * @param operation Provider request to execute.
+     * @returns Provider result after successful execution.
+     */
     async provider(operation) {
         try {
             return await operation();
@@ -480,24 +680,36 @@ export class DatastoreRecordStorage extends RecordStorage {
     }
 }
 /**
- * Converts values between Spine records and the Datastore provider representation.
+ * Compares decoded query values and persisted payload bytes.
  */
-const RecordValues = Object.freeze(new (class {
+class RecordValueMethods {
     // prettier-ignore
     /**
      * Compares canonical local values for equality.
+     *
+     * @param left First decoded query value.
+     * @param right Second decoded query value.
+     * @returns True when the query evaluator considers the values equal.
      */
     equal(left, right) {
         return StorageQueryValues.equal(left, right);
     }
     /**
      * Compares canonical local values for ordering.
+     *
+     * @param left First decoded query value.
+     * @param right Second decoded query value.
+     * @returns Signed query sort comparison.
      */
     compare(left, right) {
         return StorageQueryValues.compare(left, right);
     }
     /**
      * Compares two persisted payload byte arrays.
+     *
+     * @param left First persisted payload candidate.
+     * @param right Second persisted payload candidate.
+     * @returns True only when both are byte arrays with identical bytes.
      */
     payloadEqual(left, right) {
         return (left instanceof Uint8Array &&
@@ -505,7 +717,11 @@ const RecordValues = Object.freeze(new (class {
             left.byteLength === right.byteLength &&
             left.every((value, index) => value === right[index]));
     }
-})());
+}
+/**
+ * Exposes comparisons for decoded query values and persisted payload bytes.
+ */
+const RecordValues = Object.freeze(new RecordValueMethods());
 /**
  * Raised when a query would exceed the adapter's configured finite client-side scan budget.
  */
@@ -530,6 +746,13 @@ class DatastoreQueryPushdownHelper {
     // prettier-ignore
     /**
      * Translates the legacy record-query surface.
+     *
+     * @typeParam I Record identifier type used by the query.
+     * @param query Mutable Datastore query receiving filters and ordering.
+     * @param recordQuery Legacy record query to translate.
+     * @param keyFor Converts a record ID to a Datastore key.
+     * @param columnProperty Resolves a declared column to a property name.
+     * @param columnValue Converts a column value for the provider.
      */
     translate(query, recordQuery, keyFor, columnProperty, columnValue) {
         if (recordQuery.ids !== undefined && recordQuery.ids.length > 0) {
@@ -559,6 +782,13 @@ class DatastoreQueryPushdownHelper {
     }
     /**
      * Applies the all-or-nothing legal portion of a normalized query plan.
+     *
+     * @typeParam I Record identifier type used by the plan.
+     * @param query Mutable Datastore query receiving safe clauses.
+     * @param plan Normalized plan whose predicate and ordering are inspected.
+     * @param keyFor Converts a record ID to a Datastore key.
+     * @param columnProperty Resolves a declared column to a property name.
+     * @param columnValue Converts a column value for the provider.
      */
     plan(query, plan, keyFor, columnProperty, columnValue) {
         const legal = this.legal(plan);
@@ -575,6 +805,10 @@ class DatastoreQueryPushdownHelper {
     }
     /**
      * Returns the predicate only when every clause satisfies provider restrictions.
+     *
+     * @typeParam I Record identifier type in ID predicates.
+     * @param plan Normalized plan checked for supported predicate shape and ordering.
+     * @returns Predicate when Datastore can execute it completely.
      */
     legal(plan) {
         const predicate = plan.predicate;
@@ -604,8 +838,40 @@ class DatastoreQueryPushdownHelper {
         }
         return predicate;
     }
+    /**
+     * Finds a mandatory ID set too wide for one Datastore IN filter.
+     *
+     * @typeParam I Identifier type in the predicate.
+     * @param predicate Predicate checked for a mandatory large ID set.
+     * @param order Ordering checked against any inequality comparison.
+     * @returns A required large ID set, or undefined for other shapes.
+     */
+    largeIdSet(predicate, order) {
+        const leaves = predicate.kind === "all" ? predicate.predicates : [predicate];
+        if (leaves.some((leaf) => leaf.kind !== "ids" && leaf.kind !== "comparison"))
+            return undefined;
+        const large = leaves.find((leaf) => leaf.kind === "ids" && leaf.ids.length > 30);
+        if (large?.kind !== "ids")
+            return undefined;
+        const narrowed = leaves.map((leaf) => leaf.kind === "ids" && leaf.ids.length > 30 ? { ...leaf, ids: leaf.ids.slice(0, 1) } : leaf);
+        const representative = predicate.kind === "all"
+            ? { kind: "all", predicates: narrowed }
+            : { kind: "ids", ids: large.ids.slice(0, 1) };
+        const legal = this.legal({
+            predicate: representative,
+            ...(order === undefined ? {} : { order }),
+        });
+        return legal === undefined ? undefined : large.ids;
+    }
     /**
      * Adds one already-legal normalized predicate to the provider query.
+     *
+     * @typeParam I Record identifier type in ID predicates.
+     * @param query Mutable Datastore query receiving provider filters.
+     * @param predicate Normalized predicate approved for provider execution.
+     * @param keyFor Converts a record ID to a Datastore key.
+     * @param columnProperty Resolves a declared column to a property name.
+     * @param columnValue Converts a comparison value for the provider.
      */
     predicate(query, predicate, keyFor, columnProperty, columnValue) {
         if (predicate.kind === "all") {
@@ -644,13 +910,14 @@ class DatastoreQueryPushdownHelper {
  */
 const DatastoreQueryPushdown = Object.freeze(new DatastoreQueryPushdownHelper());
 /**
- * Selects safe provider bounds for direct record queries.
+ * Selects safe provider bounds for direct legacy record queries.
  */
-const DatastoreRecordQuery = Object.freeze(new (class {
+class DatastoreRecordQueryMethods {
     // prettier-ignore
     /**
      * Returns a caller limit only when it cannot change local query semantics.
      *
+     * @typeParam I Record identifier type in the legacy query.
      * @param query Supplies the requested record query.
      * @param scanLimit Supplies the configured materialization limit.
      * @returns The finite provider row bound.
@@ -671,6 +938,7 @@ const DatastoreRecordQuery = Object.freeze(new (class {
     /**
      * Returns whether a legacy query is exactly an ascending identifier keyset page.
      *
+     * @typeParam I Record identifier type in the legacy query.
      * @param query The record query to classify.
      * @returns `true` when Datastore can apply its limit and continuation completely.
      */
@@ -690,7 +958,11 @@ const DatastoreRecordQuery = Object.freeze(new (class {
                     continuationValue?.field === "id" &&
                     RecordValues.equal(continuationValue.value, continuation.id))));
     }
-})());
+}
+/**
+ * Provides the bounded legacy record-query checks used by this adapter.
+ */
+const DatastoreRecordQuery = Object.freeze(new DatastoreRecordQueryMethods());
 /**
  * Applies record-query filtering, ordering, continuation, and paging locally.
  */
@@ -698,6 +970,12 @@ class LocalQueryResultsHelper {
     // prettier-ignore
     /**
      * Applies one legacy record query to materialized candidate entries.
+     *
+     * @typeParam I Record identifier type in the candidates.
+     * @typeParam R Generated record message type in the candidates.
+     * @param entries Materialized candidates with declared column values.
+     * @param query Legacy filter, ordering, continuation, and paging request.
+     * @returns Selected record entries after local query evaluation.
      */
     apply(entries, query) {
         const matching = entries.filter((entry) => this.matches(entry, query));
@@ -713,6 +991,12 @@ class LocalQueryResultsHelper {
     }
     /**
      * Tests whether a candidate satisfies the ID and equality filters.
+     *
+     * @typeParam I Record identifier type in the candidate.
+     * @typeParam R Generated record message type in the candidate.
+     * @param entry Candidate record with materialized columns.
+     * @param query Legacy ID and column filters.
+     * @returns True when the candidate satisfies every requested filter.
      */
     matches(entry, query) {
         return ((query.ids === undefined ||
@@ -725,7 +1009,14 @@ class LocalQueryResultsHelper {
             }));
     }
     /**
-     * Orders candidates by requested sort fields and canonical ID tie-breaker.
+     * Compares candidates by requested sort fields and canonical ID tie-breaker.
+     *
+     * @typeParam I Record identifier type in the candidates.
+     * @typeParam R Generated record message type in the candidates.
+     * @param left First candidate entry.
+     * @param right Second candidate entry.
+     * @param orders Requested field order in priority order.
+     * @returns Signed sort comparison with ID as final tie-breaker.
      */
     order(left, right, orders) {
         for (const order of orders) {
@@ -737,6 +1028,13 @@ class LocalQueryResultsHelper {
     }
     /**
      * Compares a candidate with a normalized continuation cursor.
+     *
+     * @typeParam I Record identifier type in the candidate and cursor.
+     * @typeParam R Generated record message type in the candidate.
+     * @param entry Candidate record with materialized columns.
+     * @param orders Requested field order used by the cursor.
+     * @param after Continuation cursor from the preceding page.
+     * @returns Signed comparison after applying order directions and ID tie-breaker.
      */
     continuation(entry, orders, after) {
         for (let index = 0; index < orders.length; index += 1) {
@@ -750,7 +1048,13 @@ class LocalQueryResultsHelper {
         return RecordValues.compare(entry.id, after.id);
     }
     /**
-     * Obtains an ID or indexed column value from a candidate.
+     * Reads an ID or indexed column value from a candidate.
+     *
+     * @typeParam I Record identifier type in the candidate.
+     * @typeParam R Generated record message type in the candidate.
+     * @param entry Candidate record with materialized columns.
+     * @param field ID or declared column name.
+     * @returns Candidate ID or stored column value.
      */
     value(entry, field) {
         return field === "id" ? entry.id : entry.columns.get(field);
@@ -766,14 +1070,20 @@ const LocalQueryResults = Object.freeze(new LocalQueryResultsHelper());
 class DatastoreTransactionsHelper {
     // prettier-ignore
     /**
-     * Redacts credential-like errors while preserving safe provider failures.
+     * Replaces transaction errors with a stable public failure message.
+     *
+     * @param error Provider failure whose details must be hidden.
+     * @returns New error without provider details.
      */
     redact(error) {
         void error;
         return new Error("Datastore transaction failed.");
     }
     /**
-     * Identifies a safe-to-retry Datastore transaction conflict.
+     * Checks for a safe-to-retry Datastore transaction conflict.
+     *
+     * @param error Provider failure to classify.
+     * @returns True for non-sensitive Datastore conflict code 10.
      */
     retry(error) {
         return (error instanceof Error &&
@@ -782,6 +1092,9 @@ class DatastoreTransactionsHelper {
     }
     /**
      * Waits using exponential jitter before a bounded CAS retry.
+     *
+     * @param attempt Zero-based retry attempt used for backoff.
+     * @returns Completes after the randomized delay.
      */
     async wait(attempt) {
         const exponentialDelay = casRetryDelayMs * 2 ** attempt;
@@ -799,7 +1112,10 @@ const DatastoreTransactions = Object.freeze(new DatastoreTransactionsHelper());
 class DatastoreResultsHelper {
     // prettier-ignore
     /**
-     * Extracts the optional first entity from a Datastore read response.
+     * Reads the optional first entity from a Datastore read response.
+     *
+     * @param response Raw provider read response.
+     * @returns First validated entity, if a row was returned.
      */
     first(response) {
         if (!Array.isArray(response))
@@ -808,7 +1124,10 @@ class DatastoreResultsHelper {
         return entity === undefined ? undefined : this.entity(entity);
     }
     /**
-     * Extracts entity rows from a Datastore query response.
+     * Reads entity rows from a Datastore query response.
+     *
+     * @param response Raw provider query response.
+     * @returns Validated entity objects in provider order.
      */
     entities(response) {
         if (!Array.isArray(response) || !Array.isArray(response[0])) {
@@ -817,7 +1136,10 @@ class DatastoreResultsHelper {
         return response[0].map((value) => this.entity(value));
     }
     /**
-     * Extracts the provider continuation and the remaining-row indication.
+     * Reads the provider continuation and the remaining-row indication.
+     *
+     * @param response Raw provider query response.
+     * @returns Validated cursor and whether another page exists.
      */
     queryInfo(response) {
         if (!Array.isArray(response) || typeof response[1] !== "object" || response[1] === null)
@@ -830,15 +1152,21 @@ class DatastoreResultsHelper {
             moreResults !== "MORE_RESULTS_AFTER_CURSOR")
             throw new Error("Datastore returned an invalid query response.");
         const more = moreResults === "MORE_RESULTS_AFTER_LIMIT" || moreResults === "MORE_RESULTS_AFTER_CURSOR";
-        if (more && !(cursor instanceof Buffer || typeof cursor === "string"))
-            throw new Error("Datastore returned an invalid query response.");
+        if (more) {
+            if (!(cursor instanceof Buffer || typeof cursor === "string"))
+                throw new Error("Datastore returned an invalid query response.");
+            return { cursor, more: true };
+        }
         return {
             cursor: cursor instanceof Buffer || typeof cursor === "string" ? cursor : undefined,
-            more,
+            more: false,
         };
     }
     /**
      * Validates one provider entity object.
+     *
+     * @param value Candidate entity returned by Datastore.
+     * @returns Record-like entity object.
      */
     entity(value) {
         if (typeof value !== "object" || value === null) {