@luxdb/sdk 2.0.0 → 2.2.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/cjs/ssr.js

@@ -3,21 +3,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createServerClient = createServerClient;
 const project_1 = require("./project");
 const DEFAULT_COOKIE = 'lux-auth-session';
-function createServerClient(url, key, options) {
+function createServerClient(url, key, options = {}) {
     const storageKey = options.auth?.storageKey ?? DEFAULT_COOKIE;
     const cookieOptions = options.auth?.cookieOptions ?? {
         path: '/',
         sameSite: 'lax',
     };
     const { cookieOptions: _cookieOptions, ...authOptions } = options.auth ?? {};
+    // With cookies -> cookie-backed session (SSR). Without -> stateless backend
+    // client: no session storage, nothing to persist.
+    const hasCookies = options.cookies !== undefined;
     return (0, project_1.createClient)(url, key, {
         fetch: options.fetch,
         auth: {
-            persistSession: true,
+            persistSession: hasCookies,
             autoRefreshToken: false,
             ...authOptions,
             storageKey,
-            storage: cookieStorage(options.cookies, cookieOptions),
+            storage: hasCookies ? cookieStorage(options.cookies, cookieOptions) : null,
         },
     });
 }

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/esm/ssr.js

@@ -1,20 +1,23 @@
 import { createClient } from './project.js';
 const DEFAULT_COOKIE = 'lux-auth-session';
-export function createServerClient(url, key, options) {
+export function createServerClient(url, key, options = {}) {
     const storageKey = options.auth?.storageKey ?? DEFAULT_COOKIE;
     const cookieOptions = options.auth?.cookieOptions ?? {
         path: '/',
         sameSite: 'lax',
     };
     const { cookieOptions: _cookieOptions, ...authOptions } = options.auth ?? {};
+    // With cookies -> cookie-backed session (SSR). Without -> stateless backend
+    // client: no session storage, nothing to persist.
+    const hasCookies = options.cookies !== undefined;
     return createClient(url, key, {
         fetch: options.fetch,
         auth: {
-            persistSession: true,
+            persistSession: hasCookies,
             autoRefreshToken: false,
             ...authOptions,
             storageKey,
-            storage: cookieStorage(options.cookies, cookieOptions),
+            storage: hasCookies ? cookieStorage(options.cookies, cookieOptions) : null,
         },
     });
 }

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/dist/types/ssr.d.ts

@@ -17,6 +17,11 @@ export interface LuxServerClientOptions extends Omit<LuxProjectOptions, 'url' |
     auth?: Omit<NonNullable<LuxProjectOptions['auth']>, 'storage'> & {
         cookieOptions?: LuxCookieOptions;
     };
-    cookies: LuxCookieMethods;
+    /**
+     * Cookie adapter for SSR session persistence (Next/SvelteKit/etc). Omit it
+     * for a stateless backend client (secret key, or `setSession` per request):
+     * `createServerClient(url, key)` then works with no cookie plumbing.
+     */
+    cookies?: LuxCookieMethods;
 }
-export declare function createServerClient(url: string, key: string, options: LuxServerClientOptions): import("./project").LuxProjectClient;
+export declare function createServerClient(url: string, key: string, options?: LuxServerClientOptions): import("./project").LuxProjectClient;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luxdb/sdk",
-    "version": "2.0.0",
+    "version": "2.2.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",