@fragno-dev/db 0.2.1 → 0.3.0

package/src/hooks/hooks.ts

@@ -1,18 +1,28 @@
+import type {
+  ExecuteTxOptions,
+  HandlerTxBuilder,
+} from "../query/unit-of-work/execute-unit-of-work";
 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";
+import type { TxResult } from "../query/unit-of-work/execute-unit-of-work";
+import type { FragnoId } from "../schema/create";
 
 /**
  * Context available in hook functions via `this`.
- * Contains the nonce for idempotency and database access.
+ * Contains the idempotency key for idempotency and database access.
  */
 export interface HookContext {
   /**
-   * Unique nonce for this transaction.
+   * Unique idempotency key for this transaction.
    * Use this for idempotency checks in your hook implementation.
    */
-  nonce: string;
+  idempotencyKey: string;
+  /**
+   * Create a handler transaction builder to run atomic operations.
+   */
+  handlerTx: HookHandlerTx;
 }
 
 /**
@@ -42,6 +52,11 @@ export interface TriggerHookOptions {
    * If not provided, uses the default retry policy.
    */
   retryPolicy?: RetryPolicy;
+  /**
+   * Absolute time for the first attempt. If in the future, the hook is
+   * scheduled for that time; if in the past, it runs immediately.
+   */
+  processAt?: Date;
 }
 
 /**
@@ -54,14 +69,88 @@ export interface TriggeredHook {
   options?: TriggerHookOptions;
 }
 
+export type HookScheduler = {
+  schedule: () => Promise<number>;
+  drain: () => Promise<void>;
+};
+
 /**
  * Configuration for hook processing.
  */
