@fragno-dev/db 0.3.0 → 0.4.1

package/src/dispatchers/cloudflare-do/index.test.ts

@@ -1,33 +1,52 @@
-import { describe, expect, it, vi } from "vitest";
-import { createDurableHooksDispatcherDurableObject } from "./index";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { DurableHooksLogger } from "../../hooks/durable-hooks-logger";
+import { createDurableHooksDispatcherDurableObject } from "./dispatcher";
 
 describe("createDurableHooksDispatcherDurableObject", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
   it("should schedule an initial alarm on creation", async () => {
-    const process = vi.fn().mockResolvedValue(0);
+    const processDue = vi.fn().mockResolvedValue(0);
     const getNextWakeAt = vi.fn().mockResolvedValue(new Date());
     const drain = vi.fn().mockResolvedValue(undefined);
     const setAlarm = vi.fn().mockResolvedValue(undefined);
 
     const handlerFactory = createDurableHooksDispatcherDurableObject({
-      createProcessor: () => ({ process, getNextWakeAt, drain, namespace: "test" }),
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
     });
 
     handlerFactory({ storage: { setAlarm } }, {});
 
     await Promise.resolve();
     expect(setAlarm).toHaveBeenCalledTimes(1);
-    expect(process).not.toHaveBeenCalled();
+    expect(processDue).not.toHaveBeenCalled();
   });
 
   it("should delete the alarm when no pending hooks exist", async () => {
-    const process = vi.fn().mockResolvedValue(0);
+    const processDue = vi.fn().mockResolvedValue(0);
     const getNextWakeAt = vi.fn().mockResolvedValue(null);
     const drain = vi.fn().mockResolvedValue(undefined);
     const setAlarm = vi.fn().mockResolvedValue(undefined);
     const deleteAlarm = vi.fn().mockResolvedValue(undefined);
 
     const handlerFactory = createDurableHooksDispatcherDurableObject({
-      createProcessor: () => ({ process, getNextWakeAt, drain, namespace: "test" }),
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
     });
 
     const handler = handlerFactory({ storage: { setAlarm, deleteAlarm } }, {});
@@ -37,24 +56,61 @@ describe("createDurableHooksDispatcherDurableObject", () => {
 
     await handler.alarm?.();
 
-    expect(process).toHaveBeenCalledTimes(1);
-    expect(deleteAlarm).toHaveBeenCalledTimes(2);
+    expect(processDue).toHaveBeenCalledTimes(1);
+    expect(deleteAlarm).toHaveBeenCalledTimes(1);
     expect(setAlarm).not.toHaveBeenCalled();
   });
 
+  it("should schedule alarm on notify and forward promise to waitUntil", async () => {
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date("2024-01-01T00:00:00Z"));
+    const drain = vi.fn().mockResolvedValue(undefined);
+    const setAlarm = vi.fn().mockResolvedValue(undefined);
+
+    const handlerFactory = createDurableHooksDispatcherDurableObject({
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm } }, {});
+    await Promise.resolve();
+    expect(setAlarm).toHaveBeenCalledTimes(1);
+
+    const waitUntil = vi.fn();
+    handler.notify?.({ source: "request", waitUntil });
+
+    expect(waitUntil).toHaveBeenCalledTimes(1);
+    const [notifyPromise] = waitUntil.mock.calls[0] as [Promise<void>];
+    await notifyPromise;
+
+    expect(processDue).not.toHaveBeenCalled();
+    expect(setAlarm).toHaveBeenCalledTimes(2);
+  });
+
   it("should schedule alarm using max(nextWakeAt, now)", async () => {
     vi.useFakeTimers();
     const now = new Date("2024-01-01T00:00:00Z");
     vi.setSystemTime(now);
 
-    const process = vi.fn().mockResolvedValue(0);
+    const processDue = vi.fn().mockResolvedValue(0);
     const getNextWakeAt = vi.fn().mockResolvedValue(new Date(now.getTime() - 10000));
     const drain = vi.fn().mockResolvedValue(undefined);
     const setAlarm = vi.fn().mockResolvedValue(undefined);
     const deleteAlarm = vi.fn().mockResolvedValue(undefined);
 
     const handlerFactory = createDurableHooksDispatcherDurableObject({
-      createProcessor: () => ({ process, getNextWakeAt, drain, namespace: "test" }),
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
     });
 
     const handler = handlerFactory({ storage: { setAlarm, deleteAlarm } }, {});
@@ -64,10 +120,87 @@ describe("createDurableHooksDispatcherDurableObject", () => {
 
     await handler.alarm?.();
 
-    expect(setAlarm).toHaveBeenCalledTimes(2);
+    expect(setAlarm.mock.calls.length).toBeGreaterThanOrEqual(1);
     for (const [scheduledAt] of setAlarm.mock.calls) {
       expect(scheduledAt.getTime()).toBeGreaterThanOrEqual(now.getTime());
     }
     vi.useRealTimers();
   });
+
+  it("should recover alarm processing when onProcessError throws", async () => {
+    const processFailure = new Error("process failed");
+    const processDue = vi.fn().mockRejectedValueOnce(processFailure).mockResolvedValueOnce(0);
+    const getNextWakeAt = vi.fn().mockResolvedValue(new Date("2024-01-01T00:00:00Z"));
+    const drain = vi.fn().mockResolvedValue(undefined);
+    const setAlarm = vi.fn().mockResolvedValue(undefined);
+    const onProcessError = vi.fn(() => {
+      throw new Error("callback failed");
+    });
+    const errorSpy = vi.spyOn(DurableHooksLogger, "error").mockImplementation(() => {});
+
+    const handlerFactory = createDurableHooksDispatcherDurableObject({
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
+      onProcessError,
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm } }, {});
+    await Promise.resolve();
+
+    await handler.alarm?.();
+    await handler.alarm?.();
+    await Promise.resolve();
+
+    expect(processDue).toHaveBeenCalledTimes(2);
+    expect(onProcessError).toHaveBeenCalledWith(processFailure);
+    expect(
+      errorSpy.mock.calls.some(
+        ([message]) => message === "Durable hooks dispatcher onProcessError callback failed",
+      ),
+    ).toBe(true);
+  });
+
+  it("should resolve notify when onProcessError throws in schedule error path", async () => {
+    const scheduleFailure = new Error("schedule failed");
+    const processDue = vi.fn().mockResolvedValue(0);
+    const getNextWakeAt = vi
+      .fn()
+      .mockResolvedValueOnce(new Date("2024-01-01T00:00:00Z"))
+      .mockRejectedValueOnce(scheduleFailure);
+    const drain = vi.fn().mockResolvedValue(undefined);
+    const setAlarm = vi.fn().mockResolvedValue(undefined);
+    const onProcessError = vi.fn(() => {
+      throw new Error("callback failed");
+    });
+    const errorSpy = vi.spyOn(DurableHooksLogger, "error").mockImplementation(() => {});
+
+    const handlerFactory = createDurableHooksDispatcherDurableObject({
+      createProcessor: () => ({
+        processDue,
+        process: processDue,
+        getNextWakeAt,
+        drain,
+        namespace: "test",
+      }),
+      onProcessError,
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm } }, {});
+    await Promise.resolve();
+
+    await handler.notify?.({ source: "request" });
+    await Promise.resolve();
+
+    expect(onProcessError).toHaveBeenCalledWith(scheduleFailure);
+    expect(
+      errorSpy.mock.calls.some(
+        ([message]) => message === "Durable hooks dispatcher onProcessError callback failed",
+      ),
+    ).toBe(true);
+  });
 });

