@luxdb/sdk 1.4.3 → 2.0.0

package/README.md

@@ -96,29 +96,67 @@ const { data: deleted, error: deleteError } = await lux
   .eq("id", inserted?.id);
 ```
 
+### Filters and JSON
+
+Beyond `.eq/.neq/.gt/.gte/.lt/.lte`, the query builder supports `IN` lists, JSON
+dot-paths, and arrays:
+
+```ts
+await lux.table("users").select().in("id", [1, 2, 3]);
+await lux.table("users").select().notIn("status", ["banned", "deleted"]);
+
+// JSON columns round-trip as native objects (no manual JSON.stringify)
+await lux.table("events").insert({ metadata: { plan: { tier: "pro" }, count: 0 } });
+
+// Query JSON by dot-path, like a JS object. A path that does not resolve is a
+// non-match, never an error.
+await lux.table("events").select().eq("metadata.plan.tier", "pro");
+
+// IS VALID is existence, not truthiness: 0 / false / "" all count as valid.
+await lux.table("events").select().isValid("metadata.count");
+await lux.table("events").select().isNotValid("metadata.deleted_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");
+```
+
 ## Live tables
 
 Browser clients can subscribe to table queries over Lux Live. The SDK opens a WebSocket to the project live endpoint, and Lux core sends a snapshot followed by insert/update/delete events for rows matching the query.
 
+`.live()` resolves once the server confirms the subscription, returning the same
+`{ data, error }` shape as the rest of the SDK (here named `{ live, error }`). If
+the query isn't permitted by a read grant, `error` is populated and `live` is
+`null`. The subscription is async-iterable: the buffered snapshot arrives first,
+then live changes.
+
 ```ts
-const sub = lux
+const { live, error } = await lux
   .table<{ id: string; channel_id: string; body: string }>("messages")
   .eq("channel_id", "general")
-  .live()
-  .on("snapshot", (event) => {
-    console.log(event.rows);
-  })
-  .on("insert", (event) => {
-    console.log(event.new);
-  })
-  .on("update", (event) => {
-    console.log(event.old, event.new);
-  })
-  .on("delete", (event) => {
-    console.log(event.old);
-  });
-
-await sub.unsubscribe();
+  .live();
+
+if (error) throw error;
+
+for await (const event of live) {
+  if (event.type === "snapshot") console.log(event.rows);
+  else console.log(event.type, event.new ?? event.old);
+}
+```
+
+You can also attach callbacks instead of iterating:
+
+```ts
+const { live, error } = await lux.table("messages").eq("channel_id", "general").live();
+if (error) throw error;
+
+live
+  .on("insert", (event) => console.log(event.new))
+  .on("update", (event) => console.log(event.old, event.new))
+  .on("delete", (event) => console.log(event.old));
+
+await live.unsubscribe();
 ```
 
 ## OAuth
@@ -203,3 +241,4 @@ const value = await lux.get("hello");
 - Browser live subscriptions use the project publishable key plus the signed-in user's JWT.
 - Table `select()` accepts Lux's constrained projection grammar, not arbitrary SQL.
 - Direct `lux://` or `rediss://` database access uses the database password and is for trusted infrastructure.
+- With auth enabled, signed-in users are denied by default and gated by per-table **grants** (`GRANT read, write ON t WHERE user_id = auth.uid()`). Reads, writes, and `.live()` are all checked against the grant: a query or subscription must satisfy the predicate or it is rejected (an unscoped `.live()` under a row-scoped grant fails at subscribe time). Grants are authored as migrations.

package/dist/cjs/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Lux = exports.TableSubscription = exports.TableQueryBuilder = exports.createServerClient = exports.createBrowserClient = exports.LuxProjectClient = exports.createProjectClient = void 0;
+exports.Lux = exports.TableSubscription = exports.TableQueryBuilder = exports.createServerClient = exports.createBrowserClient = exports.LuxProjectLiveSubscription = exports.LuxProjectClient = exports.createProjectClient = void 0;
 exports.createClient = createClient;
 exports.createAuthClient = createAuthClient;
 const ioredis_1 = __importDefault(require("ioredis"));
