@knymbus/firestoredb 1.0.2

package/dist/FirestoreDB.d.ts

@@ -0,0 +1,114 @@
+import { Firestore } from "firebase/firestore";
+import { FirestoreQuery } from './FirestoreQuery';
+import { DocumentInput, QueryFilter, UpdateDocument, WithSystemFields } from './types';
+export interface DBOptions {
+    softDelete?: boolean;
+}
+export declare class FirestoreDB<T> {
+    private _db;
+    private _collectionName;
+    private _collectionRef;
+    private _isSoftDeleteEnabled;
+    /**
+     * Initialize with Firebase DB and targeted collection Name
+     * @param db: Firebase
+     * @param collection string
+     */
+    constructor(db: Firestore, collectionName: string, options?: DBOptions);
+    /**
+     * FIRESTOREDB: findOne({ age: '13' }); or findOne('id_123');
+     */
+    findOne: (filter: string | Record<string, any>) => Promise<WithSystemFields<T> | null>;
+    /**
+     * This will count the number of documents found based on the given filter
+     * @param filter Object with the filter key/value pair
+     * @returns number
+     */
+    countDocuments: (filter?: QueryFilter<T>) => Promise<number>;
+    findOneAndUpdate: (filter: string | QueryFilter<T>, updateObject: Partial<T>) => Promise<WithSystemFields<T>>;
+    /**
+     * NEW: find(query)
+     * Basic implementation. For production, you'd expand the 'filter' to handle where clauses.
+     */
+    find: (filter?: QueryFilter<T>) => FirestoreQuery<T>;
+    /**
+     * FIRESTOREDB: insertOne(doc)
+     * Optimized: Uses set with merge or create
+     */
+    insertOne: (entity: Partial<T & {
+        _id?: string;
+    }>) => Promise<WithSystemFields<T>>;
+    /**
+     * FIRESTOREDB: insertMany(docs) - Uses Firestore Batched Writes (Limit 500 per batch)
+     *
+     */
+    insertMany: (entities: DocumentInput<T>[]) => Promise<string[]>;
+    /**
+     * FIRESTOREDB: updateOne(filter, update)
+     * Use "Upsert" logic when true will create a new document default to false
+     */
+    updateOne: (filter: string | Record<string, any>, updateObject: Partial<T>, options?: {
+        upsert?: boolean;
+    }) => Promise<Record<string, any> | null>;
+    /**
+     * FIRESTOREDB: updateMany([ { docId: '1', entity: { status: 'A' } }, ... ])
+     * Optimized: Chunks updates into batches of 500 to handle large datasets.
+     */
+    updateMany: <T_1>(updates: UpdateDocument<T_1>[], options?: {
+        upsert?: boolean;
+    }) => Promise<{
+        _id: string;
+    }[]>;
+    /**
+     * FIRESTOREDB: deleteOne('id_123')
+     */
+    deleteOne: (docId: string) => Promise<{
+        acknowledged: boolean;
+        deletedCount: number;
+    }>;
+    /**
+     * FIRESTOREDB: deleteMany()
+     * Uses Batched Writes for speed.
+     */
+    deleteMany: (docIds: string[]) => Promise<{
+        acknowledged: boolean;
+        deletedCount: number;
+    }>;
+    /**
+ * FIRESTOREDB: db.collection.restore(id)
+ * Reverses a soft delete by flipping the flag and removing deletedAt.
+ */
+    restore(id: string): Promise<{
+        acknowledged: boolean;
+        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;
+    /**
+     * Efficiently checks if a document exists without downloading it. (only metadata).
+     * Optimized to only check for the presence of a document
+     */
+    exists: (filter: Record<string, any>) => Promise<boolean>;
+    /**
+     * FIRESTOREDB STYLE: aggregate({ status: 'sold' }, { total: { $sum: 'price' }, avg: { $avg: 'price' } })
+     */
+    aggregate: (filter: Record<string, any> | undefined, aggregations: {
+        [key: string]: {
+            $sum?: string;
+            $avg?: string;
+            $count?: boolean;
+        };
+    }) => Promise<import("@firebase/firestore").AggregateSpecData<any>>;
+    private _buildConstraints;
+    private _flattenFilter;
+    /**
+     * In FirestoreDB class:
+     * Purges all cached queries for THIS collection to ensure data freshness.
+     */
+    private _invalidateCache;
+}
+//# sourceMappingURL=FirestoreDB.d.ts.map

package/dist/FirestoreDB.d.ts.map

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

package/dist/FirestoreDB.js

@@ -0,0 +1,407 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+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 {
+    /**
+     * Initialize with Firebase DB and targeted collection Name
+     * @param db: Firebase
+     * @param collection string
+     */
+    constructor(db, collectionName, options = {}) {
+        var _a;
+        /**
+         * FIRESTOREDB: findOne({ age: '13' }); or findOne('id_123');
+         */
+        this.findOne = (filter) => __awaiter(this, void 0, void 0, function* () {
+            // 1. Handle case where user passes a direct string ID
+            if (typeof filter === 'string') {
+                // We use the find() builder even for IDs to ensure the 'where("isDeleted", "==", false)' 
+                // constraint is automatically added by the _buildConstraints helper.
+                const results = yield this.find({ _id: filter })
+                    .limit(1)
+                    .execute();
+                return results.length > 0 ? results[0] : null;
+            }
+            // 2. If it's an object filter, use the standard find logic
+            const results = yield this.find(filter)
+                .limit(1)
+                .execute();
+            return results.length > 0 ? results[0] : null;
+        });
+        /**
+         * This will count the number of documents found based on the given filter
+         * @param filter Object with the filter key/value pair
+         * @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));
+            // Update the query with the incoming filter
+            const snapshot = yield (0, firestore_1.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);
+            }
+            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);
+            }
+            return yield (0, firestore_1.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)() });
+            }));
+        });
+        /**
+         * NEW: find(query)
+         * 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
+            this.countDocuments.bind(this), // pass the count helper
+            this._isSoftDeleteEnabled);
+        };
+        /**
+         * FIRESTOREDB: insertOne(doc)
+         * 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
+            // 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)() }));
+            // 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 freshData = Object.assign({ _id: freshSnap.id }, freshSnap.data());
+            return (0, utils_1.hydrateDates)(freshData);
+        });
+        /**
+         * FIRESTOREDB: insertMany(docs) - Uses Firestore Batched Writes (Limit 500 per batch)
+         *
+         */
+        this.insertMany = (entities) => __awaiter(this, void 0, void 0, function* () {
+            const CHUNK_SIZE = 500;
+            const results = [];
+            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 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 
+                     });
+                    // Add operation to the current batch
+                    batch.set(docRef, finalDoc);
+                    // Track the processed doc to return to the user
+                    results.push(finalDoc._id);
+                });
+                // Queue the batch commit
+                batchPromises.push(batch.commit());
+            }
+            // 2. TRIGGER INVALIDATION: Any cached 'find' results for this 
+            // collection are now potentially stale.
+            this._invalidateCache();
+            // 4. Execute all batches in parallel for maximum speed
+            try {
+                yield Promise.all(batchPromises);
+                return results;
+            }
+            catch (error) {
+                console.error("FirestoreDB::insertMany: Error committing batches", error);
+                throw error;
+            }
+        });
+        /**
+         * FIRESTOREDB: updateOne(filter, update)
+         * Use "Upsert" logic when true will create a new document default to false
+         */
+        this.updateOne = (filter_1, updateObject_1, ...args_1) => __awaiter(this, [filter_1, updateObject_1, ...args_1], void 0, function* (filter, updateObject, options = {}) {
+            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);
+            }
+            else {
+                // 2. If it's an object, we must find the first matching ID (Slower)
+                const match = yield this.findOne(filter);
+                // If we do not find any object we need to check if we can create a new object
+                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);
+                        return Object.assign({ _id: newDocRef.id }, initialData);
+                    }
+                    return null;
+                }
+                docRef = (0, firestore_1.doc)(this._db, this._collectionRef.id, 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 });
+            // 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 freshData = Object.assign({ _id: freshSnap.id }, freshSnap.data() || {});
+            return (0, utils_1.hydrateDates)(freshData);
+        });
+        /**
+         * FIRESTOREDB: updateMany([ { docId: '1', entity: { status: 'A' } }, ... ])
+         * Optimized: Chunks updates into batches of 500 to handle large datasets.
+         */
+        this.updateMany = (updates_1, ...args_1) => __awaiter(this, [updates_1, ...args_1], void 0, function* (updates, options = { upsert: false }) {
+            const CHUNK_SIZE = 500;
+            const batchPromises = [];
+            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 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);
+                    // Inject updatedAt into the update payload
+                    const updateData = Object.assign(Object.assign({}, entity), { updatedAt: (0, firestore_1.serverTimestamp)() });
+                    if (options.upsert) {
+                        // UPSERT: Create if missing, merge if exists
+                        // We ensure _id is included in the document for consistency
+                        // For upserts, we also need to ensure createdAt is set if the doc is new
+                        // 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)();
+                        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 });
+                    }
+                    else {
+                        // STRICT UPDATE: Fails if document doesn't exist (Standard Mongo)
+                        batch.update(docRef, updateData);
+                    }
+                });
+                // Queue the batch commit
+                batchPromises.push(batch.commit());
+            }
+            // 2. TRIGGER INVALIDATION: Any cached 'find' results for this 
+            // collection are now potentially stale.
+            this._invalidateCache();
+            // Run all batches in parallel
+            try {
+                yield Promise.all(batchPromises);
+                return results;
+            }
+            catch (error) {
+                console.error("FirestoreDB::updateMany: Error during batched update", error);
+                throw error;
+            }
+        });
+        /**
+         * 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);
+            // Check if it exists first if you want an accurate deletedCount
+            const snap = yield (0, firestore_1.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, {
+                    isDeleted: true,
+                    deletedAt: (0, firestore_1.serverTimestamp)(),
+                    updatedAt: (0, firestore_1.serverTimestamp)()
+                });
+            }
+            else {
+                // HARD DELETE: Remove from disk
+                yield (0, firestore_1.deleteDoc)(docRef);
+            }
+            // 2. TRIGGER INVALIDATION: Any cached 'find' results for this 
+            // collection are now potentially stale.
+            this._invalidateCache();
+            return { acknowledged: true, deletedCount: 1 };
+        });
+        /**
+         * FIRESTOREDB: deleteMany()
+         * Uses Batched Writes for speed.
+         */
+        this.deleteMany = (docIds) => __awaiter(this, void 0, void 0, function* () {
+            const CHUNK_SIZE = 500;
+            const batchPromises = [];
+            let totalDeleted = 0;
+            for (let i = 0; i < docIds.length; i += CHUNK_SIZE) {
+                const batch = (0, firestore_1.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);
+                    if (this._isSoftDeleteEnabled) {
+                        batch.update(docRef, {
+                            isDeleted: true,
+                            deletedAt: (0, firestore_1.serverTimestamp)(),
+                            updatedAt: (0, firestore_1.serverTimestamp)()
+                        });
+                    }
+                    else {
+                        batch.delete(docRef);
+                    }
+                    totalDeleted++;
+                });
+                batchPromises.push(batch.commit());
+            }
+            yield Promise.all(batchPromises);
+            // 2. TRIGGER INVALIDATION: Any cached 'find' results for this 
+            // collection are now potentially stale.
+            this._invalidateCache();
+            return { acknowledged: true, deletedCount: totalDeleted };
+        });
+        /**
+         * Efficiently checks if a document exists without downloading it. (only metadata).
+         * 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);
+            return !snapshot.empty;
+        });
+        /**
+         * FIRESTOREDB STYLE: aggregate({ status: 'sold' }, { total: { $sum: 'price' }, avg: { $avg: 'price' } })
+         */
+        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);
+            // 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);
+                if (op.$avg)
+                    spec[alias] = (0, firestore_1.average)(op.$avg);
+                if (op.$count)
+                    spec[alias] = (0, firestore_1.count)();
+            });
+            // 2. Execute on server (Calculates across millions of docs instantly)
+            const snapshot = yield (0, firestore_1.getAggregateFromServer)(q, spec);
+            return snapshot.data();
+        });
+        this._flattenFilter = (obj, prefix = '') => {
+            let constraints = [];
+            Object.entries(obj).forEach(([key, value]) => {
+                const path = prefix ? `${prefix}.${key}` : key;
+                if (value && typeof value === 'object' && !Array.isArray(value)) {
+                    // Check if this object is a KnymbusDB operator (e.g. { $gt: 20 })
+                    const firstKey = Object.keys(value)[0];
+                    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]));
+                    }
+                    else {
+                        // It's a nested object, keep flattening
+                        constraints = [...constraints, ...this._flattenFilter(value, path)];
+                    }
+                }
+                else {
+                    // It's a primitive value, use standard equality
+                    constraints.push((0, firestore_1.where)(path, '==', value));
+                }
+            });
+            return constraints;
+        };
+        this._db = db;
+        this._collectionName = collectionName;
+        // Ensure Store is initialized or passed in
+        this._collectionRef = (0, firestore_1.collection)(this._db, this._collectionName);
+        this._isSoftDeleteEnabled = (_a = options.softDelete) !== null && _a !== void 0 ? _a : false;
+    }
+    /**
+ * FIRESTOREDB: db.collection.restore(id)
+ * Reverses a soft delete by flipping the flag and removing deletedAt.
+ */
+    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, {
+                isDeleted: false,
+                deletedAt: null, // Clear the timestamp
+                updatedAt: (0, firestore_1.serverTimestamp)()
+            });
+            // 2. TRIGGER INVALIDATION: Any cached 'find' results for this 
+            // collection are now potentially stale.
+            this._invalidateCache();
+            return { acknowledged: true, restoredCount: 1 };
+        });
+    }
+    /**
+ * MONGODB: db.collection.watch(filter)
+ * 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);
+        // Returns the unsubscribe function
+        return (0, firestore_1.onSnapshot)(q, (snapshot) => {
+            const docs = snapshot.docs.map(d => {
+                const raw = Object.assign({ _id: d.id }, d.data());
+                return (0, utils_1.hydrateDates)(raw);
+            });
+            callback(docs);
+        }, (err) => {
+            if (onError)
+                onError(err);
+            else
+                console.error("FirestoreDB::watch:Error: ", err);
+        });
+    }
+    // PRIVATE METHODS
+    _buildConstraints(filter) {
+        return [...this._flattenFilter(filter)];
+    }
+    /**
+     * In FirestoreDB class:
+     * Purges all cached queries for THIS collection to ensure data freshness.
+     */
+    _invalidateCache() {
+        const prefix = `${this._collectionName}_`;
+        // Convert keys to an array before iterating to avoid 
+        // "Concurrent Modification" issues while deleting
+        const keys = Array.from(FirestoreQuery_1.FirestoreQuery._globalCache.keys());
+        keys.forEach(key => {
+            if (key.startsWith(prefix)) {
+                FirestoreQuery_1.FirestoreQuery._globalCache.delete(key);
+            }
+        });
+    }
+}
+exports.FirestoreDB = FirestoreDB;

