@syncular/migrations 0.0.1-60

package/dist/define.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @syncular/migrations - Migration definition
+ */
+import type { DefinedMigrations, MigrationRecord, ParsedMigration } from './types';
+/**
+ * Define versioned migrations with automatic version parsing and sorting.
+ *
+ * @example
+ * ```typescript
+ * export const migrations = defineMigrations({
+ *   v1: async (db) => {
+ *     await db.schema.createTable('tasks')
+ *       .addColumn('id', 'text', col => col.primaryKey())
+ *       .addColumn('title', 'text', col => col.notNull())
+ *       .execute();
+ *   },
+ *   v2: async (db) => {
+ *     await db.schema.alterTable('tasks')
+ *       .addColumn('priority', 'integer', col => col.defaultTo(0))
+ *       .execute();
+ *   },
+ * });
+ * ```
+ */
+export declare function defineMigrations<DB = unknown, T extends MigrationRecord<DB> = MigrationRecord<DB>>(versionedMigrations: T): DefinedMigrations<DB>;
+/**
+ * Get the checksum for a migration.
+ */
+export declare function getMigrationChecksum<DB>(migration: ParsedMigration<DB>): string;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAEjB,eAAe,EACf,eAAe,EAChB,MAAM,SAAS,CAAC;AAuCjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,GAAG,OAAO,EACZ,CAAC,SAAS,eAAe,CAAC,EAAE,CAAC,GAAG,eAAe,CAAC,EAAE,CAAC,EACnD,mBAAmB,EAAE,CAAC,GAAG,iBAAiB,CAAC,EAAE,CAAC,CA0C/C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EACrC,SAAS,EAAE,eAAe,CAAC,EAAE,CAAC,GAC7B,MAAM,CAER"}

package/dist/define.js

