@fragno-dev/db 0.2.1 → 0.3.0

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

@@ -1,18 +1,18 @@
 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";
 import { withDatabase } from "./with-database";
 import type { FragnoPublicConfigWithDatabase } from "./db-fragment-definition-builder";
-import { ConcurrencyConflictError } from "./query/unit-of-work/execute-unit-of-work";
+import { ConcurrencyConflictError, type TxResult } from "./query/unit-of-work/execute-unit-of-work";
 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())
@@ -48,106 +48,124 @@ describe.sequential("Database Fragment Integration", () => {
     });
   });
 
-  // Define Users Fragment
+  // 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({
-        createUser(name: string, email: string): FragnoId {
-          const uow = this.uow(usersSchema);
-          return uow.create("users", { name, email });
+        // Creates a user - returns TxResult<FragnoId>
+        createUser(name: string, email: string) {
+          return this.serviceTx(usersSchema)
+            .mutate(({ uow }) => uow.create("users", { name, email }))
+            .build();
         },
-        async getUserById(userId: FragnoId | string) {
-          const uow = this.uow(usersSchema).find("users", (b) =>
-            b.whereIndex("primary", (eb) => eb("id", "=", userId)),
-          );
-          // Note: executeRetrieve() should be called by the caller before awaiting retrievalPhase
-          const [users] = await uow.retrievalPhase;
-          return users?.[0] ?? null;
+        // Gets a user by ID - returns TxResult<User | null>
+        getUserById(userId: FragnoId | string) {
+          return this.serviceTx(usersSchema)
+            .retrieve((uow) =>
+              uow.find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId))),
+            )
+            .transformRetrieve(
+              ([users]): { id: FragnoId; name: string; email: string } | null => users[0] ?? null,
+            )
+            .build();
         },
-        createProfile(userId: FragnoId | string, bio: string): FragnoId {
-          const uow = this.uow(usersSchema);
-          return uow.create("profiles", {
-            user_id: userId,
-            bio,
-          });
+        // Creates a profile - returns TxResult<FragnoId>
+        createProfile(userId: FragnoId | string, bio: string) {
+          return this.serviceTx(usersSchema)
+            .mutate(({ uow }) =>
+              uow.create("profiles", {
+                user_id: userId,
+                bio,
+              }),
+            )
+            .build();
         },
       });
     })
     .build();
 
-  // Define routes for Users Fragment
-  const usersRoutes = defineRoutes(usersFragmentDef).create(({ services, defineRoute }) => [
+  // Define routes for Users Fragment using new handlerTx API
+  const usersRoutes = defineRoutes(usersFragmentDef).create(({ defineRoute }) => [
     defineRoute({
       method: "POST",
       path: "/users",
       outputSchema: z.object({ userId: z.string(), profileId: z.string() }),
       handler: async function (_input, { json }) {
-        const { userId, profileId } = await this.uow(async ({ executeMutate }) => {
-          const userId = services.userService.createUser("John Doe", "john@example.com");
-          const profileId = services.userService.createProfile(userId, "Software engineer");
-          await executeMutate();
-          return { userId, profileId };
-        });
+        // Use handlerTx with mutate to create both user and profile atomically
+        const result = await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const uow = forSchema(usersSchema);
+            const userId = uow.create("users", { name: "John Doe", email: "john@example.com" });
+            const profileId = uow.create("profiles", {
+              user_id: userId,
+              bio: "Software engineer",
+            });
+            return { userId, profileId };
+          })
+          .execute();
 
         return json(
-          { userId: userId.externalId, profileId: profileId.externalId },
+          { userId: result.userId.externalId, profileId: result.profileId.externalId },
           { status: 201 },
         );
       },
     }),
   ]);
 
