local-lite 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 local-lite contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,362 @@
-# Temporary Holding Version
+# ⚡ local-lite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A lightweight, vendor-agnostic **local-first synchronization engine** for React Native, Expo, and Web applications.
+
+Built around the **Transactional Outbox Pattern**, `local-lite` ensures instant, zero-latency local writes in SQLite while guaranteeing offline resilience and asynchronous synchronization with your backend (including native **Supabase**, **Convex**, and **Firebase / Firestore** support).
+
+---
+
+## 📖 Documentation
+
+* **[Quickstart & Setup](docs/getting-started.md)** - 5-minute setup with Expo, React Native, or Node.js
+* **[Architecture](docs/architecture.md)** - Transactional outbox pattern, SyncWorker loops, and event pipeline
+* **[Configuration Reference](docs/configuration.md)** - Options for `defineSyncConfig()`, retries, and loggers
+* **[Local SQLite Adapters](docs/adapters-local.md)** - Expo SQLite, OP-SQLite, better-sqlite3, node:sqlite, and LibSQL
+* **[Remote Cloud Adapters](docs/adapters-remote.md)** - Supabase, Convex, Cloud Firestore, and custom adapters
+* **[React & Expo Hooks](docs/react-hooks.md)** - `useLiveQuery()` and `useOutboxStatus()`
+* **[Conflict Resolution](docs/conflict-resolution.md)** - LWW, Client-Wins, Server-Wins, and custom resolvers
+
+---
+
+## Features
+
+* **⚡ 0ms Optimistic Writes:** Write to local SQLite immediately via atomic dual-write (`client.mutate()`).
+* **📦 Transactional Outbox:** Mutations are stored atomically in a local `sync_outbox` table, preventing data loss if the app closes or loses connectivity mid-write.
+* **🌐 Native Cloud Adapters:** First-class sync with Postgres tables (via **Supabase**), reactive document datastores (via **Convex**), and document collections (via **Firebase / Firestore**).
+* **🛡️ Conflict Resolution:** Built-in strategies including **Last-Write-Wins (LWW)**, Server-Wins, Client-Wins, or custom resolver functions.
+* **📶 Network-Aware:** Automatically pauses polling when offline and triggers immediate sync flushes the instant connectivity is restored.
+* **🔄 Infinite-Loop Safe:** Incoming remote deltas update local tables and fire reactive UI listeners without echoing back into the outbox.
+
+---
+
+## Installation
+
+```bash
+npm install local-lite
+```
+
+Peer dependencies (install what you use):
+
+```bash
+# If using Expo SQLite
+npx expo install expo-sqlite @react-native-community/netinfo
+
+# If syncing with Supabase
+npm install @supabase/supabase-js
+
+# If syncing with Convex
+npm install convex
+
+# If syncing with Firebase / Firestore
+npm install firebase # or @react-native-firebase/firestore
+```
+
+---
+
+### 1. Define your Configuration (`sync.config.ts`)
+
+#### Option A: With Supabase
+
+```typescript
+// sync.config.ts
+import { defineSyncConfig, createSyncClient } from 'local-lite';
+import * as SQLite from 'expo-sqlite';
+
+export const syncConfig = defineSyncConfig({
+  database: () => SQLite.openDatabaseAsync('app.db'),
+  tables: ['todos', 'notes'],
+  autoSchema: true,
+
+  // Supabase backend configuration
+  supabase: {
+    url: process.env.EXPO_PUBLIC_SUPABASE_URL || 'https://xyz.supabase.co',
+    anonKey: process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY || 'YOUR_ANON_KEY',
+  },
+
+  conflictResolver: 'last-write-wins',
+});
+
+export const client = await createSyncClient(syncConfig);
+```
+
+#### Option B: With Convex
+
+```typescript
+// sync.config.ts
+import { defineSyncConfig, createSyncClient } from 'local-lite';
+import { ConvexClient } from 'convex/browser';
+import * as SQLite from 'expo-sqlite';
+
+const convexClient = new ConvexClient(process.env.EXPO_PUBLIC_CONVEX_URL!);
+
+export const syncConfig = defineSyncConfig({
+  database: () => SQLite.openDatabaseAsync('app.db'),
+  tables: ['properties', 'tenants'],
+  autoSchema: true,
+
+  // Convex backend configuration
+  convex: {
+    client: convexClient,
+    pushMutation: 'sync:pushBatch', // Or api.sync.pushBatch
+    pullQuery: 'sync:pullDeltas',   // Or api.sync.pullDeltas
+    deletedColumn: 'deleted',
+    updatedAtColumn: 'updatedAt',
+  },
+
+  conflictResolver: 'last-write-wins',
+});
+
+export const client = await createSyncClient(syncConfig);
+```
+
+#### Option C: With Firebase / Cloud Firestore
+
+```typescript
+// sync.config.ts
+import { defineSyncConfig, createSyncClient } from 'local-lite';
+import { initializeApp } from 'firebase/app';
+import { getFirestore } from 'firebase/firestore';
+import * as SQLite from 'expo-sqlite';
+
+const app = initializeApp({
+  apiKey: process.env.EXPO_PUBLIC_FIREBASE_API_KEY,
+  projectId: process.env.EXPO_PUBLIC_FIREBASE_PROJECT_ID,
+});
+const db = getFirestore(app);
+
+export const syncConfig = defineSyncConfig({
+  database: () => SQLite.openDatabaseAsync('app.db'),
+  tables: ['properties', 'tenants'],
+  autoSchema: true,
+
+  // Firebase Firestore backend configuration
+  firebase: {
+    firestore: db,                // Modular Firestore or @react-native-firebase/firestore
+    updatedAtColumn: 'updatedAt', // Timestamp field used for delta sync
+    deletedColumn: 'deleted',     // Soft delete flag
+  },
+
+  conflictResolver: 'last-write-wins',
+});
+
+export const client = await createSyncClient(syncConfig);
+```
+
+---
+
+### 2. Use in React Native / Expo UI
+
+```tsx
+import { useLiveQuery, useOutboxStatus } from 'local-lite';
+import { client } from './sync.config';
+
+export function TodoScreen() {
+  // ⚡ Zero-SQL Reactive Live Query (Auto re-renders on local writes AND background remote pulls!)
+  const { data: todos } = useLiveQuery(client, 'todos', {
+    orderBy: 'id',
+    order: 'desc',
+  });
+
+  const { pendingCount } = useOutboxStatus(client);
+
+  const addTodo = async (title: string) => {
+    await client.insert('todos', {
+      title,
+      completed: 0,
+    });
+  };
+
+  const toggleTodo = async (id: string, completed: number) => {
+    await client.update('todos', id, { completed: completed ? 0 : 1 });
+  };
+
+  const removeTodo = async (id: string) => {
+    await client.delete('todos', id);
+  };
+
+  return (
+    <View>
+      <Text>Pending outbox items: {pendingCount}</Text>
+      {todos.map(t => <Text key={t.id}>{t.title}</Text>)}
+    </View>
+  );
+}
+```
+
+---
+
+## Supabase Backend Setup & Schema
+
+To synchronize with Supabase using zero-clock-skew delta queries and `deleted: true` soft deletes, execute the following script in your Supabase project (**Dashboard → SQL Editor**):
+
+```sql
+-- 1. Automatic Timestamp Trigger
+CREATE OR REPLACE FUNCTION public.set_sync_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = timezone('utc'::text, now());
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- 2. Create Synced Table (e.g. 'todos')
+CREATE TABLE IF NOT EXISTS public.todos (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  completed INTEGER DEFAULT 0,
+  deleted BOOLEAN DEFAULT FALSE NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT timezone('utc'::text, now()) NOT NULL,
+  updated_at TIMESTAMPTZ DEFAULT timezone('utc'::text, now()) NOT NULL
+);
+
+-- 3. Index for high-performance delta sync queries
+CREATE INDEX IF NOT EXISTS idx_todos_sync ON public.todos (updated_at);
+
+-- 4. Auto-update updated_at on changes (including soft deletes)
+CREATE OR REPLACE TRIGGER trigger_todos_updated_at
+BEFORE UPDATE ON public.todos
+FOR EACH ROW EXECUTE FUNCTION public.set_sync_updated_at();
+
+-- 5. Enable Supabase Realtime broadcast replication
+ALTER PUBLICATION supabase_realtime ADD TABLE public.todos;
+```
+
+---
+
+## Convex Backend Setup & Functions
+
+In Convex, create a sync module (e.g., `convex/sync.ts`):
+
+```typescript
+// convex/sync.ts
+import { mutation, query } from "./_generated/server";
+import { v } from "convex/values";
+
+// 1. Push batch mutation from outbox
+export const pushBatch = mutation({
+  args: {
+    operations: v.array(
+      v.object({
+        id: v.string(),
+        tableName: v.string(),
+        rowId: v.string(),
+        operation: v.string(),
+        payload: v.any(),
+        timestamp: v.number(),
+      })
+    ),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    for (const op of args.operations) {
+      const table = op.tableName;
+      const existing = await ctx.db
+        .query(table as any)
+        .filter((q) => q.eq(q.field("id"), op.rowId))
+        .first();
+
+      if (op.operation === "DELETE") {
+        if (existing) {
+          await ctx.db.patch(existing._id, { deleted: true, updatedAt: now });
+        }
+      } else {
+        const doc = { ...(op.payload || {}), id: op.rowId, deleted: false, updatedAt: now };
+        if (existing) {
+          await ctx.db.patch(existing._id, doc);
+        } else {
+          await ctx.db.insert(table as any, doc);
+        }
+      }
+    }
+    return true;
+  },
+});
+
+// 2. Pull deltas query since timestamp cursor
+export const pullDeltas = query({
+  args: {
+    sinceTimestamp: v.number(),
+    tables: v.array(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const results: any[] = [];
+    for (const table of args.tables) {
+      const docs = await ctx.db
+        .query(table as any)
+        .filter((q) => q.gt(q.field("updatedAt"), args.sinceTimestamp))
+        .collect();
+
+      for (const d of docs) {
+        results.push({ ...d, tableName: table });
+      }
+    }
+    return results;
+  },
+});
+```
+
+---
+
+## Supported SQLite Drivers
+
+`local-lite` is fully driver-agnostic and auto-detects your SQLite instance directly:
+
+| Platform | Recommended Driver | Auto-Detected or Subpath Import |
+| :--- | :--- | :--- |
+| **Expo (iOS/Android/Web)** | `expo-sqlite` | `database: () => SQLite.openDatabaseAsync('app.db')` |
+| **Bare React Native** | `@op-engineering/op-sqlite` | `local-lite/op-sqlite` |
+| **Node.js / Electron / Desktop** | `better-sqlite3` | `local-lite/better-sqlite3` |
+| **Edge / Server / Turso** | `@libsql/client` (LibSQL) | `local-lite/libsql` |
+| **Web Browser / PWAs** | `sql.js` (WebAssembly) | `local-lite/sql-js` |
+| **Node.js 22+ (Built-in)** | `node:sqlite` (DatabaseSync) | `local-lite/node-sqlite` |
+
+---
+
+## Architecture
+
+```
+[ App UI ]
+    │
+    ▼
+LocalFirstClient ──(Atomic Transaction)──► Local SQLite Table
+    │                                             │
+    ▼                                             ▼
+sync_outbox (Pending queue)                 EventEmitter (UI refresh)
+    │
+    ▼ (Immediate / Debounced / Network-Aware)
+SyncWorker
+    │
+    ├──► pushChanges() ──► Remote Backend (Supabase / Convex / Firebase / Custom)
+    │
+    └──◄ fetchChanges() ◄── Remote Deltas (Merged via Conflict Resolver)
+```
+
+---
+
+## Example App
+
+An interactive Expo app is included in the [`example/`](./example) directory demonstrating:
+- Rental property & tenant management application
+- Live SQLite reads and atomic dual-writes
+- Network online/offline toggle simulation
+- Real-time `sync_outbox` inspector
+- Simulated server delta broadcasts
+
+To run the example:
+```bash
+cd example
+npm start
+```
+
+---
+
+## Testing
+
+Run the Vitest test suite:
+```bash
+npm test
+```
+
+## License
+
+MIT

