local-lite 0.0.4 → 0.0.5

package/dist/adapters/remote/supabase.d.ts

@@ -15,8 +15,8 @@ export interface SupabaseAdapterOptions {
     updatedAtColumn?: string;
     /**
      * Optional subset of tables to which dynamic `syncScope` filters should apply.
-     * If provided, scope filters (like `business_id`) will only be attached to queries for these tables.
-     * Tables not in this list (e.g. 'businesses', 'profiles') will be fetched without the scope filter.
+     * If provided, scope filters (like `tenant_id` or `org_id`) will only be attached to queries for these tables.
+     * Tables not in this list (e.g. global tables, user profiles) will be fetched without the scope filter.
      */
     scopedTables?: string[];
     /**

package/dist/config/types.d.ts

@@ -178,7 +178,7 @@ export interface LocalLiteConfig {
      */
     autoHydrateJSON?: boolean;
     /**
-     * Scoped synchronization filter (e.g. { business_id: '...' } or dynamic resolver callback).
+     * Scoped synchronization filter (e.g. { org_id: '...' } or dynamic resolver callback).
      */
     syncScope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>);
 }

package/dist/core/client.d.ts

@@ -2,9 +2,10 @@ import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
 import { RemoteDBAdapter } from '../adapters/remote/index.js';
 import { EventEmitter } from '../reactive/event-emitter.js';
 import { SyncWorker } from './sync-worker.js';
-import { SchemaManager, DBExecutable } from './schema-manager.js';
-import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SyncMetrics, SyncOp, TableChangeEvent } from './types.js';
+import { SchemaManager } from './schema-manager.js';
+import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SyncMetrics, SyncOp, TableChangeEvent, WhereFilter } from './types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
+import { QueryBuilder, AggregateSpec, AggregateResult } from './query-builder.js';
 export interface LocalFirstClientConfig {
     local: LocalDBAdapter;
     remote: RemoteDBAdapter;
@@ -51,6 +52,8 @@ export declare class TransactionalClient {
         includeDeleted?: boolean;
     }): Promise<T[]>;
     findMany<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
