@syncular/migrations 0.0.6-95 → 0.1.1

package/src/index.ts

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

package/src/naming.ts

@@ -0,0 +1,106 @@
+/**
+ * @syncular/migrations - Migration tracking table naming helpers
+ */
+
+export type MigrationTrackingTableNamePart =
+  | string
+  | number
+  | null
+  | undefined
+  | false;
+
+export interface CreateMigrationTrackingTableNameOptions {
+  /**
+   * Optional namespace prefix placed before the scope segments.
+   * Defaults to `sync`.
+   */
+  namespace?:
+    | MigrationTrackingTableNamePart
+    | readonly MigrationTrackingTableNamePart[];
+  /**
+   * Optional suffix segments appended after `migration_state`.
+   */
+  suffix?:
+    | MigrationTrackingTableNamePart
+    | readonly MigrationTrackingTableNamePart[];
+}
+
+export const DEFAULT_MIGRATION_TRACKING_TABLE = 'sync_migration_state';
+
+function normalizeTrackingTableNamePart(
+  part: MigrationTrackingTableNamePart
+): string | null {
+  if (part === null || part === undefined || part === false) {
+    return null;
+  }
+
+  const normalized = String(part)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .replace(/_+/g, '_');
+
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeTrackingTableNameParts(
+  input:
+    | MigrationTrackingTableNamePart
+    | readonly MigrationTrackingTableNamePart[]
+    | undefined
+): string[] {
+  if (Array.isArray(input)) {
+    return input
+      .map((part) => normalizeTrackingTableNamePart(part))
+      .filter((part): part is string => part !== null);
+  }
+
+  const normalized = normalizeTrackingTableNamePart(
+    input as MigrationTrackingTableNamePart
+  );
+  return normalized ? [normalized] : [];
+}
+
+/**
+ * Create a stable migration tracking table name.
+ *
+ * The generated name always includes the `migration_state` suffix and
+ * normalizes segments to lowercase snake_case.
+ *
+ * @example
+ * createMigrationTrackingTableName()
+ * // => 'sync_migration_state'
+ *
+ * @example
+ * createMigrationTrackingTableName('server')
+ * // => 'sync_server_migration_state'
+ *
+ * @example
+ * createMigrationTrackingTableName(['spaces', 'billing'], {
+ *   suffix: ['prod', 'v2'],
+ * })
+ * // => 'sync_spaces_billing_migration_state_prod_v2'
+ */
+export function createMigrationTrackingTableName(
+  scope?:
+    | MigrationTrackingTableNamePart
+    | readonly MigrationTrackingTableNamePart[],
+  options: CreateMigrationTrackingTableNameOptions = {}
+): string {
+  const namespace =
+    options.namespace === undefined ? ['sync'] : options.namespace;
+  const segments = [
+    ...normalizeTrackingTableNameParts(namespace),
+    ...normalizeTrackingTableNameParts(scope),
+    'migration',
+    'state',
+    ...normalizeTrackingTableNameParts(options.suffix),
+  ];
+
+  if (segments.length === 0) {
+    return DEFAULT_MIGRATION_TRACKING_TABLE;
+  }
+
+  return segments.join('_');
+}

package/src/runner.ts

@@ -2,7 +2,13 @@
  * @syncular/migrations - Migration runner
  */
 
-import { getMigrationChecksum } from './define';
+import {
+  DISABLED_MIGRATION_CHECKSUM,
+  DISABLED_MIGRATION_CHECKSUM_ALGORITHM,
+  getMigrationChecksumAlgorithm,
+  getStoredDeterministicChecksum,
+} from './checksum';
+import { DEFAULT_MIGRATION_TRACKING_TABLE } from './naming';
 import {
   clearAppliedMigrations,
   ensureTrackingTable,
@@ -11,13 +17,15 @@ import {
   removeAppliedMigration,
 } from './tracking';
 import type {
+  DefinedMigrations,
+  MigrationChecksumAlgorithm,
+  ParsedMigration,
   RunMigrationsOptions,
   RunMigrationsResult,
   RunMigrationsToVersionOptions,
   RunMigrationsToVersionResult,
 } from './types';
 
-const DEFAULT_TRACKING_TABLE = 'sync_migration_state';
 const migrationRunQueues = new Map<string, Promise<void>>();
 
 function toErrorMessage(error: unknown): string {
@@ -32,6 +40,39 @@ 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 === '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>
@@ -63,8 +104,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({
@@ -98,7 +145,8 @@ export async function runMigrationsToVersion<DB>(
   options: RunMigrationsToVersionOptions<DB>
 ): Promise<RunMigrationsToVersionResult> {
   const { db, migrations, targetVersion } = options;
-  const trackingTable = options.trackingTable ?? DEFAULT_TRACKING_TABLE;
+  const trackingTable =
+    options.trackingTable ?? DEFAULT_MIGRATION_TRACKING_TABLE;
   const onChecksumMismatch = options.onChecksumMismatch ?? 'error';
   const beforeReset = options.beforeReset;
   if (!Number.isInteger(targetVersion) || targetVersion < 0) {
@@ -126,14 +174,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 getMigrationChecksum(migration) !== 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
@@ -153,8 +215,18 @@ export async function runMigrationsToVersion<DB>(
       if (!existing) {
         continue;
       }
-      const currentChecksum = getMigrationChecksum(migration);
-      if (currentChecksum !== 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}. ` +
@@ -202,10 +274,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);
       }
@@ -221,12 +302,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);
@@ -249,7 +324,7 @@ export async function getSchemaVersion<DB>(
   db: import('kysely').Kysely<DB>,
   trackingTable?: string
 ): Promise<number> {
-  const tableName = trackingTable ?? DEFAULT_TRACKING_TABLE;
+  const tableName = trackingTable ?? DEFAULT_MIGRATION_TRACKING_TABLE;
   const applied = await getAppliedMigrations(db, tableName);
   if (applied.length === 0) return 0;
   return applied[applied.length - 1]!.version;

package/src/tracking.ts

@@ -19,6 +19,7 @@ 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();
 }
 
@@ -32,7 +33,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 +52,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,12 @@ import type { Kysely } from 'kysely';
  */
 export type MigrationFn<DB = unknown> = (db: Kysely<DB>) => Promise<void>;
 
+export type MigrationChecksumMode = 'deterministic' | 'disabled';
+
+export type MigrationChecksumAlgorithm = 'sql_trace_v1' | 'disabled';
+
+export type MigrationChecksums = Record<string, string>;
+
 /**
  * A reversible migration definition.
  */
@@ -16,16 +22,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>;
+  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').
@@ -43,8 +47,10 @@ export interface ParsedMigration<DB = unknown> {
   name: string;
   /** Up migration function. */
   up: MigrationFn<DB>;
-  /** Optional down migration function. */
-  down?: MigrationFn<DB>;
+  /** Down migration function. */
+  down: MigrationFn<DB>;
+  /** Controls whether this migration participates in checksum validation. */
+  checksum: MigrationChecksumMode;
 }
 
 /**
@@ -67,6 +73,7 @@ export interface MigrationStateRow {
   name: string;
   applied_at: string;
   checksum: string;
+  checksum_algorithm: MigrationChecksumAlgorithm;
 }
 
 /**
@@ -77,6 +84,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' */