@techfinityedge/koolbase-react-native 2.0.0 → 2.2.0

package/README.md

@@ -162,6 +162,52 @@ await Koolbase.db.update('record-id', { title: 'Updated' });
 await Koolbase.db.delete('record-id');
 ```
 
+### Handling unique-constraint conflicts
+
+  A write that would violate a unique constraint throws `KoolbaseConflictError`:
+
+  \`\`\`ts
+  try {
+    await koolbase.db.upsert('users', { email }, { name });
+  } catch (e) {
+    if (e instanceof KoolbaseConflictError) {
+      showError('That email is already registered.');
+    }
+  }
+  \`\`\`
+
+### Upsert
+
+Insert a record, or update the existing one matching a filter.
+
+\`\`\`ts
+const result = await Koolbase.db.upsert(
+  'profiles',
+  { user_id: userId },
+  { weightKg: 70 }
+);
+
+console.log(result.created); // true if inserted, false if updated
+console.log(result.record.id);
+\`\`\`
+
+> Online-only: needs the server's view to decide insert vs update, so unlike
+> `insert` it isn't queued offline and throws on network failure.
+
+### Delete where
+
+Bulk-delete every record matching a filter. Returns the number deleted.
+
+\`\`\`ts
+const deleted = await Koolbase.db.deleteWhere('sessions', {
+  user_id: userId,
+  status: 'expired',
+});
+\`\`\`
+
+> 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

package/dist/database-errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Thrown when a write is rejected because the value would violate a
+ * collection's unique constraint — the server responds with 409 Conflict.
+ * Catch it to handle duplicates, e.g. an email or username already in use.
+ *
+ * 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.
+ *
+ * @example
+ * try {
+ *   await koolbase.db.upsert('users', { email }, { name });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseConflictError) {
+ *     showError('That email is already registered.');
+ *   }
+ * }
+ */
+export declare class KoolbaseConflictError extends Error {
+    code: string;
+    constructor(message?: string);
+}

package/dist/database-errors.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseConflictError = void 0;
+/**
+ * Thrown when a write is rejected because the value would violate a
+ * collection's unique constraint — the server responds with 409 Conflict.
+ * Catch it to handle duplicates, e.g. an email or username already in use.
+ *
+ * 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.
+ *
+ * @example
+ * try {
+ *   await koolbase.db.upsert('users', { email }, { name });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseConflictError) {
+ *     showError('That email is already registered.');
+ *   }
+ * }
+ */
+class KoolbaseConflictError extends Error {
+    constructor(message) {
+        super(message ?? 'Value violates a unique constraint');
+        this.code = 'unique_violation';
+        this.name = 'KoolbaseConflictError';
+        Object.setPrototypeOf(this, KoolbaseConflictError.prototype);
+    }
+}
+exports.KoolbaseConflictError = KoolbaseConflictError;

package/dist/database.d.ts

@@ -1,4 +1,4 @@
-import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult } from './types';
+import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult } from './types';
 export declare class KoolbaseDatabase {
     private config;
     private getUserId;
@@ -9,6 +9,34 @@ export declare class KoolbaseDatabase {
     private runQuery;
     query(collection: string, options?: QueryOptions): Promise<QueryResult>;
     insert(collection: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
+    /**
+     * Insert a record, or update the existing one matching `match`.
+     *
+     * The server decides: exactly one match updates it, no match inserts a new
+     * record (seeded with the `match` fields), more than one match is an error.
+     * Returns the resulting record and a `created` flag (true = inserted, false
+     * = updated).
+     *
+     * Online-only by design. Unlike `insert`, an upsert is NOT queued offline:
+     * the insert-vs-update decision needs the server's authoritative view of
+     * what already exists, so deferring it could create a duplicate or apply a
+     * wrong update on later sync. It throws on network failure instead. A raw
+     * fetch is used (not `request`) so the status code is readable: 201 =
+     * created, 200 = updated.
+     */
+    upsert(collection: string, match: Record<string, unknown>, data: Record<string, unknown>): Promise<UpsertResult>;
+    /**
+     * Bulk-delete every record in `collection` matching `filters`.
+     *
+     * The server applies the collection's delete rule (scoping to the caller for
+     * owner/scoped rules) and returns the number of records deleted.
+     *
+     * Online-only by design — like upsert, this is NOT queued offline: a bulk
+     * delete needs the server's authoritative view of what matches, so it throws
+     * on network failure rather than risk deleting the wrong set on later sync.
+     * The collection cache is invalidated on success.
+     */
+    deleteWhere(collection: string, filters: Record<string, unknown>): Promise<number>;
     get(recordId: string): Promise<KoolbaseRecord>;
     update(recordId: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
     delete(recordId: string): Promise<void>;

package/dist/database.js

@@ -4,6 +4,7 @@ exports.KoolbaseDatabase = void 0;
 const cache_store_1 = require("./cache-store");
 const sync_engine_1 = require("./sync-engine");
 const record_1 = require("./record");
+const database_errors_1 = require("./database-errors");
 function generateId() {
     return 'local_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
 }
@@ -97,6 +98,68 @@ class KoolbaseDatabase {
         });
         return optimisticRecord;
     }
+    // ─── Upsert (online-only) ─────────────────────────────────────────────────
+    /**
+     * Insert a record, or update the existing one matching `match`.
+     *
+     * The server decides: exactly one match updates it, no match inserts a new
+     * record (seeded with the `match` fields), more than one match is an error.
+     * Returns the resulting record and a `created` flag (true = inserted, false
+     * = updated).
+     *
+     * Online-only by design. Unlike `insert`, an upsert is NOT queued offline:
+     * the insert-vs-update decision needs the server's authoritative view of
+     * what already exists, so deferring it could create a duplicate or apply a
+     * wrong update on later sync. It throws on network failure instead. A raw
+     * fetch is used (not `request`) so the status code is readable: 201 =
+     * created, 200 = updated.
+     */
+    async upsert(collection, match, data) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/upsert`, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ collection, match, data }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+            if (res.status === 409) {
+                throw new database_errors_1.KoolbaseConflictError(body.error);
+            }
+            throw new Error(body.error ?? `Upsert failed: ${res.status}`);
+        }
+        const created = res.status === 201;
+        const record = (0, record_1.recordFromWire)(body);
+        // Keep the cache fresh, same intent as insert's post-success invalidate.
+        const userId = this.getUserId() ?? 'anonymous';
+        await (0, cache_store_1.invalidateCache)(userId, collection);
+        return { record, created };
+    }
+    // ─── Delete where (online-only) ─────────────────────────────────────────────
+    /**
+     * Bulk-delete every record in `collection` matching `filters`.
+     *
+     * The server applies the collection's delete rule (scoping to the caller for
+     * owner/scoped rules) and returns the number of records deleted.
+     *
+     * Online-only by design — like upsert, this is NOT queued offline: a bulk
+     * delete needs the server's authoritative view of what matches, so it throws
+     * on network failure rather than risk deleting the wrong set on later sync.
+     * The collection cache is invalidated on success.
+     */
+    async deleteWhere(collection, filters) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/delete-where`, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ collection, filters }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+            throw new Error(body.error ?? `Delete failed: ${res.status}`);
+        }
+        const userId = this.getUserId() ?? 'anonymous';
+        await (0, cache_store_1.invalidateCache)(userId, collection);
+        return body.deleted ?? 0;
+    }
     // ─── Get single record ──────────────────────────────────────────────────────
     async get(recordId) {
         const raw = await this.request('GET', `/v1/sdk/db/records/${recordId}`);

package/dist/index.d.ts

@@ -18,6 +18,7 @@ import { KoolbaseStorage } from './storage';
 import { KoolbaseConfig, VersionCheckResult } from './types';
 export * from './types';
 export * from './auth-errors';
+export * from './database-errors';
 export { KoolbaseAuth, KoolbaseDatabase, KoolbaseFlags, KoolbaseFunctions, KoolbaseRealtime, KoolbaseStorage };
 export declare const Koolbase: {
     initialize(config: KoolbaseConfig): Promise<void>;

package/dist/index.js

@@ -45,6 +45,7 @@ const storage_1 = require("./storage");
 Object.defineProperty(exports, "KoolbaseStorage", { enumerable: true, get: function () { return storage_1.KoolbaseStorage; } });
 __exportStar(require("./types"), exports);
 __exportStar(require("./auth-errors"), exports);
+__exportStar(require("./database-errors"), exports);
 let _auth = null;
 let _db = null;
 let _storage = null;

package/dist/types.d.ts

@@ -130,6 +130,10 @@ export interface QueryResult {
     total: number;
     isFromCache?: boolean;
 }
+export interface UpsertResult {
+    record: KoolbaseRecord;
+    created: boolean;
+}
 export interface PendingWrite {
     id: string;
     type: 'insert' | 'update' | 'delete';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "2.0.0",
+  "version": "2.2.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",