@luxdb/sdk 2.0.0 → 2.1.0

package/README.md

@@ -80,17 +80,32 @@ const { data: matches } = await lux
   .near("embedding", queryEmbedding, { k: 10, threshold: 0.8 });
 ```
 
+Writes return the affected row(s), including server-generated columns (`id`,
+UUIDv7 primary keys, `DEFAULT now()` timestamps):
+
 ```ts
+// insert -> the inserted row
 const { data: inserted, error: insertError } = await lux
   .table("messages")
   .insert({ body: "hello", channel: "general" });
 
-const { data: updated, error: updateError } = await lux
+// bulk insert in a single request -> array of rows
+const { data: many } = await lux
+  .table("messages")
+  .insert([{ body: "a" }, { body: "b" }]);
+
+// upsert: insert, or update the row that conflicts on `onConflict` (default: PK)
+const { data: user } = await lux
+  .table("users")
+  .upsert({ email: "a@x.com", name: "Bob" }, { onConflict: "email" });
+
+// update / delete -> the affected rows
+const { data: updated } = await lux
   .table("messages")
   .update({ body: "edited" })
   .eq("id", inserted?.id);
 
-const { data: deleted, error: deleteError } = await lux
+const { data: deleted } = await lux
   .table("messages")
   .delete()
   .eq("id", inserted?.id);
@@ -116,6 +131,10 @@ await lux.table("events").select().eq("metadata.plan.tier", "pro");
 await lux.table("events").select().isValid("metadata.count");
 await lux.table("events").select().isNotValid("metadata.deleted_at");
 
+// IS NULL / IS NOT NULL on a regular column (NULL == the column is absent)
+await lux.table("tasks").select().isNull("deleted_at");
+await lux.table("tasks").select().isNotNull("archived_at");
+
 // Array membership, and a declared JSON-path index for range queries at scale.
 await lux.table("events").select().contains("tags", "urgent");
 await lux.table("events").createIndex("metadata.plan.tier", "str");

package/dist/cjs/project.js

@@ -218,6 +218,12 @@ class LuxProjectTable {
     insert(rowOrRows) {
         return new LuxProjectInsertBuilder(this.client, this.name, rowOrRows);
     }
+    upsert(rowOrRows, options) {
+        return new LuxProjectInsertBuilder(this.client, this.name, rowOrRows, {
+            upsert: true,
+            onConflict: options?.onConflict,
+        });
+    }
     update(patch) {
         return new LuxProjectMutationBuilder(this.client, this.name, 'PATCH', patch);
     }
@@ -272,8 +278,17 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
         return this.addFilter(column, 'lte', value);
     }
     is(column, value) {
+        // `.is(col, null)` is the Supabase-style spelling of an IS NULL check.
+        if (value === null)
+            return this.addFilter(column, 'isNull', '');
         return this.addFilter(column, 'is', value);
     }
+    isNull(column) {
+        return this.addFilter(column, 'isNull', '');
+    }
+    isNotNull(column) {
+        return this.addFilter(column, 'isNotNull', '');
+    }
     in(column, values) {
         return this.addFilter(column, 'in', values);
     }
@@ -589,24 +604,30 @@ class LuxProjectLiveSubscription {
 }
 exports.LuxProjectLiveSubscription = LuxProjectLiveSubscription;
 class LuxProjectInsertBuilder extends LuxProjectThenable {
-    constructor(client, tableName, rowOrRows) {
+    constructor(client, tableName, rowOrRows, upsertOptions) {
         super();
         this.client = client;
         this.tableName = tableName;
         this.rowOrRows = rowOrRows;
+        this.upsertOptions = upsertOptions;
     }
     async execute() {
-        if (!Array.isArray(this.rowOrRows)) {
-            return this.client.request('POST', `/tables/${encodeURIComponent(this.tableName)}`, this.rowOrRows);
-        }
-        const results = [];
-        for (const row of this.rowOrRows) {
-            const result = await this.client.request('POST', `/tables/${encodeURIComponent(this.tableName)}`, row);
-            if (result.error)
-                return result;
-            results.push(result.data);
+        // One request for both shapes: an array body inserts all rows server-side
+        // in a single round-trip. The server returns the affected row(s)
+        // ({result: row} for a single row, {result: [rows]} for an array).
+        let path = `/tables/${encodeURIComponent(this.tableName)}`;
+        if (this.upsertOptions?.upsert) {
+            const params = new URLSearchParams();
+            if (this.upsertOptions.onConflict)
+                params.set('on_conflict', this.upsertOptions.onConflict);
+            else
+                params.set('upsert', 'true');
+            path += `?${params.toString()}`;
         }
-        return (0, utils_1.ok)(results);
+        const res = await this.client.request('POST', path, this.rowOrRows);
+        if (res.error)
+            return res;
+        return (0, utils_1.ok)(unwrapResult(res.data));
     }
 }
 exports.LuxProjectInsertBuilder = LuxProjectInsertBuilder;
@@ -622,7 +643,11 @@ class LuxProjectMutationBuilder extends LuxProjectFilterBuilder {
         }
         const params = this.filteredQueryParams();
         const query = params.toString();
-        return this.client.request(this.method, `/tables/${encodeURIComponent(this.tableName)}${query ? `?${query}` : ''}`, this.body);
+        // Update/delete return the affected rows ({result: [rows]}); unwrap them.
+        const res = await this.client.request(this.method, `/tables/${encodeURIComponent(this.tableName)}${query ? `?${query}` : ''}`, this.body);
+        if (res.error)
+            return res;
+        return (0, utils_1.ok)(unwrapResult(res.data));
     }
 }
 exports.LuxProjectMutationBuilder = LuxProjectMutationBuilder;
