@fragno-dev/db 0.3.0 → 0.4.1

package/src/hooks/hooks.ts

@@ -1,3 +1,5 @@
+import type { InternalFragmentInstance } from "../fragments/internal-fragment";
+import { dbNow, isDbNow, type DbNow } from "../query/db-now";
 import type {
   ExecuteTxOptions,
   HandlerTxBuilder,
@@ -5,9 +7,8 @@ import type {
 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";
+import { DurableHooksLogger, type DurableHooksLoggerConfig } from "./durable-hooks-logger";
 
 /**
  * Context available in hook functions via `this`.
@@ -19,12 +20,58 @@ export interface HookContext {
    * Use this for idempotency checks in your hook implementation.
    */
   idempotencyKey: string;
+  /**
+   * Hook event identifier (versioned FragnoId).
+   */
+  hookId: FragnoId;
+  /**
+   * Hook name for this event.
+   */
+  hookName: string;
+  /**
+   * Current status of the hook event.
+   */
+  status: HookStatus;
+  /**
+   * Attempt count for this hook event.
+   */
+  attempts: number;
+  /**
+   * Maximum attempts configured for this hook event.
+   */
+  maxAttempts: number;
+  /**
+   * Timestamp of the last attempt (if any).
+   */
+  lastAttemptAt: Date | null;
+  /**
+   * Next scheduled retry timestamp (if any).
+   */
+  nextRetryAt: Date | null;
+  /**
+   * When the hook event was created.
+   */
+  createdAt: Date;
   /**
    * Create a handler transaction builder to run atomic operations.
    */
   handlerTx: HookHandlerTx;
 }
 
+export const hookStatusValues = ["pending", "processing", "completed", "failed"] as const;
+
+export type HookStatus = (typeof hookStatusValues)[number];
+
+export const isHookStatus = (value: unknown): value is HookStatus =>
+  typeof value === "string" && hookStatusValues.includes(value as HookStatus);
+
+const assertHookStatus = (value: unknown): HookStatus => {
+  if (isHookStatus(value)) {
+    return value;
+  }
+  throw new Error(`Invalid hook status: ${String(value)}`);
+};
+
 /**
  * A hook function signature.
  * Hooks receive a typed payload and access context via `this`.
@@ -52,11 +99,16 @@ export interface TriggerHookOptions {
    * If not provided, uses the default retry policy.
    */
   retryPolicy?: RetryPolicy;
+  /**
+   * Optional hook event ID. When provided, the hook insert will fail if a hook
+   * with the same ID already exists.
+   */
+  id?: string | FragnoId;
   /**
    * 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;
+  processAt?: Date | DbNow;
 }
 
 /**
@@ -64,11 +116,32 @@ export interface TriggerHookOptions {
  * Stored in the Unit of Work before execution.
  */
 export interface TriggeredHook {
+  namespace: string;
   hookName: string;
   payload: unknown;
   options?: TriggerHookOptions;
 }
 
+export type HookNotifySource = "request" | "hook" | "alarm";
+
+export type HookNotifyContext = {
+  source: HookNotifySource;
+  route?: string | null;
+  waitUntil?: (promise: Promise<unknown>) => void;
+};
+
+export type HookNotifier = {
+  notify: (context: HookNotifyContext) => void | Promise<void>;
+};
+
+export type DurableHooksRunner = {
+  processDue: () => Promise<number>;
+  drain: () => Promise<void>;
+};
+
+/**
+ * @deprecated Use DurableHooksRunner.
+ */
 export type HookScheduler = {
   schedule: () => Promise<number>;
   drain: () => Promise<void>;
@@ -78,12 +151,25 @@ export type HookScheduler = {
  * Configuration for hook processing.
  */
 export interface HookProcessorConfig<THooks extends HooksMap = HooksMap> {
-  hooks: THooks;
+  hooks?: THooks;
   namespace: string;
   internalFragment: InternalFragmentInstance;
   handlerTx: HookHandlerTx;
   /**
-   * Internal hook scheduler used to coordinate processing/drain.
+   * Whether post-mutate notifications should auto-schedule processing.
+   * Defaults to true.
+   */
+  autoSchedule?: boolean;
+  /**
+   * Internal hook runner used to coordinate processing/drain.
+   */
+  runner?: DurableHooksRunner;
+  /**
+   * Post-commit durable hooks notifier.
+   */
+  notifier?: HookNotifier;
+  /**
+   * @deprecated Use `runner`.
    */
   scheduler?: HookScheduler;
   defaultRetryPolicy?: RetryPolicy;
@@ -128,11 +214,21 @@ export type DurableHooksProcessingOptions = {
    * Default: 10 minutes.
    */
   stuckProcessingTimeoutMinutes?: StuckHookProcessingTimeoutMinutes;
+  /**
+   * Automatically schedule hook processing after successful mutations.
+   * Defaults to true. Set false to disable auto scheduling (manual drain only).
+   */
+  autoSchedule?: boolean;
   /**
    * Called when stuck processing hooks are detected and re-queued.
    * Invoked after the hooks are moved back to `pending`.
    */
   onStuckProcessingHooks?: (info: StuckHookProcessingInfo) => void;
+  /**
+   * Durable hooks logging controls.
+   * Defaults: enabled=true, level="warn".
+   */
+  logging?: DurableHooksLoggerConfig;
 };
 
 export type HookHandlerTx = (
@@ -157,12 +253,16 @@ function resolveStuckProcessingTimeoutMinutes(
  * 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.
+ *
+ * Each triggered hook carries its own namespace (set at trigger-time), so this
+ * function works regardless of which fragment's handler is executing. When a
+ * `config` is provided its `defaultRetryPolicy` is used as fallback.
  */
-export function prepareHookMutations<THooks extends HooksMap>(
-  uow: IUnitOfWork,
-  config: HookProcessorConfig<THooks>,
+export function prepareHookMutations(
+  uow: Pick<IUnitOfWork, "getTriggeredHooks" | "forSchema" | "idempotencyKey">,
+  internalFragment: InternalFragmentInstance,
+  defaultRetryPolicy?: RetryPolicy,
 ): void {
-  const { namespace, internalFragment, defaultRetryPolicy } = config;
   const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
 
   const triggeredHooks = uow.getTriggeredHooks();
@@ -171,16 +271,45 @@ export function prepareHookMutations<THooks extends HooksMap>(
     return;
   }
 
+  const primaryNamespace = triggeredHooks[0]?.namespace;
+  DurableHooksLogger.debug("Durable hooks queued", {
+    namespace: primaryNamespace,
+    fields: () => {
+      const hookSummary = new Map<string, { namespace: string; hookName: string; count: number }>();
+      for (const hook of triggeredHooks) {
+        const key = `${hook.namespace}:${hook.hookName}`;
+        const summary = hookSummary.get(key);
+        if (summary) {
+          summary.count += 1;
+          continue;
+        }
+        hookSummary.set(key, {
+          namespace: hook.namespace,
+          hookName: hook.hookName,
+          count: 1,
+        });
+      }
+      const hooks = Array.from(hookSummary.values());
+      return {
+        hooks,
+        total: triggeredHooks.length,
+      };
+    },
+  });
+
   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;
-    const processAt = hook.options?.processAt ? new Date(hook.options.processAt) : null;
+    const rawProcessAt = hook.options?.processAt ?? null;
+    const processAt: Date | DbNow | null =
+      rawProcessAt === null ? null : isDbNow(rawProcessAt) ? rawProcessAt : new Date(rawProcessAt);
     const nextRetryAt = processAt ?? null;
-    internalUow.create("fragno_hooks", {
-      namespace,
+    const hookValues = {
+      ...(hook.options?.id !== undefined ? { id: hook.options.id } : {}),
+      namespace: hook.namespace,
       hookName: hook.hookName,
       payload: hook.payload,
       status: "pending",
@@ -190,7 +319,9 @@ export function prepareHookMutations<THooks extends HooksMap>(
       nextRetryAt,
       error: null,
       nonce: uow.idempotencyKey,
-    });
+    };
+
+    internalUow.create("fragno_hooks", hookValues);
   }
 }
 
@@ -202,68 +333,113 @@ export async function processHooks<THooks extends HooksMap>(
   config: HookProcessorConfig<THooks>,
 ): Promise<number> {
   const { hooks, namespace, internalFragment, defaultRetryPolicy } = config;
+  if (!hooks) {
+    throw new Error("Hook processor hooks not initialized.");
+  }
   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();
-
-  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();
-    });
-
-    if (stuckEvents.length > 0) {
-      try {
-        config.onStuckProcessingHooks?.({
-          namespace,
-          timeoutMinutes: stuckProcessingTimeoutMinutes,
-          events: stuckEvents,
-        });
-      } catch (error) {
-        console.error("Error calling onStuckProcessingHooks", error);
-      }
-    }
-  }
-
-  // Claim pending events in the same transaction to avoid double-processing.
-  const pendingEvents = await internalFragment.inContext(async function () {
+  const internalSchema = internalFragment.$internal.deps.schema;
+  const includeStuckProcessing = stuckProcessingTimeoutMinutes !== false;
+  const staleBefore = includeStuckProcessing
+    ? dbNow().plus({ minutes: -stuckProcessingTimeoutMinutes })
+    : null;
+  let claimedEvents: Array<{
+    id: FragnoId;
+    hookName: string;
+    payload: unknown;
+    status: HookStatus;
+    attempts: number;
+    maxAttempts: number;
+    idempotencyKey: string;
+    lastAttemptAt: Date | null;
+    nextRetryAt: Date | null;
+    createdAt: Date;
+  }> = [];
+  let stuckEvents: StuckHookProcessingEvent[] = [];
+
+  const result = await internalFragment.inContext(async function () {
     return await this.handlerTx()
-      .withServiceCalls(
-        () => [internalFragment.services.hookService.claimPendingHookEvents(namespace)] as const,
-      )
-      .transform(({ serviceResult: [events] }) => events)
+      .withServiceCalls(() => {
+        const pending = internalFragment.services.hookService.claimPendingHookEvents(namespace);
+        const stuck = includeStuckProcessing
+          ? internalFragment.services.hookService.claimStuckProcessingHookEvents(
+              namespace,
+              staleBefore!,
+            )
+          : undefined;
+        return [pending, stuck] as const;
+      })
+      .transform(({ serviceResult: [pendingEvents, stuckResult] }) => ({
+        pendingEvents,
+        stuckResult,
+      }))
       .execute();
   });
 
-  if (pendingEvents.length === 0) {
+  const pendingCount = result.pendingEvents.length;
+  const stuckClaimedCount = result.stuckResult?.events.length ?? 0;
+  const stuckRequeuedCount = result.stuckResult?.stuckEvents.length ?? 0;
+  const staleBeforeApprox = includeStuckProcessing
+    ? new Date(Date.now() - stuckProcessingTimeoutMinutes * 60_000).toISOString()
+    : null;
+  DurableHooksLogger.debug("Durable hooks claimed", {
+    namespace,
+    fields: {
+      pending: pendingCount,
+      stuck: stuckClaimedCount,
+      requeued: stuckRequeuedCount,
+      includeStuckProcessing,
+      staleBeforeApprox,
+    },
+  });
+
+  claimedEvents = [...result.pendingEvents, ...(result.stuckResult?.events ?? [])].map((event) => ({
+    ...event,
+    status: assertHookStatus(event.status),
+  }));
+  stuckEvents = result.stuckResult?.stuckEvents ?? [];
+
+  if (includeStuckProcessing && stuckEvents.length > 0) {
+    try {
+      config.onStuckProcessingHooks?.({
+        namespace,
+        timeoutMinutes: stuckProcessingTimeoutMinutes,
+        events: stuckEvents,
+      });
+    } catch (error) {
+      DurableHooksLogger.error("Error calling onStuckProcessingHooks", {
+        namespace,
+        fields: {
+          error: DurableHooksLogger.toErrorMessage(error),
+        },
+      });
+    }
+  }
+
+  if (claimedEvents.length === 0) {
+    DurableHooksLogger.debug("Durable hooks idle", {
+      namespace,
+    });
     return 0;
   }
 
   // Process events (async work outside transaction)
   const processedEvents = await Promise.allSettled(
-    pendingEvents.map(async (event) => {
+    claimedEvents.map(async (event) => {
       const hookFn = hooks[event.hookName];
       if (!hookFn) {
+        DurableHooksLogger.error("Hook missing", {
+          namespace,
+          fields: {
+            eventId: event.id,
+            hookName: event.hookName,
+            attempts: event.attempts,
+            maxAttempts: event.maxAttempts,
+            createdAt: event.createdAt.toISOString(),
+          },
+        });
         return {
           eventId: event.id,
           status: "failed" as const,
@@ -274,17 +450,56 @@ export async function processHooks<THooks extends HooksMap>(
       }
 
       try {
+        const startedAt = Date.now();
+        DurableHooksLogger.debug("Hook start", {
+          namespace,
+          fields: {
+            eventId: event.id,
+            hookName: event.hookName,
+            status: event.status,
+            attempts: event.attempts,
+            maxAttempts: event.maxAttempts,
+            createdAt: event.createdAt.toISOString(),
+            nextRetryAt: event.nextRetryAt ? event.nextRetryAt.toISOString() : null,
+            lastAttemptAt: event.lastAttemptAt ? event.lastAttemptAt.toISOString() : null,
+          },
+        });
         const hookContext: HookContext = {
           idempotencyKey: event.idempotencyKey,
+          hookId: event.id,
+          hookName: event.hookName,
+          status: event.status,
+          attempts: event.attempts,
+          maxAttempts: event.maxAttempts,
+          lastAttemptAt: event.lastAttemptAt,
+          nextRetryAt: event.nextRetryAt,
+          createdAt: event.createdAt,
           handlerTx: config.handlerTx,
         };
         await hookFn.call(hookContext, event.payload);
+        DurableHooksLogger.debug("Hook completed", {
+          namespace,
+          fields: {
+            eventId: event.id,
+            hookName: event.hookName,
+            ms: Date.now() - startedAt,
+          },
+        });
         return {
           eventId: event.id,
           status: "completed" as const,
         };
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
+        DurableHooksLogger.error("Hook failed", {
+          namespace,
+          fields: {
+            eventId: event.id.toJSON(),
+            hookName: event.hookName,
+            error: errorMessage,
+            idempotencyKey: event.idempotencyKey,
+          },
+        });
         return {
           eventId: event.id,
           status: "failed" as const,
@@ -299,31 +514,61 @@ export async function processHooks<THooks extends HooksMap>(
   // Mark events as completed/failed
   await internalFragment.inContext(async function () {
     await this.handlerTx()
-      .withServiceCalls(() => {
-        const txResults: TxResult<void>[] = [];
+      .mutate(({ forSchema }) => {
+        const uow = forSchema(internalSchema);
+        const now = dbNow();
+
         for (const processedEvent of processedEvents) {
           if (processedEvent.status === "rejected") {
+            DurableHooksLogger.error("Hook processing promise rejected", {
+              namespace,
+              fields: {
+                error: DurableHooksLogger.toErrorMessage(processedEvent.reason),
+              },
+            });
             continue;
           }
 
           const { eventId, status } = processedEvent.value;
 
           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,
-              ),
+            uow.update("fragno_hooks", eventId, (b) =>
+              b.set({ status: "completed", lastAttemptAt: now }).check(),
+            );
+            continue;
+          }
+
+          const { error, attempts } = processedEvent.value;
+          const newAttempts = attempts + 1;
+          const shouldRetry = retryPolicy.shouldRetry(newAttempts - 1);
+
+          if (shouldRetry) {
+            const delayMs = retryPolicy.getDelayMs(newAttempts - 1);
+            const nextRetryAt = now.plus({ ms: delayMs });
+            uow.update("fragno_hooks", eventId, (b) =>
+              b
+                .set({
+                  status: "pending",
+                  attempts: newAttempts,
+                  lastAttemptAt: now,
+                  nextRetryAt,
+                  error,
+                })
+                .check(),
+            );
+          } else {
+            uow.update("fragno_hooks", eventId, (b) =>
+              b
+                .set({
+                  status: "failed",
+                  attempts: newAttempts,
+                  lastAttemptAt: now,
+                  error,
+                })
+                .check(),
             );
           }
         }
-        return txResults;
       })
       .execute();
   });
@@ -333,15 +578,37 @@ export async function processHooks<THooks extends HooksMap>(
     0,
   );
 
+  const failed = processedEvents
+    .filter((result) => result.status === "fulfilled" && result.value.status === "failed")
+    .map((result) => {
+      if (result.status !== "fulfilled") {
+        return null;
+      }
+      return {
+        eventId: result.value.eventId,
+        error: result.value.error ?? null,
+      };
+    })
+    .filter(Boolean);
+
+  DurableHooksLogger.debug("Durable hooks processed", {
+    namespace,
+    fields: {
+      processed: processedCount,
+      failed: failed.length,
+      failures: failed.length > 0 ? failed : null,
+    },
+  });
+
   return processedCount;
 }
 
-export function createHookScheduler(config: HookProcessorConfig): HookScheduler {
+export function createDurableHooksRunner(config: HookProcessorConfig): DurableHooksRunner {
   let processing = false;
   let queued = false;
   let currentPromise: Promise<number> | null = null;
 
-  const schedule = async () => {
+  const processDue = async () => {
     if (processing) {
       queued = true;
       return currentPromise ?? Promise.resolve(0);
@@ -349,16 +616,17 @@ export function createHookScheduler(config: HookProcessorConfig): HookScheduler
 
     processing = true;
     currentPromise = (async () => {
-      let lastCount = 0;
+      let totalProcessed = 0;
       try {
         do {
           queued = false;
-          lastCount = await processHooks(config);
+          totalProcessed += await processHooks(config);
         } while (queued);
-        return lastCount;
+        return totalProcessed;
       } finally {
         processing = false;
         queued = false;
+        currentPromise = null;
       }
     })();
 
@@ -367,12 +635,23 @@ export function createHookScheduler(config: HookProcessorConfig): HookScheduler
 
   const drain = async () => {
     while (true) {
-      const processed = await schedule();
+      const processed = await processDue();
       if (processed === 0) {
         return;
       }
     }
   };
 
-  return { schedule, drain };
+  return { processDue, drain };
+}
+
+/**
+ * @deprecated Use createDurableHooksRunner.
+ */
+export function createHookScheduler(config: HookProcessorConfig): HookScheduler {
+  const runner = createDurableHooksRunner(config);
+  return {
+    schedule: () => runner.processDue(),
+    drain: () => runner.drain(),
+  };
 }

package/src/id.test.ts

@@ -0,0 +1,34 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createId, init } from "./id";
+
+const idPattern = /^[a-z][0-9a-z]*$/;
+
+const createCounter = (start = 0) => {
+  let value = start;
+  return () => value++;
+};
+
+describe("db id", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("re-exports the shared createId implementation", () => {
+    const id = createId();
+
+    expect(id).toHaveLength(24);
+    expect(id).toMatch(idPattern);
+  });
+
+  it("re-exports init for deterministic generators", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    const first = init({ random: () => 0, counter: createCounter(0), fingerprint: "fingerprint" });
+    const second = init({ random: () => 0, counter: createCounter(0), fingerprint: "fingerprint" });
+
+    expect(first()).toBe(second());
+  });
+});

package/src/id.ts

@@ -1,3 +1 @@
-import { createId } from "@paralleldrive/cuid2";
-
-export { createId };
+export { createId, init } from "@fragno-dev/core";