nexabase-console 2.0.7 → 2.0.9

package/dist/firestore/Query.js

@@ -5,6 +5,7 @@ const SnapshotManager_1 = require("./SnapshotManager");
 const DocumentReference_1 = require("./DocumentReference");
 const NexaError_1 = require("../errors/NexaError");
 const helpers_1 = require("../utils/helpers");
+const QueryUtils_1 = require("./QueryUtils");
 const query = (queryObject, ...queryConstraints) => {
     const q = {
         type: 'query',
@@ -13,85 +14,137 @@ const query = (queryObject, ...queryConstraints) => {
         constraints: queryObject.type === 'query' ? [...(queryObject.constraints || [])] : []
     };
     q.constraints = [...(q.constraints || []), ...queryConstraints];
+    // Basic client-side validation
+    for (const c of q.constraints) {
+        if (c.type === 'limit' && (!Number.isSafeInteger(c.limitValue) || c.limitValue <= 0)) {
+            throw Object.assign(new Error('Limit must be a positive safe integer.'), { code: 'invalid-argument' });
+        }
+        if (['in', 'not-in', 'array-contains-any'].includes(c.opStr || '') && (!Array.isArray(c.value) || c.value.length === 0)) {
+            throw Object.assign(new Error(`Invalid value for ${c.opStr}: must be a non-empty array.`), { code: 'invalid-argument' });
+        }
+    }
     return q;
 };
 exports.query = query;
-const getCachedDocs = (queryOrCollection) => {
+const getCachedDocs = (queryOrCollection, fromCache = true) => {
     const db = queryOrCollection.db;
     const collectionPath = queryOrCollection.path;
     const constraints = 'constraints' in queryOrCollection ? queryOrCollection.constraints || [] : [];
     const results = [];
-    Object.keys(db._firestoreCache).forEach((p) => {
-        if (p.startsWith(collectionPath + '/')) {
+    // Local evaluation over cache
+    for (const p of Object.keys(db._firestoreCache)) {
+        if ((0, QueryUtils_1.isDirectChildDocument)(collectionPath, p)) {
             const parts = p.split('/');
             const docId = parts[parts.length - 1];
             const docRef = (0, DocumentReference_1.doc)(db, `${collectionPath}/${docId}`);
-            const cachedData = db._firestoreCache[p];
+            const cachedData = (0, QueryUtils_1.cloneNexaData)(db._firestoreCache[p]);
             results.push({
                 id: docId,
                 ref: docRef,
-                metadata: { fromCache: true, hasPendingWrites: db.hasPendingWrites(docRef.path) },
+                metadata: { fromCache, hasPendingWrites: db.hasPendingWrites(docRef.path) },
                 exists: () => true,
                 data: () => cachedData,
                 get: (fieldPath) => (0, helpers_1.getNestedValue)(cachedData, fieldPath, docId)
             });
         }
-    });
+    }
     let filtered = results;
     let limitCount = undefined;
+    const orderBys = [];
+    for (const c of constraints) {
+        if (c.type === 'orderBy')
+            orderBys.push(c);
+    }
+    // Add implicit tie-breaker by document ID
+    orderBys.push({ type: 'orderBy', fieldPath: '__name__', directionStr: 'asc' });
     for (const c of constraints) {
         if (c.type === 'where' && c.fieldPath && c.opStr) {
             filtered = filtered.filter((docItem) => {
                 const val = (0, helpers_1.getNestedValue)(docItem.data(), c.fieldPath, docItem.id);
+                if (val === undefined) {
+                    // Missing fields should not match inequalities by default
+                    if (['!=', 'not-in', '<', '<=', '>', '>='].includes(c.opStr))
+                        return false;
+                }
                 if (c.opStr === '==')
-                    return val === c.value;
+                    return (0, QueryUtils_1.compareNexaValues)(val, c.value) === 0;
                 if (c.opStr === '>')
-                    return val > c.value;
+                    return (0, QueryUtils_1.compareNexaValues)(val, c.value) > 0;
                 if (c.opStr === '<')
-                    return val < c.value;
+                    return (0, QueryUtils_1.compareNexaValues)(val, c.value) < 0;
                 if (c.opStr === '>=')
-                    return val >= c.value;
+                    return (0, QueryUtils_1.compareNexaValues)(val, c.value) >= 0;
                 if (c.opStr === '<=')
-                    return val <= c.value;
+                    return (0, QueryUtils_1.compareNexaValues)(val, c.value) <= 0;
                 if (c.opStr === '!=')
-                    return val !== c.value;
+                    return (0, QueryUtils_1.compareNexaValues)(val, c.value) !== 0;
                 if (c.opStr === 'in')
-                    return Array.isArray(c.value) && c.value.includes(val);
+                    return Array.isArray(c.value) && c.value.some((v) => (0, QueryUtils_1.compareNexaValues)(v, val) === 0);
                 if (c.opStr === 'not-in')
-                    return Array.isArray(c.value) && !c.value.includes(val);
+                    return Array.isArray(c.value) && !c.value.some((v) => (0, QueryUtils_1.compareNexaValues)(v, val) === 0);
                 if (c.opStr === 'array-contains')
-                    return Array.isArray(val) && val.includes(c.value);
+                    return Array.isArray(val) && val.some((v) => (0, QueryUtils_1.compareNexaValues)(v, c.value) === 0);
                 if (c.opStr === 'array-contains-any')
-                    return Array.isArray(val) && Array.isArray(c.value) && c.value.some((v) => val.includes(v));
-                return true;
-            });
-        }
-        else if (c.type === 'orderBy' && c.fieldPath) {
-            filtered = [...filtered].sort((a, b) => {
-                const valA = (0, helpers_1.getNestedValue)(a.data(), c.fieldPath, a.id);
-                const valB = (0, helpers_1.getNestedValue)(b.data(), c.fieldPath, b.id);
-                if (valA < valB)
-                    return c.directionStr === 'desc' ? 1 : -1;
-                if (valA > valB)
-                    return c.directionStr === 'desc' ? -1 : 1;
-                return 0;
+                    return Array.isArray(val) && Array.isArray(c.value) && c.value.some((cVal) => val.some((v) => (0, QueryUtils_1.compareNexaValues)(v, cVal) === 0));
+                throw new Error(`Unsupported operator: ${c.opStr}`);
             });
         }
     }
+    // Documents without orderBy field must be excluded
+    filtered = filtered.filter((docItem) => {
+        for (const ob of orderBys) {
+            if (ob.fieldPath !== '__name__') {
+                const val = (0, helpers_1.getNestedValue)(docItem.data(), ob.fieldPath, docItem.id);
+                if (val === undefined)
+                    return false;
+            }
+        }
+        return true;
+    });
+    filtered = [...filtered].sort((a, b) => {
+        for (const ob of orderBys) {
+            const field = ob.fieldPath === '__name__' ? null : ob.fieldPath;
+            const valA = field ? (0, helpers_1.getNestedValue)(a.data(), field, a.id) : a.id;
+            const valB = field ? (0, helpers_1.getNestedValue)(b.data(), field, b.id) : b.id;
+            const comp = (0, QueryUtils_1.compareNexaValues)(valA, valB);
+            if (comp !== 0) {
+                return ob.directionStr === 'desc' ? -comp : comp;
+            }
+        }
+        return 0;
+    });
     for (const c of constraints) {
         if (['startAt', 'startAfter', 'endAt', 'endBefore'].includes(c.type)) {
             const isSnapshot = c.docSnapshot && typeof c.docSnapshot === 'object' && 'id' in c.docSnapshot;
-            const cursorIndex = filtered.findIndex((d) => (isSnapshot ? d.id === c.docSnapshot.id : d.id === c.docSnapshot));
-            if (cursorIndex !== -1) {
-                if (c.type === 'startAt')
-                    filtered = filtered.slice(cursorIndex);
-                if (c.type === 'startAfter')
-                    filtered = filtered.slice(cursorIndex + 1);
-                if (c.type === 'endAt')
-                    filtered = filtered.slice(0, cursorIndex + 1);
-                if (c.type === 'endBefore')
-                    filtered = filtered.slice(0, cursorIndex);
-            }
+            const cursorVals = isSnapshot
+                ? orderBys.map(ob => {
+                    if (ob.fieldPath === '__name__')
+                        return c.docSnapshot.id;
+                    return typeof c.docSnapshot.get === 'function'
+                        ? c.docSnapshot.get(ob.fieldPath)
+                        : (0, helpers_1.getNestedValue)(c.docSnapshot.data ? c.docSnapshot.data() : c.docSnapshot, ob.fieldPath, c.docSnapshot.id);
+                })
+                : (Array.isArray(c.cursorValues) ? c.cursorValues : [c.cursorValues]);
+            filtered = filtered.filter(d => {
+                for (let i = 0; i < Math.min(orderBys.length, cursorVals.length); i++) {
+                    const field = orderBys[i].fieldPath === '__name__' ? null : orderBys[i].fieldPath;
+                    const dVal = field ? (0, helpers_1.getNestedValue)(d.data(), field, d.id) : d.id;
+                    const cVal = cursorVals[i];
+                    const comp = (0, QueryUtils_1.compareNexaValues)(dVal, cVal);
+                    if (comp !== 0) {
+                        const dir = orderBys[i].directionStr === 'desc' ? -1 : 1;
+                        const adjustedComp = comp * dir;
+                        if (c.type === 'startAt' || c.type === 'startAfter')
+                            return adjustedComp > 0;
+                        if (c.type === 'endAt' || c.type === 'endBefore')
+                            return adjustedComp < 0;
+                    }
+                }
+                // If all evaluated fields are equal
+                if (c.type === 'startAt' || c.type === 'endAt')
+                    return true;
+                return false;
+            });
         }
         else if (c.type === 'limit' && typeof c.limitValue === 'number') {
             limitCount = c.limitValue;
@@ -100,7 +153,7 @@ const getCachedDocs = (queryOrCollection) => {
     if (limitCount !== undefined) {
         filtered = filtered.slice(0, limitCount);
     }
-    return SnapshotManager_1.SnapshotManager.createQuerySnapshot(filtered, true, db.hasPendingWrites(collectionPath));
+    return SnapshotManager_1.SnapshotManager.createQuerySnapshot(filtered, fromCache, filtered.some(d => d.metadata.hasPendingWrites) || db.hasPendingWrites(collectionPath));
 };
 exports.getCachedDocs = getCachedDocs;
 const getDocs = async (queryOrCollection) => {
@@ -109,68 +162,72 @@ const getDocs = async (queryOrCollection) => {
         await db._initPromise;
     const collectionPath = queryOrCollection.path;
     const constraints = 'constraints' in queryOrCollection ? queryOrCollection.constraints || [] : [];
+    const serializedConstraints = constraints.map(QueryUtils_1.serializeConstraint);
     if (db.cacheStrategy === 'cache-first') {
-        const cached = (0, exports.getCachedDocs)(queryOrCollection);
-        if (cached && !cached.empty) {
+        const cached = (0, exports.getCachedDocs)(queryOrCollection, true);
+        if (cached && (db._queryCacheMetadata[collectionPath] || !cached.empty)) {
+            // background refresh
             db.client
-                .post(`/api/firestore/${db.projectId}/query`, { collectionPath, constraints })
+                .post(`/api/firestore/${db.projectId}/query`, { collectionPath, constraints: serializedConstraints })
                 .then(async (res) => {
-                const docs = res.data.documents || [];
-                const serverIds = new Set(docs.map((d) => d.id));
-                for (const d of docs) {
-                    await db._setCache(`${collectionPath}/${d.id}`, d.fields);
-                }
-                if (constraints.length === 0) {
-                    for (const cachePath of Object.keys(db._firestoreCache)) {
-                        if (cachePath.startsWith(collectionPath + '/')) {
-                            const docId = cachePath.split('/').pop();
-                            if (docId && !serverIds.has(docId)) {
-                                await db._deleteCache(cachePath);
-                            }
-                        }
-                    }
-                }
+                const docs = res.data?.documents;
+                if (!Array.isArray(docs))
+                    return;
+                const complete = res.data?.complete === true;
+                await db._commitAtomicQueryResults({
+                    queryKey: collectionPath,
+                    collectionPath,
+                    serverDocs: docs,
+                    isComplete: complete,
+                    constraints: serializedConstraints
+                });
+                db._queryCacheMetadata[collectionPath] = true;
                 db._notifySnapshotCallbacks(collectionPath, 'bulk_update', null);
             })
-                .catch(() => { });
+                .catch((err) => {
+                console.error('[NexaBase] Background query refresh failed:', err);
+            });
             return cached;
         }
     }
     try {
-        const res = await db.client.post(`/api/firestore/${db.projectId}/query`, { collectionPath, constraints });
-        const docs = res.data.documents || [];
-        const serverIds = new Set(docs.map((d) => d.id));
-        for (const d of docs) {
-            await db._setCache(`${collectionPath}/${d.id}`, d.fields);
+        const res = await db.client.post(`/api/firestore/${db.projectId}/query`, { collectionPath, constraints: serializedConstraints });
+        const docs = res.data?.documents;
+        if (!Array.isArray(docs)) {
+            throw Object.assign(new Error('Invalid server response: documents must be an array'), { code: 'internal' });
         }
-        if (constraints.length === 0) {
-            for (const cachePath of Object.keys(db._firestoreCache)) {
-                if (cachePath.startsWith(collectionPath + '/')) {
-                    const docId = cachePath.split('/').pop();
-                    if (docId && !serverIds.has(docId)) {
-                        await db._deleteCache(cachePath);
-                    }
-                }
+        const seenIds = new Set();
+        const validDocs = [];
+        for (const d of docs) {
+            if (d && typeof d.id === 'string' && d.fields && typeof d.fields === 'object' && !seenIds.has(d.id)) {
+                seenIds.add(d.id);
+                validDocs.push(d);
             }
         }
-        const docsArray = docs.map((d) => {
-            const docRef = (0, DocumentReference_1.doc)(db, `${collectionPath}/${d.id}`);
-            return {
-                id: d.id,
-                ref: docRef,
-                metadata: { fromCache: false, hasPendingWrites: db.hasPendingWrites(docRef.path) },
-                exists: () => true,
-                data: () => d.fields,
-                get: (fieldPath) => (0, helpers_1.getNestedValue)(d.fields, fieldPath, d.id)
-            };
+        const complete = res.data?.complete === true;
+        // Apply results while preserving pending mutations safely
+        await db._commitAtomicQueryResults({
+            queryKey: collectionPath,
+            collectionPath,
+            serverDocs: validDocs,
+            isComplete: complete,
+            constraints: serializedConstraints
         });
-        return SnapshotManager_1.SnapshotManager.createQuerySnapshot(docsArray, false, db.hasPendingWrites(collectionPath));
+        db._queryCacheMetadata[collectionPath] = true;
+        // After persistence, read the newly reconciled local state
+        return (0, exports.getCachedDocs)(queryOrCollection, false);
     }
     catch (err) {
-        if (err && err.response && err.response.status < 500) {
-            throw (0, NexaError_1.toNexaError)(err);
+        const status = err?.response?.status;
+        const code = err?.code || 'internal';
+        const isRetryable = status
+            ? [408, 425, 429, 500, 502, 503, 504].includes(status)
+            : ['network-error', 'timeout', 'unavailable', 'aborted', 'resource-exhausted'].includes(code);
+        if (isRetryable) {
+            // Return cache if it's just a network disconnect/retryable error
+            return (0, exports.getCachedDocs)(queryOrCollection, true);
         }
-        return (0, exports.getCachedDocs)(queryOrCollection);
+        throw (0, NexaError_1.toNexaError)(err);
     }
 };
 exports.getDocs = getDocs;
@@ -187,51 +244,45 @@ const average = (field) => {
 };
 exports.average = average;
 const getAggregateFromServer = async (queryOrCollection, aggregateSpec) => {
-    const querySnapshot = await (0, exports.getDocs)(queryOrCollection);
-    const docs = querySnapshot.docs;
-    const resultData = {};
+    const db = queryOrCollection.db;
+    if (db._initPromise)
+        await db._initPromise;
+    const collectionPath = queryOrCollection.path;
+    const constraints = 'constraints' in queryOrCollection ? queryOrCollection.constraints || [] : [];
+    const serializedSpec = {};
     for (const [key, spec] of Object.entries(aggregateSpec)) {
-        if (spec.type === 'count') {
-            resultData[key] = docs.length;
+        if (key === '__proto__' || key === 'constructor')
+            continue;
+        let fp = spec.fieldPath;
+        if (fp && typeof fp === 'object' && 'getPathString' in fp && typeof fp.getPathString === 'function') {
+            fp = fp.getPathString();
         }
-        else if (spec.type === 'sum') {
-            const field = spec.fieldPath || '';
-            let sumVal = 0;
-            for (const d of docs) {
-                const val = (0, helpers_1.getNestedValue)(d.data(), field, d.id);
-                if (typeof val === 'number' && !isNaN(val)) {
-                    sumVal += val;
-                }
-            }
-            resultData[key] = sumVal;
-        }
-        else if (spec.type === 'average') {
-            const field = spec.fieldPath || '';
-            let sumVal = 0;
-            let countVal = 0;
-            for (const d of docs) {
-                const val = (0, helpers_1.getNestedValue)(d.data(), field, d.id);
-                if (typeof val === 'number' && !isNaN(val)) {
-                    sumVal += val;
-                    countVal++;
-                }
-            }
-            resultData[key] = countVal > 0 ? sumVal / countVal : null;
+        serializedSpec[key] = {
+            type: spec.type,
+            fieldPath: typeof fp === 'string' ? fp : undefined
+        };
+    }
+    try {
+        const res = await db.client.post(`/api/firestore/${db.projectId}/aggregate`, {
+            collectionPath,
+            constraints: constraints.map(QueryUtils_1.serializeConstraint),
+            aggregateSpec: serializedSpec
+        });
+        if (!res.data || typeof res.data.result !== 'object' || res.data.result === null) {
+            throw Object.assign(new Error('Invalid aggregate server response'), { code: 'internal' });
         }
+        return {
+            type: 'AggregateQuerySnapshot',
+            query: queryOrCollection,
+            data: () => (0, QueryUtils_1.cloneNexaData)(res.data.result)
+        };
+    }
+    catch (err) {
+        throw (0, NexaError_1.toNexaError)(err);
     }
-    return {
-        type: 'AggregateQuerySnapshot',
-        query: queryOrCollection,
-        data: () => resultData
-    };
 };
 exports.getAggregateFromServer = getAggregateFromServer;
 const getCountFromServer = async (queryOrCollection) => {
-    const querySnapshot = await (0, exports.getDocs)(queryOrCollection);
-    return {
-        type: 'AggregateQuerySnapshot',
-        query: queryOrCollection,
-        data: () => ({ count: querySnapshot.docs.length })
-    };
+    return (0, exports.getAggregateFromServer)(queryOrCollection, { count: (0, exports.count)() });
 };
 exports.getCountFromServer = getCountFromServer;

package/dist/firestore/QueryUtils.d.ts

@@ -0,0 +1,5 @@
+export declare function isDirectChildDocument(collectionPath: string, documentPath: string): boolean;
+export declare function reviveNexaData(data: any): any;
+export declare function cloneNexaData(data: any): any;
+export declare function compareNexaValues(a: any, b: any): number;
+export declare function serializeConstraint(c: any): any;

package/dist/firestore/QueryUtils.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDirectChildDocument = isDirectChildDocument;
+exports.reviveNexaData = reviveNexaData;
+exports.cloneNexaData = cloneNexaData;
+exports.compareNexaValues = compareNexaValues;
+exports.serializeConstraint = serializeConstraint;
+const Timestamp_1 = require("./Timestamp");
+function isDirectChildDocument(collectionPath, documentPath) {
+    if (!documentPath.startsWith(`${collectionPath}/`))
+        return false;
+    return documentPath.split('/').length === collectionPath.split('/').length + 1;
+}
+function reviveNexaData(data) {
+    if (data === null || data === undefined)
+        return data;
+    if (data instanceof Timestamp_1.Timestamp)
+        return new Timestamp_1.Timestamp(data.seconds, data.nanoseconds);
+    if (Array.isArray(data))
+        return data.map(reviveNexaData);
+    if (typeof data === 'object') {
+        if (typeof data.isEqual === 'function' && typeof data.toMillis === 'function') {
+            return data;
+        }
+        // Revive timestamp
+        if (typeof data.seconds === 'number' && typeof data.nanoseconds === 'number' && Object.keys(data).length <= 2) {
+            return new Timestamp_1.Timestamp(data.seconds, data.nanoseconds);
+        }
+        const cloned = {};
+        for (const k in data) {
+            if (Object.prototype.hasOwnProperty.call(data, k)) {
+                cloned[k] = reviveNexaData(data[k]);
+            }
+        }
+        return cloned;
+    }
+    return data;
+}
+function cloneNexaData(data) {
+    if (data === null || data === undefined)
+        return data;
+    if (data instanceof Timestamp_1.Timestamp)
+        return new Timestamp_1.Timestamp(data.seconds, data.nanoseconds);
+    if (Array.isArray(data))
+        return data.map(cloneNexaData);
+    if (typeof data === 'object') {
+        if (typeof data.isEqual === 'function' && typeof data.toMillis === 'function') {
+            return data; // Treat as immutable if it's our own object like Timestamp/GeoPoint
+        }
+        const cloned = {};
+        for (const k in data) {
+            if (Object.prototype.hasOwnProperty.call(data, k)) {
+                cloned[k] = cloneNexaData(data[k]);
+            }
+        }
+        return cloned;
+    }
+    return data;
+}
+function compareNexaValues(a, b) {
+    if (a === b)
+        return 0;
+    if (a === null && b !== null)
+        return -1;
+    if (a !== null && b === null)
+        return 1;
+    if (a === undefined && b !== undefined)
+        return -1;
+    if (a !== undefined && b === undefined)
+        return 1;
+    if (typeof a === 'number' && typeof b === 'number') {
+        if (Number.isNaN(a) && Number.isNaN(b))
+            return 0;
+        if (Number.isNaN(a))
+            return -1;
+        if (Number.isNaN(b))
+            return 1;
+        return a < b ? -1 : 1;
+    }
+    if (a?.toMillis && b?.toMillis) {
+        const ma = a.toMillis();
+        const mb = b.toMillis();
+        return ma < mb ? -1 : (ma > mb ? 1 : 0);
+    }
+    if (typeof a === 'string' && typeof b === 'string')
+        return a < b ? -1 : 1;
+    if (typeof a === 'boolean' && typeof b === 'boolean')
+        return a === b ? 0 : (a ? 1 : -1);
+    return 0; // Fallback
+}
+function serializeConstraint(c) {
+    const res = { type: c.type };
+    if (c.fieldPath) {
+        res.fieldPath = typeof c.fieldPath === 'string' ? c.fieldPath : c.fieldPath.getPathString();
+    }
+    if (c.opStr)
+        res.opStr = c.opStr;
+    if (c.value !== undefined)
+        res.value = cloneNexaData(c.value);
+    if (c.directionStr)
+        res.directionStr = c.directionStr;
+    if (c.limitValue !== undefined)
+        res.limitValue = c.limitValue;
+    if (c.docSnapshot) {
+        res.docSnapshotId = c.docSnapshot.id;
+    }
+    if (c.cursorValues) {
+        res.cursorValues = cloneNexaData(c.cursorValues);
+    }
+    return res;
+}

package/dist/firestore/writes.d.ts

@@ -1,15 +1,28 @@
 import { DocumentReference } from '../types/index';
 export { FieldValue } from './FieldValue';
+export type WriteResult<T = unknown> = {
+    status: 'committed';
+    committed: true;
+    writtenLocally: true;
+    mutationId: string;
+    data?: T;
+} | {
+    status: 'pending';
+    committed: false;
+    writtenLocally: true;
+    mutationId: string;
+};
 export declare const setDoc: (docRef: DocumentReference, data: any, options?: {
     merge?: boolean;
     idempotencyKey?: string;
-}) => Promise<any>;
+}) => Promise<WriteResult>;
 export declare const patchDoc: (docRef: DocumentReference, data: any, options?: {
     idempotencyKey?: string;
-}) => Promise<any>;
+    preconditionExists?: boolean;
+}) => Promise<WriteResult>;
 export declare const updateDoc: (docRef: DocumentReference, data: any, options?: {
     idempotencyKey?: string;
-}) => Promise<any>;
+}) => Promise<WriteResult>;
 export declare const deleteDoc: (docRef: DocumentReference, options?: {
     idempotencyKey?: string;
-}) => Promise<any>;
+}) => Promise<WriteResult>;