@@ -14,6 +14,8 @@ Object.defineProperty(exports, "LuxProjectClient", { enumerable: true, get: func
 const namespaces_1 = require("./namespaces");
 const realtime_1 = require("./realtime");
 const table_1 = require("./table");
+var project_2 = require("./project");
+Object.defineProperty(exports, "LuxProjectLiveSubscription", { enumerable: true, get: function () { return project_2.LuxProjectLiveSubscription; } });
 var browser_1 = require("./browser");
 Object.defineProperty(exports, "createBrowserClient", { enumerable: true, get: function () { return browser_1.createBrowserClient; } });
 var ssr_1 = require("./ssr");

package/dist/cjs/project.js

@@ -274,6 +274,21 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
     is(column, value) {
         return this.addFilter(column, 'is', value);
     }
+    in(column, values) {
+        return this.addFilter(column, 'in', values);
+    }
+    notIn(column, values) {
+        return this.addFilter(column, 'notIn', values);
+    }
+    isValid(column) {
+        return this.addFilter(column, 'isValid', '');
+    }
+    isNotValid(column) {
+        return this.addFilter(column, 'isNotValid', '');
+    }
+    contains(column, value) {
+        return this.addFilter(column, 'contains', value);
+    }
     join(table, alias, onLeft, onRight) {
         this.joins.push({ type: 'inner', table, alias, onLeft, onRight });
         return this;
@@ -377,8 +392,14 @@ class LuxProjectSelectBuilder extends LuxProjectFilterBuilder {
         }
         return (0, utils_1.ok)(rows[0]);
     }
-    live() {
-        return new LuxProjectLiveSubscription(this.client, this.tableName, this.columns, this.filters, this.nearQuery, this.orderBy, this.limitCount, this.offsetCount);
+    async live() {
+        const live = new LuxProjectLiveSubscription(this.client, this.tableName, this.columns, this.filters, this.nearQuery, this.orderBy, this.limitCount, this.offsetCount);
+        const error = await live.start();
+        if (error) {
+            await live.unsubscribe();
+            return { live: null, error };
+        }
+        return { live, error: null };
     }
 }
 exports.LuxProjectSelectBuilder = LuxProjectSelectBuilder;
@@ -401,7 +422,11 @@ class LuxProjectLiveSubscription {
             change: [],
         };
         this.unsubscribeFn = null;
-        void this.start();
+        // Async-iterator plumbing: events buffer in `queue` until a `for await`
+        // consumer pulls them; pending `next()` calls park in `waiters`.
+        this.queue = [];
+        this.waiters = [];
+        this.closed = false;
     }
     on(type, handler) {
         this.handlers[type].push(handler);
@@ -410,15 +435,76 @@ class LuxProjectLiveSubscription {
     async unsubscribe() {
         this.unsubscribeFn?.();
         this.unsubscribeFn = null;
-    }
+        this.close();
+    }
+    /**
+     * Open the subscription and wait for the server to confirm it. Resolves
+     * `null` once the initial snapshot arrives, or a `LuxError` if the
+     * subscription is rejected (e.g. a grant `FORBIDDEN`) or the socket fails.
+     * Subsequent errors after a successful start surface via `on('error')` and
+     * end the async iterator.
+     */
     async start() {
-        this.unsubscribeFn = await this.client._subscribeLive(this.spec(), (event) => this.handleEvent(event), (error) => this.emit({
-            type: 'error',
-            table: this.table,
-            new: null,
-            old: null,
-            error,
-        }));
+        let settled = false;
+        let settle;
+        const ready = new Promise((resolve) => {
+            settle = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(error);
+            };
+        });
+        // Safety net: a server that never answers shouldn't hang the caller.
+        const timeout = setTimeout(() => {
+            settle({ code: 'LIVE_TIMEOUT', message: 'Timed out establishing live subscription' });
+        }, 15000);
+        this.unsubscribeFn = await this.client._subscribeLive(this.spec(), (event) => {
+            const kind = event?.kind;
+            this.handleEvent(event);
+            if (kind === 'snapshot')
+                settle(null);
+        }, (error) => {
+            const luxError = {
+                code: error.code ?? 'LIVE_ERROR',
+                message: error.message ?? 'Live subscription failed',
+            };
+            if (settled) {
+                // Post-start failure: notify handlers and end the stream.
+                this.emit({ type: 'error', table: this.table, new: null, old: null, error });
+                this.close();
+            }
+            else {
+                settle(luxError);
+            }
+        });
+        const result = await ready;
+        clearTimeout(timeout);
+        return result;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const buffered = this.queue.shift();
+                if (buffered)
+                    return Promise.resolve({ value: buffered, done: false });
+                if (this.closed)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiters.push(resolve));
+            },
+            return: () => {
+                void this.unsubscribe();
+                return Promise.resolve({ value: undefined, done: true });
+            },
+        };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
     }
     spec() {
         const spec = {
@@ -487,6 +573,18 @@ class LuxProjectLiveSubscription {
             for (const handler of this.handlers.change)
                 handler(event);
         }
+        // Feed `for await` consumers the data events (errors end the stream via close()).
+        if (event.type !== 'error')
+            this.pushIterator(event);
+    }
+    pushIterator(event) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter({ value: event, done: false });
+        else
+            this.queue.push(event);
     }
 }
 exports.LuxProjectLiveSubscription = LuxProjectLiveSubscription;
