nexabase-console 1.0.6 → 1.1.0

package/README.md

@@ -7,8 +7,9 @@ SDK Client Resmi untuk **NexaBase**: Platform sinkronisasi database modern yang
 ## 🚀 Fitur Utama
 
 -   **⚡ Real-Time Synchronization**: Sinkronisasi data real-time dengan latency rendah menggunakan Server-Sent Events (SSE).
+-   **🔒 Concurrency Control & Transactions (`runTransaction`)**: Transaksi dua arah (Read-Before-Write) atomik dengan kontrol konkurensi (Optimistic Locking & Automatic Retry) untuk mencegah race conditions pada pemotongan stok, kuota, atau transaksi finansial.
 -   **📦 Offline-First & Auto-Sync**: Sinkronisasi state lokal secara otomatis menggunakan **IndexedDB**. Data tetap tersimpan di browser jika koneksi terputus dan akan disinkronkan ke server secara otomatis saat kembali online.
--   **🔥 Modular Firestore API**: Desain API modular modern mirip Firebase SDK (v9+) sehingga sangat mudah dipelajari.
+-   **🔥 Modular Firestore API & TypeScript Generics**: Desain API modular modern mirip Firebase SDK (v9+) dengan dukungan penuh parameter tipe generik (TypeScript Generics) untuk menjamin tipe data yang aman (type-safe) secara end-to-end.
 -   **🔑 Secure Auth & Passwordless OTP**: Dukungan penuh registrasi, login email/sandi, serta OTP instan via SMTP yang aman.
 -   **📂 File Storage Integration**: Unggah aset media dan file blob ke cloud storage dengan satu perintah.
 
@@ -109,24 +110,80 @@ const listenLive = () => {
 };
 ```
 
-#### Menggunakan Atomic Write Batch
+#### 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).
+
 ```javascript
 import { doc, writeBatch } from 'nexabase-console';
 
