@beignet/provider-db-drizzle 0.0.21 → 0.0.23

package/src/mysql/index.ts

@@ -30,6 +30,7 @@
 import type { IdempotencyPort } from "@beignet/core/idempotency";
 import type { OutboxPort } from "@beignet/core/outbox";
 import {
+  type AuditLogPort,
   type BufferedDomainEventRecorder,
   createDomainEventRecorder,
   type EventBusPort,
@@ -52,6 +53,12 @@ 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 {
+  createAuditLogInsertQuery,
+  createAuditLogSqlRow,
+  type DrizzleAuditLogCoreOptions,
+} from "../shared/audit-core.js";
+import { type DbHealth, dbHealthError, dbHealthOk } from "../shared/health.js";
 import {
   createIdempotencyPortCore,
   formatIdempotencyMutationErrorMessage,
@@ -92,8 +99,18 @@ export interface DbPort<
    * Use this for advanced operations not covered by Drizzle ORM.
    */
   pool: Pool;
+
+  /**
+   * Check whether the underlying database pool can run a cheap read query.
+   *
+   * Intended for app-owned readiness endpoints. This does not run migrations
+   * or mutate schema.
+   */
+  checkHealth(): Promise<DbHealth>;
 }
 
+export type { DbHealth };
+
 /**
  * Drizzle database or transaction client accepted by repository factories.
  *
@@ -116,6 +133,15 @@ export type DrizzleMysqlTransaction<
   ExtractTablesWithRelations<TSchema>
 >;
 
+async function checkMysqlHealth(pool: Pool): Promise<DbHealth> {
+  try {
+    await pool.query("select 1");
+    return dbHealthOk("mysql");
+  } catch (error) {
+    return dbHealthError("mysql", error);
+  }
+}
+
 /**
  * Options for creating a Drizzle MySQL-backed Unit of Work port.
  */
@@ -186,6 +212,19 @@ export function createDrizzleMysqlUnitOfWork<
   };
 }
 
+/**
+ * Options for a Drizzle MySQL-backed audit log port.
+ */
+export interface DrizzleMysqlAuditLogOptions
+  extends DrizzleAuditLogCoreOptions {
+  /**
+   * Table that stores audit log entries.
+   *
+   * Default: "audit_log".
+   */
+  tableName?: string;
+}
+
 /**
  * Options for a Drizzle MySQL-backed outbox port.
  */
@@ -319,6 +358,82 @@ function createMysqlExecutor<TSchema extends Record<string, unknown>>(
   };
 }
 
