local-lite 0.0.24 → 0.0.25

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/config/index.js

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

package/dist/config/types.d.ts

@@ -1,6 +1,6 @@
 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 { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
 export interface SupabaseConfigOptions {
     url?: string;
@@ -84,10 +84,15 @@ export interface LocalLiteConfig {
      */
     tables?: string[];
     /**
-     * Initial SQL table schema migration queries to execute on startup.
+     * 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';
@@ -31,6 +31,7 @@ export interface LocalFirstClientConfig {
     autoSchema?: boolean;
     tables?: string[];
     migrations?: string[];
+    schemaMigrations?: SchemaMigration[];
     autoStart?: boolean;
     coalesceOutbox?: boolean;
     jsonColumns?: Record<string, string[]>;
@@ -108,6 +109,7 @@ export declare class LocalFirstClient {
     readonly session: SessionManager;
     private primaryKey;
     private migrations;
+    private schemaMigrations;
     private autoStart;
     private initialization?;
     constructor(config: LocalFirstClientConfig);
@@ -139,6 +141,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;
@@ -182,6 +206,7 @@ class LocalFirstClient {
     session;
     primaryKey;
     migrations;
+    schemaMigrations;
     autoStart;
     initialization;
     constructor(config) {
@@ -193,6 +218,7 @@ class LocalFirstClient {
         this.coalesceOutbox = config.coalesceOutbox ?? true;
         this.tables = config.tables ?? [];
         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 +442,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,6 +451,36 @@ 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.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "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 package-smoke.mjs",
+    "prepublishOnly": "npm run test && npm run build && npm run test:package"
   },
   "peerDependencies": {
     "@libsql/client": "^0.6.0",