@fragno-dev/db 0.1.15 → 0.2.0

package/src/hooks/hooks.ts

@@ -0,0 +1,179 @@
+import type { RetryPolicy } from "../query/unit-of-work/retry-policy";
+import { ExponentialBackoffRetryPolicy } from "../query/unit-of-work/retry-policy";
+import type { IUnitOfWork } from "../query/unit-of-work/unit-of-work";
+import type { InternalFragmentInstance } from "../fragments/internal-fragment";
+
+/**
+ * Context available in hook functions via `this`.
+ * Contains the nonce for idempotency and database access.
+ */
+export interface HookContext {
+  /**
+   * Unique nonce for this transaction.
+   * Use this for idempotency checks in your hook implementation.
+   */
+  nonce: string;
+}
+
+/**
+ * A hook function signature.
+ * Hooks receive a typed payload and access context via `this`.
+ */
+export type HookFn<TPayload = unknown> = (payload: TPayload) => void | Promise<void>;
+
+/**
+ * Map of hook names to hook functions.
+ * Used for type-safe hook definitions and triggering.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type HooksMap = Record<string, HookFn<any>>;
+
+/**
+ * Extract the payload type from a hook function.
+ */
+export type HookPayload<T> = T extends HookFn<infer P> ? P : never;
+
+/**
+ * Options for triggering a hook.
+ */
+export interface TriggerHookOptions {
+  /**
+   * Optional retry policy override for this specific hook trigger.
+   * If not provided, uses the default retry policy.
+   */
+  retryPolicy?: RetryPolicy;
+}
+
+/**
+ * Internal representation of a triggered hook.
+ * Stored in the Unit of Work before execution.
+ */
+export interface TriggeredHook {
+  hookName: string;
+  payload: unknown;
+  options?: TriggerHookOptions;
+}
+
+/**
+ * Configuration for hook processing.
+ */
+export interface HookProcessorConfig {
+  hooks: HooksMap;
+  namespace: string;
+  internalFragment: InternalFragmentInstance;
+  defaultRetryPolicy?: RetryPolicy;
+}
+
+/**
+ * Add hook events as mutation operations to the UOW.
+ * This should be called before executeMutations() so hook records are created
+ * in the same transaction as the user's mutations.
+ */
+export function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConfig): void {
+  const { namespace, internalFragment, defaultRetryPolicy } = config;
+  const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
+
+  const triggeredHooks = uow.getTriggeredHooks();
+
+  if (triggeredHooks.length === 0) {
+    return;
+  }
+
+  const internalSchema = internalFragment.$internal.deps.schema;
+  const internalUow = uow.forSchema(internalSchema);
+
+  for (const hook of triggeredHooks) {
+    const hookRetryPolicy = hook.options?.retryPolicy ?? retryPolicy;
+    const maxAttempts = hookRetryPolicy.shouldRetry(4) ? 5 : 1;
+    internalUow.create("fragno_hooks", {
+      namespace,
+      hookName: hook.hookName,
+      payload: hook.payload,
+      status: "pending",
+      attempts: 0,
+      maxAttempts,
+      lastAttemptAt: null,
+      nextRetryAt: null,
+      error: null,
+      nonce: uow.nonce,
+    });
+  }
+}
+
+/**
+ * Process pending hook events after the transaction has committed.
+ * This should be called in the onSuccess callback after executeMutations().
+ */
+export async function processHooks(config: HookProcessorConfig): Promise<void> {
+  const { hooks, namespace, internalFragment, defaultRetryPolicy } = config;
+  const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
+
+  await internalFragment.inContext(async function () {
+    return await this.uow(async ({ executeRetrieve, executeMutate }) => {
+      const pendingEventsPromise =
+        internalFragment.services.hookService.getPendingHookEvents(namespace);
+      await executeRetrieve();
+
+      const pendingEvents = await pendingEventsPromise;
+
+      if (pendingEvents.length === 0) {
+        return;
+      }
+
+      const processedEvents = await Promise.allSettled(
+        pendingEvents.map(async (event) => {
+          const hookFn = hooks[event.hookName];
+          if (!hookFn) {
+            return {
+              eventId: event.id,
+              status: "failed" as const,
+              error: `Hook '${event.hookName}' not found in hooks map`,
+              attempts: event.attempts,
+              maxAttempts: event.maxAttempts,
+            };
+          }
+
+          try {
+            const hookContext: HookContext = { nonce: event.nonce };
+            await hookFn.call(hookContext, event.payload);
+            return {
+              eventId: event.id,
+              status: "completed" as const,
+            };
+          } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+              eventId: event.id,
+              status: "failed" as const,
+              error: errorMessage,
+              attempts: event.attempts,
+              maxAttempts: event.maxAttempts,
+            };
+          }
+        }),
+      );
+
+      for (const processedEvent of processedEvents) {
+        if (processedEvent.status === "rejected") {
+          continue;
+        }
+
+        const { eventId, status } = processedEvent.value;
+
+        if (status === "completed") {
+          internalFragment.services.hookService.markHookCompleted(eventId);
+        } else if (status === "failed") {
+          const { error, attempts } = processedEvent.value;
+          internalFragment.services.hookService.markHookFailed(
+            eventId,
+            error,
+            attempts,
+            retryPolicy,
+          );
+        }
+      }
+
+      await executeMutate();
+    });
+  });
+}

