@decaf-ts/for-fabric 0.13.9 → 0.13.11

package/lib/esm/contracts/ContractAdapter.js

@@ -1,11 +1,11 @@
-import { CouchDBAdapter, CouchDBKeys, } from "@decaf-ts/for-couchdb";
+import { CouchDBAdapter, CouchDBKeys, ensureDeterministicSort as couchEnsureDeterministicSort, getSortDirection, getSortFields, warnScanProneMangoOperators, } from "@decaf-ts/for-couchdb";
 import { Model, ValidationKeys } from "@decaf-ts/decorator-validation";
 import { createHash } from "crypto";
 import { FabricContractContext } from "./ContractContext.js";
 import { BadRequestError, BulkCrudOperationKeys, ConflictError, InternalError, NotFoundError, onCreate, onCreateUpdate, SerializationError, } from "@decaf-ts/db-decorators";
 import { Object as FabricObject, Property, Property as FabricProperty, } from "fabric-contract-api";
 import { Logging } from "@decaf-ts/logging";
-import { PersistenceKeys, UnsupportedError, Adapter, QueryError, PagingError, MigrationError, ObserverError, AuthorizationError, ForbiddenError, ConnectionError, Context, TransactionOperationKeys, promiseSequence, resolveBulkSequenceResult, } from "@decaf-ts/core";
+import { PersistenceKeys, UnsupportedError, Adapter, QueryError, PagingError, MigrationError, ObserverError, AuthorizationError, ForbiddenError, ConnectionError, Context, OrderDirection, TransactionOperationKeys, promiseSequence, resolveBulkSequenceResult, } from "@decaf-ts/core";
 import { FabricContractRepository } from "./FabricContractRepository.js";
 import { FabricStatement } from "./FabricContractStatement.js";
 import { FabricContractSequence } from "./FabricContractSequence.js";
@@ -116,114 +116,104 @@ export class FabricContractAdapter extends CouchDBAdapter {
             .update(FabricContractAdapter.stableStringify(relevant))
             .digest("base64url");
     }
