local-lite 0.0.24 → 0.0.27

package/README.md

@@ -63,9 +63,10 @@ remain configurable; the existing default conflict strategy is last-write-wins.
   `inMemoryRemote: true`; it must never silently acknowledge production writes.
 - `autoSchema` now defaults to `false` in the configuration factory as well as the
   core constructor. Set `autoSchema: true` to retain inferred schema behavior.
-- Migrations run transactionally before sync starts, including when initialization
-  is deferred with `autoInitialize: false`. Use idempotent SQL; this is not a
-  versioned migration framework.
+- Versioned `schemaMigrations` run transactionally before sync starts, including
+  when initialization is deferred with `autoInitialize: false`. The existing
+  `migrations` option remains available for legacy idempotent SQL that runs on
+  every initialization.
 - `initialize()` is safe to call repeatedly or concurrently. After `stop()`, call
   `client.syncWorker.start()` to resume. Mutations after stop remain queued.
 - `autoStart: false` prepares storage without automatic sync. Explicit push/pull

package/dist/adapters/remote/convex.js

@@ -4,6 +4,27 @@ exports.createConvexStorageUploader = exports.ConvexRemoteAdapter = void 0;
 const logger_js_1 = require("../../utils/logger.js");
 const convex_js_1 = require("../../storage/convex.js");
 Object.defineProperty(exports, "createConvexStorageUploader", { enumerable: true, get: function () { return convex_js_1.createConvexStorageUploader; } });