@@ -0,0 +1,98 @@
+/**
+ * @syncular/migrations - Migration definition
+ */
+/**
+ * Parse a version key (e.g., 'v1', 'v2', '1', '2') into a version number.
+ */
+function parseVersionKey(key) {
+    // Support both 'v1' and '1' formats
+    const match = key.match(/^v?(\d+)$/i);
+    if (!match)
+        return null;
+    const version = Number.parseInt(match[1], 10);
+    return Number.isNaN(version) ? null : version;
+}
+/**
+ * Normalize a function source string for checksum comparison.
+ * Strips comments and collapses whitespace so that formatting-only
+ * changes don't break checksums.
+ */
+function normalizeSource(source) {
+    return source
+        .replace(/\/\/[^\n]*/g, '') // strip // comments
+        .replace(/\/\*[\s\S]*?\*\//g, '') // strip /* */ comments
+        .replace(/\s+/g, ' ') // collapse whitespace
+        .trim();
+}
+/**
+ * Compute a simple checksum for a migration function.
+ * Used to detect if a migration has changed after being applied.
+ */
+function computeChecksum(fn) {
+    const fnStr = normalizeSource(fn.toString());
+    let hash = 0;
+    for (let i = 0; i < fnStr.length; i++) {
+        hash = (hash * 31 + fnStr.charCodeAt(i)) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+/**
+ * Define versioned migrations with automatic version parsing and sorting.
+ *
+ * @example
+ * ```typescript
+ * export const migrations = defineMigrations({
+ *   v1: async (db) => {
+ *     await db.schema.createTable('tasks')
+ *       .addColumn('id', 'text', col => col.primaryKey())
+ *       .addColumn('title', 'text', col => col.notNull())
+ *       .execute();
+ *   },
+ *   v2: async (db) => {
+ *     await db.schema.alterTable('tasks')
+ *       .addColumn('priority', 'integer', col => col.defaultTo(0))
+ *       .execute();
+ *   },
+ * });
+ * ```
+ */
+export function defineMigrations(versionedMigrations) {
+    const migrations = [];
+    for (const [key, fn] of Object.entries(versionedMigrations)) {
+        const version = parseVersionKey(key);
+        if (version === null) {
+            throw new Error(`Invalid migration key "${key}": must be a version number (e.g., 'v1', 'v2', '1', '2')`);
+        }
+        if (version < 1) {
+            throw new Error(`Invalid migration version ${version}: versions must be >= 1`);
+        }
+        migrations.push({
+            version,
+            name: key,
+            fn,
+        });
+    }
+    // Sort by version number
+    migrations.sort((a, b) => a.version - b.version);
+    // Check for duplicate versions
+    for (let i = 1; i < migrations.length; i++) {
+        if (migrations[i].version === migrations[i - 1].version) {
+            throw new Error(`Duplicate migration version ${migrations[i].version}`);
+        }
+    }
+    const currentVersion = migrations.length > 0 ? migrations[migrations.length - 1].version : 0;
+    return {
+        migrations,
+        currentVersion,
+        getMigration(version) {
+            return migrations.find((m) => m.version === version);
+        },
+    };
+}
+/**
+ * Get the checksum for a migration.
+ */
+export function getMigrationChecksum(migration) {
+    return computeChecksum(migration.fn);
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @syncular/migrations - Versioned migration system
+ *
+ * Provides migration definition, tracking, and execution.
+ */
+export * from './define';
+export * from './runner';
+export * from './tracking';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @syncular/migrations - Versioned migration system
+ *
+ * Provides migration definition, tracking, and execution.
+ */
+export * from './define';
+export * from './runner';
+export * from './tracking';
+export * from './types';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC"}

package/dist/runner.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @syncular/migrations - Migration runner
+ */
+import type { RunMigrationsOptions, RunMigrationsResult } from './types';
+/**
+ * Run pending migrations and track their state.
+ *
+ * @example
+ * ```typescript
+ * import { defineMigrations, runMigrations } from '@syncular/migrations';
+ *
+ * const migrations = defineMigrations({
+ *   v1: async (db) => { ... },
+ *   v2: async (db) => { ... },
+ * });
+ *
+ * const result = await runMigrations({
+ *   db,
+ *   migrations,
+ *   trackingTable: 'sync_migration_state', // optional
+ * });
+ *
+ * console.log(`Applied versions: ${result.applied.join(', ')}`);
+ * console.log(`Current version: ${result.currentVersion}`);
+ * ```
+ */
+export declare function runMigrations<DB>(options: RunMigrationsOptions<DB>): Promise<RunMigrationsResult>;
+/**
+ * Get the current schema version without running any migrations.
+ */
+export declare function getSchemaVersion<DB>(db: import('kysely').Kysely<DB>, trackingTable?: string): Promise<number>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CAAC,EAAE,EACpC,OAAO,EAAE,oBAAoB,CAAC,EAAE,CAAC,GAChC,OAAO,CAAC,mBAAmB,CAAC,CAsE9B;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EACvC,EAAE,EAAE,OAAO,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,EAC/B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC,CAKjB"}

package/dist/runner.js

@@ -0,0 +1,97 @@
+/**
+ * @syncular/migrations - Migration runner
+ */
+import { getMigrationChecksum } from './define';
+import { clearAppliedMigrations, ensureTrackingTable, getAppliedMigrations, recordAppliedMigration, } from './tracking';
+const DEFAULT_TRACKING_TABLE = 'sync_migration_state';
+/**
+ * Run pending migrations and track their state.
+ *
+ * @example
+ * ```typescript
+ * import { defineMigrations, runMigrations } from '@syncular/migrations';
+ *
+ * const migrations = defineMigrations({
+ *   v1: async (db) => { ... },
+ *   v2: async (db) => { ... },
+ * });
+ *
+ * const result = await runMigrations({
+ *   db,
+ *   migrations,
+ *   trackingTable: 'sync_migration_state', // optional
+ * });
+ *
+ * console.log(`Applied versions: ${result.applied.join(', ')}`);
+ * console.log(`Current version: ${result.currentVersion}`);
+ * ```
+ */
+export async function runMigrations(options) {
+    const { db, migrations } = options;
+    const trackingTable = options.trackingTable ?? DEFAULT_TRACKING_TABLE;
+    const onChecksumMismatch = options.onChecksumMismatch ?? 'error';
+    // Ensure tracking table exists
+    await ensureTrackingTable(db, trackingTable);
+    // Get already applied migrations
+    let applied = await getAppliedMigrations(db, trackingTable);
+    let appliedByVersion = new Map(applied.map((m) => [m.version, m]));
+    const appliedVersions = [];
+    let wasReset = false;
+    // Check for checksum mismatches up-front when reset mode is enabled
+    if (onChecksumMismatch === 'reset' && applied.length > 0) {
+        const hasMismatch = migrations.migrations.some((migration) => {
+            const existing = appliedByVersion.get(migration.version);
+            if (!existing)
+                return false;
+            return existing.checksum !== getMigrationChecksum(migration);
+        });
+        if (hasMismatch) {
+            // Let caller drop application tables first
+            await options.beforeReset?.(db);
+            // Clear tracking state so all migrations re-run
+            await clearAppliedMigrations(db, trackingTable);
+            wasReset = true;
+            // Refresh applied list (now empty)
+            applied = await getAppliedMigrations(db, trackingTable);
+            appliedByVersion = new Map(applied.map((m) => [m.version, m]));
+        }
+    }
+    for (const migration of migrations.migrations) {
+        const existing = appliedByVersion.get(migration.version);
+        if (existing) {
+            // Migration already applied - verify checksum hasn't changed
+            const currentChecksum = getMigrationChecksum(migration);
+            if (existing.checksum !== currentChecksum) {
+                throw new Error(`Migration v${migration.version} (${migration.name}) has changed since it was applied. ` +
+                    `Expected checksum ${existing.checksum}, got ${currentChecksum}. ` +
+                    'Migrations must not be modified after being applied.');
+            }
+            continue;
+        }
+        // Run the migration
+        await migration.fn(db);
+        // Record it as applied
+        await recordAppliedMigration(db, trackingTable, {
+            version: migration.version,
+            name: migration.name,
+            checksum: getMigrationChecksum(migration),
+        });
+        appliedVersions.push(migration.version);
+    }
+    return {
+        applied: appliedVersions,
+        currentVersion: migrations.currentVersion,
+        wasReset,
+    };
+}
+/**
+ * Get the current schema version without running any migrations.
+ */
+export async function getSchemaVersion(db, trackingTable) {
+    const tableName = trackingTable ?? DEFAULT_TRACKING_TABLE;
+    const applied = await getAppliedMigrations(db, tableName);
+    if (applied.length === 0)
+        return 0;
+    return applied[applied.length - 1].version;
+}
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/dist/tracking.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @syncular/migrations - Migration tracking table helpers
+ */
+import { type Kysely } from 'kysely';
+import type { MigrationStateRow } from './types';
+/**
+ * Ensure the migration tracking table exists.
+ */
+export declare function ensureTrackingTable<DB>(db: Kysely<DB>, tableName: string): Promise<void>;
+/**
+ * Get all applied migrations from the tracking table.
+ */
+export declare function getAppliedMigrations<DB, TTableName extends string>(db: Kysely<DB>, tableName: TTableName): Promise<MigrationStateRow[]>;
+/**
+ * Record a migration as applied in the tracking table.
+ */
+export declare function recordAppliedMigration<DB, TTableName extends string>(db: Kysely<DB>, tableName: TTableName, migration: Omit<MigrationStateRow, 'applied_at'>): Promise<void>;
+/**
+ * Clear all rows from the migration tracking table.
+ * Used when resetting the database after a checksum mismatch.
+ */
+export declare function clearAppliedMigrations<DB>(db: Kysely<DB>, tableName: string): Promise<void>;
+/**
+ * Get the current schema version from the tracking table.
+ * Returns 0 if no migrations have been applied.
+ */
+export declare function getCurrentVersion<DB, TTableName extends string>(db: Kysely<DB>, tableName: TTableName): Promise<number>;
+//# sourceMappingURL=tracking.d.ts.map

package/dist/tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../src/tracking.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAO,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAC1C,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,UAAU,SAAS,MAAM,EACtE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EACd,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAU9B;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,UAAU,SAAS,MAAM,EACxE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EACd,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,IAAI,CAAC,iBAAiB,EAAE,YAAY,CAAC,GAC/C,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAC7C,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,UAAU,SAAS,MAAM,EACnE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EACd,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/dist/tracking.js

@@ -0,0 +1,62 @@
+/**
+ * @syncular/migrations - Migration tracking table helpers
+ */
+import { sql } from 'kysely';
+/**
+ * Ensure the migration tracking table exists.
+ */
+export async function ensureTrackingTable(db, tableName) {
+    await db.schema
+        .createTable(tableName)
+        .ifNotExists()
+        .addColumn('version', 'integer', (col) => col.primaryKey())
+        .addColumn('name', 'text', (col) => col.notNull())
+        .addColumn('applied_at', 'text', (col) => col.notNull())
+        .addColumn('checksum', 'text', (col) => col.notNull())
+        .execute();
+}
+/**
+ * Get all applied migrations from the tracking table.
+ */
+export async function getAppliedMigrations(db, tableName) {
+    await ensureTrackingTable(db, tableName);
+    const result = await sql `
+    select version, name, applied_at, checksum
+    from ${sql.table(tableName)}
+    order by version asc
+  `.execute(db);
+    return result.rows;
+}
+/**
+ * Record a migration as applied in the tracking table.
+ */
+export async function recordAppliedMigration(db, tableName, migration) {
+    await ensureTrackingTable(db, tableName);
+    await sql `
+    insert into ${sql.table(tableName)} (version, name, applied_at, checksum)
+    values (
+      ${migration.version},
+      ${migration.name},
+      ${new Date().toISOString()},
+      ${migration.checksum}
+    )
+  `.execute(db);
+}
+/**
+ * Clear all rows from the migration tracking table.
+ * Used when resetting the database after a checksum mismatch.
+ */
+export async function clearAppliedMigrations(db, tableName) {
+    await sql `delete from ${sql.table(tableName)}`.execute(db);
+}
+/**
+ * Get the current schema version from the tracking table.
+ * Returns 0 if no migrations have been applied.
+ */
+export async function getCurrentVersion(db, tableName) {
+    const applied = await getAppliedMigrations(db, tableName);
+    if (applied.length === 0)
+        return 0;
+    return applied[applied.length - 1].version;
+}
+//# sourceMappingURL=tracking.js.map

package/dist/tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.js","sourceRoot":"","sources":["../src/tracking.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAe,GAAG,EAAE,MAAM,QAAQ,CAAC;AAG1C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,EAAc,EACd,SAAiB,EACF;IACf,MAAM,EAAE,CAAC,MAAM;SACZ,WAAW,CAAC,SAAS,CAAC;SACtB,WAAW,EAAE;SACb,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;SAC1D,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;SACvD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;SACrD,OAAO,EAAE,CAAC;AAAA,CACd;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAAc,EACd,SAAqB,EACS;IAC9B,MAAM,mBAAmB,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAEzC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAmB;;WAElC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC;;GAE5B,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAEd,OAAO,MAAM,CAAC,IAAI,CAAC;AAAA,CACpB;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,EAAc,EACd,SAAqB,EACrB,SAAgD,EACjC;IACf,MAAM,mBAAmB,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAEzC,MAAM,GAAG,CAAA;kBACO,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC;;QAE9B,SAAS,CAAC,OAAO;QACjB,SAAS,CAAC,IAAI;QACd,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACxB,SAAS,CAAC,QAAQ;;GAEvB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAAA,CACf;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,EAAc,EACd,SAAiB,EACF;IACf,MAAM,GAAG,CAAA,eAAe,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAAA,CAC5D;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAc,EACd,SAAqB,EACJ;IACjB,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC1D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,OAAO,CAAC;AAAA,CAC7C"}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @syncular/migrations - Type definitions
+ */
+import type { Kysely } from 'kysely';
+/**
+ * A single migration function that modifies the database schema.
+ */
+export type MigrationFn<DB = unknown> = (db: Kysely<DB>) => Promise<void>;
+/**
+ * Record of versioned migrations keyed by version string (e.g., 'v1', 'v2').
+ */
+export type MigrationRecord<DB = unknown> = Record<string, MigrationFn<DB>>;
+/**
+ * Parsed migration with version number and function.
+ */
+export interface ParsedMigration<DB = unknown> {
+    version: number;
+    name: string;
+    fn: MigrationFn<DB>;
+}
+/**
+ * Result of defineMigrations() - contains migrations and metadata.
+ */
+export interface DefinedMigrations<DB = unknown> {
+    /** Sorted list of migrations */
+    migrations: ParsedMigration<DB>[];
+    /** Current (latest) schema version */
+    currentVersion: number;
+    /** Get migration by version number */
+    getMigration(version: number): ParsedMigration<DB> | undefined;
+}
+/**
+ * Migration state row stored in the tracking table.
+ */
+export interface MigrationStateRow {
+    version: number;
+    name: string;
+    applied_at: string;
+    checksum: string;
+}
+/**
+ * Options for running migrations.
+ */
+export interface RunMigrationsOptions<DB = unknown> {
+    /** Kysely database instance */
+    db: Kysely<DB>;
+    /** Defined migrations from defineMigrations() */
+    migrations: DefinedMigrations<DB>;
+    /** Name of the tracking table (default: 'sync_migration_state') */
+    trackingTable?: string;
+    /** What to do when a migration's checksum doesn't match. Default: 'error' */
+    onChecksumMismatch?: 'error' | 'reset';
+    /** Called before clearing tracking state and re-running migrations.
+     *  Use this to drop application tables so migrations can recreate them. */
+    beforeReset?: (db: Kysely<DB>) => Promise<void>;
+}
+/**
+ * Result of running migrations.
+ */
+export interface RunMigrationsResult {
+    /** Versions that were applied in this run */
+    applied: number[];
+    /** Current schema version after migration */
+    currentVersion: number;
+    /** True if a checksum mismatch triggered a full reset */
+    wasReset: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,EAAE,GAAG,OAAO,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,EAAE,GAAG,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,EAAE,GAAG,OAAO;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,EAAE,GAAG,OAAO;IAC7C,gCAAgC;IAChC,UAAU,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC;IAClC,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;CAChE;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,EAAE,GAAG,OAAO;IAChD,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACf,iDAAiD;IACjD,UAAU,EAAE,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAClC,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACvC;+EAC2E;IAC3E,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAC;CACnB"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * @syncular/migrations - Type definitions
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@syncular/migrations",
+  "version": "0.0.1-60",
+  "description": "Database migration utilities for Syncular",
+  "license": "MIT",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/migrations"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript",
+    "migrations",
+    "database"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "test": "bun test --pass-with-no-tests",
+    "tsgo": "tsgo --noEmit",
+    "build": "rm -rf dist && tsgo",
+    "release": "bun pm pack --destination . && npm publish ./*.tgz --tag latest && rm -f ./*.tgz"
+  },
+  "peerDependencies": {
+    "kysely": "^0.28.0"
+  },
+  "devDependencies": {
+    "@syncular/config": "0.0.0",
+    "kysely": "*"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/define.ts

@@ -0,0 +1,123 @@
+/**
+ * @syncular/migrations - Migration definition
+ */
+
+import type {
+  DefinedMigrations,
+  MigrationFn,
+  MigrationRecord,
+  ParsedMigration,
+} from './types';
+
+/**
+ * Parse a version key (e.g., 'v1', 'v2', '1', '2') into a version number.
+ */
+function parseVersionKey(key: string): number | null {
+  // Support both 'v1' and '1' formats
+  const match = key.match(/^v?(\d+)$/i);
+  if (!match) return null;
+  const version = Number.parseInt(match[1]!, 10);
+  return Number.isNaN(version) ? null : version;
+}
+
+/**
+ * Normalize a function source string for checksum comparison.
+ * Strips comments and collapses whitespace so that formatting-only
+ * changes don't break checksums.
+ */
+function normalizeSource(source: string): string {
+  return source
+    .replace(/\/\/[^\n]*/g, '') // strip // comments
+    .replace(/\/\*[\s\S]*?\*\//g, '') // strip /* */ comments
+    .replace(/\s+/g, ' ') // collapse whitespace
+    .trim();
+}
+
+/**
+ * Compute a simple checksum for a migration function.
+ * Used to detect if a migration has changed after being applied.
+ */
+function computeChecksum<DB>(fn: MigrationFn<DB>): string {
+  const fnStr = normalizeSource(fn.toString());
+  let hash = 0;
+  for (let i = 0; i < fnStr.length; i++) {
+    hash = (hash * 31 + fnStr.charCodeAt(i)) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+/**
+ * Define versioned migrations with automatic version parsing and sorting.
+ *
+ * @example
+ * ```typescript
+ * export const migrations = defineMigrations({
+ *   v1: async (db) => {
+ *     await db.schema.createTable('tasks')
+ *       .addColumn('id', 'text', col => col.primaryKey())
+ *       .addColumn('title', 'text', col => col.notNull())
+ *       .execute();
+ *   },
+ *   v2: async (db) => {
+ *     await db.schema.alterTable('tasks')
+ *       .addColumn('priority', 'integer', col => col.defaultTo(0))
+ *       .execute();
+ *   },
+ * });
+ * ```
+ */
+export function defineMigrations<
+  DB = unknown,
+  T extends MigrationRecord<DB> = MigrationRecord<DB>,
+>(versionedMigrations: T): DefinedMigrations<DB> {
+  const migrations: ParsedMigration<DB>[] = [];
+
+  for (const [key, fn] of Object.entries(versionedMigrations)) {
+    const version = parseVersionKey(key);
+    if (version === null) {
+      throw new Error(
+        `Invalid migration key "${key}": must be a version number (e.g., 'v1', 'v2', '1', '2')`
+      );
+    }
+    if (version < 1) {
+      throw new Error(
+        `Invalid migration version ${version}: versions must be >= 1`
+      );
+    }
+    migrations.push({
+      version,
+      name: key,
+      fn,
+    });
+  }
+
+  // Sort by version number
+  migrations.sort((a, b) => a.version - b.version);
+
+  // Check for duplicate versions
+  for (let i = 1; i < migrations.length; i++) {
+    if (migrations[i]!.version === migrations[i - 1]!.version) {
+      throw new Error(`Duplicate migration version ${migrations[i]!.version}`);
+    }
+  }
+
+  const currentVersion =
+    migrations.length > 0 ? migrations[migrations.length - 1]!.version : 0;
+
+  return {
+    migrations,
+    currentVersion,
+    getMigration(version: number) {
+      return migrations.find((m) => m.version === version);
+    },
+  };
+}
+
+/**
+ * Get the checksum for a migration.
+ */
+export function getMigrationChecksum<DB>(
+  migration: ParsedMigration<DB>
+): string {
+  return computeChecksum(migration.fn);
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @syncular/migrations - Versioned migration system
+ *
+ * Provides migration definition, tracking, and execution.
+ */
+
+export * from './define';
+export * from './runner';
+export * from './tracking';
+export * from './types';

package/src/runner.ts

@@ -0,0 +1,123 @@
+/**
+ * @syncular/migrations - Migration runner
+ */
+
+import { getMigrationChecksum } from './define';
+import {
+  clearAppliedMigrations,
+  ensureTrackingTable,
+  getAppliedMigrations,
+  recordAppliedMigration,
+} from './tracking';
+import type { RunMigrationsOptions, RunMigrationsResult } from './types';
+
+const DEFAULT_TRACKING_TABLE = 'sync_migration_state';
+
+/**
+ * Run pending migrations and track their state.
+ *
+ * @example
+ * ```typescript
+ * import { defineMigrations, runMigrations } from '@syncular/migrations';
+ *
+ * const migrations = defineMigrations({
+ *   v1: async (db) => { ... },
+ *   v2: async (db) => { ... },
+ * });
+ *
+ * const result = await runMigrations({
+ *   db,
+ *   migrations,
+ *   trackingTable: 'sync_migration_state', // optional
+ * });
+ *
+ * console.log(`Applied versions: ${result.applied.join(', ')}`);
+ * console.log(`Current version: ${result.currentVersion}`);
+ * ```
+ */
+export async function runMigrations<DB>(
+  options: RunMigrationsOptions<DB>
+): Promise<RunMigrationsResult> {
+  const { db, migrations } = options;
+  const trackingTable = options.trackingTable ?? DEFAULT_TRACKING_TABLE;
+  const onChecksumMismatch = options.onChecksumMismatch ?? 'error';
+
+  // Ensure tracking table exists
+  await ensureTrackingTable(db, trackingTable);
+
+  // Get already applied migrations
+  let applied = await getAppliedMigrations(db, trackingTable);
+  let appliedByVersion = new Map(applied.map((m) => [m.version, m]));
+
+  const appliedVersions: number[] = [];
+  let wasReset = false;
+
+  // Check for checksum mismatches up-front when reset mode is enabled
+  if (onChecksumMismatch === 'reset' && applied.length > 0) {
+    const hasMismatch = migrations.migrations.some((migration) => {
+      const existing = appliedByVersion.get(migration.version);
+      if (!existing) return false;
+      return existing.checksum !== getMigrationChecksum(migration);
+    });
+
+    if (hasMismatch) {
+      // Let caller drop application tables first
+      await options.beforeReset?.(db);
+      // Clear tracking state so all migrations re-run
+      await clearAppliedMigrations(db, trackingTable);
+      wasReset = true;
+
+      // Refresh applied list (now empty)
+      applied = await getAppliedMigrations(db, trackingTable);
+      appliedByVersion = new Map(applied.map((m) => [m.version, m]));
+    }
+  }
+
+  for (const migration of migrations.migrations) {
+    const existing = appliedByVersion.get(migration.version);
+
+    if (existing) {
+      // Migration already applied - verify checksum hasn't changed
+      const currentChecksum = getMigrationChecksum(migration);
+      if (existing.checksum !== currentChecksum) {
+        throw new Error(
+          `Migration v${migration.version} (${migration.name}) has changed since it was applied. ` +
+            `Expected checksum ${existing.checksum}, got ${currentChecksum}. ` +
+            'Migrations must not be modified after being applied.'
+        );
+      }
+      continue;
+    }
+
+    // Run the migration
+    await migration.fn(db);
+
+    // Record it as applied
+    await recordAppliedMigration(db, trackingTable, {
+      version: migration.version,
+      name: migration.name,
+      checksum: getMigrationChecksum(migration),
+    });
+
+    appliedVersions.push(migration.version);
+  }
+
+  return {
+    applied: appliedVersions,
+    currentVersion: migrations.currentVersion,
+    wasReset,
+  };
+}
+
+/**
+ * Get the current schema version without running any migrations.
+ */
+export async function getSchemaVersion<DB>(
+  db: import('kysely').Kysely<DB>,
+  trackingTable?: string
+): Promise<number> {
+  const tableName = trackingTable ?? DEFAULT_TRACKING_TABLE;
+  const applied = await getAppliedMigrations(db, tableName);
+  if (applied.length === 0) return 0;
+  return applied[applied.length - 1]!.version;
+}

package/src/tracking.ts

@@ -0,0 +1,86 @@
+/**
+ * @syncular/migrations - Migration tracking table helpers
+ */
+
+import { type Kysely, sql } from 'kysely';
+import type { MigrationStateRow } from './types';
+
+/**
+ * Ensure the migration tracking table exists.
+ */
+export async function ensureTrackingTable<DB>(
+  db: Kysely<DB>,
+  tableName: string
+): Promise<void> {
+  await db.schema
+    .createTable(tableName)
+    .ifNotExists()
+    .addColumn('version', 'integer', (col) => col.primaryKey())
+    .addColumn('name', 'text', (col) => col.notNull())
+    .addColumn('applied_at', 'text', (col) => col.notNull())
+    .addColumn('checksum', 'text', (col) => col.notNull())
+    .execute();
+}
+
+/**
+ * Get all applied migrations from the tracking table.
+ */
+export async function getAppliedMigrations<DB, TTableName extends string>(
+  db: Kysely<DB>,
+  tableName: TTableName
+): Promise<MigrationStateRow[]> {
+  await ensureTrackingTable(db, tableName);
+
+  const result = await sql<MigrationStateRow>`
+    select version, name, applied_at, checksum
+    from ${sql.table(tableName)}
+    order by version asc
+  `.execute(db);
+
+  return result.rows;
+}
+
+/**
+ * Record a migration as applied in the tracking table.
+ */
+export async function recordAppliedMigration<DB, TTableName extends string>(
+  db: Kysely<DB>,
+  tableName: TTableName,
+  migration: Omit<MigrationStateRow, 'applied_at'>
+): Promise<void> {
+  await ensureTrackingTable(db, tableName);
+
+  await sql`
+    insert into ${sql.table(tableName)} (version, name, applied_at, checksum)
+    values (
+      ${migration.version},
+      ${migration.name},
+      ${new Date().toISOString()},
+      ${migration.checksum}
+    )
+  `.execute(db);
+}
+
+/**
+ * Clear all rows from the migration tracking table.
+ * Used when resetting the database after a checksum mismatch.
+ */
+export async function clearAppliedMigrations<DB>(
+  db: Kysely<DB>,
+  tableName: string
+): Promise<void> {
+  await sql`delete from ${sql.table(tableName)}`.execute(db);
+}
+
+/**
+ * Get the current schema version from the tracking table.
+ * Returns 0 if no migrations have been applied.
+ */
+export async function getCurrentVersion<DB, TTableName extends string>(
+  db: Kysely<DB>,
+  tableName: TTableName
+): Promise<number> {
+  const applied = await getAppliedMigrations(db, tableName);
+  if (applied.length === 0) return 0;
+  return applied[applied.length - 1]!.version;
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+/**
+ * @syncular/migrations - Type definitions
+ */
+
+import type { Kysely } from 'kysely';
+
+/**
+ * A single migration function that modifies the database schema.
+ */
+export type MigrationFn<DB = unknown> = (db: Kysely<DB>) => Promise<void>;
+
+/**
+ * Record of versioned migrations keyed by version string (e.g., 'v1', 'v2').
+ */
+export type MigrationRecord<DB = unknown> = Record<string, MigrationFn<DB>>;
+
+/**
+ * Parsed migration with version number and function.
+ */
+export interface ParsedMigration<DB = unknown> {
+  version: number;
+  name: string;
+  fn: MigrationFn<DB>;
+}
+
+/**
+ * Result of defineMigrations() - contains migrations and metadata.
+ */
+export interface DefinedMigrations<DB = unknown> {
+  /** Sorted list of migrations */
+  migrations: ParsedMigration<DB>[];
+  /** Current (latest) schema version */
+  currentVersion: number;
+  /** Get migration by version number */
+  getMigration(version: number): ParsedMigration<DB> | undefined;
+}
+
+/**
+ * Migration state row stored in the tracking table.
+ */
+export interface MigrationStateRow {
+  version: number;
+  name: string;
+  applied_at: string;
+  checksum: string;
+}
+
+/**
+ * Options for running migrations.
+ */
+export interface RunMigrationsOptions<DB = unknown> {
+  /** Kysely database instance */
+  db: Kysely<DB>;
+  /** Defined migrations from defineMigrations() */
+  migrations: DefinedMigrations<DB>;
+  /** Name of the tracking table (default: 'sync_migration_state') */
+  trackingTable?: string;
+  /** What to do when a migration's checksum doesn't match. Default: 'error' */
+  onChecksumMismatch?: 'error' | 'reset';
+  /** Called before clearing tracking state and re-running migrations.
+   *  Use this to drop application tables so migrations can recreate them. */
+  beforeReset?: (db: Kysely<DB>) => Promise<void>;
+}
+
+/**
+ * Result of running migrations.
+ */
+export interface RunMigrationsResult {
+  /** Versions that were applied in this run */
+  applied: number[];
+  /** Current schema version after migration */
+  currentVersion: number;
+  /** True if a checksum mismatch triggered a full reset */
+  wasReset: boolean;
+}