@luxdb/sdk 1.4.2 → 2.0.0

package/dist/esm/project.js

@@ -2,9 +2,13 @@ import { LuxAuthClient } from './auth.js';
 import { err, ok, toLuxError } from './utils.js';
 export 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 LuxAuthClient({
             ...options.auth,
             httpUrl: this.url,
@@ -79,6 +83,96 @@ export class LuxProjectClient {
             return err('LUX_PROJECT_REQUEST_ERROR', 'Lux request failed', 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);
+    }
 }
 export class LuxProjectTable {
     constructor(client, name) {
@@ -88,6 +182,33 @@ export 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);
     }
@@ -121,6 +242,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);
@@ -143,6 +267,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;
@@ -151,6 +308,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'}`);
         }
@@ -171,6 +344,15 @@ export 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;
@@ -203,6 +385,199 @@ export class LuxProjectSelectBuilder extends LuxProjectFilterBuilder {
         }
         return 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 };
+    }
+}
+export 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);
+    }
 }
 export class LuxProjectInsertBuilder extends LuxProjectThenable {
     constructor(client, tableName, rowOrRows) {
@@ -258,6 +633,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)}`);
@@ -278,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) {
@@ -301,3 +699,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;
+}