package/dist/FirestoreQuery.d.ts

@@ -0,0 +1,58 @@
+import { QueryConstraint } from "firebase/firestore";
+import { WithSystemFields } from "./types";
+import { LRUCache } from './utils';
+export type SortDescriptor = "asc" | "desc";
+export interface PaginationMetadata {
+    totalRecords: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+}
+export declare class FirestoreQuery<T> {
+    private db;
+    private collectionName;
+    private collectionRef;
+    private filter;
+    private buildConstraints;
+    private countDocs;
+    static _globalCache: LRUCache;
+    private _useCache;
+    private _ttl;
+    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);
+    /** Enables result caching for this query */
+    cache(ttlMs?: number): this;
+    sort(sortObj: Record<keyof T, SortDescriptor>): this;
+    limit(n: number): this;
+    /** Move to the next page */
+    after(id: string): this;
+    /** Move to the previous page */
+    before(id: string): this;
+    /**
+     * FirestoreDB: db.collection.find({}).withDeleted().execute()
+     * Allows viewing soft-deleted documents for this specific query.
+     */
+    withDeleted(): this;
+    onlyDeleted(): this;
+    /** Simple execution (Returns Array) */
+    execute(): Promise<WithSystemFields<T>[]>;
+    /** Paginated execution (Returns Data + Metadata) */
+    paginate(): Promise<{
+        data: WithSystemFields<T>[];
+        metadata: PaginationMetadata;
+    }>;
+    stream(): ReadableStream<T & {
+        _id: string;
+    }>;
+    private _prepareConstraints;
+    private _generateCacheKey;
+    /**
+ * Helper to ensure {a:1, b:2} and {b:2, a:1} result in the same JSON string
+ */
+    private _sortObjectKeys;
+}
+//# sourceMappingURL=FirestoreQuery.d.ts.map

package/dist/FirestoreQuery.d.ts.map

@@ -0,0 +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"}