nexabase-console 1.0.7 → 1.1.1

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,82 @@ const listenLive = () => {
 };
 ```
 
-#### Menggunakan Atomic Write Batch
+#### 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';
 
-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 +244,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.js

@@ -696,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) { }
+                }
+            }, 50); // Debounce to batch rapid changes (fast enough for manual scans)
         };
         // 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.7",
+  "version": "1.1.1",
   "description": "SDK Client resmi untuk NexaBase: Platform Sinkronisasi NoSQL, Realtime, File Storage, & Autentikasi Offline-First.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",