+/**
+ * Create idempotent SQL statements for the Drizzle MySQL audit log table.
+ *
+ * Run these during migrations or local setup before using
+ * `createDrizzleMysqlAuditLogPort(...)`.
+ *
+ * Indexes are declared inline because MySQL has no
+ * `CREATE INDEX IF NOT EXISTS`; the whole shape stays idempotent under
+ * `CREATE TABLE IF NOT EXISTS`.
+ */
+export function createDrizzleMysqlAuditLogSetupStatements(
+  options: DrizzleMysqlAuditLogOptions = {},
+): readonly string[] {
+  const tableName = options.tableName ?? "audit_log";
+  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,
+      action varchar(255) NOT NULL,
+      actor_type varchar(32) NOT NULL,
+      actor_id varchar(255),
+      actor_display_name varchar(255),
+      tenant_id varchar(255),
+      tenant_slug varchar(255),
+      resource_type varchar(255),
+      resource_id varchar(255),
+      resource_name varchar(255),
+      outcome varchar(16) NOT NULL DEFAULT 'success',
+      request_id varchar(255),
+      trace_id varchar(255),
+      message longtext,
+      metadata longtext,
+      actor_metadata longtext,
+      tenant_metadata longtext,
+      resource_metadata longtext,
+      occurred_at varchar(32) NOT NULL,
+      INDEX ${quoteIdentifier(`${indexPrefix}_action_idx`, "`")} (action),
+      INDEX ${quoteIdentifier(`${indexPrefix}_actor_idx`, "`")} (actor_type, actor_id),
+      INDEX ${quoteIdentifier(`${indexPrefix}_occurred_at_idx`, "`")} (occurred_at),
+      INDEX ${quoteIdentifier(`${indexPrefix}_request_idx`, "`")} (request_id),
+      INDEX ${quoteIdentifier(`${indexPrefix}_resource_idx`, "`")} (resource_type, resource_id),
+      INDEX ${quoteIdentifier(`${indexPrefix}_tenant_idx`, "`")} (tenant_id)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin`,
+  ];
+}
+
+/**
+ * Create a Beignet audit log port backed by a Drizzle MySQL database.
+ *
+ * The port accepts both the root Drizzle database and transaction clients, so
+ * applications can rebuild audit logging inside Unit of Work transaction ports.
+ */
+export function createDrizzleMysqlAuditLogPort<
+  TSchema extends Record<string, unknown>,
+>(
+  db: DrizzleMysqlDatabase<TSchema>,
+  adapterOptions: DrizzleMysqlAuditLogOptions = {},
+): AuditLogPort {
+  const table = sql.raw(
+    quoteIdentifier(adapterOptions.tableName ?? "audit_log", "`"),
+  );
+
+  return {
+    async record(input) {
+      await db.execute(
+        createAuditLogInsertQuery(
+          table,
+          createAuditLogSqlRow(input, adapterOptions),
+        ),
+      );
+    },
+  };
+}
+
 /**
  * Create idempotent SQL statements for the Drizzle MySQL outbox table.
  *
@@ -612,7 +727,12 @@ export function createDrizzleMysqlProvider<
         : drizzle(pool, { schema, mode });
 
       // 3. Build a typed DbPort
-      const dbPort: DbPort<TSchema> = { drizzle: db, db, pool };
+      const dbPort: DbPort<TSchema> = {
+        drizzle: db,
+        db,
+        pool,
+        checkHealth: () => checkMysqlHealth(pool),
+      };
 
       return {
         ports: { [portName]: dbPort } as Record<PortName, DbPort<TSchema>>,

package/src/postgres/index.ts

@@ -30,6 +30,7 @@
 import type { IdempotencyPort } from "@beignet/core/idempotency";
 import type { OutboxPort } from "@beignet/core/outbox";
 import {
+  type AuditLogPort,
   type BufferedDomainEventRecorder,
   createDomainEventRecorder,
   type EventBusPort,
@@ -50,6 +51,12 @@ import {
 } from "drizzle-orm/pg-core";
 import pg, { type Pool, type PoolConfig } from "pg";
 import { z } from "zod";
+import {
+  createAuditLogInsertQuery,
+  createAuditLogSqlRow,
+  type DrizzleAuditLogCoreOptions,
+} from "../shared/audit-core.js";
+import { type DbHealth, dbHealthError, dbHealthOk } from "../shared/health.js";
 import {
   createIdempotencyPortCore,
   formatIdempotencyMutationErrorMessage,
@@ -90,8 +97,18 @@ export interface DbPort<
    * Use this for advanced operations not covered by Drizzle ORM.
    */
   pool: Pool;
+
+  /**
+   * Check whether the underlying database pool can run a cheap read query.
+   *
+   * Intended for app-owned readiness endpoints. This does not run migrations
+   * or mutate schema.
+   */
+  checkHealth(): Promise<DbHealth>;
 }
 
+export type { DbHealth };
+
 /**
  * Drizzle database or transaction client accepted by repository factories.
  *
@@ -114,6 +131,15 @@ export type DrizzlePostgresTransaction<
   ExtractTablesWithRelations<TSchema>
 >;
 
+async function checkPostgresHealth(pool: Pool): Promise<DbHealth> {
+  try {
+    await pool.query("select 1");
+    return dbHealthOk("postgres");
+  } catch (error) {
+    return dbHealthError("postgres", error);
+  }
+}
+
 /**
  * Options for creating a Drizzle Postgres-backed Unit of Work port.
  */
@@ -181,6 +207,91 @@ export function createDrizzlePostgresUnitOfWork<
   };
 }
 
