sqlite-hub-client 0.6.0 → 0.7.0

package/README.md

@@ -73,6 +73,26 @@ const active = await db.count("users", { active: 1 });
 // Exists check
 const exists = await db.exists("users", { email: "alice@example.com" });
 
+// Upsert — INSERT OR REPLACE (relies on PRIMARY KEY / UNIQUE constraints)
+await db.upsert("users", { id: 1, email: "alice@example.com", name: "Alice" });
+
+// Upsert — explicit conflict target
+await db.upsert(
+  "users",
+  { email: "alice@example.com", name: "Alice" },
+  { conflictColumns: ["email"] }
+);
+
+// Bulk upsert
+await db.upsertMany(
+  "users",
+  [
+    { email: "alice@example.com", name: "Alice" },
+    { email: "bob@example.com",   name: "Bob"   },
+  ],
+  { conflictColumns: ["email"] }
+);
+
 // Update
 await db.update("users", { name: "Alice Smith" }, { id: 1 });
 
@@ -168,6 +188,46 @@ await db.insertMany("posts", [
 ]);
 ```
 
+#### `db.upsert(table, data, options?)` → `ExecResult`
+
+Insert a row or update it on conflict.
+
+```ts
+// INSERT OR REPLACE — relies on PRIMARY KEY / UNIQUE constraints
+await db.upsert("users", { id: 1, email: "alice@example.com", name: "Alice" });
+
+// INSERT … ON CONFLICT(email) DO UPDATE SET name = excluded.name
+await db.upsert(
+  "users",
+  { email: "alice@example.com", name: "Alice" },
+  { conflictColumns: ["email"] }
+);
+```
+
+#### `db.upsertMany(table, rows, options?)` → `ExecResult`
+
+Bulk version of `upsert`.
+
+```ts
+await db.upsertMany(
+  "users",
+  [
+    { email: "alice@example.com", name: "Alice" },
+    { email: "bob@example.com",   name: "Bob"   },
+  ],
+  { conflictColumns: ["email"] }
+);
+```
+
+**`UpsertOptions` fields:**
+
+| Field              | Type       | Description                                                                                                     |
+| ------------------ | ---------- | --------------------------------------------------------------------------------------------------------------- |
+| `conflictColumns`  | `string[]` | Conflict-target columns. Omit to use `INSERT OR REPLACE` (relies on PRIMARY KEY / UNIQUE). |
+| `updateColumns`    | `string[]` | Columns to overwrite on conflict. Defaults to all columns **not** in `conflictColumns`. Pass `[]` for DO NOTHING. |
+
+---
+
 #### `db.update(table, data, where)` → `ExecResult`
 
 ```ts

package/dist/database.d.ts

@@ -25,6 +25,21 @@ export interface CreateIndexOptions {
     unique?: boolean;
     ifNotExists?: boolean;
 }
+export interface UpsertOptions {
+    /**
+     * Column(s) that form the conflict target.
+     * When provided the statement becomes:
+     *   INSERT INTO … ON CONFLICT(col1, col2) DO UPDATE SET …
+     * When omitted `INSERT OR REPLACE` is used instead (relies on the
+     * table's PRIMARY KEY / UNIQUE constraints).
+     */
+    conflictColumns?: string[];
+    /**
+     * Columns to update on conflict.
+     * Defaults to all columns that are NOT in `conflictColumns`.
+     */
+    updateColumns?: string[];
+}
 /**
  * High-level database client.
  * Accepts any `IAdapter` — currently `HttpAdapter`, extensible to direct
@@ -76,6 +91,37 @@ export declare class Database {
      * ]);
      */
     insertMany(table: string, rows: Record<string, unknown>[]): Promise<ExecResult>;
