@fragno-dev/db 0.2.2 → 0.3.0

package/src/db-fragment-instantiator.test.ts

@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { describe, it, expect, vi, assert } from "vitest";
 import { instantiate, defineFragment } from "@fragno-dev/core";
 import { defineRoutes } from "@fragno-dev/core/route";
@@ -7,14 +10,22 @@ import type { DatabaseAdapter } from "./adapters/adapters";
 import type { SimpleQueryInterface } from "./query/simple-query-interface";
 import { RequestContextStorage } from "@fragno-dev/core/internal/request-context-storage";
 import { z } from "zod";
+import { suffixNamingStrategy } from "./naming/sql-naming";
 
 // Create a test schema
-const testSchema = schema((s) => {
+const testSchema = schema("test", (s) => {
   return s.addTable("users", (t) => {
     return t.addColumn("id", idColumn()).addColumn("name", column("string"));
   });
 });
 
+// Schema with dashes in the name (used to test namespace sanitization)
+const dashedSchema = schema("my-fragment", (s) => {
+  return s.addTable("items", (t) => {
+    return t.addColumn("id", idColumn()).addColumn("label", column("string"));
+  });
+});
+
 type TestSchema = typeof testSchema;
 
 // Mock database adapter
@@ -35,6 +46,8 @@ function createMockAdapter(): DatabaseAdapter {
           mutationPhase: Promise.resolve(),
         })),
         restrict: vi.fn(() => createMockRestrictedUow()),
+        getRetrievalOperations: vi.fn(() => []),
+        getMutationOperations: vi.fn(() => []),
         table: vi.fn(() => ({
           findMany: vi.fn(),
         })),