+/**
+ * Options for a Drizzle Postgres-backed audit log port.
+ */
+export interface DrizzlePostgresAuditLogOptions
+  extends DrizzleAuditLogCoreOptions {
+  /**
+   * Table that stores audit log entries.
+   *
+   * Default: "audit_log".
+   */
+  tableName?: string;
+}
+
+/**
+ * Create idempotent SQL statements for the Drizzle Postgres audit log table.
+ *
+ * Run these during migrations or local setup before using
+ * `createDrizzlePostgresAuditLogPort(...)`.
+ */
+export function createDrizzlePostgresAuditLogSetupStatements(
+  options: DrizzlePostgresAuditLogOptions = {},
+): readonly string[] {
+  const tableName = options.tableName ?? "audit_log";
+  const table = quoteIdentifier(tableName, '"');
+  const indexPrefix = tableName.replaceAll(/[^A-Za-z0-9_]/g, "_");
+
+  return [
+    `CREATE TABLE IF NOT EXISTS ${table} (
+      id text PRIMARY KEY NOT NULL,
+      action text NOT NULL,
+      actor_type text NOT NULL,
+      actor_id text,
+      actor_display_name text,
+      tenant_id text,
+      tenant_slug text,
+      resource_type text,
+      resource_id text,
+      resource_name text,
+      outcome text DEFAULT 'success' NOT NULL,
+      request_id text,
+      trace_id text,
+      message text,
+      metadata text,
+      actor_metadata text,
+      tenant_metadata text,
+      resource_metadata text,
+      occurred_at text NOT NULL
+    )`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_action_idx`, '"')} ON ${table} (action)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_actor_idx`, '"')} ON ${table} (actor_type, actor_id)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_occurred_at_idx`, '"')} ON ${table} (occurred_at)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_request_idx`, '"')} ON ${table} (request_id)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_resource_idx`, '"')} ON ${table} (resource_type, resource_id)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_tenant_idx`, '"')} ON ${table} (tenant_id)`,
+  ];
+}
+
+/**
+ * Create a Beignet audit log port backed by a Drizzle Postgres database.
+ *
+ * The port accepts both the root Drizzle database and transaction clients, so
+ * applications can rebuild audit logging inside Unit of Work transaction ports.
+ */
+export function createDrizzlePostgresAuditLogPort<
+  TSchema extends Record<string, unknown>,
+>(
+  db: DrizzlePostgresDatabase<TSchema>,
+  adapterOptions: DrizzlePostgresAuditLogOptions = {},
+): AuditLogPort {
+  const table = sql.raw(
+    quoteIdentifier(adapterOptions.tableName ?? "audit_log", '"'),
+  );
+
+  return {
+    async record(input) {
+      await db.execute(
+        createAuditLogInsertQuery(
+          table,
+          createAuditLogSqlRow(input, adapterOptions),
+        ),
+      );
+    },
+  };
+}
+
 /**
  * Options for a Drizzle Postgres-backed outbox port.
  */
@@ -557,7 +668,12 @@ export function createDrizzlePostgresProvider<
         : drizzle(pool, { schema });
 
       // 3. Build a typed DbPort
-      const dbPort: DbPort<TSchema> = { drizzle: db, db, pool };
+      const dbPort: DbPort<TSchema> = {
+        drizzle: db,
+        db,
+        pool,
+        checkHealth: () => checkPostgresHealth(pool),
+      };
 
       return {
         ports: { [portName]: dbPort } as Record<PortName, DbPort<TSchema>>,

package/src/shared/audit-core.ts

@@ -0,0 +1,134 @@
+import {
+  type ActivityActorType,
+  type AuditLogEntry,
+  type AuditLogEntryInput,
+  type AuditLogOptions,
+  normalizeAuditLogEntry,
+  redactAuditLogEntry,
+} from "@beignet/core/ports";
+import { type SQL, sql } from "drizzle-orm";
+
+export interface DrizzleAuditLogCoreOptions extends AuditLogOptions {
+  /**
+   * Optional ID factory for deterministic tests or runtimes without
+   * `globalThis.crypto.randomUUID()`.
+   */
+  createId?: () => string;
+}
+
+export type AuditLogSqlRow = {
+  id: string;
+  action: string;
+  actorType: ActivityActorType;
+  actorId: string | null;
+  actorDisplayName: string | null;
+  tenantId: string | null;
+  tenantSlug: string | null;
+  resourceType: string | null;
+  resourceId: string | null;
+  resourceName: string | null;
+  outcome: AuditLogEntry["outcome"];
+  requestId: string | null;
+  traceId: string | null;
+  message: string | null;
+  metadata: string | null;
+  actorMetadata: string | null;
+  tenantMetadata: string | null;
+  resourceMetadata: string | null;
+  occurredAt: string;
+};
+
+function defaultCreateAuditLogId(): string {
+  if (typeof globalThis.crypto?.randomUUID !== "function") {
+    throw new Error(
+      "Drizzle audit log adapters require globalThis.crypto.randomUUID(). Pass createId when this runtime does not provide it.",
+    );
+  }
+  return globalThis.crypto.randomUUID();
+}
+
+function serialize(value: unknown): string | null {
+  return value === undefined ? null : JSON.stringify(value);
+}
+
+export function createAuditLogSqlRow(
+  input: AuditLogEntryInput,
+  options: DrizzleAuditLogCoreOptions = {},
+): AuditLogSqlRow {
+  const normalized = normalizeAuditLogEntry(input);
+  const entry = options.redact
+    ? options.redact(redactAuditLogEntry(normalized))
+    : redactAuditLogEntry(normalized);
+  const createId = options.createId ?? defaultCreateAuditLogId;
+
+  return {
+    id: createId(),
+    action: entry.action,
+    actorType: entry.actor.type,
+    actorId: entry.actor.id ?? null,
+    actorDisplayName: entry.actor.displayName ?? null,
+    tenantId: entry.tenant?.id ?? null,
+    tenantSlug: entry.tenant?.slug ?? null,
+    resourceType: entry.resource?.type ?? null,
+    resourceId: entry.resource?.id ?? null,
+    resourceName: entry.resource?.name ?? null,
+    outcome: entry.outcome,
+    requestId: entry.requestId ?? null,
+    traceId: entry.traceId ?? null,
+    message: entry.message ?? null,
+    metadata: serialize(entry.metadata),
+    actorMetadata: serialize(entry.actor.metadata),
+    tenantMetadata: serialize(entry.tenant?.metadata),
+    resourceMetadata: serialize(entry.resource?.metadata),
+    occurredAt: entry.occurredAt.toISOString(),
+  };
+}
+
+export function createAuditLogInsertQuery(
+  table: SQL,
+  row: AuditLogSqlRow,
+): SQL {
+  return sql`
+    insert into ${table} (
+      id,
+      action,
+      actor_type,
+      actor_id,
+      actor_display_name,
+      tenant_id,
+      tenant_slug,
+      resource_type,
+      resource_id,
+      resource_name,
+      outcome,
+      request_id,
+      trace_id,
+      message,
+      metadata,
+      actor_metadata,
+      tenant_metadata,
+      resource_metadata,
+      occurred_at
+    ) values (
+      ${row.id},
+      ${row.action},
+      ${row.actorType},
+      ${row.actorId},
+      ${row.actorDisplayName},
+      ${row.tenantId},
+      ${row.tenantSlug},
+      ${row.resourceType},
+      ${row.resourceId},
+      ${row.resourceName},
+      ${row.outcome},
+      ${row.requestId},
+      ${row.traceId},
+      ${row.message},
+      ${row.metadata},
+      ${row.actorMetadata},
+      ${row.tenantMetadata},
+      ${row.resourceMetadata},
+      ${row.occurredAt}
+    )
+  `;
+}

package/src/shared/health.ts

@@ -0,0 +1,25 @@
+export interface DbHealth {
+  ok: boolean;
+  message?: string;
+  metadata: {
+    adapter: "sqlite" | "postgres" | "mysql";
+  };
+}
+
+export function dbHealthOk(adapter: DbHealth["metadata"]["adapter"]): DbHealth {
+  return {
+    ok: true,
+    metadata: { adapter },
+  };
+}
+
+export function dbHealthError(
+  adapter: DbHealth["metadata"]["adapter"],
+  error: unknown,
+): DbHealth {
+  return {
+    ok: false,
+    message: error instanceof Error ? error.message : String(error),
+    metadata: { adapter },
+  };
+}

package/src/sqlite/index.ts

@@ -32,6 +32,7 @@
 import type { IdempotencyPort } from "@beignet/core/idempotency";
 import type { OutboxPort } from "@beignet/core/outbox";
 import {
+  type AuditLogPort,
   type BufferedDomainEventRecorder,
   createDomainEventRecorder,
   type EventBusPort,
@@ -48,6 +49,12 @@ import { drizzle, type LibSQLDatabase } from "drizzle-orm/libsql";
 import type { LibSQLTransaction } from "drizzle-orm/libsql/session";
 import type { SQLiteTransactionConfig } from "drizzle-orm/sqlite-core";
 import { z } from "zod";
+import {
+  createAuditLogInsertQuery,
+  createAuditLogSqlRow,
+  type DrizzleAuditLogCoreOptions,
+} from "../shared/audit-core.js";
+import { type DbHealth, dbHealthError, dbHealthOk } from "../shared/health.js";
 import {
   createIdempotencyPortCore,
   formatIdempotencyMutationErrorMessage,
@@ -88,8 +95,18 @@ export interface DbPort<
    * Use this for advanced operations not covered by Drizzle ORM.
    */
   client: Client;
+
+  /**
+   * Check whether the underlying database client can run a cheap read query.
+   *
+   * Intended for app-owned readiness endpoints. This does not run migrations
+   * or mutate schema.
+   */
+  checkHealth(): Promise<DbHealth>;
 }
 
+export type { DbHealth };
+
 /**
  * Drizzle database or transaction client accepted by repository factories.
  */
@@ -106,6 +123,15 @@ export type DrizzleSqliteTransaction<
   TSchema extends Record<string, unknown> = Record<string, unknown>,
 > = LibSQLTransaction<TSchema, ExtractTablesWithRelations<TSchema>>;
 
+async function checkSqliteHealth(client: Client): Promise<DbHealth> {
+  try {
+    await client.execute("select 1");
+    return dbHealthOk("sqlite");
+  } catch (error) {
+    return dbHealthError("sqlite", error);
+  }
+}
+
 /**
  * Options for creating a Drizzle SQLite-backed Unit of Work port.
  */
@@ -176,6 +202,91 @@ export function createDrizzleSqliteUnitOfWork<
   };
 }
 
+/**
+ * Options for a Drizzle SQLite-backed audit log port.
+ */
+export interface DrizzleSqliteAuditLogOptions
+  extends DrizzleAuditLogCoreOptions {
+  /**
+   * Table that stores audit log entries.
+   *
+   * Default: "audit_log".
+   */
+  tableName?: string;
+}
+
+/**
+ * Create idempotent SQL statements for the Drizzle SQLite audit log table.
+ *
+ * Run these during migrations or local setup before using
+ * `createDrizzleSqliteAuditLogPort(...)`.
+ */
+export function createDrizzleSqliteAuditLogSetupStatements(
+  options: DrizzleSqliteAuditLogOptions = {},
+): readonly string[] {
+  const tableName = options.tableName ?? "audit_log";
+  const table = quoteIdentifier(tableName, '"');
+  const indexPrefix = tableName.replaceAll(/[^A-Za-z0-9_]/g, "_");
+
+  return [
+    `CREATE TABLE IF NOT EXISTS ${table} (
+      id text PRIMARY KEY NOT NULL,
+      action text NOT NULL,
+      actor_type text NOT NULL,
+      actor_id text,
+      actor_display_name text,
+      tenant_id text,
+      tenant_slug text,
+      resource_type text,
+      resource_id text,
+      resource_name text,
+      outcome text DEFAULT 'success' NOT NULL,
+      request_id text,
+      trace_id text,
+      message text,
+      metadata text,
+      actor_metadata text,
+      tenant_metadata text,
+      resource_metadata text,
+      occurred_at text NOT NULL
+    )`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_action_idx`, '"')} ON ${table} (action)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_actor_idx`, '"')} ON ${table} (actor_type, actor_id)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_occurred_at_idx`, '"')} ON ${table} (occurred_at)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_request_idx`, '"')} ON ${table} (request_id)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_resource_idx`, '"')} ON ${table} (resource_type, resource_id)`,
+    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${indexPrefix}_tenant_idx`, '"')} ON ${table} (tenant_id)`,
+  ];
+}
+
+/**
+ * Create a Beignet audit log port backed by a Drizzle SQLite database.
+ *
+ * The port accepts both the root Drizzle database and transaction clients, so
+ * applications can rebuild audit logging inside Unit of Work transaction ports.
+ */
+export function createDrizzleSqliteAuditLogPort<
+  TSchema extends Record<string, unknown>,
+>(
+  db: DrizzleSqliteDatabase<TSchema>,
+  adapterOptions: DrizzleSqliteAuditLogOptions = {},
+): AuditLogPort {
+  const table = sql.raw(
+    quoteIdentifier(adapterOptions.tableName ?? "audit_log", '"'),
+  );
+
+  return {
+    async record(input) {
+      await db.run(
+        createAuditLogInsertQuery(
+          table,
+          createAuditLogSqlRow(input, adapterOptions),
+        ),
+      );
+    },
+  };
+}
+
 /**
  * Options for a Drizzle SQLite-backed outbox port.
  */
@@ -532,7 +643,12 @@ export function createDrizzleSqliteProvider<
         : drizzle(client, { schema });
 
       // 3. Build a typed DbPort
-      const dbPort: DbPort<TSchema> = { drizzle: db, db, client };
+      const dbPort: DbPort<TSchema> = {
+        drizzle: db,
+        db,
+        client,
+        checkHealth: () => checkSqliteHealth(client),
+      };
 
       return {
         ports: { [portName]: dbPort } as Record<PortName, DbPort<TSchema>>,