@fragno-dev/db 0.3.0 → 0.4.1

package/src/query/unit-of-work/execute-unit-of-work.test.ts

@@ -1,24 +1,30 @@
-import { describe, it, expect, expectTypeOf } from "vitest";
+import { describe, it, expect, expectTypeOf, vi } from "vitest";
+
+import { InMemoryAdapter } from "../../adapters/in-memory/in-memory-adapter";
+import type { InternalFragmentInstance } from "../../fragments/internal-fragment";
+import { internalSchema } from "../../fragments/internal-fragment.schema";
+import { prepareHookMutations } from "../../hooks/hooks";
 import { schema, idColumn, FragnoId } from "../../schema/create";
-import {
-  createUnitOfWork,
-  type IUnitOfWork,
-  type UOWCompiler,
-  type UOWDecoder,
-  type UOWExecutor,
-} from "./unit-of-work";
 import {
   createServiceTxBuilder,
   createHandlerTxBuilder,
   isTxResult,
+  serviceCalls,
   ConcurrencyConflictError,
 } from "./execute-unit-of-work";
+import type { AwaitedPromisesInObject, TxResult } from "./execute-unit-of-work";
 import {
   ExponentialBackoffRetryPolicy,
   LinearBackoffRetryPolicy,
   NoRetryPolicy,
 } from "./retry-policy";