package/dist/adapters/local/better-sqlite3.d.ts

@@ -0,0 +1,23 @@
+import { LocalDBAdapter, LocalTransaction } from './index.js';
+export interface BetterSqliteStatement {
+    reader?: boolean;
+    all(...params: any[]): any[];
+    run(...params: any[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+}
+export interface BetterSqliteDatabase {
+    prepare(query: string): BetterSqliteStatement;
+    exec?(sql: string): void;
+    close?(): void;
+}
+/**
+ * Adapter for better-sqlite3 in Node.js, Electron, Next.js, and server environments.
+ */
+export declare class BetterSQLite3Adapter implements LocalDBAdapter {
+    private db;
+    constructor(betterSqliteInstance: any);
+    execute(query: string, params?: any[]): Promise<any[]>;
+    transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
+}

package/dist/adapters/local/better-sqlite3.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BetterSQLite3Adapter = void 0;
+/**
+ * Adapter for better-sqlite3 in Node.js, Electron, Next.js, and server environments.
+ */
+class BetterSQLite3Adapter {
+    db;
+    constructor(betterSqliteInstance) {
+        this.db = betterSqliteInstance;
+    }
+    async execute(query, params = []) {
+        const trimmed = query.trim();
+        const stmt = this.db.prepare(trimmed);
+        // If query returns rows (SELECT, PRAGMA) or is marked as reader
+        if (stmt.reader || /^SELECT|^PRAGMA/i.test(trimmed)) {
+            return stmt.all(...params);
+        }
+        const info = stmt.run(...params);
+        return [info];
+    }
+    async transaction(action) {
+        // Explicit transaction control compatible with async actions
+        this.db.prepare('BEGIN IMMEDIATE').run();
+        try {
+            const txWrapper = {
+                execute: async (q, p = []) => {
+                    return await this.execute(q, p);
+                },
+            };
+            const result = await action(txWrapper);
+            this.db.prepare('COMMIT').run();
+            return result;
+        }
+        catch (err) {
+            try {
+                this.db.prepare('ROLLBACK').run();
+            }
+            catch {
+                // Ignore secondary rollback error if connection closed
+            }
+            throw err;
+        }
+    }
+}
+exports.BetterSQLite3Adapter = BetterSQLite3Adapter;

package/dist/adapters/local/expo-sqlite.d.ts

@@ -0,0 +1,8 @@
+import { LocalDBAdapter, LocalTransaction } from './index.js';
+export declare class ExpoSQLiteAdapter implements LocalDBAdapter {
+    private db;
+    private txMutex;
+    constructor(expoDbInstance: any);
+    execute(query: string, params?: any[]): Promise<any[]>;
+    transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
+}

package/dist/adapters/local/expo-sqlite.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExpoSQLiteAdapter = void 0;
+class ExpoSQLiteAdapter {
+    db;
+    txMutex = Promise.resolve();
+    constructor(expoDbInstance) {
+        this.db = expoDbInstance;
+    }
+    async execute(query, params = []) {
+        return await this.db.getAllAsync(query, params);
+    }
+    async transaction(action) {
+        const run = async () => {
+            let result;
+            await this.db.withTransactionAsync(async () => {
+                const txWrapper = {
+                    execute: async (q, p = []) => await this.db.getAllAsync(q, p)
+                };
+                result = await action(txWrapper);
+            });
+            return result;
+        };
+        // Serialize transactions to prevent SQLite "cannot start a transaction within a transaction"
+        const currentTx = this.txMutex.then(run, run);
+        this.txMutex = currentTx.catch(() => { });
+        return await currentTx;
+    }
+}
+exports.ExpoSQLiteAdapter = ExpoSQLiteAdapter;

package/dist/adapters/local/index.d.ts

@@ -0,0 +1,13 @@
+export interface LocalTransaction {
+    execute(query: string, params?: any[]): Promise<any[]>;
+}
+export interface LocalDBAdapter {
+    execute(query: string, params?: any[]): Promise<any[]>;
+    transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
+}
+export * from './expo-sqlite.js';
+export * from './op-sqlite.js';
+export * from './better-sqlite3.js';
+export * from './libsql.js';
+export * from './sql-js.js';
+export * from './node-sqlite.js';

package/dist/adapters/local/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./expo-sqlite.js"), exports);
+__exportStar(require("./op-sqlite.js"), exports);
+__exportStar(require("./better-sqlite3.js"), exports);
+__exportStar(require("./libsql.js"), exports);
+__exportStar(require("./sql-js.js"), exports);
+__exportStar(require("./node-sqlite.js"), exports);

package/dist/adapters/local/libsql.d.ts

@@ -0,0 +1,24 @@
+import { LocalDBAdapter, LocalTransaction } from './index.js';
+export interface LibSQLRow {
+    [key: string]: any;
+}
+export interface LibSQLResultSet {
+    columns: string[];
+    rows: any[];
+    rowsAffected?: number;
+    lastInsertRowid?: bigint | number;
+}
+export interface LibSQLClient {
+    execute(stmt: any): Promise<LibSQLResultSet>;
+    transaction?(mode?: 'write' | 'read' | 'deferred'): Promise<any>;
+}
+/**
+ * Adapter for @libsql/client (Turso & LibSQL).
+ * Supports local SQLite files, embedded replicas, in-memory databases, and server/edge deployments.
+ */
+export declare class LibSQLAdapter implements LocalDBAdapter {
+    private client;
+    constructor(libsqlClient: any);
+    execute(query: string, params?: any[]): Promise<any[]>;
+    transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
+}

package/dist/adapters/local/libsql.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LibSQLAdapter = void 0;
+function normalizeRows(res) {
+    if (!res || !res.rows)
+        return [];
+    const { columns, rows } = res;
+    if (rows.length === 0)
+        return [];
+    // If rows are already standard objects
+    if (typeof rows[0] === 'object' && !Array.isArray(rows[0]) && rows[0] !== null) {
+        return rows;
+    }
+    // If rows are tuples/arrays, map them to column names
+    if (Array.isArray(rows[0]) && Array.isArray(columns)) {
+        return rows.map((rowArr) => {
+            const obj = {};
+            columns.forEach((col, i) => {
+                obj[col] = rowArr[i];
+            });
+            return obj;
+        });
+    }
+    return rows;
+}
+/**
+ * Adapter for @libsql/client (Turso & LibSQL).
+ * Supports local SQLite files, embedded replicas, in-memory databases, and server/edge deployments.
+ */
+class LibSQLAdapter {
+    client;
+    constructor(libsqlClient) {
+        this.client = libsqlClient;
+    }
+    async execute(query, params = []) {
+        const res = await this.client.execute({
+            sql: query,
+            args: params,
+        });
+        return normalizeRows(res);
+    }
+    async transaction(action) {
+        if (typeof this.client.transaction === 'function') {
+            const tx = await this.client.transaction('write');
+            try {
+                const txWrapper = {
+                    execute: async (q, p = []) => {
+                        const res = await tx.execute({ sql: q, args: p });
+                        return normalizeRows(res);
+                    },
+                };
+                const result = await action(txWrapper);
+                await tx.commit();
+                return result;
+            }
+            catch (err) {
+                try {
+                    await tx.rollback();
+                }
+                catch {
+                    // ignore rollback failure
+                }
+                throw err;
+            }
+        }
+        // Fallback using SQL statements
+        await this.execute('BEGIN IMMEDIATE');
+        try {
+            const txWrapper = {
+                execute: async (q, p = []) => this.execute(q, p),
+            };
+            const result = await action(txWrapper);
+            await this.execute('COMMIT');
+            return result;
+        }
+        catch (err) {
+            try {
+                await this.execute('ROLLBACK');
+            }
+            catch {
+                // ignore
+            }
+            throw err;
+        }
+    }
+}
+exports.LibSQLAdapter = LibSQLAdapter;

package/dist/adapters/local/node-sqlite.d.ts

@@ -0,0 +1,24 @@
+import { LocalDBAdapter, LocalTransaction } from './index.js';
+export interface NodeSqliteStatement {
+    all(...params: any[]): any[];
+    run(...params: any[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get?(...params: any[]): any;
+}
+export interface NodeSqliteDatabaseSync {
+    prepare(sql: string): NodeSqliteStatement;
+    exec(sql: string): void;
+    close?(): void;
+}
+/**
+ * Adapter for Node.js 22+ built-in `node:sqlite` (DatabaseSync).
+ * Provides zero-dependency, native SQLite on modern Node.js runtimes.
+ */
+export declare class NodeSQLiteAdapter implements LocalDBAdapter {
+    private db;
+    constructor(nodeSqliteDb: any);
+    execute(query: string, params?: any[]): Promise<any[]>;
+    transaction<T>(action: (tx: LocalTransaction) => Promise<T>): Promise<T>;
+}