@knymbus/firestoredb 1.0.10 → 1.0.12

package/dist/cjs/FirestoreDB.d.ts

@@ -1,12 +1,14 @@
-import { Firestore } from "firebase/firestore";
+import type { Firestore, FirestoreError, Unsubscribe } from 'firebase/firestore';
 import { FirestoreQuery } from './FirestoreQuery';
-import { DocumentInput, QueryFilter, UpdateDocument, WithSystemFields } from './types';
+import { DocumentInput, FirestoreSDK, QueryFilter, UpdateDocument, WithSystemFields } from './types';
 export interface DBOptions {
     softDelete?: boolean;
 }
 export declare class FirestoreDB<T> {
     private _db;
     private _collectionName;
+    private _sdk;
+    private _options;
     private _collectionRef;
     private _isSoftDeleteEnabled;
     /**
@@ -14,7 +16,7 @@ export declare class FirestoreDB<T> {
      * @param db: Firebase
      * @param collection string
      */
-    constructor(db: Firestore, collectionName: string, options?: DBOptions);
+    constructor(_db: Firestore, _collectionName: string, _sdk: FirestoreSDK, _options?: DBOptions);
     /**
      * FIRESTOREDB: findOne({ age: '13' }); or findOne('id_123');
      */
@@ -83,13 +85,18 @@ export declare class FirestoreDB<T> {
         restoredCount: number;
     }>;
     /**
- * MONGODB: db.collection.watch(filter)
- * A real-time listener that bypasses the manual cache and
- * pushes updates as they happen in the database.
- */
-    watch<T>(filter: Record<string, any> | undefined, callback: (data: WithSystemFields<T>[]) => void, onError?: (error: any) => void): import("@firebase/firestore").Unsubscribe;
+     * @title
+     * FIRESTOREDB: collection.watch(filter)
+     *
+     * @detail
+     * A real-time listener that bypasses the manual cache and
+     * pushes updates as they happen in the database.
+     */
+    watch<T>(filter: Record<string, any> | undefined, callback: (data: WithSystemFields<T>[]) => void, onError?: (error: FirestoreError) => void): Unsubscribe;
     /**
      * Efficiently checks if a document exists without downloading it. (only metadata).
+     *
+     * @optimized
      * Optimized to only check for the presence of a document
      */
     exists: (filter: Record<string, any>) => Promise<boolean>;
@@ -106,9 +113,15 @@ export declare class FirestoreDB<T> {
     private _buildConstraints;
     private _flattenFilter;
     /**
-     * In FirestoreDB class:
+     * FirestoreDB class:
      * Purges all cached queries for THIS collection to ensure data freshness.
      */
     private _invalidateCache;
+    /**
+     * This will try to get the document Reference of a given id, however if id missing return a auto generated Document Referrence
+     * @param docId optional
+     * @returns Firebase DocumentReferrence
+     */
+    private _getDocRef;
 }
 //# sourceMappingURL=FirestoreDB.d.ts.map

package/dist/cjs/FirestoreDB.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FirestoreDB.d.ts","sourceRoot":"","sources":["../../src/FirestoreDB.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"FirestoreDB.d.ts","sourceRoot":"","sources":["../../src/FirestoreDB.ts"],"names":[],"mappings":"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"}

package/dist/cjs/FirestoreDB.js