-const executeBatch = async () => {
+const executeBulkUpload = async (listResi) => {
   const batch = writeBatch(db);
   
-  const ref1 = doc(db, 'products', 'prod_a');
-  const ref2 = doc(db, 'products', 'prod_b');
-  
-  batch.set(ref1, { name: 'Sandal Kulit', price: 75000 });
-  batch.set(ref2, { name: 'Sepatu Kulit', price: 250000 });
+  // ListResi adalah array berisi objek resi. Maksimal 500 per batch.
+  listResi.forEach((resi) => {
+    // Referensi dokumen
+    const docRef = doc(db, 'resi', resi.nomor_resi);
+    batch.set(docRef, resi);
+  });
   
+  // Eksekusi semua secara atomik (bersamaan dalam 1 request)
   const result = await batch.commit();
-  console.log("Semua operasi batch berhasil di-commit secara atomik.");
+  console.log(`Berhasil mengunggah ${listResi.length} resi secara massal.`);
 };
 ```
 
+#### Menggunakan Transactions (`runTransaction`) — Concurrency Control
+```javascript
+import { doc, runTransaction } from 'nexabase-console';
+
+async function potongStokAman(productId, variantId, qtyBeli) {
+  const productRef = doc(db, 'products', productId);
+
+  try {
+    const hasil = await runTransaction(db, async (transaction) => {
+      // 1. Baca dokumen di dalam transaksi (Read)
+      const productSnap = await transaction.get(productRef);
+      if (!productSnap.exists()) {
+        throw new Error("Produk tidak ditemukan!");
+      }
+
+      const productData = productSnap.data();
+      const variantIndex = productData.variants?.findIndex((v) => v.id === variantId);
+      if (variantIndex === -1 || variantIndex === undefined) {
+        throw new Error("Varian produk tidak ditemukan!");
+      }
+
+      const variant = productData.variants[variantIndex];
+      const stokSaatIni = variant.stock;
+
+      // 2. Validasi stok sebelum dipotong
+      if (stokSaatIni < qtyBeli) {
+        throw new Error(`Stok tidak mencukupi! Tersedia: ${stokSaatIni}, Diminta: ${qtyBeli}`);
+      }
+
+      // 3. Kalkulasi data baru
+      const updatedVariants = [...productData.variants];
+      updatedVariants[variantIndex] = {
+        ...variant,
+        stock: stokSaatIni - qtyBeli
+      };
+
+      // 4. Tulis perubahan di dalam transaksi (Write)
+      transaction.update(productRef, {
+        variants: updatedVariants,
+        updatedAt: new Date().toISOString()
+      });
+
+      return { success: true, sisaStok: stokSaatIni - qtyBeli };
+    });
+
+    console.log("Transaksi Berhasil!", hasil);
+  } catch (error) {
+    console.error("Transaksi Gagal / Conflict:", error.message);
+  }
+}
+```
+
 ---
 
 ### 3. Autentikasi Pengguna & OTP Tanpa Sandi
@@ -185,6 +242,51 @@ const uploadImage = async (fileBlob) => {
 
 ---
 
+### 5. Keamanan Tipe TypeScript (Generics) & Kueri Lanjutan
+
+#### Dukungan TypeScript Generics
+Kini Anda bisa mendefinisikan tipe data struktur dokumen Anda agar penulisan dan pembacaan data sepenuhnya aman (Type-safe).
+
+```typescript
+import { collection, doc, getDoc, getDocs } from 'nexabase-console';
+
+interface Product {
+  name: string;
+  price: number;
+  stock: number;
+  tags: string[];
+}
+
+// 1. Definisikan tipe koleksi
+const productsCol = collection<Product>(db, 'products');
+
+// 2. Definisikan tipe referensi dokumen
+const productRef = doc<Product>(db, 'products', 'prod_a');
+
+// 3. Baca data dengan Autocomplete & Type Checking penuh
+const snapshot = await getDoc(productRef);
+if (snapshot.exists()) {
+  const data = snapshot.data(); // Tipe data otomatis terdeteksi sebagai 'Product'
+  console.log(data.name);  // Aman! Autocomplete tersedia
+  console.log(data.price); // Aman!
+}
+```
+
+#### Kompatibilitas QuerySnapshot (`docChanges()`)
+Bagi Anda yang bermigrasi dari Firebase, objek `QuerySnapshot` yang dikembalikan oleh `getDocs` atau `onSnapshot` kini mendukung metode `.docChanges()` secara native:
+
+```typescript
+const snapshot = await getDocs(productsCol);
+const changes = snapshot.docChanges(); // Mengembalikan array perubahan dokumen
+```
+
+#### Filter Offline Lengkap (Advanced Querying Operators)
+Mekanisme kueri offline pada SDK NexaBase kini mendukung operator Firestore tingkat lanjut secara penuh demi keandalan luar biasa bahkan saat koneksi terputus:
+- Operator dasar: `==`, `!=`, `>`, `<`, `>=`, `<=`
+- Operator array & keanggotaan: `in`, `not-in`, `array-contains`, `array-contains-any`
+
+---
+
 ## 🗄️ Dukungan Sinkronisasi Offline (IndexedDB)
 
 NexaBase JS SDK dikembangkan dengan arsitektur **Offline-First**. 

package/dist/index.d.ts

@@ -58,16 +58,29 @@ export interface QuerySnapshot<T = any> {
     docChanges: () => any[];
 }
 export interface DatabaseReference {
+    path: string;
     get: () => Promise<any>;
     set: (data: any) => Promise<any>;
-    onDataChanged: (callback: (data: any) => void) => void;
+    update: (data: any) => Promise<any>;
+    delete: () => Promise<any>;
+    remove: () => Promise<any>;
+    onDataChanged: (callback: (data: any) => void) => () => void;
+}
+export interface UploadOptions {
+    contextType?: 'chat' | 'public_post';
+    contextId?: string;
+    fileId?: string;
 }
 export interface StorageReference {
     name: string;
     fullPath: string;
-    put: (file: File | Blob, onProgress?: (percent: number) => void) => Promise<{
+    put: (file: File | Blob, options?: UploadOptions | ((percent: number) => void), onProgress?: (percent: number) => void) => Promise<{
         url: string;
         success: boolean;
+        fileId?: string;
+        proxyViewUrl?: string;
+        proxyDownloadUrl?: string;
+        metadata?: any;
     }>;
     delete: () => Promise<{
         success: boolean;

package/dist/index.js

@@ -85,25 +85,50 @@ class NexaApp {
     // -----------------------------------------------------------------
     database() {
         return {
-            ref: (path = '') => ({
-                get: async () => {
-                    const response = await this.client.get(`/api/db/${this.projectId}/${path}`);
-                    return response.data;
-                },
-                set: async (data) => {
-                    const payload = data instanceof Map ? Object.fromEntries(data) : data;
-                    const response = await this.client.put(`/api/db/${this.projectId}/${path}`, payload);
-                    return response.data;
-                },
-                onDataChanged: (callback) => {
-                    this.connectRealtime();
-                    this._sseCallbacks.data_changed.push((payload) => {
-                        if (payload.path === path || payload.path === '/' + path) {
-                            callback(payload.data);
-                        }
-                    });
-                }
-            })
+            ref: (path = '') => {
+                const cleanPath = (path || '').replace(/^\/+|\/+$/g, '');
+                return {
+                    path: cleanPath,
+                    get: async () => {
+                        const response = await this.client.get(`/api/db/${this.projectId}/${cleanPath}`);
+                        return response.data;
+                    },
+                    set: async (data) => {
+                        const payload = data instanceof Map ? Object.fromEntries(data) : data;
+                        const response = await this.client.put(`/api/db/${this.projectId}/${cleanPath}`, payload);
+                        return response.data;
+                    },
+                    update: async (data) => {
+                        const payload = data instanceof Map ? Object.fromEntries(data) : data;
+                        const response = await this.client.patch(`/api/db/${this.projectId}/${cleanPath}`, payload);
+                        return response.data;
+                    },
+                    delete: async () => {
+                        const response = await this.client.put(`/api/db/${this.projectId}/${cleanPath}`, null);
+                        return response.data;
+                    },
+                    remove: async () => {
+                        const response = await this.client.put(`/api/db/${this.projectId}/${cleanPath}`, null);
+                        return response.data;
+                    },
+                    onDataChanged: (callback) => {
+                        this.connectRealtime();
+                        const handler = (payload) => {
+                            const payloadPath = (payload.path || '').replace(/^\/+|\/+$/g, '');
+                            if (payloadPath === cleanPath ||
+                                payloadPath.startsWith(cleanPath + '/') ||
+                                cleanPath === '' ||
+                                cleanPath.startsWith(payloadPath + '/')) {
+                                callback(payload.data);
+                            }
+                        };
+                        this._sseCallbacks.data_changed.push(handler);
+                        return () => {
+                            this._sseCallbacks.data_changed = this._sseCallbacks.data_changed.filter((cb) => cb !== handler);
+                        };
+                    }
+                };
+            }
         };
     }
     // -----------------------------------------------------------------
@@ -167,19 +192,43 @@ class NexaApp {
                 return {
                     name,
                     fullPath: path,
-                    put: async (file, onProgress) => {
+                    put: async (file, options, onProgress) => {
+                        let actualOptions = {};
+                        let actualOnProgress = onProgress;
+                        if (typeof options === 'function') {
+                            actualOnProgress = options;
+                        }
+                        else if (options && typeof options === 'object') {
+                            actualOptions = options;
+                        }
                         const formData = new FormData();
                         formData.append('file', file);
+                        if (actualOptions.contextType) {
+                            formData.append('contextType', actualOptions.contextType);
+                        }
+                        if (actualOptions.contextId) {
+                            formData.append('contextId', actualOptions.contextId);
+                        }
+                        if (actualOptions.fileId) {
+                            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 (onProgress && progressEvent.total) {
+                                if (actualOnProgress && progressEvent.total) {
                                     const percent = Math.round((progressEvent.loaded * 100) / progressEvent.total);
-                                    onProgress(percent);
+                                    actualOnProgress(percent);
                                 }
                             }
                         });
-                        return response.data;
+                        return {
+                            url: response.data.url,
+                            success: true,
+                            fileId: response.data.fileId,
+                            proxyViewUrl: response.data.proxyViewUrl,
+                            proxyDownloadUrl: response.data.proxyDownloadUrl,
+                            metadata: response.data.metadata
+                        };
                     },
                     delete: async () => {
                         const response = await this.client.delete(`/api/project/${this.projectId}/storage/${encodeURIComponent(name)}`);
@@ -647,15 +696,29 @@ const onSnapshot = (ref, callback) => {
                 callback(cached);
             }
         }
-        const triggerCallback = async () => {
-            if (ref.type === 'collection' || ref.type === 'query') {
-                const docs = await (0, exports.getDocs)(ref);
-                callback(docs);
-            }
-            else {
-                const docData = await (0, exports.getDoc)(ref);
-                callback(docData);
-            }
+        let debounceTimer = null;
+        const triggerCallback = () => {
+            if (debounceTimer)
+                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);
+                        callback(docs);
+                    }
+                    catch (e) { }
+                }
+                else {
+                    callback((0, exports.getCachedDoc)(ref));
+                    try {
+                        const docData = await (0, exports.getDoc)(ref);
+                        callback(docData);
+                    }
+                    catch (e) { }
+                }
+            }, 800); // Debounce to batch rapid changes (e.g. 500 inserts)
         };
         // 2. Fetch the latest live server data and update cache + trigger the callback again
         triggerCallback();

package/package.json

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