@beignet/provider-db-drizzle 0.0.9

package/src/mysql/index.ts

@@ -0,0 +1,627 @@
+/**
+ * @beignet/provider-db-drizzle/mysql
+ *
+ * Drizzle ORM MySQL provider, backed by mysql2, that creates a typed
+ * database port. Works with self-hosted MySQL 8.0+ and hosted MySQL services.
+ *
+ * Configuration:
+ * - MYSQL_DB_URL: MySQL connection URL (required), e.g.
+ *   "mysql://user:password@localhost:3306/app"
+ *
+ * @example
+ * ```ts
+ * import * as schema from "@/db/schema";
+ * import { createDrizzleMysqlProvider } from "@beignet/provider-db-drizzle/mysql";
+ *
+ * export const drizzleMysqlProvider = createDrizzleMysqlProvider({ schema });
+ *
+ * // In createNextServer:
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [drizzleMysqlProvider],
+ *   // ...
+ * });
+ *
+ * // In infra:
+ * const todos = createDrizzleTodoRepository(ctx.ports.db.db);
+ * ```
+ */
+
+import type { IdempotencyPort } from "@beignet/core/idempotency";
+import type { OutboxPort } from "@beignet/core/outbox";
+import {
+  type BufferedDomainEventRecorder,
+  createDomainEventRecorder,
+  type EventBusPort,
+  type UnitOfWorkCallback,
+  type UnitOfWorkPort,
+} from "@beignet/core/ports";
+import {
+  createProvider,
+  createProviderInstrumentation,
+} from "@beignet/core/providers";
+import { type ExtractTablesWithRelations, type SQL, sql } from "drizzle-orm";
+import type {
+  MySqlDatabase,
+  MySqlQueryResultHKT,
+  MySqlTransaction,
+  MySqlTransactionConfig,
+  PreparedQueryHKTBase,
+} from "drizzle-orm/mysql-core";
+import { drizzle, type MySql2Database } from "drizzle-orm/mysql2";
+import type { Pool, PoolOptions } from "mysql2/promise";
+import * as mysql from "mysql2/promise";
+import { z } from "zod";
+import {
+  createIdempotencyPortCore,
+  formatIdempotencyMutationErrorMessage,
+  type IdempotencySqlExecutor,
+} from "../shared/idempotency-core.js";
+import { quoteIdentifier } from "../shared/identifiers.js";
+import { createDbQueryLogger } from "../shared/instrumentation.js";
+import {
+  createOutboxPortCore,
+  type OutboxSqlExecutor,
+  type SqlExecutorBase,
+} from "../shared/outbox-core.js";
+
+/**
+ * Typed database port interface.
+ * Exposes a typed Drizzle database instance for your schema.
+ *
+ * @template TSchema - The Drizzle schema type (e.g., `typeof schema`)
+ */
+export interface DbPort<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /**
+   * The typed Drizzle database instance.
+   * Use this to query your database with full type safety.
+   */
+  db: MySql2Database<TSchema>;
+
+  /**
+   * The underlying mysql2 connection pool.
+   * Use this for advanced operations not covered by Drizzle ORM.
+   */
+  pool: Pool;
+}
+
+/**
+ * Drizzle database or transaction client accepted by repository factories.
+ *
+ * `MySqlTransaction` extends `MySqlDatabase`, so both the root database and
+ * transaction clients satisfy this seam.
+ */
+export type DrizzleMysqlDatabase<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+> = MySqlDatabase<MySqlQueryResultHKT, PreparedQueryHKTBase, TSchema>;
+
+/**
+ * Drizzle transaction client passed to Unit of Work repository factories.
+ */
+export type DrizzleMysqlTransaction<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+> = MySqlTransaction<
+  MySqlQueryResultHKT,
+  PreparedQueryHKTBase,
+  TSchema,
+  ExtractTablesWithRelations<TSchema>
+>;
+
+/**
+ * Options for creating a Drizzle MySQL-backed Unit of Work port.
+ */
+export interface DrizzleMysqlUnitOfWorkOptions<
+  TSchema extends Record<string, unknown>,
+  TxPorts,
+> {
+  /**
+   * The root Drizzle database instance from `ctx.ports.db.db`.
+   */
+  db: DrizzleMysqlDatabase<TSchema>;
+
+  /**
+   * Create transaction-scoped ports from the Drizzle transaction client.
+   *
+   * The event recorder is transaction-local. Record domain events inside the
+   * callback and pass `eventBus` to publish them after the database commit.
+   */
+  createTransactionPorts: (
+    db: DrizzleMysqlTransaction<TSchema>,
+    events: BufferedDomainEventRecorder,
+  ) => TxPorts;
+
+  /**
+   * Optional event bus used to flush recorded domain events after commit.
+   */
+  eventBus?: EventBusPort;
+
+  /**
+   * Optional Drizzle transaction configuration.
+   */
+  transactionConfig?: MySqlTransactionConfig;
+}
+
+/**
+ * Create a Unit of Work port backed by Drizzle's MySQL transaction API.
+ *
+ * Beignet does not own your repository interfaces. This helper only
+ * provides the transaction boundary and post-commit event flushing; your app
+ * decides which transaction-scoped ports to create.
+ */
+export function createDrizzleMysqlUnitOfWork<
+  TSchema extends Record<string, unknown>,
+  TxPorts,
+>(
+  options: DrizzleMysqlUnitOfWorkOptions<TSchema, TxPorts>,
+): UnitOfWorkPort<TxPorts> {
+  return {
+    async transaction<Result>(
+      work: UnitOfWorkCallback<TxPorts, Result>,
+    ): Promise<Result> {
+      const events = createDomainEventRecorder();
+
+      const result = await options.db.transaction(async (tx) => {
+        const txPorts = options.createTransactionPorts(
+          tx as DrizzleMysqlTransaction<TSchema>,
+          events,
+        );
+        return work(txPorts);
+      }, options.transactionConfig);
+
+      if (options.eventBus) {
+        await events.flush(options.eventBus);
+      }
+
+      return result;
+    },
+  };
+}
+
+/**
+ * Options for a Drizzle MySQL-backed outbox port.
+ */
+export interface DrizzleMysqlOutboxOptions {
+  /**
+   * Table that stores outbox messages.
+   *
+   * Default: "outbox_messages".
+   */
+  tableName?: string;
+
+  /**
+   * Clock used by tests and deterministic environments.
+   */
+  now?: () => Date;
+}
+
+/**
+ * Read the first element of a drizzle mysql2 `db.execute(...)` result tuple.
+ *
+ * drizzle-orm/mysql2 returns `[rows | ResultSetHeader, fields]`: for selects
+ * element 0 is the row array; for mutations element 0 is a ResultSetHeader.
+ */
+function readResultHead(result: unknown): unknown {
+  return Array.isArray(result) ? result[0] : undefined;
+}
+
+function readResultRows(result: unknown): Record<string, unknown>[] {
+  const head = readResultHead(result);
+  return Array.isArray(head) ? (head as Record<string, unknown>[]) : [];
+}
+
+function readAffectedRows(result: unknown): number | undefined {
+  const head = readResultHead(result);
+  if (head === null || typeof head !== "object" || Array.isArray(head)) {
+    return undefined;
+  }
+  const affectedRows = (head as { affectedRows?: unknown }).affectedRows;
+  return typeof affectedRows === "number" ? affectedRows : undefined;
+}
+
+/**
+ * Detect a MySQL duplicate-key violation (ER_DUP_ENTRY, errno 1062) anywhere
+ * in an error's cause chain — drizzle wraps driver errors in
+ * DrizzleQueryError with the mysql2 error as `cause`.
+ */
+function isDuplicateKeyError(error: unknown): boolean {
+  for (
+    let current = error;
+    current !== null && typeof current === "object";
+    current = (current as { cause?: unknown }).cause
+  ) {
+    const candidate = current as { errno?: unknown; code?: unknown };
+    if (candidate.errno === 1062 || candidate.code === "ER_DUP_ENTRY") {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * MySQL executor implementing both the outbox and idempotency seams of the
+ * shared database cores.
+ */
+interface DrizzleMysqlSqlExecutor
+  extends SqlExecutorBase<DrizzleMysqlSqlExecutor> {
+  claimLockSuffix: SQL;
+  insertPrefix: SQL;
+  insertConflictSuffix: SQL;
+}
+
+function createMysqlExecutor<TSchema extends Record<string, unknown>>(
+  db: DrizzleMysqlDatabase<TSchema>,
+  table: SQL,
+): DrizzleMysqlSqlExecutor {
+  return {
+    table,
+    // MySQL 8.0+ row-locking clause so concurrent claimers skip locked rows.
+    claimLockSuffix: sql.raw(" for update skip locked"),
+    // Duplicate keys surface as ER_DUP_ENTRY caught in run() below — a plain
+    // insert keeps the conflict signal independent of connection flags.
+    // mysql2 enables CLIENT_FOUND_ROWS by default, which makes
+    // `on duplicate key update x = x` report affectedRows 1 instead of 0,
+    // so counting-based duplicate detection silently misreads duplicates as
+    // inserts. Do NOT switch to INSERT IGNORE either: strict mode downgrades
+    // truncation errors to warnings, silently corrupting stored values.
+    insertPrefix: sql.raw("insert into"),
+    insertConflictSuffix: sql.raw(""),
+
+    async rows(query) {
+      return readResultRows(await db.execute(query));
+    },
+
+    async row(query) {
+      return readResultRows(await db.execute(query))[0];
+    },
+
+    async run(query) {
+      // With mysql2's default CLIENT_FOUND_ROWS flag, affectedRows for
+      // UPDATE counts MATCHED rows (without it, CHANGED rows). Every guarded
+      // update issued by the shared cores deterministically changes at least
+      // one column (fresh claim token or status transition), so the count is
+      // identical either way. Keep it that way: a no-op update would make
+      // the two flag modes disagree.
+      //
+      // A duplicate-key violation reports 0 instead of throwing: the only
+      // unique-key inserts the shared cores issue are the idempotency
+      // reserve (where "0 rows" is exactly the conflict fall-through signal)
+      // and outbox enqueues keyed by fresh UUIDs. MySQL does not abort the
+      // surrounding transaction on a statement error, so the reserve's
+      // read-and-classify step still runs inside the same transaction.
+      try {
+        return readAffectedRows(await db.execute(query));
+      } catch (error) {
+        if (isDuplicateKeyError(error)) {
+          return 0;
+        }
+        throw error;
+      }
+    },
+
+    withTransaction(fn) {
+      if ("transaction" in db && typeof db.transaction === "function") {
+        return db.transaction((tx) =>
+          fn(createMysqlExecutor(tx as DrizzleMysqlDatabase<TSchema>, table)),
+        );
+      }
+
+      return undefined;
+    },
+  };
+}
+
+/**
+ * Create idempotent SQL statements for the Drizzle MySQL outbox table.
+ *
+ * Run these during migrations or local setup before using
+ * `createDrizzleMysqlOutboxPort(...)`.
+ *
+ * Indexes are declared inline because MySQL has no
+ * `CREATE INDEX IF NOT EXISTS`; the whole shape stays idempotent under
+ * `CREATE TABLE IF NOT EXISTS`. The binary no-pad collation
+ * `utf8mb4_0900_bin` (MySQL 8.0+) keeps string comparisons case-sensitive
+ * and free of PAD SPACE semantics, which claim tokens and fingerprints
+ * require.
+ */
+export function createDrizzleMysqlOutboxSetupStatements(
+  options: DrizzleMysqlOutboxOptions = {},
+): readonly string[] {
+  const tableName = options.tableName ?? "outbox_messages";
+  const table = quoteIdentifier(tableName, "`");
+  const indexPrefix = tableName.replaceAll(/[^A-Za-z0-9_]/g, "_");
+
+  return [
+    `CREATE TABLE IF NOT EXISTS ${table} (
+      id varchar(255) NOT NULL PRIMARY KEY,
+      kind varchar(32) NOT NULL,
+      name varchar(255) NOT NULL,
+      payload_json longtext NOT NULL,
+      status varchar(32) NOT NULL,
+      attempts int NOT NULL DEFAULT 0,
+      max_attempts int NOT NULL DEFAULT 3,
+      available_at varchar(32) NOT NULL,
+      claimed_at varchar(32),
+      locked_until varchar(32),
+      claim_token varchar(64),
+      delivered_at varchar(32),
+      last_error_json longtext,
+      created_at varchar(32) NOT NULL,
+      updated_at varchar(32) NOT NULL,
+      INDEX ${quoteIdentifier(`${indexPrefix}_available_idx`, "`")} (status, available_at),
+      INDEX ${quoteIdentifier(`${indexPrefix}_locked_idx`, "`")} (status, locked_until)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin`,
+  ];
+}
+
+/**
+ * Create a Beignet outbox port backed by a Drizzle MySQL database.
+ *
+ * Claiming uses a claim-token lease so concurrent workers can safely compete
+ * for eligible messages, combined with `for update skip locked` row locking.
+ */
+export function createDrizzleMysqlOutboxPort<
+  TSchema extends Record<string, unknown>,
+>(
+  db: DrizzleMysqlDatabase<TSchema>,
+  adapterOptions: DrizzleMysqlOutboxOptions = {},
+): OutboxPort {
+  const table = sql.raw(
+    quoteIdentifier(adapterOptions.tableName ?? "outbox_messages", "`"),
+  );
+  const executor: OutboxSqlExecutor = createMysqlExecutor(db, table);
+
+  return createOutboxPortCore(executor, { now: adapterOptions.now });
+}
+
+/**
+ * Options for a Drizzle MySQL-backed idempotency port.
+ */
+export interface DrizzleMysqlIdempotencyOptions {
+  /**
+   * Table that stores idempotency records.
+   *
+   * Default: "idempotency_records".
+   */
+  tableName?: string;
+
+  /**
+   * Clock used by tests and deterministic environments.
+   */
+  now?: () => Date;
+}
+
+/**
+ * Error thrown when `complete(...)` or `fail(...)` does not match an
+ * in-progress idempotency reservation with the provided fingerprint.
+ *
+ * This usually signals a workflow bug: the reservation was never made, was
+ * already completed or released, expired and was cleaned up, or the caller
+ * passed a different fingerprint than the one used to reserve.
+ */
+export class DrizzleMysqlIdempotencyMutationError extends Error {
+  readonly action: "complete" | "fail";
+  readonly namespace: string;
+  readonly key: string;
+  readonly scopeKey: string;
+
+  constructor(args: {
+    action: "complete" | "fail";
+    namespace: string;
+    key: string;
+    scopeKey: string;
+  }) {
+    super(formatIdempotencyMutationErrorMessage(args));
+    this.name = "DrizzleMysqlIdempotencyMutationError";
+    this.action = args.action;
+    this.namespace = args.namespace;
+    this.key = args.key;
+    this.scopeKey = args.scopeKey;
+  }
+}
+
+/**
+ * Create idempotent SQL statements for the Drizzle MySQL idempotency table.
+ *
+ * Run these during migrations or local setup before using
+ * `createDrizzleMysqlIdempotencyPort(...)`.
+ *
+ * Indexes are declared inline because MySQL has no
+ * `CREATE INDEX IF NOT EXISTS`; the whole shape stays idempotent under
+ * `CREATE TABLE IF NOT EXISTS`. The binary no-pad collation
+ * `utf8mb4_0900_bin` (MySQL 8.0+) keeps fingerprint comparisons
+ * case-sensitive — "ABC" and "abc" must classify as conflict, never replay.
+ */
+export function createDrizzleMysqlIdempotencySetupStatements(
+  options: DrizzleMysqlIdempotencyOptions = {},
+): readonly string[] {
+  const tableName = options.tableName ?? "idempotency_records";
+  const table = quoteIdentifier(tableName, "`");
+  const indexPrefix = tableName.replaceAll(/[^A-Za-z0-9_]/g, "_");
+
+  return [
+    `CREATE TABLE IF NOT EXISTS ${table} (
+      storage_key varchar(512) NOT NULL PRIMARY KEY,
+      namespace varchar(255) NOT NULL,
+      idempotency_key varchar(255) NOT NULL,
+      scope_key varchar(255) NOT NULL,
+      fingerprint varchar(255) NOT NULL,
+      status varchar(16) NOT NULL,
+      result_json longtext,
+      reserved_at varchar(32) NOT NULL,
+      completed_at varchar(32),
+      expires_at varchar(32),
+      updated_at varchar(32) NOT NULL,
+      INDEX ${quoteIdentifier(`${indexPrefix}_lookup_idx`, "`")} (namespace, scope_key, idempotency_key),
+      INDEX ${quoteIdentifier(`${indexPrefix}_expires_idx`, "`")} (expires_at)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin`,
+  ];
+}
+
+/**
+ * Create a Beignet idempotency port backed by a Drizzle MySQL database.
+ *
+ * The port accepts both the root Drizzle database and transaction clients, so
+ * applications can expose root idempotency for ordinary retry-safe commands and
+ * transaction-scoped idempotency from Unit of Work.
+ */
+export function createDrizzleMysqlIdempotencyPort<
+  TSchema extends Record<string, unknown>,
+>(
+  db: DrizzleMysqlDatabase<TSchema>,
+  adapterOptions: DrizzleMysqlIdempotencyOptions = {},
+): IdempotencyPort {
+  const table = sql.raw(
+    quoteIdentifier(adapterOptions.tableName ?? "idempotency_records", "`"),
+  );
+  const executor: IdempotencySqlExecutor = createMysqlExecutor(db, table);
+
+  return createIdempotencyPortCore(
+    executor,
+    { now: adapterOptions.now },
+    DrizzleMysqlIdempotencyMutationError,
+  );
+}
+
+/**
+ * Configuration schema for the Drizzle MySQL provider.
+ * Validates environment variables with MYSQL_ prefix.
+ */
+export const MysqlConfigSchema = z.object({
+  /**
+   * MySQL connection URL.
+   * Example: "mysql://user:password@localhost:3306/app"
+   */
+  DB_URL: z
+    .string()
+    .min(1)
+    .refine((val) => val.startsWith("mysql://"), {
+      message:
+        'DB_URL must start with "mysql://" (e.g., "mysql://user:password@localhost:3306/app")',
+    }),
+});
+
+/**
+ * MySQL provider config loaded from `MYSQL_*` env vars.
+ */
+export type MysqlConfig = z.infer<typeof MysqlConfigSchema>;
+
+/**
+ * Options for creating a Drizzle MySQL provider.
+ *
+ * @template TSchema - The Drizzle schema type
+ */
+export interface DrizzleMysqlProviderOptions<
+  TSchema extends Record<string, unknown>,
+  PortName extends string = "db",
+> {
+  /**
+   * The Drizzle schema object (e.g. `import * as schema from '@/db/schema'`).
+   * This schema is used to create a typed Drizzle database instance.
+   */
+  schema: TSchema;
+
+  /**
+   * Optional port name. Defaults to "db".
+   * Renames the contributed port. The provider always reads its connection
+   * from `MYSQL_DB_URL`; for a second database, wire an app-owned provider
+   * with its own env prefix instead.
+   */
+  portName?: PortName;
+
+  /**
+   * Optional mysql2 pool options merged into the pool created from
+   * `MYSQL_DB_URL` (e.g. `connectionLimit`, `timezone`, TLS settings).
+   */
+  pool?: Omit<PoolOptions, "uri">;
+
+  /**
+   * Drizzle relational-query mode. Use "planetscale" when connecting to
+   * PlanetScale; defaults to "default".
+   */
+  mode?: "default" | "planetscale";
+}
+
+/**
+ * Create a Drizzle MySQL provider factory.
+ *
+ * This factory creates a service provider that:
+ * - Uses a mysql2/promise connection pool
+ * - Uses Drizzle ORM via drizzle-orm/mysql2
+ * - Exposes a typed DbPort<TSchema> on ports
+ * - Uses MYSQL_-prefixed env vars for connection config
+ *
+ * @template TSchema - The Drizzle schema type (inferred from the schema parameter)
+ * @param options - Configuration options including the schema
+ * @returns A service provider that can be used with createNextServer
+ *
+ * @example
+ * ```ts
+ * import * as schema from "@/db/schema";
+ * import { createDrizzleMysqlProvider } from "@beignet/provider-db-drizzle/mysql";
+ *
+ * export const drizzleMysqlProvider = createDrizzleMysqlProvider({ schema });
+ * ```
+ */
+export function createDrizzleMysqlProvider<
+  TSchema extends Record<string, unknown>,
+  PortName extends string = "db",
+>(options: DrizzleMysqlProviderOptions<TSchema, PortName>) {
+  const { schema, portName = "db", mode = "default" } = options;
+
+  return createProvider({
+    name: "drizzle-mysql",
+
+    config: {
+      schema: MysqlConfigSchema,
+      envPrefix: "MYSQL_",
+    },
+
+    async setup({ ports, config }) {
+      if (!config) {
+        throw new Error(
+          "[drizzleMysqlProvider] Missing config. Set MYSQL_DB_URL.",
+        );
+      }
+
+      // 1. Create mysql2 connection pool
+      const pool: Pool = mysql.createPool({
+        uri: config.DB_URL,
+        ...options.pool,
+      });
+
+      const instrumentation = createProviderInstrumentation(ports, {
+        providerName: "drizzle-mysql",
+        watcher: "db",
+      });
+
+      const logger = createDbQueryLogger(instrumentation, portName);
+
+      // 2. Create typed Drizzle instance (mode is required when a schema is
+      //    provided to drizzle-orm/mysql2)
+      const db: MySql2Database<TSchema> = logger
+        ? drizzle(pool, { schema, logger, mode })
+        : drizzle(pool, { schema, mode });
+
+      // 3. Build a typed DbPort
+      const dbPort: DbPort<TSchema> = { db, pool };
+
+      return {
+        ports: { [portName]: dbPort } as Record<PortName, DbPort<TSchema>>,
+        async stop() {
+          // Gracefully close the database connection pool
+          try {
+            await dbPort.pool.end();
+          } catch (error) {
+            // Log error but don't throw - we're shutting down anyway
+            console.error(
+              "[drizzleMysqlProvider] Error closing database connection:",
+              error,
+            );
+          }
+        },
+      };
+    },
+  });
+}