@knymbus/firestoredb 1.0.2

package/dist/cjs/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/cjs/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/cjs/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"}

package/dist/cjs/FirestoreQuery.js

@@ -0,0 +1,200 @@
+"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.FirestoreQuery = void 0;
+const firestore_1 = require("firebase/firestore");
+const utils_1 = require("./utils");
+const Hasher_1 = require("./utils/Hasher");
+const utils_2 = require("./utils");
+class FirestoreQuery {
+    constructor(db, collectionName, collectionRef, filter, buildConstraints, countDocs, isSoftDeleteEnabled) {
+        this.db = db;
+        this.collectionName = collectionName;
+        this.collectionRef = collectionRef;
+        this.filter = filter;
+        this.buildConstraints = buildConstraints;
+        this.countDocs = countDocs;
+        this._useCache = false;
+        this._ttl = 60000; // Default 1 minute
+        this._deleteMode = 'hide';
+        this._limit = 100;
+        this._sort = {};
+        this._cursorType = null;
+        this._deleteMode = isSoftDeleteEnabled ? 'hide' : 'include';
+    }
+    /** Enables result caching for this query */
+    cache(ttlMs) {
+        this._useCache = true;
+        if (ttlMs)
+            this._ttl = ttlMs;
+        return this;
+    }
+    sort(sortObj) {
+        this._sort = sortObj;
+        return this;
+    }
+    limit(n) {
+        this._limit = n;
+        return this;
+    }
+    /** Move to the next page */
+    after(id) {
+        this._cursorId = id;
+        this._cursorType = 'after';
+        return this;
+    }
+    /** Move to the previous page */
+    before(id) {
+        this._cursorId = id;
+        this._cursorType = 'before';
+        return this;
+    }
+    /**
+     * FirestoreDB: db.collection.find({}).withDeleted().execute()
+     * Allows viewing soft-deleted documents for this specific query.
+     */
+    withDeleted() {
+        this._deleteMode = 'include';
+        return this;
+    }
+    onlyDeleted() { this._deleteMode = 'only'; return this; }
+    /** Simple execution (Returns Array) */
+    execute() {
+        return __awaiter(this, void 0, void 0, function* () {
+            let finalConstraints = yield this._prepareConstraints();
+            const q = (0, firestore_1.query)(this.collectionRef, ...finalConstraints);
+            const snapshot = yield (0, firestore_1.getDocs)(q);
+            return snapshot.docs.map(d => {
+                const rawData = Object.assign({ _id: d.id }, (d.data() || {}));
+                return (0, utils_1.hydrateDates)(rawData);
+            });
+        });
+    }
+    /** Paginated execution (Returns Data + Metadata) */
+    paginate() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // set the global key for this query
+            const key = this._generateCacheKey();
+            // 1. Check Cache
+            if (this._useCache) {
+                const cached = FirestoreQuery._globalCache.get(key);
+                if (cached && (Date.now() - cached.timestamp < this._ttl)) {
+                    return cached.data;
+                }
+            }
+            const data = yield this.execute();
+            const totalRecords = yield this.countDocs(this.filter);
+            const totalPages = this._limit > 0 ? Math.ceil(totalRecords / this._limit) : 1;
+            const result = {
+                data,
+                metadata: {
+                    totalRecords,
+                    totalPages,
+                    hasNext: data.length === this._limit,
+                    hasPrevious: !!this._cursorId
+                }
+            };
+            // 2. Fetch & Store
+            if (this._useCache) {
+                FirestoreQuery._globalCache.set(key, {
+                    data: result,
+                    timestamp: Date.now()
+                });
+            }
+            return result;
+        });
+    }
+    stream() {
+        const fetchDocs = () => __awaiter(this, void 0, void 0, function* () { return this.execute(); });
+        return new ReadableStream({
+            start(controller) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    try {
+                        const docs = yield fetchDocs();
+                        for (let d of docs) {
+                            controller.enqueue(d); // push docs into pipe
+                        }
+                        controller.close(); // End of stream
+                    }
+                    catch (error) {
+                        controller.error(error);
+                    }
+                });
+            }
+        });
+    }
+    // PRIVATE METHODS
+    _prepareConstraints() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const constraints = [...this.buildConstraints(this.filter)];
+            // If mode is 'include', we simply don't add an isDeleted constraint at all
+            if (this._deleteMode === 'hide') {
+                constraints.push((0, firestore_1.where)("isDeleted", "==", false));
+            }
+            else if (this._deleteMode === 'only') {
+                constraints.push((0, firestore_1.where)("isDeleted", "==", true));
+            }
+            // 1. Apply Sorting (Required for cursors)
+            Object.entries(this._sort).forEach(([field, dir]) => {
+                constraints.push((0, firestore_1.orderBy)(field, dir));
+            });
+            // 2. Handle Cursors (Validation + Logic)
+            if (this._cursorId) {
+                const docRef = (0, firestore_1.doc)(this.db, this.collectionName, this._cursorId);
+                const snap = yield (0, firestore_1.getDoc)(docRef);
+                if (snap.exists()) {
+                    if (this._cursorType === 'after') {
+                        constraints.push((0, firestore_1.startAfter)(snap));
+                        if (this._limit)
+                            constraints.push((0, firestore_1.limit)(this._limit));
+                    }
+                    // If not start then before
+                    else {
+                        constraints.push((0, firestore_1.endBefore)(snap));
+                        // limitToLast is required to get the 10 items *closest* to the cursor
+                        if (this._limit)
+                            constraints.push((0, firestore_1.limitToLast)(this._limit));
+                    }
+                }
+            }
+            else if (this._limit) {
+                constraints.push((0, firestore_1.limit)(this._limit));
+            }
+            return constraints;
+        });
+    }
+    _generateCacheKey() {
+        const params = {
+            filter: this._sortObjectKeys(this.filter), // Sort keys for consistency
+            sort: this._sort,
+            limit: this._limit,
+            cursorId: this._cursorId,
+            cursorType: this._cursorType,
+            includeDeleted: this._deleteMode
+        };
+        // Use the static Hasher class
+        return Hasher_1.Hasher.generateCacheKey(this.collectionName, params);
+    }
+    /**
+ * Helper to ensure {a:1, b:2} and {b:2, a:1} result in the same JSON string
+ */
+    _sortObjectKeys(obj) {
+        if (obj === null || typeof obj !== 'object' || Array.isArray(obj))
+            return obj;
+        return Object.keys(obj).sort().reduce((acc, key) => {
+            acc[key] = this._sortObjectKeys(obj[key]);
+            return acc;
+        }, {});
+    }
+}
+exports.FirestoreQuery = FirestoreQuery;
+// CACHE VARS
+FirestoreQuery._globalCache = new utils_2.LRUCache(); // Shared across instances