package/src/dispatchers/cloudflare-do/index.ts

@@ -1,104 +1,63 @@
-import type { DurableHooksProcessor } from "../../hooks/durable-hooks-processor";
-
-type AlarmStorage = {
-  setAlarm?: (timestamp: number | Date) => Promise<void>;
-  deleteAlarm?: () => Promise<void>;
-};
-
-export type DurableHooksDispatcherDurableObjectState = {
-  readonly storage: AlarmStorage;
+import { createDurableHooksProcessorGroup } from "../../hooks/durable-hooks-processor";
+import { getDurableHooksRuntimeByToken } from "../../hooks/durable-hooks-runtime";
+import type { AnyFragnoInstantiatedDatabaseFragment } from "../../mod";
+import {
+  createDurableHooksDispatcherDurableObject,
+  type DurableHooksDispatcherDurableObjectFactory,
+  type DurableHooksDispatcherDurableObjectHandler,
+  type DurableHooksDispatcherDurableObjectState,
+} from "./dispatcher";
+
+export type DurableHooksProcessorOptions = {
+  onProcessError?: (error: unknown) => void;
 };
 
-export type DurableHooksDispatcherDurableObjectHandler = {
-  fetch?: (request: Request) => Promise<Response>;
-  alarm?: () => Promise<void>;
+export type {
+  DurableHooksDispatcherDurableObjectFactory,
+  DurableHooksDispatcherDurableObjectHandler,
+  DurableHooksDispatcherDurableObjectState,
 };
 
-export type DurableHooksDispatcherDurableObjectFactory<TEnv = unknown> = (
-  state: DurableHooksDispatcherDurableObjectState,
-  env: TEnv,
-) => DurableHooksDispatcherDurableObjectHandler;
-
-export type DurableHooksDispatcherDurableObjectOptions<TEnv = unknown> = {
-  createProcessor: (context: {
-    state: DurableHooksDispatcherDurableObjectState;
-    env: TEnv;
-  }) => DurableHooksProcessor;
-  onProcessError?: (error: unknown) => void;
+type DurableHooksInternal = {
+  durableHooksToken?: object;
 };
 
-export function createDurableHooksDispatcherDurableObject<TEnv>(
-  options: DurableHooksDispatcherDurableObjectOptions<TEnv>,
+export function createDurableHooksProcessor<TEnv>(
+  fragments: readonly AnyFragnoInstantiatedDatabaseFragment[],
+  options: DurableHooksProcessorOptions = {},
 ): DurableHooksDispatcherDurableObjectFactory<TEnv> {
-  return (state, env) => {
-    const processor = options.createProcessor({ state, env });
-    const onProcessError =
-      options.onProcessError ??
-      ((error: unknown) => {
-        console.error("Durable hooks dispatcher error", error);
-      });
-    const rawSetAlarm = state.storage.setAlarm;
-    const rawDeleteAlarm = state.storage.deleteAlarm;
-
-    if (!rawSetAlarm) {
-      throw new Error(
-        "Durable hooks dispatcher requires state.storage.setAlarm to schedule alarms.",
-      );
-    }
-    const setAlarm = rawSetAlarm.bind(state.storage);
-    const deleteAlarm = rawDeleteAlarm?.bind(state.storage);
-
-    let processing = false;
-    let queued = false;
-    let currentPromise: Promise<void> | undefined;
-
-    const runProcess = () => {
-      if (processing) {
-        queued = true;
-        return currentPromise ?? Promise.resolve();
-      }
+  const processor = createDurableHooksProcessorGroup(fragments, {
+    onError: options.onProcessError,
+  });
+  const factory = createDurableHooksDispatcherDurableObject<TEnv>({
+    createProcessor: () => processor,
+    onProcessError: options.onProcessError,
+  });
 
-      processing = true;
-      currentPromise = (async () => {
-        do {
-          queued = false;
-          try {
-            await processor.process();
-          } catch (error) {
-            onProcessError(error);
-          }
-        } while (queued);
-        processing = false;
-      })();
-
-      return currentPromise;
+  return (state, env) => {
+    const handler = factory(state, env);
+    const notifier = {
+      notify: (context: Parameters<NonNullable<typeof handler.notify>>[0]) => {
+        if (!handler.notify) {
+          return;
+        }
+        return handler.notify(context);
+      },
     };
 
-    const scheduleNextAlarm = async () => {
-      const nextWakeAt = await processor.getNextWakeAt();
-      if (!nextWakeAt) {
-        await deleteAlarm?.();
-        return;
+    for (const fragment of fragments) {
+      const internal = fragment.$internal as DurableHooksInternal | undefined;
+      const durableHooksToken = internal?.durableHooksToken;
+      if (!durableHooksToken) {
+        continue;
       }
+      const runtime = getDurableHooksRuntimeByToken(durableHooksToken);
+      if (!runtime) {
+        continue;
+      }
+      runtime.config.notifier = notifier;
+    }
 
-      const now = Date.now();
-      const scheduledAt = new Date(Math.max(nextWakeAt.getTime(), now));
-      await setAlarm(scheduledAt);
-    };
-
-    void scheduleNextAlarm().catch((error) => {
-      onProcessError(error);
-    });
-
-    return {
-      alarm: async () => {
-        try {
-          await runProcess();
-          await scheduleNextAlarm();
-        } catch (error) {
-          onProcessError(error);
-        }
-      },
-    };
+    return handler;
   };
 }

package/src/dispatchers/node/dispatcher.ts

@@ -0,0 +1,112 @@
+import { DurableHooksLogger } from "../../hooks/durable-hooks-logger";
+import type { DurableHooksProcessor } from "../../hooks/durable-hooks-processor";
+import type { HookNotifyContext } from "../../hooks/hooks";
+
+export type DurableHooksDispatcher = {
+  notify: (context: HookNotifyContext) => void;
+  wake: () => Promise<void>;
+  drain: () => Promise<void>;
+  startPolling: () => void;
+  stopPolling: () => void;
+};
+
+export type DurableHooksDispatcherOptions = {
+  processor: DurableHooksProcessor;
+  pollIntervalMs?: number;
+  onError?: (error: unknown) => void;
+};
+
+export function createDurableHooksDispatcher(
+  options: DurableHooksDispatcherOptions,
+): DurableHooksDispatcher {
+  const pollIntervalMs = options.pollIntervalMs ?? 5000;
+  const onError =
+    options.onError ??
+    ((error: unknown) => {
+      DurableHooksLogger.error("Durable hooks dispatcher error", {
+        namespace: options.processor.namespace,
+        fields: { error: DurableHooksLogger.toErrorMessage(error) },
+      });
+    });
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let processing = false;
+  let queued = false;
+  let notifyQueued = false;
+  let currentPromise: Promise<void> | undefined;
+
+  const runProcess = () => {
+    if (processing) {
+      queued = true;
+      return currentPromise ?? Promise.resolve();
+    }
+
+    processing = true;
+    currentPromise = (async () => {
+      do {
+        queued = false;
+        try {
+          await options.processor.processDue();
+        } catch (error) {
+          onError(error);
+        }
+      } while (queued);
+      processing = false;
+    })();
+
+    return currentPromise;
+  };
+
+  const poll = async () => {
+    try {
+      const nextWakeAt = await options.processor.getNextWakeAt();
+      if (!nextWakeAt) {
+        return;
+      }
+      if (Date.now() >= nextWakeAt.getTime()) {
+        await runProcess();
+      }
+    } catch (error) {
+      onError(error);
+    }
+  };
+
+  return {
+    notify: (_context) => {
+      if (notifyQueued) {
+        return;
+      }
+      notifyQueued = true;
+      setTimeout(() => {
+        notifyQueued = false;
+        void runProcess();
+      }, 0);
+    },
+    wake: async () => {
+      await runProcess();
+    },
+    drain: async () => {
+      try {
+        await options.processor.drain();
+      } catch (error) {
+        onError(error);
+      }
+    },
+    startPolling: () => {
+      if (timer) {
+        return;
+      }
+
+      timer = setInterval(() => {
+        void poll();
+      }, pollIntervalMs);
+    },
+    stopPolling: () => {
+      if (!timer) {
+        return;
+      }
+
+      clearInterval(timer);
+      timer = undefined;
+    },
+  };
+}

package/src/dispatchers/node/index.test.ts

@@ -1,19 +1,47 @@
 import { describe, expect, it, vi } from "vitest";
-import { createDurableHooksDispatcher } from "./index";
+
+import { createDurableHooksDispatcher } from "./dispatcher";
 
 describe("createDurableHooksDispatcher", () => {
+  it("should notify via macrotask wake hint", async () => {
+    vi.useFakeTimers();
+    try {
+      const processDue = vi.fn().mockResolvedValue(0);
+      const dispatcher = createDurableHooksDispatcher({
+        processor: {
+          processDue,
+          process: processDue,
+          getNextWakeAt: vi.fn().mockResolvedValue(null),
+          drain: vi.fn().mockResolvedValue(undefined),
+          namespace: "test",
+        },
+      });
+
+      dispatcher.notify({ source: "request" });
+      dispatcher.notify({ source: "request" });
+
+      expect(processDue).toHaveBeenCalledTimes(0);
+      await Promise.resolve();
+      expect(processDue).toHaveBeenCalledTimes(0);
+      await vi.advanceTimersByTimeAsync(0);
+      expect(processDue).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("should wake and process hooks", async () => {
-    const process = vi.fn().mockResolvedValue(0);
+    const processDue = vi.fn().mockResolvedValue(0);
     const getNextWakeAt = vi.fn().mockResolvedValue(null);
     const drain = vi.fn().mockResolvedValue(undefined);
 
     const dispatcher = createDurableHooksDispatcher({
-      processor: { process, getNextWakeAt, drain, namespace: "test" },
+      processor: { processDue, process: processDue, getNextWakeAt, drain, namespace: "test" },
     });
 
     await dispatcher.wake();
 
-    expect(process).toHaveBeenCalledTimes(1);
+    expect(processDue).toHaveBeenCalledTimes(1);
   });
 
   it("should coalesce overlapping wake calls", async () => {
@@ -21,12 +49,13 @@ describe("createDurableHooksDispatcher", () => {
     const firstPromise = new Promise<number>((resolve) => {
       resolveFirst = resolve;
     });
-    const process = vi.fn().mockReturnValueOnce(firstPromise).mockResolvedValue(0);
+    const processDue = vi.fn().mockReturnValueOnce(firstPromise).mockResolvedValue(0);
     const drain = vi.fn().mockResolvedValue(undefined);
 
     const dispatcher = createDurableHooksDispatcher({
       processor: {
-        process,
+        processDue,
+        process: processDue,
         getNextWakeAt: vi.fn().mockResolvedValue(null),
         drain,
         namespace: "test",
@@ -36,13 +65,13 @@ describe("createDurableHooksDispatcher", () => {
     const first = dispatcher.wake();
     const second = dispatcher.wake();
 
-    expect(process).toHaveBeenCalledTimes(1);
+    expect(processDue).toHaveBeenCalledTimes(1);
 
     resolveFirst(0);
     await first;
     await second;
 
-    expect(process).toHaveBeenCalledTimes(2);
+    expect(processDue).toHaveBeenCalledTimes(2);
   });
 
   it("should poll and process when due", async () => {
@@ -50,12 +79,12 @@ describe("createDurableHooksDispatcher", () => {
     const now = new Date("2024-01-01T00:00:00Z");
     vi.setSystemTime(now);
 
-    const process = vi.fn().mockResolvedValue(0);
+    const processDue = vi.fn().mockResolvedValue(0);
     const getNextWakeAt = vi.fn().mockResolvedValue(new Date(now.getTime() - 1000));
     const drain = vi.fn().mockResolvedValue(undefined);
 
     const dispatcher = createDurableHooksDispatcher({
-      processor: { process, getNextWakeAt, drain, namespace: "test" },
+      processor: { processDue, process: processDue, getNextWakeAt, drain, namespace: "test" },
       pollIntervalMs: 1000,
     });
 
@@ -63,7 +92,7 @@ describe("createDurableHooksDispatcher", () => {
     await vi.advanceTimersByTimeAsync(1000);
     dispatcher.stopPolling();
 
-    expect(process).toHaveBeenCalledTimes(1);
+    expect(processDue).toHaveBeenCalledTimes(1);
     vi.useRealTimers();
   });
 
@@ -72,12 +101,12 @@ describe("createDurableHooksDispatcher", () => {
     const now = new Date("2024-01-01T00:00:00Z");
     vi.setSystemTime(now);
 
-    const process = vi.fn().mockResolvedValue(0);
+    const processDue = vi.fn().mockResolvedValue(0);
     const getNextWakeAt = vi.fn().mockResolvedValue(new Date(now.getTime() + 60000));
     const drain = vi.fn().mockResolvedValue(undefined);
 
     const dispatcher = createDurableHooksDispatcher({
-      processor: { process, getNextWakeAt, drain, namespace: "test" },
+      processor: { processDue, process: processDue, getNextWakeAt, drain, namespace: "test" },
       pollIntervalMs: 1000,
     });
 
@@ -85,7 +114,7 @@ describe("createDurableHooksDispatcher", () => {
     await vi.advanceTimersByTimeAsync(1000);
     dispatcher.stopPolling();
 
-    expect(process).not.toHaveBeenCalled();
+    expect(processDue).not.toHaveBeenCalled();
     vi.useRealTimers();
   });
 });