package/src/migration-engine/generation-engine.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeAll, beforeEach, vi, afterEach } from "vitest";
-import { Kysely, PostgresDialect } from "kysely";
+import { DummyDriver, MysqlAdapter, PostgresAdapter, SqliteAdapter } from "kysely";
 import {
   postProcessMigrationFilenames,
   type GenerationInternalResult,
@@ -8,32 +8,30 @@ import {
 import { KyselyAdapter } from "../adapters/kysely/kysely-adapter";
 import { column, idColumn, schema, type AnySchema } from "../schema/create";
 import { FragnoDatabase } from "../mod";
+import {
+  MySQL2DriverConfig,
+  NodePostgresDriverConfig,
+  SQLocalDriverConfig,
+} from "../adapters/generic-sql/driver-config";
 
 describe("generateMigrationsOrSchema - kysely", () => {
   const mockDate = new Date("2025-10-24T12:00:00Z");
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let db: Kysely<any>;
   let adapter: KyselyAdapter;
 
   beforeAll(() => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    db = new Kysely({ dialect: new PostgresDialect({} as any) });
-
-    // Mock Kysely transaction to prevent actual database connections
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    vi.spyOn(db, "transaction").mockReturnValue({
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      execute: async (callback: any) => {
-        // Return a mock transaction executor that returns empty results
-        const mockTx = {
-          executeQuery: async () => ({ rows: [] }),
-        };
-        return callback(mockTx);
+    adapter = new KyselyAdapter({
+      dialect: {
+        createAdapter: () => new PostgresAdapter(),
+        createDriver: () => new DummyDriver(),
+        createQueryCompiler: () => ({
+          compileQuery: () => ({
+            sql: "",
+            parameters: [],
+          }),
+        }),
       },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    } as any);
-
-    adapter = new KyselyAdapter({ db, provider: "postgresql" });
+      driverConfig: new NodePostgresDriverConfig(),
+    });
 
     // Mock the adapter methods
     vi.spyOn(adapter, "isConnectionHealthy").mockResolvedValue(true);
@@ -66,7 +64,7 @@ describe("generateMigrationsOrSchema - kysely", () => {
 
     expect(results).toHaveLength(2); // Settings + test-db
     expect(results[0].namespace).toBe(""); // Empty namespace for settings table
-    expect(results[0].path).toBe("20251024_001_f000_t001_fragno_db_settings.sql");
+    expect(results[0].path).toMatch(/^20251024_001_f000_t00\d_fragno_db_settings.sql$/);
     expect(results[0].schema).toContain("create table");
     expect(results[0].schema).toContain("fragno_db_settings");
 
@@ -117,7 +115,7 @@ describe("generateMigrationsOrSchema - kysely", () => {
 
     expect(results).toHaveLength(4); // Settings + 3 databases
     expect(results[0].namespace).toBe(""); // Empty namespace for settings table
-    expect(results[0].path).toBe("20251024_001_f000_t001_fragno_db_settings.sql");
+    expect(results[0].path).toMatch(/^20251024_001_f000_t00\d_fragno_db_settings.sql$/);
 
     expect(results[1].namespace).toBe("apple-db");
     expect(results[1].path).toBe("20251024_002_f000_t001_apple-db.sql");
@@ -296,23 +294,19 @@ describe("generateMigrationsOrSchema - kysely", () => {
   });
 
   it("should include MySQL-specific foreign key checks in generated SQL", async () => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const mysqlDb = new Kysely({ dialect: new PostgresDialect({} as any) });
-
-    // Mock Kysely transaction to prevent actual database connections
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    vi.spyOn(mysqlDb, "transaction").mockReturnValue({
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      execute: async (callback: any) => {
-        const mockTx = {
-          executeQuery: async () => ({ rows: [] }),
-        };
-        return callback(mockTx);
+    const mysqlAdapter = new KyselyAdapter({
+      dialect: {
+        createAdapter: () => new MysqlAdapter(),
+        createDriver: () => new DummyDriver(),
+        createQueryCompiler: () => ({
+          compileQuery: () => ({
+            sql: "",
+            parameters: [],
+          }),
+        }),
       },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    } as any);
-
-    const mysqlAdapter = new KyselyAdapter({ db: mysqlDb, provider: "mysql" });
+      driverConfig: new MySQL2DriverConfig(),
+    });
 
     vi.spyOn(mysqlAdapter, "isConnectionHealthy").mockResolvedValue(true);
     vi.spyOn(mysqlAdapter, "getSchemaVersion").mockResolvedValue(undefined);
@@ -345,23 +339,19 @@ describe("generateMigrationsOrSchema - kysely", () => {
   });
 
   it("should include SQLite-specific pragma in generated SQL", async () => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const sqliteDb = new Kysely({ dialect: new PostgresDialect({} as any) });
-
-    // Mock Kysely transaction to prevent actual database connections
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    vi.spyOn(sqliteDb, "transaction").mockReturnValue({
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      execute: async (callback: any) => {
-        const mockTx = {
-          executeQuery: async () => ({ rows: [] }),
-        };
-        return callback(mockTx);
+    const sqliteAdapter = new KyselyAdapter({
+      dialect: {
+        createAdapter: () => new SqliteAdapter(),
+        createDriver: () => new DummyDriver(),
+        createQueryCompiler: () => ({
+          compileQuery: () => ({
+            sql: "",
+            parameters: [],
+          }),
+        }),
       },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    } as any);
-
-    const sqliteAdapter = new KyselyAdapter({ db: sqliteDb, provider: "sqlite" });
+      driverConfig: new SQLocalDriverConfig(),
+    });
 
     vi.spyOn(sqliteAdapter, "isConnectionHealthy").mockResolvedValue(true);
     vi.spyOn(sqliteAdapter, "getSchemaVersion").mockResolvedValue(undefined);

package/src/migration-engine/generation-engine.ts

@@ -1,15 +1,14 @@
 import type { FragnoDatabase } from "../mod";
 import type { AnySchema } from "../schema/create";
-import type { PreparedMigration } from "./create";
 import {
   fragnoDatabaseAdapterNameFakeSymbol,
   fragnoDatabaseAdapterVersionFakeSymbol,
 } from "../adapters/adapters";
 import {
   internalFragmentDef,
-  settingsSchema,
-  SETTINGS_TABLE_NAME,
+  internalSchema,
   SETTINGS_NAMESPACE,
+  getSchemaVersionFromDatabase,
 } from "../fragments/internal-fragment";
 import { instantiate } from "@fragno-dev/core";
 
@@ -25,7 +24,6 @@ export interface GenerationInternalResult {
   namespace: string;
   fromVersion: number;
   toVersion: number;
-  preparedMigration?: PreparedMigration;
 }
 
 export interface ExecuteMigrationResult {
@@ -68,7 +66,7 @@ export async function generateMigrationsOrSchema<
 
     // Include internal fragment first with empty namespace (settings table has no prefix)
     fragmentsMap.set("", {
-      schema: settingsSchema,
+      schema: internalSchema,
       namespace: "",
     });
 
@@ -96,10 +94,10 @@ export async function generateMigrationsOrSchema<
     ];
   }
 
-  // Otherwise, use migration engine for individual generation (e.g., Kysely)
-  if (!adapter.createMigrationEngine) {
+  // Otherwise, use migration engine for individual generation (e.g., Kysely, GenericSQL)
+  if (!adapter.prepareMigrations) {
     throw new Error(
-      "Adapter does not support migration-based schema generation. Ensure your adapter implements createMigrationEngine.",
+      "Adapter does not support migration-based schema generation. Ensure your adapter implements prepareMigrations.",
     );
   }
 
@@ -115,45 +113,22 @@ export async function generateMigrationsOrSchema<
     .withOptions({ databaseAdapter: adapter })
     .build();
 
-  let settingsSourceVersion: number;
-  try {
-    const result = await internalFragment.inContext(async function () {
-      return await this.uow(async ({ executeRetrieve }) => {
-        const v = internalFragment.services.settingsService.get("version");
-        await executeRetrieve();
-
-        return v;
-      });
-    });
-
-    if (!result) {
-      settingsSourceVersion = 0;
-    } else {
-      settingsSourceVersion = parseInt(result.value);
-    }
-  } catch {
-    // Settings table doesn't exist yet (first migration)
-    settingsSourceVersion = 0;
-  }
+  const settingsSourceVersion = await getSchemaVersionFromDatabase(
+    internalFragment,
+    SETTINGS_NAMESPACE,
+  );
 
   const generatedFiles: GenerationInternalResult[] = [];
 
   // Use empty namespace for settings (SETTINGS_NAMESPACE is for prefixing keys, not the database namespace)
-  const settingsMigrator = adapter.createMigrationEngine(settingsSchema, "");
-  const settingsTargetVersion = settingsSchema.version;
+  const settingsPreparedMigrations = adapter.prepareMigrations(internalSchema, "");
+  const settingsTargetVersion = internalSchema.version;
 
   // Generate settings table migration
-  const settingsMigration = await settingsMigrator.prepareMigrationTo(settingsTargetVersion, {
-    fromVersion: settingsSourceVersion,
-  });
-
-  if (!settingsMigration.getSQL) {
-    throw new Error(
-      "Migration engine does not support SQL generation. Ensure your adapter's migration engine provides getSQL().",
-    );
-  }
-
-  const settingsSql = settingsMigration.getSQL();
+  const settingsSql = settingsPreparedMigrations.getSQL(
+    settingsSourceVersion,
+    settingsTargetVersion,
+  );
 
   if (settingsSql.trim()) {
     generatedFiles.push({
@@ -162,7 +137,6 @@ export async function generateMigrationsOrSchema<
       namespace: "", // Empty namespace for settings table
       fromVersion: settingsSourceVersion,
       toVersion: settingsTargetVersion,
-      preparedMigration: settingsMigration,
     });
   }
 
@@ -171,29 +145,19 @@ export async function generateMigrationsOrSchema<
     const dbAdapter = db.adapter;
 
     // Use migration engine
-    if (!dbAdapter.createMigrationEngine) {
+    if (!dbAdapter.prepareMigrations) {
       throw new Error(
         `Adapter for ${db.namespace} does not support schema generation. ` +
-          `Ensure your adapter implements either createSchemaGenerator or createMigrationEngine.`,
+          `Ensure your adapter implements either createSchemaGenerator or prepareMigrations.`,
       );
     }
 
-    const migrator = dbAdapter.createMigrationEngine(db.schema, db.namespace);
+    const preparedMigrations = dbAdapter.prepareMigrations(db.schema, db.namespace);
     const targetVersion = options?.toVersion ?? db.schema.version;
     const sourceVersion = options?.fromVersion ?? 0;
 
     // Generate migration from source to target version
-    const preparedMigration = await migrator.prepareMigrationTo(targetVersion, {
-      fromVersion: sourceVersion,
-    });
-
-    if (!preparedMigration.getSQL) {
-      throw new Error(
-        "Migration engine does not support SQL generation. Ensure your adapter's migration engine provides getSQL().",
-      );
-    }
-
-    const sql = preparedMigration.getSQL();
+    const sql = preparedMigrations.getSQL(sourceVersion, targetVersion);
 
     // If no migrations needed, skip this fragment
     if (sql.trim()) {
@@ -203,7 +167,6 @@ export async function generateMigrationsOrSchema<
         namespace: db.namespace,
         fromVersion: sourceVersion,
         toVersion: targetVersion,
-        preparedMigration: preparedMigration,
       });
     }
   }
@@ -230,7 +193,7 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
   const adapter = firstDb.adapter;
 
   // Validate adapter supports migrations
-  if (!adapter.createMigrationEngine) {
+  if (!adapter.prepareMigrations) {
     throw new Error(
       "Adapter does not support running migrations. The adapter only supports schema generation.\n" +
         "Try using 'generateMigrationsOrSchema' instead to generate schema files.",
@@ -264,7 +227,7 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
     namespace: string;
     fromVersion: number;
     toVersion: number;
-    preparedMigration: PreparedMigration;
+    execute: () => Promise<void>;
   }> = [];
 
   // 1. Prepare settings table migration
@@ -274,43 +237,31 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
     .withOptions({ databaseAdapter: adapter })
     .build();
 
-  let settingsSourceVersion: number;
-  try {
-    const result = await internalFragment.inContext(async function () {
-      return this.uow(async ({ forSchema, executeRetrieve }) => {
-        const uow = forSchema(settingsSchema);
-        const findOp = uow.find(SETTINGS_TABLE_NAME, (b) =>
-          b.whereIndex("unique_key", (eb) => eb("key", "=", `${SETTINGS_NAMESPACE}.version`)),
-        );
-
-        await executeRetrieve();
-
-        const [results] = await findOp.retrievalPhase;
-        return results?.[0];
-      });
-    });
-    settingsSourceVersion = result ? parseInt(result.value) : 0;
-  } catch {
-    // Settings table doesn't exist yet (first migration)
-    settingsSourceVersion = 0;
-  }
+  const settingsSourceVersion = await getSchemaVersionFromDatabase(
+    internalFragment,
+    SETTINGS_NAMESPACE,
+  );
 
   // Use empty namespace for settings (SETTINGS_NAMESPACE is for prefixing keys, not the database namespace)
-  const settingsMigrator = adapter.createMigrationEngine(settingsSchema, "");
-  const settingsTargetVersion = settingsSchema.version;
+  const settingsPreparedMigrations = adapter.prepareMigrations(internalSchema, "");
+  const settingsTargetVersion = internalSchema.version;
 
   if (settingsSourceVersion < settingsTargetVersion) {
-    const settingsMigration = await settingsMigrator.prepareMigrationTo(settingsTargetVersion, {
-      fromVersion: settingsSourceVersion,
-      updateSettings: true,
-    });
+    const compiledMigration = settingsPreparedMigrations.compile(
+      settingsSourceVersion,
+      settingsTargetVersion,
+      { updateVersionInMigration: true },
+    );
 
-    if (settingsMigration.operations.length > 0) {
+    if (compiledMigration.statements.length > 0) {
       migrationsToExecute.push({
         namespace: "", // Empty namespace for settings table
         fromVersion: settingsSourceVersion,
         toVersion: settingsTargetVersion,
-        preparedMigration: settingsMigration,
+        execute: () =>
+          settingsPreparedMigrations.execute(settingsSourceVersion, settingsTargetVersion, {
+            updateVersionInMigration: true,
+          }),
       });
     }
   }
@@ -319,21 +270,24 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
   const sortedDatabases = [...databases].sort((a, b) => a.namespace.localeCompare(b.namespace));
 
   for (const fragnoDb of sortedDatabases) {
-    const migrator = adapter.createMigrationEngine(fragnoDb.schema, fragnoDb.namespace);
-    const currentVersion = await migrator.getVersion();
+    const preparedMigrations = adapter.prepareMigrations(fragnoDb.schema, fragnoDb.namespace);
+    const currentVersion = await getSchemaVersionFromDatabase(internalFragment, fragnoDb.namespace);
     const targetVersion = fragnoDb.schema.version;
 
     if (currentVersion < targetVersion) {
-      const preparedMigration = await migrator.prepareMigrationTo(targetVersion, {
-        updateSettings: true,
+      const compiledMigration = preparedMigrations.compile(currentVersion, targetVersion, {
+        updateVersionInMigration: true,
       });
 
-      if (preparedMigration.operations.length > 0) {
+      if (compiledMigration.statements.length > 0) {
         migrationsToExecute.push({
           namespace: fragnoDb.namespace,
           fromVersion: currentVersion,
           toVersion: targetVersion,
-          preparedMigration: preparedMigration,
+          execute: () =>
+            preparedMigrations.execute(currentVersion, targetVersion, {
+              updateVersionInMigration: true,
+            }),
         });
       }
     }
@@ -341,7 +295,7 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
 
   // 3. Execute all migrations in order
   for (const migration of migrationsToExecute) {
-    await migration.preparedMigration.execute();
+    await migration.execute();
     results.push({
       namespace: migration.namespace,
       didMigrate: true,