@luxdb/sdk 1.4.2 → 1.4.3

package/dist/types/project.d.ts

@@ -1,14 +1,15 @@
 import { LuxAuthClient, type LuxAuthOptions } from './auth';
-import type { LuxResult } from './types';
+import type { LuxResult, LuxTypedRow } from './types';
 export interface LuxProjectOptions {
     url: string;
     key: string;
     fetch?: typeof fetch;
+    websocket?: typeof WebSocket;
     auth?: Omit<LuxAuthOptions, 'httpUrl' | 'apiKey' | 'fetch'>;
 }
 export interface LuxTableColumn {
     name: string;
-    type: 'STR' | 'INT' | 'FLOAT' | 'BOOL' | 'TIMESTAMP' | 'UUID';
+    type: 'STR' | 'INT' | 'FLOAT' | 'BOOL' | 'TIMESTAMP' | 'UUID' | `VECTOR(${number})`;
     primaryKey?: boolean;
     unique?: boolean;
     notNull?: boolean;
@@ -21,8 +22,10 @@ export interface LuxVectorSearchOptions {
     filter?: string;
     filter_value?: string;
 }
-type QueryValue = string | number | boolean | null;
+type QueryValue = string | number | boolean | number[] | null;
 type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'is';
+type ProjectRowInput<T extends object> = Partial<T> & Record<string, QueryValue>;
+type ProjectSelectSingle<TResult> = TResult extends readonly (infer Row)[] ? Row : TResult;
 interface QueryFilter {
     column: string;
     operator: FilterOperator;
@@ -32,13 +35,51 @@ interface QueryOrder {
     column: string;
     ascending: boolean;
 }
+interface QueryJoin {
+    type: 'inner' | 'left';
+    table: string;
+    alias: string;
+    onLeft: string;
+    onRight: string;
+}
+interface QueryHaving {
+    column: string;
+    operator: FilterOperator;
+    value: QueryValue;
+}
+interface QueryNear {
+    field: string;
+    vector: number[];
+    k: number;
+    threshold?: number;
+}
+export type LuxProjectLiveEventType = 'snapshot' | 'insert' | 'update' | 'delete' | 'error';
+export interface LuxProjectLiveEvent<T extends object = Record<string, unknown>> {
+    type: LuxProjectLiveEventType;
+    table: string;
+    pk?: string;
+    new: T | null;
+    old: T | null;
+    rows?: T[];
+    changed?: string[];
+    raw?: unknown;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+type LiveEventHandler<T extends object> = (event: LuxProjectLiveEvent<T>) => void;
 export declare class LuxProjectClient {
     readonly url: string;
     readonly key: string;
     readonly auth: LuxAuthClient;
     private fetchImpl;
+    private WebSocketImpl?;
+    private liveSocket;
+    private liveSubscriptions;
+    private livePending;
     constructor(options: LuxProjectOptions);
-    table<T extends Record<string, unknown> = Record<string, unknown>>(name: string): LuxProjectTable<T>;
+    table<T extends object | readonly object[] = Record<string, unknown>>(name: string): LuxProjectTable<LuxTypedRow<T>>;
     ping(): Promise<LuxResult<unknown>>;
     createTable(name: string, columns: Array<string | LuxTableColumn>): Promise<LuxResult<unknown>>;
     exec(command: string | string[]): Promise<LuxResult<unknown>>;
@@ -55,15 +96,33 @@ export declare class LuxProjectClient {
         count?: number;
     }): Promise<LuxResult<unknown>>;
     request<T = unknown>(method: string, path: string, body?: unknown): Promise<LuxResult<T>>;
+    _subscribeLive(spec: Record<string, unknown>, handler: (event: unknown) => void, error: (error: {
+        code?: string;
+        message?: string;
+    }) => void): Promise<() => void>;
+    private ensureLiveSocket;
+    private sendLive;
 }
-export declare class LuxProjectTable<T extends Record<string, unknown>> {
+export declare class LuxProjectTable<T extends object> {
     private client;
     private name;
     constructor(client: LuxProjectClient, name: string);
-    select(columns?: string): LuxProjectSelectBuilder<T, T[]>;
-    insert(row: Partial<T> & Record<string, QueryValue>): LuxProjectInsertBuilder<unknown>;
-    insert(rows: Array<Partial<T> & Record<string, QueryValue>>): LuxProjectInsertBuilder<unknown[]>;
-    update(patch: Partial<T> & Record<string, QueryValue>): LuxProjectMutationBuilder<unknown>;
+    select<TResult extends object = T>(columns?: string): LuxProjectSelectBuilder<T, TResult[]>;
+    eq(column: string, value: QueryValue): LuxProjectSelectBuilder<T, T[]>;
+    neq(column: string, value: QueryValue): LuxProjectSelectBuilder<T, T[]>;
+    gt(column: string, value: QueryValue): LuxProjectSelectBuilder<T, T[]>;
+    gte(column: string, value: QueryValue): LuxProjectSelectBuilder<T, T[]>;
+    lt(column: string, value: QueryValue): LuxProjectSelectBuilder<T, T[]>;
+    lte(column: string, value: QueryValue): LuxProjectSelectBuilder<T, T[]>;
+    near(column: string, vector: number[], options?: {
+        k?: number;
+        threshold?: number;
+    }): LuxProjectSelectBuilder<T, T[]>;
+    is(column: string, value: QueryValue): LuxProjectSelectBuilder<T, T[]>;
+    live(): LuxProjectLiveSubscription<T>;
+    insert(row: ProjectRowInput<T>): LuxProjectInsertBuilder<unknown>;
+    insert(rows: Array<ProjectRowInput<T>>): LuxProjectInsertBuilder<unknown[]>;
+    update(patch: ProjectRowInput<T>): LuxProjectMutationBuilder<unknown>;
     delete(): LuxProjectMutationBuilder<unknown>;
     count(): Promise<LuxResult<number>>;
 }
@@ -78,6 +137,10 @@ declare abstract class LuxProjectFilterBuilder<TResult, TSelf> extends LuxProjec
     protected tableName: string;
     protected filters: QueryFilter[];
     protected orderBy?: QueryOrder;
+    protected joins: QueryJoin[];
+    protected groupColumns: string[];
+    protected havingFilters: QueryHaving[];
+    protected nearQuery?: QueryNear;
     protected limitCount?: number;
     protected offsetCount?: number;
     protected constructor(client: LuxProjectClient, tableName: string);
@@ -88,20 +151,48 @@ declare abstract class LuxProjectFilterBuilder<TResult, TSelf> extends LuxProjec
     lt(column: string, value: QueryValue): TSelf;
     lte(column: string, value: QueryValue): TSelf;
     is(column: string, value: QueryValue): TSelf;
+    join(table: string, alias: string, onLeft: string, onRight: string): TSelf;
+    leftJoin(table: string, alias: string, onLeft: string, onRight: string): TSelf;
+    group(columns: string | string[]): TSelf;
+    having(column: string, operator: FilterOperator, value: QueryValue): TSelf;
     protected addFilter(column: string, operator: FilterOperator, value: QueryValue): TSelf;
     protected filteredQueryParams(): URLSearchParams;
 }
-export declare class LuxProjectSelectBuilder<T extends Record<string, unknown>, TResult> extends LuxProjectFilterBuilder<TResult, LuxProjectSelectBuilder<T, TResult>> {
+export declare class LuxProjectSelectBuilder<T extends object, TResult> extends LuxProjectFilterBuilder<TResult, LuxProjectSelectBuilder<T, TResult>> {
     private columns;
     private expectSingle;
     constructor(client: LuxProjectClient, tableName: string, columns: string);
     order(column: string, options?: {
         ascending?: boolean;
     }): this;
+    near(column: string, vector: number[], options?: {
+        k?: number;
+        threshold?: number;
+    }): this;
     limit(count: number): this;
     range(from: number, to: number): this;
-    single(): LuxProjectSelectBuilder<T, T>;
+    single(): LuxProjectSelectBuilder<T, ProjectSelectSingle<TResult>>;
     execute(): Promise<LuxResult<TResult>>;
+    live(): LuxProjectLiveSubscription<LuxTypedRow<TResult>>;
+}
+export declare class LuxProjectLiveSubscription<T extends object> {
+    private client;
+    private table;
+    private columns;
+    private filters;
+    private nearQuery?;
+    private orderBy?;
+    private limitCount?;
+    private offsetCount?;
+    private handlers;
+    private unsubscribeFn;
+    constructor(client: LuxProjectClient, table: string, columns: string, filters: QueryFilter[], nearQuery?: QueryNear | undefined, orderBy?: QueryOrder | undefined, limitCount?: number | undefined, offsetCount?: number | undefined);
+    on(type: LuxProjectLiveEventType | 'change', handler: LiveEventHandler<T>): this;
+    unsubscribe(): Promise<void>;
+    private start;
+    private spec;
+    private handleEvent;
+    private emit;
 }
 export declare class LuxProjectInsertBuilder<TResult> extends LuxProjectThenable<TResult> {
     private client;

package/dist/types/table.d.ts

@@ -1,4 +1,4 @@
-import type { KSubEvent, LuxError, LuxResult, TableChangeEvent, TableErrorEvent, TableRow, TableSchema, VSearchResult } from './types';
+import type { KSubEvent, LuxError, LuxResult, TableChangeEvent, TableErrorEvent, TableRow, TableSchema } from './types';
 type TableWhereOp = '=' | '!=' | '>' | '<' | '>=' | '<=';
 type TableWhereValue = string | number | boolean;
 interface TableWhereCondition {
@@ -10,19 +10,11 @@ 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> {
+export interface TableQueryBuilderOptions<T extends object> {
     schema?: TableSchema<T>;
 }
-export declare class TableSubscription<T extends TableRow> {
+export declare class TableSubscription<T extends object> {
     private client;
     private table;
     private selectArgsBuilder;
@@ -41,7 +33,7 @@ export declare class TableSubscription<T extends TableRow> {
     private start;
     private handleRawChange;
 }
-export declare class TableQueryBuilder<T extends TableRow = TableRow> {
+export declare class TableQueryBuilder<T extends object = TableRow> {
     private client;
     private name;
     private conditions;
@@ -51,6 +43,8 @@ export declare class TableQueryBuilder<T extends TableRow = TableRow> {
     private offsetCount?;
     private joinClause?;
     private similarityClause?;
+    private groupFields;
+    private havingConditions;
     private selectClause;
     private expectSingle;
     private schema?;
@@ -73,14 +67,18 @@ export declare class TableQueryBuilder<T extends TableRow = TableRow> {
     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;
-        };
+    leftJoin(table: string, alias: string, onLeft: string, onRight: string): this;
+    group(fields: string | string[]): this;
+    groupBy(fields: string | string[]): this;
+    having(field: string, op: TableWhereOp, value: TableWhereValue): this;
+    near(field: string, vector: number[], options?: {
+        k?: number;
+        threshold?: number;
+    }): this;
+    similar(field: string, vector: number[], options?: {
+        k?: number;
+        threshold?: number;
     }): this;
-    private parseSimilarityPk;
     run(): Promise<LuxResult<T[] | T>>;
     then<TFulfilled = LuxResult<T[] | T>, TRejected = never>(onfulfilled?: ((value: LuxResult<T[] | T>) => TFulfilled | PromiseLike<TFulfilled>) | null, onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null): Promise<TFulfilled | TRejected>;
     insert(data: Record<string, unknown>): Promise<LuxResult<number>>;

package/dist/types/types.d.ts

@@ -31,6 +31,14 @@ export interface TableRow {
     id?: number | string;
     [field: string]: unknown;
 }
+export type LuxInferRow<T> = T extends readonly (infer Row)[] ? Row : T;
+export type LuxTypedRow<T> = LuxInferRow<T> extends object ? LuxInferRow<T> : TableRow;
+export type LuxAggregateValue = number | string;
+export type LuxAggregateRow<Aliases extends string = string> = Record<Aliases, LuxAggregateValue>;
+export interface LuxSimilarity {
+    _similarity: number | string;
+}
+export type LuxNearRow<T extends object = Record<string, unknown>> = T & LuxSimilarity;
 export interface LuxError {
     code: string;
     message: string;
@@ -52,7 +60,7 @@ export interface TableSchema<T> {
     safeParse?: (input: unknown) => SchemaSafeParse<T>;
 }
 export type TableChangeType = 'insert' | 'update' | 'delete' | 'change' | 'error';
-export interface TableChangeEvent<T extends TableRow> {
+export interface TableChangeEvent<T extends object = TableRow> {
     type: Exclude<TableChangeType, 'error'>;
     table: string;
     pk: string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luxdb/sdk",
-    "version": "1.4.2",
+    "version": "1.4.3",
     "description": "Official Lux TypeScript SDK for app data, auth, tables, vectors, realtime, and Redis-compatible direct access",
     "main": "./dist/cjs/index.js",
     "module": "./dist/esm/index.js",