@knymbus/firestoredb 1.0.2

package/dist/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

package/dist/ParallelPipe.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PARALLEL TRANSFORM STREAM
+ * @example
+ * // 1. Stream data from Firestore
+const source = Products.find({ status: 'pending' }).stream();
+
+// 2. Process 50 items in parallel with 3 retries
+const processor = parallelPipe(50, 3, async (doc) => {
+    const apiData = await transformNetworkAction(doc); // Your slow O(n) task
+    return { ...doc, ...apiData, status: 'processed' };
+});
+
+// 3. Write back to Firestore
+const saver = new WritableStream({
+    async write(doc) { await Products.updateOne(doc._id, doc); }
+});
+
+// 4. Pipe through
+await source.pipeThrough(processor).pipeTo(saver);
+ */
+export declare const ParallelPipe: <TIn, TOut>(concurrency: number, retryCount: number, transformFn: (item: TIn) => Promise<TOut>) => TransformStream<TIn, TOut>;
+//# sourceMappingURL=ParallelPipe.d.ts.map

package/dist/ParallelPipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParallelPipe.d.ts","sourceRoot":"","sources":["../src/ParallelPipe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,EAAE,IAAI,EAClC,aAAa,MAAM,EACnB,YAAY,MAAM,EAClB,aAAa,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,+BAsB5C,CAAC"}

package/dist/ParallelPipe.js

@@ -0,0 +1,63 @@
+"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.ParallelPipe = void 0;
+/**
+ * PARALLEL TRANSFORM STREAM
+ * @example
+ * // 1. Stream data from Firestore
+const source = Products.find({ status: 'pending' }).stream();
+
+// 2. Process 50 items in parallel with 3 retries
+const processor = parallelPipe(50, 3, async (doc) => {
+    const apiData = await transformNetworkAction(doc); // Your slow O(n) task
+    return { ...doc, ...apiData, status: 'processed' };
+});
+
+// 3. Write back to Firestore
+const saver = new WritableStream({
+    async write(doc) { await Products.updateOne(doc._id, doc); }
+});
+
+// 4. Pipe through
+await source.pipeThrough(processor).pipeTo(saver);
+ */
+const ParallelPipe = (concurrency, retryCount, transformFn) => {
+    const inFlight = new Set();
+    const executeWithRetry = (item_1, ...args_1) => __awaiter(void 0, [item_1, ...args_1], void 0, function* (item, attempt = 0) {
+        try {
+            return yield transformFn(item);
+        }
+        catch (err) {
+            if (attempt < retryCount)
+                return yield executeWithRetry(item, attempt + 1);
+            throw err;
+        }
+    });
+    return new TransformStream({
+        transform(item, controller) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const p = (() => __awaiter(this, void 0, void 0, function* () {
+                    const result = yield executeWithRetry(item);
+                    controller.enqueue(result);
+                }))();
+                inFlight.add(p);
+                p.finally(() => inFlight.delete(p));
+                if (inFlight.size >= concurrency)
+                    yield Promise.race(inFlight);
+            });
+        },
+        flush() {
+            return __awaiter(this, void 0, void 0, function* () { yield Promise.all(inFlight); });
+        }
+    });
+};
+exports.ParallelPipe = ParallelPipe;

package/dist/cjs/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/cjs/FirestoreDB.d.ts.map

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