local-lite 0.0.4 → 0.0.6

package/dist/adapters/remote/supabase.js

@@ -137,20 +137,9 @@ class SupabaseRemoteAdapter {
                     batch.push(operations[i]);
                     i++;
                 }
-                const buildRowData = (item) => {
-                    const row = {
-                        ...(item.payload || {}),
-                        [this.primaryKey]: item.rowId,
-                        [this.deletedColumn]: false,
-                    };
-                    if (this.updatedAtColumn && !row[this.updatedAtColumn]) {
-                        row[this.updatedAtColumn] = new Date(item.timestamp).toISOString();
-                    }
-                    return row;
-                };
                 if (batch.length === 1) {
                     try {
-                        const rowData = buildRowData(batch[0]);
+                        const rowData = this.buildRowData(batch[0]);
                         const { error } = await client.from(op.tableName).upsert(rowData);
                         if (error) {
                             const msg = (0, logger_js_1.formatSupabaseError)(error, { table: op.tableName, operation: 'INSERT' });
@@ -174,7 +163,7 @@ class SupabaseRemoteAdapter {
                     const retryIndividually = async () => {
                         for (const item of batch) {
                             try {
-                                const singleRow = buildRowData(item);
+                                const singleRow = this.buildRowData(item);
                                 const { error: singleErr } = await client.from(op.tableName).upsert(singleRow);
                                 if (singleErr) {
                                     const msg = (0, logger_js_1.formatSupabaseError)(singleErr, { table: op.tableName, operation: 'INSERT' });
@@ -193,7 +182,7 @@ class SupabaseRemoteAdapter {
                         }
                     };
                     try {
-                        const rows = batch.map(buildRowData);
+                        const rows = batch.map((item) => this.buildRowData(item));
                         const { error } = await client.from(op.tableName).upsert(rows);
                         if (!error) {
                             for (const item of batch)
@@ -209,87 +198,173 @@ class SupabaseRemoteAdapter {
                 }
                 continue;
             }
-            // Handle DELETE
+            // Batch consecutive DELETEs for the same table
             if (op.operation === 'DELETE') {
-                try {
-                    const patch = {
-                        [this.deletedColumn]: this.deletedValue,
-                    };
-                    if (this.updatedAtColumn) {
-                        patch[this.updatedAtColumn] = new Date(op.timestamp).toISOString();
+                const batch = [];
+                while (i < operations.length &&
+                    operations[i].operation === 'DELETE' &&
+                    operations[i].tableName === op.tableName) {
+                    batch.push(operations[i]);
+                    i++;
+                }
+                const patch = {
+                    [this.deletedColumn]: this.deletedValue,
+                };
+                if (this.updatedAtColumn) {
+                    patch[this.updatedAtColumn] = new Date(op.timestamp).toISOString();
+                }
+                if (batch.length === 1) {
+                    try {
+                        const { error } = await client
+                            .from(op.tableName)
+                            .update(patch)
+                            .eq(this.primaryKey, op.rowId);
+                        if (error) {
+                            const msg = (0, logger_js_1.formatSupabaseError)(error, { table: op.tableName, operation: 'DELETE' });
+                            this.logger.error(msg);
+                            failedIds.push(op.id);
+                            errors[op.id] = msg;
+                        }
+                        else {
+                            successfulIds.push(op.id);
+                        }
                     }
-                    const { error } = await client
-                        .from(op.tableName)
-                        .update(patch)
-                        .eq(this.primaryKey, op.rowId);
-                    if (error) {
-                        const msg = (0, logger_js_1.formatSupabaseError)(error, { table: op.tableName, operation: 'DELETE' });
+                    catch (err) {
+                        const msg = (0, logger_js_1.formatSupabaseError)(err, { table: op.tableName, operation: 'DELETE' });
                         this.logger.error(msg);
                         failedIds.push(op.id);
                         errors[op.id] = msg;
                     }
-                    else {
-                        successfulIds.push(op.id);
-                    }
                 }
-                catch (err) {
-                    const msg = (0, logger_js_1.formatSupabaseError)(err, { table: op.tableName, operation: 'DELETE' });
-                    this.logger.error(msg);
-                    failedIds.push(op.id);
-                    errors[op.id] = msg;
+                else {
+                    // Bulk soft-delete using .in() to collapse N round-trips into 1
+                    const rowIds = batch.map((item) => item.rowId);
+                    try {
+                        const { error } = await client
+                            .from(op.tableName)
+                            .update(patch)
+                            .in(this.primaryKey, rowIds);
+                        if (!error) {
+                            for (const item of batch)
+                                successfulIds.push(item.id);
+                        }
+                        else {
+                            // Fallback to individual updates if .in() fails
+                            for (const item of batch) {
+                                try {
+                                    const { error: singleErr } = await client
+                                        .from(op.tableName)
+                                        .update(patch)
+                                        .eq(this.primaryKey, item.rowId);
+                                    if (singleErr) {
+                                        const msg = (0, logger_js_1.formatSupabaseError)(singleErr, { table: op.tableName, operation: 'DELETE' });
+                                        failedIds.push(item.id);
+                                        errors[item.id] = msg;
+                                    }
+                                    else {
+                                        successfulIds.push(item.id);
+                                    }
+                                }
+                                catch (singleErr) {
+                                    const msg = (0, logger_js_1.formatSupabaseError)(singleErr, { table: op.tableName, operation: 'DELETE' });
+                                    failedIds.push(item.id);
+                                    errors[item.id] = msg;
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        for (const item of batch)
+                            failedIds.push(item.id);
+                    }
                 }
-                i++;
                 continue;
             }
-            // Handle UPDATE
+            // Batch consecutive UPDATEs for the same table
             if (op.operation === 'UPDATE') {
-                try {
-                    const patch = {
-                        ...(op.payload || {}),
-                        [this.deletedColumn]: false,
-                    };
-                    if (this.updatedAtColumn) {
-                        patch[this.updatedAtColumn] = new Date(op.timestamp).toISOString();
+                const batch = [];
+                while (i < operations.length &&
+                    operations[i].operation === 'UPDATE' &&
+                    operations[i].tableName === op.tableName) {
+                    batch.push(operations[i]);
+                    i++;
+                }
+                if (batch.length === 1) {
+                    const item = batch[0];
+                    try {
+                        const patch = this.buildRowData(item);
+                        const { error, data } = await client
+                            .from(op.tableName)
+                            .update(patch)
+                            .eq(this.primaryKey, item.rowId)
+                            .select(this.primaryKey);
+                        if (error) {
+                            const msg = (0, logger_js_1.formatSupabaseError)(error, { table: op.tableName, operation: 'UPDATE' });
+                            this.logger.error(msg);
+                            failedIds.push(item.id);
+                            errors[item.id] = msg;
+                        }
+                        else if (!data || data.length === 0) {
+                            const { error: upsertErr } = await client.from(op.tableName).upsert(patch);
+                            if (upsertErr) {
+                                const msg = (0, logger_js_1.formatSupabaseError)(upsertErr, { table: op.tableName, operation: 'UPSERT_FALLBACK' });
+                                this.logger.error(msg);
+                                failedIds.push(item.id);
+                                errors[item.id] = msg;
+                            }
+                            else {
+                                successfulIds.push(item.id);
+                            }
+                        }
+                        else {
+                            successfulIds.push(item.id);
+                        }
                     }
-                    const { error, data } = await client
-                        .from(op.tableName)
-                        .update(patch)
-                        .eq(this.primaryKey, op.rowId)
-                        .select(this.primaryKey);
-                    if (error) {
-                        const msg = (0, logger_js_1.formatSupabaseError)(error, { table: op.tableName, operation: 'UPDATE' });
+                    catch (err) {
+                        const msg = (0, logger_js_1.formatSupabaseError)(err, { table: op.tableName, operation: 'UPDATE' });
                         this.logger.error(msg);
-                        failedIds.push(op.id);
-                        errors[op.id] = msg;
+                        failedIds.push(item.id);
+                        errors[item.id] = msg;
                     }
-                    else if (!data || data.length === 0) {
-                        // If row did not exist remotely, fallback to upsert
-                        const rowData = {
-                            ...patch,
-                            [this.primaryKey]: op.rowId,
-                        };
-                        const { error: upsertErr } = await client.from(op.tableName).upsert(rowData);
-                        if (upsertErr) {
-                            const msg = (0, logger_js_1.formatSupabaseError)(upsertErr, { table: op.tableName, operation: 'UPSERT_FALLBACK' });
-                            this.logger.error(msg);
-                            failedIds.push(op.id);
-                            errors[op.id] = msg;
+                }
+                else {
+                    // Bulk upsert for multiple consecutive updates (merges fields by primaryKey in 1 HTTP call)
+                    const rows = batch.map((item) => this.buildRowData(item));
+                    try {
+                        const { error } = await client.from(op.tableName).upsert(rows);
+                        if (!error) {
+                            for (const item of batch)
+                                successfulIds.push(item.id);
                         }
                         else {
-                            successfulIds.push(op.id);
+                            // Fallback to individual updates if bulk upsert has a schema conflict
+                            for (const item of batch) {
+                                try {
+                                    const singleRow = this.buildRowData(item);
+                                    const { error: singleErr } = await client.from(op.tableName).upsert(singleRow);
+                                    if (singleErr) {
+                                        const msg = (0, logger_js_1.formatSupabaseError)(singleErr, { table: op.tableName, operation: 'UPDATE' });
+                                        failedIds.push(item.id);
+                                        errors[item.id] = msg;
+                                    }
+                                    else {
+                                        successfulIds.push(item.id);
+                                    }
+                                }
+                                catch (singleErr) {
+                                    const msg = (0, logger_js_1.formatSupabaseError)(singleErr, { table: op.tableName, operation: 'UPDATE' });
+                                    failedIds.push(item.id);
+                                    errors[item.id] = msg;
+                                }
+                            }
                         }
                     }
-                    else {
-                        successfulIds.push(op.id);
+                    catch {
+                        for (const item of batch) {
+                            failedIds.push(item.id);
+                        }
                     }
                 }
-                catch (err) {
-                    const msg = (0, logger_js_1.formatSupabaseError)(err, { table: op.tableName, operation: 'UPDATE' });
-                    this.logger.error(msg);
-                    failedIds.push(op.id);
-                    errors[op.id] = msg;
-                }
-                i++;
                 continue;
             }
             i++;
@@ -438,6 +513,20 @@ class SupabaseRemoteAdapter {
             changes,
         };
     }
+    /**
+     * Formats a row payload for remote Supabase storage (adds primaryKey, deleted: false, updated_at).
+     */
+    buildRowData(item) {
+        const row = {
+            ...(item.payload || {}),
+            [this.primaryKey]: item.rowId,
+            [this.deletedColumn]: false,
+        };
+        if (this.updatedAtColumn && !row[this.updatedAtColumn]) {
+            row[this.updatedAtColumn] = new Date(item.timestamp).toISOString();
+        }
+        return row;
+    }
     /**
      * Helper to determine if a record represents a soft delete.
      */
@@ -454,6 +543,7 @@ class SupabaseRemoteAdapter {
     }
     /**
      * Subscribes to live realtime postgres_changes from Supabase.
+     * Batches rapid burst events in the same microtask turn into a single SQLite sync transaction.
      */
     subscribeToLiveChanges(callback) {
         this.activeLiveCallback = callback;
@@ -479,6 +569,23 @@ class SupabaseRemoteAdapter {
             };
         }
         const channel = client.channel(this.channelName);
+        let pendingLiveChanges = [];
+        let isScheduled = false;
+        const flushLiveChanges = () => {
+            isScheduled = false;
+            if (pendingLiveChanges.length === 0)
+                return;
+            const toSend = pendingLiveChanges;
+            pendingLiveChanges = [];
+            const maxTimestamp = Math.max(...toSend.map((c) => c.timestamp || 0), Date.now());
+            callback({
+                timestamp: maxTimestamp,
+                changes: toSend,
+            });
+        };
+        const scheduleFlush = typeof queueMicrotask === 'function'
+            ? queueMicrotask
+            : (fn) => setTimeout(fn, 0);
         for (const table of this.tables) {
             channel.on('postgres_changes', { event: '*', schema: this.schema, table }, (payload) => {
                 let op = 'UPDATE';
@@ -495,18 +602,17 @@ class SupabaseRemoteAdapter {
                 const timestamp = record[this.updatedAtColumn]
                     ? new Date(record[this.updatedAtColumn]).getTime()
                     : Date.now();
-                callback({
+                pendingLiveChanges.push({
+                    tableName: table,
+                    operation: finalOp,
+                    rowId,
+                    payload: finalOp === 'DELETE' ? null : record,
                     timestamp,
-                    changes: [
-                        {
-                            tableName: table,
-                            operation: finalOp,
-                            rowId,
-                            payload: finalOp === 'DELETE' ? null : record,
-                            timestamp,
-                        },
-                    ],
                 });
+                if (!isScheduled) {
+                    isScheduled = true;
+                    scheduleFlush(flushLiveChanges);
+                }
             });
         }
         channel.subscribe((status) => {
@@ -516,6 +622,7 @@ class SupabaseRemoteAdapter {
         });
         this.activeChannel = channel;
         return () => {
+            flushLiveChanges();
             this.activeLiveCallback = undefined;
             this.destroy();
         };

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>;
+    /**
+     * Executes a native SQLite SUM(column) query and returns the sum directly.
+     */
+    sum(tableName: string, column: string, options?: {
+        where?: WhereFilter;
+    }): Promise<number>;
     /**
-     * Internal findMany implementation shared between LocalFirstClient and TransactionalClient.
+     * Executes a native SQLite AVG(column) query and returns the average directly.
      */
-    findManyInternal<T = any>(db: DBExecutable, tableName: string, options?: QueryOptions): Promise<T[]>;
+    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.
      *
@@ -167,14 +212,6 @@ export declare class LocalFirstClient {
     findById<T = any>(tableName: string, id: string, options?: {
         includeDeleted?: boolean;
     }): Promise<T | null>;
-    /**
-     * Finds multiple records by primary keys in a single batched SQL query.
-     * Eliminates the N-roundtrip bridge overhead of multiple findById calls.
-     * Automatically omits soft-deleted records unless includeDeleted: true.
-     *
-     * Example:
-     * const tenants = await client.findByIds('tenants', ['ten-1', 'ten-2', 'ten-3']);
-     */
     findByIds<T = any>(tableName: string, ids: string[], options?: {
         includeDeleted?: boolean;
     }): Promise<T[]>;