@@ -548,6 +646,13 @@ function normalizeWhere(where) {
 function filtersToWhere(filters) {
     return filters.map((filter) => {
         const op = filterOperatorToWhere(filter.operator);
+        if (filter.operator === 'in' || filter.operator === 'notIn') {
+            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') {
+            return normalizeWhere(`${filter.column} ${op}`);
+        }
         return normalizeWhere(`${filter.column} ${op} ${formatWhereValue(filter.value)}`);
     }).join(' AND ');
 }
@@ -572,6 +677,16 @@ function filterOperatorToWhere(operator) {
             return '<';
         case 'lte':
             return '<=';
+        case 'in':
+            return 'IN';
+        case 'notIn':
+            return 'NOT IN';
+        case 'isValid':
+            return 'IS VALID';
+        case 'isNotValid':
+            return 'IS NOT VALID';
+        case 'contains':
+            return 'CONTAINS';
     }
 }
 function formatWhereValue(value) {

package/dist/cjs/table.js

@@ -2,6 +2,41 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TableQueryBuilder = exports.TableSubscription = void 0;
 const utils_1 = require("./utils");
+/** Serialize a field value: JSON objects/arrays round-trip as JSON text. */
+function serializeFieldValue(v) {
+    if (v !== null && typeof v === 'object') {
+        return JSON.stringify(v);
+    }
+    return String(v);
+}
+/** Serialize one WHERE condition into RESP tokens. */
+function serializeCondition(cond) {
+    if (cond.op === 'IN' || cond.op === 'NOT IN') {
+        const values = Array.isArray(cond.value) ? cond.value : [cond.value];
+        return [
+            cond.field,
+            ...(cond.op === 'NOT IN' ? ['NOT', 'IN'] : ['IN']),
+            '(',
+            ...values.map(String),
+            ')',
+        ];
+    }
+    if (cond.op === 'IS VALID')
+        return [cond.field, 'IS', 'VALID'];
+    if (cond.op === 'IS NOT VALID')
+        return [cond.field, 'IS', 'NOT', 'VALID'];
+    return [cond.field, cond.op, String(cond.value)];
+}
+/** Join serialized conditions with AND separators. */
+function serializeConditions(conditions) {
+    const out = [];
+    for (let i = 0; i < conditions.length; i++) {
+        out.push(...serializeCondition(conditions[i]));
+        if (i < conditions.length - 1)
+            out.push('AND');
+    }
+    return out;
+}
 class TableSubscription {
     constructor(client, table, selectArgsBuilder, initError = null) {
         this.handlers = {
@@ -165,14 +200,7 @@ class TableQueryBuilder {
             args.push(...(this.joinClause.type === 'LEFT' ? ['LEFT', 'JOIN'] : ['JOIN']), this.joinClause.table, this.joinClause.alias, 'ON', this.joinClause.onLeft, '=', this.joinClause.onRight);
         }
         if (allConditions.length) {
-            args.push('WHERE');
-            for (let i = 0; i < allConditions.length; i++) {
-                const cond = allConditions[i];
-                args.push(cond.field, cond.op, String(cond.value));
-                if (i < allConditions.length - 1) {
-                    args.push('AND');
-                }
-            }
+            args.push('WHERE', ...serializeConditions(allConditions));
         }
         if (this.groupFields.length) {
             args.push('GROUP', 'BY', ...this.groupFields);
@@ -237,6 +265,29 @@ class TableQueryBuilder {
     lte(field, value) {
         return this.where(field, '<=', value);
     }
+    in(field, values) {
+        this.conditions.push({ field, op: 'IN', value: values });
+        return this;
+    }
+    notIn(field, values) {
+        this.conditions.push({ field, op: 'NOT IN', value: values });
+        return this;
+    }
+    /** Match rows where a JSON dot-path resolves to a present, non-null value. */
+    isValid(field) {
+        this.conditions.push({ field, op: 'IS VALID', value: '' });
+        return this;
+    }
+    /** Match rows where a JSON dot-path is absent or resolves to null. */
+    isNotValid(field) {
+        this.conditions.push({ field, op: 'IS NOT VALID', value: '' });
+        return this;
+    }
+    /** Match rows where an ARRAY column (or array-valued path) contains a value. */
+    contains(field, value) {
+        this.conditions.push({ field, op: 'CONTAINS', value });
+        return this;
+    }
     orderBy(field, dir = 'asc') {
         this.orderField = field;
         this.orderDir = dir.toUpperCase();
@@ -312,7 +363,7 @@ class TableQueryBuilder {
             }
             const args = [this.name];
             for (const [k, v] of Object.entries(data)) {
-                args.push(k, String(v));
+                args.push(k, serializeFieldValue(v));
             }
             const result = await this.client.call('TINSERT', ...args);
             return (0, utils_1.ok)(parseInt(result, 10) || 0);
@@ -321,6 +372,26 @@ class TableQueryBuilder {
             return (0, utils_1.err)('TINSERT_ERROR', `Failed to insert into '${this.name}'`, (0, utils_1.toLuxError)(error));
         }
     }
+    /** Declare a typed index on a JSON dot-path, e.g. ('meta.reactions.count', 'int'). */
+    async createIndex(path, type) {
+        try {
+            await this.client.call('TINDEX', this.name, path, type.toUpperCase());
+            return (0, utils_1.ok)(true);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TINDEX_ERROR', `Failed to index '${path}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
+    /** Drop a previously declared JSON path index. */
+    async dropIndex(path) {
+        try {
+            await this.client.call('TDROPINDEX', this.name, path);
+            return (0, utils_1.ok)(true);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TDROPINDEX_ERROR', `Failed to drop index '${path}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
     async update(idOrData, data) {
         try {
             const hasExplicitId = data !== undefined;
@@ -330,20 +401,14 @@ class TableQueryBuilder {
             }
             const args = [this.name, 'SET'];
             for (const [k, v] of Object.entries(patch)) {
-                args.push(k, String(v));
+                args.push(k, serializeFieldValue(v));
             }
             args.push('WHERE');
             if (hasExplicitId) {
                 args.push('id', '=', String(idOrData));
             }
             else {
-                for (let i = 0; i < this.conditions.length; i++) {
-                    const cond = this.conditions[i];
-                    args.push(cond.field, cond.op, String(cond.value));
-                    if (i < this.conditions.length - 1) {
-                        args.push('AND');
-                    }
-                }
+                args.push(...serializeConditions(this.conditions));
             }
             const result = await this.client.call('TUPDATE', ...args);
             return (0, utils_1.ok)(Number(result) || 0);
@@ -359,13 +424,7 @@ class TableQueryBuilder {
                     return (0, utils_1.err)('MISSING_WHERE', 'delete requires at least one filter');
                 }
                 const args = ['FROM', this.name, 'WHERE'];
-                for (let i = 0; i < this.conditions.length; i++) {
-                    const cond = this.conditions[i];
-                    args.push(cond.field, cond.op, String(cond.value));
-                    if (i < this.conditions.length - 1) {
-                        args.push('AND');
-                    }
-                }
+                args.push(...serializeConditions(this.conditions));
                 const result = await this.client.call('TDELETE', ...args);
                 return (0, utils_1.ok)(Number(result) || 0);
             }

package/dist/esm/index.js

@@ -5,6 +5,7 @@ import { TimeSeriesNamespace, VectorNamespace } from './namespaces.js';
 import { LuxRealtimeManager } from './realtime.js';
 import { TableQueryBuilder } from './table.js';
 export { createProjectClient, LuxProjectClient, };
+export { LuxProjectLiveSubscription } from './project.js';
 export { createBrowserClient } from './browser.js';
 export { createServerClient } from './ssr.js';
 export { TableQueryBuilder, TableSubscription } from './table.js';

package/dist/esm/project.js

@@ -267,6 +267,21 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
     is(column, value) {
         return this.addFilter(column, 'is', value);
     }
+    in(column, values) {
+        return this.addFilter(column, 'in', values);
+    }
+    notIn(column, values) {
+        return this.addFilter(column, 'notIn', values);
+    }
+    isValid(column) {
+        return this.addFilter(column, 'isValid', '');
+    }
+    isNotValid(column) {
+        return this.addFilter(column, 'isNotValid', '');
+    }
+    contains(column, value) {
+        return this.addFilter(column, 'contains', value);
+    }
     join(table, alias, onLeft, onRight) {
         this.joins.push({ type: 'inner', table, alias, onLeft, onRight });
         return this;
@@ -370,8 +385,14 @@ export class LuxProjectSelectBuilder extends LuxProjectFilterBuilder {
         }
         return ok(rows[0]);
     }
-    live() {
-        return new LuxProjectLiveSubscription(this.client, this.tableName, this.columns, this.filters, this.nearQuery, this.orderBy, this.limitCount, this.offsetCount);
+    async live() {
+        const live = new LuxProjectLiveSubscription(this.client, this.tableName, this.columns, this.filters, this.nearQuery, this.orderBy, this.limitCount, this.offsetCount);
+        const error = await live.start();
+        if (error) {
+            await live.unsubscribe();
+            return { live: null, error };
+        }
+        return { live, error: null };
     }
 }
 export class LuxProjectLiveSubscription {
@@ -393,7 +414,11 @@ export class LuxProjectLiveSubscription {
             change: [],
         };
         this.unsubscribeFn = null;
-        void this.start();
+        // Async-iterator plumbing: events buffer in `queue` until a `for await`
+        // consumer pulls them; pending `next()` calls park in `waiters`.
+        this.queue = [];
+        this.waiters = [];
+        this.closed = false;
     }
     on(type, handler) {
         this.handlers[type].push(handler);
@@ -402,15 +427,76 @@ export class LuxProjectLiveSubscription {
     async unsubscribe() {
         this.unsubscribeFn?.();
         this.unsubscribeFn = null;
-    }
+        this.close();
+    }
+    /**
+     * Open the subscription and wait for the server to confirm it. Resolves
+     * `null` once the initial snapshot arrives, or a `LuxError` if the
+     * subscription is rejected (e.g. a grant `FORBIDDEN`) or the socket fails.
+     * Subsequent errors after a successful start surface via `on('error')` and
+     * end the async iterator.
+     */
     async start() {
-        this.unsubscribeFn = await this.client._subscribeLive(this.spec(), (event) => this.handleEvent(event), (error) => this.emit({
-            type: 'error',
-            table: this.table,
-            new: null,
-            old: null,
-            error,
-        }));
+        let settled = false;
+        let settle;
+        const ready = new Promise((resolve) => {
+            settle = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(error);
+            };
+        });
+        // Safety net: a server that never answers shouldn't hang the caller.
+        const timeout = setTimeout(() => {
+            settle({ code: 'LIVE_TIMEOUT', message: 'Timed out establishing live subscription' });
+        }, 15000);
+        this.unsubscribeFn = await this.client._subscribeLive(this.spec(), (event) => {
+            const kind = event?.kind;
+            this.handleEvent(event);
+            if (kind === 'snapshot')
+                settle(null);
+        }, (error) => {
+            const luxError = {
+                code: error.code ?? 'LIVE_ERROR',
+                message: error.message ?? 'Live subscription failed',
+            };
+            if (settled) {
+                // Post-start failure: notify handlers and end the stream.
+                this.emit({ type: 'error', table: this.table, new: null, old: null, error });
+                this.close();
+            }
+            else {
+                settle(luxError);
+            }
+        });
+        const result = await ready;
+        clearTimeout(timeout);
+        return result;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const buffered = this.queue.shift();
+                if (buffered)
+                    return Promise.resolve({ value: buffered, done: false });
+                if (this.closed)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiters.push(resolve));
+            },
+            return: () => {
+                void this.unsubscribe();
+                return Promise.resolve({ value: undefined, done: true });
+            },
+        };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
     }
     spec() {
         const spec = {
@@ -479,6 +565,18 @@ export class LuxProjectLiveSubscription {
             for (const handler of this.handlers.change)
                 handler(event);
         }
+        // Feed `for await` consumers the data events (errors end the stream via close()).
+        if (event.type !== 'error')
+            this.pushIterator(event);
+    }
+    pushIterator(event) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter({ value: event, done: false });
+        else
+            this.queue.push(event);
     }
 }
 export class LuxProjectInsertBuilder extends LuxProjectThenable {
@@ -537,6 +635,13 @@ function normalizeWhere(where) {
 function filtersToWhere(filters) {
     return filters.map((filter) => {
         const op = filterOperatorToWhere(filter.operator);
+        if (filter.operator === 'in' || filter.operator === 'notIn') {
+            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') {
+            return normalizeWhere(`${filter.column} ${op}`);
+        }
         return normalizeWhere(`${filter.column} ${op} ${formatWhereValue(filter.value)}`);
     }).join(' AND ');
 }
@@ -561,6 +666,16 @@ function filterOperatorToWhere(operator) {
             return '<';
         case 'lte':
             return '<=';
+        case 'in':
+            return 'IN';
+        case 'notIn':
+            return 'NOT IN';
+        case 'isValid':
+            return 'IS VALID';
+        case 'isNotValid':
+            return 'IS NOT VALID';
+        case 'contains':
+            return 'CONTAINS';
     }
 }
 function formatWhereValue(value) {

package/dist/esm/table.js

@@ -1,4 +1,39 @@
 import { err, ok, toLuxError } from './utils.js';
+/** Serialize a field value: JSON objects/arrays round-trip as JSON text. */
+function serializeFieldValue(v) {
+    if (v !== null && typeof v === 'object') {
+        return JSON.stringify(v);
+    }
+    return String(v);
+}
+/** Serialize one WHERE condition into RESP tokens. */
+function serializeCondition(cond) {
+    if (cond.op === 'IN' || cond.op === 'NOT IN') {
+        const values = Array.isArray(cond.value) ? cond.value : [cond.value];
+        return [
+            cond.field,
+            ...(cond.op === 'NOT IN' ? ['NOT', 'IN'] : ['IN']),
+            '(',
+            ...values.map(String),
+            ')',
+        ];
+    }
+    if (cond.op === 'IS VALID')
+        return [cond.field, 'IS', 'VALID'];
+    if (cond.op === 'IS NOT VALID')
+        return [cond.field, 'IS', 'NOT', 'VALID'];
+    return [cond.field, cond.op, String(cond.value)];
+}
+/** Join serialized conditions with AND separators. */
+function serializeConditions(conditions) {
+    const out = [];
+    for (let i = 0; i < conditions.length; i++) {
+        out.push(...serializeCondition(conditions[i]));
+        if (i < conditions.length - 1)
+            out.push('AND');
+    }
+    return out;
+}
 export class TableSubscription {
     constructor(client, table, selectArgsBuilder, initError = null) {
         this.handlers = {
@@ -161,14 +196,7 @@ export class TableQueryBuilder {
             args.push(...(this.joinClause.type === 'LEFT' ? ['LEFT', 'JOIN'] : ['JOIN']), this.joinClause.table, this.joinClause.alias, 'ON', this.joinClause.onLeft, '=', this.joinClause.onRight);
         }
         if (allConditions.length) {
-            args.push('WHERE');
-            for (let i = 0; i < allConditions.length; i++) {
-                const cond = allConditions[i];
-                args.push(cond.field, cond.op, String(cond.value));
-                if (i < allConditions.length - 1) {
-                    args.push('AND');
-                }
-            }
+            args.push('WHERE', ...serializeConditions(allConditions));
         }
         if (this.groupFields.length) {
             args.push('GROUP', 'BY', ...this.groupFields);
@@ -233,6 +261,29 @@ export class TableQueryBuilder {
     lte(field, value) {
         return this.where(field, '<=', value);
     }
+    in(field, values) {
+        this.conditions.push({ field, op: 'IN', value: values });
+        return this;
+    }
+    notIn(field, values) {
+        this.conditions.push({ field, op: 'NOT IN', value: values });
+        return this;
+    }
+    /** Match rows where a JSON dot-path resolves to a present, non-null value. */
+    isValid(field) {
+        this.conditions.push({ field, op: 'IS VALID', value: '' });
+        return this;
+    }
+    /** Match rows where a JSON dot-path is absent or resolves to null. */
+    isNotValid(field) {
+        this.conditions.push({ field, op: 'IS NOT VALID', value: '' });
+        return this;
+    }
+    /** Match rows where an ARRAY column (or array-valued path) contains a value. */
+    contains(field, value) {
+        this.conditions.push({ field, op: 'CONTAINS', value });
+        return this;
+    }
     orderBy(field, dir = 'asc') {
         this.orderField = field;
         this.orderDir = dir.toUpperCase();
@@ -308,7 +359,7 @@ export class TableQueryBuilder {
             }
             const args = [this.name];
             for (const [k, v] of Object.entries(data)) {
-                args.push(k, String(v));
+                args.push(k, serializeFieldValue(v));
             }
             const result = await this.client.call('TINSERT', ...args);
             return ok(parseInt(result, 10) || 0);
@@ -317,6 +368,26 @@ export class TableQueryBuilder {
             return err('TINSERT_ERROR', `Failed to insert into '${this.name}'`, toLuxError(error));
         }
     }
+    /** Declare a typed index on a JSON dot-path, e.g. ('meta.reactions.count', 'int'). */
+    async createIndex(path, type) {
+        try {
+            await this.client.call('TINDEX', this.name, path, type.toUpperCase());
+            return ok(true);
+        }
+        catch (error) {
+            return err('TINDEX_ERROR', `Failed to index '${path}'`, toLuxError(error));
+        }
+    }
+    /** Drop a previously declared JSON path index. */
+    async dropIndex(path) {
+        try {
+            await this.client.call('TDROPINDEX', this.name, path);
+            return ok(true);
+        }
+        catch (error) {
+            return err('TDROPINDEX_ERROR', `Failed to drop index '${path}'`, toLuxError(error));
+        }
+    }
     async update(idOrData, data) {
         try {
             const hasExplicitId = data !== undefined;
@@ -326,20 +397,14 @@ export class TableQueryBuilder {
             }
             const args = [this.name, 'SET'];
             for (const [k, v] of Object.entries(patch)) {
-                args.push(k, String(v));
+                args.push(k, serializeFieldValue(v));
             }
             args.push('WHERE');
             if (hasExplicitId) {
                 args.push('id', '=', String(idOrData));
             }
             else {
-                for (let i = 0; i < this.conditions.length; i++) {
-                    const cond = this.conditions[i];
-                    args.push(cond.field, cond.op, String(cond.value));
-                    if (i < this.conditions.length - 1) {
-                        args.push('AND');
-                    }
-                }
+                args.push(...serializeConditions(this.conditions));
             }
             const result = await this.client.call('TUPDATE', ...args);
             return ok(Number(result) || 0);
@@ -355,13 +420,7 @@ export class TableQueryBuilder {
                     return err('MISSING_WHERE', 'delete requires at least one filter');
                 }
                 const args = ['FROM', this.name, 'WHERE'];
-                for (let i = 0; i < this.conditions.length; i++) {
-                    const cond = this.conditions[i];
-                    args.push(cond.field, cond.op, String(cond.value));
-                    if (i < this.conditions.length - 1) {
-                        args.push('AND');
-                    }
-                }
+                args.push(...serializeConditions(this.conditions));
                 const result = await this.client.call('TDELETE', ...args);
                 return ok(Number(result) || 0);
             }

package/dist/types/index.d.ts

@@ -6,11 +6,12 @@ import { TableQueryBuilder, type TableQueryBuilderOptions } from './table';
 import type { KSubEvent, LuxTypedRow, TableRow, TSAddOptions, TSMRangeResult, TSRangeOptions, TSSample, VSearchResult } from './types';
 export type { LuxAuthKey, LuxAuthGrantRow, LuxAuthIdentityRow, LuxAuthChangeEvent, LuxAuthOptions, LuxAuthKeyRow, LuxAuthProviderRow, LuxAuthSession, LuxAuthSessionRow, LuxAuthSigningKeyRow, LuxAuthStateChangeCallback, LuxAuthStorage, LuxAuthSubscription, LuxAuthTables, LuxAuthUserRow, LuxAuthUser, LuxUser, LuxOAuthProvider, LuxOAuthUrl, LuxSignInWithOAuthOptions, LuxCreateApiKeyOptions, LuxSignInOptions, LuxSignUpOptions, } from './auth';
 export { createProjectClient, LuxProjectClient, };
+export { LuxProjectLiveSubscription } from './project';
 export { createBrowserClient } from './browser';
 export type { LuxBrowserClientOptions } from './browser';
 export { createServerClient } from './ssr';
 export type { LuxCookieMethods, LuxCookieOptions, LuxServerClientOptions } from './ssr';
-export type { LuxProjectLiveEvent, LuxProjectLiveEventType, LuxProjectOptions, LuxTableColumn, LuxVectorSearchOptions, } from './project';
+export type { LuxLiveResult, LuxProjectLiveEvent, LuxProjectLiveEventType, LuxProjectOptions, LuxTableColumn, LuxVectorSearchOptions, } from './project';
 export type { KSubEvent, LuxAggregateRow, LuxAggregateValue, LuxError, LuxInferRow, LuxNearRow, LuxResult, LuxSimilarity, LuxTypedRow, TableChangeEvent, TableChangeType, TableErrorEvent, TableRow, TableSchema, TSAddOptions, TSMRangeResult, TSRangeOptions, TSSample, VSearchResult, } from './types';
 export { TableQueryBuilder, TableSubscription } from './table';
 export type { TableQueryBuilderOptions } from './table';

package/dist/types/project.d.ts

@@ -1,5 +1,5 @@
 import { LuxAuthClient, type LuxAuthOptions } from './auth';
-import type { LuxResult, LuxTypedRow } from './types';
+import type { LuxError, LuxResult, LuxTypedRow } from './types';
 export interface LuxProjectOptions {
     url: string;
     key: string;
@@ -23,13 +23,13 @@ export interface LuxVectorSearchOptions {
     filter_value?: string;
 }
 type QueryValue = string | number | boolean | number[] | null;
-type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'is';
+type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'is' | 'in' | 'notIn' | 'isValid' | 'isNotValid' | 'contains';
 type ProjectRowInput<T extends object> = Partial<T> & Record<string, QueryValue>;
 type ProjectSelectSingle<TResult> = TResult extends readonly (infer Row)[] ? Row : TResult;
 interface QueryFilter {
     column: string;
     operator: FilterOperator;
-    value: QueryValue;
+    value: QueryValue | QueryValue[];
 }
 interface QueryOrder {
     column: string;
@@ -69,6 +69,15 @@ export interface LuxProjectLiveEvent<T extends object = Record<string, unknown>>
     };
 }
 type LiveEventHandler<T extends object> = (event: LuxProjectLiveEvent<T>) => void;
+/**
+ * Result of opening a live subscription, in the same `{ data, error }` spirit as
+ * the rest of the SDK: `live` is the established subscription (or `null` if the
+ * server rejected it), `error` carries the rejection (e.g. a grant `FORBIDDEN`).
+ */
+export interface LuxLiveResult<T extends object> {
+    live: LuxProjectLiveSubscription<T> | null;
+    error: LuxError | null;
+}
 export declare class LuxProjectClient {
     readonly url: string;
     readonly key: string;
@@ -119,7 +128,7 @@ export declare class LuxProjectTable<T extends object> {
         threshold?: number;
     }): LuxProjectSelectBuilder<T, T[]>;
     is(column: string, value: QueryValue): LuxProjectSelectBuilder<T, T[]>;
-    live(): LuxProjectLiveSubscription<T>;
+    live(): Promise<LuxLiveResult<T>>;
     insert(row: ProjectRowInput<T>): LuxProjectInsertBuilder<unknown>;
     insert(rows: Array<ProjectRowInput<T>>): LuxProjectInsertBuilder<unknown[]>;
     update(patch: ProjectRowInput<T>): LuxProjectMutationBuilder<unknown>;
@@ -151,11 +160,16 @@ 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;
+    in(column: string, values: QueryValue[]): TSelf;
+    notIn(column: string, values: QueryValue[]): TSelf;
+    isValid(column: string): TSelf;
+    isNotValid(column: string): TSelf;
+    contains(column: string, value: QueryValue): TSelf;
     join(table: string, alias: string, onLeft: string, onRight: string): TSelf;
     leftJoin(table: string, alias: string, onLeft: string, onRight: string): TSelf;
     group(columns: string | string[]): TSelf;
     having(column: string, operator: FilterOperator, value: QueryValue): TSelf;
-    protected addFilter(column: string, operator: FilterOperator, value: QueryValue): TSelf;
+    protected addFilter(column: string, operator: FilterOperator, value: QueryValue | QueryValue[]): TSelf;
     protected filteredQueryParams(): URLSearchParams;
 }
 export declare class LuxProjectSelectBuilder<T extends object, TResult> extends LuxProjectFilterBuilder<TResult, LuxProjectSelectBuilder<T, TResult>> {
@@ -173,7 +187,7 @@ export declare class LuxProjectSelectBuilder<T extends object, TResult> extends
     range(from: number, to: number): this;
     single(): LuxProjectSelectBuilder<T, ProjectSelectSingle<TResult>>;
     execute(): Promise<LuxResult<TResult>>;
-    live(): LuxProjectLiveSubscription<LuxTypedRow<TResult>>;
+    live(): Promise<LuxLiveResult<LuxTypedRow<TResult>>>;
 }
 export declare class LuxProjectLiveSubscription<T extends object> {
     private client;
@@ -186,13 +200,26 @@ export declare class LuxProjectLiveSubscription<T extends object> {
     private offsetCount?;
     private handlers;
     private unsubscribeFn;
+    private queue;
+    private waiters;
+    private closed;
     constructor(client: LuxProjectClient, table: string, columns: string, filters: QueryFilter[], nearQuery?: QueryNear | undefined, orderBy?: QueryOrder | undefined, limitCount?: number | undefined, offsetCount?: number | undefined);
     on(type: LuxProjectLiveEventType | 'change', handler: LiveEventHandler<T>): this;
     unsubscribe(): Promise<void>;
-    private start;
+    /**
+     * Open the subscription and wait for the server to confirm it. Resolves
+     * `null` once the initial snapshot arrives, or a `LuxError` if the
+     * subscription is rejected (e.g. a grant `FORBIDDEN`) or the socket fails.
+     * Subsequent errors after a successful start surface via `on('error')` and
+     * end the async iterator.
+     */
+    start(): Promise<LuxError | null>;
+    [Symbol.asyncIterator](): AsyncIterator<LuxProjectLiveEvent<T>>;
+    private close;
     private spec;
     private handleEvent;
     private emit;
+    private pushIterator;
 }
 export declare class LuxProjectInsertBuilder<TResult> extends LuxProjectThenable<TResult> {
     private client;

package/dist/types/table.d.ts

@@ -1,10 +1,10 @@
 import type { KSubEvent, LuxError, LuxResult, TableChangeEvent, TableErrorEvent, TableRow, TableSchema } from './types';
-type TableWhereOp = '=' | '!=' | '>' | '<' | '>=' | '<=';
+type TableWhereOp = '=' | '!=' | '>' | '<' | '>=' | '<=' | 'IN' | 'NOT IN' | 'IS VALID' | 'IS NOT VALID' | 'CONTAINS';
 type TableWhereValue = string | number | boolean;
 interface TableWhereCondition {
     field: string;
     op: TableWhereOp;
-    value: TableWhereValue;
+    value: TableWhereValue | TableWhereValue[];
 }
 interface TableClient {
     call(command: string, ...args: Array<string | number>): Promise<unknown>;
@@ -60,6 +60,14 @@ export declare class TableQueryBuilder<T extends object = TableRow> {
     gte(field: string, value: TableWhereValue): this;
     lt(field: string, value: TableWhereValue): this;
     lte(field: string, value: TableWhereValue): this;
+    in(field: string, values: TableWhereValue[]): this;
+    notIn(field: string, values: TableWhereValue[]): this;
+    /** Match rows where a JSON dot-path resolves to a present, non-null value. */
+    isValid(field: string): this;
+    /** Match rows where a JSON dot-path is absent or resolves to null. */
+    isNotValid(field: string): this;
+    /** Match rows where an ARRAY column (or array-valued path) contains a value. */
+    contains(field: string, value: TableWhereValue): this;
     orderBy(field: string, dir?: 'asc' | 'desc'): this;
     order(field: string, options?: {
         ascending?: boolean;
@@ -82,6 +90,10 @@ export declare class TableQueryBuilder<T extends object = TableRow> {
     run(): Promise<LuxResult<T[] | T>>;
     then<TFulfilled = LuxResult<T[] | T>, TRejected = never>(onfulfilled?: ((value: LuxResult<T[] | T>) => TFulfilled | PromiseLike<TFulfilled>) | null, onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null): Promise<TFulfilled | TRejected>;
     insert(data: Record<string, unknown>): Promise<LuxResult<number>>;
+    /** Declare a typed index on a JSON dot-path, e.g. ('meta.reactions.count', 'int'). */
+    createIndex(path: string, type: 'int' | 'float' | 'bool' | 'timestamp' | 'str'): Promise<LuxResult<true>>;
+    /** Drop a previously declared JSON path index. */
+    dropIndex(path: string): Promise<LuxResult<true>>;
     update(id: number | string, data: Record<string, unknown>): Promise<LuxResult<number>>;
     update(data: Record<string, unknown>): Promise<LuxResult<number>>;
     delete(...ids: Array<number | string>): Promise<LuxResult<number>>;

package/package.json

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