+    /**
+     * Upsert a single row — insert or update on conflict.
+     *
+     * Without `conflictColumns` the statement uses `INSERT OR REPLACE` which
+     * relies on the table's PRIMARY KEY / UNIQUE constraints.
+     *
+     * With `conflictColumns` it uses the more precise:
+     *   `INSERT … ON CONFLICT(cols) DO UPDATE SET …`
+     *
+     * @example
+     * // relies on PRIMARY KEY / UNIQUE constraints
+     * await db.upsert("users", { id: 1, email: "a@b.com", name: "Alice" });
+     *
+     * // explicit conflict target
+     * await db.upsert("users", { email: "a@b.com", name: "Alice" }, { conflictColumns: ["email"] });
+     */
+    upsert(table: string, data: Record<string, unknown>, options?: UpsertOptions): Promise<ExecResult>;
+    /**
+     * Upsert multiple rows — insert or update each row on conflict.
+     *
+     * @example
+     * await db.upsertMany(
+     *   "users",
+     *   [
+     *     { email: "a@b.com", name: "Alice" },
+     *     { email: "b@c.com", name: "Bob" },
+     *   ],
+     *   { conflictColumns: ["email"] }
+     * );
+     */
+    upsertMany(table: string, rows: Record<string, unknown>[], options?: UpsertOptions): Promise<ExecResult>;
     /**
      * Update rows matching `where`.
      *

package/dist/database.js

@@ -114,6 +114,62 @@ export class Database {
         const bindings = rows.flatMap((row) => keys.map((k) => row[k]));
         return this._write(`INSERT INTO "${table}" (${cols}) VALUES ${rowPlaceholders}`, bindings);
     }
+    /**
+     * Upsert a single row — insert or update on conflict.
+     *
+     * Without `conflictColumns` the statement uses `INSERT OR REPLACE` which
+     * relies on the table's PRIMARY KEY / UNIQUE constraints.
+     *
+     * With `conflictColumns` it uses the more precise:
+     *   `INSERT … ON CONFLICT(cols) DO UPDATE SET …`
+     *
+     * @example
+     * // relies on PRIMARY KEY / UNIQUE constraints
+     * await db.upsert("users", { id: 1, email: "a@b.com", name: "Alice" });
+     *
+     * // explicit conflict target
+     * await db.upsert("users", { email: "a@b.com", name: "Alice" }, { conflictColumns: ["email"] });
+     */
+    async upsert(table, data, options = {}) {
+        return this.upsertMany(table, [data], options);
+    }
+    /**
+     * Upsert multiple rows — insert or update each row on conflict.
+     *
+     * @example
+     * await db.upsertMany(
+     *   "users",
+     *   [
+     *     { email: "a@b.com", name: "Alice" },
+     *     { email: "b@c.com", name: "Bob" },
+     *   ],
+     *   { conflictColumns: ["email"] }
+     * );
+     */
+    async upsertMany(table, rows, options = {}) {
+        if (rows.length === 0)
+            return { rowsAffected: 0, lastInsertRowid: null };
+        const keys = Object.keys(rows[0]);
+        const cols = keys.map((k) => `"${k}"`).join(", ");
+        const rowPlaceholders = rows
+            .map(() => `(${keys.map(() => "?").join(", ")})`)
+            .join(", ");
+        const bindings = rows.flatMap((row) => keys.map((k) => row[k]));
+        if (options.conflictColumns && options.conflictColumns.length > 0) {
+            const conflictCols = options.conflictColumns
+                .map((c) => `"${c}"`)
+                .join(", ");
+            const updateCols = options.updateColumns ??
+                keys.filter((k) => !options.conflictColumns.includes(k));
+            const conflictClause = updateCols.length === 0
+                ? `ON CONFLICT(${conflictCols}) DO NOTHING`
+                : `ON CONFLICT(${conflictCols}) DO UPDATE SET ${updateCols
+                    .map((k) => `"${k}" = excluded."${k}"`)
+                    .join(", ")}`;
+            return this._write(`INSERT INTO "${table}" (${cols}) VALUES ${rowPlaceholders} ${conflictClause}`, bindings);
+        }
+        return this._write(`INSERT OR REPLACE INTO "${table}" (${cols}) VALUES ${rowPlaceholders}`, bindings);
+    }
     /**
      * Update rows matching `where`.
      *

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Database } from "./database.js";
-export type { ColumnDef, CreateIndexOptions, CreateTableOptions, FindOptions, OrderDirection, WhereClause } from "./database.js";
+export type { ColumnDef, CreateIndexOptions, CreateTableOptions, FindOptions, OrderDirection, UpsertOptions, WhereClause } from "./database.js";
 export { HttpAdapter } from "./adapters/http.js";
 export type { HttpAdapterOptions } from "./adapters/http.js";
 export type { ColumnHeader, ExecResult, IAdapter, QueryResult, RawResult } from "./adapters/types.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-hub-client",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "High-level SQLite client for sqlite-hub — HTTP adapter included, direct SQLite coming soon",
   "type": "module",
   "main": "dist/index.js",