@@ -61,7 +74,11 @@ function createMockAdapter(): DatabaseAdapter {
         executeMutations: vi.fn(async () => ({ success: true })),
         commit: vi.fn(),
         rollback: vi.fn(),
+        registerSchema: vi.fn(),
         reset: vi.fn(),
+        getRetrievalOperations: vi.fn(() => []),
+        getMutationOperations: vi.fn(() => []),
+        getCreatedIds: vi.fn(() => []),
         table: vi.fn(() => ({
           findMany: vi.fn(),
         })),
@@ -74,10 +91,11 @@ function createMockAdapter(): DatabaseAdapter {
 
   return {
     createQueryEngine: vi.fn(() => mockdb),
-    migrate: vi.fn(),
+    getSchemaVersion: vi.fn(async () => undefined),
     close: vi.fn(),
     type: "mock",
     contextStorage: new RequestContextStorage(),
+    namingStrategy: suffixNamingStrategy,
   } as unknown as DatabaseAdapter;
 }
 
@@ -206,7 +224,7 @@ describe("db-fragment-instantiator", () => {
 
   describe("database operations with UOW", () => {
     it("should allow accessing schema-typed UOW in handlers via handlerTx", async () => {
-      const testSchemaWithCounter = schema((s) => {
+      const testSchemaWithCounter = schema("testschemawithcounter", (s) => {
         return s.addTable("counters", (t) => {
           return t.addColumn("id", idColumn()).addColumn("value", column("integer"));
         });
@@ -447,7 +465,73 @@ describe("db-fragment-instantiator", () => {
         .build();
 
       expect(fragment.$internal.deps.schema).toBe(testSchema);
-      expect(fragment.$internal.deps.namespace).toBe("test-db-fragment");
+      expect(fragment.$internal.deps.namespace).toBe("test");
+    });
+
+    it("should use databaseNamespace override when provided", () => {
+      const definition = defineFragment("test-db-fragment")
+        .extend(withDatabase(testSchema))
+        .build();
+
+      const mockAdapter = createMockAdapter();
+      const fragment = instantiate(definition)
+        .withOptions({
+          mountRoute: "/api",
+          databaseAdapter: mockAdapter,
+          databaseNamespace: "custom-namespace",
+        })
+        .build();
+
+      expect(fragment.$internal.deps.namespace).toBe("custom-namespace");
+    });
+
+    it("should allow explicit null namespace override", () => {
+      const definition = defineFragment("test-db-fragment")
+        .extend(withDatabase(testSchema))
+        .build();
+
+      const mockAdapter = createMockAdapter();
+      const fragment = instantiate(definition)
+        .withOptions({
+          mountRoute: "/api",
+          databaseAdapter: mockAdapter,
+          databaseNamespace: null,
+        })
+        .build();
+
+      expect(fragment.$internal.deps.namespace).toBeNull();
+    });
+
+    it("should sanitize dashes in schema.name when used as default namespace", () => {
+      const definition = defineFragment("test-dashed-fragment")
+        .extend(withDatabase(dashedSchema))
+        .build();
+
+      const mockAdapter = createMockAdapter();
+      const fragment = instantiate(definition)
+        .withOptions({ mountRoute: "/api", databaseAdapter: mockAdapter })
+        .build();
+
+      // schema.name is "my-fragment", but default namespace should be sanitized to "my_fragment"
+      expect(fragment.$internal.deps.namespace).toBe("my_fragment");
+    });
+
+    it("should NOT sanitize explicit databaseNamespace even when it contains dashes", () => {
+      const definition = defineFragment("test-dashed-fragment")
+        .extend(withDatabase(dashedSchema))
+        .build();
+
+      const mockAdapter = createMockAdapter();
+      const fragment = instantiate(definition)
+        .withOptions({
+          mountRoute: "/api",
+          databaseAdapter: mockAdapter,
+          databaseNamespace: "my-fragment",
+        })
+        .build();
+
+      // Explicit override should be used as-is, dashes preserved
+      expect(fragment.$internal.deps.namespace).toBe("my-fragment");
     });
 
     it("should populate $internal when using providesBaseService without withDependencies", () => {
@@ -478,18 +562,26 @@ describe("db-fragment-instantiator", () => {
     });
   });
 
-  describe("error handling", () => {
-    it("should throw when databaseAdapter is not provided", () => {
+  describe("default adapter", () => {
+    it("should default to sqlite adapter when databaseAdapter is not provided", () => {
       const definition = defineFragment("test-db-fragment")
         .extend(withDatabase(testSchema))
         .build();
-
-      expect(() => {
-        instantiate(definition)
-          // @ts-expect-error - Test case
-          .withOptions({})
-          .build();
-      }).toThrow("Database fragment requires a database adapter");
+      const previous = process.env["FRAGNO_DATA_DIR"];
+      const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "fragno-db-default-"));
+      process.env["FRAGNO_DATA_DIR"] = dataDir;
+
+      try {
+        const fragment = instantiate(definition).withOptions({}).build();
+        expect(fragment.$internal.options.databaseAdapter).toBeDefined();
+        expect(fragment.$internal.deps.db).toBeDefined();
+      } finally {
+        if (previous === undefined) {
+          delete process.env["FRAGNO_DATA_DIR"];
+        } else {
+          process.env["FRAGNO_DATA_DIR"] = previous;
+        }
+      }
     });
 
     it("should throw when serviceTx called outside request context", () => {

package/src/db-fragment-integration.test.ts

@@ -1,7 +1,7 @@
 import { SQLocalKysely } from "sqlocal/kysely";
 import { assert, beforeAll, describe, expect, it } from "vitest";
 import { z } from "zod";
-import { KyselyAdapter } from "./adapters/kysely/kysely-adapter";
+import { SqlAdapter } from "./adapters/generic-sql/generic-sql-adapter";
 import { column, idColumn, referenceColumn, schema, type FragnoId } from "./schema/create";
 import { defineFragment, instantiate } from "@fragno-dev/core";
 import { defineRoutes } from "@fragno-dev/core/route";
@@ -12,7 +12,7 @@ import { SQLocalDriverConfig } from "./adapters/generic-sql/driver-config";
 
 describe.sequential("Database Fragment Integration", () => {
   // Schema 1: Users fragment
-  const usersSchema = schema((s) => {
+  const usersSchema = schema("users", (s) => {
     return s
       .addTable("users", (t) => {
         return t
@@ -36,7 +36,7 @@ describe.sequential("Database Fragment Integration", () => {
   });
 
   // Schema 2: Orders fragment
-  const ordersSchema = schema((s) => {
+  const ordersSchema = schema("orders", (s) => {
     return s.addTable("orders", (t) => {
       return t
         .addColumn("id", idColumn())
@@ -50,7 +50,7 @@ describe.sequential("Database Fragment Integration", () => {
 
   // Define Users Fragment using the new unified serviceTx API
   const usersFragmentDef = defineFragment("users-fragment")
-    .extend(withDatabase(usersSchema, "users"))
+    .extend(withDatabase(usersSchema))
     .providesService("userService", ({ defineService }) => {
       return defineService({
         // Creates a user - returns TxResult<FragnoId>
@@ -118,7 +118,7 @@ describe.sequential("Database Fragment Integration", () => {
 
   // Define Orders Fragment with cross-fragment service dependency using new serviceTx API
   const ordersFragmentDef = defineFragment("orders-fragment")
-    .extend(withDatabase(ordersSchema, "orders"))
+    .extend(withDatabase(ordersSchema))
     .usesService<
       "userService",
       {
@@ -209,7 +209,7 @@ describe.sequential("Database Fragment Integration", () => {
     }),
   ]);
 
-  let adapter: KyselyAdapter;
+  let adapter: SqlAdapter;
   let usersFragment: ReturnType<typeof instantiateUsersFragment>;
   let ordersFragment: ReturnType<typeof instantiateOrdersFragment>;
 
@@ -239,7 +239,7 @@ describe.sequential("Database Fragment Integration", () => {
   beforeAll(async () => {
     // Create in-memory SQLite database with Kysely
     const { dialect } = new SQLocalKysely(":memory:");
-    adapter = new KyselyAdapter({
+    adapter = new SqlAdapter({
       dialect,
       driverConfig: new SQLocalDriverConfig(),
     });
@@ -414,6 +414,8 @@ describe.sequential("Database Fragment Integration", () => {
 
     const result = await usersFragment.inContext(async function () {
       return await this.handlerTx()
+        // Add a retrieve op so retry is allowed for the forced conflict below.
+        .retrieve(({ forSchema }) => forSchema(usersSchema).find("users"))
         .mutate(({ forSchema, idempotencyKey, currentAttempt }) => {
           if (currentAttempt === 0) {
             firstIdempotencyKey = idempotencyKey;

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

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from "vitest";
+import { createDurableHooksDispatcherDurableObject } from "./index";
+
+describe("createDurableHooksDispatcherDurableObject", () => {
+  it("should schedule an initial alarm on creation", async () => {
+    const process = 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" }),
+    });
+
+    handlerFactory({ storage: { setAlarm } }, {});
+
+    await Promise.resolve();
+    expect(setAlarm).toHaveBeenCalledTimes(1);
+    expect(process).not.toHaveBeenCalled();
+  });
+
+  it("should delete the alarm when no pending hooks exist", async () => {
+    const process = 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" }),
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm, deleteAlarm } }, {});
+
+    await Promise.resolve();
+    expect(getNextWakeAt).toHaveBeenCalledTimes(1);
+
+    await handler.alarm?.();
+
+    expect(process).toHaveBeenCalledTimes(1);
+    expect(deleteAlarm).toHaveBeenCalledTimes(2);
+    expect(setAlarm).not.toHaveBeenCalled();
+  });
+
+  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 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" }),
+    });
+
+    const handler = handlerFactory({ storage: { setAlarm, deleteAlarm } }, {});
+
+    await Promise.resolve();
+    expect(setAlarm).toHaveBeenCalledTimes(1);
+
+    await handler.alarm?.();
+
+    expect(setAlarm).toHaveBeenCalledTimes(2);
+    for (const [scheduledAt] of setAlarm.mock.calls) {
+      expect(scheduledAt.getTime()).toBeGreaterThanOrEqual(now.getTime());
+    }
+    vi.useRealTimers();
+  });
+});

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

@@ -0,0 +1,104 @@
+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;
+};
+
+export type DurableHooksDispatcherDurableObjectHandler = {
+  fetch?: (request: Request) => Promise<Response>;
+  alarm?: () => Promise<void>;
+};
+
+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;
+};
+
+export function createDurableHooksDispatcherDurableObject<TEnv>(
+  options: DurableHooksDispatcherDurableObjectOptions<TEnv>,
+): 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();
+      }
+
+      processing = true;
+      currentPromise = (async () => {
+        do {
+          queued = false;
+          try {
+            await processor.process();
+          } catch (error) {
+            onProcessError(error);
+          }
+        } while (queued);
+        processing = false;
+      })();
+
+      return currentPromise;
+    };
+
+    const scheduleNextAlarm = async () => {
+      const nextWakeAt = await processor.getNextWakeAt();
+      if (!nextWakeAt) {
+        await deleteAlarm?.();
+        return;
+      }
+
+      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);
+        }
+      },
+    };
+  };
+}

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

@@ -0,0 +1,91 @@
+import { describe, expect, it, vi } from "vitest";
+import { createDurableHooksDispatcher } from "./index";
+
+describe("createDurableHooksDispatcher", () => {
+  it("should wake and process hooks", async () => {
+    const process = 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" },
+    });
+
+    await dispatcher.wake();
+
+    expect(process).toHaveBeenCalledTimes(1);
+  });
+
+  it("should coalesce overlapping wake calls", async () => {
+    let resolveFirst!: (value: number) => void;
+    const firstPromise = new Promise<number>((resolve) => {
+      resolveFirst = resolve;
+    });
+    const process = vi.fn().mockReturnValueOnce(firstPromise).mockResolvedValue(0);
+    const drain = vi.fn().mockResolvedValue(undefined);
+
+    const dispatcher = createDurableHooksDispatcher({
+      processor: {
+        process,
+        getNextWakeAt: vi.fn().mockResolvedValue(null),
+        drain,
+        namespace: "test",
+      },
+    });
+
+    const first = dispatcher.wake();
+    const second = dispatcher.wake();
+
+    expect(process).toHaveBeenCalledTimes(1);
+
+    resolveFirst(0);
+    await first;
+    await second;
+
+    expect(process).toHaveBeenCalledTimes(2);
+  });
+
+  it("should poll and process when due", async () => {
+    vi.useFakeTimers();
+    const now = new Date("2024-01-01T00:00:00Z");
+    vi.setSystemTime(now);
+
+    const process = 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" },
+      pollIntervalMs: 1000,
+    });
+
+    dispatcher.startPolling();
+    await vi.advanceTimersByTimeAsync(1000);
+    dispatcher.stopPolling();
+
+    expect(process).toHaveBeenCalledTimes(1);
+    vi.useRealTimers();
+  });
+
+  it("should skip polling when next wake is in the future", async () => {
+    vi.useFakeTimers();
+    const now = new Date("2024-01-01T00:00:00Z");
+    vi.setSystemTime(now);
+
+    const process = 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" },
+      pollIntervalMs: 1000,
+    });
+
+    dispatcher.startPolling();
+    await vi.advanceTimersByTimeAsync(1000);
+    dispatcher.stopPolling();
+
+    expect(process).not.toHaveBeenCalled();
+    vi.useRealTimers();
+  });
+});

package/src/dispatchers/node/index.ts

@@ -0,0 +1,87 @@
+import type { DurableHooksProcessor } from "../../hooks/durable-hooks-processor";
+
+export type DurableHooksDispatcher = {
+  wake: () => 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) => {
+      console.error("Durable hooks dispatcher error", error);
+    });
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let processing = false;
+  let queued = 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.process();
+        } 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 {
+    wake: async () => {
+      await runProcess();
+    },
+    startPolling: () => {
+      if (timer) {
+        return;
+      }
+
+      timer = setInterval(() => {
+        void poll();
+      }, pollIntervalMs);
+    },
+    stopPolling: () => {
+      if (!timer) {
+        return;
+      }
+
+      clearInterval(timer);
+      timer = undefined;
+    },
+  };
+}

package/src/fragments/internal-fragment.routes.ts

@@ -0,0 +1,42 @@
+import { defineRoutes } from "@fragno-dev/core";
+import { internalFragmentDef } from "./internal-fragment";
+
+export const internalFragmentRoutes = defineRoutes(internalFragmentDef).create(
+  ({ defineRoute, services }) => [
+    defineRoute({
+      method: "GET",
+      path: "/outbox",
+      handler: async function (input, { json }) {
+        // We intentionally skip input/output schemas here to keep the internal route lightweight.
+        // Query params are validated manually and the response shape is stable (OutboxEntry[]),
+        // while the public API surface is still gated behind adapter config.
+        const afterVersionstamp = input.query.get("afterVersionstamp") ?? undefined;
+        const limitValue = input.query.get("limit");
+        let limit: number | undefined;
+
+        if (limitValue !== null) {
+          const parsed = Number.parseInt(limitValue, 10);
+          if (!Number.isFinite(parsed) || parsed < 1) {
+            return json(
+              {
+                error: "Invalid limit query parameter.",
+                code: "INVALID_LIMIT",
+              },
+              { status: 400 },
+            );
+          }
+          limit = parsed;
+        }
+
+        const entries = await this.handlerTx()
+          .withServiceCalls(
+            () => [services.outboxService.list({ afterVersionstamp, limit })] as const,
+          )
+          .transform(({ serviceResult: [result] }) => result)
+          .execute();
+
+        return json(entries);
+      },
+    }),
+  ],
+);