@luxdb/sdk 1.4.2 → 2.0.0

package/README.md

@@ -35,8 +35,20 @@ if (error) throw error;
 Queries and mutations return a Supabase-style result object:
 
 ```ts
+interface User {
+  id: number;
+  email: string;
+  age: number;
+}
+
+interface Message {
+  id: string;
+  body: string;
+  embedding: number[];
+}
+
 const { data: users, error } = await lux
-  .table<{ id: number; email: string; age: number }>("users")
+  .table<User[]>("users")
   .select()
   .gt("age", 25)
   .order("age", { ascending: false })
@@ -46,6 +58,28 @@ if (error) throw error;
 console.log(users);
 ```
 
+`table<T>()` accepts either a row type or an array type. `table<User>("users")`
+and `table<User[]>("users")` both infer `User` rows; the array form is useful
+when you want the generic to read like the returned data.
+
+For computed projections, pass the projection shape to `select<T>()`:
+
+```ts
+import type { LuxAggregateRow, LuxNearRow } from "@luxdb/sdk";
+
+type TeamStats = { team_id: number } & LuxAggregateRow<"member_count" | "avg_age">;
+
+const { data: teamStats } = await lux
+  .table<User>("members")
+  .select<TeamStats>("team_id,COUNT(*) AS member_count,AVG(age) AS avg_age")
+  .group("team_id");
+
+const { data: matches } = await lux
+  .table<Message>("messages")
+  .select<LuxNearRow<Message>>("id,body,_similarity")
+  .near("embedding", queryEmbedding, { k: 10, threshold: 0.8 });
+```
+
 ```ts
 const { data: inserted, error: insertError } = await lux
   .table("messages")
@@ -62,6 +96,69 @@ 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 { live, error } = await lux
+  .table<{ id: string; channel_id: string; body: string }>("messages")
+  .eq("channel_id", "general")
+  .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
 
 ```ts
