nexabase-console 1.1.0 → 1.1.2

package/README.md

@@ -110,8 +110,10 @@ const listenLive = () => {
 };
 ```
 
-#### Menggunakan Atomic Write Batch (Sangat Disarankan untuk >100 Data/Hari)
-Jika Anda harus memasukkan data dalam jumlah besar (misal: 500 resi pengiriman), hindari memanggil `setDoc` satu per satu di dalam _looping_ (looping 500 kali = 500 koneksi = berpotensi menimbulkan lag di sisi klien yang sedang berlangganan `onSnapshot`). Gunakan fitur `writeBatch` yang membundel seluruh operasi Anda dalam satu pengiriman jaringan (hingga 500 operasi per eksekusi).
+#### Menggunakan Atomic Write Batch (Untuk Upload File / Excel Massal)
+Jika Anda mengunggah data sekaligus dalam jumlah besar dari file (misal: import 500 resi dari Excel), hindari memanggil `setDoc` satu per satu di dalam _looping_. Gunakan fitur `writeBatch` yang membundel seluruh operasi Anda dalam satu pengiriman jaringan (hingga 500 operasi per eksekusi).
+
+**Catatan:** Jika alur kerjanya adalah **kasir/admin melakukan scan barcode satu-per-satu lalu menekan enter**, maka Anda **TIDAK PERLU** menggunakan `writeBatch`. Menyimpan data satu-per-satu (`setDoc` / `addDoc`) setiap kali dienter adalah **cara yang paling benar dan normal** untuk kebutuhan _realtime_. Database dapat dengan mudah menangani 500 scan yang terjadi secara bertahap sepanjang hari.
 
 ```javascript
 import { doc, writeBatch } from 'nexabase-console';

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export interface NexaConfig {
     projectId: string;
     apiKey?: string;
     endpoint?: string;
+    enablePersistence?: boolean;
+    cacheStrategy?: 'network-first' | 'cache-first';
 }
 export interface User {
     id: string;
@@ -26,6 +28,7 @@ export interface DocumentReference<T = any> {
     type: 'document';
     path: string;
     db: NexaApp;
+    patch?: (data: Partial<T>) => Promise<any>;
 }
 export interface CollectionReference<T = any> {
     type: 'collection';
@@ -90,21 +93,27 @@ export interface StorageReference {
 export interface WriteBatch {
     set: (docRef: DocumentReference, data: any) => WriteBatch;
     update: (docRef: DocumentReference, data: any) => WriteBatch;
+    patch: (docRef: DocumentReference, data: any) => WriteBatch;
     delete: (docRef: DocumentReference) => WriteBatch;
     commit: () => Promise<any>;
 }
 interface OfflineJob {
     id: string;
-    type: 'set' | 'update' | 'delete';
+    type: 'set' | 'update' | 'patch' | 'delete';
     path: string;
     data?: any;
+    idempotencyKey?: string;
+    timestamp?: number;
 }
+export declare function generateIdempotencyKey(): string;
 export declare class NexaApp {
     projectId: string;
     token: string | null;
     endpoint: string;
     client: AxiosInstance;
     sse: EventSource | null;
+    enablePersistence: boolean;
+    cacheStrategy: 'network-first' | 'cache-first';
     _firestoreCache: Record<string, any>;
     _snapshotCallbacks: Record<string, (payload?: any) => void>;
     _sseCallbacks: {
@@ -116,8 +125,14 @@ export declare class NexaApp {
     _idb: any;
     _firestoreListening: boolean;
     _initPromise: Promise<void> | null;
+    _broadcastChannel: any;
+    _reconnectAttempts: number;
+    _reconnectTimer: any;
     constructor(config: NexaConfig);
+    _initCrossTabSync(): void;
+    _broadcastLocalMutation(docPath: string, action: 'set' | 'update' | 'patch' | 'delete' | 'bulk_update', data?: any): void;
     connectRealtime(): EventSource;
+    _notifySnapshotCallbacks(docPath: string, eventType: string, data?: any): void;
     database(): {
         ref: (path?: string) => DatabaseReference;
     };
@@ -146,6 +161,10 @@ export declare class NexaApp {
     _syncOfflineQueue(): Promise<void>;
     _ensureFirestoreSSE(): void;
 }
+export declare const NexaBase: {
+    init: (config: NexaConfig) => NexaApp;
+    initializeApp: (config: NexaConfig) => NexaApp;
+};
 export declare const initializeApp: (config: NexaConfig) => NexaApp;
 export declare const getFirestore: (app: NexaApp) => NexaApp;
 export declare const collection: <T = any>(db: NexaApp, collectionPath: string) => CollectionReference<T>;
@@ -158,9 +177,18 @@ export declare const getCachedDocs: <T = any>(queryOrCollection: Query<T> | Coll
 export declare const getCachedDoc: <T = any>(docRef: DocumentReference<T>) => DocumentSnapshot<T>;
 export declare const getDocs: <T = any>(queryOrCollection: Query<T> | CollectionReference<T>) => Promise<QuerySnapshot<T>>;
 export declare const getDoc: <T = any>(docRef: DocumentReference<T>) => Promise<DocumentSnapshot<T>>;
-export declare const setDoc: (docRef: DocumentReference, data: any) => Promise<any>;
-export declare const updateDoc: (docRef: DocumentReference, data: any) => Promise<any>;
-export declare const deleteDoc: (docRef: DocumentReference) => Promise<any>;
+export declare const setDoc: (docRef: DocumentReference, data: any, options?: {
+    idempotencyKey?: string;
+}) => Promise<any>;
+export declare const patchDoc: (docRef: DocumentReference, data: any, options?: {
+    idempotencyKey?: string;
+}) => Promise<any>;
+export declare const updateDoc: (docRef: DocumentReference, data: any, options?: {
+    idempotencyKey?: string;
+}) => Promise<any>;
+export declare const deleteDoc: (docRef: DocumentReference, options?: {
+    idempotencyKey?: string;
+}) => Promise<any>;
 export declare const onSnapshot: (ref: CollectionReference | DocumentReference | Query, callback: (snapshot: any) => void) => (() => void);
 export declare const enableIndexedDbPersistence: (db: NexaApp) => Promise<void>;
 export declare const enableOfflinePersistence: (db: NexaApp) => Promise<void>;
@@ -169,6 +197,7 @@ export interface Transaction {
     get: <T = any>(docRef: DocumentReference<T>) => Promise<DocumentSnapshot<T>>;
     set: (docRef: DocumentReference, data: any) => Transaction;
     update: (docRef: DocumentReference, data: any) => Transaction;
+    patch: (docRef: DocumentReference, data: any) => Transaction;
     delete: (docRef: DocumentReference) => Transaction;
 }
 export declare const runTransaction: <T = any>(db: NexaApp, updateFunction: (transaction: Transaction) => Promise<T>, options?: {

package/dist/index.js

@@ -3,9 +3,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runTransaction = exports.writeBatch = exports.enableOfflinePersistence = exports.enableIndexedDbPersistence = exports.onSnapshot = exports.deleteDoc = exports.updateDoc = exports.setDoc = exports.getDoc = exports.getDocs = exports.getCachedDoc = exports.getCachedDocs = exports.limit = exports.orderBy = exports.where = exports.query = exports.doc = exports.collection = exports.getFirestore = exports.initializeApp = exports.NexaApp = void 0;
+exports.runTransaction = exports.writeBatch = exports.enableOfflinePersistence = exports.enableIndexedDbPersistence = exports.onSnapshot = exports.deleteDoc = exports.updateDoc = exports.patchDoc = exports.setDoc = exports.getDoc = exports.getDocs = exports.getCachedDoc = exports.getCachedDocs = exports.limit = exports.orderBy = exports.where = exports.query = exports.doc = exports.collection = exports.getFirestore = exports.initializeApp = exports.NexaBase = exports.NexaApp = void 0;
+exports.generateIdempotencyKey = generateIdempotencyKey;
 const axios_1 = __importDefault(require("axios"));
 // -----------------------------------------------------------------
+// Idempotency Utility
+// -----------------------------------------------------------------
+function generateIdempotencyKey() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return `nexa_idemp_${Date.now()}_${Math.random().toString(36).substring(2, 9)}_${Math.floor(Math.random() * 1000000)}`;
+}
+// -----------------------------------------------------------------
 // Main NexaApp SDK Class
 // -----------------------------------------------------------------
 class NexaApp {
@@ -21,18 +31,23 @@ class NexaApp {
         this._idb = null;
         this._firestoreListening = false;
         this._initPromise = null;
+        // Real-time Engine Utilities (Cross-Tab & Cross-Device)
+        this._broadcastChannel = null;
+        this._reconnectAttempts = 0;
+        this._reconnectTimer = null;
         this.projectId = config.projectId;
         this.token = config.apiKey || null;
+        this.enablePersistence = config.enablePersistence !== false;
+        this.cacheStrategy = config.cacheStrategy || 'cache-first';
         if (typeof window !== 'undefined' && window.localStorage) {
             const savedToken = localStorage.getItem(`nexa_token_${this.projectId}`);
             if (savedToken) {
                 this.token = savedToken;
             }
         }
-        // 3. Smart Endpoint Resolution: Auto-detect domain/host if none is specified
+        // Auto-detect endpoint
         let defaultEndpoint = 'https://db.nexabase.id';
         if (typeof window !== 'undefined' && window.location) {
-            // Default to the current page origin in dev/proxy preview environments so it auto-points to /api/*
             defaultEndpoint = window.location.origin;
         }
         this.endpoint = config.endpoint || defaultEndpoint;
@@ -42,43 +57,131 @@ class NexaApp {
                 'Content-Type': 'application/json'
             }
         });
-        // Request interceptor to attach bearer token and automatically resolve the axios boundary issue for file uploads
+        // Request interceptor to attach bearer token and boundary fix
         this.client.interceptors.request.use((req) => {
             if (this.token) {
                 req.headers.Authorization = `Bearer ${this.token}`;
             }
-            // 2. Fix Axios Multipart Boundary on File Upload
-            // If Content-Type is multipart/form-data, delete it so axios/browser automatically appends the boundary header
             if (req.headers && req.headers['Content-Type'] === 'multipart/form-data') {
                 delete req.headers['Content-Type'];
             }
             return req;
         });
+        // Initialize Cross-Tab Sync via BroadcastChannel
+        this._initCrossTabSync();
+    }
+    // Cross-Tab Engine via BroadcastChannel API
+    _initCrossTabSync() {
+        if (typeof window !== 'undefined' && 'BroadcastChannel' in window && !this._broadcastChannel) {
+            try {
+                this._broadcastChannel = new BroadcastChannel(`nexabase_sync_${this.projectId}`);
+                this._broadcastChannel.onmessage = (event) => {
+                    const { type, docPath, data, action } = event.data || {};
+                    if (type === 'cross_tab_mutation' && docPath) {
+                        if (action === 'set' || action === 'update' || action === 'patch') {
+                            if (action === 'patch' || action === 'update') {
+                                const existing = this._firestoreCache[docPath] || {};
+                                this._firestoreCache[docPath] = { ...existing, ...data };
+                            }
+                            else {
+                                this._firestoreCache[docPath] = data;
+                            }
+                            if (this.enablePersistence && this._idb) {
+                                this._setCache(docPath, this._firestoreCache[docPath]);
+                            }
+                            this._notifySnapshotCallbacks(docPath, 'document_written', this._firestoreCache[docPath]);
+                        }
+                        else if (action === 'delete') {
+                            delete this._firestoreCache[docPath];
+                            if (this.enablePersistence && this._idb) {
+                                this._deleteCache(docPath);
+                            }
+                            this._notifySnapshotCallbacks(docPath, 'document_deleted', null);
+                        }
+                        else if (action === 'bulk_update') {
+                            this._notifySnapshotCallbacks('*', 'bulk_update', null);
+                        }
+                    }
+                };
+            }
+            catch (e) {
+                // BroadcastChannel fallback silently if disabled by security context
+            }
+        }
+    }
+    _broadcastLocalMutation(docPath, action, data) {
+        if (this._broadcastChannel) {
+            try {
+                this._broadcastChannel.postMessage({
+                    type: 'cross_tab_mutation',
+                    docPath,
+                    action,
+                    data,
+                    timestamp: Date.now()
+                });
+            }
+            catch (e) { }
+        }
     }
-    // Real-time listener connection via Server-Sent Events (SSE)
+    // Cross-Device Realtime Connection via SSE with Auto-Reconnect & Heartbeat
     connectRealtime() {
         if (this.sse)
             return this.sse;
         const url = `${this.endpoint}/api/firestore/${this.projectId}/listen`;
         const listenUrl = this.token ? `${url}?token=${this.token}` : url;
-        this.sse = new EventSource(listenUrl);
-        this.sse.onmessage = async (event) => {
-            try {
-                const payload = JSON.parse(event.data);
-                if (payload.type === 'connected')
-                    return;
-                if (payload.type && (payload.type.includes('document_') || payload.type === 'bulk_update')) {
-                    this._sseCallbacks.firestore_changed.forEach((cb) => cb(payload));
+        try {
+            this.sse = new EventSource(listenUrl);
+            this.sse.onmessage = async (event) => {
+                try {
+                    const payload = JSON.parse(event.data);
+                    if (payload.type === 'connected') {
+                        this._reconnectAttempts = 0; // Reset backoff on stable connection
+                        return;
+                    }
+                    if (payload.type && (payload.type.includes('document_') || payload.type === 'bulk_update')) {
+                        this._sseCallbacks.firestore_changed.forEach((cb) => cb(payload));
+                    }
+                    else {
+                        this._sseCallbacks.data_changed.forEach((cb) => cb(payload));
+                    }
                 }
-                else {
-                    this._sseCallbacks.data_changed.forEach((cb) => cb(payload));
+                catch (e) {
+                    // Ignore JSON parse errors on ping
+                }
+            };
+            this.sse.onerror = () => {
+                if (this.sse) {
+                    this.sse.close();
+                    this.sse = null;
                 }
+                if (this._reconnectTimer)
+                    clearTimeout(this._reconnectTimer);
+                // Exponential backoff reconnect: 1s, 2s, 4s, ... max 30s
+                this._reconnectAttempts++;
+                const backoffMs = Math.min(1000 * Math.pow(2, this._reconnectAttempts), 30000);
+                this._reconnectTimer = setTimeout(() => {
+                    this.connectRealtime();
+                }, backoffMs);
+            };
+        }
+        catch (e) {
+            // Return dummy EventSource if SSE fails in environment
+        }
+        return this.sse;
+    }
+    _notifySnapshotCallbacks(docPath, eventType, data) {
+        Object.keys(this._snapshotCallbacks).forEach((key) => {
+            const cb = this._snapshotCallbacks[key];
+            if (docPath === '*') {
+                cb({ type: eventType });
+                return;
             }
-            catch (e) {
-                // Silent catch JSON parsing errors
+            const parts = key.split('_');
+            const pathKey = parts.slice(2).join('_');
+            if (pathKey === docPath || docPath.startsWith(pathKey + '/')) {
+                cb({ type: eventType, docPath, data });
             }
-        };
-        return this.sse;
+        });
     }
     // -----------------------------------------------------------------
     // Realtime Key-Value Database API
@@ -213,7 +316,6 @@ class NexaApp {
                             formData.append('fileId', actualOptions.fileId);
                         }
                         const response = await this.client.post(`/api/project/${this.projectId}/storage/upload`, formData, {
-                            // We omit Content-Type headers here (interceptor strips it anyway) so the browser naturally generates the boundary
                             onUploadProgress: (progressEvent) => {
                                 if (actualOnProgress && progressEvent.total) {
                                     const percent = Math.round((progressEvent.loaded * 100) / progressEvent.total);
@@ -247,6 +349,8 @@ class NexaApp {
     // Offline Synchronization & Local IndexedDB Cache Engine
     // -----------------------------------------------------------------
     async _initFirestoreState() {
+        if (!this.enablePersistence)
+            return; // Respect enablePersistence ON / OFF option
         if (this._offlineQueueInitialized)
             return;
         this._offlineQueueInitialized = true;
@@ -255,29 +359,33 @@ class NexaApp {
             return;
         }
         const dbName = `nexa_idb_${this.projectId}`;
-        this._idb = await new Promise((resolve, reject) => {
-            const req = indexedDB.open(dbName, 1);
-            req.onupgradeneeded = (e) => {
-                const db = e.target.result;
-                if (!db.objectStoreNames.contains('offline_queue')) {
-                    db.createObjectStore('offline_queue', { keyPath: 'id' });
-                }
-                if (!db.objectStoreNames.contains('offline_cache')) {
-                    db.createObjectStore('offline_cache', { keyPath: 'path' });
-                }
-            };
-            req.onsuccess = () => resolve(req.result);
-            req.onerror = () => reject(req.error);
-        });
-        await this._loadCache();
-        // Trigger queue sync periodically when browser returns online
-        if (typeof window !== 'undefined') {
-            window.addEventListener('online', () => this._syncOfflineQueue());
-            setTimeout(() => this._syncOfflineQueue(), 1000);
+        try {
+            this._idb = await new Promise((resolve, reject) => {
+                const req = indexedDB.open(dbName, 1);
+                req.onupgradeneeded = (e) => {
+                    const db = e.target.result;
+                    if (!db.objectStoreNames.contains('offline_queue')) {
+                        db.createObjectStore('offline_queue', { keyPath: 'id' });
+                    }
+                    if (!db.objectStoreNames.contains('offline_cache')) {
+                        db.createObjectStore('offline_cache', { keyPath: 'path' });
+                    }
+                };
+                req.onsuccess = () => resolve(req.result);
+                req.onerror = () => reject(req.error);
+            });
+            await this._loadCache();
+            if (typeof window !== 'undefined') {
+                window.addEventListener('online', () => this._syncOfflineQueue());
+                setTimeout(() => this._syncOfflineQueue(), 1000);
+            }
+        }
+        catch (err) {
+            console.warn('[NexaBase SDK] IndexedDB persistence unavailable, falling back to memory cache.');
         }
     }
     async _getOfflineQueue() {
-        if (!this._idb)
+        if (!this._idb || !this.enablePersistence)
             return [];
         return new Promise((resolve, reject) => {
             const tx = this._idb.transaction('offline_queue', 'readonly');
@@ -288,7 +396,7 @@ class NexaApp {
         });
     }
     async _saveOfflineQueue(queue) {
-        if (!this._idb)
+        if (!this._idb || !this.enablePersistence)
             return;
         return new Promise((resolve, reject) => {
             const tx = this._idb.transaction('offline_queue', 'readwrite');
@@ -300,7 +408,7 @@ class NexaApp {
         });
     }
     async _addOfflineJob(job) {
-        if (!this._idb)
+        if (!this._idb || !this.enablePersistence)
             return;
         return new Promise((resolve, reject) => {
             const tx = this._idb.transaction('offline_queue', 'readwrite');
@@ -317,7 +425,7 @@ class NexaApp {
     }
     async _setCache(path, data) {
         this._firestoreCache[path] = data;
-        if (!this._idb)
+        if (!this._idb || !this.enablePersistence)
             return;
         return new Promise((resolve, reject) => {
             const tx = this._idb.transaction('offline_cache', 'readwrite');
@@ -329,7 +437,7 @@ class NexaApp {
     }
     async _deleteCache(path) {
         delete this._firestoreCache[path];
-        if (!this._idb)
+        if (!this._idb || !this.enablePersistence)
             return;
         return new Promise((resolve, reject) => {
             const tx = this._idb.transaction('offline_cache', 'readwrite');
@@ -340,7 +448,7 @@ class NexaApp {
         });
     }
     async _loadCache() {
-        if (!this._idb)
+        if (!this._idb || !this.enablePersistence)
             return;
         return new Promise((resolve, reject) => {
             const tx = this._idb.transaction('offline_cache', 'readonly');
@@ -355,8 +463,9 @@ class NexaApp {
             req.onerror = () => reject(req.error);
         });
     }
+    // Outbox Pattern Offline Queue Flush with Idempotency Key
     async _syncOfflineQueue() {
-        if (this._isSyncing)
+        if (this._isSyncing || !this.enablePersistence)
             return;
         this._isSyncing = true;
         const queue = await this._getOfflineQueue();
@@ -366,26 +475,25 @@ class NexaApp {
         }
         for (const job of [...queue]) {
             try {
+                const headers = job.idempotencyKey ? { 'X-Idempotency-Key': job.idempotencyKey } : {};
                 if (job.type === 'set') {
-                    await this.client.post(`/api/firestore/${this.projectId}/document`, { docPath: job.path, data: job.data });
+                    await this.client.post(`/api/firestore/${this.projectId}/document`, { docPath: job.path, data: job.data, idempotencyKey: job.idempotencyKey }, { headers });
                 }
-                else if (job.type === 'update') {
-                    await this.client.patch(`/api/firestore/${this.projectId}/document`, { docPath: job.path, data: job.data });
+                else if (job.type === 'update' || job.type === 'patch') {
+                    await this.client.patch(`/api/firestore/${this.projectId}/document`, { docPath: job.path, data: job.data, idempotencyKey: job.idempotencyKey }, { headers });
                 }
                 else if (job.type === 'delete') {
-                    await this.client.delete(`/api/firestore/${this.projectId}/document?docPath=${encodeURIComponent(job.path)}`);
+                    await this.client.delete(`/api/firestore/${this.projectId}/document?docPath=${encodeURIComponent(job.path)}`, { headers });
                 }
                 const currentQueue = await this._getOfflineQueue();
                 await this._saveOfflineQueue(currentQueue.filter((q) => q.id !== job.id));
             }
             catch (err) {
-                break; // Stop syncing on network exceptions
+                break; // Stop syncing on network exception
             }
         }
         this._isSyncing = false;
-        if (this._snapshotCallbacks) {
-            Object.values(this._snapshotCallbacks).forEach((cb) => cb());
-        }
+        this._notifySnapshotCallbacks('*', 'bulk_update', null);
     }
     _ensureFirestoreSSE() {
         this.connectRealtime();
@@ -394,7 +502,7 @@ class NexaApp {
         this._firestoreListening = true;
         this._sseCallbacks.firestore_changed.push(async (change) => {
             if (change.type === 'bulk_update') {
-                Object.values(this._snapshotCallbacks).forEach((cb) => cb());
+                this._notifySnapshotCallbacks('*', 'bulk_update', null);
                 return;
             }
             if (change.type === 'document_written') {
@@ -403,27 +511,37 @@ class NexaApp {
             else if (change.type === 'document_deleted') {
                 await this._deleteCache(change.docPath);
             }
-            Object.keys(this._snapshotCallbacks).forEach((key) => {
-                const cb = this._snapshotCallbacks[key];
-                const parts = key.split('_');
-                const pathKey = parts.slice(2).join('_');
-                if (pathKey === change.docPath || change.docPath.startsWith(pathKey + '/')) {
-                    cb(change);
-                }
-            });
+            this._notifySnapshotCallbacks(change.docPath, change.type, change.data);
         });
     }
 }
 exports.NexaApp = NexaApp;
 // -----------------------------------------------------------------
-// Modular Firestore-like APIs (Firebase Modular pattern match)
+// Static NexaBase Initialization Helper
+// -----------------------------------------------------------------
+exports.NexaBase = {
+    init: (config) => {
+        const app = new NexaApp(config);
+        if (app.enablePersistence) {
+            app._initPromise = app._initFirestoreState();
+        }
+        return app;
+    },
+    initializeApp: (config) => {
+        return exports.NexaBase.init(config);
+    }
+};
+// -----------------------------------------------------------------
+// Modular Firestore-like APIs (Firebase Modular pattern)
 // -----------------------------------------------------------------
 const initializeApp = (config) => {
-    return new NexaApp(config);
+    return exports.NexaBase.init(config);
 };
 exports.initializeApp = initializeApp;
 const getFirestore = (app) => {
-    app._initPromise = app._initFirestoreState();
+    if (app.enablePersistence) {
+        app._initPromise = app._initFirestoreState();
+    }
     return app;
 };
 exports.getFirestore = getFirestore;
@@ -432,10 +550,15 @@ const collection = (db, collectionPath) => {
 };
 exports.collection = collection;
 const doc = (dbOrCollection, ...pathSegments) => {
+    let docRef;
     if ('type' in dbOrCollection && dbOrCollection.type === 'collection') {
-        return { type: 'document', path: `${dbOrCollection.path}/${pathSegments.join('/')}`, db: dbOrCollection.db };
+        docRef = { type: 'document', path: `${dbOrCollection.path}/${pathSegments.join('/')}`, db: dbOrCollection.db };
     }
-    return { type: 'document', path: pathSegments.join('/'), db: dbOrCollection };
+    else {
+        docRef = { type: 'document', path: pathSegments.join('/'), db: dbOrCollection };
+    }
+    docRef.patch = (data) => (0, exports.patchDoc)(docRef, data);
+    return docRef;
 };
 exports.doc = doc;
 const query = (queryObject, ...queryConstraints) => {
@@ -461,7 +584,7 @@ const limit = (limitValue) => {
     return { type: 'limit', limitValue };
 };
 exports.limit = limit;
-// 1. Helper to retrieve docs from the local Offline cache (Cache-First)
+// Helper to retrieve docs from local cache
 const getCachedDocs = (queryOrCollection) => {
     const db = queryOrCollection.db;
     const collectionPath = queryOrCollection.path;
@@ -480,7 +603,6 @@ const getCachedDocs = (queryOrCollection) => {
             });
         }
     });
-    // Simple offline filters
     let filtered = results;
     for (const c of constraints) {
         if (c.type === 'where' && c.fieldPath && c.opStr) {
@@ -507,11 +629,10 @@ const getCachedDocs = (queryOrCollection) => {
         forEach: (cb) => filtered.forEach(cb),
         empty: filtered.length === 0,
         size: filtered.length,
-        docChanges: () => filtered.map(doc => ({ type: 'added', doc }))
+        docChanges: () => filtered.map((d) => ({ type: 'added', doc: d }))
     };
 };
 exports.getCachedDocs = getCachedDocs;
-// 1. Helper to retrieve single doc from the local Offline cache (Cache-First)
 const getCachedDoc = (docRef) => {
     const db = docRef.db;
     const segments = docRef.path.split('/');
@@ -554,7 +675,7 @@ const getDocs = async (queryOrCollection) => {
             forEach: (cb) => docsArray.forEach(cb),
             empty: docsArray.length === 0,
             size: docsArray.length,
-            docChanges: () => docsArray.map(doc => ({ type: 'added', doc }))
+            docChanges: () => docsArray.map((d) => ({ type: 'added', doc: d }))
         };
     }
     catch (err) {
@@ -590,87 +711,87 @@ const getDoc = async (docRef) => {
     }
 };
 exports.getDoc = getDoc;
-const setDoc = async (docRef, data) => {
+// -----------------------------------------------------------------
+// Atomic Document Mutation APIs with Idempotency & Partial Patching
+// -----------------------------------------------------------------
+const setDoc = async (docRef, data, options) => {
     const db = docRef.db;
     if (db._initPromise)
         await db._initPromise;
     await db._setCache(docRef.path, data);
-    // Trigger snapshot listeners
-    Object.keys(db._snapshotCallbacks).forEach((key) => {
-        const cb = db._snapshotCallbacks[key];
-        const parts = key.split('_');
-        const pathKey = parts.slice(2).join('_');
-        if (pathKey === docRef.path || docRef.path.startsWith(pathKey + '/')) {
-            cb({ type: 'document_written', docPath: docRef.path, data });
-        }
-    });
+    // Broadcast cross-tab and notify snapshot listeners
+    db._broadcastLocalMutation(docRef.path, 'set', data);
+    db._notifySnapshotCallbacks(docRef.path, 'document_written', data);
+    const key = options?.idempotencyKey || generateIdempotencyKey();
     const jobId = Math.random().toString(36).substring(2, 9);
     const isOnline = typeof navigator !== 'undefined' ? navigator.onLine : true;
     if (!isOnline) {
-        await db._addOfflineJob({ id: jobId, type: 'set', path: docRef.path, data });
-        return { success: true, message: 'Offline: Tersimpan di cache lokal IndexedDB' };
+        await db._addOfflineJob({ id: jobId, type: 'set', path: docRef.path, data, idempotencyKey: key });
+        return { success: true, message: 'Offline: Tersimpan di cache lokal' };
     }
     else {
         try {
-            return (await db.client.post(`/api/firestore/${db.projectId}/document`, { docPath: docRef.path, data })).data;
+            return (await db.client.post(`/api/firestore/${db.projectId}/document`, { docPath: docRef.path, data, idempotencyKey: key }, { headers: { 'X-Idempotency-Key': key } })).data;
         }
         catch (error) {
-            await db._addOfflineJob({ id: jobId, type: 'set', path: docRef.path, data });
-            return { success: true, message: 'Koneksi terganggu: Tersimpan di antrean offline IndexedDB' };
+            await db._addOfflineJob({ id: jobId, type: 'set', path: docRef.path, data, idempotencyKey: key });
+            return { success: true, message: 'Koneksi terganggu: Tersimpan di antrean offline' };
         }
     }
 };
 exports.setDoc = setDoc;
-const updateDoc = async (docRef, data) => {
+// Partial Update (UpdateDoc) & Atomic Patch (PatchDoc)
+const patchDoc = async (docRef, data, options) => {
     const db = docRef.db;
     if (db._initPromise)
         await db._initPromise;
-    const jobId = Math.random().toString(36).substring(2, 9);
     const existingData = db._firestoreCache[docRef.path] || {};
     const updatedData = { ...existingData, ...data };
     await db._setCache(docRef.path, updatedData);
+    db._broadcastLocalMutation(docRef.path, 'patch', data);
+    db._notifySnapshotCallbacks(docRef.path, 'document_written', updatedData);
+    const key = options?.idempotencyKey || generateIdempotencyKey();
+    const jobId = Math.random().toString(36).substring(2, 9);
     const isOnline = typeof navigator !== 'undefined' ? navigator.onLine : true;
     if (!isOnline) {
-        await db._addOfflineJob({ id: jobId, type: 'update', path: docRef.path, data });
-        return { success: true, message: 'Offline: Tersimpan di cache lokal IndexedDB' };
+        await db._addOfflineJob({ id: jobId, type: 'patch', path: docRef.path, data, idempotencyKey: key });
+        return { success: true, message: 'Offline: Tersimpan di cache lokal' };
     }
     else {
         try {
-            return (await db.client.patch(`/api/firestore/${db.projectId}/document`, { docPath: docRef.path, data })).data;
+            return (await db.client.patch(`/api/firestore/${db.projectId}/document`, { docPath: docRef.path, data, idempotencyKey: key }, { headers: { 'X-Idempotency-Key': key } })).data;
         }
         catch (error) {
-            await db._addOfflineJob({ id: jobId, type: 'update', path: docRef.path, data });
-            return { success: true, message: 'Koneksi terganggu: Tersimpan di antrean offline IndexedDB' };
+            await db._addOfflineJob({ id: jobId, type: 'patch', path: docRef.path, data, idempotencyKey: key });
+            return { success: true, message: 'Koneksi terganggu: Tersimpan di antrean offline' };
         }
     }
 };
+exports.patchDoc = patchDoc;
+const updateDoc = async (docRef, data, options) => {
+    return (0, exports.patchDoc)(docRef, data, options);
+};
 exports.updateDoc = updateDoc;
-const deleteDoc = async (docRef) => {
+const deleteDoc = async (docRef, options) => {
     const db = docRef.db;
     if (db._initPromise)
         await db._initPromise;
     await db._deleteCache(docRef.path);
-    // Trigger snapshot listeners
-    Object.keys(db._snapshotCallbacks).forEach((key) => {
-        const cb = db._snapshotCallbacks[key];
-        const parts = key.split('_');
-        const pathKey = parts.slice(2).join('_');
-        if (pathKey === docRef.path || docRef.path.startsWith(pathKey + '/')) {
-            cb({ type: 'document_deleted', docPath: docRef.path });
-        }
-    });
+    db._broadcastLocalMutation(docRef.path, 'delete');
+    db._notifySnapshotCallbacks(docRef.path, 'document_deleted', null);
+    const key = options?.idempotencyKey || generateIdempotencyKey();
     const jobId = Math.random().toString(36).substring(2, 9);
     const isOnline = typeof navigator !== 'undefined' ? navigator.onLine : true;
     if (!isOnline) {
-        await db._addOfflineJob({ id: jobId, type: 'delete', path: docRef.path });
+        await db._addOfflineJob({ id: jobId, type: 'delete', path: docRef.path, idempotencyKey: key });
         return { success: true };
     }
     else {
         try {
-            return (await db.client.delete(`/api/firestore/${db.projectId}/document?docPath=${encodeURIComponent(docRef.path)}`)).data;
+            return (await db.client.delete(`/api/firestore/${db.projectId}/document?docPath=${encodeURIComponent(docRef.path)}`, { headers: { 'X-Idempotency-Key': key } })).data;
         }
         catch (error) {
-            await db._addOfflineJob({ id: jobId, type: 'delete', path: docRef.path });
+            await db._addOfflineJob({ id: jobId, type: 'delete', path: docRef.path, idempotencyKey: key });
             return { success: true };
         }
     }
@@ -683,7 +804,7 @@ const onSnapshot = (ref, callback) => {
             await db._initPromise;
         db._ensureFirestoreSSE();
         const pathKey = ref.path;
-        // 1. Native Offline Cache/Persistence Priority: Emits cached snapshot IMMEDIATELY to trigger instant optimistic rendering!
+        // Fast cache emit
         if (ref.type === 'collection' || ref.type === 'query') {
             const cached = (0, exports.getCachedDocs)(ref);
             if (cached && cached.docs.length > 0) {
@@ -702,7 +823,6 @@ const onSnapshot = (ref, callback) => {
                 clearTimeout(debounceTimer);
             debounceTimer = setTimeout(async () => {
                 if (ref.type === 'collection' || ref.type === 'query') {
-                    // Immediately serve from cache for UI responsiveness
                     callback((0, exports.getCachedDocs)(ref));
                     try {
                         const docs = await (0, exports.getDocs)(ref);
@@ -718,9 +838,8 @@ const onSnapshot = (ref, callback) => {
                     }
                     catch (e) { }
                 }
-            }, 800); // Debounce to batch rapid changes (e.g. 500 inserts)
+            }, 50); // Debounce to batch rapid updates
         };
-        // 2. Fetch the latest live server data and update cache + trigger the callback again
         triggerCallback();
         const listenerId = Math.random().toString(36).substring(2, 9);
         db._snapshotCallbacks[`${ref.type}_${listenerId}_${pathKey}`] = triggerCallback;
@@ -735,13 +854,14 @@ const onSnapshot = (ref, callback) => {
     return () => unsubscribe();
 };
 exports.onSnapshot = onSnapshot;
-// Supporting standard Firebase modular options functions
 const enableIndexedDbPersistence = async (db) => {
+    db.enablePersistence = true;
     if (db._initPromise)
         await db._initPromise;
 };
 exports.enableIndexedDbPersistence = enableIndexedDbPersistence;
 const enableOfflinePersistence = async (db) => {
+    db.enablePersistence = true;
     if (db._initPromise)
         await db._initPromise;
 };
@@ -757,6 +877,10 @@ const writeBatch = (db) => {
             operations.push({ type: 'update', path: docRef.path, data });
             return batchObj;
         },
+        patch: (docRef, data) => {
+            operations.push({ type: 'update', path: docRef.path, data });
+            return batchObj;
+        },
         delete: (docRef) => {
             operations.push({ type: 'delete', path: docRef.path });
             return batchObj;
@@ -766,31 +890,20 @@ const writeBatch = (db) => {
                 await db._initPromise;
             if (operations.length === 0)
                 return;
+            const idempotencyKey = generateIdempotencyKey();
             const isOnline = typeof navigator !== 'undefined' ? navigator.onLine : true;
             // Update local cache optimistically
             for (const op of operations) {
                 if (op.type === 'set' || op.type === 'update') {
                     const newData = { ...db._firestoreCache[op.path], ...op.data };
                     await db._setCache(op.path, newData);
-                    Object.keys(db._snapshotCallbacks).forEach((key) => {
-                        const cb = db._snapshotCallbacks[key];
-                        const parts = key.split('_');
-                        const pathKey = parts.slice(2).join('_');
-                        if (pathKey === op.path || op.path.startsWith(pathKey + '/')) {
-                            cb({ type: 'document_written', docPath: op.path, data: db._firestoreCache[op.path] });
-                        }
-                    });
+                    db._broadcastLocalMutation(op.path, op.type === 'set' ? 'set' : 'patch', op.data);
+                    db._notifySnapshotCallbacks(op.path, 'document_written', db._firestoreCache[op.path]);
                 }
                 else if (op.type === 'delete') {
                     await db._deleteCache(op.path);
-                    Object.keys(db._snapshotCallbacks).forEach((key) => {
-                        const cb = db._snapshotCallbacks[key];
-                        const parts = key.split('_');
-                        const pathKey = parts.slice(2).join('_');
-                        if (pathKey === op.path || op.path.startsWith(pathKey + '/')) {
-                            cb({ type: 'document_deleted', docPath: op.path });
-                        }
-                    });
+                    db._broadcastLocalMutation(op.path, 'delete');
+                    db._notifySnapshotCallbacks(op.path, 'document_deleted', null);
                 }
             }
             if (!isOnline) {
@@ -799,14 +912,15 @@ const writeBatch = (db) => {
                         id: Math.random().toString(36).substring(2, 9),
                         type: op.type,
                         path: op.path,
-                        data: op.data
+                        data: op.data,
+                        idempotencyKey
                     });
                 }
                 return { success: true, message: 'Offline: Batch operations queued in IndexedDB' };
             }
             else {
                 try {
-                    return (await db.client.post(`/api/firestore/${db.projectId}/batch`, { operations })).data;
+                    return (await db.client.post(`/api/firestore/${db.projectId}/batch`, { operations, idempotencyKey }, { headers: { 'X-Idempotency-Key': idempotencyKey } })).data;
                 }
                 catch (error) {
                     for (const op of operations) {
@@ -814,10 +928,11 @@ const writeBatch = (db) => {
                             id: Math.random().toString(36).substring(2, 9),
                             type: op.type,
                             path: op.path,
-                            data: op.data
+                            data: op.data,
+                            idempotencyKey
                         });
                     }
-                    return { success: true, message: 'Koneksi terganggu: Tersimpan di antrean offline IndexedDB' };
+                    return { success: true, message: 'Koneksi terganggu: Tersimpan di antrean offline' };
                 }
             }
         }
@@ -834,6 +949,7 @@ const runTransaction = async (db, updateFunction, options) => {
         attempt++;
         const reads = [];
         const operations = [];
+        const idempotencyKey = generateIdempotencyKey();
         const transaction = {
             get: async (docRef) => {
                 const segments = docRef.path.split('/');
@@ -856,6 +972,10 @@ const runTransaction = async (db, updateFunction, options) => {
                 operations.push({ type: 'update', path: docRef.path, data });
                 return transaction;
             },
+            patch: (docRef, data) => {
+                operations.push({ type: 'update', path: docRef.path, data });
+                return transaction;
+            },
             delete: (docRef) => {
                 operations.push({ type: 'delete', path: docRef.path });
                 return transaction;
@@ -864,34 +984,19 @@ const runTransaction = async (db, updateFunction, options) => {
         try {
             const result = await updateFunction(transaction);
             if (operations.length > 0 || reads.length > 0) {
-                await db.client.post(`/api/firestore/${db.projectId}/transaction`, {
-                    reads,
-                    operations
-                });
+                await db.client.post(`/api/firestore/${db.projectId}/transaction`, { reads, operations, idempotencyKey }, { headers: { 'X-Idempotency-Key': idempotencyKey } });
             }
             for (const op of operations) {
                 if (op.type === 'set' || op.type === 'update') {
                     const newData = { ...db._firestoreCache[op.path], ...op.data };
                     await db._setCache(op.path, newData);
-                    Object.keys(db._snapshotCallbacks).forEach((key) => {
-                        const cb = db._snapshotCallbacks[key];
-                        const parts = key.split('_');
-                        const pathKey = parts.slice(2).join('_');
-                        if (pathKey === op.path || op.path.startsWith(pathKey + '/')) {
-                            cb({ type: 'document_written', docPath: op.path, data: db._firestoreCache[op.path] });
-                        }
-                    });
+                    db._broadcastLocalMutation(op.path, op.type === 'set' ? 'set' : 'patch', op.data);
+                    db._notifySnapshotCallbacks(op.path, 'document_written', db._firestoreCache[op.path]);
                 }
                 else if (op.type === 'delete') {
                     await db._deleteCache(op.path);
-                    Object.keys(db._snapshotCallbacks).forEach((key) => {
-                        const cb = db._snapshotCallbacks[key];
-                        const parts = key.split('_');
-                        const pathKey = parts.slice(2).join('_');
-                        if (pathKey === op.path || op.path.startsWith(pathKey + '/')) {
-                            cb({ type: 'document_deleted', docPath: op.path });
-                        }
-                    });
+                    db._broadcastLocalMutation(op.path, 'delete');
+                    db._notifySnapshotCallbacks(op.path, 'document_deleted', null);
                 }
             }
             return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexabase-console",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "SDK Client resmi untuk NexaBase: Platform Sinkronisasi NoSQL, Realtime, File Storage, & Autentikasi Offline-First.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",