sailfork / t3code-github / .repos/ alchemy-effect/ packages/ sql/ src/ Migrations/ Registry.ts

import { recordsEqual } from "alchemy/Util/equal";
import * as Effect from "effect/Effect";
import type * as FileSystem from "effect/FileSystem";
import type * as Path from "effect/Path";
import { hashMigrations } from "../SqlFile.ts";
import { ALCHEMY_DEFAULT_TABLE, applyAlchemyFormat } from "./AlchemyFormat.ts";
import {
  MigrationError,
  type DrizzleV0LayoutError,
  type MigrationApplyError,
  type SqlExecutor,
} from "./Format.ts";
import { readMigrationRecords } from "./Records.ts";

/**
 * The migrations input surface shared by every SQL database resource.
 * A plain string is a directory; the object form overrides the
 * applied-migrations table name. A `Drizzle.Schema` resource's attributes
 * satisfy the `{ out }` shape structurally, so `migrations: schema` works
 * without importing the Drizzle module.
 *
 * There is exactly ONE bookkeeping format — Alchemy's `__alchemy_migrations`
 * table. A database previously migrated with drizzle-kit, Prisma, or
 * wrangler is adopted by a one-way conversion: the foreign table's history
 * is copied into Alchemy's table once and the foreign table is left frozen
 * (never written, never dropped). From then on Alchemy's table is the only
 * bookkeeping.
 */
export type MigrationsInput =
  | string
  | {
      /** Directory containing the migration files. */
      dir: string;
      /** Override the applied-migrations table name. */
      table?: string;
    }
  | {
      /** A `Drizzle.Schema`-shaped resource output. */
      out: string;
    };

export interface NormalizedMigrationsInput {
  dir: string;
  table?: string;
}

export const normalizeMigrationsInput = (input: MigrationsInput): NormalizedMigrationsInput => {
  if (typeof input === "string") return { dir: input };
  if ("out" in input) return { dir: input.out };
  return input;
};

/**
 * Normalize a resource's `migrations` prop into the registry input shape.
 * Shared by every SQL database resource.
 */
export const migrationsInputOf = (props: {
  migrations?: MigrationsInput;
}): NormalizedMigrationsInput | undefined =>
  props.migrations ? normalizeMigrationsInput(props.migrations) : undefined;

/**
 * What prior state remembers about migrations — the bookkeeping table a
 * previous deploy used. Rows written by pre-registry Alchemy persisted
 * their table name (`d1_migrations`, `neon_migrations`, custom names), and
 * honoring it keeps them converging against the same table (upgraded in
 * place to the current column shape) instead of starting a new one.
 */
export interface StampedMigrationsState {
  table?: string | undefined;
}

export const stampedOf = (
  output: { migrationsTable: string | undefined } | undefined,
): StampedMigrationsState => ({ table: output?.migrationsTable });

export interface ResolvedMigrations {
  dir: string;
  table: string;
}

/**
 * Resolve where this deploy's bookkeeping lives. Precedence: explicit
 * `table` on the input, then the table persisted by a prior deploy, then
 * the default `__alchemy_migrations`.
 */
export const resolveMigrations = (options: {
  input: NormalizedMigrationsInput;
  stamped: StampedMigrationsState;
}): ResolvedMigrations => ({
  dir: options.input.dir,
  table: options.input.table ?? options.stamped.table ?? ALCHEMY_DEFAULT_TABLE,
});

/**
 * Apply pending migrations. The directory layout only selects how records
 * are read and keyed (drizzle-kit/Prisma dirs by directory name, flat dirs
 * by file path) — the bookkeeping is always Alchemy's table, converting
 * foreign or legacy history on first contact (see `AlchemyFormat.ts`).
 */
export const applyMigrations = (options: {
  resolved: ResolvedMigrations;
  executor: SqlExecutor;
}): Effect.Effect<
  void,
  MigrationApplyError | DrizzleV0LayoutError,
  FileSystem.FileSystem | Path.Path
> =>
  Effect.gen(function* () {
    const { resolved, executor } = options;
    const records = yield* readMigrationRecords(resolved.dir);
    yield* applyAlchemyFormat({
      executor,
      table: resolved.table,
      records,
    });
  });

const hashMigrationsDir = (dir: string) =>
  hashMigrations(dir).pipe(
    Effect.mapError(
      (cause) =>
        new MigrationError({
          message: `Failed to read migrations from ${dir}: ${String(cause)}`,
          cause,
        }),
    ),
  );

/** The result of one migration sync, ready to stamp into attributes. */
export interface MigrationRun {
  resolved: ResolvedMigrations;
  hashes: Record<string, string>;
}

/**
 * The whole per-deploy migration pipeline: hash the directory (for state
 * drift tracking), resolve the bookkeeping table, and — when the directory
 * is non-empty — apply pending migrations. The database provider supplies
 * only `withExecutor`, a bracket that acquires its target's
 * {@link SqlExecutor} (a D1 HTTP handle, a pg client over a Neon URI or
 * PlanetScale temp role, a mysql2 connection) around the apply.
 */