@@ -82,6 +179,18 @@ if (error) throw error;
 console.log(data.user);
 ```
 
+Auth types are exported for app code and system table reads:
+
+```ts
+import type { LuxUser, LuxAuthTables } from "@luxdb/sdk";
+
+type AuthUserRow = LuxAuthTables["auth.users"];
+
+function renderUser(user: LuxUser, row: AuthUserRow) {
+  return row.email ?? user.email;
+}
+```
+
 ## Server client
 
 Use a secret key only from trusted server code.
@@ -129,4 +238,7 @@ const value = await lux.get("hello");
 - `lux_pub_...` keys are safe for browser app calls.
 - `lux_sec_...` keys are server-only.
 - User sessions issue JWT access tokens.
+- 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

@@ -1,15 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LuxProjectMutationBuilder = exports.LuxProjectInsertBuilder = exports.LuxProjectSelectBuilder = exports.LuxProjectTable = exports.LuxProjectClient = void 0;
+exports.LuxProjectMutationBuilder = exports.LuxProjectInsertBuilder = exports.LuxProjectLiveSubscription = exports.LuxProjectSelectBuilder = exports.LuxProjectTable = exports.LuxProjectClient = void 0;
 exports.createProjectClient = createProjectClient;
 exports.createClient = createClient;
 const auth_1 = require("./auth");
 const utils_1 = require("./utils");
 class LuxProjectClient {
     constructor(options) {
+        this.liveSocket = null;
+        this.liveSubscriptions = new Map();
+        this.livePending = [];
         this.url = options.url.replace(/\/+$/, '');
         this.key = options.key;
         this.fetchImpl = resolveFetch(options.fetch);
+        this.WebSocketImpl = options.websocket;
         this.auth = new auth_1.LuxAuthClient({
             ...options.auth,
             httpUrl: this.url,
@@ -84,6 +88,96 @@ class LuxProjectClient {
             return (0, utils_1.err)('LUX_PROJECT_REQUEST_ERROR', 'Lux request failed', (0, utils_1.toLuxError)(error));
         }
     }
+    async _subscribeLive(spec, handler, error) {
+        const id = `sub_${Math.random().toString(36).slice(2)}_${Date.now().toString(36)}`;
+        const record = { id, spec, handler, error };
+        this.liveSubscriptions.set(id, record);
+        await this.ensureLiveSocket();
+        this.sendLive({
+            type: 'live.subscribe',
+            id,
+            spec,
+        });
+        return () => {
+            this.liveSubscriptions.delete(id);
+            this.sendLive({ type: 'live.unsubscribe', id });
+            if (this.liveSubscriptions.size === 0) {
+                this.liveSocket?.close();
+                this.liveSocket = null;
+            }
+        };
+    }
+    async ensureLiveSocket() {
+        const WebSocketImpl = resolveWebSocket(this.WebSocketImpl);
+        this.WebSocketImpl = WebSocketImpl;
+        if (this.liveSocket &&
+            (this.liveSocket.readyState === WebSocketImpl.OPEN ||
+                this.liveSocket.readyState === WebSocketImpl.CONNECTING)) {
+            return;
+        }
+        const accessToken = await this.auth.getAccessToken();
+        const url = new URL(`${this.url}/live`);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        url.searchParams.set('apikey', this.key);
+        if (accessToken)
+            url.searchParams.set('access_token', accessToken);
+        const socket = new WebSocketImpl(url.toString());
+        this.liveSocket = socket;
+        socket.onopen = () => {
+            for (const message of this.livePending.splice(0))
+                socket.send(message);
+        };
+        socket.onmessage = (event) => {
+            let message;
+            try {
+                message = JSON.parse(String(event.data));
+            }
+            catch {
+                return;
+            }
+            const subscription = typeof message.id === 'string' ? this.liveSubscriptions.get(message.id) : null;
+            if (message.type === 'live.event' && subscription) {
+                subscription.handler(message.event);
+                return;
+            }
+            if (message.type === 'live.error') {
+                const target = subscription ? [subscription] : [...this.liveSubscriptions.values()];
+                for (const sub of target) {
+                    sub.error(message.error || { code: 'LIVE_ERROR', message: 'Live subscription failed' });
+                }
+            }
+        };
+        socket.onerror = () => {
+            for (const subscription of this.liveSubscriptions.values()) {
+                subscription.error({ code: 'LIVE_SOCKET_ERROR', message: 'Live socket failed' });
+            }
+        };
+        socket.onclose = () => {
+            if (this.liveSocket === socket)
+                this.liveSocket = null;
+            if (this.liveSubscriptions.size > 0) {
+                for (const subscription of this.liveSubscriptions.values()) {
+                    this.livePending.push(JSON.stringify({
+                        type: 'live.subscribe',
+                        id: subscription.id,
+                        spec: subscription.spec,
+                    }));
+                }
+                setTimeout(() => {
+                    void this.ensureLiveSocket();
+                }, 1000);
+            }
+        };
+    }
+    sendLive(message) {
+        const payload = JSON.stringify(message);
+        const WebSocketImpl = this.WebSocketImpl;
+        if (WebSocketImpl && this.liveSocket?.readyState === WebSocketImpl.OPEN) {
+            this.liveSocket.send(payload);
+            return;
+        }
+        this.livePending.push(payload);
+    }
 }
 exports.LuxProjectClient = LuxProjectClient;
 class LuxProjectTable {
@@ -94,6 +188,33 @@ class LuxProjectTable {
     select(columns = '*') {
         return new LuxProjectSelectBuilder(this.client, this.name, columns);
     }
+    eq(column, value) {
+        return this.select().eq(column, value);
+    }
+    neq(column, value) {
+        return this.select().neq(column, value);
+    }
+    gt(column, value) {
+        return this.select().gt(column, value);
+    }
+    gte(column, value) {
+        return this.select().gte(column, value);
+    }
+    lt(column, value) {
+        return this.select().lt(column, value);
+    }
+    lte(column, value) {
+        return this.select().lte(column, value);
+    }
+    near(column, vector, options = {}) {
+        return this.select().near(column, vector, options);
+    }
+    is(column, value) {
+        return this.select().is(column, value);
+    }
+    live() {
+        return this.select().live();
+    }
     insert(rowOrRows) {
         return new LuxProjectInsertBuilder(this.client, this.name, rowOrRows);
     }
@@ -128,6 +249,9 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
         this.client = client;
         this.tableName = tableName;
         this.filters = [];
+        this.joins = [];
+        this.groupColumns = [];
+        this.havingFilters = [];
     }
     eq(column, value) {
         return this.addFilter(column, 'eq', value);
@@ -150,6 +274,39 @@ 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;
+    }
+    leftJoin(table, alias, onLeft, onRight) {
+        this.joins.push({ type: 'left', table, alias, onLeft, onRight });
+        return this;
+    }
+    group(columns) {
+        this.groupColumns = Array.isArray(columns)
+            ? columns
+            : columns.split(',').map((column) => column.trim()).filter(Boolean);
+        return this;
+    }
+    having(column, operator, value) {
+        this.havingFilters.push({ column, operator, value });
+        return this;
+    }
     addFilter(column, operator, value) {
         this.filters.push({ column, operator, value });
         return this;
@@ -158,6 +315,22 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
         const params = new URLSearchParams();
         if (this.filters.length)
             params.set('where', filtersToWhere(this.filters));
+        for (const join of this.joins) {
+            const kind = join.type === 'left' ? ':left' : '';
+            params.append('join', `${join.table}:${join.alias}${kind}:on(${join.onLeft}=${join.onRight})`);
+        }
+        if (this.groupColumns.length)
+            params.set('group', this.groupColumns.join(','));
+        if (this.havingFilters.length)
+            params.set('having', havingToWhere(this.havingFilters));
+        if (this.nearQuery) {
+            params.set('near_field', this.nearQuery.field);
+            params.set('near_vector', `[${this.nearQuery.vector.join(',')}]`);
+            params.set('near_k', String(this.nearQuery.k));
+            if (this.nearQuery.threshold != null) {
+                params.set('near_threshold', String(this.nearQuery.threshold));
+            }
+        }
         if (this.orderBy) {
             params.set('order', `${this.orderBy.column} ${this.orderBy.ascending ? 'ASC' : 'DESC'}`);
         }
@@ -178,6 +351,15 @@ class LuxProjectSelectBuilder extends LuxProjectFilterBuilder {
         this.orderBy = { column, ascending: options.ascending ?? true };
         return this;
     }
+    near(column, vector, options = {}) {
+        this.nearQuery = {
+            field: column,
+            vector,
+            k: options.k ?? 10,
+            threshold: options.threshold,
+        };
+        return this;
+    }
     limit(count) {
         this.limitCount = count;
         return this;
@@ -210,8 +392,202 @@ class LuxProjectSelectBuilder extends LuxProjectFilterBuilder {
         }
         return (0, utils_1.ok)(rows[0]);
     }
+    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;
+class LuxProjectLiveSubscription {
+    constructor(client, table, columns, filters, nearQuery, orderBy, limitCount, offsetCount) {
+        this.client = client;
+        this.table = table;
+        this.columns = columns;
+        this.filters = filters;
+        this.nearQuery = nearQuery;
+        this.orderBy = orderBy;
+        this.limitCount = limitCount;
+        this.offsetCount = offsetCount;
+        this.handlers = {
+            snapshot: [],
+            insert: [],
+            update: [],
+            delete: [],
+            error: [],
+            change: [],
+        };
+        this.unsubscribeFn = null;
+        // 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);
+        return this;
+    }
+    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() {
+        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 = {
+            kind: 'table',
+            table: this.table,
+            select: this.columns,
+        };
+        if (this.filters.length) {
+            spec.where = this.filters.map((filter) => ({
+                field: filter.column,
+                op: filterOperatorToWhere(filter.operator),
+                value: filter.value,
+            }));
+        }
+        if (this.nearQuery) {
+            spec.near = {
+                field: this.nearQuery.field,
+                vector: this.nearQuery.vector,
+                k: this.nearQuery.k,
+                threshold: this.nearQuery.threshold,
+            };
+        }
+        if (this.orderBy) {
+            spec.orderBy = {
+                field: this.orderBy.column,
+                dir: this.orderBy.ascending ? 'asc' : 'desc',
+            };
+        }
+        if (this.limitCount != null)
+            spec.limit = this.limitCount;
+        if (this.offsetCount != null)
+            spec.offset = this.offsetCount;
+        return spec;
+    }
+    handleEvent(raw) {
+        if (!raw || typeof raw !== 'object')
+            return;
+        const event = raw;
+        if (event.kind === 'snapshot') {
+            this.emit({
+                type: 'snapshot',
+                table: this.table,
+                new: null,
+                old: null,
+                rows: Array.isArray(event.rows) ? event.rows : [],
+                raw,
+            });
+            return;
+        }
+        if (event.kind === 'insert' || event.kind === 'update' || event.kind === 'delete') {
+            this.emit({
+                type: event.kind,
+                table: this.table,
+                pk: event.pk == null ? undefined : String(event.pk),
+                new: event.row ?? null,
+                old: event.previous ?? null,
+                changed: Array.isArray(event.changed) ? event.changed : undefined,
+                raw,
+            });
+        }
+    }
+    emit(event) {
+        for (const handler of this.handlers[event.type])
+            handler(event);
+        if (event.type !== 'snapshot' && event.type !== 'error') {
+            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;
 class LuxProjectInsertBuilder extends LuxProjectThenable {
     constructor(client, tableName, rowOrRows) {
         super();
@@ -268,6 +644,19 @@ function normalizeWhere(where) {
     return where.trim().replace(/\s*(>=|<=|!=|=|>|<)\s*/g, ' $1 ');
 }
 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 ');
+}
+function havingToWhere(filters) {
     return filters.map((filter) => {
         const op = filterOperatorToWhere(filter.operator);
         return normalizeWhere(`${filter.column} ${op} ${formatWhereValue(filter.value)}`);
@@ -288,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) {
@@ -311,3 +710,10 @@ function resolveFetch(fetchImpl) {
     }
     return candidate;
 }
+function resolveWebSocket(websocketImpl) {
+    const candidate = websocketImpl ?? globalThis.WebSocket;
+    if (!candidate) {
+        throw new Error('Lux project live subscriptions require a WebSocket implementation');
+    }
+    return candidate;
+}