@luxdb/sdk 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,19 +1,93 @@
-import Redis, { RedisOptions } from 'ioredis';
+import Redis, { type RedisOptions } from 'ioredis';
 export interface VSearchResult {
     key: string;
     similarity: number;
     metadata?: Record<string, unknown>;
 }
-export interface VSearchOptions {
-    k: number;
-    filter?: {
-        key: string;
-        value: string;
+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;
     };
-    meta?: boolean;
+}
+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>>;
 }
 export declare class Lux extends Redis {
+    vectors: VectorNamespace;
+    timeseries: TimeSeriesNamespace;
     constructor(options?: RedisOptions | string);
+    table(name: string): TableQueryBuilder;
+    _tquery(args: string[]): Promise<TableRow[]>;
     vset(key: string, vector: number[], options?: {
         metadata?: Record<string, unknown>;
         ex?: number;
@@ -24,7 +98,24 @@ export declare class Lux extends Redis {
         vector: number[];
         metadata?: Record<string, unknown>;
     } | null>;
-    vsearch(query: number[], options: VSearchOptions): Promise<VSearchResult[]>;
+    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>;
+    tsmadd(...entries: [string, number | '*', number][]): Promise<string>;
+    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>>;
+    ksub(patterns: string[], handler: (event: KSubEvent) => void): {
+        unsubscribe: () => void;
+        connection: Redis;
+    };
 }
 export default Lux;

package/dist/index.js

@@ -5,10 +5,139 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Lux = void 0;
 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);
+    }
+}
 class Lux extends ioredis_1.default {
     constructor(options) {
         super(options);
+        this.vectors = new VectorNamespace(this);
+        this.timeseries = new TimeSeriesNamespace(this);
+    }
+    table(name) {
+        return new TableQueryBuilder(this, name);
     }
+    async _tquery(args) {
+        const result = await this.call('TQUERY', ...args);
+        if (!result || !Array.isArray(result))
+            return [];
+        const rows = [];
+        for (const item of result) {
+            if (Array.isArray(item) && item.length >= 2) {
+                const row = { id: 0 };
+                for (let i = 0; i < item.length - 1; i += 2) {
+                    const key = String(item[i]);
+                    const val = item[i + 1];
+                    if (key === 'id') {
+                        row.id = parseInt(val, 10);
+                    }
+                    else {
+                        row[key] = val;
+                    }
+                }
+                rows.push(row);
+            }
+        }
+        return rows;
+    }
+    // Vector methods (keep for backward compat)
     async vset(key, vector, options) {
         const args = [key, vector.length, ...vector];
         if (options?.metadata) {
@@ -23,7 +152,7 @@ class Lux extends ioredis_1.default {
         return this.call('VSET', ...args);
     }
     async vget(key) {
-        const result = (await this.call('VGET', key));
+        const result = await this.call('VGET', key);
         if (!result || !Array.isArray(result))
             return null;
         const dims = parseInt(result[0], 10);
@@ -49,16 +178,13 @@ class Lux extends ioredis_1.default {
         if (options.meta) {
             args.push('META');
         }
-        const result = (await this.call('VSEARCH', ...args));
+        const result = await this.call('VSEARCH', ...args);
         if (!result || !Array.isArray(result))
             return [];
         const results = [];
         for (const item of result) {
             if (Array.isArray(item)) {
-                const entry = {
-                    key: item[0],
-                    similarity: parseFloat(item[1]),
-                };
+                const entry = { key: item[0], similarity: parseFloat(item[1]) };
                 if (options.meta && item[2]) {
                     try {
                         entry.metadata = JSON.parse(item[2]);
@@ -75,6 +201,122 @@ class Lux extends ioredis_1.default {
     async vcard() {
         return this.call('VCARD');
     }
+    // Time series methods (keep for backward compat)
+    async tsadd(key, timestamp, value, options) {
+        const args = [key, timestamp === '*' ? '*' : timestamp, value];
+        if (options?.retention != null) {
+            args.push('RETENTION', options.retention);
+        }
+        if (options?.labels) {
+            args.push('LABELS');
+            for (const [k, v] of Object.entries(options.labels)) {
+                args.push(k, v);
+            }
+        }
+        return this.call('TSADD', ...args);
+    }
+    async tsmadd(...entries) {
+        const args = [];
+        for (const [key, ts, val] of entries) {
+            args.push(key, ts === '*' ? '*' : ts, val);
+        }
+        return this.call('TSMADD', ...args);
+    }
+    async tsget(key) {
+        const result = await this.call('TSGET', key);
+        if (!result || !Array.isArray(result) || result.length < 2)
+            return null;
+        return { timestamp: parseInt(result[0], 10), value: parseFloat(result[1]) };
+    }
+    async tsrange(key, from, to, options) {
+        const args = [key, from === '-' ? '-' : from, to === '+' ? '+' : to];
+        if (options?.aggregation) {
+            args.push('AGGREGATION', options.aggregation.type, options.aggregation.bucketSize);
+        }
+        const result = await this.call('TSRANGE', ...args);
+        if (!result || !Array.isArray(result))
+            return [];
+        return result.map((pair) => ({ timestamp: parseInt(pair[0], 10), value: parseFloat(pair[1]) }));
+    }
+    async tsmrange(from, to, filter, options) {
+        const args = [from === '-' ? '-' : from, to === '+' ? '+' : to];
+        if (options?.aggregation) {
+            args.push('AGGREGATION', options.aggregation.type, options.aggregation.bucketSize);
+        }
+        args.push('FILTER', filter);
+        const result = await this.call('TSMRANGE', ...args);
+        if (!result || !Array.isArray(result))
+            return [];
+        return result.map((series) => {
+            const labels = {};
+            if (Array.isArray(series[1])) {
+                for (const pair of series[1]) {
+                    if (Array.isArray(pair) && pair.length >= 2)
+                        labels[pair[0]] = pair[1];
+                }
+            }
+            const samples = Array.isArray(series[2])
+                ? series[2].map((s) => ({ timestamp: parseInt(s[0], 10), value: parseFloat(s[1]) }))
+                : [];
+            return { key: series[0], labels, samples };
+        });
+    }
+    async tsinfo(key) {
+        const result = await this.call('TSINFO', key);
+        if (!result || !Array.isArray(result))
+            return {};
+        const info = {};
+        for (let i = 0; i < result.length - 1; i += 2) {
+            const k = result[i];
+            const v = result[i + 1];
+            if (k === 'labels' && Array.isArray(v)) {
+                const labels = {};
+                for (const pair of v) {
+                    if (Array.isArray(pair) && pair.length >= 2)
+                        labels[pair[0]] = pair[1];
+                }
+                info[k] = labels;
+            }
+            else {
+                info[k] = v;
+            }
+        }
+        return info;
+    }
+    // Realtime key subscriptions
+    ksub(patterns, handler) {
+        const sub = this.duplicate();
+        sub.on('error', () => { });
+        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') {
+                    handler({ 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) {
+                        handler({ pattern: match[1], key: match[2], operation: match[3] });
+                        return true;
+                    }
+                }
+                return origEmit(event, ...args);
+            };
+        }
+        sub.call('KSUB', ...patterns);
+        return {
+            connection: sub,
+            unsubscribe() { sub.disconnect(); },
+        };
+    }
 }
 exports.Lux = Lux;
 exports.default = Lux;

package/package.json

@@ -1,18 +1,19 @@
 {
     "name": "@luxdb/sdk",
-    "version": "1.0.0",
-    "description": "Lux SDK - ioredis extended with native vector search",
+    "version": "1.2.0",
+    "description": "Lux SDK - ioredis extended with vector search, time series, and realtime key subscriptions",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "files": ["dist"],
     "scripts": {
         "build": "tsc",
-        "prepublishOnly": "npm run build"
+        "prepublishOnly": "bun run build"
     },
     "dependencies": {
         "ioredis": "^5.0.0"
     },
     "devDependencies": {
+        "@types/node": "^25.5.0",
         "typescript": "^5.9.0"
     },
     "peerDependencies": {
@@ -24,5 +25,5 @@
         "url": "https://github.com/lux-db/lux",
         "directory": "sdk"
     },
-    "keywords": ["lux", "redis", "vector", "search", "database", "ioredis", "similarity"]
+    "keywords": ["lux", "redis", "vector", "search", "database", "ioredis", "similarity", "timeseries", "realtime", "subscriptions"]
 }