@@ -650,7 +675,10 @@ function filtersToWhere(filters) {
             const values = Array.isArray(filter.value) ? filter.value : [filter.value];
             return normalizeWhere(`${filter.column} ${op} ( ${values.map(formatWhereValue).join(' ')} )`);
         }
-        if (filter.operator === 'isValid' || filter.operator === 'isNotValid') {
+        if (filter.operator === 'isValid' ||
+            filter.operator === 'isNotValid' ||
+            filter.operator === 'isNull' ||
+            filter.operator === 'isNotNull') {
             return normalizeWhere(`${filter.column} ${op}`);
         }
         return normalizeWhere(`${filter.column} ${op} ${formatWhereValue(filter.value)}`);
@@ -685,6 +713,10 @@ function filterOperatorToWhere(operator) {
             return 'IS VALID';
         case 'isNotValid':
             return 'IS NOT VALID';
+        case 'isNull':
+            return 'IS NULL';
+        case 'isNotNull':
+            return 'IS NOT NULL';
         case 'contains':
             return 'CONTAINS';
     }

package/dist/esm/project.js

@@ -212,6 +212,12 @@ export class LuxProjectTable {
     insert(rowOrRows) {
         return new LuxProjectInsertBuilder(this.client, this.name, rowOrRows);
     }
+    upsert(rowOrRows, options) {
+        return new LuxProjectInsertBuilder(this.client, this.name, rowOrRows, {
+            upsert: true,
+            onConflict: options?.onConflict,
+        });
+    }
     update(patch) {
         return new LuxProjectMutationBuilder(this.client, this.name, 'PATCH', patch);
     }
@@ -265,8 +271,17 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
         return this.addFilter(column, 'lte', value);
     }
     is(column, value) {
+        // `.is(col, null)` is the Supabase-style spelling of an IS NULL check.
+        if (value === null)
+            return this.addFilter(column, 'isNull', '');
         return this.addFilter(column, 'is', value);
     }
+    isNull(column) {
+        return this.addFilter(column, 'isNull', '');
+    }
+    isNotNull(column) {
+        return this.addFilter(column, 'isNotNull', '');
+    }
     in(column, values) {
         return this.addFilter(column, 'in', values);
     }
@@ -580,24 +595,30 @@ export class LuxProjectLiveSubscription {
     }
 }
 export class LuxProjectInsertBuilder extends LuxProjectThenable {
-    constructor(client, tableName, rowOrRows) {
+    constructor(client, tableName, rowOrRows, upsertOptions) {
         super();
         this.client = client;
         this.tableName = tableName;
         this.rowOrRows = rowOrRows;
+        this.upsertOptions = upsertOptions;
     }
     async execute() {
-        if (!Array.isArray(this.rowOrRows)) {
-            return this.client.request('POST', `/tables/${encodeURIComponent(this.tableName)}`, this.rowOrRows);
-        }
-        const results = [];
-        for (const row of this.rowOrRows) {
-            const result = await this.client.request('POST', `/tables/${encodeURIComponent(this.tableName)}`, row);
-            if (result.error)
-                return result;
-            results.push(result.data);
+        // One request for both shapes: an array body inserts all rows server-side
+        // in a single round-trip. The server returns the affected row(s)
+        // ({result: row} for a single row, {result: [rows]} for an array).
+        let path = `/tables/${encodeURIComponent(this.tableName)}`;
+        if (this.upsertOptions?.upsert) {
+            const params = new URLSearchParams();
+            if (this.upsertOptions.onConflict)
+                params.set('on_conflict', this.upsertOptions.onConflict);
+            else
+                params.set('upsert', 'true');
+            path += `?${params.toString()}`;
         }
-        return ok(results);
+        const res = await this.client.request('POST', path, this.rowOrRows);
+        if (res.error)
+            return res;
+        return ok(unwrapResult(res.data));
     }
 }
 export class LuxProjectMutationBuilder extends LuxProjectFilterBuilder {
@@ -612,7 +633,11 @@ export class LuxProjectMutationBuilder extends LuxProjectFilterBuilder {
         }
         const params = this.filteredQueryParams();
         const query = params.toString();
-        return this.client.request(this.method, `/tables/${encodeURIComponent(this.tableName)}${query ? `?${query}` : ''}`, this.body);
+        // Update/delete return the affected rows ({result: [rows]}); unwrap them.
+        const res = await this.client.request(this.method, `/tables/${encodeURIComponent(this.tableName)}${query ? `?${query}` : ''}`, this.body);
+        if (res.error)
+            return res;
+        return ok(unwrapResult(res.data));
     }
 }
 function unwrapRows(payload) {
@@ -639,7 +664,10 @@ function filtersToWhere(filters) {
             const values = Array.isArray(filter.value) ? filter.value : [filter.value];
             return normalizeWhere(`${filter.column} ${op} ( ${values.map(formatWhereValue).join(' ')} )`);
         }
-        if (filter.operator === 'isValid' || filter.operator === 'isNotValid') {
+        if (filter.operator === 'isValid' ||
+            filter.operator === 'isNotValid' ||
+            filter.operator === 'isNull' ||
+            filter.operator === 'isNotNull') {
             return normalizeWhere(`${filter.column} ${op}`);
         }
         return normalizeWhere(`${filter.column} ${op} ${formatWhereValue(filter.value)}`);
@@ -674,6 +702,10 @@ function filterOperatorToWhere(operator) {
             return 'IS VALID';
         case 'isNotValid':
             return 'IS NOT VALID';
+        case 'isNull':
+            return 'IS NULL';
+        case 'isNotNull':
+            return 'IS NOT NULL';
         case 'contains':
             return 'CONTAINS';
     }

package/dist/types/project.d.ts

@@ -23,7 +23,7 @@ export interface LuxVectorSearchOptions {
     filter_value?: string;
 }
 type QueryValue = string | number | boolean | number[] | null;
-type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'is' | 'in' | 'notIn' | 'isValid' | 'isNotValid' | 'contains';
+type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'is' | 'in' | 'notIn' | 'isValid' | 'isNotValid' | 'isNull' | 'isNotNull' | 'contains';
 type ProjectRowInput<T extends object> = Partial<T> & Record<string, QueryValue>;
 type ProjectSelectSingle<TResult> = TResult extends readonly (infer Row)[] ? Row : TResult;
 interface QueryFilter {
@@ -131,6 +131,12 @@ export declare class LuxProjectTable<T extends object> {
     live(): Promise<LuxLiveResult<T>>;
     insert(row: ProjectRowInput<T>): LuxProjectInsertBuilder<unknown>;
     insert(rows: Array<ProjectRowInput<T>>): LuxProjectInsertBuilder<unknown[]>;
+    upsert(row: ProjectRowInput<T>, options?: {
+        onConflict?: string;
+    }): LuxProjectInsertBuilder<unknown>;
+    upsert(rows: Array<ProjectRowInput<T>>, options?: {
+        onConflict?: string;
+    }): LuxProjectInsertBuilder<unknown[]>;
     update(patch: ProjectRowInput<T>): LuxProjectMutationBuilder<unknown>;
     delete(): LuxProjectMutationBuilder<unknown>;
     count(): Promise<LuxResult<number>>;
@@ -160,6 +166,8 @@ declare abstract class LuxProjectFilterBuilder<TResult, TSelf> extends LuxProjec
     lt(column: string, value: QueryValue): TSelf;
     lte(column: string, value: QueryValue): TSelf;
     is(column: string, value: QueryValue): TSelf;
+    isNull(column: string): TSelf;
+    isNotNull(column: string): TSelf;
     in(column: string, values: QueryValue[]): TSelf;
     notIn(column: string, values: QueryValue[]): TSelf;
     isValid(column: string): TSelf;
@@ -225,7 +233,11 @@ export declare class LuxProjectInsertBuilder<TResult> extends LuxProjectThenable
     private client;
     private tableName;
     private rowOrRows;
-    constructor(client: LuxProjectClient, tableName: string, rowOrRows: Record<string, QueryValue> | Array<Record<string, QueryValue>>);
+    private upsertOptions?;
+    constructor(client: LuxProjectClient, tableName: string, rowOrRows: Record<string, QueryValue> | Array<Record<string, QueryValue>>, upsertOptions?: {
+        upsert: boolean;
+        onConflict?: string;
+    } | undefined);
     execute(): Promise<LuxResult<TResult>>;
 }
 export declare class LuxProjectMutationBuilder<TResult> extends LuxProjectFilterBuilder<TResult, LuxProjectMutationBuilder<TResult>> {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luxdb/sdk",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "description": "Official Lux TypeScript SDK for app data, auth, tables, vectors, realtime, and Redis-compatible direct access",
     "main": "./dist/cjs/index.js",
     "module": "./dist/esm/index.js",