-export interface HookProcessorConfig {
-  hooks: HooksMap;
+export interface HookProcessorConfig<THooks extends HooksMap = HooksMap> {
+  hooks: THooks;
   namespace: string;
   internalFragment: InternalFragmentInstance;
+  handlerTx: HookHandlerTx;
+  /**
+   * Internal hook scheduler used to coordinate processing/drain.
+   */
+  scheduler?: HookScheduler;
   defaultRetryPolicy?: RetryPolicy;
+  /**
+   * Re-queue hooks that have been in `processing` for at least this many minutes.
+   * Use `false` to disable stuck-processing recovery entirely.
+   * Values <= 0 are treated as `false`.
+   *
+   * Default: 10 minutes.
+   */
+  stuckProcessingTimeoutMinutes?: StuckHookProcessingTimeoutMinutes;
+  /**
+   * Called when stuck processing hooks are detected and re-queued.
+   * Invoked after the hooks are moved back to `pending`.
+   */
+  onStuckProcessingHooks?: (info: StuckHookProcessingInfo) => void;
+}
+
+export type StuckHookProcessingTimeoutMinutes = number | false;
+
+export type StuckHookProcessingEvent = {
+  id: FragnoId;
+  hookName: string;
+  attempts: number;
+  maxAttempts: number;
+  lastAttemptAt: Date | null;
+  nextRetryAt: Date | null;
+};
+
+export type StuckHookProcessingInfo = {
+  namespace: string;
+  timeoutMinutes: number;
+  events: StuckHookProcessingEvent[];
+};
+
+export type DurableHooksProcessingOptions = {
+  /**
+   * Re-queue hooks that have been in `processing` for at least this many minutes.
+   * Use `false` to disable stuck-processing recovery entirely.
+   * Values <= 0 are treated as `false`.
+   *
+   * Default: 10 minutes.
+   */
+  stuckProcessingTimeoutMinutes?: StuckHookProcessingTimeoutMinutes;
+  /**
+   * Called when stuck processing hooks are detected and re-queued.
+   * Invoked after the hooks are moved back to `pending`.
+   */
+  onStuckProcessingHooks?: (info: StuckHookProcessingInfo) => void;
+};
+
+export type HookHandlerTx = (
+  execOptions?: Omit<ExecuteTxOptions, "createUnitOfWork">,
+) => HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, HooksMap>;
+
+const DEFAULT_STUCK_PROCESSING_TIMEOUT_MINUTES = 10;
+
+function resolveStuckProcessingTimeoutMinutes(
+  value: StuckHookProcessingTimeoutMinutes | undefined,
+): number | false {
+  if (value === false) {
+    return false;
+  }
+  if (typeof value === "number") {
+    return value > 0 ? value : false;
+  }
+  return DEFAULT_STUCK_PROCESSING_TIMEOUT_MINUTES;
 }
 
 /**
@@ -69,7 +158,10 @@ export interface HookProcessorConfig {
  * 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 {
+export function prepareHookMutations<THooks extends HooksMap>(
+  uow: IUnitOfWork,
+  config: HookProcessorConfig<THooks>,
+): void {
   const { namespace, internalFragment, defaultRetryPolicy } = config;
   const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
 
@@ -85,6 +177,8 @@ export function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConf
   for (const hook of triggeredHooks) {
     const hookRetryPolicy = hook.options?.retryPolicy ?? retryPolicy;
     const maxAttempts = hookRetryPolicy.shouldRetry(4) ? 5 : 1;
+    const processAt = hook.options?.processAt ? new Date(hook.options.processAt) : null;
+    const nextRetryAt = processAt ?? null;
     internalUow.create("fragno_hooks", {
       namespace,
       hookName: hook.hookName,
@@ -93,9 +187,9 @@ export function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConf
       attempts: 0,
       maxAttempts,
       lastAttemptAt: null,
-      nextRetryAt: null,
+      nextRetryAt,
       error: null,
-      nonce: uow.nonce,
+      nonce: uow.idempotencyKey,
     });
   }
 }
@@ -104,76 +198,181 @@ export function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConf
  * 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> {
+export async function processHooks<THooks extends HooksMap>(
+  config: HookProcessorConfig<THooks>,
+): Promise<number> {
   const { hooks, namespace, internalFragment, defaultRetryPolicy } = config;
   const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
+  const stuckProcessingTimeoutMinutes = resolveStuckProcessingTimeoutMinutes(
+    config.stuckProcessingTimeoutMinutes,
+  );
+  const getDbNow = async () => {
+    const services = internalFragment.services as { getDbNow?: () => Promise<Date> };
+    if (services.getDbNow) {
+      return services.getDbNow();
+    }
+    return new Date();
+  };
+  const dbNow = await getDbNow();
 
-  await internalFragment.inContext(async function () {
-    return await this.uow(async ({ executeRetrieve, executeMutate }) => {
-      const pendingEventsPromise =
-        internalFragment.services.hookService.getPendingHookEvents(namespace);
-      await executeRetrieve();
+  if (stuckProcessingTimeoutMinutes !== false) {
+    const staleBefore = new Date(dbNow.getTime() - stuckProcessingTimeoutMinutes * 60_000);
+    const stuckEvents = await internalFragment.inContext(async function () {
+      return await this.handlerTx()
+        .withServiceCalls(
+          () =>
+            [
+              internalFragment.services.hookService.requeueStuckProcessingHooks(
+                namespace,
+                staleBefore,
+              ),
+            ] as const,
+        )
+        .transform(({ serviceResult: [events] }) => events)
+        .execute();
+    });
 
-      const pendingEvents = await pendingEventsPromise;
+    if (stuckEvents.length > 0) {
+      try {
+        config.onStuckProcessingHooks?.({
+          namespace,
+          timeoutMinutes: stuckProcessingTimeoutMinutes,
+          events: stuckEvents,
+        });
+      } catch (error) {
+        console.error("Error calling onStuckProcessingHooks", error);
+      }
+    }
+  }
 
-      if (pendingEvents.length === 0) {
-        return;
+  // Claim pending events in the same transaction to avoid double-processing.
+  const pendingEvents = await internalFragment.inContext(async function () {
+    return await this.handlerTx()
+      .withServiceCalls(
+        () => [internalFragment.services.hookService.claimPendingHookEvents(namespace)] as const,
+      )
+      .transform(({ serviceResult: [events] }) => events)
+      .execute();
+  });
+
+  if (pendingEvents.length === 0) {
+    return 0;
+  }
+
+  // Process events (async work outside transaction)
+  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,
+        };
       }
 
-      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 = {
+          idempotencyKey: event.idempotencyKey,
+          handlerTx: config.handlerTx,
+        };
+        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,
+        };
+      }
+    }),
+  );
 
-          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,
-            };
+  // Mark events as completed/failed
+  await internalFragment.inContext(async function () {
+    await this.handlerTx()
+      .withServiceCalls(() => {
+        const txResults: TxResult<void>[] = [];
+        for (const processedEvent of processedEvents) {
+          if (processedEvent.status === "rejected") {
+            continue;
           }
-        }),
-      );
 
-      for (const processedEvent of processedEvents) {
-        if (processedEvent.status === "rejected") {
-          continue;
-        }
+          const { eventId, status } = processedEvent.value;
 
-        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,
-          );
+          if (status === "completed") {
+            txResults.push(internalFragment.services.hookService.markHookCompleted(eventId));
+          } else if (status === "failed") {
+            const { error, attempts } = processedEvent.value;
+            txResults.push(
+              internalFragment.services.hookService.markHookFailed(
+                eventId,
+                error,
+                attempts,
+                retryPolicy,
+                dbNow,
+              ),
+            );
+          }
         }
+        return txResults;
+      })
+      .execute();
+  });
+
+  const processedCount = processedEvents.reduce(
+    (count, result) => count + (result.status === "fulfilled" ? 1 : 0),
+    0,
+  );
+
+  return processedCount;
+}
+
+export function createHookScheduler(config: HookProcessorConfig): HookScheduler {
+  let processing = false;
+  let queued = false;
+  let currentPromise: Promise<number> | null = null;
+
+  const schedule = async () => {
+    if (processing) {
+      queued = true;
+      return currentPromise ?? Promise.resolve(0);
+    }
+
+    processing = true;
+    currentPromise = (async () => {
+      let lastCount = 0;
+      try {
+        do {
+          queued = false;
+          lastCount = await processHooks(config);
+        } while (queued);
+        return lastCount;
+      } finally {
+        processing = false;
+        queued = false;
       }
+    })();
 
-      await executeMutate();
-    });
-  });
+    return currentPromise;
+  };
+
+  const drain = async () => {
+    while (true) {
+      const processed = await schedule();
+      if (processed === 0) {
+        return;
+      }
+    }
+  };
+
+  return { schedule, drain };
 }

package/src/migration-engine/auto-from-schema.test.ts

@@ -4,7 +4,7 @@ import { generateMigrationFromSchema } from "./auto-from-schema";
 
 describe("generateMigrationFromSchema", () => {
   it("should generate create-table operation for new tables", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("name", column("string"));
@@ -35,7 +35,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate multiple table operations in sequence", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("name", column("string"));
@@ -79,7 +79,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate add-foreign-key operation for new foreign keys", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn());
@@ -108,7 +108,7 @@ describe("generateMigrationFromSchema", () => {
     const fkOp = operations[0];
     if (fkOp.type === "add-foreign-key") {
       expect(fkOp.value).toMatchObject({
-        name: "posts_users_author_fk",
+        name: "author",
         referencedTable: "users",
         columns: ["authorId"],
         referencedColumns: ["_internalId"],
@@ -117,7 +117,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate add-index operation for indexes added via alterTable", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("email", column("string"));
@@ -141,7 +141,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate mixed operations for tables and foreign keys", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("name", column("string"));
@@ -166,7 +166,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate mixed operations for tables, indexes, and foreign keys", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("email", column("string"));
@@ -195,7 +195,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate no operations when version range is empty", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s.addTable("users", (t) => {
         return t.addColumn("id", idColumn()).addColumn("name", column("string"));
       });
@@ -207,7 +207,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should throw error when fromVersion exceeds schema version", () => {
-    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+    const mySchema = schema("my", (s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
 
     expect(() => {
       generateMigrationFromSchema(mySchema, 999, 1000);
@@ -215,7 +215,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should throw error when toVersion exceeds schema version", () => {
-    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+    const mySchema = schema("my", (s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
 
     expect(() => {
       generateMigrationFromSchema(mySchema, 0, 999);
@@ -223,7 +223,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should throw error when trying to migrate backwards", () => {
-    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+    const mySchema = schema("my", (s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
 
     expect(() => {
       generateMigrationFromSchema(mySchema, 1, 0);
@@ -231,7 +231,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should throw error for negative fromVersion", () => {
-    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+    const mySchema = schema("my", (s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
 
     expect(() => {
       generateMigrationFromSchema(mySchema, -1, 1);
@@ -239,7 +239,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should only create constraints for references, not for referenceColumns", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("posts", (t) => {
           return t
@@ -276,7 +276,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should not create duplicate foreign key constraints", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => t.addColumn("id", idColumn()))
         .addTable("posts", (t) =>

package/src/migration-engine/auto-from-schema.ts

@@ -16,7 +16,7 @@ import type { MigrationOperation, ColumnInfo } from "./shared";
  *
  * @example
  * ```ts
- * const mySchema = schema(s => s
+ * const mySchema = schema("my", s => s
  *   .addTable("users", t => t.addColumn("id", idColumn()))       // version 1
  *   .addTable("posts", t => t.addColumn("id", idColumn()))       // version 2
  * );
@@ -156,11 +156,14 @@ export function generateMigrationFromSchema(
         }
       }
     } else if (op.type === "add-reference") {
+      if (!op.referenceName || op.referenceName.trim().length === 0) {
+        throw new Error(`referenceName is required for add-reference on ${op.tableName}`);
+      }
       migrationOperations.push({
         type: "add-foreign-key",
         table: op.tableName,
         value: {
-          name: `${op.tableName}_${op.config.to.table}_${op.referenceName}_fk`,
+          name: op.referenceName,
           columns: [op.config.from.column],
           referencedTable: op.config.to.table,
           referencedColumns: [op.config.to.column],

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

@@ -4,7 +4,7 @@ import { schema, idColumn, column, referenceColumn } from "../schema/create";
 import type { MigrationOperation } from "./shared";
 
 describe("createMigrator", () => {
-  const testSchema = schema((s) => {
+  const testSchema = schema("test", (s) => {
     return s
       .addTable("users", (t) => {
         return t.addColumn("id", idColumn()).addColumn("name", column("string"));
@@ -296,7 +296,7 @@ describe("createMigrator", () => {
 
   describe("with foreign keys", () => {
     it("should handle schema with foreign keys", async () => {
-      const fkSchema = schema((s) => {
+      const fkSchema = schema("fk", (s) => {
         return s
           .addTable("users", (t) => {
             return t.addColumn("id", idColumn());