+    query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    from<T = any>(tableName: string): QueryBuilder<T>;
     get rawTx(): LocalTransaction;
 }
 export declare class LocalFirstClient {
@@ -149,15 +152,57 @@ export declare class LocalFirstClient {
      * Pushes simple equality where clauses down to SQLite for high performance, with memory fallback.
      * Gracefully returns [] if table or columns have not been populated yet on empty schemas.
      *
+    /**
+     * Executes a raw relational SQL query with parameters directly against SQLite.
+     * Enables complex multi-table JOINs, GROUP BY aggregations (COUNT, SUM, AVG), CTEs, and window functions.
+     */
+    query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    /**
+     * Returns a fluent SQL QueryBuilder for the specified table.
+     * Allows writing clean JavaScript method chains (select, join, leftJoin, where, orderBy, groupBy)
+     * that automatically compile into optimized native SQLite queries.
+     *
      * Example:
-     * const tenants = await client.findMany('tenants', { where: { status: 'ACTIVE' }, orderBy: 'name' });
-     * const expensive = await client.findMany('properties', { where: { rent: { $gte: 2000 } } });
+     * const activeRentals = await client
+     *   .from('contracts')
+     *   .join('houses', 'contracts.house_id', 'houses.id')
+     *   .leftJoin('tenants', 'contracts.tenant_id', 'tenants.id')
+     *   .where({ 'contracts.business_id': bizId, 'contracts.status': 'ACTIVE' })
+     *   .select('contracts.id', 'contracts.rent_amount', 'houses.house_number', 'tenants.name')
+     *   .execute();
      */
-    findMany<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
+    from<T = any>(tableName: string): QueryBuilder<T>;
+    /**
+     * Executes a native SQLite COUNT(*) query and returns the count directly.
+     */
+    count(tableName: string, options?: {
+        where?: WhereFilter;
+    }): Promise<number>;
     /**
-     * Internal findMany implementation shared between LocalFirstClient and TransactionalClient.
+     * Executes a native SQLite SUM(column) query and returns the sum directly.
      */
-    findManyInternal<T = any>(db: DBExecutable, tableName: string, options?: QueryOptions): Promise<T[]>;
+    sum(tableName: string, column: string, options?: {
+        where?: WhereFilter;
+    }): Promise<number>;
+    /**
+     * Executes a native SQLite AVG(column) query and returns the average directly.
+     */
+    avg(tableName: string, column: string, options?: {
+        where?: WhereFilter;
+    }): Promise<number | null>;
+    /**
+     * Executes native multi-metric SQLite aggregation in a single query.
+     *
+     * Example:
+     * const stats = await client.aggregate('receipts', {
+     *   where: { business_id: bizId },
+     *   count: true,
+     *   sum: ['amount', 'refunded_amount'],
+     *   avg: ['amount']
+     * });
+     */
+    aggregate(tableName: string, spec: AggregateSpec): Promise<AggregateResult>;
+    findMany<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
     /**
      * Finds a single record by primary key.
      *

package/dist/core/client.js

@@ -10,6 +10,7 @@ const schema_manager_js_1 = require("./schema-manager.js");
 const uuid_js_1 = require("../utils/uuid.js");
 const sql_js_1 = require("../utils/sql.js");
 const query_js_1 = require("./query.js");
+const query_builder_js_1 = require("./query-builder.js");
 class TransactionalClient {
     parent;
     tx;
@@ -110,7 +111,14 @@ class TransactionalClient {
         }
     }
     async findMany(tableName, options) {
-        return this.parent.findManyInternal(this.tx, tableName, options);
+        const rows = await this.from(tableName).applyOptions(options).execute();
+        return (0, query_js_1.applyQueryOptions)(rows, options);
+    }
+    async query(sql, params = []) {
+        return (await this.tx.execute(sql, params));
+    }
+    from(tableName) {
+        return new query_builder_js_1.QueryBuilder(this, tableName);
     }
     get rawTx() {
         return this.tx;
@@ -492,142 +500,137 @@ class LocalFirstClient {
      * Pushes simple equality where clauses down to SQLite for high performance, with memory fallback.
      * Gracefully returns [] if table or columns have not been populated yet on empty schemas.
      *
+    /**
+     * Executes a raw relational SQL query with parameters directly against SQLite.
+     * Enables complex multi-table JOINs, GROUP BY aggregations (COUNT, SUM, AVG), CTEs, and window functions.
+     */
+    async query(sql, params = []) {
+        return (await this.db.execute(sql, params));
+    }
+    /**
+     * Returns a fluent SQL QueryBuilder for the specified table.
+     * Allows writing clean JavaScript method chains (select, join, leftJoin, where, orderBy, groupBy)
+     * that automatically compile into optimized native SQLite queries.
+     *
      * Example:
-     * const tenants = await client.findMany('tenants', { where: { status: 'ACTIVE' }, orderBy: 'name' });
-     * const expensive = await client.findMany('properties', { where: { rent: { $gte: 2000 } } });
+     * const activeRentals = await client
+     *   .from('contracts')
+     *   .join('houses', 'contracts.house_id', 'houses.id')
+     *   .leftJoin('tenants', 'contracts.tenant_id', 'tenants.id')
+     *   .where({ 'contracts.business_id': bizId, 'contracts.status': 'ACTIVE' })
+     *   .select('contracts.id', 'contracts.rent_amount', 'houses.house_number', 'tenants.name')
+     *   .execute();
      */
-    async findMany(tableName, options) {
-        return this.findManyInternal(this.db, tableName, options);
+    from(tableName) {
+        return new query_builder_js_1.QueryBuilder(this, tableName);
     }
     /**
-     * Internal findMany implementation shared between LocalFirstClient and TransactionalClient.
+     * Executes a native SQLite COUNT(*) query and returns the count directly.
      */
-    async findManyInternal(db, tableName, options) {
-        await this.schemaManager.ensureTableIntrospected(db, tableName);
-        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
-        let rows;
-        const projection = options?.select && Array.isArray(options.select) && options.select.length > 0
-            ? options.select.map(sql_js_1.escapeIdentifier).join(', ')
-            : '*';
-        let sql = `SELECT ${projection} FROM ${safeTable}`;
-        const params = [];
-        const whereClauses = [];
-        // Automatically push down soft-delete filter if table has deleted column and not explicitly overridden
-        const hasDeletedClause = options?.where && typeof options.where === 'object' && (0, query_js_1.hasExplicitDeletedFilter)(options.where);
-        if (!options?.includeDeleted && !hasDeletedClause && this.schemaManager.hasColumn(tableName, 'deleted')) {
-            const safeDel = (0, sql_js_1.escapeIdentifier)('deleted');
-            whereClauses.push(`(${safeDel} IS NULL OR (${safeDel} != 1 AND ${safeDel} != 'true'))`);
-        }
-        // Push down where conditions to SQLite
-        if (options?.where && typeof options.where === 'object' && !Array.isArray(options.where)) {
-            for (const [col, filter] of Object.entries(options.where)) {
-                if (col === '$or' || col === '$and')
-                    continue;
-                const safeCol = (0, sql_js_1.escapeIdentifier)(col);
-                if (filter === null) {
-                    whereClauses.push(`${safeCol} IS NULL`);
-                }
-                else if (typeof filter === 'boolean') {
-                    whereClauses.push(`${safeCol} = ?`);
-                    params.push(filter ? 1 : 0);
-                }
-                else if (typeof filter === 'string' || typeof filter === 'number') {
-                    whereClauses.push(`${safeCol} = ?`);
-                    params.push(filter);
-                }
-                else if (typeof filter === 'object' && !Array.isArray(filter)) {
-                    const ops = filter;
-                    if (ops.$eq !== undefined) {
-                        whereClauses.push(`${safeCol} = ?`);
-                        params.push(typeof ops.$eq === 'boolean' ? (ops.$eq ? 1 : 0) : ops.$eq);
-                    }
-                    if (ops.$ne !== undefined) {
-                        whereClauses.push(`${safeCol} != ?`);
-                        params.push(typeof ops.$ne === 'boolean' ? (ops.$ne ? 1 : 0) : ops.$ne);
-                    }
-                    if (ops.$gt !== undefined) {
-                        whereClauses.push(`${safeCol} > ?`);
-                        params.push(ops.$gt);
-                    }
-                    if (ops.$gte !== undefined) {
-                        whereClauses.push(`${safeCol} >= ?`);
-                        params.push(ops.$gte);
-                    }
-                    if (ops.$lt !== undefined) {
-                        whereClauses.push(`${safeCol} < ?`);
-                        params.push(ops.$lt);
-                    }
-                    if (ops.$lte !== undefined) {
-                        whereClauses.push(`${safeCol} <= ?`);
-                        params.push(ops.$lte);
-                    }
-                    if (Array.isArray(ops.$in) && ops.$in.length > 0) {
-                        const placeholders = ops.$in.map(() => '?').join(', ');
-                        whereClauses.push(`${safeCol} IN (${placeholders})`);
-                        params.push(...ops.$in.map((v) => (typeof v === 'boolean' ? (v ? 1 : 0) : v)));
-                    }
-                    if (Array.isArray(ops.$nin) && ops.$nin.length > 0) {
-                        const placeholders = ops.$nin.map(() => '?').join(', ');
-                        whereClauses.push(`${safeCol} NOT IN (${placeholders})`);
-                        params.push(...ops.$nin.map((v) => (typeof v === 'boolean' ? (v ? 1 : 0) : v)));
-                    }
-                    if (ops.$null !== undefined) {
-                        whereClauses.push(ops.$null ? `${safeCol} IS NULL` : `${safeCol} IS NOT NULL`);
-                    }
-                    if (ops.$contains !== undefined) {
-                        whereClauses.push(`${safeCol} LIKE ?`);
-                        params.push(`%${ops.$contains}%`);
-                    }
-                    if (ops.$startsWith !== undefined) {
-                        whereClauses.push(`${safeCol} LIKE ?`);
-                        params.push(`${ops.$startsWith}%`);
-                    }
-                    if (ops.$endsWith !== undefined) {
-                        whereClauses.push(`${safeCol} LIKE ?`);
-                        params.push(`%${ops.$endsWith}`);
-                    }
-                }
+    async count(tableName, options) {
+        const qb = this.from(tableName);
+        if (options?.where)
+            qb.where(options.where);
+        return qb.count();
+    }
+    /**
+     * Executes a native SQLite SUM(column) query and returns the sum directly.
+     */
+    async sum(tableName, column, options) {
+        const qb = this.from(tableName);
+        if (options?.where)
+            qb.where(options.where);
+        return qb.sum(column);
+    }
+    /**
+     * Executes a native SQLite AVG(column) query and returns the average directly.
+     */
+    async avg(tableName, column, options) {
+        const qb = this.from(tableName);
+        if (options?.where)
+            qb.where(options.where);
+        return qb.avg(column);
+    }
+    /**
+     * Executes native multi-metric SQLite aggregation in a single query.
+     *
+     * Example:
+     * const stats = await client.aggregate('receipts', {
+     *   where: { business_id: bizId },
+     *   count: true,
+     *   sum: ['amount', 'refunded_amount'],
+     *   avg: ['amount']
+     * });
+     */
+    async aggregate(tableName, spec) {
+        const projections = [];
+        if (spec.count) {
+            projections.push('COUNT(*) AS "_count"');
+        }
+        if (spec.sum) {
+            for (const col of spec.sum) {
+                projections.push(`COALESCE(SUM("${col.replace(/"/g, '""')}"), 0) AS "sum_${col}"`);
             }
-            if (whereClauses.length > 0) {
-                sql += ` WHERE ${whereClauses.join(' AND ')}`;
+        }
+        if (spec.avg) {
+            for (const col of spec.avg) {
+                projections.push(`AVG("${col.replace(/"/g, '""')}") AS "avg_${col}"`);
             }
         }
-        // Push down ORDER BY
-        if (options?.orderBy && typeof options.orderBy === 'string') {
-            const safeCol = (0, sql_js_1.escapeIdentifier)(options.orderBy);
-            const dir = options.order && String(options.order).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-            sql += ` ORDER BY ${safeCol} ${dir}`;
-        }
-        // Push down LIMIT & OFFSET
-        if (typeof options?.limit === 'number' && options.limit > 0) {
-            sql += ` LIMIT ?`;
-            params.push(options.limit);
-            if (typeof options.offset === 'number' && options.offset > 0) {
-                sql += ` OFFSET ?`;
-                params.push(options.offset);
+        if (spec.min) {
+            for (const col of spec.min) {
+                projections.push(`MIN("${col.replace(/"/g, '""')}") AS "min_${col}"`);
             }
         }
-        try {
-            rows = await db.execute(sql, params);
+        if (spec.max) {
+            for (const col of spec.max) {
+                projections.push(`MAX("${col.replace(/"/g, '""')}") AS "max_${col}"`);
+            }
         }
-        catch (err) {
-            const msg = String(err?.message || err || '');
-            if (msg.includes('no such table') || msg.includes('no such column')) {
-                return [];
+        if (projections.length === 0) {
+            return {};
+        }
+        const qb = this.from(tableName).select(...projections);
+        if (spec.where) {
+            qb.where(spec.where);
+        }
+        const rows = await qb.execute();
+        const row = rows[0] || {};
+        const result = {};
+        if (spec.count) {
+            result.count = typeof row._count === 'number' ? row._count : Number(row._count) || 0;
+        }
+        if (spec.sum) {
+            result.sum = {};
+            for (const col of spec.sum) {
+                const val = row[`sum_${col}`];
+                result.sum[col] = typeof val === 'number' ? val : Number(val) || 0;
             }
-            // Fallback to select * if pushdown syntax differs
-            try {
-                rows = await db.execute(`SELECT * FROM ${safeTable}`);
+        }
+        if (spec.avg) {
+            result.avg = {};
+            for (const col of spec.avg) {
+                const val = row[`avg_${col}`];
+                result.avg[col] = val === null || val === undefined ? null : Number(val) || 0;
             }
-            catch {
-                return [];
+        }
+        if (spec.min) {
+            result.min = {};
+            for (const col of spec.min) {
+                result.min[col] = row[`min_${col}`];
+            }
+        }
+        if (spec.max) {
+            result.max = {};
+            for (const col of spec.max) {
+                result.max[col] = row[`max_${col}`];
             }
         }
-        const hasJsonConfig = Boolean(this.jsonColumns[tableName] || this.autoHydrateJSON);
-        const hydratedRows = hasJsonConfig
-            ? rows.map((r) => this.hydrateRow(tableName, r))
-            : rows;
-        return (0, query_js_1.applyQueryOptions)(hydratedRows, options);
+        return result;
+    }
+    async findMany(tableName, options) {
+        const rows = await this.from(tableName).applyOptions(options).execute();
+        return (0, query_js_1.applyQueryOptions)(rows, options);
     }
     /**
      * Finds a single record by primary key.

package/dist/core/index.d.ts

@@ -7,6 +7,7 @@ export * from './outbox-store.js';
 export * from './meta-store.js';
 export * from './table-manager.js';
 export * from './schema-manager.js';
+export * from './query-builder.js';
 export * from '../reactive/event-emitter.js';
 export * from '../adapters/network/index.js';
 export type { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';

package/dist/core/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./outbox-store.js"), exports);
 __exportStar(require("./meta-store.js"), exports);
 __exportStar(require("./table-manager.js"), exports);
 __exportStar(require("./schema-manager.js"), exports);
+__exportStar(require("./query-builder.js"), exports);
 __exportStar(require("../reactive/event-emitter.js"), exports);
 __exportStar(require("../adapters/network/index.js"), exports);
 __exportStar(require("../utils/logger.js"), exports);

package/dist/core/query-builder.d.ts

@@ -0,0 +1,119 @@
+import { LocalFirstClient, TransactionalClient } from './client.js';
+import { QueryOptions, WhereFilter } from './types.js';
+type ClientLike = LocalFirstClient | TransactionalClient;
+/**
+ * Escapes an identifier or compound identifier (e.g. 'table.column' or 'table.col as alias').
+ */
+export declare function formatColumnIdentifier(col: string): string;
+export interface JoinDefinition {
+    type: 'INNER' | 'LEFT' | 'CROSS';
+    table: string;
+    firstCol: string;
+    secondCol: string;
+}
+export interface AggregateSpec {
+    where?: WhereFilter;
+    count?: boolean;
+    sum?: string[];
+    avg?: string[];
+    min?: string[];
+    max?: string[];
+}
+export interface AggregateResult {
+    count?: number;
+    sum?: Record<string, number>;
+    avg?: Record<string, number | null>;
+    min?: Record<string, any>;
+    max?: Record<string, any>;
+}
+/**
+ * Fluent, type-safe SQL Query Builder for local-first SQLite operations.
+ * Allows writing expressive JavaScript code that compiles and executes high-performance SQL under the hood.
+ */
+export declare class QueryBuilder<T = any> {
+    private client;
+    private tableName;
+    private selectCols;
+    private joins;
+    private whereConditions;
+    private orderColumn?;
+    private orderDirection;
+    private limitCount?;
+    private offsetCount?;
+    private groupByCols;
+    private includeDeleted;
+    constructor(client: ClientLike, tableName: string);
+    /**
+     * Specifies which columns to select.
+     * Supports column aliases (e.g. ['id', 'contracts.rent_amount AS rent', 'houses.house_number']).
+     */
+    select(...columns: Array<string | string[]>): this;
+    /**
+     * Inner joins another SQLite table on a matching column expression.
+     */
+    join(table: string, firstCol: string, secondCol: string): this;
+    /**
+     * Left joins another SQLite table on a matching column expression.
+     */
+    leftJoin(table: string, firstCol: string, secondCol: string): this;
+    /**
+     * Adds WHERE criteria to filter results.
+     * Supports:
+     * - where({ status: 'ACTIVE' })
+     * - where('status', 'ACTIVE')
+     * - where('end_date', '>=', today)
+     */
+    where(columnOrFilter: string | WhereFilter, operatorOrValue?: any, value?: any): this;
+    /**
+     * Orders query results by column and direction.
+     */
+    orderBy(column: string, direction?: 'asc' | 'desc' | 'ASC' | 'DESC'): this;
+    /**
+     * Groups rows by one or more columns for aggregation.
+     */
+    groupBy(...columns: Array<string | string[]>): this;
+    /**
+     * Limits the number of returned records.
+     */
+    limit(count: number): this;
+    /**
+     * Offsets the starting record position.
+     */
+    offset(count: number): this;
+    /**
+     * Includes soft-deleted rows in results.
+     */
+    withDeleted(include?: boolean): this;
+    /**
+     * Applies standard QueryOptions (select, where, orderBy, limit, offset, includeDeleted) to this query.
+     */
+    applyOptions(options?: QueryOptions): this;
+    /**
+     * Compiles the current builder state into an executable SQL string and parameter list.
+     */
+    toSQL(): {
+        sql: string;
+        params: any[];
+    };
+    /**
+     * Executes the compiled SQL query against SQLite and returns rows.
+     */
+    execute(): Promise<T[]>;
+    /**
+     * Returns the first matching record or null if not found.
+     */
+    first(): Promise<T | null>;
+    /**
+     * Executes a COUNT(*) in SQLite and returns the numeric count directly.
+     */
+    count(): Promise<number>;
+    /**
+     * Executes a SUM(column) in SQLite and returns the numeric total directly.
+     */
+    sum(column: string): Promise<number>;
+    /**
+     * Executes an AVG(column) in SQLite and returns the average directly.
+     */
+    avg(column: string): Promise<number | null>;
+}
+export {};