-  // Define Orders Fragment with cross-fragment service dependency
+  // User type for service dependency
+  type User = { id: FragnoId; name: string; email: string };
+
+  // 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",
       {
-        getUserById: (
-          userId: FragnoId | string,
-        ) => Promise<{ id: FragnoId; name: string; email: string } | null>;
+        // Service methods now return TxResult instead of Promise
+        // TxResult<T> defaults to TxResult<T, T> (deps receive same type as final result)
+        getUserById: (userId: FragnoId | string) => TxResult<User | null>;
       }
     >("userService")
     .providesService("orderService", ({ defineService, serviceDeps }) => {
       return defineService({
-        async createOrder(
-          userExternalId: string,
-          productName: string,
-          quantity: number,
-          total: number,
-        ) {
-          // Verify user exists by calling the userService from the other fragment
-          const user = await serviceDeps.userService.getUserById(userExternalId);
-
-          if (!user) {
-            throw new Error("User not found");
-          }
-
-          const uow = this.uow(ordersSchema);
-          const orderId = uow.create("orders", {
-            user_external_id: userExternalId,
-            product_name: productName,
-            quantity,
-            total,
-          });
-
-          await uow.mutationPhase;
-          return orderId;
+        createOrder(userExternalId: string, productName: string, quantity: number, total: number) {
+          return this.serviceTx(ordersSchema)
+            .withServiceCalls(() => [serviceDeps.userService.getUserById(userExternalId)] as const)
+            .mutate(({ uow, serviceIntermediateResult: [user] }) => {
+              if (!user) {
+                throw new Error("User not found");
+              }
+
+              expect(user.id.externalId).toBe(userExternalId);
+
+              return uow.create("orders", {
+                user_external_id: userExternalId,
+                product_name: productName,
+                quantity,
+                total,
+              });
+            })
+            .build();
         },
-        async getOrdersByUser(userExternalId: string) {
-          const uow = this.uow(ordersSchema).find("orders", (b) =>
-            b.whereIndex("orders_user_idx", (eb) => eb("user_external_id", "=", userExternalId)),
-          );
-          // Note: executeRetrieve() should be called by the caller before awaiting retrievalPhase
-          const [orders] = await uow.retrievalPhase;
-          return orders;
+        // Gets orders by user - returns TxResult<Order[]>
+        getOrdersByUser(userExternalId: string) {
+          return this.serviceTx(ordersSchema)
+            .retrieve((uow) =>
+              uow.find("orders", (b) =>
+                b.whereIndex("orders_user_idx", (eb) =>
+                  eb("user_external_id", "=", userExternalId),
+                ),
+              ),
+            )
+            .transformRetrieve(([orders]) => orders)
+            .build();
         },
       });
     })
     .build();
 
-  // Define routes for Orders Fragment
+  // Define routes for Orders Fragment using new handlerTx API
   const ordersRoutes = defineRoutes(ordersFragmentDef).create(({ services, defineRoute }) => [
     defineRoute({
       method: "POST",
@@ -159,28 +177,39 @@ describe.sequential("Database Fragment Integration", () => {
         total: z.number(),
       }),
       outputSchema: z.object({ orderId: z.string() }),
-      handler: async function ({ input }, { json }) {
+      handler: async function ({ input }, { json, error }) {
         const body = await input.valid();
 
-        const { orderId } = await this.uow(async ({ executeMutate }) => {
-          const orderIdPromise = services.orderService.createOrder(
-            body.userId,
-            body.productName,
-            body.quantity,
-            body.total,
-          );
-
-          await executeMutate();
-
-          return { orderId: await orderIdPromise };
-        });
-
-        return json({ orderId: orderId.externalId }, { status: 201 });
+        try {
+          // Use handlerTx with withServiceCalls to execute the service TxResult
+          // createOrder validates that the user exists
+          const result = await this.handlerTx()
+            .withServiceCalls(
+              () =>
+                [
+                  services.orderService.createOrder(
+                    body.userId,
+                    body.productName,
+                    body.quantity,
+                    body.total,
+                  ),
+                ] as const,
+            )
+            .transform(({ serviceResult: [orderId] }) => ({ orderId }))
+            .execute();
+
+          return json({ orderId: result.orderId.externalId }, { status: 201 });
+        } catch (e) {
+          if (e instanceof Error && e.message === "User not found") {
+            return error({ message: "User not found", code: "USER_NOT_FOUND" }, { status: 404 });
+          }
+          throw e;
+        }
       },
     }),
   ]);
 
-  let adapter: KyselyAdapter;
+  let adapter: SqlAdapter;
   let usersFragment: ReturnType<typeof instantiateUsersFragment>;
   let ordersFragment: ReturnType<typeof instantiateOrdersFragment>;
 
@@ -210,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(),
     });
@@ -244,11 +273,12 @@ describe.sequential("Database Fragment Integration", () => {
 
   it("should verify user was created with profile", async () => {
     const user = await usersFragment.inContext(async function () {
-      return await this.uow(async ({ executeRetrieve }) => {
-        const userPromise = usersFragment.services.userService.getUserById(userId);
-        await executeRetrieve();
-        return await userPromise;
-      });
+      // Use handlerTx with withServiceCalls to execute the service TxResult
+      const result = await this.handlerTx()
+        .withServiceCalls(() => [usersFragment.services.userService.getUserById(userId)] as const)
+        .transform(({ serviceResult: [user] }) => user)
+        .execute();
+      return result;
     });
 
     expect(user).toMatchObject({
@@ -274,15 +304,18 @@ describe.sequential("Database Fragment Integration", () => {
       `createOrderResponse.type !== json: ${createOrderResponse.type}`,
     );
     orderId = createOrderResponse.data.orderId;
-  });
+  }, 500);
 
   it("should verify order was created with correct user reference", async () => {
     const orders = await ordersFragment.inContext(async function () {
-      return await this.uow(async ({ executeRetrieve }) => {
-        const ordersPromise = ordersFragment.services.orderService.getOrdersByUser(userId);
-        await executeRetrieve();
-        return await ordersPromise;
-      });
+      // Use handlerTx with withServiceCalls to execute the service TxResult
+      const result = await this.handlerTx()
+        .withServiceCalls(
+          () => [ordersFragment.services.orderService.getOrdersByUser(userId)] as const,
+        )
+        .transform(({ serviceResult: [orders] }) => orders)
+        .execute();
+      return result;
     });
     expect(orders).toHaveLength(1);
     expect(orders[0]).toMatchObject({
@@ -299,20 +332,25 @@ describe.sequential("Database Fragment Integration", () => {
   it("should verify cross-fragment service integration works bidirectionally", async () => {
     // Orders service should be able to query users via the shared userService
     const ordersByUser = await ordersFragment.inContext(async function () {
-      return await this.uow(async ({ executeRetrieve }) => {
-        const ordersPromise = ordersFragment.services.orderService.getOrdersByUser(userId);
-        await executeRetrieve();
-        return await ordersPromise;
-      });
+      const result = await this.handlerTx()
+        .withServiceCalls(
+          () => [ordersFragment.services.orderService.getOrdersByUser(userId)] as const,
+        )
+        .transform(({ serviceResult: [orders] }) => orders)
+        .execute();
+      return result;
     });
     const userFromOrdersContext = await usersFragment.inContext(async function () {
-      return await this.uow(async ({ executeRetrieve }) => {
-        const userPromise = usersFragment.services.userService.getUserById(
-          ordersByUser[0].user_external_id,
-        );
-        await executeRetrieve();
-        return await userPromise;
-      });
+      const result = await this.handlerTx()
+        .withServiceCalls(
+          () =>
+            [
+              usersFragment.services.userService.getUserById(ordersByUser[0].user_external_id),
+            ] as const,
+        )
+        .transform(({ serviceResult: [user] }) => user)
+        .execute();
+      return result;
     });
 
     expect(userFromOrdersContext).toMatchObject({
@@ -334,27 +372,36 @@ describe.sequential("Database Fragment Integration", () => {
       },
     });
 
-    // Should return error because user doesn't exist
-    expect(invalidOrderResponse.type).toBe("error");
+    // Should return 404 error because user doesn't exist
+    expect(invalidOrderResponse.status).toBe(404);
   });
 
   it("should be able to use inContext to call a service", async () => {
-    const [user, order] = await usersFragment.inContext(async function () {
-      return await this.uow(async ({ executeRetrieve }) => {
-        const user = usersFragment.services.userService.getUserById(userId);
-        const orders = ordersFragment.services.orderService.getOrdersByUser(userId);
-        await executeRetrieve();
-        return [user, orders];
-      });
+    const result = await usersFragment.inContext(async function () {
+      // Use handlerTx with multiple deps
+      return await this.handlerTx()
+        .withServiceCalls(
+          () =>
+            [
+              usersFragment.services.userService.getUserById(userId),
+              ordersFragment.services.orderService.getOrdersByUser(userId),
+            ] as const,
+        )
+        .transform(({ serviceResult: [userResult, ordersResult] }) => ({
+          user: userResult,
+          orders: ordersResult,
+        }))
+        .execute();
     });
-    expect(user).toMatchObject({
+
+    expect(result.user).toMatchObject({
       id: expect.objectContaining({
         externalId: userId,
       }),
     });
 
-    expect(order).toHaveLength(1);
-    expect(order[0]).toMatchObject({
+    expect(result.orders).toHaveLength(1);
+    expect(result.orders[0]).toMatchObject({
       id: expect.objectContaining({
         externalId: orderId,
       }),
@@ -362,45 +409,150 @@ describe.sequential("Database Fragment Integration", () => {
     });
   });
 
-  it("should provide nonce and currentAttempt in the UOW context", async () => {
-    let firstNonce: string;
+  it("should provide idempotencyKey and currentAttempt in the handlerTx context", async () => {
+    let firstIdempotencyKey: string;
 
     const result = await usersFragment.inContext(async function () {
-      return await this.uow(async ({ executeRetrieve, nonce, currentAttempt }) => {
-        const user = usersFragment.services.userService.getUserById(userId);
-        await executeRetrieve();
-
-        if (currentAttempt === 0) {
-          firstNonce = nonce;
-          // Trigger a conflict by throwing the specific conflict error
-          throw new ConcurrencyConflictError();
-        }
+      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;
+            // Trigger a conflict by throwing the specific conflict error
+            throw new ConcurrencyConflictError();
+          }
 
-        expect(nonce).toBe(firstNonce);
+          expect(idempotencyKey).toBe(firstIdempotencyKey);
 
-        // Return context data along with user data
-        return {
-          user,
-          nonce,
-          currentAttempt,
-        };
-      });
+          // Create something to verify the mutation works
+          const newUserId = forSchema(usersSchema).create("users", {
+            name: "Nonce Test User",
+            email: `nonce-test-${Date.now()}@example.com`,
+          });
+
+          // Return context data
+          return {
+            newUserId,
+            idempotencyKey,
+            currentAttempt,
+          };
+        })
+        .execute();
     });
 
-    // Verify nonce is a string UUID
-    expect(result.nonce).toBeDefined();
-    expect(typeof result.nonce).toBe("string");
-    expect(result.nonce).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+    // Verify idempotencyKey is a string UUID
+    expect(result.idempotencyKey).toBeDefined();
+    expect(typeof result.idempotencyKey).toBe("string");
+    expect(result.idempotencyKey).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
 
     expect(result.currentAttempt).toBe(1);
 
-    // Verify user data is still correct
-    expect(result.user).toMatchObject({
-      id: expect.objectContaining({
-        externalId: userId,
-      }),
-      name: "John Doe",
-      email: "john@example.com",
+    // Verify user was created
+    expect(result.newUserId).toBeDefined();
+    expect(result.newUserId.externalId).toBeDefined();
+  });
+
+  describe("Unified Tx Builder API (serviceTx/handlerTx)", () => {
+    it("should use handlerTx with mutate to create records", async () => {
+      const result = await usersFragment.inContext(async function () {
+        return await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const newUserId = forSchema(usersSchema).create("users", {
+              name: "Unified API User",
+              email: "unified@example.com",
+            });
+            return { newUserId };
+          })
+          .execute();
+      });
+
+      expect(result.newUserId).toBeDefined();
+      expect(result.newUserId.externalId).toBeDefined();
+    });
+
+    it("should use handlerTx with retrieve callback to query data", async () => {
+      const result = await usersFragment.inContext(async function () {
+        return await this.handlerTx()
+          .retrieve(({ forSchema }) =>
+            forSchema(usersSchema).find("users", (b) =>
+              b.whereIndex("primary", (eb) => eb("id", "=", userId)),
+            ),
+          )
+          .transformRetrieve(([users]) => {
+            return { retrieved: true, user: users[0] };
+          })
+          .execute();
+      });
+
+      expect(result.retrieved).toBe(true);
+      expect(result.user).toMatchObject({
+        id: expect.objectContaining({ externalId: userId }),
+        name: "John Doe",
+      });
+    });
+
+    it("should use handlerTx with mutate and transform callbacks", async () => {
+      const result = await usersFragment.inContext(async function () {
+        return await this.handlerTx()
+          .mutate(({ forSchema }) => {
+            const newUserId = forSchema(usersSchema).create("users", {
+              name: "Success Callback User",
+              email: "success-callback@example.com",
+            });
+            return { newUserId, createdInMutate: true };
+          })
+          .transform(({ mutateResult }) => {
+            return {
+              userId: mutateResult.newUserId,
+              wasCreatedInMutate: mutateResult.createdInMutate,
+              processedAt: new Date().toISOString(),
+            };
+          })
+          .execute();
+      });
+
+      expect(result.userId).toBeDefined();
+      expect(result.wasCreatedInMutate).toBe(true);
+      expect(result.processedAt).toBeDefined();
+    });
+
+    it("should use handlerTx with retrieve, mutate, and transform callbacks", async () => {
+      const result = await ordersFragment.inContext(async function () {
+        return await this.handlerTx()
+          .retrieve(({ forSchema }) =>
+            forSchema(ordersSchema).find("orders", (b) =>
+              b.whereIndex("orders_user_idx", (eb) => eb("user_external_id", "=", userId)),
+            ),
+          )
+          .transformRetrieve(([orders]) => {
+            return { existingOrders: orders };
+          })
+          .mutate(({ forSchema, retrieveResult }) => {
+            expect(retrieveResult.existingOrders.length).toBeGreaterThan(0);
+            const orderId = forSchema(ordersSchema).create("orders", {
+              user_external_id: userId,
+              product_name: "Full Flow Product",
+              quantity: 3,
+              total: 3000,
+            });
+            return { orderId };
+          })
+          .transform(({ mutateResult, retrieveResult }) => {
+            return {
+              orderId: mutateResult.orderId,
+              hadRetrieve: retrieveResult.existingOrders.length > 0,
+              completedAt: new Date().toISOString(),
+            };
+          })
+          .execute();
+      });
+
+      expect(result.orderId).toBeDefined();
+      expect(result.hadRetrieve).toBe(true);
+      expect(result.completedAt).toBeDefined();
     });
   });
 });

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();
+  });
+});