@fragno-dev/db 0.1.14 → 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,17 +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) });
-    adapter = new KyselyAdapter({ db, provider: "postgresql" });
+    adapter = new KyselyAdapter({
+      dialect: {
+        createAdapter: () => new PostgresAdapter(),
+        createDriver: () => new DummyDriver(),
+        createQueryCompiler: () => ({
+          compileQuery: () => ({
+            sql: "",
+            parameters: [],
+          }),
+        }),
+      },
+      driverConfig: new NodePostgresDriverConfig(),
+    });
 
     // Mock the adapter methods
     vi.spyOn(adapter, "isConnectionHealthy").mockResolvedValue(true);
@@ -50,8 +63,8 @@ describe("generateMigrationsOrSchema - kysely", () => {
     const results = await generateMigrationsOrSchema([fragnoDb]);
 
     expect(results).toHaveLength(2); // Settings + test-db
-    expect(results[0].namespace).toBe("fragno-db-settings");
-    expect(results[0].path).toBe("20251024_001_f000_t001_fragno-db-settings.sql");
+    expect(results[0].namespace).toBe(""); // Empty namespace for settings table
+    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");
 
@@ -101,8 +114,8 @@ describe("generateMigrationsOrSchema - kysely", () => {
     const results = await generateMigrationsOrSchema([fragnoDb1, fragnoDb2, fragnoDb3]);
 
     expect(results).toHaveLength(4); // Settings + 3 databases
-    expect(results[0].namespace).toBe("fragno-db-settings");
-    expect(results[0].path).toBe("20251024_001_f000_t001_fragno-db-settings.sql");
+    expect(results[0].namespace).toBe(""); // Empty namespace for settings table
+    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");
@@ -142,7 +155,7 @@ describe("generateMigrationsOrSchema - kysely", () => {
     // Settings table already at version 1, so no settings migration needed
     // But fragment migration is still generated
     expect(results).toHaveLength(2);
-    expect(results[0].namespace).toBe("fragno-db-settings");
+    expect(results[0].namespace).toBe(""); // Empty namespace for settings table
     expect(results[1].namespace).toBe("test-db");
     expect(results[1].path).toBe("20251024_002_f000_t002_test-db.sql");
     expect(results[1].schema).toContain("create table");
@@ -170,7 +183,7 @@ describe("generateMigrationsOrSchema - kysely", () => {
 
     // Settings migration is generated, but no fragment migration (since toVersion=0)
     expect(results).toHaveLength(1);
-    expect(results[0].namespace).toBe("fragno-db-settings");
+    expect(results[0].namespace).toBe(""); // Empty namespace for settings table
   });
 
   it("should throw error when no databases provided", async () => {
@@ -281,9 +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) });
-    const mysqlAdapter = new KyselyAdapter({ db: mysqlDb, provider: "mysql" });
+    const mysqlAdapter = new KyselyAdapter({
+      dialect: {
+        createAdapter: () => new MysqlAdapter(),
+        createDriver: () => new DummyDriver(),
+        createQueryCompiler: () => ({
+          compileQuery: () => ({
+            sql: "",
+            parameters: [],
+          }),
+        }),
+      },
+      driverConfig: new MySQL2DriverConfig(),
+    });
 
     vi.spyOn(mysqlAdapter, "isConnectionHealthy").mockResolvedValue(true);
     vi.spyOn(mysqlAdapter, "getSchemaVersion").mockResolvedValue(undefined);
@@ -316,9 +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) });
-    const sqliteAdapter = new KyselyAdapter({ db: sqliteDb, provider: "sqlite" });
+    const sqliteAdapter = new KyselyAdapter({
+      dialect: {
+        createAdapter: () => new SqliteAdapter(),
+        createDriver: () => new DummyDriver(),
+        createQueryCompiler: () => ({
+          compileQuery: () => ({
+            sql: "",
+            parameters: [],
+          }),
+        }),
+      },
+      driverConfig: new SQLocalDriverConfig(),
+    });
 
     vi.spyOn(sqliteAdapter, "isConnectionHealthy").mockResolvedValue(true);
     vi.spyOn(sqliteAdapter, "getSchemaVersion").mockResolvedValue(undefined);
@@ -377,7 +410,7 @@ describe("postProcessMigrationFilenames", () => {
       {
         schema: "schema2",
         path: "placeholder.sql",
-        namespace: "fragno-db-settings",
+        namespace: "", // Empty namespace for settings table
         fromVersion: 0,
         toVersion: 1,
       },
@@ -393,8 +426,8 @@ describe("postProcessMigrationFilenames", () => {
     const result = postProcessMigrationFilenames(files);
 
     expect(result).toHaveLength(3);
-    expect(result[0].namespace).toBe("fragno-db-settings");
-    expect(result[0].path).toBe("20251024_001_f000_t001_fragno-db-settings.sql");
+    expect(result[0].namespace).toBe(""); // Empty namespace for settings table
+    expect(result[0].path).toBe("20251024_001_f000_t001_fragno_db_settings.sql");
   });
 
   it("should sort non-settings namespaces alphabetically", () => {
@@ -435,9 +468,9 @@ describe("postProcessMigrationFilenames", () => {
       {
         schema: "CREATE TABLE users;",
         path: "placeholder.sql",
-        namespace: "fragno-db-settings",
+        namespace: "", // Empty namespace for settings table
         fromVersion: 0,
-        toVersion: 1,
+        toVersion: 5,
       },
       {
         schema: "CREATE TABLE comments;",
@@ -450,7 +483,7 @@ describe("postProcessMigrationFilenames", () => {
 
     const result = postProcessMigrationFilenames(files);
 
-    expect(result[0].path).toBe("20251024_001_f000_t001_fragno-db-settings.sql");
+    expect(result[0].path).toBe("20251024_001_f000_t005_fragno_db_settings.sql");
     expect(result[1].path).toBe("20251024_002_f005_t010_comment-db.sql");
   });
 
@@ -514,7 +547,7 @@ describe("postProcessMigrationFilenames", () => {
       {
         schema: "schema2",
         path: "placeholder.sql",
-        namespace: "fragno-db-settings",
+        namespace: "", // Empty namespace for settings table
         fromVersion: 0,
         toVersion: 5,
       },
@@ -537,8 +570,8 @@ describe("postProcessMigrationFilenames", () => {
     const result = postProcessMigrationFilenames(files);
 
     expect(result).toHaveLength(4);
-    expect(result[0].namespace).toBe("fragno-db-settings");
-    expect(result[0].path).toBe("20251024_001_f000_t005_fragno-db-settings.sql");
+    expect(result[0].namespace).toBe(""); // Empty namespace for settings table
+    expect(result[0].path).toBe("20251024_001_f000_t005_fragno_db_settings.sql");
     expect(result[1].namespace).toBe("apple-db");
     expect(result[1].path).toBe("20251024_002_f003_t004_apple-db.sql");
     expect(result[2].namespace).toBe("mango-db");