@degenerate/generic 0.7.1 → 0.9.1

package/dist/application/database/firestore/generics/get-items-from-database.js

@@ -1,87 +1,206 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getItemsFromDatabase = void 0;
-const firebase = __importStar(require("firebase-admin"));
+const firestore_1 = require("firebase-admin/firestore");
 const application_settings_1 = require("../../../../_settings/application-settings");
+const database_errors_1 = require("../../../../errors/database/database-errors");
 const application_audit_log_models_1 = require("../../../../models/application/audit-log/application-audit-log-models");
 const create_audit_log_col_ref_1 = require("../path-references/audit-log/create-audit-log-col-ref");
 const create_application_audit_log_1 = require("../../../audit-log/create-application-audit-log");
-const db = firebase.firestore();
+const page_cursor_1 = require("../page-cursor/page-cursor");
+const firestore_id_helpers_1 = require("../../../../helpers/firestore/firestore-id-helpers");
+// Filters Firestore orders a query by, when no orderBy names their field.
+const INEQUALITY_OPERATORS = new Set(['<', '<=', '>', '>=', '!=', 'not-in']);
+const DOCUMENT_ID_SEGMENTS = ['__name__'];
 /**
- * This function queries the database and returns the items or an empty array.
+ * A field path's segments. A dotted string names a nested field, as everywhere in Firestore. A
+ * FieldPath's typings don't expose its segments, but every FieldPath carries them; they're read
+ * through a checked accessor so all paths order and compare the same way.
+ */
+const segmentsOf = (fieldPath, collectionPath) => {
+    if (typeof fieldPath === 'string') {
+        const segments = fieldPath.split('.');
+        if (segments.some((segment) => segment === '')) {
+            throw new database_errors_1.DatabaseQueryNotSupportedError(collectionPath, `the field path '${fieldPath}' has an empty segment`);
+        }
+        return segments;
+    }
+    const segments = fieldPath.segments;
+    if (!Array.isArray(segments) || segments.length === 0 || !segments.every((segment) => typeof segment === 'string')) {
+        throw new database_errors_1.DatabaseQueryNotSupportedError(collectionPath, 'a FieldPath whose segments can\'t be read');
+    }
+    return [...segments];
+};
+const sameSegments = (left, right) => left.length === right.length && left.every((segment, index) => segment === right[index]);
+// Firestore's field path order (its Path.compareTo): segment by segment, numeric `__id<n>__`
+// segments first and by value, the rest in UTF-8 byte order, then the shorter path first. The
+// numeric pattern is stricter than the SDK's (which treats any `__id…__` as a number, and throws
+// on one that isn't): such names are reserved, so only well-formed ones occur.
+const NUMERIC_SEGMENT = /^__id(-?\d+)__$/;
+const compareSegment = (left, right) => {
+    const leftNumber = NUMERIC_SEGMENT.exec(left);
+    const rightNumber = NUMERIC_SEGMENT.exec(right);
+    if (leftNumber && rightNumber) {
+        const [a, b] = [BigInt(leftNumber[1]), BigInt(rightNumber[1])];
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+    if (leftNumber || rightNumber) {
+        return leftNumber ? -1 : 1;
+    }
+    return Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8'));
+};
+const compareSegments = (left, right) => {
+    for (let index = 0; index < Math.min(left.length, right.length); index++) {
+        const comparison = compareSegment(left[index], right[index]);
+        if (comparison !== 0) {
+            return comparison;
+        }
+    }
+    return left.length - right.length;
+};
+const ordering = (segments, direction) => ({
+    segments,
+    direction,
+    path: new firestore_1.FieldPath(...segments),
+    isDocumentId: sameSegments(segments, DOCUMENT_ID_SEGMENTS),
+});
+/**
+ * The list's orderings, all explicit, so a cursor of values can mark a place in it. They mirror
+ * the order Firestore uses implicitly: the orderBy, then every other field an inequality filter
+ * uses, sorted by field path, then the document id, which makes the order total. Extra orderings
+ * take the orderBy's direction.
+ *
+ * @throws {DatabaseQueryNotSupportedError} for an order by document id with an inequality filter on
+ *     another field (Firestore rejects any ordering after the key).
+ */
+const listOrderings = (getInformation) => {
+    const collectionPath = getInformation.itemColRef.path;
+    const direction = getInformation.orderBy?.direction ?? 'asc';
+    const orderings = [];
+    if (getInformation.orderBy) {
+        orderings.push(ordering(segmentsOf(getInformation.orderBy.fieldPath, collectionPath), getInformation.orderBy.direction));
+    }
+    const inequalityFields = [];
+    for (const queryField of getInformation.queryFields) {
+        // Every filter's path is checked, so a malformed one is refused here rather than by the SDK.
+        const segments = segmentsOf(queryField.fieldPath, collectionPath);
+        if (!INEQUALITY_OPERATORS.has(queryField.opStr)) {
+            continue;
+        }
+        const isKnown = sameSegments(segments, DOCUMENT_ID_SEGMENTS)
+            || orderings.some((existing) => sameSegments(existing.segments, segments))
+            || inequalityFields.some((field) => sameSegments(field, segments));
+        if (!isKnown) {
+            inequalityFields.push(segments);
+        }
+    }
+    inequalityFields.sort(compareSegments);
+    if (orderings[0]?.isDocumentId && inequalityFields.length > 0) {
+        // Firestore orders inequality fields after the id, and rejects any ordering after the key.
+        throw new database_errors_1.DatabaseQueryNotSupportedError(collectionPath, 'an order by document id with an inequality filter on another field');
+    }
+    orderings.push(...inequalityFields.map((segments) => ordering(segments, direction)));
+    if (!orderings.some((existing) => existing.isDocumentId)) {
+        orderings.push(ordering(DOCUMENT_ID_SEGMENTS, direction));
+    }
+    return orderings;
+};
+/**
+ * Whether a cursor's values mark a place in this list: one value per ordering, with a single
+ * document id where the list orders by id. The other values are the caller's: they only position
+ * the page, and the filters still decide which items it holds, so made-up values reveal nothing.
+ */
+const fitsList = (values, orderings) => values.length === orderings.length
+    && orderings.every((ordering, index) => !ordering.isDocumentId || (0, firestore_id_helpers_1.isFirestoreDocumentId)(values[index]));
+/**
+ * This function queries the database and returns a page of items, and the cursor for the next page.
  *
  * @param getInformation the get information (instructions for this function)
  * @param userId the user ID performing the action
  * @param applicationAuditLogType the type of audit log to create
  * @param <T> the type of the items to return
- * @returns
+ * @returns the page's items, and nextCursor when more items follow
+ * @throws {DatabaseQueryNotSupportedError} when the list's filters and order can't be run (a bad
+ *     field path, or a filter value the SDK refuses while building the query, such as undefined),
+ *     or the last item's ordered values can't be held in a page cursor. A value the SDK only
+ *     refuses when it serializes the request (a function, say) surfaces as the SDK's own error.
+ * @throws {DatabaseCursorInvalidError} when the cursor is malformed or came from another list.
  */
 const getItemsFromDatabase = async (userId, getInformation, applicationAuditLogType = application_audit_log_models_1.ApplicationAuditLogTypeSchema.enum.global) => {
-    const maxResults = application_settings_1.ApplicationSettings.SystemValues.MaxSnapshotSize; // the maximum number of results to return.
-    const auditLogColRef = (0, create_audit_log_col_ref_1.createAuditLogColRef)(); // create the audit log collection reference
-    // get the items from the database.
-    const itemsToReturn = await db.runTransaction(async (t) => {
-        const databaseItems = [];
-        const itemQuery = getInformation.itemColRef;
-        // add in the query fields if they are set.
+    const collectionPath = getInformation.itemColRef.path;
+    // the maximum number of results to return: a smaller page for a set of large documents.
+    const maxResults = getInformation.isMaxSizeDocumentSet
+        ? application_settings_1.ApplicationSettings.SystemValues.MaxSnapshotSizeLargeDocSet
+        : application_settings_1.ApplicationSettings.SystemValues.MaxSnapshotSize;
+    // The orderings and the cursor depend only on the input, so both are settled before the
+    // transaction, and a list or cursor that can't be used is refused without starting one.
+    const orderings = listOrderings(getInformation);
+    let cursorValues;
+    if (getInformation.cursor !== undefined) {
+        // References in the cursor belong to the listed collection's own database.
+        cursorValues = (0, page_cursor_1.decodePageCursor)(getInformation.cursor, getInformation.itemColRef.firestore, orderings);
+        if (cursorValues === undefined || !fitsList(cursorValues, orderings)) {
+            throw new database_errors_1.DatabaseCursorInvalidError(collectionPath);
+        }
+    }
+    // Build the whole query up front too. Firestore queries are immutable: where, orderBy,
+    // startAfter and limit each return a new Query, which has to be kept (dropping it once ran every
+    // list unfiltered, unsorted and unlimited). Filters take a FieldPath built from the checked
+    // segments, as orderings do, so a field that can be ordered by can also be filtered on; any
+    // filter value or cursor value the SDK refuses becomes a typed error, with no transaction started.
+    let itemQuery = getInformation.itemColRef;
+    try {
         for (const queryField of getInformation.queryFields) {
-            itemQuery.where(queryField.fieldPath, queryField.opStr, queryField.value);
+            const path = new firestore_1.FieldPath(...segmentsOf(queryField.fieldPath, collectionPath));
+            itemQuery = itemQuery.where(path, queryField.opStr, queryField.value);
         }
-        // If order by is set, then order the items.
-        if (getInformation.orderBy) {
-            itemQuery.orderBy(getInformation.orderBy.fieldPath, getInformation.orderBy.direction);
+        for (const ordering of orderings) {
+            itemQuery = itemQuery.orderBy(ordering.path, ordering.direction);
         }
-        // add in the query for the pagination.
-        if (typeof getInformation.lastId !== 'undefined' && getInformation.lastId.length > 0) {
-            const lastElement = await t.get(itemQuery.doc(getInformation.lastId));
-            itemQuery.startAfter(lastElement);
+    }
+    catch (error) {
+        throw error instanceof database_errors_1.DatabaseQueryNotSupportedError ? error
+            : new database_errors_1.DatabaseQueryNotSupportedError(collectionPath, 'a filter or order Firestore can\'t build', error);
+    }
+    // Start after the previous page's last item. The cursor holds that item's values, which the
+    // caller saw while it was in the list, so no document is read: a page still follows an item
+    // deleted or moved out of the list since, and a cursor naming a document outside the filters
+    // positions the page without revealing anything about it.
+    if (cursorValues !== undefined) {
+        try {
+            itemQuery = itemQuery.startAfter(...cursorValues);
         }
-        // set the limit and query the database.
-        itemQuery.limit(maxResults);
-        const itemSnapshot = await t.get(itemQuery);
-        // get the items from the database.
-        for (const docSnap of itemSnapshot.docs) {
-            const item = docSnap.data();
-            databaseItems.push(item);
+        catch (error) {
+            // Firestore refuses a value it can't order by; the cursor is the caller's input.
+            throw new database_errors_1.DatabaseCursorInvalidError(collectionPath, error);
         }
+    }
+    // Read one item past the page: if it exists, more follow, and the page's last item starts
+    // the next one. A list that ends exactly at a page boundary gets no cursor.
+    itemQuery = itemQuery.limit(maxResults + 1);
+    const auditLogColRef = (0, create_audit_log_col_ref_1.createAuditLogColRef)(); // create the audit log collection reference
+    // get the items from the database.
+    const page = await (0, firestore_1.getFirestore)().runTransaction(async (t) => {
+        const itemSnapshot = await t.get(itemQuery);
+        const pageDocs = itemSnapshot.docs.slice(0, maxResults);
+        const databaseItems = pageDocs.map((docSnap) => docSnap.data());
         // create the audit log information
         const auditLog = (0, create_application_audit_log_1.createApplicationAuditLog)(application_audit_log_models_1.ApplicationAuditLogActionSchema.enum.list, getInformation.auditLogSubType, userId, applicationAuditLogType, getInformation.alai, undefined, undefined);
         t.create(auditLogColRef.doc(), auditLog); // add the audit log to the database.
-        return databaseItems;
+        if (itemSnapshot.docs.length <= maxResults) {
+            return { items: databaseItems };
+        }
+        const lastItem = pageDocs[pageDocs.length - 1];
+        const values = orderings.map((ordering) => (ordering.isDocumentId ? lastItem.id : lastItem.get(ordering.path)));
+        try {
+            return { items: databaseItems, nextCursor: (0, page_cursor_1.encodePageCursor)(values, orderings) };
+        }
+        catch (error) {
+            // A value type the token has no tag for (Enterprise-edition BSON types), or a token
+            // over the cap: refuse with a typed error rather than hand out an unusable cursor.
+            throw new database_errors_1.DatabaseQueryNotSupportedError(collectionPath, 'the last item\'s ordered values can\'t be held in a page cursor', error);
+        }
     });
-    return itemsToReturn;
+    return page;
 };
 exports.getItemsFromDatabase = getItemsFromDatabase;

package/dist/application/database/firestore/generics/update-items-on-database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-items-on-database.d.ts","sourceRoot":"","sources":["../../../../../src/application/database/firestore/generics/update-items-on-database.ts"],"names":[],"mappings":"AACA,OAAO,EAEH,uBAAuB,EAE1B,MAAM,uEAAuE,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,MAAM,0DAA0D,CAAC;AAMtG;;;;;;;GAOG;AACH,QAAA,MAAM,qBAAqB,GAAU,CAAC,EAClC,2BAA2B,0BAA0B,EAAE,EACvD,QAAQ,MAAM,EACd,0BAAyB,uBAAmE,KAC7F,OAAO,CAAC,IAAI,CA0Bd,CAAC;AAEF,OAAO,EAAE,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"update-items-on-database.d.ts","sourceRoot":"","sources":["../../../../../src/application/database/firestore/generics/update-items-on-database.ts"],"names":[],"mappings":"AACA,OAAO,EAEH,uBAAuB,EAE1B,MAAM,uEAAuE,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,MAAM,0DAA0D,CAAC;AAItG;;;;;;;GAOG;AACH,QAAA,MAAM,qBAAqB,GAAU,CAAC,EAClC,2BAA2B,0BAA0B,EAAE,EACvD,QAAQ,MAAM,EACd,0BAAyB,uBAAmE,KAC7F,OAAO,CAAC,IAAI,CA0Bd,CAAC;AAEF,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/application/database/firestore/generics/update-items-on-database.js

@@ -1,45 +1,11 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateItemsOnDatabase = void 0;
-const admin = __importStar(require("firebase-admin"));
+const firestore_1 = require("firebase-admin/firestore");
 const application_audit_log_models_1 = require("../../../../models/application/audit-log/application-audit-log-models");
 const create_audit_log_col_ref_1 = require("../path-references/audit-log/create-audit-log-col-ref");
 const create_application_audit_log_1 = require("../../../audit-log/create-application-audit-log");
 const database_errors_1 = require("../../../../errors/database/database-errors");
-const db = admin.firestore();
 /**
  * This updates the items on the database.
  *
@@ -50,7 +16,7 @@ const db = admin.firestore();
  */
 const updateItemsOnDatabase = async (databaseChangeInformation, userId, applicationAuditLogType = application_audit_log_models_1.ApplicationAuditLogTypeSchema.enum.global) => {
     // loop the transaction and update the database
-    await db.runTransaction(async (t) => {
+    await (0, firestore_1.getFirestore)().runTransaction(async (t) => {
         // get the existing records from the database
         const existingRecords = [];
         for (const changeRecords of databaseChangeInformation) {

package/dist/application/database/firestore/generics/update-items-properties-on-database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-items-properties-on-database.d.ts","sourceRoot":"","sources":["../../../../../src/application/database/firestore/generics/update-items-properties-on-database.ts"],"names":[],"mappings":"AAEA,OAAO,EAGH,uBAAuB,EAE1B,MAAM,uEAAuE,CAAC;AAC/E,OAAO,EAAE,kCAAkC,EAAE,MAAM,0DAA0D,CAAC;AAI9G;;;;;;;;GAQG;AACH,QAAA,MAAM,+BAA+B,GAAU,CAAC,EAC5C,uBAAuB,kCAAkC,EAAE,EAC3D,QAAQ,MAAM,EACd,0BAAyB,uBAAmE,KAC7F,OAAO,CAAC,IAAI,CA6Bd,CAAC;AAEF,OAAO,EAAE,+BAA+B,EAAE,CAAC"}
+{"version":3,"file":"update-items-properties-on-database.d.ts","sourceRoot":"","sources":["../../../../../src/application/database/firestore/generics/update-items-properties-on-database.ts"],"names":[],"mappings":"AAEA,OAAO,EAGH,uBAAuB,EAE1B,MAAM,uEAAuE,CAAC;AAC/E,OAAO,EAAE,kCAAkC,EAAE,MAAM,0DAA0D,CAAC;AAG9G;;;;;;;;GAQG;AACH,QAAA,MAAM,+BAA+B,GAAU,CAAC,EAC5C,uBAAuB,kCAAkC,EAAE,EAC3D,QAAQ,MAAM,EACd,0BAAyB,uBAAmE,KAC7F,OAAO,CAAC,IAAI,CA6Bd,CAAC;AAEF,OAAO,EAAE,+BAA+B,EAAE,CAAC"}

package/dist/application/database/firestore/generics/update-items-properties-on-database.js

@@ -1,45 +1,11 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateItemsPropertiesOnDatabase = void 0;
-const admin = __importStar(require("firebase-admin"));
+const firestore_1 = require("firebase-admin/firestore");
 const database_errors_1 = require("../../../../errors/database/database-errors");
 const application_audit_log_models_1 = require("../../../../models/application/audit-log/application-audit-log-models");
 const create_audit_log_col_ref_1 = require("../path-references/audit-log/create-audit-log-col-ref");
 const create_application_audit_log_1 = require("../../../audit-log/create-application-audit-log");
-const db = admin.firestore();
 /**
  * This takes a partial object to update and updates the properties on the database. This function is used to update
  * the properties of an object on the database.
@@ -51,7 +17,7 @@ const db = admin.firestore();
  */
 const updateItemsPropertiesOnDatabase = async (databaseChangeRecords, userId, applicationAuditLogType = application_audit_log_models_1.ApplicationAuditLogTypeSchema.enum.global) => {
     // loop the transaction and update the database
-    await db.runTransaction(async (t) => {
+    await (0, firestore_1.getFirestore)().runTransaction(async (t) => {
         const auditLogUpdates = []; // create an array of audit log updates
         const updatedRecord = []; // create an array of updated records
         // get the existing records from the database

package/dist/application/database/firestore/page-cursor/page-cursor.d.ts

@@ -0,0 +1,33 @@
+import { Firestore } from 'firebase-admin/firestore';
+import { OrderByDirection } from '../../../../models/application/database/firestore-models';
+/**
+ * One of a list's orderings, as a cursor records it: the field's path segments and the direction.
+ */
+export interface IPageCursorOrdering {
+    segments: string[];
+    direction: OrderByDirection;
+}
+/**
+ * Encodes a page's cursor values as an opaque string token.
+ *
+ * @param values the last item's value for each of the list's orderings, in order.
+ * @param orderings the list's orderings, which the token records so it only fits that list.
+ * @returns the token, in URL-safe (base64url) characters; its size depends on the ordered values.
+ * @throws {TypeError} when a value is of a type the token can't hold (such as Enterprise-edition
+ *     BSON types), and {RangeError} when the token would exceed MaxPageCursorLength.
+ */
+declare const encodePageCursor: (values: unknown[], orderings: IPageCursorOrdering[]) => string;
+/**
+ * Decodes a page cursor token back into its Firestore values.
+ *
+ * @param token a token from encodePageCursor.
+ * @param firestore the Firestore instance document references are rebuilt against.
+ * @param orderings the orderings of the list the token is used on.
+ * @returns the cursor's values, or undefined when the token is malformed, longer than
+ *     ApplicationSettings.SystemValues.MaxPageCursorLength, or came from a list with different
+ *     orderings. The length is checked before parsing, and the orderings and value count before any
+ *     value is decoded.
+ */
+declare const decodePageCursor: (token: string, firestore: Firestore, orderings: IPageCursorOrdering[]) => unknown[] | undefined;
+export { decodePageCursor, encodePageCursor };
+//# sourceMappingURL=page-cursor.d.ts.map

package/dist/application/database/firestore/page-cursor/page-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-cursor.d.ts","sourceRoot":"","sources":["../../../../../src/application/database/firestore/page-cursor/page-cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,SAAS,EAAuB,MAAM,0BAA0B,CAAC;AAEzG,OAAO,EAAE,gBAAgB,EAAE,MAAM,0DAA0D,CAAC;AAqC5F;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,gBAAgB,CAAC;CAC/B;AA0ID;;;;;;;;GAQG;AACH,QAAA,MAAM,gBAAgB,GAAI,QAAQ,OAAO,EAAE,EAAE,WAAW,mBAAmB,EAAE,KAAG,MAS/E,CAAC;AAEF;;;;;;;;;;GAUG;AACH,QAAA,MAAM,gBAAgB,GAAI,OAAO,MAAM,EAAE,WAAW,SAAS,EAAE,WAAW,mBAAmB,EAAE,KAAG,OAAO,EAAE,GAAG,SAc7G,CAAC;AAEF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/application/database/firestore/page-cursor/page-cursor.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodePageCursor = exports.decodePageCursor = void 0;
+const firestore_1 = require("firebase-admin/firestore");
+const application_settings_1 = require("../../../../_settings/application-settings");
+const firestore_id_helpers_1 = require("../../../../helpers/firestore/firestore-id-helpers");
+// A page cursor travels as an opaque string of URL-safe (base64url) characters; its size depends
+// on the ordered values (see IDatabasePageCursorSchema). Inside it, every Firestore value keeps its type: a Timestamp sent as plain JSON
+// would come back as a map, which Firestore orders after every timestamp, and the page would
+// silently start in the wrong place.
+//
+// The token is base64url JSON: { v: 1, o: <the list's orderings>, values: [...] }. The orderings
+// tie a cursor to the list it came from, so one passed to a differently ordered list is refused
+// rather than silently starting the page in the wrong place. Strings, booleans, null and finite
+// numbers are written as themselves; every other value is a one-key tag object, and a map is
+// always tagged, so any untagged object in a token is malformed.
+const TOKEN_VERSION = 1;
+// Firestore's own limits, so a decoded value the backend would reject is refused as a bad cursor
+// up front rather than failing later with a raw error: maps and arrays nest at most 20 deep, and a
+// vector holds at most 2048 numbers.
+const MAX_DEPTH = 20;
+const MAX_VECTOR_LENGTH = 2048;
+// Map keys, strings and ids are checked with the shared Firestore id helpers: a cursor can only
+// hold names and text read from a stored document, so a reserved or empty key, a lone surrogate or
+// an invalid id is forged, and refusing it here matters because Firestore fails some of them with
+// an error a transaction retries for minutes.
+// A document path: collection and id pairs, each a valid id. A cursor can only hold a reference
+// read from a stored document, so any other path is forged.
+const isDocumentPath = (path) => {
+    const segments = path.split('/');
+    return segments.length % 2 === 0 && segments.every(firestore_id_helpers_1.isFirestoreDocumentId);
+};
+// Firestore integers are 64-bit.
+const MIN_INT64 = -(2n ** 63n);
+const MAX_INT64 = 2n ** 63n - 1n;
+const orderingsKey = (orderings) => JSON.stringify(orderings.map((ordering) => [ordering.segments, ordering.direction]));
+const isPlainObject = (value) => typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+// firebase-admin doesn't export VectorValue, so it's recognised by its shape.
+const isVectorValue = (value) => typeof value === 'object' && value !== null && value.constructor?.name === 'VectorValue'
+    && typeof value.toArray === 'function';
+const encodeValue = (value) => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'bigint') {
+        return { $int: value.toString() }; // what Firestore returns for an integer with useBigInt
+    }
+    if (typeof value === 'number') {
+        if (Object.is(value, -0)) {
+            return { $num: '-0' }; // String(-0) is '0', and JSON writes -0 as 0
+        }
+        return Number.isFinite(value) ? value : { $num: String(value) };
+    }
+    if (value instanceof firestore_1.Timestamp) {
+        return { $ts: [value.seconds, value.nanoseconds] };
+    }
+    if (value instanceof firestore_1.GeoPoint) {
+        return { $geo: [value.latitude, value.longitude] };
+    }
+    if (value instanceof firestore_1.DocumentReference) {
+        return { $ref: value.path };
+    }
+    if (value instanceof Uint8Array) {
+        return { $bytes: Buffer.from(value).toString('base64') };
+    }
+    if (isVectorValue(value)) {
+        return { $vec: value.toArray().map(encodeValue) }; // numbers, so ±Infinity and -0 keep their $num tags
+    }
+    if (Array.isArray(value)) {
+        return value.map(encodeValue);
+    }
+    if (isPlainObject(value)) {
+        return { $map: Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, encodeValue(entry)])) };
+    }
+    throw new TypeError(`A page cursor can't hold a value of type ${typeof value}`);
+};
+const isNumberPair = (value) => Array.isArray(value) && value.length === 2 && value.every((entry) => typeof entry === 'number');
+// A key a stored map can hold: not empty, not reserved, and well-formed.
+const isAllowedMapKey = (key) => key !== '' && !(0, firestore_id_helpers_1.isReservedFirestoreName)(key) && (0, firestore_id_helpers_1.isWellFormedText)(key);
+const decodeValue = (encoded, firestore, depth = 0) => {
+    if (depth > MAX_DEPTH) {
+        throw new TypeError('nested too deep');
+    }
+    if (typeof encoded === 'string') {
+        if (!(0, firestore_id_helpers_1.isWellFormedText)(encoded)) {
+            throw new TypeError('malformed string');
+        }
+        return encoded;
+    }
+    if (encoded === null || typeof encoded === 'boolean' || typeof encoded === 'number') {
+        return encoded;
+    }
+    if (Array.isArray(encoded)) {
+        return encoded.map((entry) => decodeValue(entry, firestore, depth + 1));
+    }
+    if (!isPlainObject(encoded) || Object.keys(encoded).length !== 1) {
+        throw new TypeError('malformed value');
+    }
+    const [[tag, body]] = Object.entries(encoded);
+    switch (tag) {
+        case '$num':
+            if (body === 'NaN' || body === 'Infinity' || body === '-Infinity' || body === '-0') {
+                return Number(body);
+            }
+            break;
+        case '$int':
+            if (typeof body === 'string' && /^-?\d{1,20}$/.test(body)) {
+                const value = BigInt(body);
+                if (value >= MIN_INT64 && value <= MAX_INT64) {
+                    return value;
+                }
+            }
+            break;
+        case '$ts':
+            if (isNumberPair(body)) {
+                return new firestore_1.Timestamp(body[0], body[1]);
+            }
+            break;
+        case '$geo':
+            if (isNumberPair(body)) {
+                return new firestore_1.GeoPoint(body[0], body[1]);
+            }
+            break;
+        case '$ref':
+            if (typeof body === 'string' && isDocumentPath(body)) {
+                return firestore.doc(body);
+            }
+            break;
+        case '$bytes':
+            if (typeof body === 'string') {
+                return Buffer.from(body, 'base64');
+            }
+            break;
+        case '$vec':
+            if (Array.isArray(body) && body.length >= 1 && body.length <= MAX_VECTOR_LENGTH) {
+                // An element is a number or a `$num` tag, nothing else, so a vector can't nest
+                // anything (or recurse past MAX_DEPTH); NaN can't be stored, so it's refused.
+                return firestore_1.FieldValue.vector(body.map((entry) => {
+                    const isNumberTag = isPlainObject(entry) && Object.keys(entry).length === 1 && '$num' in entry;
+                    const element = typeof entry === 'number' || isNumberTag
+                        // a scalar, so it sits at the vector's depth; the shape check rules out nesting
+                        ? decodeValue(entry, firestore, depth)
+                        : undefined;
+                    if (typeof element !== 'number' || Number.isNaN(element)) {
+                        throw new TypeError('malformed vector element');
+                    }
+                    return element;
+                }));
+            }
+            break;
+        case '$map':
+            if (isPlainObject(body) && Object.keys(body).every(isAllowedMapKey)) {
+                return Object.fromEntries(Object.entries(body).map(([key, entry]) => [key, decodeValue(entry, firestore, depth + 1)]));
+            }
+            break;
+    }
+    throw new TypeError('malformed value');
+};
+/**
+ * Encodes a page's cursor values as an opaque string token.
+ *
+ * @param values the last item's value for each of the list's orderings, in order.
+ * @param orderings the list's orderings, which the token records so it only fits that list.
+ * @returns the token, in URL-safe (base64url) characters; its size depends on the ordered values.
+ * @throws {TypeError} when a value is of a type the token can't hold (such as Enterprise-edition
+ *     BSON types), and {RangeError} when the token would exceed MaxPageCursorLength.
+ */
+const encodePageCursor = (values, orderings) => {
+    const token = Buffer.from(JSON.stringify({ v: TOKEN_VERSION, o: orderingsKey(orderings), values: values.map(encodeValue) }))
+        .toString('base64url');
+    if (token.length > application_settings_1.ApplicationSettings.SystemValues.MaxPageCursorLength) {
+        // Rare but reachable (an ordered value Firestore stores small that encodes large, such as
+        // millions of empty Bytes): never issue a cursor the next call would refuse.
+        throw new RangeError('A page cursor would be longer than MaxPageCursorLength');
+    }
+    return token;
+};
+exports.encodePageCursor = encodePageCursor;
+/**
+ * Decodes a page cursor token back into its Firestore values.
+ *
+ * @param token a token from encodePageCursor.
+ * @param firestore the Firestore instance document references are rebuilt against.
+ * @param orderings the orderings of the list the token is used on.
+ * @returns the cursor's values, or undefined when the token is malformed, longer than
+ *     ApplicationSettings.SystemValues.MaxPageCursorLength, or came from a list with different
+ *     orderings. The length is checked before parsing, and the orderings and value count before any
+ *     value is decoded.
+ */
+const decodePageCursor = (token, firestore, orderings) => {
+    if (token.length > application_settings_1.ApplicationSettings.SystemValues.MaxPageCursorLength) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
+        if (!isPlainObject(parsed) || parsed.v !== TOKEN_VERSION || parsed.o !== orderingsKey(orderings)
+            || !Array.isArray(parsed.values) || parsed.values.length !== orderings.length) {
+            return undefined;
+        }
+        return parsed.values.map((entry) => decodeValue(entry, firestore));
+    }
+    catch {
+        return undefined;
+    }
+};
+exports.decodePageCursor = decodePageCursor;

package/dist/application/database/firestore/path-references/audit-log/create-audit-log-col-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-audit-log-col-ref.d.ts","sourceRoot":"","sources":["../../../../../../src/application/database/firestore/path-references/audit-log/create-audit-log-col-ref.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAI/D;;;;GAIG;AACH,QAAA,MAAM,oBAAoB,QAAO,mBAEhC,CAAC;AAEF,OAAO,EAAE,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"create-audit-log-col-ref.d.ts","sourceRoot":"","sources":["../../../../../../src/application/database/firestore/path-references/audit-log/create-audit-log-col-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAgB,MAAM,0BAA0B,CAAC;AAE7E;;;;GAIG;AACH,QAAA,MAAM,oBAAoB,QAAO,mBAEhC,CAAC;AAEF,OAAO,EAAE,oBAAoB,EAAE,CAAC"}