@@ -10,7 +10,6 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FirestoreDB = void 0;
-const firestore_1 = require("firebase/firestore");
 const FirestoreQuery_1 = require("./FirestoreQuery");
 const utils_1 = require("./utils");
 class FirestoreDB {
@@ -19,8 +18,12 @@ class FirestoreDB {
      * @param db: Firebase
      * @param collection string
      */
-    constructor(db, collectionName, options = {}) {
+    constructor(_db, _collectionName, _sdk, _options = {}) {
         var _a;
+        this._db = _db;
+        this._collectionName = _collectionName;
+        this._sdk = _sdk;
+        this._options = _options;
         /**
          * FIRESTOREDB: findOne({ age: '13' }); or findOne('id_123');
          */
@@ -46,29 +49,29 @@ class FirestoreDB {
          * @returns number
          */
         this.countDocuments = (...args_1) => __awaiter(this, [...args_1], void 0, function* (filter = {}) {
-            let q = (0, firestore_1.query)(this._collectionRef, ...this._buildConstraints(filter));
+            let q = this._sdk.query(this._collectionRef, ...this._buildConstraints(filter));
             // Update the query with the incoming filter
-            const snapshot = yield (0, firestore_1.getCountFromServer)(q);
+            const snapshot = yield this._sdk.getCountFromServer(q);
             return snapshot.data().count;
         });
         this.findOneAndUpdate = (filter, updateObject) => __awaiter(this, void 0, void 0, function* () {
             let docRef;
             if (typeof filter === 'string') {
-                docRef = (0, firestore_1.doc)(this._db, this._collectionRef.id, filter);
+                docRef = this._getDocRef(filter);
             }
             else {
                 // if object we need to find the id first using the findOne fn
                 const existing = yield this.findOne(filter);
                 if (!existing)
                     throw new Error("Document not found for update");
-                docRef = (0, firestore_1.doc)(this._db, this._collectionRef.id, existing._id);
+                docRef = this._getDocRef(existing._id);
             }
-            return yield (0, firestore_1.runTransaction)(this._db, (transaction) => __awaiter(this, void 0, void 0, function* () {
+            return yield this._sdk.runTransaction(this._db, (transaction) => __awaiter(this, void 0, void 0, function* () {
                 const docSnap = yield transaction.get(docRef);
                 if (!docSnap.exists())
                     throw new Error("Document Vanished during transaction");
-                transaction.update(docRef, Object.assign(Object.assign({}, updateObject), { updatedAt: (0, firestore_1.serverTimestamp)() }));
-                return Object.assign(Object.assign(Object.assign({ _id: docRef.id }, (docSnap.data() || {})), updateObject), { updatedAt: (0, firestore_1.serverTimestamp)() });
+                transaction.update(docRef, Object.assign(Object.assign({}, updateObject), { updatedAt: this._sdk.serverTimestamp() }));
+                return Object.assign(Object.assign(Object.assign({ _id: docRef.id }, (docSnap.data() || {})), updateObject), { updatedAt: this._sdk.serverTimestamp() });
             }));
         });
         /**
@@ -76,7 +79,7 @@ class FirestoreDB {
          * Basic implementation. For production, you'd expand the 'filter' to handle where clauses.
          */
         this.find = (filter = {}) => {
-            return new FirestoreQuery_1.FirestoreQuery(this._db, this._collectionName, this._collectionRef, filter, this._buildConstraints.bind(this), //Pass the private helper
+            return new FirestoreQuery_1.FirestoreQuery(this._db, this._collectionName, this._collectionRef, filter, this._sdk, this._buildConstraints.bind(this), //Pass the private helper
             this.countDocuments.bind(this), // pass the count helper
             this._isSoftDeleteEnabled);
         };
@@ -85,16 +88,14 @@ class FirestoreDB {
          * Optimized: Uses set with merge or create
          */
         this.insertOne = (entity) => __awaiter(this, void 0, void 0, function* () {
-            const docRef = entity._id
-                ? (0, firestore_1.doc)(this._db, this._collectionRef.id, entity._id) //Custom ID
-                : (0, firestore_1.doc)(this._collectionRef); //Auto ID
+            const docRef = this._getDocRef(entity._id);
             // Using 'set' with { merge: false } acts like an insert/overwrite
-            yield (0, firestore_1.setDoc)(docRef, Object.assign(Object.assign({}, entity), { _id: docRef.id, isDeleted: false, createdAt: (0, firestore_1.serverTimestamp)(), updatedAt: (0, firestore_1.serverTimestamp)() }));
+            yield this._sdk.setDoc(docRef, Object.assign(Object.assign({}, entity), { _id: docRef.id, isDeleted: false, createdAt: this._sdk.serverTimestamp(), updatedAt: this._sdk.serverTimestamp() }));
             // 2. TRIGGER INVALIDATION: Any cached 'find' results for this 
             // collection are now potentially stale.
             this._invalidateCache();
             // 3. REFRESH: Fetch the document back to get the real server-generated timestamps
-            const freshSnap = yield (0, firestore_1.getDoc)(docRef);
+            const freshSnap = yield this._sdk.getDoc(docRef);
             const freshData = Object.assign({ _id: freshSnap.id }, freshSnap.data());
             return (0, utils_1.hydrateDates)(freshData);
         });
@@ -108,14 +109,12 @@ class FirestoreDB {
             const batchPromises = [];
             // 1. Outer Loop: Creates a new batch for every 500 items
             for (let i = 0; i < entities.length; i += CHUNK_SIZE) {
-                const batch = (0, firestore_1.writeBatch)(this._db);
+                const batch = this._sdk.writeBatch(this._db);
                 const chunk = entities.slice(i, i + CHUNK_SIZE);
                 // Inner loop:  Set the item to be created
                 chunk.forEach(entity => {
-                    const docRef = entity._id
-                        ? (0, firestore_1.doc)(this._db, this._collectionRef.id, entity._id) //Custom ID
-                        : (0, firestore_1.doc)(this._collectionRef); //Auto ID
-                    const finalDoc = Object.assign(Object.assign({}, entity), { _id: docRef.id, isDeleted: false, createdAt: (0, firestore_1.serverTimestamp)(), updatedAt: (0, firestore_1.serverTimestamp)() // Added 
+                    const docRef = this._getDocRef(entity._id);
+                    const finalDoc = Object.assign(Object.assign({}, entity), { _id: docRef.id, isDeleted: false, createdAt: this._sdk.serverTimestamp(), updatedAt: this._sdk.serverTimestamp() // Added 
                      });
                     // Add operation to the current batch
                     batch.set(docRef, finalDoc);
@@ -146,7 +145,7 @@ class FirestoreDB {
             let docRef;
             // 1. If it's a string, we have the direct path (Fastest)
             if (typeof filter === 'string') {
-                docRef = (0, firestore_1.doc)(this._db, this._collectionRef.id, filter);
+                docRef = this._getDocRef(filter);
             }
             else {
                 // 2. If it's an object, we must find the first matching ID (Slower)
@@ -155,23 +154,23 @@ class FirestoreDB {
                 if (!match) {
                     if (options === null || options === void 0 ? void 0 : options.upsert) {
                         // If upsert is true, we create a new doc with a random ID or from filter
-                        const newDocRef = (0, firestore_1.doc)(this._collectionRef);
-                        const initialData = Object.assign(Object.assign(Object.assign({}, this._flattenFilter), updateObject), { updatedAt: (0, firestore_1.serverTimestamp)(), createdAt: (0, firestore_1.serverTimestamp)() });
-                        yield (0, firestore_1.setDoc)(newDocRef, initialData);
+                        const newDocRef = this._sdk.doc(this._collectionRef);
+                        const initialData = Object.assign(Object.assign(Object.assign({}, this._flattenFilter), updateObject), { updatedAt: this._sdk.serverTimestamp(), createdAt: this._sdk.serverTimestamp() });
+                        yield this._sdk.setDoc(newDocRef, initialData);
                         return Object.assign({ _id: newDocRef.id }, initialData);
                     }
                     return null;
                 }
-                docRef = (0, firestore_1.doc)(this._db, this._collectionRef.id, match._id);
+                docRef = this._getDocRef(match._id);
             }
             // 3. Perform the update
             // Using { merge: true } acts as an 'upsert' for the specific document reference
-            yield (0, firestore_1.setDoc)(docRef, Object.assign(Object.assign({}, updateObject), { updatedAt: (0, firestore_1.serverTimestamp)() }), { merge: true });
+            yield this._sdk.setDoc(docRef, Object.assign(Object.assign({}, updateObject), { updatedAt: this._sdk.serverTimestamp() }), { merge: true });
             // 2. TRIGGER INVALIDATION: Any cached 'find' results for this 
             // collection are now potentially stale.
             this._invalidateCache();
             // We need to retrive the saved object and return that 
-            const freshSnap = yield (0, firestore_1.getDoc)(docRef);
+            const freshSnap = yield this._sdk.getDoc(docRef);
             const freshData = Object.assign({ _id: freshSnap.id }, freshSnap.data() || {});
             return (0, utils_1.hydrateDates)(freshData);
         });
@@ -185,13 +184,13 @@ class FirestoreDB {
             const results = [];
             // Math-based Chunking Loop (Jumps by 500)
             for (let i = 0; i < updates.length; i += CHUNK_SIZE) {
-                const batch = (0, firestore_1.writeBatch)(this._db);
+                const batch = this._sdk.writeBatch(this._db);
                 const chunk = updates.slice(i, i + CHUNK_SIZE);
                 chunk.forEach(item => {
                     const { docId, entity } = item;
-                    const docRef = (0, firestore_1.doc)(this._db, this._collectionRef.id, docId);
+                    const docRef = this._getDocRef(docId);
                     // Inject updatedAt into the update payload
-                    const updateData = Object.assign(Object.assign({}, entity), { updatedAt: (0, firestore_1.serverTimestamp)() });
+                    const updateData = Object.assign(Object.assign({}, entity), { updatedAt: this._sdk.serverTimestamp() });
                     if (options.upsert) {
                         // UPSERT: Create if missing, merge if exists
                         // We ensure _id is included in the document for consistency
@@ -199,7 +198,7 @@ class FirestoreDB {
                         // Firestore's 'set' with merge doesn't know if it's new, so we 
                         // usually set createdAt only on first creation via a different method
                         if (!this.exists({ _id: docRef.id }))
-                            updateData['createdAt'] = (0, firestore_1.serverTimestamp)();
+                            updateData['createdAt'] = this._sdk.serverTimestamp();
                         batch.set(docRef, updateData, { merge: true });
                         // Set the Id of the object so the consumer knows which id was affected
                         results.push({ _id: docRef.id });
@@ -229,23 +228,23 @@ class FirestoreDB {
          * FIRESTOREDB: deleteOne('id_123')
          */
         this.deleteOne = (docId) => __awaiter(this, void 0, void 0, function* () {
-            const docRef = (0, firestore_1.doc)(this._db, this._collectionRef.id, docId);
+            const docRef = this._getDocRef(docId);
             // Check if it exists first if you want an accurate deletedCount
-            const snap = yield (0, firestore_1.getDoc)(docRef);
+            const snap = yield this._sdk.getDoc(docRef);
             if (!snap.exists()) {
                 return { acknowledged: true, deletedCount: 0 };
             }
             if (this._isSoftDeleteEnabled) {
                 // SOFT DELETE: Update with flag and timestamp
-                yield (0, firestore_1.updateDoc)(docRef, {
+                yield this._sdk.updateDoc(docRef, {
                     isDeleted: true,
-                    deletedAt: (0, firestore_1.serverTimestamp)(),
-                    updatedAt: (0, firestore_1.serverTimestamp)()
+                    deletedAt: this._sdk.serverTimestamp(),
+                    updatedAt: this._sdk.serverTimestamp()
                 });
             }
             else {
                 // HARD DELETE: Remove from disk
-                yield (0, firestore_1.deleteDoc)(docRef);
+                yield this._sdk.deleteDoc(docRef);
             }
             // 2. TRIGGER INVALIDATION: Any cached 'find' results for this 
             // collection are now potentially stale.
@@ -261,15 +260,15 @@ class FirestoreDB {
             const batchPromises = [];
             let totalDeleted = 0;
             for (let i = 0; i < docIds.length; i += CHUNK_SIZE) {
-                const batch = (0, firestore_1.writeBatch)(this._db);
+                const batch = this._sdk.writeBatch(this._db);
                 const chunk = docIds.slice(i, i + CHUNK_SIZE);
                 chunk.forEach(id => {
-                    let docRef = (0, firestore_1.doc)(this._db, this._collectionRef.id, id);
+                    let docRef = this._getDocRef(id);
                     if (this._isSoftDeleteEnabled) {
                         batch.update(docRef, {
                             isDeleted: true,
-                            deletedAt: (0, firestore_1.serverTimestamp)(),
-                            updatedAt: (0, firestore_1.serverTimestamp)()
+                            deletedAt: this._sdk.serverTimestamp(),
+                            updatedAt: this._sdk.serverTimestamp()
                         });
                     }
                     else {
@@ -287,11 +286,13 @@ class FirestoreDB {
         });
         /**
          * Efficiently checks if a document exists without downloading it. (only metadata).
+         *
+         * @optimized
          * Optimized to only check for the presence of a document
          */
         this.exists = (filter) => __awaiter(this, void 0, void 0, function* () {
-            const q = (0, firestore_1.query)(this._collectionRef, ...this._buildConstraints(filter), (0, firestore_1.limit)(1));
-            const snapshot = yield (0, firestore_1.getDocs)(q);
+            const q = this._sdk.query(this._collectionRef, ...this._buildConstraints(filter), this._sdk.limit(1));
+            const snapshot = yield this._sdk.getDocs(q);
             return !snapshot.empty;
         });
         /**
@@ -299,19 +300,19 @@ class FirestoreDB {
          */
         this.aggregate = (...args_1) => __awaiter(this, [...args_1], void 0, function* (filter = {}, aggregations) {
             const constraints = this._buildConstraints(filter);
-            const q = (0, firestore_1.query)(this._collectionRef, ...constraints);
+            const q = this._sdk.query(this._collectionRef, ...constraints);
             // 1. Map the request to Firestore's aggregation functions
             const spec = {};
             Object.entries(aggregations).forEach(([alias, op]) => {
                 if (op.$sum)
-                    spec[alias] = (0, firestore_1.sum)(op.$sum);
+                    spec[alias] = this._sdk.sum(op.$sum);
                 if (op.$avg)
-                    spec[alias] = (0, firestore_1.average)(op.$avg);
+                    spec[alias] = this._sdk.average(op.$avg);
                 if (op.$count)
-                    spec[alias] = (0, firestore_1.count)();
+                    spec[alias] = this._sdk.count();
             });
             // 2. Execute on server (Calculates across millions of docs instantly)
-            const snapshot = yield (0, firestore_1.getAggregateFromServer)(q, spec);
+            const snapshot = yield this._sdk.getAggregateFromServer(q, spec);
             return snapshot.data();
         });
         this._flattenFilter = (obj, prefix = '') => {
@@ -324,7 +325,7 @@ class FirestoreDB {
                     if (firstKey.startsWith("$")) {
                         // get the symbol if not found then default to equality
                         const op = utils_1.$OperatorMap[firstKey] || '==';
-                        constraints.push((0, firestore_1.where)(path, op, value[firstKey]));
+                        constraints.push(this._sdk.where(path, op, value[firstKey]));
                     }
                     else {
                         // It's a nested object, keep flattening
@@ -333,24 +334,31 @@ class FirestoreDB {
                 }
                 else {
                     // It's a primitive value, use standard equality
-                    constraints.push((0, firestore_1.where)(path, '==', value));
+                    constraints.push(this._sdk.where(path, '==', value));
                 }
             });
             return constraints;
         };
-        this._db = db;
-        this._collectionName = collectionName;
+        /**
+         * This will try to get the document Reference of a given id, however if id missing return a auto generated Document Referrence
+         * @param docId optional
+         * @returns Firebase DocumentReferrence
+         */
+        this._getDocRef = (docId) => {
+            return docId
+                ? this._sdk.doc(this._db, this._collectionRef.id, docId) //Custom ID
+                : this._sdk.doc(this._collectionRef); //Auto ID
+        };
         // Ensure Store is initialized or passed in
-        console.log("Is valid Firestore instance?", this._db instanceof firestore_1.Firestore);
         try {
             if (!this._db) {
                 throw new Error(`Firestore db not present ${this._db} @collection: ${this._collectionName}`);
             }
-            this._collectionRef = (0, firestore_1.collection)(this._db, this._collectionName);
-            this._isSoftDeleteEnabled = (_a = options.softDelete) !== null && _a !== void 0 ? _a : false;
+            this._collectionRef = this._sdk.collection(this._db, this._collectionName);
+            this._isSoftDeleteEnabled = (_a = this._options.softDelete) !== null && _a !== void 0 ? _a : false;
         }
         catch (error) {
-            throw new Error(`error on init @collection: ${this._collectionName}` + error.message);
+            throw new Error(`error on init @collection: ${this._collectionName} - ` + error.message);
         }
     }
     /**
@@ -359,11 +367,11 @@ class FirestoreDB {
  */
     restore(id) {
         return __awaiter(this, void 0, void 0, function* () {
-            const docRef = (0, firestore_1.doc)(this._db, this._collectionName, id);
-            yield (0, firestore_1.updateDoc)(docRef, {
+            const docRef = this._getDocRef(id);
+            yield this._sdk.updateDoc(docRef, {
                 isDeleted: false,
                 deletedAt: null, // Clear the timestamp
-                updatedAt: (0, firestore_1.serverTimestamp)()
+                updatedAt: this._sdk.serverTimestamp()
             });
             // 2. TRIGGER INVALIDATION: Any cached 'find' results for this 
             // collection are now potentially stale.
@@ -372,15 +380,18 @@ class FirestoreDB {
         });
     }
     /**
- * MONGODB: db.collection.watch(filter)
- * A real-time listener that bypasses the manual cache and
- * pushes updates as they happen in the database.
- */
+     * @title
+     * FIRESTOREDB: collection.watch(filter)
+     *
+     * @detail
+     * A real-time listener that bypasses the manual cache and
+     * pushes updates as they happen in the database.
+     */
     watch(filter = {}, callback, onError) {
         const constraints = this._buildConstraints(filter);
-        const q = (0, firestore_1.query)(this._collectionRef, ...constraints);
+        const q = this._sdk.query(this._collectionRef, ...constraints);
         // Returns the unsubscribe function
-        return (0, firestore_1.onSnapshot)(q, (snapshot) => {
+        return this._sdk.onSnapshot(q, (snapshot) => {
             const docs = snapshot.docs.map(d => {
                 const raw = Object.assign({ _id: d.id }, d.data());
                 return (0, utils_1.hydrateDates)(raw);
@@ -398,7 +409,7 @@ class FirestoreDB {
         return [...this._flattenFilter(filter)];
     }
     /**
-     * In FirestoreDB class:
+     * FirestoreDB class:
      * Purges all cached queries for THIS collection to ensure data freshness.
      */
     _invalidateCache() {

package/dist/cjs/FirestoreQuery.d.ts

@@ -1,10 +1,12 @@
-import { QueryConstraint } from "firebase/firestore";
-import { WithSystemFields } from "./types";
+import type { QueryConstraint } from "firebase/firestore";
+import { FirestoreSDK, WithSystemFields } from "./types";
 import { LRUCache } from './utils';
+import { FirestoreCursor } from "./utils/FirestoreCursor";
 export type SortDescriptor = "asc" | "desc";
 export interface PaginationMetadata {
     totalRecords: number;
     totalPages: number;
+    currentPage: number;
     hasNext: boolean;
     hasPrevious: boolean;
 }
@@ -13,19 +15,25 @@ export declare class FirestoreQuery<T> {
     private collectionName;
     private collectionRef;
     private filter;
+    private _sdk;
     private buildConstraints;
     private countDocs;
     static _globalCache: LRUCache;
     private _useCache;
     private _ttl;
+    private _pageNumber;
     private _deleteMode;
     private _limit;
     private _sort;
     private _cursorId?;
     private _cursorType;
-    constructor(db: any, collectionName: string, collectionRef: any, filter: Record<string, any>, buildConstraints: (f: any) => QueryConstraint[], countDocs: (f: any) => Promise<number>, isSoftDeleteEnabled: boolean);
+    constructor(db: any, collectionName: string, collectionRef: any, filter: Record<string, any>, _sdk: FirestoreSDK, buildConstraints: (f: any) => QueryConstraint[], countDocs: (f: any) => Promise<number>, isSoftDeleteEnabled: boolean);
     /** Enables result caching for this query */
     cache(ttlMs?: number): this;
+    /**
+     * Optional: Set the current page number for metadata reporting.
+     */
+    page(n: number): this;
     sort(sortObj: Record<keyof T, SortDescriptor>): this;
     limit(n: number): this;
     /** Move to the next page */
@@ -40,7 +48,24 @@ export declare class FirestoreQuery<T> {
     onlyDeleted(): this;
     /** Simple execution (Returns Array) */
     execute(): Promise<WithSystemFields<T>[]>;
-    /** Paginated execution (Returns Data + Metadata) */
+    /**
+     * Paginated execution (Returns Data + Metadata)
+     *
+     * @example
+     * // React State example
+        const [currentPage, setCurrentPage] = useState(1);
+        const [lastId, setLastId] = useState(null);
+
+        const { data, metadata } = await Products.find({ category: 'electronics' })
+            .sort({ price: 'asc' })
+            .limit(10)
+            .page(currentPage)   // Sets the metadata
+            .after(lastId)       // Sets the cursor
+            .cache()             // Speeds up the "Back" button
+            .paginate();
+
+        console.log(`Viewing page ${metadata.currentPage} of ${metadata.totalPages}`);
+     */
     paginate(): Promise<{
         data: WithSystemFields<T>[];
         metadata: PaginationMetadata;
@@ -48,6 +73,18 @@ export declare class FirestoreQuery<T> {
     stream(): ReadableStream<T & {
         _id: string;
     }>;
+    /**
+     * @example
+     * const cursor = await Users.find({ role: 'admin' }).sort({ name: 1 }).cursor();
+     *
+     *
+     * while (await cursor.hasNext()) {
+     *      const doc = await cursor.next();
+     *      console.log("Processing admin:", doc.name);
+     * }
+     * @returns
+     */
+    cursor(): Promise<FirestoreCursor<T>>;
     private _prepareConstraints;
     private _generateCacheKey;
     /**

package/dist/cjs/FirestoreQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FirestoreQuery.d.ts","sourceRoot":"","sources":["../../src/FirestoreQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EAC8E,eAAe,EAEnG,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAG3C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAElC,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,CAAA;AAC3C,MAAM,WAAW,kBAAkB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,cAAc,CAAC,CAAC;IAerB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,SAAS;IAjBrB,OAAc,YAAY,WAAkB;IAC5C,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,IAAI,CAAiB;IAG7B,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAmC;gBAG1C,EAAE,EAAE,GAAG,EACP,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,GAAG,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,gBAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,eAAe,EAAE,EAC/C,SAAS,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,EAC9C,mBAAmB,EAAE,OAAO;IAKhC,4CAA4C;IAC5C,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM;IAMb,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IAK7C,KAAK,CAAC,CAAC,EAAE,MAAM;IAKtB,4BAA4B;IACrB,KAAK,CAAC,EAAE,EAAE,MAAM;IAMvB,gCAAgC;IACzB,MAAM,CAAC,EAAE,EAAE,MAAM;IAMxB;;;OAGG;IACH,WAAW;IAKX,WAAW;IAEX,uCAAuC;IAC1B,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAUtD,oDAAoD;IACvC,QAAQ,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;QAAC,QAAQ,EAAE,kBAAkB,CAAA;KAAE,CAAC;IAsCxF,MAAM,IAAI,cAAc,CAAC,CAAC,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;YAoBtC,mBAAmB;IAsCjC,OAAO,CAAC,iBAAiB;IAczB;;GAED;IACC,OAAO,CAAC,eAAe;CAQ1B"}
+{"version":3,"file":"FirestoreQuery.d.ts","sourceRoot":"","sources":["../../src/FirestoreQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGzD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,CAAA;AAC3C,MAAM,WAAW,kBAAkB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,cAAc,CAAC,CAAC;IAgBrB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,SAAS;IAnBrB,OAAc,YAAY,WAAkB;IAC5C,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,IAAI,CAAiB;IAC7B,OAAO,CAAC,WAAW,CAAa;IAGhC,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAmC;gBAG1C,EAAE,EAAE,GAAG,EACP,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,GAAG,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,YAAY,EAClB,gBAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,eAAe,EAAE,EAC/C,SAAS,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,EAC9C,mBAAmB,EAAE,OAAO;IAKhC,4CAA4C;IAC5C,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM;IAMpB;;OAEG;IACH,IAAI,CAAC,CAAC,EAAE,MAAM;IAKP,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IAK7C,KAAK,CAAC,CAAC,EAAE,MAAM;IAKtB,4BAA4B;IACrB,KAAK,CAAC,EAAE,EAAE,MAAM;IAMvB,gCAAgC;IACzB,MAAM,CAAC,EAAE,EAAE,MAAM;IAMxB;;;OAGG;IACH,WAAW;IAKX,WAAW;IAEX,uCAAuC;IAC1B,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAUtD;;;;;;;;;;;;;;;;;OAiBG;IACU,QAAQ,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;QAAC,QAAQ,EAAE,kBAAkB,CAAA;KAAE,CAAC;IAuCxF,MAAM,IAAI,cAAc,CAAC,CAAC,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAkBpD;;;;;;;;;;OAUG;IACU,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YAapC,mBAAmB;IAsCjC,OAAO,CAAC,iBAAiB;IAezB;;GAED;IACC,OAAO,CAAC,eAAe;CAQ1B"}