@luxdb/sdk 1.4.2 → 1.4.3

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,31 @@ const { data: deleted, error: deleteError } = await lux
   .eq("id", inserted?.id);
 ```
 
+## 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.
+
+```ts
+const sub = 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();
+```
+
 ## OAuth
 
 ```ts
@@ -82,6 +141,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 +200,6 @@ 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.

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,24 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
     is(column, value) {
         return this.addFilter(column, 'is', 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 +300,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 +336,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 +377,119 @@ 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);
+    }
 }
 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;
+        void this.start();
+    }
+    on(type, handler) {
+        this.handlers[type].push(handler);
+        return this;
+    }
+    async unsubscribe() {
+        this.unsubscribeFn?.();
+        this.unsubscribeFn = null;
+    }
+    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,
+        }));
+    }
+    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);
+        }
+    }
+}
+exports.LuxProjectLiveSubscription = LuxProjectLiveSubscription;
 class LuxProjectInsertBuilder extends LuxProjectThenable {
     constructor(client, tableName, rowOrRows) {
         super();
@@ -273,6 +551,12 @@ function filtersToWhere(filters) {
         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)}`);
+    }).join(' AND ');
+}
 function filterOperatorToWhere(operator) {
     switch (operator) {
         case 'eq':
@@ -311,3 +595,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;
+}

package/dist/cjs/table.js

@@ -59,9 +59,10 @@ class TableSubscription {
         try {
             const initial = await this.fetchMatches();
             for (const row of initial) {
-                if (row.id == null)
+                const id = row.id;
+                if (id == null)
                     continue;
-                this.knownRows.set(String(row.id), row);
+                this.knownRows.set(String(id), row);
             }
             const pattern = `_t:${this.table}:row:*`;
             this.unsubscribeFn = await this.client._subscribePattern(pattern, (raw) => {
@@ -111,7 +112,9 @@ class TableSubscription {
             if (!previous || !next)
                 return;
             this.knownRows.set(pk, next);
-            const changed = Object.keys(next).filter((key) => previous[key] !== next[key]);
+            const previousRow = previous;
+            const nextRow = next;
+            const changed = Object.keys(nextRow).filter((key) => previousRow[key] !== nextRow[key]);
             this.emitChange({
                 type: 'update',
                 table: this.table,
@@ -132,6 +135,8 @@ exports.TableSubscription = TableSubscription;
 class TableQueryBuilder {
     constructor(client, name, options) {
         this.conditions = [];
+        this.groupFields = [];
+        this.havingConditions = [];
         this.selectClause = '*';
         this.expectSingle = false;
         this.client = client;
@@ -157,7 +162,7 @@ class TableQueryBuilder {
         const args = [this.selectClause, 'FROM', this.name];
         const allConditions = extra ? [...this.conditions, ...extra] : this.conditions;
         if (this.joinClause) {
-            args.push('JOIN', this.joinClause.table, this.joinClause.alias, 'ON', this.joinClause.onLeft, '=', this.joinClause.onRight);
+            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');
@@ -169,6 +174,25 @@ class TableQueryBuilder {
                 }
             }
         }
+        if (this.groupFields.length) {
+            args.push('GROUP', 'BY', ...this.groupFields);
+        }
+        if (this.havingConditions.length) {
+            args.push('HAVING');
+            for (let i = 0; i < this.havingConditions.length; i++) {
+                const cond = this.havingConditions[i];
+                args.push(cond.field, cond.op, String(cond.value));
+                if (i < this.havingConditions.length - 1) {
+                    args.push('AND');
+                }
+            }
+        }
+        if (this.similarityClause) {
+            args.push('NEAR', this.similarityClause.field, `[${this.similarityClause.vector.join(',')}]`, 'K', String(this.similarityClause.k));
+            if (this.similarityClause.threshold != null) {
+                args.push('THRESHOLD', String(this.similarityClause.threshold));
+            }
+        }
         if (this.orderField) {
             args.push('ORDER', 'BY', this.orderField, this.orderDir || 'ASC');
         }
@@ -230,68 +254,41 @@ class TableQueryBuilder {
         return this;
     }
     join(table, alias, onLeft, onRight) {
-        this.joinClause = { table, alias, onLeft, onRight };
+        this.joinClause = { type: 'INNER', table, alias, onLeft, onRight };
+        return this;
+    }
+    leftJoin(table, alias, onLeft, onRight) {
+        this.joinClause = { type: 'LEFT', table, alias, onLeft, onRight };
+        return this;
+    }
+    group(fields) {
+        this.groupFields = Array.isArray(fields)
+            ? fields
+            : fields.split(',').map((field) => field.trim()).filter(Boolean);
+        return this;
+    }
+    groupBy(fields) {
+        return this.group(fields);
+    }
+    having(field, op, value) {
+        this.havingConditions.push({ field, op, value });
         return this;
     }
-    similar(field, vector, options) {
+    near(field, vector, options = {}) {
         this.similarityClause = {
             field,
             vector,
-            k: options.k,
-            filter: options.filter,
+            k: options.k ?? 10,
+            threshold: options.threshold,
         };
         return this;
     }
-    parseSimilarityPk(result, field) {
-        const metadata = result.metadata;
-        if (metadata && typeof metadata === 'object') {
-            for (const key of ['id', 'pk', 'row_id']) {
-                const value = metadata[key];
-                if (value != null)
-                    return String(value);
-            }
-        }
-        const expectedPrefix = `${this.name}:${field}:`;
-        if (result.key.startsWith(expectedPrefix)) {
-            return result.key.slice(expectedPrefix.length);
-        }
-        const segments = result.key.split(':');
-        if (segments.length > 0) {
-            return segments[segments.length - 1] || null;
-        }
-        return null;
+    similar(field, vector, options = {}) {
+        return this.near(field, vector, options);
     }
     async run() {
         try {
-            let rows = [];
-            if (this.similarityClause) {
-                if (this.joinClause) {
-                    return (0, utils_1.err)('SIMILAR_JOIN_UNSUPPORTED', 'similar(...) cannot be combined with join(...) yet');
-                }
-                const similarResults = await this.client.vsearch(this.similarityClause.vector, {
-                    k: this.similarityClause.k,
-                    filter: this.similarityClause.filter,
-                    meta: true,
-                });
-                for (const match of similarResults) {
-                    const pk = this.parseSimilarityPk(match, this.similarityClause.field);
-                    if (!pk)
-                        continue;
-                    const args = this.buildSelectArgs([{ field: 'id', op: '=', value: pk }]);
-                    const one = await this.client._tselect(args);
-                    if (one.length === 0)
-                        continue;
-                    rows.push({ ...one[0], _similarity: match.similarity });
-                }
-                if (this.offsetCount != null || this.limitCount != null) {
-                    const start = this.offsetCount ?? 0;
-                    const end = this.limitCount != null ? start + this.limitCount : undefined;
-                    rows = rows.slice(start, end);
-                }
-            }
-            else {
-                rows = await this.client._tselect(this.buildSelectArgs());
-            }
+            const rows = await this.client._tselect(this.buildSelectArgs());
             const validated = rows.map((row) => this.validateRow(row));
             if (this.expectSingle) {
                 if (validated.length === 0) {
@@ -384,12 +381,6 @@ class TableQueryBuilder {
         }
     }
     subscribe() {
-        if (this.similarityClause) {
-            return new TableSubscription(this.client, this.name, (extra) => this.buildSelectArgs(extra), {
-                code: 'SIMILAR_SUBSCRIBE_UNSUPPORTED',
-                message: 'subscribe() is not supported on similar(...) queries yet',
-            });
-        }
         return new TableSubscription(this.client, this.name, (extra) => this.buildSelectArgs(extra));
     }
 }