local-lite 0.0.0-stage → 0.0.2

package/dist/config/types.d.ts

@@ -0,0 +1,159 @@
+import { LocalDBAdapter } from '../adapters/local/index.js';
+import { RemoteDBAdapter } from '../adapters/remote/index.js';
+import { ConflictResolver, ConflictStrategy, NetworkStatusProvider, RetryConfig } from '../core/types.js';
+import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
+export interface SupabaseConfigOptions {
+    url?: string;
+    anonKey?: string;
+    client?: any;
+    schema?: string;
+    updatedAtColumn?: string;
+    deletedColumn?: string;
+    deletedValue?: any;
+    deletedAtColumn?: string;
+    pushRpcName?: string;
+    channelName?: string;
+}
+export interface ConvexConfigOptions {
+    /**
+     * ConvexClient instance.
+     */
+    client: any;
+    /**
+     * Primary key field name. Default: config.primaryKey or 'id'
+     */
+    primaryKey?: string;
+    /**
+     * Convex mutation function or name for pushing changes.
+     * Default: 'sync:pushBatch'
+     */
+    pushMutation?: any;
+    /**
+     * Convex query function or name for pulling changes.
+     * Default: 'sync:pullDeltas'
+     */
+    pullQuery?: any;
+    /**
+     * Column used for soft deletes. Default: 'deleted'
+     */
+    deletedColumn?: string;
+    /**
+     * Column used for updatedAt timestamp. Default: 'updatedAt'
+     */
+    updatedAtColumn?: string;
+}
+export interface FirebaseConfigOptions {
+    /**
+     * Firestore database instance (from modular firebase/firestore, @react-native-firebase/firestore, or compat SDK).
+     */
+    firestore: any;
+    /**
+     * Primary key field name. Default: config.primaryKey or 'id'
+     */
+    primaryKey?: string;
+    /**
+     * Field used for soft deletes. Default: 'deleted'
+     */
+    deletedColumn?: string;
+    /**
+     * Field used for updatedAt timestamp tracking. Default: 'updatedAt'
+     */
+    updatedAtColumn?: string;
+    /**
+     * Optional reference to modular firebase/firestore module if not globally available.
+     */
+    firestoreModule?: any;
+}
+export interface LocalLiteConfig {
+    /**
+     * Local SQLite Database instance, name, factory function, or LocalDBAdapter.
+     * - Pass an Expo database instance (e.g. from SQLite.openDatabaseAsync('app.db'))
+     * - Pass a factory: () => SQLite.openDatabaseAsync('app.db')
+     * - Pass a database file name: 'app.db'
+     * - Or a custom LocalDBAdapter
+     */
+    database?: any | string | (() => Promise<any> | any) | LocalDBAdapter;
+    /**
+     * Database name if database is not provided. Default: 'local_lite.db'
+     */
+    databaseName?: string;
+    /**
+     * List of tables to sync.
+     * e.g. ['todos', 'notes']
+     */
+    tables?: string[];
+    /**
+     * Initial SQL table schema migration queries to execute on startup.
+     * e.g. ["CREATE TABLE IF NOT EXISTS todos (id TEXT PRIMARY KEY, title TEXT);"]
+     */
+    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,
+     * and any missing columns are added dynamically on insert/update/pull.
+     */
+    autoSchema?: boolean;
+    /**
+     * Primary key column. Default: 'id'
+     */
+    primaryKey?: string;
+    /**
+     * Supabase backend connection options.
+     */
+    supabase?: SupabaseConfigOptions;
+    /**
+     * Convex backend connection options.
+     */
+    convex?: ConvexConfigOptions;
+    /**
+     * Firebase / Firestore backend connection options.
+     */
+    firebase?: FirebaseConfigOptions;
+    /**
+     * Custom remote adapter (overrides Supabase / Convex / Firebase).
+     */
+    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
+     */
+    inMemoryRemote?: boolean;
+    /**
+     * Conflict resolution strategy. Default: 'last-write-wins'
+     */
+    conflictResolver?: ConflictStrategy | ConflictResolver;
+    /**
+     * Periodic outbox push interval in ms. Default: 5000
+     */
+    pushIntervalMs?: number;
+    /**
+     * Periodic remote pull interval in ms. Default: 10000
+     */
+    pullIntervalMs?: number;
+    /**
+     * Maximum retry attempts for failed push items. Default: 5
+     */
+    maxRetries?: number;
+    /**
+     * Advanced retry configuration with exponential backoff and custom retry predicates.
+     */
+    retry?: number | RetryConfig;
+    /**
+     * Custom logger or false to silence logs in production.
+     */
+    logger?: SyncLogger | CustomLogger | boolean;
+    /**
+     * Minimum log level. Default: 'info'
+     */
+    logLevel?: LogLevel;
+    /**
+     * Network status provider. Default: DefaultNetworkStatusProvider
+     */
+    network?: NetworkStatusProvider;
+    /**
+     * Automatically call client.initialize() and create tables.
+     * Default: true
+     */
+    autoInitialize?: boolean;
+}

package/dist/config/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/client.d.ts