export const runMigrations = <E, R>(options: {
  input: NormalizedMigrationsInput;
  stamped: StampedMigrationsState;
  withExecutor: (
    apply: (
      executor: SqlExecutor,
    ) => Effect.Effect<
      void,
      MigrationApplyError | DrizzleV0LayoutError,
      FileSystem.FileSystem | Path.Path
    >,
  ) => Effect.Effect<void, E, R>;
}): Effect.Effect<MigrationRun, MigrationError | E, R | FileSystem.FileSystem | Path.Path> =>
  Effect.gen(function* () {
    const hashes = yield* hashMigrationsDir(options.input.dir);
    const resolved = resolveMigrations(options);
    if (Object.keys(hashes).length > 0) {
      yield* options.withExecutor((executor) => applyMigrations({ resolved, executor }));
    }
    return { resolved, hashes };
  });

/**
 * Prior migration files whose contents changed or that disappeared from
 * the directory, relative to the hashes persisted on the last deploy.
 * Additive files (new names) are not rewritten history.
 */
export const rewrittenMigrationHistory = (
  previous: Record<string, string> | undefined,
  next: Record<string, string>,
): { changed: string[]; removed: string[] } | undefined => {
  if (previous === undefined) return undefined;
  const changed: string[] = [];
  const removed: string[] = [];
  for (const name of Object.keys(previous)) {
    const hash = next[name];
    if (hash === undefined) removed.push(name);
    else if (hash !== previous[name]) changed.push(name);
  }
  changed.sort();
  removed.sort();
  if (changed.length === 0 && removed.length === 0) return undefined;
  return { changed, removed };
};

export type MigrationHistoryChange =
  | { readonly kind: "none" }
  | { readonly kind: "pending" }
  | {
      readonly kind: "rewritten";
      readonly changed: ReadonlyArray<string>;
      readonly removed: ReadonlyArray<string>;
    };

/**
 * Classify the migration half of a provider `diff`:
 * - `none` — hashes and bookkeeping table are unchanged
 * - `pending` — new files and/or a table rename; apply in place
 * - `rewritten` — an already-applied file was edited or removed
 */
export const classifyMigrationHistory = (options: {
  news: { migrations?: MigrationsInput };
  output:
    | {
        migrationsTable: string | undefined;
        migrationsHashes: Record<string, string>;
      }
    | undefined;
}): Effect.Effect<MigrationHistoryChange, MigrationError, FileSystem.FileSystem | Path.Path> =>
  Effect.gen(function* () {
    const input = migrationsInputOf(options.news);
    if (!input) return { kind: "none" } as const;
    const newHashes = yield* hashMigrationsDir(input.dir);
    const rewritten = rewrittenMigrationHistory(options.output?.migrationsHashes, newHashes);
    if (rewritten) {
      return { kind: "rewritten", ...rewritten } as const;
    }
    if (!recordsEqual(newHashes, options.output?.migrationsHashes ?? {})) {
      return { kind: "pending" } as const;
    }
    const resolved = resolveMigrations({
      input,
      stamped: stampedOf(options.output),
    });
    return resolved.table !== (options.output?.migrationsTable ?? resolved.table)
      ? ({ kind: "pending" } as const)
      : ({ kind: "none" } as const);
  });

/**
 * The shared migration half of a provider `diff`: true when pending file
 * changes, rewritten history, or a bookkeeping-table move require an
 * action. Callers that can replace (PlanetScale development branches)
 * should consult {@link classifyMigrationHistory} instead of this boolean.
 */
export const diffMigrations = (options: {
  news: { migrations?: MigrationsInput };
  output:
    | {
        migrationsTable: string | undefined;
        migrationsHashes: Record<string, string>;
      }
    | undefined;
}): Effect.Effect<boolean, MigrationError, FileSystem.FileSystem | Path.Path> =>
  classifyMigrationHistory(options).pipe(Effect.map((change) => change.kind !== "none"));

/** The attributes every SQL database resource with `migrations` exposes. */
export interface MigrationAttributes {
  /** Directory of the applied SQL migrations. */
  migrationsDir: string | undefined;
  /** Migration bookkeeping table. */
  migrationsTable: string | undefined;
  /** Applied migration content hashes. */
  migrationsHashes: Record<string, string>;
}

/**
 * Carry migration attributes from prior state (`read`, `list`), defaulting
 * to none recorded.
 */
export const migrationAttributesOf = (
  prior: Partial<MigrationAttributes> | undefined,
): MigrationAttributes => ({
  migrationsDir: prior?.migrationsDir,
  migrationsTable: prior?.migrationsTable,
  migrationsHashes: prior?.migrationsHashes ?? {},
});

/**
 * The migration attributes every SQL database resource persists, threaded
 * uniformly: the run's results when migrations ran, otherwise the prior
 * state (so removing `migrations` keeps the stamp and hashes for a later
 * re-add).
 */
export const migrationsAttrs = (options: {
  input: NormalizedMigrationsInput | undefined;
  run: MigrationRun | undefined;
  output:
    | {
        migrationsTable: string | undefined;
        migrationsHashes: Record<string, string>;
      }
    | undefined;
}): MigrationAttributes => ({
  migrationsDir: options.input?.dir,
  migrationsTable: options.run?.resolved.table ?? options.output?.migrationsTable,
  migrationsHashes: options.run?.hashes ?? options.output?.migrationsHashes ?? {},
});