@syncular/migrations 0.0.6-244 → 0.0.6-246

package/src/define.ts

@@ -4,8 +4,8 @@
 
 import type {
   DefinedMigrations,
+  MigrationChecksumMode,
   MigrationDefinition,
-  MigrationFn,
   MigrationRecord,
   ParsedMigration,
 } from './types';
@@ -21,149 +21,26 @@ function parseVersionKey(key: string): number | null {
   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 stripCommentsPreservingStrings(source: string): string {
-  let out = '';
-  let i = 0;
-  let mode:
-    | 'code'
-    | 'singleQuote'
-    | 'doubleQuote'
-    | 'template'
-    | 'lineComment'
-    | 'blockComment' = 'code';
-
-  while (i < source.length) {
-    const char = source[i]!;
-    const next = source[i + 1];
-
-    if (mode === 'lineComment') {
-      if (char === '\n') {
-        out += '\n';
-        mode = 'code';
-      }
-      i += 1;
-      continue;
-    }
-
-    if (mode === 'blockComment') {
-      if (char === '*' && next === '/') {
-        i += 2;
-        mode = 'code';
-        continue;
-      }
-      if (char === '\n') {
-        out += '\n';
-      }
-      i += 1;
-      continue;
-    }
-
-    if (mode === 'singleQuote') {
-      out += char;
-      if (char === '\\' && next !== undefined) {
-        out += next;
-        i += 2;
-        continue;
-      }
-      if (char === "'") {
-        mode = 'code';
-      }
-      i += 1;
-      continue;
-    }
-
-    if (mode === 'doubleQuote') {
-      out += char;
-      if (char === '\\' && next !== undefined) {
-        out += next;
-        i += 2;
-        continue;
-      }
-      if (char === '"') {
-        mode = 'code';
-      }
-      i += 1;
-      continue;
-    }
-
-    if (mode === 'template') {
-      out += char;
-      if (char === '\\' && next !== undefined) {
-        out += next;
-        i += 2;
-        continue;
-      }
-      if (char === '`') {
-        mode = 'code';
-      }
-      i += 1;
-      continue;
-    }
-
-    if (char === '/' && next === '/') {
-      mode = 'lineComment';
-      i += 2;
-      continue;
-    }
-    if (char === '/' && next === '*') {
-      mode = 'blockComment';
-      i += 2;
-      continue;
-    }
-    if (char === "'") {
-      mode = 'singleQuote';
-      out += char;
-      i += 1;
-      continue;
-    }
-    if (char === '"') {
-      mode = 'doubleQuote';
-      out += char;
-      i += 1;
-      continue;
-    }
-    if (char === '`') {
-      mode = 'template';
-      out += char;
-      i += 1;
-      continue;
-    }
-
-    out += char;
-    i += 1;
-  }
-
-  return out;
-}
-
-function normalizeSource(source: string): string {
-  return stripCommentsPreservingStrings(source)
-    .replace(/\s+/g, ' ') // collapse whitespace
-    .trim();
+function isMigrationDefinitionObject<DB>(
+  value: MigrationDefinition<DB>
+): value is MigrationDefinition<DB> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-/**
- * 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;
+function normalizeChecksumMode(
+  key: string,
+  checksum: MigrationChecksumMode | undefined
+): MigrationChecksumMode {
+  if (checksum === undefined) {
+    return 'deterministic';
+  }
+  if (checksum === 'deterministic' || checksum === 'disabled') {
+    return checksum;
   }
-  return hash.toString(16).padStart(8, '0');
-}
 
-function isMigrationDefinitionObject<DB>(
-  value: MigrationDefinition<DB>
-): value is { up: MigrationFn<DB>; down?: MigrationFn<DB> } {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+  throw new Error(
+    `Invalid migration "${key}": "checksum" must be "deterministic" or "disabled" when provided.`
+  );
 }
 
 /**
@@ -172,16 +49,28 @@ function isMigrationDefinitionObject<DB>(
  * @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();
+ *   v1: {
+ *     up: async (db) => {
+ *       await db.schema.createTable('tasks')
+ *         .addColumn('id', 'text', col => col.primaryKey())
+ *         .addColumn('title', 'text', col => col.notNull())
+ *         .execute();
+ *     },
+ *     down: async (db) => {
+ *       await db.schema.dropTable('tasks').ifExists().execute();
+ *     },
  *   },
- *   v2: async (db) => {
- *     await db.schema.alterTable('tasks')
- *       .addColumn('priority', 'integer', col => col.defaultTo(0))
- *       .execute();
+ *   v2: {
+ *     up: async (db) => {
+ *       await db.schema.alterTable('tasks')
+ *         .addColumn('priority', 'integer', col => col.defaultTo(0))
+ *         .execute();
+ *     },
+ *     down: async (db) => {
+ *       await db.schema.alterTable('tasks')
+ *         .dropColumn('priority')
+ *         .execute();
+ *     },
  *   },
  * });
  * ```
@@ -205,45 +94,27 @@ export function defineMigrations<
       );
     }
 
-    const up = isMigrationDefinitionObject(definition)
-      ? definition.up
-      : definition;
-    const down = isMigrationDefinitionObject(definition)
-      ? definition.down
-      : undefined;
-    const compatibleChecksums = isMigrationDefinitionObject(definition)
-      ? (definition.compatibleChecksums ?? [])
-      : [];
-    if (typeof up !== 'function') {
+    if (!isMigrationDefinitionObject(definition)) {
       throw new Error(
-        `Invalid migration "${key}": expected an async function or { up, down? } object.`
+        `Invalid migration "${key}": expected a { up, down } object. Shorthand migration functions are not supported.`
       );
     }
-    if (down !== undefined && typeof down !== 'function') {
-      throw new Error(
-        `Invalid migration "${key}": "down" must be a function when provided.`
-      );
+
+    const { up, down } = definition;
+    const checksum = normalizeChecksumMode(key, definition.checksum);
+
+    if (typeof up !== 'function') {
+      throw new Error(`Invalid migration "${key}": "up" must be a function.`);
     }
-    if (
-      !Array.isArray(compatibleChecksums) ||
-      compatibleChecksums.some(
-        (checksum) =>
-          typeof checksum !== 'string' || checksum.trim().length === 0
-      )
-    ) {
-      throw new Error(
-        `Invalid migration "${key}": "compatibleChecksums" must be an array of non-empty strings when provided.`
-      );
+    if (typeof down !== 'function') {
+      throw new Error(`Invalid migration "${key}": "down" must be a function.`);
     }
-
     migrations.push({
       version,
       name: key,
       up,
       down,
-      compatibleChecksums: [
-        ...new Set(compatibleChecksums.map((v) => v.trim())),
-      ],
+      checksum,
     });
   }
 
@@ -268,26 +139,3 @@ export function defineMigrations<
     },
   };
 }
-
-/**
- * Get the checksum for a migration.
- */
-export function getMigrationChecksum<DB>(
-  migration: ParsedMigration<DB>
-): string {
-  return computeChecksum(migration.up);
-}
-
-/**
- * Get the accepted checksums for a migration, including the current checksum.
- */
-export function getCompatibleMigrationChecksums<DB>(
-  migration: ParsedMigration<DB>
-): string[] {
-  return [
-    ...new Set([
-      getMigrationChecksum(migration),
-      ...migration.compatibleChecksums,
-    ]),
-  ];
-}

package/src/index.ts

@@ -4,6 +4,7 @@
  * Provides migration definition, tracking, naming, and execution.
  */
 
+export * from './checksum';
 export * from './define';
 export * from './naming';
 export * from './runner';

package/src/runner.ts

@@ -3,9 +3,13 @@
  */
 
 import {
-  getCompatibleMigrationChecksums,
-  getMigrationChecksum,
-} from './define';
+  DISABLED_MIGRATION_CHECKSUM,
+  DISABLED_MIGRATION_CHECKSUM_ALGORITHM,
+  getLegacyMigrationChecksum,
+  getMigrationChecksumAlgorithm,
+  getStoredDeterministicChecksum,
+  LEGACY_SOURCE_MIGRATION_CHECKSUM_ALGORITHM,
+} from './checksum';
 import { DEFAULT_MIGRATION_TRACKING_TABLE } from './naming';
 import {
   clearAppliedMigrations,
@@ -15,6 +19,9 @@ import {
   removeAppliedMigration,
 } from './tracking';
 import type {
+  DefinedMigrations,
+  MigrationChecksumAlgorithm,
+  ParsedMigration,
   RunMigrationsOptions,
   RunMigrationsResult,
   RunMigrationsToVersionOptions,
@@ -35,6 +42,43 @@ function isAlreadyExistsSchemaError(error: unknown): boolean {
   );
 }
 
+function isDeterministicMigration<DB>(migration: ParsedMigration<DB>): boolean {
+  return migration.checksum === 'deterministic';
+}
+
+function getDeterministicMigrations<DB>(
+  migrations: DefinedMigrations<DB>
+): ParsedMigration<DB>[] {
+  return migrations.migrations.filter(isDeterministicMigration);
+}
+
+async function getStoredChecksumForMigration<DB>(
+  options: RunMigrationsOptions<DB>,
+  migration: ParsedMigration<DB>
+): Promise<string> {
+  return getStoredDeterministicChecksum(migration, options.checksums);
+}
+
+async function getChecksumForAlgorithm<DB>(
+  options: RunMigrationsOptions<DB>,
+  migration: ParsedMigration<DB>,
+  algorithm: MigrationChecksumAlgorithm
+): Promise<string> {
+  if (algorithm === DISABLED_MIGRATION_CHECKSUM_ALGORITHM) {
+    return DISABLED_MIGRATION_CHECKSUM;
+  }
+
+  if (algorithm === LEGACY_SOURCE_MIGRATION_CHECKSUM_ALGORITHM) {
+    return getLegacyMigrationChecksum(migration);
+  }
+
+  if (algorithm === 'sql_trace_v1') {
+    return await getStoredChecksumForMigration(options, migration);
+  }
+
+  throw new Error(`Unsupported migration checksum algorithm: ${algorithm}`);
+}
+
 async function runWithMigrationQueue<T>(
   queueKey: string,
   task: () => Promise<T>
@@ -66,8 +110,14 @@ async function runWithMigrationQueue<T>(
  * import { defineMigrations, runMigrations } from '@syncular/migrations';
  *
  * const migrations = defineMigrations({
- *   v1: async (db) => { ... },
- *   v2: async (db) => { ... },
+ *   v1: {
+ *     up: async (db) => { ... },
+ *     down: async (db) => { ... },
+ *   },
+ *   v2: {
+ *     up: async (db) => { ... },
+ *     down: async (db) => { ... },
+ *   },
  * });
  *
  * const result = await runMigrations({
@@ -130,16 +180,28 @@ export async function runMigrationsToVersion<DB>(
     const revertedVersions: number[] = [];
     let wasReset = false;
     let recoveredFromSchemaConflict = false;
+    const deterministicMigrations = getDeterministicMigrations(migrations);
 
     // Check for checksum mismatches up-front when reset mode is enabled
     if (onChecksumMismatch === 'reset' && applied.length > 0) {
-      const hasMismatch = migrations.migrations.some((migration) => {
+      let hasMismatch = false;
+
+      for (const migration of deterministicMigrations) {
         const existing = appliedByVersion.get(migration.version);
-        if (!existing) return false;
-        return !getCompatibleMigrationChecksums(migration).includes(
-          existing.checksum
+        if (!existing) {
+          continue;
+        }
+
+        const currentChecksum = await getChecksumForAlgorithm(
+          options,
+          migration,
+          existing.checksum_algorithm
         );
-      });
+        if (existing.checksum !== currentChecksum) {
+          hasMismatch = true;
+          break;
+        }
+      }
 
       if (hasMismatch) {
         // Let caller drop application tables first
@@ -159,9 +221,18 @@ export async function runMigrationsToVersion<DB>(
       if (!existing) {
         continue;
       }
-      const currentChecksum = getMigrationChecksum(migration);
-      const compatibleChecksums = getCompatibleMigrationChecksums(migration);
-      if (!compatibleChecksums.includes(existing.checksum)) {
+
+      if (migration.checksum === 'disabled') {
+        continue;
+      }
+
+      const currentChecksum = await getChecksumForAlgorithm(
+        options,
+        migration,
+        existing.checksum_algorithm
+      );
+
+      if (existing.checksum !== currentChecksum) {
         throw new Error(
           `Migration v${migration.version} (${migration.name}) has changed since it was applied. ` +
             `Stored checksum ${existing.checksum} is not compatible with current checksum ${currentChecksum}. ` +
@@ -209,10 +280,19 @@ export async function runMigrationsToVersion<DB>(
           continue;
         }
 
+        const checksum = await getStoredChecksumForMigration(
+          options,
+          migration
+        );
+
         await recordAppliedMigration(db, trackingTable, {
           version: migration.version,
           name: migration.name,
-          checksum: getMigrationChecksum(migration),
+          checksum,
+          checksum_algorithm: getMigrationChecksumAlgorithm(
+            migration,
+            options.checksums
+          ),
         });
         appliedVersions.push(migration.version);
       }
@@ -228,12 +308,6 @@ export async function runMigrationsToVersion<DB>(
             `Cannot revert migration v${version}: migration is not defined in current migration set.`
           );
         }
-        if (typeof migration.down !== 'function') {
-          throw new Error(
-            `Cannot revert migration v${version} (${migration.name}): down migration is not defined.`
-          );
-        }
-
         await migration.down(db);
         await removeAppliedMigration(db, trackingTable, version);
         revertedVersions.push(version);

package/src/tracking.ts

@@ -3,8 +3,22 @@
  */
 
 import { type Kysely, sql } from 'kysely';
+import { LEGACY_SOURCE_MIGRATION_CHECKSUM_ALGORITHM } from './checksum';
 import type { MigrationStateRow } from './types';
 
+function isDuplicateColumnError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  const message = error.message.toLowerCase();
+  return (
+    message.includes('duplicate column') ||
+    message.includes('already exists') ||
+    (message.includes('column') && message.includes('exists'))
+  );
+}
+
 /**
  * Ensure the migration tracking table exists.
  */
@@ -19,7 +33,19 @@ export async function ensureTrackingTable<DB>(
     .addColumn('name', 'text', (col) => col.notNull())
     .addColumn('applied_at', 'text', (col) => col.notNull())
     .addColumn('checksum', 'text', (col) => col.notNull())
+    .addColumn('checksum_algorithm', 'text', (col) => col.notNull())
     .execute();
+
+  try {
+    await sql`
+      alter table ${sql.table(tableName)}
+      add column checksum_algorithm text not null default ${sql.raw(`'${LEGACY_SOURCE_MIGRATION_CHECKSUM_ALGORITHM}'`)}
+    `.execute(db);
+  } catch (error) {
+    if (!isDuplicateColumnError(error)) {
+      throw error;
+    }
+  }
 }
 
 /**
@@ -32,7 +58,7 @@ export async function getAppliedMigrations<DB, TTableName extends string>(
   await ensureTrackingTable(db, tableName);
 
   const result = await sql<MigrationStateRow>`
-    select version, name, applied_at, checksum
+    select version, name, applied_at, checksum, checksum_algorithm
     from ${sql.table(tableName)}
     order by version asc
   `.execute(db);
@@ -51,12 +77,19 @@ export async function recordAppliedMigration<DB, TTableName extends string>(
   await ensureTrackingTable(db, tableName);
 
   await sql`
-    insert into ${sql.table(tableName)} (version, name, applied_at, checksum)
+    insert into ${sql.table(tableName)} (
+      version,
+      name,
+      applied_at,
+      checksum,
+      checksum_algorithm
+    )
     values (
       ${migration.version},
       ${migration.name},
       ${new Date().toISOString()},
-      ${migration.checksum}
+      ${migration.checksum},
+      ${migration.checksum_algorithm}
     )
   `.execute(db);
 }

package/src/types.ts

@@ -9,6 +9,15 @@ import type { Kysely } from 'kysely';
  */
 export type MigrationFn<DB = unknown> = (db: Kysely<DB>) => Promise<void>;
 
+export type MigrationChecksumMode = 'deterministic' | 'disabled';
+
+export type MigrationChecksumAlgorithm =
+  | 'legacy_source_v1'
+  | 'sql_trace_v1'
+  | 'disabled';
+
+export type MigrationChecksums = Record<string, string>;
+
 /**
  * A reversible migration definition.
  */
@@ -16,21 +25,14 @@ export interface ReversibleMigrationDefinition<DB = unknown> {
   /** Apply schema/data changes for this version. */
   up: MigrationFn<DB>;
   /** Revert schema/data changes for this version. */
-  down?: MigrationFn<DB>;
-  /**
-   * Historical checksums that should still be accepted for previously-applied
-   * copies of this migration.
-   */
-  compatibleChecksums?: string[];
+  down: MigrationFn<DB>;
+  /** Controls whether this migration participates in checksum validation. */
+  checksum?: MigrationChecksumMode;
 }
 
-/**
- * A migration definition can be a single "up" function or
- * an object with explicit up/down handlers.
- */
+/** A migration definition must explicitly provide both up/down handlers. */
 export type MigrationDefinition<DB = unknown> =
-  | MigrationFn<DB>
-  | ReversibleMigrationDefinition<DB>;
+  ReversibleMigrationDefinition<DB>;
 
 /**
  * Record of versioned migrations keyed by version string (e.g., 'v1', 'v2').
@@ -48,10 +50,10 @@ export interface ParsedMigration<DB = unknown> {
   name: string;
   /** Up migration function. */
   up: MigrationFn<DB>;
-  /** Optional down migration function. */
-  down?: MigrationFn<DB>;
-  /** Historical checksums that remain valid for already-applied copies. */
-  compatibleChecksums: string[];
+  /** Down migration function. */
+  down: MigrationFn<DB>;
+  /** Controls whether this migration participates in checksum validation. */
+  checksum: MigrationChecksumMode;
 }
 
 /**
@@ -74,6 +76,7 @@ export interface MigrationStateRow {
   name: string;
   applied_at: string;
   checksum: string;
+  checksum_algorithm: MigrationChecksumAlgorithm;
 }
 
 /**
@@ -84,6 +87,8 @@ export interface RunMigrationsOptions<DB = unknown> {
   db: Kysely<DB>;
   /** Defined migrations from defineMigrations() */
   migrations: DefinedMigrations<DB>;
+  /** Generated deterministic checksums for this migration set. */
+  checksums?: MigrationChecksums;
   /** Name of the tracking table (default: 'sync_migration_state') */
   trackingTable?: string;
   /** What to do when a migration's checksum doesn't match. Default: 'error' */