-    static parseSyntheticPrivateBookmark(bookmark) {
-        if (typeof bookmark !== "string")
-            return undefined;
-        if (!bookmark.startsWith(FabricContractAdapter.PRIVATE_BOOKMARK_PREFIX))
-            return undefined;
-        const raw = bookmark.slice(FabricContractAdapter.PRIVATE_BOOKMARK_PREFIX.length);
-        try {
-            const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
-            if (!parsed ||
-                typeof parsed !== "object" ||
-                typeof parsed.sortField !== "string" ||
-                typeof parsed.direction !== "string" ||
-                typeof parsed.idField !== "string" ||
-                typeof parsed.lastId !== "string"
-                || typeof parsed.queryHash !== "string") {
-                return undefined;
-            }
-            return {
-                sortField: parsed.sortField,
-                direction: parsed.direction === "desc" ? "desc" : "asc",
-                idField: parsed.idField,
-                lastValue: parsed.lastValue,
-                lastId: parsed.lastId,
-                queryHash: parsed.queryHash,
-            };
-        }
-        catch {
-            return undefined;
-        }
-    }
-    static buildSyntheticPrivateBookmark(cursor) {
-        return `${FabricContractAdapter.PRIVATE_BOOKMARK_PREFIX}${Buffer.from(JSON.stringify(cursor)).toString("base64url")}`;
-    }
-    static buildPrivateCursorSelector(selector, sortField, direction, cursor) {
+    static buildPrivateContinuationSelector(selector, sortField, direction, idField, lastValue, lastId, variant) {
         const cmp = direction === "desc" ? "$lt" : "$gt";
-        if (cursor.idField === sortField) {
+        const idCmp = direction === "desc" ? "$lt" : "$gt";
+        if (idField === sortField) {
             const continuation = {
                 [sortField]: {
-                    [cmp]: cursor.lastValue,
+                    [cmp]: lastValue,
                 },
             };
-            if (!Object.keys(selector || {}).length)
+            if (!selector || !Object.keys(selector).length) {
                 return continuation;
+            }
             return {
                 $and: [selector, continuation],
             };
         }
-        const continuation = {
-            $or: [
+        const clauses = variant === "same"
+            ? [
                 {
                     [sortField]: {
-                        [cmp]: cursor.lastValue,
+                        $eq: lastValue,
                     },
                 },
                 {
-                    $and: [
-                        {
-                            [sortField]: {
-                                $eq: cursor.lastValue,
-                            },
-                        },
-                        {
-                            [cursor.idField]: {
-                                [cmp]: cursor.lastId,
-                            },
-                        },
-                    ],
+                    [idField]: {
+                        [idCmp]: lastId,
+                    },
                 },
-            ],
-        };
-        if (!Object.keys(selector || {}).length)
-            return continuation;
+            ]
+            : [
+                {
+                    [sortField]: {
+                        [cmp]: lastValue,
+                    },
+                },
+            ];
+        if (!selector || !Object.keys(selector).length) {
+            return clauses.length === 1
+                ? clauses[0]
+                : {
+                    $and: clauses,
+                };
+        }
         return {
-            $and: [selector, continuation],
+            $and: [selector, ...clauses],
         };
     }
-    static normalizePrivateSort(query, idField = "id") {
-        if (!Array.isArray(query.sort) || query.sort.length === 0) {
-            throw new PagingError("Private collection pagination requires an explicit Mango sort");
+    static buildOrlessKeysetContinuationQueries(query, cursor, pageSize) {
+        const baseQuery = { ...query };
+        delete baseQuery.skip;
+        delete baseQuery.bookmark;
+        delete baseQuery.limit;
+        if (cursor.idField === cursor.sortField) {
+            const single = {
+                ...baseQuery,
+                selector: FabricContractAdapter.buildPrivateContinuationSelector((baseQuery.selector || {}), cursor.sortField, cursor.direction, cursor.idField, cursor.lastValue, cursor.lastId, "same"),
+                limit: pageSize + 1,
+            };
+            return [single];
         }
-        const firstSort = Object.entries(query.sort[0] || {})[0];
-        if (!firstSort || typeof firstSort[0] !== "string") {
-            throw new PagingError("Private collection pagination requires a valid first sort field");
+        const first = {
+            ...baseQuery,
+            selector: FabricContractAdapter.buildPrivateContinuationSelector((baseQuery.selector || {}), cursor.sortField, cursor.direction, cursor.idField, cursor.lastValue, cursor.lastId, "same"),
+            limit: pageSize + 1,
+        };
+        const second = {
+            ...baseQuery,
+            selector: FabricContractAdapter.buildPrivateContinuationSelector((baseQuery.selector || {}), cursor.sortField, cursor.direction, cursor.idField, cursor.lastValue, cursor.lastId, "next"),
+            limit: pageSize + 1,
+        };
+        return [first, second];
+    }
+    static ensureDeterministicPrivateSort(query, tieBreaker) {
+        if (!Array.isArray(query.sort) || !query.sort.length) {
+            throw new PagingError("Private Mango pagination requires an explicit sort. Add orderBy(...) so a stable generated index can be selected.");
         }
-        const sortField = firstSort[0];
-        const direction = String(firstSort[1] || "asc").toLowerCase();
-        if (direction !== "asc" && direction !== "desc") {
-            throw new PagingError(`Unsupported private pagination sort direction: ${direction}`);
+        const direction = (getSortDirection(query) ||
+            OrderDirection.ASC);
+        couchEnsureDeterministicSort(query, tieBreaker, direction);
+        const sortFields = getSortFields(query);
+        const sortField = sortFields[0];
+        if (!sortField) {
+            throw new PagingError("Private Mango pagination requires a valid first sort field.");
         }
-        const hasIdTieBreaker = idField === sortField ||
-            query.sort.some((entry) => {
-                const [field, dir] = Object.entries(entry || {})[0] || [];
-                return (field === idField && String(dir || "").toLowerCase() === direction);
-            });
-        if (!hasIdTieBreaker && idField !== sortField) {
-            query.sort = [...query.sort, { [idField]: direction }];
+        if (!sortFields.includes(tieBreaker)) {
+            throw new PagingError(`Private Mango pagination requires tie-breaker sort field "${tieBreaker}".`);
         }
         return {
             sortField,
             direction: direction,
-            idField,
+            idField: tieBreaker,
         };
     }
     static parsePrivateResultValue(value) {
         try {
             const parsed = JSON.parse(value.toString("utf8"));
-            if (!parsed || typeof parsed !== "object") {
-                throw new Error("Private query result is not an object");
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error("Private query result is not a JSON object");
             }
             return parsed;
         }
@@ -231,6 +221,102 @@ export class FabricContractAdapter extends CouchDBAdapter {
             throw new SerializationError(`Failed to parse private query result while building bookmark: ${e}`);
         }
     }
+    static async executePrivateMangoPageQueries(stub, collection, queries, pageSize, log) {
+        const paged = [];
+        for (const query of queries) {
+            if (paged.length >= pageSize + 1) {
+                break;
+            }
+            const remaining = pageSize + 1 - paged.length;
+            const queryForExecution = {
+                ...query,
+                limit: remaining,
+            };
+            delete queryForExecution.skip;
+            delete queryForExecution.bookmark;
+            log.debug(`Querying collection ${collection} for ${JSON.stringify(queryForExecution)}`);
+            const response = await stub.getPrivateDataQueryResult(collection, JSON.stringify(queryForExecution));
+            const iterator = (response.iterator ||
+                response);
+            try {
+                while (paged.length < pageSize + 1) {
+                    const res = await iterator.next();
+                    if (res.done)
+                        break;
+                    if (!res.value || !res.value.value)
+                        continue;
+                    paged.push({
+                        key: res.value.key,
+                        value: Buffer.isBuffer(res.value.value)
+                            ? res.value.value
+                            : Buffer.from(res.value.value.toString("utf8")),
+                    });
+                }
+            }
+            finally {
+                await iterator.close();
+            }
+        }
+        return paged;
+    }
+    static toFabricPaginationResponse(docs, bookmark) {
+        let idx = 0;
+        const iterator = {
+            async next() {
+                if (idx < docs.length) {
+                    return {
+                        value: docs[idx++],
+                        done: false,
+                    };
+                }
+                return {
+                    value: undefined,
+                    done: true,
+                };
+            },
+            async close() { },
+        };
+        return {
+            iterator: iterator,
+            metadata: {
+                fetchedRecordsCount: docs.length,
+                bookmark,
+            },
+        };
+    }
+    static parseSyntheticPrivateBookmark(bookmark) {
+        if (typeof bookmark !== "string")
+            return undefined;
+        if (!bookmark.startsWith(FabricContractAdapter.PRIVATE_BOOKMARK_PREFIX))
+            return undefined;
+        const raw = bookmark.slice(FabricContractAdapter.PRIVATE_BOOKMARK_PREFIX.length);
+        try {
+            const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+            if (!parsed ||
+                typeof parsed !== "object" ||
+                typeof parsed.sortField !== "string" ||
+                typeof parsed.direction !== "string" ||
+                typeof parsed.idField !== "string" ||
+                typeof parsed.lastId !== "string"
+                || typeof parsed.queryHash !== "string") {
+                return undefined;
+            }
+            return {
+                sortField: parsed.sortField,
+                direction: parsed.direction === "desc" ? "desc" : "asc",
+                idField: parsed.idField,
+                lastValue: parsed.lastValue,
+                lastId: parsed.lastId,
+                queryHash: parsed.queryHash,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    static buildSyntheticPrivateBookmark(cursor) {
+        return `${FabricContractAdapter.PRIVATE_BOOKMARK_PREFIX}${Buffer.from(JSON.stringify(cursor)).toString("base64url")}`;
+    }
     getClient() {
         throw new UnsupportedError("Client is not supported in Fabric contracts");
     }
@@ -623,76 +709,48 @@ export class FabricContractAdapter extends CouchDBAdapter {
                             }
                             case "queryResultPaginated": {
                                 const [stub, rawInput, limit, skip, bookmark, ...args] = argsList;
-                                const { log } = thisArg["logCtx"](args, prop);
+                                const { log, ctx } = thisArg["logCtx"](args, prop);
                                 if (skip !== undefined && skip !== null && Number(skip) > 0) {
-                                    throw new PagingError("Private collection pagination does not support skip/offset pagination. Use the returned bookmark instead.");
+                                    throw new PagingError("Private Mango pagination does not support skip/offset pagination. Use the returned synthetic bookmark instead.");
                                 }
                                 const pageSize = Math.max(1, Number(limit) || 250);
                                 const query = { ...rawInput };
-                                const queryPkField = typeof query["__pkField"] === "string" &&
-                                    query["__pkField"].trim().length
-                                    ? String(query["__pkField"])
-                                    : "id";
-                                delete query["__pkField"];
-                                const { sortField, direction: sortDirection, idField, } = FabricContractAdapter.normalizePrivateSort(query, queryPkField);
+                                const queryInput = query;
+                                const queryPkField = typeof queryInput["__pkField"] === "string" &&
+                                    queryInput["__pkField"].trim().length
+                                    ? String(queryInput["__pkField"])
+                                    : String(ctx?.getOrUndefined("privatePaginationTieBreaker") ||
+                                        "id");
+                                delete queryInput["__pkField"];
                                 const syntheticCursor = FabricContractAdapter.parseSyntheticPrivateBookmark(bookmark);
                                 if (bookmark !== undefined &&
                                     bookmark !== null &&
                                     bookmark !== "" &&
                                     !syntheticCursor) {
-                                    throw new PagingError("Private collection pagination only supports adapter-generated synthetic bookmarks");
+                                    throw new PagingError("Private Mango pagination only supports adapter-generated synthetic bookmarks.");
+                                }
+                                if (!Array.isArray(query.sort) || !query.sort.length) {
+                                    throw new PagingError("Private Mango pagination requires an explicit sort. Add orderBy(...) so a stable generated index can be selected.");
                                 }
+                                const { sortField, direction: sortDirection, idField } = FabricContractAdapter.ensureDeterministicPrivateSort(query, queryPkField);
+                                warnScanProneMangoOperators(query.selector || {}, log);
                                 log.debug(`Private paginated query input collection=${collection} limit=${limit} skip=${skip} bookmark=${bookmark} sortField=${sortField} direction=${sortDirection} synthetic=${Boolean(syntheticCursor)}`);
-                                delete query.skip;
-                                delete query.bookmark;
                                 query.limit = pageSize + 1;
                                 const queryHash = FabricContractAdapter.privateQueryHash(query);
                                 if (syntheticCursor) {
                                     if (syntheticCursor.queryHash !== queryHash) {
-                                        throw new PagingError("Private collection bookmark does not match the current query");
-                                    }
-                                    query.selector = FabricContractAdapter.buildPrivateCursorSelector(query.selector || {}, syntheticCursor.sortField, syntheticCursor.direction, syntheticCursor);
-                                }
-                                log.debug(`Querying collection ${collection} for ${JSON.stringify(query)}`);
-                                const response = await stub.getPrivateDataQueryResult(collection, JSON.stringify(query));
-                                const iterator = (response.iterator ||
-                                    response);
-                                const responseMetadata = response.metadata ||
-                                    iterator.metadata ||
-                                    {};
-                                log.debug(`Private paginated response collection=${collection} metadata=${JSON.stringify(responseMetadata)}`);
-                                log.verbose(`iterator from collection ${collection} received`);
-                                const paged = [];
-                                let hasMore = false;
-                                try {
-                                    while (true) {
-                                        const res = await iterator.next();
-                                        if (res.done)
-                                            break;
-                                        if (res.value && res.value.value) {
-                                            const key = res.value.key;
-                                            if (paged.length < pageSize) {
-                                                paged.push({
-                                                    key,
-                                                    value: Buffer.isBuffer(res.value.value)
-                                                        ? res.value.value
-                                                        : Buffer.from(res.value.value.toString("utf8")),
-                                                });
-                                            }
-                                            else {
-                                                hasMore = true;
-                                                break; // early exit
-                                            }
-                                        }
+                                        throw new PagingError("Private Mango bookmark does not match the current query.");
                                     }
                                 }
-                                finally {
-                                    await iterator.close();
-                                }
-                                log.debug(`Private paginated collection=${collection} produced ${paged.length} rows hasMore=${hasMore}`);
+                                const queries = syntheticCursor
+                                    ? FabricContractAdapter.buildOrlessKeysetContinuationQueries(query, syntheticCursor, pageSize)
+                                    : [{ ...query, limit: pageSize + 1 }];
+                                const paged = await FabricContractAdapter.executePrivateMangoPageQueries(stub, collection, queries, pageSize, log);
+                                const hasMore = paged.length > pageSize;
+                                const docs = hasMore ? paged.slice(0, pageSize) : paged;
                                 let nextBookmark = "";
-                                if (hasMore && paged.length) {
-                                    const last = paged[paged.length - 1];
+                                if (hasMore && docs.length) {
+                                    const last = docs[docs.length - 1];
                                     const lastDoc = FabricContractAdapter.parsePrivateResultValue(last.value);
                                     if (!(sortField in lastDoc)) {
                                         throw new PagingError(`Cannot build private pagination bookmark: sorted field "${sortField}" is missing from the last result`);
@@ -712,24 +770,7 @@ export class FabricContractAdapter extends CouchDBAdapter {
                                             queryHash,
                                         });
                                 }
-                                // Wrap the page in an async iterator for resultIterator()
-                                let idx = 0;
-                                const arrayIterator = {
-                                    async next() {
-                                        if (idx < paged.length) {
-                                            return { value: paged[idx++], done: false };
-                                        }
-                                        return { value: undefined, done: true };
-                                    },
-                                    async close() { },
-                                };
-                                return {
-                                    iterator: arrayIterator,
-                                    metadata: {
-                                        fetchedRecordsCount: paged.length,
-                                        bookmark: nextBookmark,
-                                    },
-                                };
+                                return FabricContractAdapter.toFabricPaginationResponse(docs, nextBookmark);
                             }
                             default:
                                 throw new InternalError(`Unsupported method override ${String(prop)}`);
@@ -799,6 +840,8 @@ export class FabricContractAdapter extends CouchDBAdapter {
             segregated: false,
             rebuildWithTransient: false,
             fullySegregated: false,
+            strictPrivateMangoPagination: true,
+            privatePaginationTieBreaker: "id",
         };
         if (flags instanceof FabricContractContext || flags instanceof Context) {
             flags = flags.toOverrides();
@@ -933,6 +976,8 @@ export class FabricContractAdapter extends CouchDBAdapter {
         const originalInput = { ...rawInput };
         const { skip, limit } = originalInput;
         const bookmark = originalInput["bookmark"];
+        const hasSort = Array.isArray(originalInput.sort) &&
+            originalInput.sort.length > 0;
         const pkField = typeof originalInput["__pkField"] === "string" &&
             originalInput["__pkField"].trim().length
             ? String(originalInput["__pkField"])
@@ -940,7 +985,8 @@ export class FabricContractAdapter extends CouchDBAdapter {
         const hasSkip = skip !== undefined && skip !== null && Number(skip) > 0;
         const hasBookmark = bookmark !== undefined && bookmark !== null && bookmark !== "";
         const paginationActive = Boolean(limit || hasSkip || hasBookmark);
-        const shouldPaginate = Boolean(paginationActive && (enableSegregates || hasSkip || hasBookmark));
+        const shouldPaginate = Boolean(paginationActive &&
+            (enableSegregates || hasSkip || hasBookmark || hasSort));
         const baseInput = { ...originalInput };
         delete baseInput["skip"];
         delete baseInput["bookmark"];