+function getRowTimestamp(value, fallback) {
+    const timestamp = value ?? fallback;
+    if (typeof timestamp === 'number' && Number.isFinite(timestamp))
+        return timestamp;
+    if (typeof timestamp === 'string') {
+        const numeric = Number(timestamp);
+        if (timestamp.trim() !== '' && Number.isFinite(numeric))
+            return numeric;
+        const parsed = Date.parse(timestamp);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    throw new Error('Convex change is missing a valid updatedAt timestamp.');
+}
+function getRowId(row, primaryKey) {
+    const id = row?.[primaryKey] ?? row?._id ?? row?.id;
+    if (id === undefined || id === null || String(id).length === 0) {
+        throw new Error('Convex change is missing its document ID.');
+    }
+    return String(id);
+}
 class ConvexRemoteAdapter {
     client;
     tables;
@@ -95,11 +116,11 @@ class ConvexRemoteAdapter {
                         (row[this.deletedColumn] &&
                             !['false', '0', 'null', 'undefined'].includes(String(row[this.deletedColumn]).toLowerCase())));
                     const operation = isSoftDeleted ? 'DELETE' : 'UPDATE';
-                    const rowTime = Number(row[this.updatedAtColumn] || row._creationTime || Date.now());
+                    const rowTime = getRowTimestamp(row[this.updatedAtColumn], row._creationTime);
                     if (rowTime > maxServerTimestamp) {
                         maxServerTimestamp = rowTime;
                     }
-                    const rowId = String(row[this.primaryKey] || row._id || row.id);
+                    const rowId = getRowId(row, this.primaryKey);
                     const tableName = row.tableName || row._table || (this.tables.length === 1 ? this.tables[0] : 'default');
                     changes.push({
                         tableName,
@@ -118,7 +139,7 @@ class ConvexRemoteAdapter {
         }
         catch (error) {
             this.logger.error((0, logger_js_1.formatConvexError)(error, { operation: 'fetchChanges' }));
-            return { timestamp: sinceTimestamp, changes: [] };
+            throw error;
         }
     }
     /**
@@ -147,8 +168,8 @@ class ConvexRemoteAdapter {
                     const changes = data.map((row) => {
                         const isSoftDeleted = Boolean(row[this.deletedColumn] === true);
                         const op = isSoftDeleted ? 'DELETE' : 'UPDATE';
-                        const rowTime = Number(row[this.updatedAtColumn] || row._creationTime || Date.now());
-                        const rowId = String(row[this.primaryKey] || row._id || row.id);
+                        const rowTime = getRowTimestamp(row[this.updatedAtColumn], row._creationTime);
+                        const rowId = getRowId(row, this.primaryKey);
                         const tableName = row.tableName || row._table || (this.tables[0] ?? 'default');
                         return {
                             tableName,

package/dist/adapters/remote/firestore.js

@@ -8,10 +8,20 @@ Object.defineProperty(exports, "createFirebaseStorageUploader", { enumerable: tr
  * Safely extracts epoch milliseconds from numbers, Firestore Timestamps, or ISO strings.
  */
 function extractTimestamp(val) {
-    if (!val)
-        return Date.now();
-    if (typeof val === 'number')
+    if (val == null) {
+        throw new Error('Firestore change is missing its updatedAt timestamp.');
+    }
+    if (typeof val === 'number' && Number.isFinite(val))
         return val;
+    if (typeof val === 'string') {
+        const numeric = Number(val);
+        if (val.trim() !== '' && Number.isFinite(numeric))
+            return numeric;
+        const parsed = Date.parse(val);
+        if (Number.isFinite(parsed))
+            return parsed;
+        throw new Error(`Firestore change has an invalid updatedAt timestamp: ${val}`);
+    }
     if (typeof val.toMillis === 'function')
         return val.toMillis();
     if (typeof val.toDate === 'function')
@@ -19,12 +29,14 @@ function extractTimestamp(val) {
     if (typeof val.seconds === 'number') {
         return val.seconds * 1000 + Math.floor((val.nanoseconds || 0) / 1000000);
     }
-    if (typeof val.string === 'string') {
-        const parsed = Date.parse(val);
-        if (!isNaN(parsed))
-            return parsed;
+    throw new Error('Firestore change has an unsupported updatedAt timestamp.');
+}
+function getRowId(data, primaryKey, documentId) {
+    const id = data?.[primaryKey] ?? documentId ?? data?.id;
+    if (id === undefined || id === null || String(id).length === 0) {
+        throw new Error('Firestore change is missing its document ID.');
     }
-    return Date.now();
+    return String(id);
 }
 class FirestoreRemoteAdapter {
     db;
@@ -211,7 +223,7 @@ class FirestoreRemoteAdapter {
                         if (rowTime > maxServerTimestamp) {
                             maxServerTimestamp = rowTime;
                         }
-                        const rowId = String(data[this.primaryKey] || doc.id || data.id);
+                        const rowId = getRowId(data, this.primaryKey, doc.id);
                         const operation = isSoftDeleted ? 'DELETE' : 'UPDATE';
                         changes.push({
                             tableName: table,
@@ -230,7 +242,7 @@ class FirestoreRemoteAdapter {
         }
         catch (error) {
             this.logger.error((0, logger_js_1.formatFirestoreError)(error, { operation: 'fetchChanges' }));
-            return { timestamp: sinceTimestamp, changes: [] };
+            throw error;
         }
     }
     /**
@@ -273,7 +285,7 @@ class FirestoreRemoteAdapter {
                                 data[this.deletedColumn] === true ||
                                 data[this.deletedColumn] === 1);
                             const rowTime = extractTimestamp(data[this.updatedAtColumn]);
-                            const rowId = String(data[this.primaryKey] || doc.id || data.id);
+                            const rowId = getRowId(data, this.primaryKey, doc.id);
                             changes.push({
                                 tableName: table,
                                 operation: isSoftDeleted ? 'DELETE' : 'UPDATE',

package/dist/auth/session.d.ts

@@ -48,6 +48,9 @@ export declare class SessionManager {
     private db;
     private events?;
     private tableName;
+    private sqlTableName;
+    private sqlUserIndexName;
+    private sqlActiveIndexName;
     private defaultOfflineDurationMs;
     private network?;
     constructor(db: DBExecutable, events?: EventEmitter | undefined, options?: SessionManagerOptions);

package/dist/auth/session.js

@@ -5,6 +5,9 @@ exports.mapSessionRow = mapSessionRow;
 const uuid_js_1 = require("../utils/uuid.js");
 exports.DEFAULT_SESSIONS_TABLE = '_local_sessions';
 exports.DEFAULT_OFFLINE_DURATION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+function quoteIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
 function mapSessionRow(r) {
     let userData;
     try {
@@ -41,12 +44,18 @@ class SessionManager {
     db;
     events;
     tableName;
+    sqlTableName;
+    sqlUserIndexName;
+    sqlActiveIndexName;
     defaultOfflineDurationMs;
     network;
     constructor(db, events, options = {}) {
         this.db = db;
         this.events = events;
         this.tableName = options.tableName ?? exports.DEFAULT_SESSIONS_TABLE;
+        this.sqlTableName = quoteIdentifier(this.tableName);
+        this.sqlUserIndexName = quoteIdentifier(`idx_${this.tableName}_user`);
+        this.sqlActiveIndexName = quoteIdentifier(`idx_${this.tableName}_active`);
         this.defaultOfflineDurationMs = options.defaultOfflineDurationMs ?? exports.DEFAULT_OFFLINE_DURATION_MS;
         this.network = options.network;
     }
@@ -54,7 +63,7 @@ class SessionManager {
      * Ensures the _local_sessions schema exists.
      */
     async initialize() {
-        await this.db.execute(`CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        await this.db.execute(`CREATE TABLE IF NOT EXISTS ${this.sqlTableName} (
         id TEXT PRIMARY KEY,
         user_id TEXT NOT NULL,
         user_data TEXT NOT NULL,
@@ -68,8 +77,8 @@ class SessionManager {
         metadata TEXT,
         is_active INTEGER NOT NULL DEFAULT 1
       );`);
-        await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_user ON ${this.tableName} (user_id);`);
-        await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_active ON ${this.tableName} (is_active);`);
+        await this.db.execute(`CREATE INDEX IF NOT EXISTS ${this.sqlUserIndexName} ON ${this.sqlTableName} (user_id);`);
+        await this.db.execute(`CREATE INDEX IF NOT EXISTS ${this.sqlActiveIndexName} ON ${this.sqlTableName} (is_active);`);
     }
     /**
      * Creates or updates a user session, persisting it to local SQLite so it remains available offline.
@@ -88,10 +97,10 @@ class SessionManager {
         const metadataStr = options.metadata ? JSON.stringify(options.metadata) : null;
         if (setActive) {
             // Deactivate other sessions
-            await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?;`, [0]);
+            await this.db.execute(`UPDATE ${this.sqlTableName} SET is_active = ?;`, [0]);
         }
         const sql = `
-      INSERT INTO ${this.tableName} (id, user_id, user_data, token, refresh_token, provider, created_at, last_active_at, expires_at, offline_access_until, metadata, is_active)
+      INSERT INTO ${this.sqlTableName} (id, user_id, user_data, token, refresh_token, provider, created_at, last_active_at, expires_at, offline_access_until, metadata, is_active)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         user_id = excluded.user_id,
@@ -141,7 +150,7 @@ class SessionManager {
      * If offline, the session remains active even if server tokens expired, as long as offlineAccessUntil is valid.
      */
     async getActiveSession() {
-        const rows = await this.db.execute(`SELECT * FROM ${this.tableName} WHERE is_active = ? LIMIT 1;`, [1]);
+        const rows = await this.db.execute(`SELECT * FROM ${this.sqlTableName} WHERE is_active = ? LIMIT 1;`, [1]);
         if (!rows || rows.length === 0) {
             return null;
         }
@@ -176,10 +185,10 @@ class SessionManager {
     async touch(sessionId) {
         const now = Date.now();
         if (sessionId) {
-            await this.db.execute(`UPDATE ${this.tableName} SET last_active_at = ? WHERE id = ?;`, [now, sessionId]);
+            await this.db.execute(`UPDATE ${this.sqlTableName} SET last_active_at = ? WHERE id = ?;`, [now, sessionId]);
         }
         else {
-            await this.db.execute(`UPDATE ${this.tableName} SET last_active_at = ? WHERE is_active = ?;`, [now, 1]);
+            await this.db.execute(`UPDATE ${this.sqlTableName} SET last_active_at = ? WHERE is_active = ?;`, [now, 1]);
         }
     }
     /**
@@ -195,7 +204,7 @@ class SessionManager {
         };
         const userDataStr = JSON.stringify(updatedUser);
         const now = Date.now();
-        await this.db.execute(`UPDATE ${this.tableName} SET user_data = ?, last_active_at = ? WHERE id = ?;`, [userDataStr, now, session.id]);
+        await this.db.execute(`UPDATE ${this.sqlTableName} SET user_data = ?, last_active_at = ? WHERE id = ?;`, [userDataStr, now, session.id]);
         session.user = updatedUser;
         session.lastActiveAt = now;
         this.events?.emit(this.tableName, { operation: 'UPDATE_USER', session });
@@ -212,7 +221,7 @@ class SessionManager {
         const refreshToken = tokens.refreshToken !== undefined ? tokens.refreshToken : session.refreshToken;
         const expiresAt = tokens.expiresAt !== undefined ? tokens.expiresAt : session.expiresAt;
         const now = Date.now();
-        await this.db.execute(`UPDATE ${this.tableName} SET token = ?, refresh_token = ?, expires_at = ?, last_active_at = ? WHERE id = ?;`, [token, refreshToken, expiresAt, now, session.id]);
+        await this.db.execute(`UPDATE ${this.sqlTableName} SET token = ?, refresh_token = ?, expires_at = ?, last_active_at = ? WHERE id = ?;`, [token, refreshToken, expiresAt, now, session.id]);
         session.token = token;
         session.refreshToken = refreshToken;
         session.expiresAt = expiresAt;
@@ -222,34 +231,34 @@ class SessionManager {
      * Signs out the active user session.
      */
     async clearSession() {
-        await this.db.execute(`UPDATE ${this.tableName} SET is_active = ? WHERE is_active = ?;`, [0, 1]);
+        await this.db.execute(`UPDATE ${this.sqlTableName} SET is_active = ? WHERE is_active = ?;`, [0, 1]);
         this.events?.emit(this.tableName, { operation: 'CLEAR_SESSION' });
     }
     /**
      * Completely purges all stored sessions (e.g. factory reset or privacy wipe).
      */
     async purgeAllSessions() {
-        await this.db.execute(`DELETE FROM ${this.tableName};`);
+        await this.db.execute(`DELETE FROM ${this.sqlTableName};`);
         this.events?.emit(this.tableName, { operation: 'PURGE_SESSIONS' });
     }
     /**
      * Lists all sessions currently cached in SQLite.
      */
     async listSessions() {
-        const rows = await this.db.execute(`SELECT * FROM ${this.tableName} ORDER BY last_active_at DESC;`);
+        const rows = await this.db.execute(`SELECT * FROM ${this.sqlTableName} ORDER BY last_active_at DESC;`);
         return (rows || []).map((r) => mapSessionRow(r));
     }
     /**
      * Switches the active session to a different account (e.g., multi-account or organization switching offline).
      */
     async switchSession(sessionIdOrUserId) {
-        const rows = await this.db.execute(`SELECT * FROM ${this.tableName} WHERE id = ? OR user_id = ? LIMIT 1;`, [sessionIdOrUserId, sessionIdOrUserId]);
+        const rows = await this.db.execute(`SELECT * FROM ${this.sqlTableName} WHERE id = ? OR user_id = ? LIMIT 1;`, [sessionIdOrUserId, sessionIdOrUserId]);
         if (!rows || rows.length === 0) {
             return null;
         }
         const targetSession = mapSessionRow(rows[0]);
-        await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?;`, [0]);
-        await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?, last_active_at = ? WHERE id = ?;`, [1, Date.now(), targetSession.id]);
+        await this.db.execute(`UPDATE ${this.sqlTableName} SET is_active = ?;`, [0]);
+        await this.db.execute(`UPDATE ${this.sqlTableName} SET is_active = ?, last_active_at = ? WHERE id = ?;`, [1, Date.now(), targetSession.id]);
         targetSession.isActive = true;
         targetSession.lastActiveAt = Date.now();
         this.events?.emit(this.tableName, { operation: 'SWITCH_SESSION', session: targetSession });

package/dist/config/index.js

@@ -84,7 +84,9 @@ async function createSyncClient(config) {
         logLevel: config.logLevel,
         autoSchema,
         tables: config.tables ?? [],
+        relationships: config.relationships ?? [],
         migrations: config.migrations,
+        schemaMigrations: config.schemaMigrations,
         autoStart: config.autoStart,
         jsonColumns: config.jsonColumns,
         autoHydrateJSON: config.autoHydrateJSON,

package/dist/config/types.d.ts

@@ -1,7 +1,9 @@
 import { LocalDBAdapter } from '../adapters/local/index.js';
 import { RemoteDBAdapter } from '../adapters/remote/index.js';
-import { ConflictResolver, ConflictStrategy, NetworkStatusProvider, RetryConfig } from '../core/types.js';
+import { ConflictResolver, ConflictStrategy, NetworkStatusProvider, RetryConfig, SchemaMigration } from '../core/types.js';
+import type { RelationshipDefinition } from '../core/client.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
+export type { OnDeleteAction, RelationshipDefinition } from '../core/client.js';
 export interface SupabaseConfigOptions {
     url?: string;
     anonKey?: string;
@@ -84,10 +86,20 @@ export interface LocalLiteConfig {
      */
     tables?: string[];
     /**
-     * Initial SQL table schema migration queries to execute on startup.
+     * Parent-child relationships. `onDelete` defaults to `noAction`, which rejects deletion when children exist.
+     * Deletes through client.delete(), client.mutate(..., 'DELETE'), or batch are handled atomically.
+     */
+    relationships?: RelationshipDefinition[];
+    /**
+     * Legacy idempotent SQL statements executed transactionally on every initialization.
      * e.g. ["CREATE TABLE IF NOT EXISTS todos (id TEXT PRIMARY KEY, title TEXT);"]
      */
     migrations?: string[];
+    /**
+     * Versioned application schema migrations. Versions must be consecutive integers
+     * starting at 1; each migration is applied once and recorded in schema_migrations.
+     */
+    schemaMigrations?: SchemaMigration[];
     /**
      * Automatically create tables and columns dynamically on the fly without manual SQL migrations.
      * Opt-in (default: false). When true, tables in `tables` are created automatically,

package/dist/core/client.d.ts

@@ -4,7 +4,7 @@ import { EventEmitter } from '../reactive/event-emitter.js';
 import { SyncWorker } from './sync-worker.js';
 import { DatabaseMaintenance } from './maintenance.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 { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SchemaMigration, SyncMetrics, SyncOp, TableChangeEvent, WhereFilter } from './types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
 import { QueryBuilder, AggregateSpec, AggregateResult } from './query-builder.js';
 import { type ExportJsonOptions, type ImportJsonOptions, type ExportCsvOptions, type ImportCsvOptions, type ImportSummary } from '../utils/portability.js';
@@ -16,6 +16,17 @@ import { SearchManager } from '../search/index.js';
 import { BlobStorageManager, type BlobStorageManagerOptions } from '../storage/index.js';
 import { JobScheduler, type JobSchedulerOptions } from '../scheduler/index.js';
 import { SessionManager, type SessionManagerOptions } from '../auth/session.js';
+export type OnDeleteAction = 'cascade' | 'restrict' | 'setNull' | 'noAction';
+export interface RelationshipDefinition {
+    /** Table containing the referencing rows. */
+    table: string;
+    /** Foreign-key field in the referencing table. */
+    foreignKey: string;
+    /** Referenced parent table; its configured primary key is used. */
+    references: string;
+    /** Behavior when the referenced parent row is deleted. Defaults to `noAction` (rejects when children exist). */
+    onDelete?: OnDeleteAction;
+}
 export interface LocalFirstClientConfig {
     local: LocalDBAdapter;
     remote: RemoteDBAdapter;
@@ -30,7 +41,9 @@ export interface LocalFirstClientConfig {
     logLevel?: LogLevel;
     autoSchema?: boolean;
     tables?: string[];
+    relationships?: RelationshipDefinition[];
     migrations?: string[];
+    schemaMigrations?: SchemaMigration[];
     autoStart?: boolean;
     coalesceOutbox?: boolean;
     jsonColumns?: Record<string, string[]>;
@@ -63,6 +76,8 @@ export declare class TransactionalClient {
         event: TableChangeEvent;
     }>, queuedOutboxIds: string[]);
     mutate(tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, options?: MutateOptions): Promise<void>;
+    private deleteRelated;
+    private applyMutation;
     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<{
@@ -94,6 +109,7 @@ export declare class LocalFirstClient {
     autoSchema: boolean;
     coalesceOutbox: boolean;
     tables: string[];
+    relationships: RelationshipDefinition[];
     jsonColumns: Record<string, string[]>;
     autoHydrateJSON: boolean;
     /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
@@ -108,6 +124,7 @@ export declare class LocalFirstClient {
     readonly session: SessionManager;
     private primaryKey;
     private migrations;
+    private schemaMigrations;
     private autoStart;
     private initialization?;
     constructor(config: LocalFirstClientConfig);
@@ -139,6 +156,7 @@ export declare class LocalFirstClient {
      */
     initialize(): Promise<void>;
     private initializeStorage;
+    private applySchemaMigrations;
     /**
      * Performs an atomic dual-write: mutates the local data table AND writes
      * to sync_outbox within the same database transaction.

package/dist/core/client.js

@@ -21,6 +21,30 @@ const index_js_5 = require("../search/index.js");
 const index_js_6 = require("../storage/index.js");
 const index_js_7 = require("../scheduler/index.js");
 const session_js_1 = require("../auth/session.js");
+function normalizeSchemaMigrations(migrations) {
+    if (!Array.isArray(migrations)) {
+        throw new TypeError('schemaMigrations must be an array.');
+    }
+    if (migrations.some((migration) => !migration ||
+        typeof migration !== 'object' ||
+        !Number.isSafeInteger(migration.version) ||
+        migration.version < 1)) {
+        throw new TypeError('Each schema migration must have a positive integer version.');
+    }
+    const ordered = [...migrations].sort((a, b) => a.version - b.version);
+    return ordered.map((migration, index) => {
+        const expectedVersion = index + 1;
+        if (!migration || !Number.isSafeInteger(migration.version) || migration.version !== expectedVersion) {
+            throw new TypeError(`schemaMigrations must use consecutive integer versions starting at 1; expected version ${expectedVersion}.`);
+        }
+        const statements = Array.isArray(migration.up) ? migration.up : [migration.up];
+        if (statements.length === 0 ||
+            statements.some((statement) => typeof statement !== 'string' || statement.trim().length === 0)) {
+            throw new TypeError(`schemaMigrations version ${migration.version} must contain non-empty SQL.`);
+        }
+        return { version: migration.version, up: statements.map((statement) => statement.trim()) };
+    });
+}
 function hasFunctionFilter(value) {
     if (typeof value === 'function')
         return true;
@@ -82,6 +106,47 @@ class TransactionalClient {
         this.queuedOutboxIds = queuedOutboxIds;
     }
     async mutate(tableName, rowId, operation, payload, options = {}) {
+        if (operation === 'DELETE') {
+            await this.deleteRelated(tableName, rowId, new Set(), options);
+            return;
+        }
+        await this.applyMutation(tableName, rowId, operation, payload, options);
+    }
+    async deleteRelated(tableName, rowId, visited, options = {}) {
+        const key = `${tableName}:${rowId}`;
+        if (visited.has(key))
+            return;
+        visited.add(key);
+        const relationships = this.parent.relationships.filter((relationship) => relationship.references === tableName);
+        for (const relationship of relationships) {
+            const relatedRows = await this.findMany(relationship.table, {
+                where: { [relationship.foreignKey]: rowId },
+            });
+            if (relatedRows.length === 0)
+                continue;
+            const action = relationship.onDelete ?? 'noAction';
+            if (action === 'restrict' || action === 'noAction') {
+                throw new Error(`Cannot delete ${tableName} record while ${relationship.table} records still reference it.`);
+            }
+            if (action === 'setNull') {
+                for (const row of relatedRows) {
+                    const childId = row[this.parent.getPrimaryKey()];
+                    if (childId !== undefined && childId !== null) {
+                        await this.update(relationship.table, String(childId), { [relationship.foreignKey]: null }, options);
+                    }
+                }
+                continue;
+            }
+            for (const row of relatedRows) {
+                const childId = row[this.parent.getPrimaryKey()];
+                if (childId !== undefined && childId !== null) {
+                    await this.deleteRelated(relationship.table, String(childId), visited, options);
+                }
+            }
+        }
+        await this.applyMutation(tableName, rowId, 'DELETE', null, options);
+    }
+    async applyMutation(tableName, rowId, operation, payload, options = {}) {
         const pk = options.primaryKey ?? this.parent.getPrimaryKey();
         const timestamp = options.customTimestamp ?? Date.now();
         await table_manager_js_1.TableManager.applyMutation(this.tx, tableName, rowId, operation, payload, pk, this.parent.localMutationOptions(timestamp));
@@ -168,6 +233,7 @@ class LocalFirstClient {
     autoSchema;
     coalesceOutbox;
     tables;
+    relationships;
     jsonColumns;
     autoHydrateJSON;
     /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
@@ -182,6 +248,7 @@ class LocalFirstClient {
     session;
     primaryKey;
     migrations;
+    schemaMigrations;
     autoStart;
     initialization;
     constructor(config) {
@@ -192,7 +259,33 @@ class LocalFirstClient {
         this.autoSchema = config.autoSchema ?? false;
         this.coalesceOutbox = config.coalesceOutbox ?? true;
         this.tables = config.tables ?? [];
+        this.relationships = config.relationships ?? [];
+        for (const relationship of this.relationships) {
+            if (!relationship.table || !relationship.foreignKey || !relationship.references) {
+                throw new TypeError('Each relationship requires table, foreignKey, and references.');
+            }
+            if (this.tables.length > 0) {
+                for (const tableName of [relationship.table, relationship.references]) {
+                    if (!this.tables.includes(tableName)) {
+                        throw new TypeError(`Relationship table "${tableName}" must be included in config.tables.`);
+                    }
+                }
+            }
+            if (relationship.onDelete !== undefined &&
+                !['cascade', 'restrict', 'setNull', 'noAction'].includes(relationship.onDelete)) {
+                throw new TypeError(`Unsupported onDelete action: ${relationship.onDelete}`);
+            }
+        }
+        const relationshipKeys = new Set();
+        for (const relationship of this.relationships) {
+            const key = `${relationship.references}\0${relationship.table}\0${relationship.foreignKey}`;
+            if (relationshipKeys.has(key)) {
+                throw new TypeError(`Duplicate relationship for ${relationship.table}.${relationship.foreignKey} referencing ${relationship.references}.`);
+            }
+            relationshipKeys.add(key);
+        }
         this.migrations = config.migrations ?? [];
+        this.schemaMigrations = normalizeSchemaMigrations(config.schemaMigrations ?? []);
         this.autoStart = config.autoStart ?? true;
         this.jsonColumns = config.jsonColumns ?? {};
         this.autoHydrateJSON = config.autoHydrateJSON ?? false;
@@ -416,6 +509,7 @@ class LocalFirstClient {
                 }
             });
         }
+        await this.applySchemaMigrations();
         if (this.autoSchema && this.tables.length > 0) {
             for (const table of this.tables) {
                 await this.schemaManager.ensureTable(this.db, table, this.primaryKey);
@@ -424,11 +518,60 @@ class LocalFirstClient {
         if (this.autoStart)
             this.syncWorker.start();
     }
+    async applySchemaMigrations() {
+        if (this.schemaMigrations.length === 0)
+            return;
+        await this.db.transaction(async (tx) => {
+            await tx.execute(`CREATE TABLE IF NOT EXISTS schema_migrations (
+          version INTEGER PRIMARY KEY,
+          applied_at INTEGER NOT NULL
+        );`);
+            const rows = await tx.execute('SELECT version FROM schema_migrations ORDER BY version ASC');
+            const appliedVersions = rows.map((row) => Number(row.version));
+            for (let index = 0; index < appliedVersions.length; index += 1) {
+                if (appliedVersions[index] !== index + 1) {
+                    throw new Error('The schema_migrations table contains a missing or invalid version.');
+                }
+            }
+            let currentVersion = appliedVersions.at(-1) ?? 0;
+            if (currentVersion > this.schemaMigrations.length) {
+                throw new Error(`Database schema version ${currentVersion} is newer than the latest available migration (${this.schemaMigrations.length}).`);
+            }
+            for (const migration of this.schemaMigrations) {
+                if (migration.version <= currentVersion)
+                    continue;
+                for (const statement of migration.up) {
+                    await tx.execute(statement);
+                }
+                await tx.execute('INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)', [migration.version, Date.now()]);
+                currentVersion = migration.version;
+            }
+        });
+    }
     /**
      * Performs an atomic dual-write: mutates the local data table AND writes
      * to sync_outbox within the same database transaction.
      */
     async mutate(tableName, rowId, operation, payload, options = {}) {
+        if (operation === 'DELETE') {
+            if (options.tx) {
+                const queuedEvents = [];
+                const queuedOutboxIds = [];
+                const txClient = new TransactionalClient(this, options.tx, queuedEvents, queuedOutboxIds);
+                await txClient.delete(tableName, rowId, options);
+                for (const item of queuedEvents) {
+                    this.events.emit(item.tableName, item.event);
+                }
+                if (queuedOutboxIds.length > 0) {
+                    this.events.emit('sync_outbox', { operation: 'INSERT', rowId: 'batch' });
+                    this.syncWorker.schedulePush(20);
+                }
+            }
+            else {
+                await this.transaction((tx) => tx.delete(tableName, rowId, options));
+            }
+            return;
+        }
         const pk = options.primaryKey ?? this.primaryKey;
         const timestamp = options.customTimestamp ?? Date.now();
         let affectedOutboxId;
@@ -475,6 +618,7 @@ class LocalFirstClient {
         const pendingOutboxOps = [];
         let pendingOutboxMap;
         const executeInTx = async (tx) => {
+            const txClient = new TransactionalClient(this, tx, queuedEvents, queuedOutboxIds);
             if (this.coalesceOutbox && mutations.length > 1) {
                 pendingOutboxMap = await outbox_store_js_1.OutboxStore.getActivePendingMap(tx);
             }
@@ -487,8 +631,16 @@ class LocalFirstClient {
                         : (0, uuid_js_1.generateUUID)());
                 generatedIds.push(rowId);
                 const timestamp = m.customTimestamp ?? options.customTimestamp ?? Date.now();
-                await table_manager_js_1.TableManager.applyMutation(tx, m.tableName, rowId, m.operation, payload, pk, this.localMutationOptions(timestamp));
                 const skipOutbox = m.skipOutbox ?? options.skipOutbox ?? false;
+                if (m.operation === 'DELETE') {
+                    await txClient.delete(m.tableName, rowId, {
+                        primaryKey: pk,
+                        customTimestamp: timestamp,
+                        skipOutbox,
+                    });
+                    continue;
+                }
+                await table_manager_js_1.TableManager.applyMutation(tx, m.tableName, rowId, m.operation, payload, pk, this.localMutationOptions(timestamp));
                 if (!skipOutbox) {
                     if (this.coalesceOutbox && m.operation !== 'INSERT') {
                         const outboxId = await this.recordOutboxMutation(tx, m.tableName, rowId, m.operation, payload, timestamp, pendingOutboxMap);

package/dist/core/query-builder.js

@@ -349,7 +349,7 @@ class QueryBuilder {
             sql += ` ORDER BY ${formatColumnIdentifier(this.orderColumn)} ${this.orderDirection}`;
         }
         // LIMIT & OFFSET
-        if (typeof this.limitCount === 'number' && this.limitCount > 0) {
+        if (typeof this.limitCount === 'number' && this.limitCount >= 0) {
             sql += ` LIMIT ?`;
             params.push(this.limitCount);
             if (typeof this.offsetCount === 'number' && this.offsetCount > 0) {
@@ -357,6 +357,10 @@ class QueryBuilder {
                 params.push(this.offsetCount);
             }
         }
+        else if (typeof this.offsetCount === 'number' && this.offsetCount > 0) {
+            sql += ` LIMIT -1 OFFSET ?`;
+            params.push(this.offsetCount);
+        }
         return { sql, params };
     }
     /**
@@ -398,9 +402,13 @@ class QueryBuilder {
     async first() {
         const originalLimit = this.limitCount;
         this.limitCount = 1;
-        const rows = await this.execute();
-        this.limitCount = originalLimit;
-        return rows.length > 0 ? rows[0] : null;
+        try {
+            const rows = await this.execute();
+            return rows.length > 0 ? rows[0] : null;
+        }
+        finally {
+            this.limitCount = originalLimit;
+        }
     }
     /**
      * Executes a COUNT(*) in SQLite and returns the numeric count directly.
@@ -408,10 +416,14 @@ class QueryBuilder {
     async count() {
         const originalSelect = this.selectCols;
         this.selectCols = ['COUNT(*) AS _count'];
-        const rows = await this.execute();
-        this.selectCols = originalSelect;
-        const countVal = rows[0]?._count;
-        return typeof countVal === 'number' ? countVal : Number(countVal) || 0;
+        try {
+            const rows = await this.execute();
+            const countVal = rows[0]?._count;
+            return typeof countVal === 'number' ? countVal : Number(countVal) || 0;
+        }
+        finally {
+            this.selectCols = originalSelect;
+        }
     }
     /**
      * Executes a SUM(column) in SQLite and returns the numeric total directly.
@@ -420,10 +432,14 @@ class QueryBuilder {
         const originalSelect = this.selectCols;
         const safeCol = formatColumnIdentifier(column);
         this.selectCols = [`COALESCE(SUM(${safeCol}), 0) AS _sum`];
-        const rows = await this.execute();
-        this.selectCols = originalSelect;
-        const sumVal = rows[0]?._sum;
-        return typeof sumVal === 'number' ? sumVal : Number(sumVal) || 0;
+        try {
+            const rows = await this.execute();
+            const sumVal = rows[0]?._sum;
+            return typeof sumVal === 'number' ? sumVal : Number(sumVal) || 0;
+        }
+        finally {
+            this.selectCols = originalSelect;
+        }
     }
     /**
      * Executes an AVG(column) in SQLite and returns the average directly.
@@ -432,10 +448,14 @@ class QueryBuilder {
         const originalSelect = this.selectCols;
         const safeCol = formatColumnIdentifier(column);
         this.selectCols = [`AVG(${safeCol}) AS _avg`];
-        const rows = await this.execute();
-        this.selectCols = originalSelect;
-        const avgVal = rows[0]?._avg;
-        return avgVal === null || avgVal === undefined ? null : Number(avgVal) || 0;
+        try {
+            const rows = await this.execute();
+            const avgVal = rows[0]?._avg;
+            return avgVal === null || avgVal === undefined ? null : Number(avgVal) || 0;
+        }
+        finally {
+            this.selectCols = originalSelect;
+        }
     }
 }
 exports.QueryBuilder = QueryBuilder;

package/dist/core/types.d.ts

@@ -1,5 +1,9 @@
 export type SyncOp = 'INSERT' | 'UPDATE' | 'DELETE';
 export type OutboxStatus = 'PENDING' | 'PROCESSING' | 'FAILED';
+export interface SchemaMigration {
+    version: number;
+    up: string | string[];
+}
 export interface SyncOperation {
     id: string;
     tableName: string;

package/dist/devtools/BenchmarkModal.d.ts

@@ -3,7 +3,7 @@ import { LocalFirstClient } from '../core/client.js';
 import { type SyncThemeColors } from '../react/theme.js';
 export interface BuiltinBenchmarkResult {
     name: string;
-    category: 'Local-Lite Client' | 'ACID / Transactions' | 'Outbox / Sync' | 'Memory / JSON';
+    category: 'Local-Lite Client' | 'ACID / Transactions' | 'Outbox / Sync' | 'Memory / JSON' | 'App Data';
     description: string;
     operations: number;
     durationMs: number;

package/dist/devtools/BenchmarkModal.js

@@ -38,6 +38,7 @@ exports.BenchmarkModal = BenchmarkModal;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = __importStar(require("react"));
 const theme_js_1 = require("../react/theme.js");
+const sql_js_1 = require("../utils/sql.js");
 let RN;
 try {
     RN = require('react-native');
@@ -52,6 +53,26 @@ try {
 catch {
     // Web / DOM environment or not installed
 }
+const now = () => typeof performance !== 'undefined' && typeof performance.now === 'function'
+    ? performance.now()
+    : Date.now();
+const elapsed = (start) => Math.max(0.01, Math.round((now() - start) * 100) / 100);
+const median = (values) => {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+};
+/** Runs one untimed warm-up pass, then returns the median duration (ms) of `runs` timed passes. */
+async function timeMedian(action, runs = 5) {
+    await action();
+    const samples = [];
+    for (let i = 0; i < runs; i++) {
+        const start = now();
+        await action();
+        samples.push(elapsed(start));
+    }
+    return median(samples);
+}
 /**
  * Executes a comprehensive performance & ACID test suite
  * directly testing local-lite client APIs:
@@ -65,6 +86,34 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
     const db = client?.db || clientOrDb;
     try {
         onProgress?.('Preparing benchmark environment...', 0.05);
+        let appRowCount = 0;
+        let appTableCount = 0;
+        let appTables = [];
+        const appDataSamples = [];
+        if (client?.maintenance) {
+            const stats = await client.maintenance.getStorageStats();
+            appTables = Object.entries(stats.tables).filter(([, count]) => count > 0);
+            appRowCount = appTables.reduce((total, [, count]) => total + count, 0);
+            appTableCount = appTables.length;
+            for (const [tableName] of appTables) {
+                const rows = await db.execute(`SELECT * FROM ${(0, sql_js_1.escapeIdentifier)(tableName)} LIMIT 1`);
+                if (rows[0]) {
+                    const sample = JSON.stringify(rows[0], (_key, value) => typeof value === 'bigint' ? value.toString() : value);
+                    if (sample)
+                        appDataSamples.push(sample.slice(0, 4096));
+                }
+            }
+        }
+        const workloadScale = Math.min(10, Math.max(1, Math.ceil(appRowCount / 1000)));
+        const scaleWorkload = (count) => count * workloadScale;
+        const makeMetadata = (index, tag) => JSON.stringify({
+            index,
+            tag,
+            timestamp: Date.now(),
+            ...(appDataSamples.length > 0
+                ? { appRecord: appDataSamples[index % appDataSamples.length] }
+                : {}),
+        });
         await db.execute('DROP TABLE IF EXISTS "_sync_bench_tags"').catch(() => { });
         await db.execute('DROP TABLE IF EXISTS "_sync_bench_temp"').catch(() => { });
         await db.execute('DROP TABLE IF EXISTS "_sync_bench_outbox"').catch(() => { });
@@ -91,9 +140,9 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
       )
     `);
         await db.execute('CREATE INDEX IF NOT EXISTS "idx_sync_bench_outbox" ON "_sync_bench_outbox" (status, timestamp)');
-        // 1. client.batch() Ingestion (500 rows in single atomic transaction)
-        onProgress?.('Testing client.batch() atomic multi-mutation (500 rows)...', 0.12);
-        const batchCount = 500;
+        // 1. client.batch() Ingestion
+        const batchCount = scaleWorkload(500);
+        onProgress?.(`Testing client.batch() atomic multi-mutation (${batchCount} rows)...`, 0.12);
         const batchMutations = Array.from({ length: batchCount }, (_, i) => ({
             tableName: '_sync_bench_temp',
             operation: 'INSERT',
@@ -102,11 +151,11 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 id: `b-batch-${i}`,
                 title: `Item ${i}`,
                 score: Math.floor(Math.random() * 100),
-                metadata: JSON.stringify({ index: i, tag: 'batch', timestamp: Date.now() }),
+                metadata: makeMetadata(i, 'batch'),
                 created_at: new Date().toISOString(),
             },
         }));
-        const t1Start = Date.now();
+        const t1Start = now();
         if (client?.batch) {
             await client.batch(batchMutations, { skipOutbox: true });
         }
@@ -117,25 +166,26 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 }
             });
         }
-        const t1Duration = Math.max(1, Date.now() - t1Start);
+        const t1Duration = elapsed(t1Start);
         list.push({
             name: 'client.batch() Ingestion',
             category: 'Local-Lite Client',
-            description: '500 rows inserted via local-lite atomic batch() mutation pipeline',
+            description: `${batchCount.toLocaleString()} rows inserted via local-lite atomic batch() mutation pipeline`,
             operations: batchCount,
             durationMs: t1Duration,
             opsPerSec: Math.round((batchCount / t1Duration) * 1000),
             status: 'success',
+            note: `Calibrated to ${appRowCount.toLocaleString()} app rows across ${appTableCount} tables (${workloadScale}x workload).`,
         });
-        // 2. client.insert() Individual Mutations (40 rows)
-        onProgress?.('Testing client.insert() individual mutations (40 rows)...', 0.24);
-        const indivCount = 40;
-        const t2Start = Date.now();
+        // 2. client.insert() Individual Mutations
+        const indivCount = scaleWorkload(40);
+        onProgress?.(`Testing client.insert() individual mutations (${indivCount} rows)...`, 0.24);
+        const t2Start = now();
         for (let i = 0; i < indivCount; i++) {
             const payload = {
                 title: `Individual Item ${i}`,
                 score: Math.floor(Math.random() * 100),
-                metadata: JSON.stringify({ index: i, tag: 'indiv' }),
+                metadata: makeMetadata(i, 'indiv'),
                 created_at: new Date().toISOString(),
             };
             if (client?.insert) {
@@ -145,25 +195,25 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 await db.execute('INSERT INTO "_sync_bench_temp" (id, title, score, metadata, created_at) VALUES (?, ?, ?, ?, ?)', [`b-indiv-${i}`, payload.title, payload.score, payload.metadata, payload.created_at]);
             }
         }
-        const t2Duration = Math.max(1, Date.now() - t2Start);
+        const t2Duration = elapsed(t2Start);
         list.push({
             name: 'client.insert() Mutation',
             category: 'Local-Lite Client',
-            description: '40 standalone client.insert() calls testing dual-write mutation pipeline',
+            description: `${indivCount.toLocaleString()} standalone client.insert() calls testing the dual-write mutation pipeline`,
             operations: indivCount,
             durationMs: t2Duration,
             opsPerSec: Math.round((indivCount / t2Duration) * 1000),
             status: 'success',
         });
-        // 3. client.update() Reactive Updates (150 rows)
-        onProgress?.('Testing client.update() reactive updates (150 rows)...', 0.36);
-        const updateCount = 150;
-        const t3Start = Date.now();
+        // 3. client.update() Reactive Updates
+        const updateCount = scaleWorkload(150);
+        onProgress?.(`Testing client.update() reactive updates (${updateCount} rows)...`, 0.36);
+        const t3Start = now();
         for (let i = 0; i < updateCount; i++) {
             const patch = {
                 title: `Updated Item ${i}`,
                 score: 999 + i,
-                metadata: JSON.stringify({ updated: true, rev: i + 1 }),
+                metadata: makeMetadata(i, 'update'),
             };
             if (client?.update) {
                 await client.update('_sync_bench_temp', `b-batch-${i}`, patch, { skipOutbox: true });
@@ -172,20 +222,20 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 await db.execute('UPDATE "_sync_bench_temp" SET title = ?, score = ?, metadata = ? WHERE id = ?', [patch.title, patch.score, patch.metadata, `b-batch-${i}`]);
             }
         }
-        const t3Duration = Math.max(1, Date.now() - t3Start);
+        const t3Duration = elapsed(t3Start);
         list.push({
             name: 'client.update() Pipeline',
             category: 'Local-Lite Client',
-            description: '150 client.update() calls testing schema verification & event emission',
+            description: `${updateCount.toLocaleString()} client.update() calls testing schema verification & event emission`,
             operations: updateCount,
             durationMs: t3Duration,
             opsPerSec: Math.round((updateCount / t3Duration) * 1000),
             status: 'success',
         });
-        // 4. client.findById() Indexed Lookups (400 queries)
-        onProgress?.('Testing client.findById() indexed point lookups (400 queries)...', 0.48);
-        const findCount = 400;
-        const t4Start = Date.now();
+        // 4. client.findById() Indexed Lookups
+        const findCount = scaleWorkload(400);
+        onProgress?.(`Testing client.findById() indexed point lookups (${findCount} queries)...`, 0.48);
+        const t4Start = now();
         for (let i = 0; i < findCount; i++) {
             const id = `b-batch-${i % batchCount}`;
             if (client?.findById) {
@@ -195,21 +245,21 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 await db.execute('SELECT * FROM "_sync_bench_temp" WHERE id = ?', [id]);
             }
         }
-        const t4Duration = Math.max(1, Date.now() - t4Start);
+        const t4Duration = elapsed(t4Start);
         list.push({
             name: 'client.findById() Lookups',
             category: 'Local-Lite Client',
-            description: '400 point lookups testing PK index resolution & auto JSON hydration',
+            description: `${findCount.toLocaleString()} point lookups testing PK index resolution & auto JSON hydration`,
             operations: findCount,
             durationMs: t4Duration,
             opsPerSec: Math.round((findCount / t4Duration) * 1000),
             status: 'success',
         });
-        // 5. client.findByIds() Batched PK Lookups (400 entities loaded in 20 queries)
-        onProgress?.('Testing client.findByIds() batched lookups (400 entities)...', 0.55);
-        const batchedQueryCount = 20;
+        // 5. client.findByIds() Batched PK Lookups
+        const batchedQueryCount = scaleWorkload(20);
         const batchLookupSize = 20;
-        const tBatchFindStart = Date.now();
+        onProgress?.(`Testing client.findByIds() batched lookups (${batchedQueryCount * batchLookupSize} entities)...`, 0.55);
+        const tBatchFindStart = now();
         for (let i = 0; i < batchedQueryCount; i++) {
             const ids = Array.from({ length: batchLookupSize }, (_, idx) => `b-batch-${(i * batchLookupSize + idx) % batchCount}`);
             if (client?.findByIds) {
@@ -220,7 +270,7 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 await db.execute(`SELECT * FROM "_sync_bench_temp" WHERE id IN (${placeholders})`, ids);
             }
         }
-        const tBatchFindDuration = Math.max(1, Date.now() - tBatchFindStart);
+        const tBatchFindDuration = elapsed(tBatchFindStart);
         const totalBatchedFinds = batchedQueryCount * batchLookupSize;
         list.push({
             name: 'client.findByIds() Batched',
@@ -231,10 +281,10 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
             opsPerSec: Math.round((totalBatchedFinds / tBatchFindDuration) * 1000),
             status: 'success',
         });
-        // 6. client.findMany() with SQL Pushdown Filters (40 queries)
-        onProgress?.('Testing client.findMany() query filter compilation (40 queries)...', 0.6);
-        const findManyCount = 40;
-        const t5Start = Date.now();
+        // 6. client.findMany() with SQL Pushdown Filters
+        const findManyCount = scaleWorkload(40);
+        onProgress?.(`Testing client.findMany() query filter compilation (${findManyCount} queries)...`, 0.6);
+        const t5Start = now();
         for (let i = 0; i < findManyCount; i++) {
             if (client?.findMany) {
                 await client.findMany('_sync_bench_temp', {
@@ -248,21 +298,21 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 await db.execute('SELECT * FROM "_sync_bench_temp" WHERE score > 50 ORDER BY created_at DESC LIMIT 20');
             }
         }
-        const t5Duration = Math.max(1, Date.now() - t5Start);
+        const t5Duration = elapsed(t5Start);
         list.push({
             name: 'client.findMany() Filters',
             category: 'Local-Lite Client',
-            description: '40 queries through local-lite SQL pushdown ($gt, ORDER BY, LIMIT)',
+            description: `${findManyCount.toLocaleString()} queries through local-lite SQL pushdown ($gt, ORDER BY, LIMIT)`,
             operations: findManyCount,
             durationMs: t5Duration,
             opsPerSec: Math.round((findManyCount / t5Duration) * 1000),
             status: 'success',
         });
         // 6. client.findMany() with $contains (Fuzzy Substring Search)
-        onProgress?.('Testing client.findMany() $contains fuzzy search (50 queries)...', 0.7);
-        const searchCount = 50;
+        const searchCount = scaleWorkload(50);
+        onProgress?.(`Testing client.findMany() $contains fuzzy search (${searchCount} queries)...`, 0.7);
         const searchTokens = ['Item 1', 'Updated', 'rev', 'Large', 'nonexistent'];
-        const t6Start = Date.now();
+        const t6Start = now();
         for (let i = 0; i < searchCount; i++) {
             const token = searchTokens[i % searchTokens.length];
             if (client?.findMany) {
@@ -275,11 +325,11 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 await db.execute('SELECT * FROM "_sync_bench_temp" WHERE title LIKE ? LIMIT 25', [`%${token}%`]);
             }
         }
-        const t6Duration = Math.max(1, Date.now() - t6Start);
+        const t6Duration = elapsed(t6Start);
         list.push({
             name: 'client.findMany() $contains Search',
             category: 'Local-Lite Client',
-            description: '50 fuzzy text queries compiling $contains into SQL LIKE pushdown',
+            description: `${searchCount.toLocaleString()} fuzzy text queries compiling $contains into SQL LIKE pushdown`,
             operations: searchCount,
             durationMs: t6Duration,
             opsPerSec: Math.round((searchCount / t6Duration) * 1000),
@@ -287,8 +337,9 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
         });
         // 7. client.transaction() ACID Rollback Verification
         onProgress?.('Testing client.transaction() ACID rollback isolation...', 0.78);
-        const rollbackStart = Date.now();
-        for (let c = 0; c < 10; c++) {
+        const rollbackStart = now();
+        const rollbackCount = scaleWorkload(10);
+        for (let c = 0; c < rollbackCount; c++) {
             try {
                 if (client?.transaction) {
                     await client.transaction(async (txClient) => {
@@ -315,21 +366,21 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
             })
             : [];
         const leaked = Array.isArray(leakedCheck) ? leakedCheck.length : 0;
-        const rbDuration = Math.max(1, Date.now() - rollbackStart);
+        const rbDuration = elapsed(rollbackStart);
         list.push({
             name: 'client.transaction() Rollback',
             category: 'ACID / Transactions',
-            description: `10 aborted transactions via client.transaction() (${leaked} leaked rows, zero pollution)`,
-            operations: 10,
+            description: `${rollbackCount} aborted transactions via client.transaction() (${leaked} leaked rows, zero pollution)`,
+            operations: rollbackCount,
             durationMs: rbDuration,
-            opsPerSec: Math.round((10 / rbDuration) * 1000),
+            opsPerSec: Math.round((rollbackCount / rbDuration) * 1000),
             status: 'success',
             note: `${leaked} leaked rows`,
         });
-        // 8. Outbox Pipeline Ingestion (200 mutations)
-        onProgress?.('Testing outbox mutation pipeline (200 mutations)...', 0.85);
-        const outboxCount = 200;
-        const tOutboxStart = Date.now();
+        // 8. Outbox Pipeline Ingestion
+        const outboxCount = scaleWorkload(200);
+        onProgress?.(`Testing outbox mutation pipeline (${outboxCount} mutations)...`, 0.85);
+        const tOutboxStart = now();
         await db.transaction(async (tx) => {
             for (let i = 0; i < outboxCount; i++) {
                 await tx.execute('INSERT INTO "_sync_bench_outbox" (id, tableName, rowId, operation, payload, timestamp, status, retryCount) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', [
@@ -344,20 +395,20 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 ]);
             }
         });
-        const tOutboxDuration = Math.max(1, Date.now() - tOutboxStart);
+        const tOutboxDuration = elapsed(tOutboxStart);
         list.push({
             name: 'Outbox Pipeline Ingestion',
             category: 'Outbox / Sync',
-            description: '200 mutations staged through outbox queue with compound index',
+            description: `${outboxCount.toLocaleString()} mutations staged through outbox queue with compound index`,
             operations: outboxCount,
             durationMs: tOutboxDuration,
             opsPerSec: Math.round((outboxCount / tOutboxDuration) * 1000),
             status: 'success',
         });
         // 9. client.delete() Pipeline
-        onProgress?.('Testing client.delete() removal (50 rows)...', 0.9);
-        const deleteCount = 50;
-        const tDelStart = Date.now();
+        const deleteCount = scaleWorkload(50);
+        onProgress?.(`Testing client.delete() removal (${deleteCount} rows)...`, 0.9);
+        const tDelStart = now();
         for (let i = 0; i < deleteCount; i++) {
             if (client?.delete) {
                 await client.delete('_sync_bench_temp', `b-batch-${i}`, { skipOutbox: true });
@@ -366,11 +417,11 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
                 await db.execute('DELETE FROM "_sync_bench_temp" WHERE id = ?', [`b-batch-${i}`]);
             }
         }
-        const tDelDuration = Math.max(1, Date.now() - tDelStart);
+        const tDelDuration = elapsed(tDelStart);
         list.push({
             name: 'client.delete() Pipeline',
             category: 'Local-Lite Client',
-            description: '50 deletions through local-lite mutate() deletion pipeline',
+            description: `${deleteCount.toLocaleString()} deletions through local-lite mutate() deletion pipeline`,
             operations: deleteCount,
             durationMs: tDelDuration,
             opsPerSec: Math.round((deleteCount / tDelDuration) * 1000),
@@ -378,9 +429,9 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
         });
         // 10. WAL Read/Write Concurrency Under Contention
         onProgress?.('Testing WAL non-blocking concurrent reads & writes...', 0.95);
-        const concReadCount = 100;
-        const concWriteCount = 60;
-        const tConcStart = Date.now();
+        const concReadCount = scaleWorkload(100);
+        const concWriteCount = scaleWorkload(60);
+        const tConcStart = now();
         const writePromise = db.transaction(async (tx) => {
             for (let i = 0; i < concWriteCount; i++) {
                 await tx.execute('INSERT INTO "_sync_bench_temp" (id, title, score, metadata, created_at) VALUES (?, ?, ?, ?, ?)', [`wal-w-${i}`, `WAL Item ${i}`, i, '{"wal":true}', new Date().toISOString()]);
@@ -388,20 +439,20 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
         });
         const readPromises = Array.from({ length: concReadCount }, (_, idx) => db.execute('SELECT COUNT(*) as c FROM "_sync_bench_temp" WHERE score >= ?', [idx % 50]));
         await Promise.all([writePromise, ...readPromises]);
-        const tConcDuration = Math.max(1, Date.now() - tConcStart);
+        const tConcDuration = elapsed(tConcStart);
         const totalConcOps = concWriteCount + concReadCount;
         list.push({
             name: 'WAL Concurrency Under Contention',
             category: 'ACID / Transactions',
-            description: '60 atomic writes executed simultaneously with 100 concurrent reads in non-blocking WAL mode',
+            description: `${concWriteCount.toLocaleString()} atomic writes executed simultaneously with ${concReadCount.toLocaleString()} concurrent reads in non-blocking WAL mode`,
             operations: totalConcOps,
             durationMs: tConcDuration,
             opsPerSec: Math.round((totalConcOps / tConcDuration) * 1000),
             status: 'success',
         });
         // 11. Resilient JSON Fuzz Parsing
-        onProgress?.('Testing resilient JSON fuzz hydration (1,000 cycles)...', 0.99);
-        const fuzzCount = 1000;
+        const fuzzCount = scaleWorkload(1000);
+        onProgress?.(`Testing resilient JSON fuzz hydration (${fuzzCount.toLocaleString()} cycles)...`, 0.99);
         const fuzzPayloads = [
             JSON.stringify({ nested: { title: 'Document 🏢', val: 42, tags: ['sync', 'offline'] } }),
             '{"corrupted": [1, 2, 3, {"unclosed": true',
@@ -410,7 +461,7 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
             '',
             'null',
         ];
-        const t8Start = Date.now();
+        const t8Start = now();
         for (let i = 0; i < fuzzCount; i++) {
             const raw = fuzzPayloads[i % fuzzPayloads.length];
             try {
@@ -419,16 +470,58 @@ async function runSQLiteBenchmark(clientOrDb, onProgress) {
             }
             catch { }
         }
-        const t8Duration = Math.max(1, Date.now() - t8Start);
+        const t8Duration = elapsed(t8Start);
         list.push({
             name: 'Resilient JSON Fuzz Parsing',
             category: 'Memory / JSON',
-            description: '1,000 cycles parsing deep unicode trees, corrupted shapes & fallback structures',
+            description: `${fuzzCount.toLocaleString()} cycles parsing deep unicode trees, corrupted shapes & fallback structures`,
             operations: fuzzCount,
             durationMs: t8Duration,
             opsPerSec: Math.round((fuzzCount / t8Duration) * 1000),
             status: 'success',
         });
+        // 12. Read-only benchmarks against the app's real tables (never writes app data)
+        const realTables = [...appTables].sort((a, b) => b[1] - a[1]).slice(0, 3);
+        for (const [tableName, rowCount] of realTables) {
+            onProgress?.(`Reading real app table "${tableName}"...`, 0.995);
+            try {
+                const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+                const pk = client?.getPrimaryKey?.() ?? 'id';
+                const safePk = (0, sql_js_1.escapeIdentifier)(pk);
+                const pkRows = await db.execute(`SELECT ${safePk} AS pk FROM ${safeTable} LIMIT 200`);
+                const ids = pkRows.map((r) => String(r.pk));
+                const scanMs = await timeMedian(async () => {
+                    await db.execute(`SELECT * FROM ${safeTable} LIMIT 500`);
+                });
+                list.push({
+                    name: `Real table scan: ${tableName}`,
+                    category: 'App Data',
+                    description: `Median of 5 runs reading up to 500 of ${rowCount.toLocaleString()} real rows (SELECT *)`,
+                    operations: Math.min(500, rowCount),
+                    durationMs: scanMs,
+                    opsPerSec: Math.round((Math.min(500, rowCount) / scanMs) * 1000),
+                    status: 'success',
+                });
+                if (ids.length > 0 && client?.findById) {
+                    const lookupMs = await timeMedian(async () => {
+                        for (const id of ids)
+                            await client.findById(tableName, id);
+                    });
+                    list.push({
+                        name: `Real point lookups: ${tableName}`,
+                        category: 'App Data',
+                        description: `Median of 5 runs of ${ids.length} client.findById() calls on real rows`,
+                        operations: ids.length,
+                        durationMs: lookupMs,
+                        opsPerSec: Math.round((ids.length / lookupMs) * 1000),
+                        status: 'success',
+                    });
+                }
+            }
+            catch {
+                // Table without the expected primary key column; skip it
+            }
+        }
         onProgress?.('Benchmark complete!', 1);
     }
     finally {
@@ -478,6 +571,7 @@ function BenchmarkModal({ client, visible, onDismiss, theme = 'auto' }) {
             '# ⚡ local-lite SQLite Benchmark Report',
             `- Platform: ${RN && RN.Platform ? RN.Platform.OS : 'web'}`,
             `- Date: ${new Date().toLocaleString()}`,
+            ...(results[0]?.note ? [`- App dataset: ${results[0].note}`] : []),
             '',
             '| Benchmark | Category | Operations | Duration | Throughput |',
             '| :--- | :--- | :--- | :--- | :--- |',
@@ -522,7 +616,7 @@ function BenchmarkModal({ client, visible, onDismiss, theme = 'auto' }) {
                                     : r.opsPerSec > 500
                                         ? { label: 'Fast ⚡', color: '#8B5CF6', bg: currentTheme.isDark ? '#4C1D95' : '#EDE9FE' }
                                         : { label: 'Normal 👍', color: currentTheme.textMuted, bg: currentTheme.border };
-                                return ((0, jsx_runtime_1.jsxs)(View, { style: [styles.card, { backgroundColor: currentTheme.card, borderColor: currentTheme.border }], children: [(0, jsx_runtime_1.jsxs)(View, { style: styles.cardHeader, children: [(0, jsx_runtime_1.jsx)(Text, { style: [styles.cardTitle, { color: currentTheme.text }], children: r.name }), (0, jsx_runtime_1.jsx)(View, { style: [styles.badge, { backgroundColor: rating.bg }], children: (0, jsx_runtime_1.jsx)(Text, { style: [styles.badgeText, { color: rating.color }], children: rating.label }) })] }), (0, jsx_runtime_1.jsx)(Text, { style: [styles.cardDesc, { color: currentTheme.textMuted }], children: r.description }), (0, jsx_runtime_1.jsxs)(View, { style: [styles.cardMetrics, { borderTopColor: currentTheme.border }], children: [(0, jsx_runtime_1.jsxs)(View, { children: [(0, jsx_runtime_1.jsx)(Text, { style: [styles.metricLabel, { color: currentTheme.textMuted }], children: "Duration" }), (0, jsx_runtime_1.jsxs)(Text, { style: [styles.metricVal, { color: currentTheme.text }], children: [r.durationMs, " ms"] })] }), (0, jsx_runtime_1.jsxs)(View, { style: { alignItems: 'flex-end' }, children: [(0, jsx_runtime_1.jsx)(Text, { style: [styles.metricLabel, { color: currentTheme.textMuted }], children: "Throughput" }), (0, jsx_runtime_1.jsxs)(Text, { style: [styles.metricVal, { color: '#8B5CF6' }], children: [r.opsPerSec.toLocaleString(), " ops/s"] })] })] })] }, idx));
+                                return ((0, jsx_runtime_1.jsxs)(View, { style: [styles.card, { backgroundColor: currentTheme.card, borderColor: currentTheme.border }], children: [(0, jsx_runtime_1.jsxs)(View, { style: styles.cardHeader, children: [(0, jsx_runtime_1.jsx)(Text, { style: [styles.cardTitle, { color: currentTheme.text }], children: r.name }), (0, jsx_runtime_1.jsx)(View, { style: [styles.badge, { backgroundColor: rating.bg }], children: (0, jsx_runtime_1.jsx)(Text, { style: [styles.badgeText, { color: rating.color }], children: rating.label }) })] }), (0, jsx_runtime_1.jsx)(Text, { style: [styles.cardDesc, { color: currentTheme.textMuted }], children: r.description }), r.note && ((0, jsx_runtime_1.jsx)(Text, { style: [styles.cardDesc, { color: currentTheme.textMuted }], children: r.note })), (0, jsx_runtime_1.jsxs)(View, { style: [styles.cardMetrics, { borderTopColor: currentTheme.border }], children: [(0, jsx_runtime_1.jsxs)(View, { children: [(0, jsx_runtime_1.jsx)(Text, { style: [styles.metricLabel, { color: currentTheme.textMuted }], children: "Duration" }), (0, jsx_runtime_1.jsxs)(Text, { style: [styles.metricVal, { color: currentTheme.text }], children: [r.durationMs, " ms"] })] }), (0, jsx_runtime_1.jsxs)(View, { style: { alignItems: 'flex-end' }, children: [(0, jsx_runtime_1.jsx)(Text, { style: [styles.metricLabel, { color: currentTheme.textMuted }], children: "Throughput" }), (0, jsx_runtime_1.jsxs)(Text, { style: [styles.metricVal, { color: '#8B5CF6' }], children: [r.opsPerSec.toLocaleString(), " ops/s"] })] })] })] }, idx));
                             })] }), (0, jsx_runtime_1.jsxs)(View, { style: [
                             styles.bottomBar,
                             { backgroundColor: currentTheme.surface, borderTopColor: currentTheme.border },
@@ -576,7 +670,7 @@ function BenchmarkModal({ client, visible, onDismiss, theme = 'auto' }) {
                             border: `1px solid ${currentTheme.border}`,
                             borderRadius: 12,
                             padding: 16,
-                        }, children: [(0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 6 }, children: [(0, jsx_runtime_1.jsx)("span", { style: { fontWeight: 700, fontSize: 14, color: currentTheme.text }, children: r.name }), (0, jsx_runtime_1.jsxs)("span", { style: { fontSize: 11, fontWeight: 700, color: '#8B5CF6', backgroundColor: currentTheme.isDark ? '#8B5CF625' : '#EDE9FE', padding: '2px 8px', borderRadius: 10 }, children: [r.opsPerSec.toLocaleString(), " ops/s"] })] }), (0, jsx_runtime_1.jsx)("div", { style: { fontSize: 12, color: currentTheme.textMuted, marginBottom: 10 }, children: r.description }), (0, jsx_runtime_1.jsxs)("div", { style: { fontSize: 11, color: currentTheme.textMuted }, children: [r.operations.toLocaleString(), " ops in ", r.durationMs, "ms"] })] }, idx)))] }), (0, jsx_runtime_1.jsxs)("div", { style: { padding: '16px 24px', borderTop: `1px solid ${currentTheme.border}`, backgroundColor: currentTheme.surface, display: 'flex', gap: 12 }, children: [(0, jsx_runtime_1.jsx)("button", { onClick: startBenchmark, disabled: isRunning, style: {
+                        }, children: [(0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 6 }, children: [(0, jsx_runtime_1.jsx)("span", { style: { fontWeight: 700, fontSize: 14, color: currentTheme.text }, children: r.name }), (0, jsx_runtime_1.jsxs)("span", { style: { fontSize: 11, fontWeight: 700, color: '#8B5CF6', backgroundColor: currentTheme.isDark ? '#8B5CF625' : '#EDE9FE', padding: '2px 8px', borderRadius: 10 }, children: [r.opsPerSec.toLocaleString(), " ops/s"] })] }), (0, jsx_runtime_1.jsx)("div", { style: { fontSize: 12, color: currentTheme.textMuted, marginBottom: 10 }, children: r.description }), r.note && ((0, jsx_runtime_1.jsx)("div", { style: { fontSize: 11, color: currentTheme.textMuted, marginBottom: 10 }, children: r.note })), (0, jsx_runtime_1.jsxs)("div", { style: { fontSize: 11, color: currentTheme.textMuted }, children: [r.operations.toLocaleString(), " ops in ", r.durationMs, "ms"] })] }, idx)))] }), (0, jsx_runtime_1.jsxs)("div", { style: { padding: '16px 24px', borderTop: `1px solid ${currentTheme.border}`, backgroundColor: currentTheme.surface, display: 'flex', gap: 12 }, children: [(0, jsx_runtime_1.jsx)("button", { onClick: startBenchmark, disabled: isRunning, style: {
                             flex: 1,
                             padding: '12px 18px',
                             backgroundColor: isRunning ? '#6D28D9' : '#8B5CF6',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.24",
+  "version": "0.0.27",
   "description": "Never let a lost connection break a promise. Local-first sync that faithfully keeps data safe until you're back online.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -141,7 +141,8 @@
     "build": "tsc",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run test && npm run build"
+    "test:package": "node scripts\\package-smoke.mjs",
+    "prepublishOnly": "npm run test && npm run build && npm run test:package"
   },
   "peerDependencies": {
     "@libsql/client": "^0.6.0",