nexabase-console 2.1.1 → 2.1.3

package/dist/app/NexaApp.d.ts

@@ -32,6 +32,8 @@ export declare class NexaApp {
     _firestoreListening: boolean;
     _firestoreUnsubscribes: (() => void)[];
     _initPromise: Promise<void> | null;
+    _initialized: boolean;
+    _activeQueryTimestamps: Map<string, number>;
     constructor(config: NexaConfig);
     get _firestoreCache(): Record<string, any>;
     private _setupCrossTabSync;
@@ -85,6 +87,7 @@ export declare class NexaApp {
         revision?: string;
     }): Promise<void>;
     _syncOfflineQueue(): Promise<void>;
+    _handleServerFirestoreChange(payload: any): void;
     _ensureFirestoreSSE(): void;
     _ensureFirestoreWebSocket(): void;
     _closeFirestoreSSEIfIdle(): void;

package/dist/app/NexaApp.js

@@ -22,6 +22,8 @@ class NexaApp {
         this._firestoreListening = false;
         this._firestoreUnsubscribes = [];
         this._initPromise = null;
+        this._initialized = false;
+        this._activeQueryTimestamps = new Map();
         this.projectId = config.projectId;
         this.token = config.apiKey || null;
         this.enablePersistence = config.enablePersistence !== false;
@@ -82,8 +84,10 @@ class NexaApp {
         this.mutationQueue.unmarkInflight(path, mutationId);
     }
     async _initFirestoreState() {
-        if (!this.enablePersistence)
+        if (!this.enablePersistence) {
+            this._initialized = true;
             return;
+        }
         try {
             await this.indexedDB.init();
             await this.localStore.loadAll();
@@ -97,6 +101,9 @@ class NexaApp {
         catch (err) {
             console.warn('[NexaApp] Failed to initialize IndexedDB offline cache:', err);
         }
+        finally {
+            this._initialized = true;
+        }
     }
     async _setCache(path, data) {
         const revived = (0, QueryUtils_1.reviveNexaData)(data);
@@ -348,23 +355,43 @@ class NexaApp {
     async _syncOfflineQueue() {
         await this.syncEngine.syncOfflineMutations();
     }
+    _handleServerFirestoreChange(payload) {
+        if (!payload)
+            return;
+        if (Array.isArray(payload)) {
+            payload.forEach((item) => this._handleServerFirestoreChange(item));
+            return;
+        }
+        const { type, docPath, collectionPath, data, path: rawPath, action } = payload;
+        const targetDocPath = docPath || rawPath;
+        const isDelete = type === 'document_deleted' || action === 'delete' || type === 'delete';
+        if (targetDocPath && typeof targetDocPath === 'string') {
+            if (isDelete) {
+                this._deleteCache(targetDocPath);
+            }
+            else if (data) {
+                this._setCache(targetDocPath, data);
+            }
+            const parts = targetDocPath.split('/');
+            const colPath = parts.length > 1 ? parts.slice(0, -1).join('/') : '';
+            this._notifySnapshotCallbacks(targetDocPath, isDelete ? 'document_deleted' : 'document_written', data);
+            if (colPath) {
+                this._notifySnapshotCallbacks(colPath, isDelete ? 'document_deleted' : 'document_written', data);
+            }
+        }
+        else if (collectionPath && typeof collectionPath === 'string') {
+            this._notifySnapshotCallbacks(collectionPath, 'server_update', data);
+        }
+    }
     _ensureFirestoreSSE() {
         if (this._firestoreListening)
             return;
         this._firestoreListening = true;
         const unsub1 = this.wsClient.addListener('data_changed', (payload) => {
-            if (payload && payload.path) {
-                if (payload.action === 'delete') {
-                    this._deleteCache(payload.path);
-                }
-                else if (payload.data) {
-                    this._setCache(payload.path, payload.data);
-                }
-                this._notifySnapshotCallbacks(payload.path, payload.action === 'delete' ? 'document_deleted' : 'document_written', payload.data);
-            }
+            this._handleServerFirestoreChange(payload);
         });
         const unsub2 = this.wsClient.addListener('firestore_changed', (payload) => {
-            this._notifySnapshotCallbacks(payload.collectionPath || payload.docPath, 'server_update', payload.data);
+            this._handleServerFirestoreChange(payload);
         });
         this._firestoreUnsubscribes.push(unsub1, unsub2);
     }
@@ -382,6 +409,8 @@ class NexaApp {
         this._closeFirestoreSSEIfIdle();
     }
     _notifySnapshotCallbacks(path, actionType, payload) {
+        if (!path || typeof path !== 'string')
+            return;
         Object.keys(this._snapshotCallbacks).forEach((cbKey) => {
             const parts = cbKey.split('_');
             const targetPath = parts.slice(2).join('_');

package/dist/firestore/CollectionReference.d.ts

@@ -1,3 +1,3 @@
 import { NexaApp } from '../app/NexaApp';
-import { CollectionReference } from '../types/index';
-export declare const collection: <T = any>(db: NexaApp, collectionPath: string) => CollectionReference<T>;
+import { CollectionReference, DocumentReference } from '../types/index';
+export declare const collection: <T = any>(dbOrRef: NexaApp | DocumentReference<any> | CollectionReference<any>, ...pathSegments: string[]) => CollectionReference<T>;

package/dist/firestore/CollectionReference.js

@@ -1,7 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collection = void 0;
-const collection = (db, collectionPath) => {
-    return { type: 'collection', path: collectionPath, db };
+const NexaError_1 = require("../errors/NexaError");
+const pathValidation_1 = require("./pathValidation");
+const collection = (dbOrRef, ...pathSegments) => {
+    if (!dbOrRef || typeof dbOrRef !== 'object') {
+        throw new NexaError_1.NexaError('invalid-argument', 'First argument to collection() must be a valid NexaApp, DocumentReference, or CollectionReference.');
+    }
+    if ('type' in dbOrRef && dbOrRef.type === 'document') {
+        if (pathSegments.length === 0) {
+            throw new NexaError_1.NexaError('invalid-argument', 'collection() called with DocumentReference requires path segments.');
+        }
+        const joined = pathSegments.join('/');
+        const finalPath = (0, pathValidation_1.validateCollectionPath)(`${dbOrRef.path}/${joined}`);
+        return {
+            type: 'collection',
+            path: finalPath,
+            db: dbOrRef.db
+        };
+    }
+    if ('type' in dbOrRef && dbOrRef.type === 'collection') {
+        if (pathSegments.length === 0) {
+            return dbOrRef;
+        }
+        const joined = pathSegments.join('/');
+        const finalPath = (0, pathValidation_1.validateCollectionPath)(`${dbOrRef.path}/${joined}`);
+        return {
+            type: 'collection',
+            path: finalPath,
+            db: dbOrRef.db
+        };
+    }
+    // dbOrRef is NexaApp
+    if (pathSegments.length === 0) {
+        throw new NexaError_1.NexaError('invalid-argument', 'collection() called with database reference requires a path.');
+    }
+    const joined = pathSegments.join('/');
+    const finalPath = (0, pathValidation_1.validateCollectionPath)(joined);
+    return {
+        type: 'collection',
+        path: finalPath,
+        db: dbOrRef
+    };
 };
 exports.collection = collection;

package/dist/firestore/DocumentReference.d.ts

@@ -1,3 +1,3 @@
 import { NexaApp } from '../app/NexaApp';
 import { CollectionReference, DocumentReference } from '../types/index';
-export declare const doc: <T = any>(dbOrCollection: NexaApp | CollectionReference<any>, ...pathSegments: string[]) => DocumentReference<T>;
+export declare const doc: <T = any>(dbOrRef: NexaApp | CollectionReference<any> | DocumentReference<any>, ...pathSegments: string[]) => DocumentReference<T>;

package/dist/firestore/DocumentReference.js

@@ -1,22 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.doc = void 0;
-const doc = (dbOrCollection, ...pathSegments) => {
-    let docRef;
-    if ('type' in dbOrCollection && dbOrCollection.type === 'collection') {
-        docRef = {
+const NexaError_1 = require("../errors/NexaError");
+const pathValidation_1 = require("./pathValidation");
+const doc = (dbOrRef, ...pathSegments) => {
+    if (!dbOrRef || typeof dbOrRef !== 'object') {
+        throw new NexaError_1.NexaError('invalid-argument', 'First argument to doc() must be a valid NexaApp, CollectionReference, or DocumentReference.');
+    }
+    if ('type' in dbOrRef && dbOrRef.type === 'collection') {
+        if (pathSegments.length === 0) {
+            const autoId = (0, pathValidation_1.generateAutoId)();
+            const finalPath = (0, pathValidation_1.validateDocumentPath)(`${dbOrRef.path}/${autoId}`);
+            return {
+                type: 'document',
+                path: finalPath,
+                db: dbOrRef.db
+            };
+        }
+        const joined = pathSegments.join('/');
+        const finalPath = (0, pathValidation_1.validateDocumentPath)(`${dbOrRef.path}/${joined}`);
+        return {
             type: 'document',
-            path: `${dbOrCollection.path}/${pathSegments.join('/')}`,
-            db: dbOrCollection.db
+            path: finalPath,
+            db: dbOrRef.db
         };
     }
-    else {
-        docRef = {
+    if ('type' in dbOrRef && dbOrRef.type === 'document') {
+        if (pathSegments.length === 0) {
+            return dbOrRef;
+        }
+        const joined = pathSegments.join('/');
+        const finalPath = (0, pathValidation_1.validateDocumentPath)(`${dbOrRef.path}/${joined}`);
+        return {
             type: 'document',
-            path: pathSegments.join('/'),
-            db: dbOrCollection
+            path: finalPath,
+            db: dbOrRef.db
         };
     }
-    return docRef;
+    // dbOrRef is NexaApp instance
+    if (pathSegments.length === 0) {
+        throw new NexaError_1.NexaError('invalid-argument', 'doc() called with database reference requires at least one path segment.');
+    }
+    const joined = pathSegments.join('/');
+    const finalPath = (0, pathValidation_1.validateDocumentPath)(joined);
+    return {
+        type: 'document',
+        path: finalPath,
+        db: dbOrRef
+    };
 };
 exports.doc = doc;

package/dist/firestore/FieldPath.d.ts

@@ -1,7 +1,8 @@
 export declare class FieldPath {
-    private readonly segments;
+    readonly segments: readonly string[];
     constructor(...fieldNames: string[]);
     static documentId(): FieldPath;
     getPathString(): string;
     isEqual(other: FieldPath): boolean;
+    toString(): string;
 }

package/dist/firestore/FieldPath.js

@@ -1,23 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FieldPath = void 0;
+const NexaError_1 = require("../errors/NexaError");
+const CONTROL_CHARS_REGEX = /[\x00-\x1F\x7F]/;
+const SIMPLE_FIELD_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 class FieldPath {
     constructor(...fieldNames) {
-        if (fieldNames.length === 0) {
-            throw new Error('FieldPath must contain at least one field name');
+        if (!fieldNames || fieldNames.length === 0) {
+            throw new NexaError_1.NexaError('invalid-argument', 'FieldPath must contain at least one field name.');
         }
-        this.segments = fieldNames;
+        for (let i = 0; i < fieldNames.length; i++) {
+            const name = fieldNames[i];
+            if (typeof name !== 'string' || name.length === 0) {
+                throw new NexaError_1.NexaError('invalid-argument', `Invalid field path segment at index ${i}. Provided field name must be a non-empty string.`);
+            }
+            if (CONTROL_CHARS_REGEX.test(name)) {
+                throw new NexaError_1.NexaError('invalid-argument', `FieldPath segment "${name}" contains invalid control characters.`);
+            }
+        }
+        this.segments = Object.freeze([...fieldNames]);
+        Object.freeze(this);
     }
     static documentId() {
         return new FieldPath('__name__');
     }
     getPathString() {
-        return this.segments.join('.');
+        return this.segments
+            .map((seg) => {
+            if (SIMPLE_FIELD_NAME_REGEX.test(seg)) {
+                return seg;
+            }
+            // Escape backslashes and backticks, then wrap in backticks
+            const escaped = seg.replace(/\\/g, '\\\\').replace(/`/g, '\\`');
+            return `\`${escaped}\``;
+        })
+            .join('.');
     }
     isEqual(other) {
+        if (!(other instanceof FieldPath))
+            return false;
         if (this.segments.length !== other.segments.length)
             return false;
         return this.segments.every((seg, idx) => seg === other.segments[idx]);
     }
+    toString() {
+        return this.getPathString();
+    }
 }
 exports.FieldPath = FieldPath;

package/dist/firestore/FieldValue.d.ts

@@ -1,8 +1,12 @@
+export declare const FIELD_VALUE_BRAND: unique symbol;
+export type FieldValueMethod = 'serverTimestamp' | 'increment' | 'arrayUnion' | 'arrayRemove' | 'deleteField';
 export declare class FieldValue {
-    method: string;
-    value?: any | undefined;
-    _isFieldValue: boolean;
-    constructor(method: string, value?: any | undefined);
+    readonly [FIELD_VALUE_BRAND] = true;
+    readonly method: FieldValueMethod;
+    readonly value?: any;
+    constructor(method: FieldValueMethod, value?: any);
+    static isFieldValue(val: any): val is FieldValue;
+    isEqual(other: any): boolean;
 }
 export declare const serverTimestamp: () => FieldValue;
 export declare const increment: (n: number) => FieldValue;

package/dist/firestore/FieldValue.js

@@ -1,26 +1,78 @@
 "use strict";
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.atomicDecrement = exports.atomicIncrement = exports.deleteField = exports.arrayRemove = exports.arrayUnion = exports.increment = exports.serverTimestamp = exports.FieldValue = void 0;
+exports.atomicDecrement = exports.atomicIncrement = exports.deleteField = exports.arrayRemove = exports.arrayUnion = exports.increment = exports.serverTimestamp = exports.FieldValue = exports.FIELD_VALUE_BRAND = void 0;
+const NexaError_1 = require("../errors/NexaError");
+exports.FIELD_VALUE_BRAND = Symbol.for('nexabase.fieldValue');
 class FieldValue {
     constructor(method, value) {
+        this[_a] = true;
         this.method = method;
         this.value = value;
-        this._isFieldValue = true;
+        Object.freeze(this);
+    }
+    static isFieldValue(val) {
+        return (val !== null &&
+            typeof val === 'object' &&
+            (val instanceof FieldValue || val[exports.FIELD_VALUE_BRAND] === true));
+    }
+    isEqual(other) {
+        if (!FieldValue.isFieldValue(other))
+            return false;
+        if (this.method !== other.method)
+            return false;
+        if (this.value === other.value)
+            return true;
+        if (Array.isArray(this.value) && Array.isArray(other.value)) {
+            return (this.value.length === other.value.length &&
+                this.value.every((v, i) => v === other.value[i]));
+        }
+        return false;
     }
 }
 exports.FieldValue = FieldValue;
+_a = exports.FIELD_VALUE_BRAND;
 const serverTimestamp = () => new FieldValue('serverTimestamp');
 exports.serverTimestamp = serverTimestamp;
-const increment = (n) => new FieldValue('increment', n);
+const increment = (n) => {
+    if (typeof n !== 'number' || !Number.isFinite(n)) {
+        throw new NexaError_1.NexaError('invalid-argument', 'FieldValue.increment() value must be a finite number.');
+    }
+    return new FieldValue('increment', n);
+};
 exports.increment = increment;
-const arrayUnion = (...elements) => new FieldValue('arrayUnion', elements);
+const arrayUnion = (...elements) => {
+    for (let i = 0; i < elements.length; i++) {
+        if (FieldValue.isFieldValue(elements[i])) {
+            throw new NexaError_1.NexaError('invalid-argument', 'FieldValue.arrayUnion() elements cannot contain nested FieldValues.');
+        }
+    }
+    return new FieldValue('arrayUnion', Object.freeze([...elements]));
+};
 exports.arrayUnion = arrayUnion;
-const arrayRemove = (...elements) => new FieldValue('arrayRemove', elements);
+const arrayRemove = (...elements) => {
+    for (let i = 0; i < elements.length; i++) {
+        if (FieldValue.isFieldValue(elements[i])) {
+            throw new NexaError_1.NexaError('invalid-argument', 'FieldValue.arrayRemove() elements cannot contain nested FieldValues.');
+        }
+    }
+    return new FieldValue('arrayRemove', Object.freeze([...elements]));
+};
 exports.arrayRemove = arrayRemove;
 const deleteField = () => new FieldValue('deleteField');
 exports.deleteField = deleteField;
 // Helper methods for Offline-First operations (e.g. POS/Inventory systems)
-const atomicIncrement = (n) => new FieldValue('increment', Math.abs(n));
+const atomicIncrement = (n) => {
+    if (typeof n !== 'number' || !Number.isFinite(n)) {
+        throw new NexaError_1.NexaError('invalid-argument', 'atomicIncrement() value must be a finite number.');
+    }
+    return new FieldValue('increment', Math.abs(n));
+};
 exports.atomicIncrement = atomicIncrement;
-const atomicDecrement = (n) => new FieldValue('increment', -Math.abs(n));
+const atomicDecrement = (n) => {
+    if (typeof n !== 'number' || !Number.isFinite(n)) {
+        throw new NexaError_1.NexaError('invalid-argument', 'atomicDecrement() value must be a finite number.');
+    }
+    return new FieldValue('increment', -Math.abs(n));
+};
 exports.atomicDecrement = atomicDecrement;

package/dist/firestore/Firestore.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enableOfflinePersistence = exports.enableIndexedDbPersistence = exports.Firestore = void 0;
+const NexaError_1 = require("../errors/NexaError");
 class Firestore {
     constructor(app) {
+        if (!app) {
+            throw new NexaError_1.NexaError('invalid-argument', 'Firestore constructor requires a valid NexaApp instance.');
+        }
         this.app = app;
     }
     getApp() {
@@ -11,14 +15,22 @@ class Firestore {
 }
 exports.Firestore = Firestore;
 const enableIndexedDbPersistence = async (db) => {
+    if (!db) {
+        throw new NexaError_1.NexaError('invalid-argument', 'enableIndexedDbPersistence requires a valid NexaApp database instance.');
+    }
+    if (typeof window !== 'undefined' && typeof window.indexedDB === 'undefined' && typeof indexedDB === 'undefined') {
+        throw new NexaError_1.NexaError('unimplemented', 'IndexedDB is not supported in the current runtime environment.');
+    }
+    if (db._initialized && !db.enablePersistence) {
+        throw new NexaError_1.NexaError('failed-precondition', 'Firestore persistence must be enabled before any other Firestore operations are executed.');
+    }
     db.enablePersistence = true;
-    if (db._initPromise)
+    if (db._initPromise) {
         await db._initPromise;
+    }
 };
 exports.enableIndexedDbPersistence = enableIndexedDbPersistence;
 const enableOfflinePersistence = async (db) => {
-    db.enablePersistence = true;
-    if (db._initPromise)
-        await db._initPromise;
+    return (0, exports.enableIndexedDbPersistence)(db);
 };
 exports.enableOfflinePersistence = enableOfflinePersistence;

package/dist/firestore/GeoPoint.d.ts

@@ -3,6 +3,7 @@ export declare class GeoPoint {
     readonly longitude: number;
     constructor(latitude: number, longitude: number);
     isEqual(other: GeoPoint): boolean;
+    toString(): string;
     toJSON(): {
         latitude: number;
         longitude: number;

package/dist/firestore/GeoPoint.js

@@ -1,20 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GeoPoint = void 0;
+const NexaError_1 = require("../errors/NexaError");
 class GeoPoint {
     constructor(latitude, longitude) {
-        this.latitude = latitude;
-        this.longitude = longitude;
-        if (isNaN(latitude) || latitude < -90 || latitude > 90) {
-            throw new Error(`Latitude must be a number between -90 and 90, but got ${latitude}`);
+        if (typeof latitude !== 'number' || !Number.isFinite(latitude) || latitude < -90 || latitude > 90) {
+            throw new NexaError_1.NexaError('invalid-argument', `Latitude must be a finite number between -90 and 90, but got ${latitude}`);
         }
-        if (isNaN(longitude) || longitude < -180 || longitude > 180) {
-            throw new Error(`Longitude must be a number between -180 and 180, but got ${longitude}`);
+        if (typeof longitude !== 'number' || !Number.isFinite(longitude) || longitude < -180 || longitude > 180) {
+            throw new NexaError_1.NexaError('invalid-argument', `Longitude must be a finite number between -180 and 180, but got ${longitude}`);
         }
+        this.latitude = latitude;
+        this.longitude = longitude;
+        Object.freeze(this);
     }
     isEqual(other) {
+        if (!(other instanceof GeoPoint))
+            return false;
         return this.latitude === other.latitude && this.longitude === other.longitude;
     }
+    toString() {
+        return `GeoPoint(latitude=${this.latitude}, longitude=${this.longitude})`;
+    }
     toJSON() {
         return { latitude: this.latitude, longitude: this.longitude };
     }

package/dist/firestore/Query.d.ts

@@ -1,5 +1,10 @@
 import { FieldPath } from './FieldPath';
 import { CollectionReference, Query, QueryConstraint, QuerySnapshot, AggregateField, AggregateSpec, AggregateSpecData, AggregateQuerySnapshot } from '../types/index';
+export declare function getCanonicalQueryKey(collectionPath: string, constraints: QueryConstraint[]): string;
+export declare function validateAndDeduplicateServerDocs(docs: any[]): Array<{
+    id: string;
+    fields: any;
+}>;
 export declare const query: <T = any>(queryObject: Query<T> | CollectionReference<T>, ...queryConstraints: QueryConstraint[]) => Query<T>;
 export declare const getCachedDocs: <T = any>(queryOrCollection: Query<T> | CollectionReference<T>, fromCache?: boolean) => QuerySnapshot<T>;
 export declare const getDocs: <T = any>(queryOrCollection: Query<T> | CollectionReference<T>) => Promise<QuerySnapshot<T>>;