@@ -0,0 +1,153 @@
+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 } from './schema-manager.js';
+import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SyncMetrics, SyncOp, TableChangeEvent } from './types.js';
+import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
+export interface LocalFirstClientConfig {
+    local: LocalDBAdapter;
+    remote: RemoteDBAdapter;
+    network?: NetworkStatusProvider;
+    conflictResolver?: ConflictStrategy | ConflictResolver;
+    primaryKey?: string;
+    pushIntervalMs?: number;
+    pullIntervalMs?: number;
+    maxRetries?: number;
+    retry?: number | RetryConfig;
+    logger?: SyncLogger | CustomLogger | boolean;
+    logLevel?: LogLevel;
+    autoSchema?: boolean;
+    tables?: string[];
+}
+export declare class TransactionalClient {
+    private parent;
+    private tx;
+    private queuedTableEvents;
+    private queuedOutboxIds;
+    constructor(parent: LocalFirstClient, tx: LocalTransaction, queuedTableEvents: Array<{
+        tableName: string;
+        event: TableChangeEvent;
+    }>, queuedOutboxIds: string[]);
+    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>;
+    delete(tableName: string, rowId: string, options?: MutateOptions): Promise<void>;
+    get rawTx(): LocalTransaction;
+}
+export declare class LocalFirstClient {
+    db: LocalDBAdapter;
+    remote: RemoteDBAdapter;
+    events: EventEmitter;
+    syncWorker: SyncWorker;
+    schemaManager: SchemaManager;
+    autoSchema: boolean;
+    tables: string[];
+    private primaryKey;
+    constructor(config: LocalFirstClientConfig);
+    getPrimaryKey(): string;
+    /**
+     * Initializes the client: creates sync_outbox schema, ensures autoSchema tables if enabled,
+     * and starts the background sync worker.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Performs an atomic dual-write: mutates the local data table AND writes
+     * to sync_outbox within the same database transaction.
+     */
+    mutate(tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, options?: MutateOptions): Promise<void>;
+    /**
+     * Executes multiple mutations in a single atomic database transaction.
+     * Inserts all corresponding outbox entries together and schedules a single push.
+     */
+    batch(mutations: BatchMutation[], options?: MutateOptions): Promise<string[]>;
+    /**
+     * Convenience helper to insert an array of records into a table atomically.
+     */
+    insertMany(tableName: string, records: Record<string, any>[], options?: MutateOptions): Promise<string[]>;
+    /**
+     * Runs an arbitrary callback inside an atomic transaction with a scoped TransactionalClient.
+     * If the callback resolves, all changes and outbox records commit and events are emitted.
+     * If the callback throws, SQLite rolls back and no change events are emitted.
+     */
+    transaction<T>(action: (txClient: TransactionalClient) => Promise<T>): Promise<T>;
+    /**
+     * Convenience helper to insert a record into a table.
+     * Auto-generates a UUID if rowId is omitted or passed inside payload.
+     *
+     * Example:
+     * await client.insert('todos', { title: 'Buy milk' });
+     * await client.insert('todos', 'custom-id', { title: 'Buy milk' });
+     */
+    insert(tableName: string, rowIdOrPayload: string | Record<string, any>, payloadOrOptions?: Record<string, any> | MutateOptions, options?: MutateOptions): Promise<string>;
+    /**
+     * Convenience helper to update an existing record by ID.
+     *
+     * Example:
+     * await client.update('todos', 'todo-1', { completed: 1 });
+     */
+    update(tableName: string, rowId: string, payload: Record<string, any>, options?: MutateOptions): Promise<void>;
+    /**
+     * Convenience helper to delete a record by ID.
+     *
+     * Example:
+     * await client.delete('todos', 'todo-1');
+     */
+    delete(tableName: string, rowId: string, options?: MutateOptions): Promise<void>;
+    /**
+     * 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.
+     * Gracefully returns [] if table or columns have not been populated yet on empty schemas.
+     *
+     * Example:
+     * const tenants = await client.findMany('tenants', { where: { status: 'ACTIVE' }, orderBy: 'name' });
+     * const expensive = await client.findMany('properties', { where: { rent: { $gte: 2000 } } });
+     */
+    findMany<T = any>(tableName: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Finds a single record by primary key.
+     *
+     * Example:
+     * const tenant = await client.findById('tenants', 'ten-1');
+     */
+    findById<T = any>(tableName: string, id: string): Promise<T | null>;
+    /**
+     * Tracks an existing mutation into sync_outbox without modifying the table.
+     * Can accept an external transaction `options.tx` for custom atomic SQL workflows.
+     */
+    trackMutation(tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, options?: MutateOptions): Promise<string>;
+    /**
+     * Returns real-time telemetry metrics captured by the sync engine.
+     */
+    getMetrics(): Promise<SyncMetrics>;
+    /**
+     * Fetches outbox records with optional status filtering and pagination.
+     */
+    getOutboxRecords(options?: {
+        status?: OutboxStatus;
+        limit?: number;
+        offset?: number;
+    }): Promise<OutboxRecord[]>;
+    /**
+     * Re-queues failed outbox mutations for retry by resetting their status to PENDING.
+     * Triggers an immediate sync push.
+     */
+    retryFailedMutations(ids?: string[]): Promise<number>;
+    /**
+     * Permanently clears failed mutations (removes poison-pill outbox records).
+     */
+    clearFailedMutations(ids?: string[]): Promise<number>;
+    /**
+     * Retrieves the persisted last_synced_at timestamp cursor (in ms).
+     */
+    getLastSyncedAt(): Promise<number>;
+    /**
+     * Resets the persistent sync cursor back to 0, forcing the next pull
+     * to query all remote records.
+     */
+    resetSyncCursor(): Promise<void>;
+    /**
+     * Stops all active intervals, background sync loops, and network listeners.
+     */
+    stop(): void;
+}