@luxdb/sdk 1.2.1 → 1.3.0

package/dist/index.d.ts

@@ -1,93 +1,18 @@
 import Redis, { type RedisOptions } from 'ioredis';
-export interface VSearchResult {
-    key: string;
-    similarity: number;
-    metadata?: Record<string, unknown>;
-}
-export interface TSSample {
-    timestamp: number;
-    value: number;
-}
-export interface TSAddOptions {
-    retention?: number;
-    labels?: Record<string, string>;
-}
-export interface TSRangeOptions {
-    aggregation?: {
-        type: 'avg' | 'sum' | 'min' | 'max' | 'count' | 'first' | 'last' | 'range' | 'std.p' | 'std.s' | 'var.p' | 'var.s';
-        bucketSize: number;
-    };
-}
-export interface TSMRangeResult {
-    key: string;
-    labels: Record<string, string>;
-    samples: TSSample[];
-}
-export interface KSubEvent {
-    pattern: string;
-    key: string;
-    operation: string;
-}
-export interface TableRow {
-    id: number;
-    [field: string]: unknown;
-}
-declare class TableQueryBuilder {
-    private client;
-    private name;
-    private conditions;
-    private orderField?;
-    private orderDir?;
-    private limitCount?;
-    private joinTable?;
-    constructor(client: Lux, name: string);
-    where(field: string, op: '=' | '!=' | '>' | '<' | '>=' | '<=', value: string | number | boolean): this;
-    orderBy(field: string, dir?: 'asc' | 'desc'): this;
-    limit(n: number): this;
-    join(table: string): this;
-    run(): Promise<TableRow[]>;
-    insert(data: Record<string, unknown>): Promise<number>;
-    update(id: number, data: Record<string, unknown>): Promise<string>;
-    delete(...ids: number[]): Promise<number>;
-}
-declare class VectorNamespace {
-    private client;
-    constructor(client: Lux);
-    set(key: string, vector: number[], metadata?: Record<string, unknown>): Promise<string>;
-    get(key: string): Promise<{
-        dims: number;
-        vector: number[];
-        metadata?: Record<string, unknown>;
-    } | null>;
-    search(query: number[], options: {
-        topK: number;
-        filter?: {
-            key: string;
-            value: string;
-        };
-        meta?: boolean;
-    }): Promise<VSearchResult[]>;
-    count(): Promise<number>;
-}
-declare class TimeSeriesNamespace {
-    private client;
-    constructor(client: Lux);
-    add(key: string, value: number, options?: {
-        timestamp?: number | '*';
-        retention?: number;
-        labels?: Record<string, string>;
-    }): Promise<number>;
-    get(key: string): Promise<TSSample | null>;
-    range(key: string, from: number | '-', to: number | '+', options?: TSRangeOptions): Promise<TSSample[]>;
-    mrange(from: number | '-', to: number | '+', filter: string, options?: TSRangeOptions): Promise<TSMRangeResult[]>;
-    info(key: string): Promise<Record<string, unknown>>;
-}
+import { TimeSeriesNamespace, VectorNamespace } from './namespaces';
+import { TableQueryBuilder, type TableQueryBuilderOptions } from './table';
+import type { KSubEvent, TableRow, TSAddOptions, TSMRangeResult, TSRangeOptions, TSSample, VSearchResult } from './types';
+export type { KSubEvent, LuxError, LuxResult, TableChangeEvent, TableChangeType, TableErrorEvent, TableRow, TableSchema, TSAddOptions, TSMRangeResult, TSRangeOptions, TSSample, VSearchResult, } from './types';
+export { TableQueryBuilder, TableSubscription } from './table';
+export type { TableQueryBuilderOptions } from './table';
 export declare class Lux extends Redis {
     vectors: VectorNamespace;
     timeseries: TimeSeriesNamespace;
+    private realtimeManager?;
     constructor(options?: RedisOptions | string);
-    table(name: string): TableQueryBuilder;
-    _tquery(args: string[]): Promise<TableRow[]>;
+    table<T extends TableRow = TableRow>(name: string, options?: TableQueryBuilderOptions<T>): TableQueryBuilder<T>;
+    _subscribePattern(pattern: string, handler: (event: KSubEvent) => void): Promise<() => void>;
+    _tselect(args: string[]): Promise<TableRow[]>;
     vset(key: string, vector: number[], options?: {
         metadata?: Record<string, unknown>;
         ex?: number;
@@ -118,4 +43,5 @@ export declare class Lux extends Redis {
         connection: Redis;
     };
 }
+export declare function createClient(options?: RedisOptions | string): Lux;
 export default Lux;

package/dist/index.js

@@ -3,108 +3,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Lux = void 0;
+exports.Lux = exports.TableSubscription = exports.TableQueryBuilder = void 0;
+exports.createClient = createClient;
 const ioredis_1 = __importDefault(require("ioredis"));
-class TableQueryBuilder {
-    constructor(client, name) {
-        this.conditions = [];
-        this.client = client;
-        this.name = name;
-    }
-    where(field, op, value) {
-        const v = typeof value === 'string' ? `'${value}'` : String(value);
-        this.conditions.push(`${field} ${op} ${v}`);
-        return this;
-    }
-    orderBy(field, dir = 'asc') {
-        this.orderField = field;
-        this.orderDir = dir.toUpperCase();
-        return this;
-    }
-    limit(n) {
-        this.limitCount = n;
-        return this;
-    }
-    join(table) {
-        this.joinTable = table;
-        return this;
-    }
-    async run() {
-        const args = [this.name];
-        if (this.conditions.length) {
-            args.push('WHERE', this.conditions.join(' AND '));
-        }
-        if (this.orderField) {
-            args.push('ORDER', 'BY', this.orderField, this.orderDir || 'ASC');
-        }
-        if (this.limitCount != null) {
-            args.push('LIMIT', String(this.limitCount));
-        }
-        if (this.joinTable) {
-            args.push('JOIN', this.joinTable);
-        }
-        return this.client._tquery(args);
-    }
-    async insert(data) {
-        const args = [this.name];
-        for (const [k, v] of Object.entries(data)) {
-            args.push(k, String(v));
-        }
-        const result = await this.client.call('TINSERT', ...args);
-        return parseInt(result, 10) || 0;
-    }
-    async update(id, data) {
-        const args = [this.name, id];
-        for (const [k, v] of Object.entries(data)) {
-            args.push(k, String(v));
-        }
-        return this.client.call('TUPDATE', ...args);
-    }
-    async delete(...ids) {
-        return this.client.call('TDEL', this.name, ...ids);
-    }
-}
-class VectorNamespace {
-    constructor(client) {
-        this.client = client;
-    }
-    async set(key, vector, metadata) {
-        const args = [key, vector.length, ...vector];
-        if (metadata) {
-            args.push('META', JSON.stringify(metadata));
-        }
-        return this.client.call('VSET', ...args);
-    }
-    async get(key) {
-        return this.client.vget(key);
-    }
-    async search(query, options) {
-        return this.client.vsearch(query, { k: options.topK, filter: options.filter, meta: options.meta ?? true });
-    }
-    async count() {
-        return this.client.vcard();
-    }
-}
-class TimeSeriesNamespace {
-    constructor(client) {
-        this.client = client;
-    }
-    async add(key, value, options) {
-        return this.client.tsadd(key, options?.timestamp ?? '*', value, { retention: options?.retention, labels: options?.labels });
-    }
-    async get(key) {
-        return this.client.tsget(key);
-    }
-    async range(key, from, to, options) {
-        return this.client.tsrange(key, from, to, options);
-    }
-    async mrange(from, to, filter, options) {
-        return this.client.tsmrange(from, to, filter, options);
-    }
-    async info(key) {
-        return this.client.tsinfo(key);
-    }
-}
+const namespaces_1 = require("./namespaces");
+const realtime_1 = require("./realtime");
+const table_1 = require("./table");
+var table_2 = require("./table");
+Object.defineProperty(exports, "TableQueryBuilder", { enumerable: true, get: function () { return table_2.TableQueryBuilder; } });
+Object.defineProperty(exports, "TableSubscription", { enumerable: true, get: function () { return table_2.TableSubscription; } });
 class Lux extends ioredis_1.default {
     constructor(options) {
         if (typeof options === 'string') {
@@ -114,25 +21,37 @@ class Lux extends ioredis_1.default {
             options = options.replace(/^lux:\/\//, 'redis://');
         }
         super(options);
-        this.vectors = new VectorNamespace(this);
-        this.timeseries = new TimeSeriesNamespace(this);
+        this.vectors = new namespaces_1.VectorNamespace(this);
+        this.timeseries = new namespaces_1.TimeSeriesNamespace(this);
     }
-    table(name) {
-        return new TableQueryBuilder(this, name);
+    table(name, options) {
+        return new table_1.TableQueryBuilder(this, name, options);
+    }
+    async _subscribePattern(pattern, handler) {
+        if (!this.realtimeManager) {
+            this.realtimeManager = new realtime_1.LuxRealtimeManager(this);
+        }
+        return this.realtimeManager.subscribe(pattern, handler);
     }
-    async _tquery(args) {
-        const result = await this.call('TQUERY', ...args);
+    async _tselect(args) {
+        const result = await this.call('TSELECT', ...args);
         if (!result || !Array.isArray(result))
             return [];
         const rows = [];
         for (const item of result) {
-            if (Array.isArray(item) && item.length >= 1) {
-                const row = { id: parseInt(item[0], 10) };
-                for (let i = 1; i < item.length - 1; i += 2) {
+            if (Array.isArray(item)) {
+                const row = {};
+                for (let i = 0; i < item.length - 1; i += 2) {
                     const key = String(item[i]);
                     const val = item[i + 1];
                     row[key] = val;
                 }
+                if (row.id != null) {
+                    const parsed = Number(row.id);
+                    if (!Number.isNaN(parsed) && Number.isFinite(parsed)) {
+                        row.id = parsed;
+                    }
+                }
                 rows.push(row);
             }
         }
@@ -320,4 +239,7 @@ class Lux extends ioredis_1.default {
     }
 }
 exports.Lux = Lux;
+function createClient(options) {
+    return new Lux(options);
+}
 exports.default = Lux;

package/dist/namespaces.d.ts

@@ -0,0 +1,56 @@
+import type { TSAddOptions, TSMRangeResult, TSRangeOptions, TSSample, VSearchResult } from './types';
+interface NamespaceClient {
+    call(command: string, ...args: Array<string | number>): Promise<unknown>;
+    vget(key: string): Promise<{
+        dims: number;
+        vector: number[];
+        metadata?: Record<string, unknown>;
+    } | null>;
+    vsearch(query: number[], options: {
+        k: number;
+        filter?: {
+            key: string;
+            value: string;
+        };
+        meta?: boolean;
+    }): Promise<VSearchResult[]>;
+    vcard(): Promise<number>;
+    tsadd(key: string, timestamp: number | '*', value: number, options?: TSAddOptions): Promise<number>;
+    tsget(key: string): Promise<TSSample | null>;
+    tsrange(key: string, from: number | '-', to: number | '+', options?: TSRangeOptions): Promise<TSSample[]>;
+    tsmrange(from: number | '-', to: number | '+', filter: string, options?: TSRangeOptions): Promise<TSMRangeResult[]>;
+    tsinfo(key: string): Promise<Record<string, unknown>>;
+}
+export declare class VectorNamespace {
+    private client;
+    constructor(client: NamespaceClient);
+    set(key: string, vector: number[], metadata?: Record<string, unknown>): Promise<string>;
+    get(key: string): Promise<{
+        dims: number;
+        vector: number[];
+        metadata?: Record<string, unknown>;
+    } | null>;
+    search(query: number[], options: {
+        topK: number;
+        filter?: {
+            key: string;
+            value: string;
+        };
+        meta?: boolean;
+    }): Promise<VSearchResult[]>;
+    count(): Promise<number>;
+}
+export declare class TimeSeriesNamespace {
+    private client;
+    constructor(client: NamespaceClient);
+    add(key: string, value: number, options?: {
+        timestamp?: number | '*';
+        retention?: number;
+        labels?: Record<string, string>;
+    }): Promise<number>;
+    get(key: string): Promise<TSSample | null>;
+    range(key: string, from: number | '-', to: number | '+', options?: TSRangeOptions): Promise<TSSample[]>;
+    mrange(from: number | '-', to: number | '+', filter: string, options?: TSRangeOptions): Promise<TSMRangeResult[]>;
+    info(key: string): Promise<Record<string, unknown>>;
+}
+export {};

package/dist/namespaces.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeSeriesNamespace = exports.VectorNamespace = void 0;
+class VectorNamespace {
+    constructor(client) {
+        this.client = client;
+    }
+    async set(key, vector, metadata) {
+        const args = [key, vector.length, ...vector];
+        if (metadata) {
+            args.push('META', JSON.stringify(metadata));
+        }
+        return this.client.call('VSET', ...args);
+    }
+    async get(key) {
+        return this.client.vget(key);
+    }
+    async search(query, options) {
+        return this.client.vsearch(query, { k: options.topK, filter: options.filter, meta: options.meta ?? true });
+    }
+    async count() {
+        return this.client.vcard();
+    }
+}
+exports.VectorNamespace = VectorNamespace;
+class TimeSeriesNamespace {
+    constructor(client) {
+        this.client = client;
+    }
+    async add(key, value, options) {
+        return this.client.tsadd(key, options?.timestamp ?? '*', value, { retention: options?.retention, labels: options?.labels });
+    }
+    async get(key) {
+        return this.client.tsget(key);
+    }
+    async range(key, from, to, options) {
+        return this.client.tsrange(key, from, to, options);
+    }
+    async mrange(from, to, filter, options) {
+        return this.client.tsmrange(from, to, filter, options);
+    }
+    async info(key) {
+        return this.client.tsinfo(key);
+    }
+}
+exports.TimeSeriesNamespace = TimeSeriesNamespace;

package/dist/realtime.d.ts

@@ -0,0 +1,16 @@
+import type Redis from 'ioredis';
+import type { KSubEvent } from './types';
+interface RealtimeClient {
+    duplicate(): Redis;
+}
+export declare class LuxRealtimeManager {
+    private client;
+    private connection;
+    private initPromise;
+    private nextHandlerId;
+    private handlersByPattern;
+    constructor(client: RealtimeClient);
+    private ensureConnection;
+    subscribe(pattern: string, handler: (event: KSubEvent) => void): Promise<() => void>;
+}
+export {};

package/dist/realtime.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LuxRealtimeManager = void 0;
+class LuxRealtimeManager {
+    constructor(client) {
+        this.connection = null;
+        this.initPromise = null;
+        this.nextHandlerId = 1;
+        this.handlersByPattern = new Map();
+        this.client = client;
+    }
+    async ensureConnection() {
+        if (this.connection)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = (async () => {
+            const sub = this.client.duplicate();
+            sub.on('error', () => { });
+            const dispatch = (event) => {
+                const handlers = this.handlersByPattern.get(event.pattern);
+                if (!handlers)
+                    return;
+                for (const handler of handlers.values()) {
+                    handler(event);
+                }
+            };
+            const dataHandler = sub._dataHandler || sub.dataHandler;
+            if (dataHandler && dataHandler.returnReply) {
+                const origReturn = dataHandler.returnReply.bind(dataHandler);
+                dataHandler.returnReply = (reply) => {
+                    if (Array.isArray(reply) && reply.length === 4 && reply[0] === 'kmessage') {
+                        dispatch({ pattern: reply[1], key: reply[2], operation: reply[3] });
+                        return;
+                    }
+                    return origReturn(reply);
+                };
+            }
+            else {
+                const origEmit = sub.emit.bind(sub);
+                sub.emit = (event, ...args) => {
+                    if (event === 'error' && args[0]?.message?.includes('Command queue state error')) {
+                        const match = args[0].message.match(/Last reply: kmessage,([^,]+),([^,]+),(.+)/);
+                        if (match) {
+                            dispatch({ pattern: match[1], key: match[2], operation: match[3] });
+                            return true;
+                        }
+                    }
+                    return origEmit(event, ...args);
+                };
+            }
+            this.connection = sub;
+        })();
+        try {
+            await this.initPromise;
+        }
+        finally {
+            this.initPromise = null;
+        }
+    }
+    async subscribe(pattern, handler) {
+        await this.ensureConnection();
+        const id = this.nextHandlerId++;
+        let handlers = this.handlersByPattern.get(pattern);
+        const firstForPattern = !handlers;
+        if (!handlers) {
+            handlers = new Map();
+            this.handlersByPattern.set(pattern, handlers);
+        }
+        handlers.set(id, handler);
+        if (firstForPattern && this.connection) {
+            await this.connection.call('KSUB', pattern);
+        }
+        return () => {
+            const map = this.handlersByPattern.get(pattern);
+            if (!map)
+                return;
+            map.delete(id);
+            if (map.size === 0) {
+                this.handlersByPattern.delete(pattern);
+                if (this.connection) {
+                    this.connection.call('KUNSUB', pattern).catch(() => { });
+                }
+            }
+        };
+    }
+}
+exports.LuxRealtimeManager = LuxRealtimeManager;

package/dist/table.d.ts

@@ -0,0 +1,83 @@
+import type { KSubEvent, LuxError, LuxResult, TableChangeEvent, TableErrorEvent, TableRow, TableSchema, VSearchResult } from './types';
+type TableWhereOp = '=' | '!=' | '>' | '<' | '>=' | '<=';
+type TableWhereValue = string | number | boolean;
+interface TableWhereCondition {
+    field: string;
+    op: TableWhereOp;
+    value: TableWhereValue;
+}
+interface TableClient {
+    call(command: string, ...args: Array<string | number>): Promise<unknown>;
+    _tselect(args: string[]): Promise<TableRow[]>;
+    _subscribePattern(pattern: string, handler: (event: KSubEvent) => void): Promise<() => void>;
+    vsearch(query: number[], options: {
+        k: number;
+        filter?: {
+            key: string;
+            value: string;
+        };
+        meta?: boolean;
+    }): Promise<VSearchResult[]>;
+}
+export interface TableQueryBuilderOptions<T extends TableRow> {
+    schema?: TableSchema<T>;
+}
+export declare class TableSubscription<T extends TableRow> {
+    private client;
+    private table;
+    private selectArgsBuilder;
+    private handlers;
+    private knownRows;
+    private unsubscribeFn;
+    private initError;
+    constructor(client: TableClient, table: string, selectArgsBuilder: (extra?: TableWhereCondition[]) => string[], initError?: LuxError | null);
+    on(event: 'insert' | 'update' | 'delete' | 'change', handler: (event: TableChangeEvent<T>) => void): this;
+    on(event: 'error', handler: (event: TableErrorEvent) => void): this;
+    unsubscribe(): Promise<void>;
+    private emitError;
+    private emitChange;
+    private extractPkFromKey;
+    private fetchMatches;
+    private start;
+    private handleRawChange;
+}
+export declare class TableQueryBuilder<T extends TableRow = TableRow> {
+    private client;
+    private name;
+    private conditions;
+    private orderField?;
+    private orderDir?;
+    private limitCount?;
+    private offsetCount?;
+    private joinClause?;
+    private similarityClause?;
+    private selectClause;
+    private expectSingle;
+    private schema?;
+    constructor(client: TableClient, name: string, options?: TableQueryBuilderOptions<T>);
+    private validateRow;
+    private buildSelectArgs;
+    select(columns?: string): this;
+    single(): this;
+    where(field: string, op: TableWhereOp, value: TableWhereValue): this;
+    orderBy(field: string, dir?: 'asc' | 'desc'): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    join(table: string, alias: string, onLeft: string, onRight: string): this;
+    similar(field: string, vector: number[], options: {
+        k: number;
+        filter?: {
+            key: string;
+            value: string;
+        };
+    }): this;
+    private parseSimilarityPk;
+    run(): Promise<LuxResult<T[] | T>>;
+    insert(data: Record<string, unknown>): Promise<LuxResult<number>>;
+    update(id: number | string, data: Record<string, unknown>): Promise<LuxResult<number>>;
+    updateWhere(data: Record<string, unknown>): Promise<LuxResult<number>>;
+    delete(...ids: Array<number | string>): Promise<LuxResult<number>>;
+    deleteWhere(): Promise<LuxResult<number>>;
+    subscribe(): TableSubscription<T>;
+}
+export {};

package/dist/table.js

@@ -0,0 +1,384 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableQueryBuilder = exports.TableSubscription = void 0;
+const utils_1 = require("./utils");
+class TableSubscription {
+    constructor(client, table, selectArgsBuilder, initError = null) {
+        this.handlers = {
+            change: [],
+            insert: [],
+            update: [],
+            delete: [],
+            error: [],
+        };
+        this.knownRows = new Map();
+        this.unsubscribeFn = null;
+        this.client = client;
+        this.table = table;
+        this.selectArgsBuilder = selectArgsBuilder;
+        this.initError = initError;
+        void this.start();
+    }
+    on(event, handler) {
+        this.handlers[event].push(handler);
+        return this;
+    }
+    async unsubscribe() {
+        if (this.unsubscribeFn) {
+            this.unsubscribeFn();
+            this.unsubscribeFn = null;
+        }
+    }
+    emitError(error) {
+        for (const handler of this.handlers.error) {
+            handler({ type: 'error', table: this.table, error });
+        }
+    }
+    emitChange(event) {
+        for (const handler of this.handlers.change)
+            handler(event);
+        for (const handler of this.handlers[event.type])
+            handler(event);
+    }
+    extractPkFromKey(key) {
+        const prefix = `_t:${this.table}:row:`;
+        if (!key.startsWith(prefix))
+            return null;
+        return key.slice(prefix.length);
+    }
+    async fetchMatches(extra) {
+        const args = this.selectArgsBuilder(extra);
+        const rows = await this.client._tselect(args);
+        return rows;
+    }
+    async start() {
+        if (this.initError) {
+            this.emitError(this.initError);
+            return;
+        }
+        try {
+            const initial = await this.fetchMatches();
+            for (const row of initial) {
+                if (row.id == null)
+                    continue;
+                this.knownRows.set(String(row.id), row);
+            }
+            const pattern = `_t:${this.table}:row:*`;
+            this.unsubscribeFn = await this.client._subscribePattern(pattern, (raw) => {
+                void this.handleRawChange(raw);
+            });
+        }
+        catch (error) {
+            this.emitError((0, utils_1.toLuxError)(error, 'LUX_SUBSCRIBE_INIT_ERROR'));
+        }
+    }
+    async handleRawChange(raw) {
+        const pk = this.extractPkFromKey(raw.key);
+        if (!pk)
+            return;
+        try {
+            const previous = this.knownRows.get(pk) ?? null;
+            const rows = await this.fetchMatches([{ field: 'id', op: '=', value: pk }]);
+            const next = rows[0] ?? null;
+            if (!previous && !next)
+                return;
+            if (!previous && next) {
+                this.knownRows.set(pk, next);
+                this.emitChange({
+                    type: 'insert',
+                    table: this.table,
+                    pk,
+                    operation: raw.operation,
+                    new: next,
+                    old: null,
+                    raw,
+                });
+                return;
+            }
+            if (previous && !next) {
+                this.knownRows.delete(pk);
+                this.emitChange({
+                    type: 'delete',
+                    table: this.table,
+                    pk,
+                    operation: raw.operation,
+                    new: null,
+                    old: previous,
+                    raw,
+                });
+                return;
+            }
+            if (!previous || !next)
+                return;
+            this.knownRows.set(pk, next);
+            const changed = Object.keys(next).filter((key) => previous[key] !== next[key]);
+            this.emitChange({
+                type: 'update',
+                table: this.table,
+                pk,
+                operation: raw.operation,
+                new: next,
+                old: previous,
+                changed,
+                raw,
+            });
+        }
+        catch (error) {
+            this.emitError((0, utils_1.toLuxError)(error, 'LUX_SUBSCRIBE_EVENT_ERROR'));
+        }
+    }
+}
+exports.TableSubscription = TableSubscription;
+class TableQueryBuilder {
+    constructor(client, name, options) {
+        this.conditions = [];
+        this.selectClause = '*';
+        this.expectSingle = false;
+        this.client = client;
+        this.name = name;
+        this.schema = options?.schema;
+    }
+    validateRow(row) {
+        if (!this.schema)
+            return row;
+        if (this.schema.safeParse) {
+            const parsed = this.schema.safeParse(row);
+            if (!parsed.success) {
+                throw new Error('row failed schema validation');
+            }
+            return parsed.data;
+        }
+        if (this.schema.parse) {
+            return this.schema.parse(row);
+        }
+        return row;
+    }
+    buildSelectArgs(extra) {
+        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);
+        }
+        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');
+                }
+            }
+        }
+        if (this.orderField) {
+            args.push('ORDER', 'BY', this.orderField, this.orderDir || 'ASC');
+        }
+        if (this.limitCount != null) {
+            args.push('LIMIT', String(this.limitCount));
+        }
+        if (this.offsetCount != null) {
+            args.push('OFFSET', String(this.offsetCount));
+        }
+        return args;
+    }
+    select(columns = '*') {
+        this.selectClause = columns;
+        return this;
+    }
+    single() {
+        this.expectSingle = true;
+        if (this.limitCount == null) {
+            this.limitCount = 1;
+        }
+        return this;
+    }
+    where(field, op, value) {
+        this.conditions.push({ field, op, value });
+        return this;
+    }
+    orderBy(field, dir = 'asc') {
+        this.orderField = field;
+        this.orderDir = dir.toUpperCase();
+        return this;
+    }
+    limit(n) {
+        this.limitCount = n;
+        return this;
+    }
+    offset(n) {
+        this.offsetCount = n;
+        return this;
+    }
+    join(table, alias, onLeft, onRight) {
+        this.joinClause = { table, alias, onLeft, onRight };
+        return this;
+    }
+    similar(field, vector, options) {
+        this.similarityClause = {
+            field,
+            vector,
+            k: options.k,
+            filter: options.filter,
+        };
+        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;
+    }
+    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 validated = rows.map((row) => this.validateRow(row));
+            if (this.expectSingle) {
+                if (validated.length === 0) {
+                    return (0, utils_1.err)('NOT_FOUND', `No rows found in table '${this.name}'`);
+                }
+                return (0, utils_1.ok)(validated[0]);
+            }
+            return (0, utils_1.ok)(validated);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TSELECT_ERROR', `Failed to query table '${this.name}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
+    async insert(data) {
+        try {
+            if (this.schema) {
+                this.validateRow(data);
+            }
+            const args = [this.name];
+            for (const [k, v] of Object.entries(data)) {
+                args.push(k, String(v));
+            }
+            const result = await this.client.call('TINSERT', ...args);
+            return (0, utils_1.ok)(parseInt(result, 10) || 0);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TINSERT_ERROR', `Failed to insert into '${this.name}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
+    async update(id, data) {
+        try {
+            const args = [this.name, 'SET'];
+            for (const [k, v] of Object.entries(data)) {
+                args.push(k, String(v));
+            }
+            args.push('WHERE', 'id', '=', String(id));
+            const result = await this.client.call('TUPDATE', ...args);
+            return (0, utils_1.ok)(Number(result) || 0);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TUPDATE_ERROR', `Failed to update '${this.name}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
+    async updateWhere(data) {
+        if (this.conditions.length === 0) {
+            return (0, utils_1.err)('MISSING_WHERE', 'updateWhere requires at least one where() condition');
+        }
+        try {
+            const args = [this.name, 'SET'];
+            for (const [k, v] of Object.entries(data)) {
+                args.push(k, String(v));
+            }
+            args.push('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');
+                }
+            }
+            const result = await this.client.call('TUPDATE', ...args);
+            return (0, utils_1.ok)(Number(result) || 0);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TUPDATE_ERROR', `Failed to update '${this.name}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
+    async delete(...ids) {
+        try {
+            let deleted = 0;
+            for (const id of ids) {
+                const result = await this.client.call('TDELETE', 'FROM', this.name, 'WHERE', 'id', '=', String(id));
+                deleted += Number(result) || 0;
+            }
+            return (0, utils_1.ok)(deleted);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TDELETE_ERROR', `Failed to delete from '${this.name}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
+    async deleteWhere() {
+        if (this.conditions.length === 0) {
+            return (0, utils_1.err)('MISSING_WHERE', 'deleteWhere requires at least one where() condition');
+        }
+        try {
+            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');
+                }
+            }
+            const result = await this.client.call('TDELETE', ...args);
+            return (0, utils_1.ok)(Number(result) || 0);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TDELETE_ERROR', `Failed to delete from '${this.name}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
+    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));
+    }
+}
+exports.TableQueryBuilder = TableQueryBuilder;

package/dist/types.d.ts

@@ -0,0 +1,70 @@
+export interface VSearchResult {
+    key: string;
+    similarity: number;
+    metadata?: Record<string, unknown>;
+}
+export interface TSSample {
+    timestamp: number;
+    value: number;
+}
+export interface TSAddOptions {
+    retention?: number;
+    labels?: Record<string, string>;
+}
+export interface TSRangeOptions {
+    aggregation?: {
+        type: 'avg' | 'sum' | 'min' | 'max' | 'count' | 'first' | 'last' | 'range' | 'std.p' | 'std.s' | 'var.p' | 'var.s';
+        bucketSize: number;
+    };
+}
+export interface TSMRangeResult {
+    key: string;
+    labels: Record<string, string>;
+    samples: TSSample[];
+}
+export interface KSubEvent {
+    pattern: string;
+    key: string;
+    operation: string;
+}
+export interface TableRow {
+    id?: number | string;
+    [field: string]: unknown;
+}
+export interface LuxError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface LuxResult<T> {
+    data: T | null;
+    error: LuxError | null;
+}
+type SchemaSafeParse<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: unknown;
+};
+export interface TableSchema<T> {
+    parse?: (input: unknown) => T;
+    safeParse?: (input: unknown) => SchemaSafeParse<T>;
+}
+export type TableChangeType = 'insert' | 'update' | 'delete' | 'change' | 'error';
+export interface TableChangeEvent<T extends TableRow> {
+    type: Exclude<TableChangeType, 'error'>;
+    table: string;
+    pk: string;
+    operation: string;
+    new: T | null;
+    old: T | null;
+    changed?: string[];
+    raw?: KSubEvent;
+}
+export interface TableErrorEvent {
+    type: 'error';
+    table: string;
+    error: LuxError;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+import type { LuxError, LuxResult } from './types';
+export declare function ok<T>(data: T): LuxResult<T>;
+export declare function err<T>(code: string, message: string, details?: unknown): LuxResult<T>;
+export declare function toLuxError(error: unknown, fallbackCode?: string): LuxError;

package/dist/utils.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ok = ok;
+exports.err = err;
+exports.toLuxError = toLuxError;
+function ok(data) {
+    return { data, error: null };
+}
+function err(code, message, details) {
+    return { data: null, error: { code, message, details } };
+}
+function toLuxError(error, fallbackCode = 'LUX_SDK_ERROR') {
+    if (typeof error === 'object' && error && 'message' in error) {
+        return { code: fallbackCode, message: String(error.message), details: error };
+    }
+    return { code: fallbackCode, message: String(error) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luxdb/sdk",
-    "version": "1.2.1",
+    "version": "1.3.0",
     "description": "Lux SDK - ioredis extended with vector search, time series, and realtime key subscriptions",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",