@techfinityedge/koolbase-react-native 3.0.0 → 4.0.0

package/README.md

@@ -16,9 +16,13 @@ Auth, database, storage, realtime, functions, feature flags, remote config, vers
 3. Add the SDK:
 
 ```bash
-npm install @techfinityedge/koolbase-react-native@^3.0.0
+npm install @techfinityedge/koolbase-react-native
 # or
-yarn add @techfinityedge/koolbase-react-native@^3.0.0
+yarn add @techfinityedge/koolbase-react-native
+# or
+pnpm add @techfinityedge/koolbase-react-native
+# or
+bun add @techfinityedge/koolbase-react-native
 ```
 
 **4. Initialize at app startup:**
@@ -215,6 +219,8 @@ const deleted = await Koolbase.db.deleteWhere('sessions', {
 > A non-empty filter is required. The collection's delete rule applies; for
 > `owner`/`scoped` rules the delete is scoped to your own records. Online-only.
 
+---
+
 ### Offline-first
 
 ```typescript
@@ -224,6 +230,53 @@ if (isFromCache) console.log('Served from local cache');
 await Koolbase.db.syncPendingWrites();
 ```
 
+### Atomic batch writes
+
+Run multiple writes in a single server-side transaction. All operations commit together or none are applied — any failure rolls back the entire batch.
+
+```ts
+import { Koolbase, BatchOp } from '@techfinityedge/koolbase-react-native';
+
+const results = await Koolbase.db.batch([
+  BatchOp.insert('orders', { total: 50, customer_id: customerId }),
+  BatchOp.update(inventoryId, { stock: 9 }),
+  BatchOp.upsert('counters', {
+    match: { name: 'orders' },
+    data: { value: 1 },
+  }),
+  BatchOp.delete(cartItemId),
+]);
+
+// results[i] corresponds to operations[i]:
+//   - insert / update: { type, record }
+//   - upsert:          { type, record, created }   // created = true if inserted
+//   - delete:          { type, deleted: true }
+```
+
+**Online-only by design.** Atomicity needs the server's authoritative view, so `batch()` is never queued offline — it throws on network failure (like `upsert` and `deleteWhere`). A server-side rejection throws a `KoolbaseDataException` with the failing operation's details; nothing was persisted.
+
+---
+
+### Handling write conflicts
+
+`insert`, `update`, and `upsert` are online-first: when the server is reachable they throw a typed error on rejection. Catch `KoolbaseConflictError` to handle unique-constraint violations (e.g. a duplicate email):
+
+```ts
+import { KoolbaseConflictError } from '@techfinityedge/koolbase-react-native';
+
+try {
+  await Koolbase.db.insert('users', { email, name });
+} catch (e) {
+  if (e instanceof KoolbaseConflictError) {
+    showError(`That ${e.field ?? 'value'} is already in use.`);
+  } else {
+    throw e;
+  }
+}
+```
+
+When the device is offline, these writes are queued and synced automatically when connectivity returns.
+
 ---
 
 ## Storage

package/dist/database-errors.d.ts

@@ -20,10 +20,11 @@ export declare class KoolbaseDataError extends Error {
  * (`details.field`) — useful when a collection has more than one unique
  * constraint and you need to know which value clashed.
  *
- * Currently surfaced by `upsert` (the online-only write). `insert` and
- * `update` are optimistic/offline-first: they accept the write locally and
- * sync in the background, so a constraint conflict on those paths is a
- * sync-time concern rather than a thrown error.
+ * Surfaced by `insert`, `update`, and `upsert` whenever the server is
+ * reachable and rejects the write with a 409. These writes are online-first:
+ * a server-side conflict throws immediately. Only a genuine network failure
+ * falls back to the offline queue, where a conflict that surfaces at sync
+ * time is handled by the sync engine rather than thrown here.
  *
  * @example
  * try {

package/dist/database-errors.js

@@ -29,10 +29,11 @@ exports.KoolbaseDataError = KoolbaseDataError;
  * (`details.field`) — useful when a collection has more than one unique
  * constraint and you need to know which value clashed.
  *
- * Currently surfaced by `upsert` (the online-only write). `insert` and
- * `update` are optimistic/offline-first: they accept the write locally and
- * sync in the background, so a constraint conflict on those paths is a
- * sync-time concern rather than a thrown error.
+ * Surfaced by `insert`, `update`, and `upsert` whenever the server is
+ * reachable and rejects the write with a 409. These writes are online-first:
+ * a server-side conflict throws immediately. Only a genuine network failure
+ * falls back to the offline queue, where a conflict that surfaces at sync
+ * time is handled by the sync engine rather than thrown here.
  *
  * @example
  * try {

package/dist/database.d.ts

@@ -1,4 +1,4 @@
-import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult } from './types';
+import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult, BatchOp, BatchResult } from './types';
 export declare class KoolbaseDatabase {
     private config;
     private getUserId;
@@ -9,6 +9,18 @@ export declare class KoolbaseDatabase {
     private request;
     private runQuery;
     query(collection: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Insert a new record into a collection.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, validation error, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass — `insert` now throws `KoolbaseConflictError`
+     * with the offending field on a 409, matching `upsert` and `update`.
+     *
+     * On genuine network failure (server unreachable, timeout) the write is
+     * accepted optimistically: saved to the local cache and queued for sync
+     * when connectivity returns.
+     */
     insert(collection: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
     /**
      * Insert a record, or update the existing one matching `match`.
@@ -38,7 +50,44 @@ export declare class KoolbaseDatabase {
      * The collection cache is invalidated on success.
      */
     deleteWhere(collection: string, filters: Record<string, unknown>): Promise<number>;
+    /**
+     * Run multiple writes as a single atomic transaction.
+     *
+     * All `operations` commit together or none are applied — the server runs
+     * them in one database transaction and rolls back entirely on any failure.
+     * Operations apply in order and may span multiple collections.
+     *
+     * Online-only by design (like `upsert` and `deleteWhere`): atomicity needs
+     * the server's authoritative view, so a batch is never queued offline — it
+     * throws on network failure. A server-side rejection throws a
+     * `KoolbaseDataException` whose message identifies which operation failed;
+     * nothing was persisted.
+     *
+     * Returns one `BatchResult` per operation, in order.
+     *
+     * @example
+     * const results = await Koolbase.db.batch([
+     *   BatchOp.insert('orders', { total: 50 }),
+     *   BatchOp.update(inventoryId, { stock: 9 }),
+     *   BatchOp.upsert('counters', { match: { name: 'orders' }, data: { value: 1 } }),
+     *   BatchOp.delete(cartItemId),
+     * ]);
+     */
+    batch(operations: BatchOp[]): Promise<BatchResult[]>;
     get(recordId: string): Promise<KoolbaseRecord>;
+    /**
+     * Update a record's fields by id.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, not found, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass. An update that would violate a unique
+     * constraint now throws `KoolbaseConflictError` with the offending field —
+     * same shape as `insert` and `upsert`.
+     *
+     * On genuine network failure the update is queued for sync and a partial
+     * optimistic record is returned so the UI can re-render the new fields
+     * immediately.
+     */
     update(recordId: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
     delete(recordId: string): Promise<void>;
     syncPendingWrites(): Promise<void>;

package/dist/database.js

@@ -8,6 +8,23 @@ const database_errors_1 = require("./database-errors");
 function generateId() {
     return 'local_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
 }
+function batchOpToWire(op) {
+    switch (op.type) {
+        case 'insert':
+            return { type: 'insert', collection: op.collection, data: op.data };
+        case 'update':
+            return { type: 'update', record_id: op.recordId, data: op.data };
+        case 'delete':
+            return { type: 'delete', record_id: op.recordId };
+        case 'upsert':
+            return {
+                type: 'upsert',
+                collection: op.collection,
+                match: op.match,
+                data: op.data,
+            };
+    }
+}
 class KoolbaseDatabase {
     constructor(config, getUserId, getToken) {
         this.config = config;
@@ -67,39 +84,56 @@ class KoolbaseDatabase {
         await (0, cache_store_1.setCached)(userId, collection, queryHash, result);
         return { ...result, isFromCache: false };
     }
-    // ─── Insert (optimistic) ────────────────────────────────────────────────────
+    // ─── Insert (online-first with offline fallback) ───────────────────────────
+    /**
+     * Insert a new record into a collection.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, validation error, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass — `insert` now throws `KoolbaseConflictError`
+     * with the offending field on a 409, matching `upsert` and `update`.
+     *
+     * On genuine network failure (server unreachable, timeout) the write is
+     * accepted optimistically: saved to the local cache and queued for sync
+     * when connectivity returns.
+     */
     async insert(collection, data) {
         const userId = this.getUserId() ?? 'anonymous';
-        // Build optimistic record
-        const optimisticRecord = {
-            id: generateId(),
-            createdBy: userId,
-            data,
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-        };
-        // Write to local cache immediately
-        await (0, cache_store_1.optimisticallyInsert)(userId, collection, optimisticRecord);
-        // Add to write queue
-        await (0, cache_store_1.addToWriteQueue)(userId, {
-            id: generateId(),
-            type: 'insert',
-            collection,
-            data,
-        });
-        // Try network in background
-        this.request('POST', '/v1/sdk/db/insert', {
-            collection,
-            data,
-        })
-            .then(async (serverRecord) => {
-            // Invalidate cache so next query gets real data
+        try {
+            // Online path: await the server and return the authoritative record
+            // (with the server-assigned id). Refresh the collection cache so the
+            // next query sees real data instead of a stale optimistic copy.
+            const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
+            const record = (0, record_1.recordFromWire)(raw);
             await (0, cache_store_1.invalidateCache)(userId, collection);
-        })
-            .catch(() => {
-            // Will sync when online via SyncEngine
-        });
-        return optimisticRecord;
+            return record;
+        }
+        catch (e) {
+            // Server-reachable rejection: the server saw the request and refused.
+            // Surface to the caller without writing optimistic state or queuing —
+            // the server has already decided it will not accept this write, and
+            // queuing it would just spin SyncEngine until max retries.
+            if (e instanceof database_errors_1.KoolbaseDataError)
+                throw e;
+            // Genuine network failure → offline path: save to local cache and
+            // queue for SyncEngine to retry when online. Return the optimistic
+            // record so the UI has something to render in the meantime.
+            const optimisticRecord = {
+                id: generateId(),
+                createdBy: userId,
+                data,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            };
+            await (0, cache_store_1.optimisticallyInsert)(userId, collection, optimisticRecord);
+            await (0, cache_store_1.addToWriteQueue)(userId, {
+                id: generateId(),
+                type: 'insert',
+                collection,
+                data,
+            });
+            return optimisticRecord;
+        }
     }
     // ─── Upsert (online-only) ─────────────────────────────────────────────────
     /**
@@ -160,25 +194,108 @@ class KoolbaseDatabase {
         await (0, cache_store_1.invalidateCache)(userId, collection);
         return body.deleted ?? 0;
     }
+    // ─── Batch (atomic, online-only) ────────────────────────────────────────────
+    /**
+     * Run multiple writes as a single atomic transaction.
+     *
+     * All `operations` commit together or none are applied — the server runs
+     * them in one database transaction and rolls back entirely on any failure.
+     * Operations apply in order and may span multiple collections.
+     *
+     * Online-only by design (like `upsert` and `deleteWhere`): atomicity needs
+     * the server's authoritative view, so a batch is never queued offline — it
+     * throws on network failure. A server-side rejection throws a
+     * `KoolbaseDataException` whose message identifies which operation failed;
+     * nothing was persisted.
+     *
+     * Returns one `BatchResult` per operation, in order.
+     *
+     * @example
+     * const results = await Koolbase.db.batch([
+     *   BatchOp.insert('orders', { total: 50 }),
+     *   BatchOp.update(inventoryId, { stock: 9 }),
+     *   BatchOp.upsert('counters', { match: { name: 'orders' }, data: { value: 1 } }),
+     *   BatchOp.delete(cartItemId),
+     * ]);
+     */
+    async batch(operations) {
+        if (operations.length === 0) {
+            throw new Error('batch requires at least one operation');
+        }
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/batch`, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+            body: JSON.stringify({
+                operations: operations.map(batchOpToWire),
+            }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+            throw (0, database_errors_1.koolbaseDataError)(res.status, body, `Batch failed: ${res.status}`);
+        }
+        const results = (body.results ?? []).map(r => ({
+            type: r.type ?? '',
+            record: r.record
+                ? (0, record_1.recordFromWire)(r.record)
+                : undefined,
+            created: r.created,
+            deleted: r.deleted ?? false,
+        }));
+        // Keep the cache consistent with what committed. Insert/upsert carry the
+        // collection in the input op; update/delete address records by id, so we
+        // don't know the collection at this layer — those refresh naturally on
+        // the next query for the affected collection.
+        const userId = this.getUserId() ?? 'anonymous';
+        const touched = new Set();
+        for (const op of operations) {
+            if (op.type === 'insert' || op.type === 'upsert') {
+                touched.add(op.collection);
+            }
+        }
+        for (const col of touched) {
+            await (0, cache_store_1.invalidateCache)(userId, col);
+        }
+        return results;
+    }
+    // ─── Get single record ──────────────────────────────────────────────────────
     // ─── Get single record ──────────────────────────────────────────────────────
     async get(recordId) {
         const raw = await this.request('GET', `/v1/sdk/db/records/${recordId}`);
         return (0, record_1.recordFromWire)(raw);
     }
-    // ─── Update ─────────────────────────────────────────────────────────────────
+    // ─── Update (online-first with offline fallback) ───────────────────────────
+    /**
+     * Update a record's fields by id.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, not found, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass. An update that would violate a unique
+     * constraint now throws `KoolbaseConflictError` with the offending field —
+     * same shape as `insert` and `upsert`.
+     *
+     * On genuine network failure the update is queued for sync and a partial
+     * optimistic record is returned so the UI can re-render the new fields
+     * immediately.
+     */
     async update(recordId, data) {
         const userId = this.getUserId() ?? 'anonymous';
-        await (0, cache_store_1.addToWriteQueue)(userId, {
-            id: generateId(),
-            type: 'update',
-            recordId,
-            data,
-        });
         try {
             const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
             return (0, record_1.recordFromWire)(raw);
         }
-        catch {
+        catch (e) {
+            // Server-reachable rejection: surface to caller without queuing — the
+            // server already refused the write and will refuse it again on retry.
+            if (e instanceof database_errors_1.KoolbaseDataError)
+                throw e;
+            // Genuine network failure → queue for sync and return an optimistic
+            // partial record so the UI reflects the update immediately.
+            await (0, cache_store_1.addToWriteQueue)(userId, {
+                id: generateId(),
+                type: 'update',
+                recordId,
+                data,
+            });
             return {
                 id: recordId,
                 data,

package/dist/types.d.ts

@@ -243,3 +243,42 @@ export interface SignInWithGoogleParams {
     idToken: string;
     nonce?: string;
 }
+export type BatchOp = {
+    type: 'insert';
+    collection: string;
+    data: Record<string, unknown>;
+} | {
+    type: 'update';
+    recordId: string;
+    data: Record<string, unknown>;
+} | {
+    type: 'delete';
+    recordId: string;
+} | {
+    type: 'upsert';
+    collection: string;
+    match: Record<string, unknown>;
+    data: Record<string, unknown>;
+};
+/**
+ * Factory helpers for constructing batch operations. Same shape as
+ * Flutter's `KoolbaseBatchOp.insert(...)` etc., so the mental model
+ * transfers between platforms.
+ */
+export declare const BatchOp: {
+    insert: (collection: string, data: Record<string, unknown>) => BatchOp;
+    update: (recordId: string, data: Record<string, unknown>) => BatchOp;
+    delete: (recordId: string) => BatchOp;
+    upsert: (collection: string, opts: {
+        match: Record<string, unknown>;
+        data: Record<string, unknown>;
+    }) => BatchOp;
+};
+export interface BatchResult {
+    type: string;
+    record?: KoolbaseRecord;
+    /** For upsert: true if a new record was inserted, false if one was updated. */
+    created?: boolean;
+    /** True for a successful delete. */
+    deleted?: boolean;
+}

package/dist/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FunctionRuntime = exports.RestoreResult = void 0;
+exports.BatchOp = exports.FunctionRuntime = exports.RestoreResult = void 0;
 /**
  * Result of KoolbaseAuth.restoreSession(). Apps should branch on this:
  * - NoSession  → show login screen
@@ -22,3 +22,19 @@ var FunctionRuntime;
     FunctionRuntime["Deno"] = "deno";
     FunctionRuntime["Dart"] = "dart";
 })(FunctionRuntime || (exports.FunctionRuntime = FunctionRuntime = {}));
+/**
+ * Factory helpers for constructing batch operations. Same shape as
+ * Flutter's `KoolbaseBatchOp.insert(...)` etc., so the mental model
+ * transfers between platforms.
+ */
+exports.BatchOp = {
+    insert: (collection, data) => ({ type: 'insert', collection, data }),
+    update: (recordId, data) => ({ type: 'update', recordId, data }),
+    delete: (recordId) => ({ type: 'delete', recordId }),
+    upsert: (collection, opts) => ({
+        type: 'upsert',
+        collection,
+        match: opts.match,
+        data: opts.data,
+    }),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "React Native SDK for Koolbase \u2014 auth, database, storage, realtime, feature flags, and functions in one package.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",