sailfork / t3code-github / .repos/ alchemy-effect/ packages/ better-auth/ src/ Migrate.ts

import { Action, Stack, type Output } from "alchemy";
import { CurrentRuntimeContext, sanitizeKey } from "alchemy/RuntimeContext";
import { sha256Object } from "alchemy/Util/sha256";
import type { BetterAuthOptions } from "better-auth";
import { getSchema } from "better-auth/db";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import type { DatabaseService } from "./Database.ts";
import { BetterAuthMigrationError } from "./Errors.ts";

/**
 * Deploy-time migration machinery.
 *
 * This module is ONLY imported dynamically from inside
 * `if (!globalThis.__ALCHEMY_RUNTIME__)` in `BetterAuth.ts`, so none of it
 * (including `better-auth/db` and the Kysely-based migration engine pulled
 * in by `better-auth/db/migration`) ever reaches a deployed runtime bundle.
 *
 * @internal
 */

interface MigrateInput {
  /** Non-secret identity of the target database (from the platform layer). */
  identity: Record<string, unknown>;
  /** Fingerprint of the Better Auth schema (tables + fields). */
  schema: string;
  /** Dialect family — part of the input so a dialect swap re-runs. */
  provider: string;
}

export interface MigrateOutput {
  tablesCreated: number;
  tablesAltered: number;
  indexesCreated: number;
}

export interface RegisterMigrationOptions {
  readonly id: string;
  /** The user's Better Auth options (without `database`). */
  readonly options: BetterAuthOptions;
  readonly db: DatabaseService;
  /** The user's `migrate` prop — `undefined` means default-on. */
  readonly migrate: boolean | undefined;
}

/**
 * Register the schema-migration Action for a `BetterAuth` instance.
 *
 * Actions run only during `alchemy deploy` (apply), re-run only when their
 * resolved input changes — here: the schema fingerprint, the database
 * identity, or the dialect — and their body gets the ambient stack
 * services, so `migrate.connect` can resolve resource Outputs and reach
 * the cloud.
 */
export const registerMigration = ({
  id,
  options,
  db,
  migrate,
}: RegisterMigrationOptions): Effect.Effect<void> =>
  Effect.gen(function* () {
    const support = db.migrate;
    if (support === undefined) {
      if (migrate === true) {
        return yield* Effect.die(
          new Error(
            `BetterAuth(${id}): \`migrate: true\` was requested, but the ` +
              `"${db.provider}" Database layer does not support automatic ` +
              "migrations. Remove `migrate: true` (and manage the schema " +
              "yourself, e.g. via `npx auth@1.7.5 generate`) or use a " +
              "layer with migration support.",
          ),
        );
      }
      return;
    }
    if (migrate === false) {
      return;
    }
    // Outside a stack evaluation (unit tests driving BetterAuth directly)
    // there is nothing to register on — skip silently.
    const stack = yield* Effect.serviceOption(Stack);
    if (Option.isNone(stack)) {
      return;
    }

    // Init-effect form: `support.connect`'s outer half runs here under the
    // Action's capture context, so resource Outputs it yields (databaseId,
    // connection-string attrs) become dependency captures resolved at
    // apply. The returned runner does the actual connect + migrate.
    const Migrate = Action(
      "BetterAuth.Migrate",
      Effect.gen(function* () {
        const acquire = yield* support.connect;
        return (_input: MigrateInput) => runMigrationWith(acquire, options);
      }),
    );
    const result = yield* Migrate(`${id}Migrate`, {
      identity: support.identity,
      schema: yield* schemaFingerprint(options),
      provider: db.provider,
    }).pipe(
      // The Action call's requirements (Stack, the runner's Req) are
      // ambient during stack evaluation — erase them; presence of Stack
      // was checked above.
      (effect) => effect as unknown as Effect.Effect<Output<MigrateOutput>>,
    );

    // Bind the migration result into the host environment (when there is a
    // host): the host's env then depends on the Action's output, giving the
    // engine a Worker/Function → Migration dependency edge so first-deploy
    // traffic cannot race the schema.
    const rc = yield* CurrentRuntimeContext;
    if (rc !== undefined) {
      yield* rc.set(sanitizeKey(`${id}Migration`), result as never);
    }
  }) as Effect.Effect<void>;

/**
 * Connect via the platform layer's `migrate.connect` and apply Better
 * Auth's schema migrations. Additive and idempotent — re-running against
 * an up-to-date database is a no-op.
 */
export const applyMigrations = (
  support: NonNullable<DatabaseService["migrate"]>,
  options: BetterAuthOptions,
) => Effect.flatMap(support.connect, (acquire) => runMigrationWith(acquire, options));

const runMigrationWith = (
  acquire: Effect.Effect<
    import("./Database.ts").DirectDatabase,
    BetterAuthMigrationError,
    import("effect/Scope").Scope
  >,
  options: BetterAuthOptions,
) =>
  Effect.scoped(
    Effect.gen(function* () {
      const database = yield* acquire;
      if (typeof database === "function") {
        return yield* Effect.die(
          new Error(
            "BetterAuth migration: `connect` yielded an adapter factory — " +
              "migrations require a direct (Kysely-resolvable) database.",
          ),
        );
      }
      const { getMigrations, UnsafeMigrationError } = yield* Effect.promise(
        () => import("better-auth/db/migration"),
      );
      const migrations = yield* Effect.tryPromise({
        try: () =>
          getMigrations({
            ...options,
            database,
            // getMigrations only introspects the schema; the secret is
            // irrelevant but required by the options type.
            secret: "alchemy-migrate",
            telemetry: { enabled: false },
          }),
        catch: (cause) =>
          new BetterAuthMigrationError({
            message:
              cause instanceof UnsafeMigrationError
                ? cause.message
                : "Failed to compute Better Auth schema migrations",
            cause,
          }),
      });
      yield* Effect.tryPromise({
        try: () => migrations.runMigrations(),
        catch: (cause) =>
          new BetterAuthMigrationError({
            message: "Failed to apply Better Auth schema migrations",
            cause,
          }),
      });
      return {
        tablesCreated: migrations.toBeCreated.length,
        tablesAltered: migrations.toBeAdded.length,
        indexesCreated: migrations.toBeAddedIndexes.length,
      } satisfies MigrateOutput;
    }),
  );

/**
 * Stable fingerprint of the Better Auth schema derived from the user's
 * options (plugins, additionalFields, model renames, table indexes).
 * Changing the schema changes the fingerprint, which changes the
 * migration Action's input and re-runs it on the next deploy.
 */
export const schemaFingerprint = (options: BetterAuthOptions): Effect.Effect<string> =>
  Effect.suspend(() => {
    const schema = getSchema(options);
    // Reduce to the migration-relevant field and index attributes;
    // sha256Object's stable serialization handles key ordering.
    const reduced = Object.fromEntries(
      Object.entries(schema).map(([table, def]) => [
        table,
        {
          fields: Object.fromEntries(
            Object.entries(def.fields).map(([name, field]) => [
              name,
              {
                type: String(field.type),
                required: field.required ?? false,
                unique: field.unique ?? false,
                index: field.index ?? false,
                fieldName: field.fieldName,
                references: field.references
                  ? {
                      model: field.references.model,
                      field: field.references.field,
                    }
                  : undefined,
              },
            ]),
          ),
          indexes: (def.indexes ?? []).map((index) => ({
            name: index.name,
            unique: index.unique ?? false,
            columns: [...index.columns],
          })),
        },
      ]),
    );
    return sha256Object(reduced);
  });