-import type { AwaitedPromisesInObject, TxResult } from "./execute-unit-of-work";
+import {
+  createUnitOfWork,
+  type IUnitOfWork,
+  type UOWCompiler,
+  type UOWDecoder,
+  type UOWExecutor,
+} from "./unit-of-work";
 
 const testSchema = schema("test", (s) =>
   s.addTable("users", (t) =>
@@ -31,6 +37,42 @@ const testSchema = schema("test", (s) =>
   ),
 );
 
+function setupCrossSchemaHookTest() {
+  const adapter = new InMemoryAdapter();
+  const schemaA = schema("alpha", (s) =>
+    s.addTable("items", (t) => t.addColumn("id", idColumn()).addColumn("label", "string")),
+  );
+  const schemaB = schema("beta", (s) =>
+    s.addTable("items", (t) => t.addColumn("id", idColumn()).addColumn("label", "string")),
+  );
+  const namespaceA = "alpha";
+  const namespaceB = "beta";
+
+  const queryA = adapter.createQueryEngine(schemaA, namespaceA);
+  const queryB = adapter.createQueryEngine(schemaB, namespaceB);
+  const internalQuery = adapter.createQueryEngine(internalSchema, null);
+
+  const internalFragment = {
+    $internal: {
+      deps: {
+        schema: internalSchema,
+        namespace: null,
+      },
+    },
+  } as InternalFragmentInstance;
+
+  return {
+    schemaA,
+    schemaB,
+    namespaceA,
+    namespaceB,
+    queryA,
+    queryB,
+    internalQuery,
+    internalFragment,
+  };
+}
+
 describe("AwaitedPromisesInObject type tests", () => {
   it("should unwrap promises in objects", () => {
     type Input = { a: Promise<string>; b: number };
@@ -390,6 +432,36 @@ describe("Unified Tx API", () => {
       expect(users[1].name).toBe("Bob");
     });
 
+    it("should call onAfterRetrieve with full results", async () => {
+      const compiler = createMockCompiler();
+      const mockUsers = [
+        {
+          id: FragnoId.fromExternal("1", 1),
+          email: "alice@example.com",
+          name: "Alice",
+          balance: 100,
+        },
+      ];
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [mockUsers],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
+      const onAfterRetrieve = vi.fn();
+
+      await createHandlerTxBuilder({
+        createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+        onAfterRetrieve,
+      })
+        .retrieve(({ forSchema }) =>
+          forSchema(testSchema).find("users", (b) => b.whereIndex("idx_email")),
+        )
+        .execute();
+
+      expect(onAfterRetrieve).toHaveBeenCalledOnce();
+      expect(onAfterRetrieve.mock.calls[0]?.[1]).toEqual([mockUsers]);
+    });
+
     it("should execute a simple mutate-only transaction", async () => {
       const compiler = createMockCompiler();
       const executor: UOWExecutor<unknown, unknown> = {
@@ -773,6 +845,72 @@ describe("Unified Tx API", () => {
       expect(result.finalDepUserId).toBeInstanceOf(FragnoId);
     });
 
+    it("should preserve tuple inference for dynamic serviceCalls using helper", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [BigInt(1)] }),
+      };
+      const decoder = createMockDecoder();
+
+      let currentUow: IUnitOfWork | null = null;
+
+      type UserData = { id: FragnoId; email: string };
+      type Stats = { count: number };
+      type HistoryEntry = { page: number };
+
+      const getUser = () =>
+        createServiceTxBuilder(testSchema, currentUow!)
+          .mutate(({ uow }): UserData => {
+            const userId = uow.create("users", {
+              email: "user@example.com",
+              name: "User",
+              balance: 0,
+            });
+            return { id: userId, email: "user@example.com" };
+          })
+          .build();
+
+      const getStats = () =>
+        createServiceTxBuilder(testSchema, currentUow!)
+          .mutate((): Stats => ({ count: 42 }))
+          .build();
+
+      const listHistory = (page: number) =>
+        createServiceTxBuilder(testSchema, currentUow!)
+          .mutate((): HistoryEntry => ({ page }))
+          .build();
+
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => {
+          const historyCalls = Array.from({ length: 2 }, (_, idx) => listHistory(idx + 1));
+          return serviceCalls(getUser(), getStats(), ...historyCalls);
+        })
+        .mutate(({ serviceIntermediateResult }) => {
+          const [user, stats, ...history] = serviceIntermediateResult;
+
+          expectTypeOf(user).toEqualTypeOf<UserData>();
+          expectTypeOf(stats).toEqualTypeOf<Stats>();
+          expectTypeOf(history).items.toEqualTypeOf<HistoryEntry>();
+
+          return {
+            userId: user.id,
+            count: stats.count,
+            pages: history.map((entry) => entry.page),
+          };
+        })
+        .execute();
+
+      expect(result.count).toBe(42);
+      expect(result.pages).toEqual([1, 2]);
+      expect(result.userId).toBeInstanceOf(FragnoId);
+    });
+
     it("should retry on concurrency conflict", async () => {
       const compiler = createMockCompiler();
       let mutationAttempts = 0;
@@ -911,6 +1049,88 @@ describe("Unified Tx API", () => {
       ).rejects.toThrow("Transaction execution aborted");
     });
 
+    it("should propagate error when mutate callback rejects a duplicate via retrieve guard", async () => {
+      const compiler = createMockCompiler();
+      const existingUser = {
+        id: FragnoId.fromExternal("existing-1", 1),
+        email: "alice@example.com",
+        name: "Alice",
+        balance: 100,
+      };
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [[existingUser]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
+
+      let currentUow: IUnitOfWork | null = null;
+
+      const createIfNotExists = (email: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) =>
+            uow.find("users", (b) => b.whereIndex("idx_email", (eb) => eb("email", "=", email))),
+          )
+          .mutate(({ uow, retrieveResult: [users] }) => {
+            if (users.length > 0) {
+              throw new Error("ALREADY_EXISTS");
+            }
+            const id = uow.create("users", { email, name: "New", balance: 0 });
+            return { id };
+          })
+          .build();
+      };
+
+      await expect(
+        createHandlerTxBuilder({
+          createUnitOfWork: () => {
+            currentUow = createUnitOfWork(compiler, executor, decoder);
+            return currentUow;
+          },
+        })
+          .withServiceCalls(() => [createIfNotExists("alice@example.com")])
+          .transform(({ serviceResult: [result] }) => result)
+          .execute(),
+      ).rejects.toThrow("ALREADY_EXISTS");
+    });
+
+    it("should succeed when retrieve guard finds no existing record", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [[]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [BigInt(1)] }),
+      };
+      const decoder = createMockDecoder();
+
+      let currentUow: IUnitOfWork | null = null;
+
+      const createIfNotExists = (email: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) =>
+            uow.find("users", (b) => b.whereIndex("idx_email", (eb) => eb("email", "=", email))),
+          )
+          .mutate(({ uow, retrieveResult: [users] }) => {
+            if (users.length > 0) {
+              throw new Error("ALREADY_EXISTS");
+            }
+            const id = uow.create("users", { email, name: "New", balance: 0 });
+            return { id };
+          })
+          .build();
+      };
+
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [createIfNotExists("new@example.com")])
+        .transform(({ serviceResult: [result] }) => result)
+        .execute();
+
+      expect(result.id).toBeInstanceOf(FragnoId);
+    });
+
     it("should pass serviceResult to transform callback with final results", async () => {
       const compiler = createMockCompiler();
       const mockUser = {
@@ -1547,6 +1767,7 @@ describe("Unified Tx API", () => {
       await createHandlerTxBuilder({
         createUnitOfWork: () => {
           currentUow = createUnitOfWork(compiler, executor, decoder);
+          currentUow.registerSchema(testSchema, "test");
           return currentUow;
         },
       })
@@ -1616,6 +1837,7 @@ describe("Unified Tx API", () => {
       await createHandlerTxBuilder({
         createUnitOfWork: () => {
           currentUow = createUnitOfWork(compiler, executor, decoder);
+          currentUow.registerSchema(testSchema, "test");
           return currentUow;
         },
       })
@@ -1631,6 +1853,122 @@ describe("Unified Tx API", () => {
         payload: { userId: expect.any(String) },
       });
     });
+
+    it("should create hook records when handler uses schema A and service uses schema B", async () => {
+      const { schemaA, schemaB, namespaceA, namespaceB, queryA, internalQuery, internalFragment } =
+        setupCrossSchemaHookTest();
+
+      type HooksA = {
+        onAlpha: (payload: { value: string }) => void;
+      };
+      type HooksB = {
+        onBeta: (payload: { value: string }) => void;
+      };
+
+      const hooksA: HooksA = {
+        onAlpha: (_payload) => {},
+      };
+      const hooksB: HooksB = {
+        onBeta: (_payload) => {},
+      };
+
+      let currentUow: IUnitOfWork | null = null;
+
+      const serviceInSchemaB = (value: string) =>
+        createServiceTxBuilder(schemaB, currentUow!, hooksB)
+          .mutate(({ uow }) => {
+            uow.create("items", { label: value });
+            uow.triggerHook("onBeta", { value });
+          })
+          .build();
+
+      await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = queryA.createBaseUnitOfWork();
+          currentUow.registerSchema(schemaA, namespaceA);
+          currentUow.registerSchema(schemaB, namespaceB);
+          currentUow.registerSchema(internalSchema, null);
+          return currentUow;
+        },
+        onBeforeMutate: (uow) => {
+          prepareHookMutations(uow, internalFragment);
+        },
+      })
+        .mutate(({ forSchema }) => {
+          const uow = forSchema(schemaA, hooksA);
+          uow.create("items", { label: "alpha" });
+          uow.triggerHook("onAlpha", { value: "alpha" });
+        })
+        .withServiceCalls(() => [serviceInSchemaB("beta")] as const)
+        .execute();
+
+      const hooks = await internalQuery.find("fragno_hooks");
+      expect(hooks).toHaveLength(2);
+      expect(hooks).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ hookName: "onAlpha", namespace: namespaceA }),
+          expect.objectContaining({ hookName: "onBeta", namespace: namespaceB }),
+        ]),
+      );
+    });
+
+    it("should create hook records when handler uses schema B and service uses schema A", async () => {
+      const { schemaA, schemaB, namespaceA, namespaceB, queryB, internalQuery, internalFragment } =
+        setupCrossSchemaHookTest();
+
+      type HooksA = {
+        onAlpha: (payload: { value: string }) => void;
+      };
+      type HooksB = {
+        onBeta: (payload: { value: string }) => void;
+      };
+
+      const hooksA: HooksA = {
+        onAlpha: (_payload) => {},
+      };
+      const hooksB: HooksB = {
+        onBeta: (_payload) => {},
+      };
+
+      let currentUow: IUnitOfWork | null = null;
+
+      const serviceInSchemaA = (value: string) =>
+        createServiceTxBuilder(schemaA, currentUow!, hooksA)
+          .mutate(({ uow }) => {
+            uow.create("items", { label: value });
+            uow.triggerHook("onAlpha", { value });
+          })
+          .build();
+
+      await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = queryB.createBaseUnitOfWork();
+          currentUow.registerSchema(schemaA, namespaceA);
+          currentUow.registerSchema(schemaB, namespaceB);
+          currentUow.registerSchema(internalSchema, null);
+          return currentUow;
+        },
+        onBeforeMutate: (uow) => {
+          prepareHookMutations(uow, internalFragment);
+        },
+      })
+        .mutate(({ forSchema }) => {
+          const uow = forSchema(schemaB, hooksB);
+          uow.create("items", { label: "beta" });
+          uow.triggerHook("onBeta", { value: "beta" });
+        })
+        .withServiceCalls(() => [serviceInSchemaA("alpha")] as const)
+        .execute();
+
+      const hooks = await internalQuery.find("fragno_hooks");
+      expect(hooks).toHaveLength(2);
+      expect(hooks).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ hookName: "onAlpha", namespace: namespaceA }),
+          expect.objectContaining({ hookName: "onBeta", namespace: namespaceB }),
+        ]),
+      );
+    });
   });
 
   describe("error handling in createServiceTx", () => {

package/src/query/unit-of-work/execute-unit-of-work.ts

@@ -1,7 +1,7 @@
-import type { AnySchema } from "../../schema/create";
-import type { TypedUnitOfWork, IUnitOfWork } from "./unit-of-work";
 import type { HooksMap } from "../../hooks/hooks";
+import type { AnySchema } from "../../schema/create";
 import { ExponentialBackoffRetryPolicy, NoRetryPolicy, type RetryPolicy } from "./retry-policy";
+import type { TypedUnitOfWork, IUnitOfWork } from "./unit-of-work";
 
 /**
  * Symbol to identify TxResult objects
@@ -58,6 +58,26 @@ export type ExtractServiceFinalResults<T extends readonly unknown[]> = {
   [K in keyof T]: ExtractTxFinalResult<T[K]>;
 };
 
+/**
+ * Helper to preserve tuple inference for service calls, especially with spreads.
+ *
+ * @example
+ * ```ts
+ * const historyCalls = Array.from({ length: 3 }, () => svc.listHistory(...));
+ * return serviceCalls(
+ *   svc.getInstanceStatus(...),
+ *   svc.getInstanceRunNumber(...),
+ *   ...historyCalls,
+ * );
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function serviceCalls<const T extends readonly (TxResult<any, any> | undefined)[]>(
+  ...calls: T
+): T {
+  return calls;
+}
+
 /**
  * Context passed to mutate callback for service methods
  */
@@ -491,6 +511,12 @@ export interface ExecuteTxOptions {
    */
   signal?: AbortSignal;
 
+  /**
+   * Callback invoked after retrieval phase completes.
+   * Use this to inspect retrieval operations and results (e.g., read tracking).
+   */
+  onAfterRetrieve?: (uow: IUnitOfWork, results: unknown[]) => void | Promise<void>;
+
   /**
    * Callback invoked before mutations are executed.
    * Use this to add additional mutation operations (e.g., hook event records).
@@ -502,6 +528,11 @@ export interface ExecuteTxOptions {
    * Use this for post-mutation processing like hook execution.
    */
   onAfterMutate?: (uow: IUnitOfWork) => Promise<void>;
+
+  /**
+   * Plan mode suppresses hook execution while still running serviceTx logic.
+   */
+  planMode?: boolean;
 }
 
 /**
@@ -738,6 +769,10 @@ async function executeTx(
     try {
       // Create a fresh UOW for this attempt
       const baseUow = options.createUnitOfWork();
+      if (options.onAfterRetrieve) {
+        const readTrackingUow = baseUow as { enableReadTracking?: () => void };
+        readTrackingUow.enableReadTracking?.();
+      }
 
       // Create handler context
       const context: HandlerTxContext<THooks> = {
@@ -777,7 +812,10 @@ async function executeTx(
           });
       }
 
-      await baseUow.executeRetrieve();
+      const allRetrieveResults = await baseUow.executeRetrieve();
+      if (options.onAfterRetrieve) {
+        await options.onAfterRetrieve(baseUow, allRetrieveResults);
+      }
 
       // Get retrieve results from TypedUnitOfWork's retrievalPhase or default to empty array
       const retrieveResult: TRetrieveResults = typedUowFromRetrieve
@@ -840,7 +878,7 @@ async function executeTx(
         mutateResult = callbacks.mutate(mutateCtx);
       }
 
-      if (options.onBeforeMutate) {
+      if (!options.planMode && options.onBeforeMutate) {
         options.onBeforeMutate(baseUow);
       }
       const result = await baseUow.executeMutations();
@@ -883,7 +921,7 @@ async function executeTx(
         finalResult = serviceFinalResults;
       }
 
-      if (options.onAfterMutate) {
+      if (!options.planMode && options.onAfterMutate) {
         await options.onAfterMutate(baseUow);
       }
 
@@ -1555,6 +1593,7 @@ interface HandlerTxBuilderState<
 > {
   options: ExecuteTxOptions;
   hooks?: THooks;
+  executeWrapper?: <T>(run: () => Promise<T>) => Promise<T>;
   withServiceCallsFn?: () => TServiceCalls;
   retrieveFn?: (context: {
     forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
@@ -1891,22 +1930,24 @@ export class HandlerTxBuilder<
         : undefined,
     };
 
-    // Use the existing executeTx implementation
-    return executeTx(callbacks as Parameters<typeof executeTx>[0], state.options) as Promise<
-      AwaitedPromisesInObject<
-        InferBuilderResultType<
-          TRetrieveResults,
-          TRetrieveSuccessResult,
-          TServiceCalls,
-          TMutateResult,
-          TTransformResult,
-          HasTransform,
-          HasMutate,
-          HasTransformRetrieve,
-          HasRetrieve
+    const run = () =>
+      executeTx(callbacks as Parameters<typeof executeTx>[0], state.options) as Promise<
+        AwaitedPromisesInObject<
+          InferBuilderResultType<
+            TRetrieveResults,
+            TRetrieveSuccessResult,
+            TServiceCalls,
+            TMutateResult,
+            TTransformResult,
+            HasTransform,
+            HasMutate,
+            HasTransformRetrieve,
+            HasRetrieve
+          >
         >
-      >
-    >;
+      >;
+
+    return state.executeWrapper ? state.executeWrapper(run) : run();
   }
 }
 
@@ -1916,9 +1957,11 @@ export class HandlerTxBuilder<
 export function createHandlerTxBuilder<THooks extends HooksMap = {}>(
   options: ExecuteTxOptions,
   hooks?: THooks,
+  executeWrapper?: <T>(run: () => Promise<T>) => Promise<T>,
 ): HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, THooks> {
   return new HandlerTxBuilder({
     options,
     hooks,
+    executeWrapper,
   });
 }

package/src/query/unit-of-work/retry-policy.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from "vitest";
+
 import {
   ExponentialBackoffRetryPolicy,
   LinearBackoffRetryPolicy,

package/src/query/unit-of-work/tx-builder.test.ts

@@ -7,12 +7,13 @@
  * not the runtime behavior (which is covered by execute-unit-of-work.test.ts).
  */
 import { describe, expectTypeOf, it } from "vitest";
+
 import type { AnySchema } from "../../schema/create";
-import type { TypedUnitOfWork } from "./unit-of-work";
 import {
   ServiceTxBuilder,
   HandlerTxBuilder,
   type TxResult,
+  serviceCalls,
   type ServiceBuilderMutateContext,
   type HandlerBuilderMutateContext,
   type BuilderTransformContextWithMutate,
@@ -21,6 +22,7 @@ import {
   type ExtractServiceFinalResults,
   type AwaitedPromisesInObject,
 } from "./execute-unit-of-work";
+import type { TypedUnitOfWork } from "./unit-of-work";
 
 // =============================================================================
 // Helper types for extracting TxResult type parameters
@@ -552,6 +554,76 @@ describe("HandlerTxBuilder type inference", () => {
         readonly [{ user: { id: string } }]
       >();
     });
+
+    it("widens serviceIntermediateResult when serviceCalls is a non-tuple array", () => {
+      type Status = { status: string };
+      type HistoryPage = { runNumber: number };
+      type StatusCall = TxResult<Status, Status>;
+      type RunNumberCall = TxResult<number, number>;
+      type HistoryCall = TxResult<HistoryPage, HistoryPage>;
+
+      // When serviceCalls are built dynamically (e.g. Array.from + spread),
+      // the tuple shape is lost and results widen to a union array.
+      type ServiceCalls = readonly (StatusCall | RunNumberCall | HistoryCall)[];
+
+      type Builder = HandlerTxBuilder<
+        ServiceCalls,
+        [],
+        [],
+        unknown,
+        unknown,
+        false,
+        false,
+        true, // HasMutate
+        false,
+        {}
+      >;
+
+      type MutateParam = Parameters<Builder["mutate"]>[0];
+      type MutateCtx = Parameters<MutateParam>[0];
+
+      expectTypeOf<MutateCtx["serviceIntermediateResult"]>().toEqualTypeOf<
+        readonly (Status | number | HistoryPage)[]
+      >();
+    });
+
+    it("preserves tuple inference for dynamic serviceCalls when using helper", () => {
+      type Status = { status: string };
+      type HistoryPage = { runNumber: number };
+      type StatusCall = TxResult<Status, Status>;
+      type RunNumberCall = TxResult<number, number>;
+      type HistoryCall = TxResult<HistoryPage, HistoryPage>;
+
+      const statusCall = null as unknown as StatusCall;
+      const runNumberCall = null as unknown as RunNumberCall;
+      const historyCalls = [] as HistoryCall[];
+
+      const calls = serviceCalls(statusCall, runNumberCall, ...historyCalls);
+
+      expectTypeOf<typeof calls>().toEqualTypeOf<
+        readonly [StatusCall, RunNumberCall, ...HistoryCall[]]
+      >();
+
+      type Builder = HandlerTxBuilder<
+        typeof calls,
+        [],
+        [],
+        unknown,
+        unknown,
+        false,
+        false,
+        true, // HasMutate
+        false,
+        {}
+      >;
+
+      type MutateParam = Parameters<Builder["mutate"]>[0];
+      type MutateCtx = Parameters<MutateParam>[0];
+
+      expectTypeOf<MutateCtx["serviceIntermediateResult"]>().toEqualTypeOf<
+        readonly [Status, number, ...HistoryPage[]]
+      >();
+    });
   });
 
   describe("retrieve + transformRetrieve flow", () => {