local-lite 0.0.3 → 0.0.5

package/dist/config/resolve-local.js

@@ -51,8 +51,19 @@ async function resolveLocalAdapter(config) {
     // 9. Auto-open by name using expo-sqlite if available
     if (typeof rawDb === 'string' || config.databaseName) {
         const dbName = typeof rawDb === 'string' ? rawDb : (config.databaseName ?? 'local_lite.db');
+        let expoSqlite;
         try {
-            const expoSqlite = await import('expo-sqlite');
+            if (typeof require === 'function') {
+                expoSqlite = require('expo-sqlite');
+            }
+        }
+        catch {
+            // ignore
+        }
+        try {
+            if (!expoSqlite) {
+                expoSqlite = await import('expo-sqlite');
+            }
             if (expoSqlite && typeof expoSqlite.openDatabaseAsync === 'function') {
                 const expoDb = await expoSqlite.openDatabaseAsync(dbName);
                 return new expo_sqlite_js_1.ExpoSQLiteAdapter(expoDb);

package/dist/config/resolve-remote.js

@@ -35,47 +35,52 @@ async function resolveRemoteAdapter(config) {
             updatedAtColumn: config.convex.updatedAtColumn,
         });
     }
+    const getSupabaseOptions = () => ({
+        tables: config.tables,
+        primaryKey: config.primaryKey,
+        schema: config.supabase?.schema,
+        updatedAtColumn: config.supabase?.updatedAtColumn,
+        deletedColumn: config.supabase?.deletedColumn,
+        deletedValue: config.supabase?.deletedValue,
+        deletedAtColumn: config.supabase?.deletedAtColumn,
+        pushRpcName: config.supabase?.pushRpcName,
+        channelName: config.supabase?.channelName,
+        scopedTables: config.supabase?.scopedTables,
+    });
     // 4. Supabase with pre-configured client
     if (config.supabase?.client) {
-        return new supabase_js_1.SupabaseRemoteAdapter(config.supabase.client, {
-            tables: config.tables,
-            primaryKey: config.primaryKey,
-            schema: config.supabase.schema,
-            updatedAtColumn: config.supabase.updatedAtColumn,
-            deletedColumn: config.supabase.deletedColumn,
-            deletedValue: config.supabase.deletedValue,
-            deletedAtColumn: config.supabase.deletedAtColumn,
-            pushRpcName: config.supabase.pushRpcName,
-            channelName: config.supabase.channelName,
-        });
+        return new supabase_js_1.SupabaseRemoteAdapter(config.supabase.client, getSupabaseOptions());
     }
     // 5. Supabase with URL + anonKey (lazy dynamic import)
     if (config.supabase?.url && config.supabase?.anonKey) {
         let supabaseModule;
+        // In CommonJS / React Native Metro environments, synchronous require avoids async chunk split failure
         try {
-            // @ts-ignore
-            supabaseModule = await import('@supabase/supabase-js');
+            if (typeof require === 'function') {
+                supabaseModule = require('@supabase/supabase-js');
+            }
         }
         catch {
-            throw new Error('To initialize Supabase from url and anonKey, please install @supabase/supabase-js or provide a pre-configured client to config.supabase.client');
+            // ignore
+        }
+        if (!supabaseModule && typeof globalThis?.supabase?.createClient === 'function') {
+            supabaseModule = globalThis.supabase;
+        }
+        if (!supabaseModule) {
+            try {
+                supabaseModule = await import('@supabase/supabase-js');
+            }
+            catch {
+                throw new Error('To initialize Supabase from url and anonKey, please install @supabase/supabase-js or provide a pre-configured client to config.supabase.client');
+            }
         }
         const createClientFn = supabaseModule.createClient || supabaseModule.default?.createClient;
         const supabaseClient = createClientFn(config.supabase.url, config.supabase.anonKey);
-        return new supabase_js_1.SupabaseRemoteAdapter(supabaseClient, {
-            tables: config.tables,
-            primaryKey: config.primaryKey,
-            schema: config.supabase.schema,
-            updatedAtColumn: config.supabase.updatedAtColumn,
-            deletedColumn: config.supabase.deletedColumn,
-            deletedValue: config.supabase.deletedValue,
-            deletedAtColumn: config.supabase.deletedAtColumn,
-            pushRpcName: config.supabase.pushRpcName,
-            channelName: config.supabase.channelName,
-        });
+        return new supabase_js_1.SupabaseRemoteAdapter(supabaseClient, getSupabaseOptions());
     }
-    // 6. In-Memory Simulated Remote (Default when no cloud credentials provided)
-    if (config.inMemoryRemote !== false) {
+    // 6. Explicitly selected demo backend only; never acknowledge writes into a temporary backend implicitly.
+    if (config.inMemoryRemote === true) {
         return new demo_js_1.MemoryDemoRemoteAdapter(300);
     }
-    throw new Error('No remote adapter configured. Please specify config.supabase, config.convex, config.firebase, or config.remote.');
+    throw new Error('No remote adapter configured. Please specify config.supabase, config.convex, config.firebase, or config.remote. For demos only, explicitly set config.inMemoryRemote: true.');
 }

package/dist/config/types.d.ts

@@ -13,6 +13,7 @@ export interface SupabaseConfigOptions {
     deletedAtColumn?: string;
     pushRpcName?: string;
     channelName?: string;
+    scopedTables?: string[];
 }
 export interface ConvexConfigOptions {
     /**
@@ -74,7 +75,7 @@ export interface LocalLiteConfig {
      */
     database?: any | string | (() => Promise<any> | any) | LocalDBAdapter;
     /**
-     * Database name if database is not provided. Default: 'local_lite.db'
+     * Explicit database filename for the Expo convenience opener when database is not provided.
      */
     databaseName?: string;
     /**
@@ -89,7 +90,7 @@ export interface LocalLiteConfig {
     migrations?: string[];
     /**
      * Automatically create tables and columns dynamically on the fly without manual SQL migrations.
-     * When true (default if migrations is not provided), tables in `tables` are created automatically,
+     * Opt-in (default: false). When true, tables in `tables` are created automatically,
      * and any missing columns are added dynamically on insert/update/pull.
      */
     autoSchema?: boolean;
@@ -114,9 +115,9 @@ export interface LocalLiteConfig {
      */
     remote?: RemoteDBAdapter;
     /**
-     * Whether to use an in-memory simulated remote backend if Supabase, Convex, or Firebase credentials are not provided.
-     * Allows running and testing full local-first sync workflows without cloud infrastructure.
-     * Default: true
+     * Explicitly enable a temporary simulated remote for demos when no backend is provided.
+     * Acknowledged writes exist only in memory. Never enabled implicitly.
+     * Default: false
      */
     inMemoryRemote?: boolean;
     /**
@@ -131,6 +132,12 @@ export interface LocalLiteConfig {
      * Periodic remote pull interval in ms. Default: 10000
      */
     pullIntervalMs?: number;
+    /**
+     * Automatically pause recurring sync timers and listeners when the app is backgrounded
+     * (React Native AppState or Web Page Visibility API), and resume when foregrounded.
+     * Default: true
+     */
+    autoPauseOnBackground?: boolean;
     /**
      * Maximum retry attempts for failed push items. Default: 5
      */
@@ -156,4 +163,22 @@ export interface LocalLiteConfig {
      * Default: true
      */
     autoInitialize?: boolean;
+    /**
+     * Start automatic sync after initialization. Default: true.
+     * Set false to initialize storage and queue writes without timers or subscriptions.
+     * Call client.syncWorker.start() to enable automatic sync, or push/pull manually.
+     */
+    autoStart?: boolean;
+    /**
+     * Explicitly configured JSON column map per table name.
+     */
+    jsonColumns?: Record<string, string[]>;
+    /**
+     * Automatically detect and hydrate stringified JSON objects and arrays across all columns.
+     */
+    autoHydrateJSON?: boolean;
+    /**
+     * 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

@@ -3,8 +3,9 @@ import { RemoteDBAdapter } from '../adapters/remote/index.js';
 import { EventEmitter } from '../reactive/event-emitter.js';
 import { SyncWorker } from './sync-worker.js';
 import { SchemaManager } from './schema-manager.js';
-import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SyncMetrics, SyncOp, TableChangeEvent } from './types.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;
@@ -19,6 +20,13 @@ export interface LocalFirstClientConfig {
     logLevel?: LogLevel;
     autoSchema?: boolean;
     tables?: string[];
+    migrations?: string[];
+    autoStart?: boolean;
+    coalesceOutbox?: boolean;
+    jsonColumns?: Record<string, string[]>;
+    autoHydrateJSON?: boolean;
+    syncScope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>);
+    autoPauseOnBackground?: boolean;
 }
 export declare class TransactionalClient {
     private parent;
@@ -32,7 +40,20 @@ export declare class TransactionalClient {
     mutate(tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, options?: MutateOptions): Promise<void>;
     insert(tableName: string, rowIdOrPayload: string | Record<string, any>, payloadOrOptions?: Record<string, any> | MutateOptions, options?: MutateOptions): Promise<string>;
     update(tableName: string, rowId: string, payload: Record<string, any>, options?: MutateOptions): Promise<void>;
+    updateMany(tableName: string, updates: Array<{
+        id: string;
+        payload: Record<string, any>;
+    }>, options?: MutateOptions): Promise<void>;
     delete(tableName: string, rowId: string, options?: MutateOptions): Promise<void>;
+    findById<T = any>(tableName: string, id: string, options?: {
+        includeDeleted?: boolean;
+    }): Promise<T | null>;
+    findByIds<T = any>(tableName: string, ids: string[], options?: {
+        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 {
@@ -42,15 +63,32 @@ export declare class LocalFirstClient {
     syncWorker: SyncWorker;
     schemaManager: SchemaManager;
     autoSchema: boolean;
+    coalesceOutbox: boolean;
     tables: string[];
+    jsonColumns: Record<string, string[]>;
+    autoHydrateJSON: boolean;
     private primaryKey;
+    private migrations;
+    private autoStart;
+    private initialization?;
     constructor(config: LocalFirstClientConfig);
     getPrimaryKey(): string;
+    /**
+     * Automatically deserializes JSON string columns into JavaScript objects/arrays.
+     */
+    hydrateRow<T = any>(tableName: string, row: any): T;
+    /**
+     * Writes a mutation to the outbox table, optionally coalescing with existing PENDING records for the same row.
+     * Returns the affected outboxId, or undefined if an offline INSERT was deleted offline before pushing.
+     */
+    recordOutboxMutation(tx: LocalTransaction, tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, timestamp: number): Promise<string | undefined>;
     /**
      * Initializes the client: creates sync_outbox schema, ensures autoSchema tables if enabled,
-     * and starts the background sync worker.
+     * applies migrations, and optionally starts automatic sync. Concurrent/repeated calls
+     * share initialization; failures can be retried. After stop(), explicitly start the worker.
      */
     initialize(): Promise<void>;
+    private initializeStorage;
     /**
      * Performs an atomic dual-write: mutates the local data table AND writes
      * to sync_outbox within the same database transaction.
@@ -87,6 +125,20 @@ export declare class LocalFirstClient {
      * await client.update('todos', 'todo-1', { completed: 1 });
      */
     update(tableName: string, rowId: string, payload: Record<string, any>, options?: MutateOptions): Promise<void>;
+    /**
+     * Updates multiple records atomically in a single database transaction.
+     * Emits reactive change events and queues outbox entries together.
+     *
+     * Example:
+     * await client.updateMany('todos', [
+     *   { id: 'todo-1', payload: { completed: 1 } },
+     *   { id: 'todo-2', payload: { completed: 1 } },
+     * ]);
+     */
+    updateMany(tableName: string, updates: Array<{
+        id: string;
+        payload: Record<string, any>;
+    }>, options?: MutateOptions): Promise<void>;
     /**
      * Convenience helper to delete a record by ID.
      *
@@ -97,12 +149,59 @@ export declare class LocalFirstClient {
     /**
      * Reads records from a local SQLite table without requiring manual SQL.
      * Supports where filtering with rich operators ($in, $gt, $contains, $or, etc.), order, limit, and offset.
+     * 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();
+     */
+    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>;
+    /**
+     * 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.
@@ -110,7 +209,20 @@ export declare class LocalFirstClient {
      * Example:
      * const tenant = await client.findById('tenants', 'ten-1');
      */
-    findById<T = any>(tableName: string, id: string): Promise<T | null>;
+    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[]>;
     /**
      * Tracks an existing mutation into sync_outbox without modifying the table.
      * Can accept an external transaction `options.tx` for custom atomic SQL workflows.
@@ -146,8 +258,24 @@ export declare class LocalFirstClient {
      * to query all remote records.
      */
     resetSyncCursor(): Promise<void>;
+    /**
+     * Dynamically sets or updates the active sync scope.
+     */
+    setSyncScope(scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): void;
     /**
      * Stops all active intervals, background sync loops, and network listeners.
      */
     stop(): void;
+    /**
+     * Stops background sync workers, cleans up remote listeners,
+     * and closes the local database adapter connection (releasing native locks).
+     */
+    close(): Promise<void>;
+    /**
+     * Resets local state by stopping sync and deleting or dropping all managed tables,
+     * clearing the sync_outbox and _sync_meta stores, and resetting the sync cursor.
+     */
+    reset(options?: {
+        dropTables?: boolean;
+    }): Promise<void>;
 }