@luxdb/sdk 1.4.2 → 2.0.0

package/dist/cjs/table.js

@@ -2,6 +2,41 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TableQueryBuilder = exports.TableSubscription = void 0;
 const utils_1 = require("./utils");
+/** Serialize a field value: JSON objects/arrays round-trip as JSON text. */
+function serializeFieldValue(v) {
+    if (v !== null && typeof v === 'object') {
+        return JSON.stringify(v);
+    }
+    return String(v);
+}
+/** Serialize one WHERE condition into RESP tokens. */
+function serializeCondition(cond) {
+    if (cond.op === 'IN' || cond.op === 'NOT IN') {
+        const values = Array.isArray(cond.value) ? cond.value : [cond.value];
+        return [
+            cond.field,
+            ...(cond.op === 'NOT IN' ? ['NOT', 'IN'] : ['IN']),
+            '(',
+            ...values.map(String),
+            ')',
+        ];
+    }
+    if (cond.op === 'IS VALID')
+        return [cond.field, 'IS', 'VALID'];
+    if (cond.op === 'IS NOT VALID')
+        return [cond.field, 'IS', 'NOT', 'VALID'];
+    return [cond.field, cond.op, String(cond.value)];
+}
+/** Join serialized conditions with AND separators. */
+function serializeConditions(conditions) {
+    const out = [];
+    for (let i = 0; i < conditions.length; i++) {
+        out.push(...serializeCondition(conditions[i]));
+        if (i < conditions.length - 1)
+            out.push('AND');
+    }
+    return out;
+}
 class TableSubscription {
     constructor(client, table, selectArgsBuilder, initError = null) {
         this.handlers = {
@@ -59,9 +94,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 +147,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 +170,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,18 +197,30 @@ 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');
-            for (let i = 0; i < allConditions.length; i++) {
-                const cond = allConditions[i];
+            args.push('WHERE', ...serializeConditions(allConditions));
+        }
+        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 < allConditions.length - 1) {
+                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');
         }
@@ -213,6 +265,29 @@ class TableQueryBuilder {
     lte(field, value) {
         return this.where(field, '<=', value);
     }
+    in(field, values) {
+        this.conditions.push({ field, op: 'IN', value: values });
+        return this;
+    }
+    notIn(field, values) {
+        this.conditions.push({ field, op: 'NOT IN', value: values });
+        return this;
+    }
+    /** Match rows where a JSON dot-path resolves to a present, non-null value. */
+    isValid(field) {
+        this.conditions.push({ field, op: 'IS VALID', value: '' });
+        return this;
+    }
+    /** Match rows where a JSON dot-path is absent or resolves to null. */
+    isNotValid(field) {
+        this.conditions.push({ field, op: 'IS NOT VALID', value: '' });
+        return this;
+    }
+    /** Match rows where an ARRAY column (or array-valued path) contains a value. */
+    contains(field, value) {
+        this.conditions.push({ field, op: 'CONTAINS', value });
+        return this;
+    }
     orderBy(field, dir = 'asc') {
         this.orderField = field;
         this.orderDir = dir.toUpperCase();
@@ -230,68 +305,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) {
@@ -315,7 +363,7 @@ class TableQueryBuilder {
             }
             const args = [this.name];
             for (const [k, v] of Object.entries(data)) {
-                args.push(k, String(v));
+                args.push(k, serializeFieldValue(v));
             }
             const result = await this.client.call('TINSERT', ...args);
             return (0, utils_1.ok)(parseInt(result, 10) || 0);
@@ -324,6 +372,26 @@ class TableQueryBuilder {
             return (0, utils_1.err)('TINSERT_ERROR', `Failed to insert into '${this.name}'`, (0, utils_1.toLuxError)(error));
         }
     }
+    /** Declare a typed index on a JSON dot-path, e.g. ('meta.reactions.count', 'int'). */
+    async createIndex(path, type) {
+        try {
+            await this.client.call('TINDEX', this.name, path, type.toUpperCase());
+            return (0, utils_1.ok)(true);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TINDEX_ERROR', `Failed to index '${path}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
+    /** Drop a previously declared JSON path index. */
+    async dropIndex(path) {
+        try {
+            await this.client.call('TDROPINDEX', this.name, path);
+            return (0, utils_1.ok)(true);
+        }
+        catch (error) {
+            return (0, utils_1.err)('TDROPINDEX_ERROR', `Failed to drop index '${path}'`, (0, utils_1.toLuxError)(error));
+        }
+    }
     async update(idOrData, data) {
         try {
             const hasExplicitId = data !== undefined;
@@ -333,20 +401,14 @@ class TableQueryBuilder {
             }
             const args = [this.name, 'SET'];
             for (const [k, v] of Object.entries(patch)) {
-                args.push(k, String(v));
+                args.push(k, serializeFieldValue(v));
             }
             args.push('WHERE');
             if (hasExplicitId) {
                 args.push('id', '=', String(idOrData));
             }
             else {
-                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');
-                    }
-                }
+                args.push(...serializeConditions(this.conditions));
             }
             const result = await this.client.call('TUPDATE', ...args);
             return (0, utils_1.ok)(Number(result) || 0);
@@ -362,13 +424,7 @@ class TableQueryBuilder {
                     return (0, utils_1.err)('MISSING_WHERE', 'delete requires at least one filter');
                 }
                 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');
-                    }
-                }
+                args.push(...serializeConditions(this.conditions));
                 const result = await this.client.call('TDELETE', ...args);
                 return (0, utils_1.ok)(Number(result) || 0);
             }
@@ -384,12 +440,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));
     }
 }

package/dist/esm/index.js

@@ -5,6 +5,7 @@ import { TimeSeriesNamespace, VectorNamespace } from './namespaces.js';
 import { LuxRealtimeManager } from './realtime.js';
 import { TableQueryBuilder } from './table.js';
 export { createProjectClient, LuxProjectClient, };
+export { LuxProjectLiveSubscription } from './project.js';
 export { createBrowserClient } from './browser.js';
 export { createServerClient } from './ssr.js';
 export { TableQueryBuilder, TableSubscription } from './table.js';