@fragno-dev/db 0.1.15 → 0.2.0

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

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, assert, expectTypeOf } from "vitest";
-import { schema, idColumn, FragnoId } from "../schema/create";
+import { schema, idColumn, FragnoId } from "../../schema/create";
 import {
   createUnitOfWork,
   type TypedUnitOfWork,
@@ -118,7 +118,11 @@ function createMockCompiler(): UOWCompiler<unknown> {
 
 // Mock decoder that returns raw results as-is
 function createMockDecoder(): UOWDecoder {
-  return (rawResults) => rawResults;
+  return {
+    decode(rawResults) {
+      return rawResults;
+    },
+  };
 }
 
 // Helper to create a UOW factory that tracks how many times it's called
@@ -838,7 +842,7 @@ describe("executeRestrictedUnitOfWork", () => {
   });
 
   describe("error handling", () => {
-    it("should throw error from callback", async () => {
+    it("should throw error from callback immediately without retry", async () => {
       const { factory, callCount } = createMockUOWFactory([{ success: true }]);
 
       await expect(
@@ -848,13 +852,13 @@ describe("executeRestrictedUnitOfWork", () => {
           },
           { createUnitOfWork: factory },
         ),
-      ).rejects.toThrow("Unit of Work execution failed: optimistic concurrency conflict");
+      ).rejects.toThrow("Callback error");
 
-      // Should attempt retries even on callback errors
-      expect(callCount.value).toBe(6); // Initial + 5 retries (default)
+      // Should NOT retry non-conflict errors
+      expect(callCount.value).toBe(1); // Only initial attempt
     });
 
-    it("should wrap callback error as cause", async () => {
+    it("should throw callback error directly", async () => {
       const { factory } = createMockUOWFactory([{ success: true }]);
       const originalError = new Error("Original error");
 
@@ -870,8 +874,8 @@ describe("executeRestrictedUnitOfWork", () => {
         );
         expect.fail("Should have thrown");
       } catch (error) {
-        expect(error).toBeInstanceOf(Error);
-        expect((error as Error).cause).toBe(originalError);
+        // Error should be thrown directly, not wrapped
+        expect(error).toBe(originalError);
       }
     });
   });
@@ -1292,19 +1296,15 @@ describe("executeRestrictedUnitOfWork", () => {
         );
         expect.fail("Should have thrown an error");
       } catch (error) {
-        // The error should be wrapped by executeRestrictedUnitOfWork
+        // The error should be thrown directly (not wrapped) since it's not a concurrency conflict
         expect(error).toBeInstanceOf(Error);
-        // Check that the original error is in the cause chain
-        expect((error as Error).cause).toBeInstanceOf(Error);
-        expect(((error as Error).cause as Error).message).toContain(
-          'relation "settings" does not exist',
-        );
+        expect((error as Error).message).toContain('relation "settings" does not exist');
         deferred.resolve((error as Error).message);
       }
 
       // Verify no unhandled rejection occurred
       // If the test completes without throwing, the promise rejection was properly handled
-      expect(await deferred.promise).toContain("Unit of Work execution failed");
+      expect(await deferred.promise).toContain('relation "settings" does not exist');
     });
   });
 });

package/src/query/{execute-unit-of-work.ts → unit-of-work/execute-unit-of-work.ts}

@@ -1,7 +1,19 @@
-import type { AnySchema } from "../schema/create";
+import type { AnySchema } from "../../schema/create";
 import type { TypedUnitOfWork, IUnitOfWork } from "./unit-of-work";
+import type { HooksMap } from "../../hooks/hooks";
 import { NoRetryPolicy, ExponentialBackoffRetryPolicy, type RetryPolicy } from "./retry-policy";
-import type { FragnoId } from "../schema/create";
+import type { FragnoId } from "../../schema/create";
+
+/**
+ * Error thrown when a Unit of Work execution fails due to optimistic concurrency conflict.
+ * This error triggers automatic retry behavior in executeRestrictedUnitOfWork.
+ */
+export class ConcurrencyConflictError extends Error {
+  constructor(message = "Optimistic concurrency conflict detected") {
+    super(message);
+    this.name = "ConcurrencyConflictError";
+  }
+}
 
 /**
  * Type utility that unwraps promises 1 level deep in objects, arrays, or direct promises
@@ -330,6 +342,18 @@ export interface ExecuteRestrictedUnitOfWorkOptions {
    * Abort signal to cancel execution
    */
   signal?: AbortSignal;
+
+  /**
+   * Callback invoked before mutations are executed.
+   * Use this to add additional mutation operations (e.g., hook event records).
+   */
+  onBeforeMutate?: (uow: IUnitOfWork) => void;
+
+  /**
+   * Callback invoked after successful mutation phase.
+   * Use this for post-mutation processing like hook execution.
+   */
+  onSuccess?: (uow: IUnitOfWork) => Promise<void>;
 }
 
 /**
@@ -370,9 +394,12 @@ export interface ExecuteRestrictedUnitOfWorkOptions {
  * );
  * ```
  */
-export async function executeRestrictedUnitOfWork<TResult>(
+export async function executeRestrictedUnitOfWork<TResult, THooks extends HooksMap = {}>(
   callback: (context: {
-    forSchema: <S extends AnySchema>(schema: S) => TypedUnitOfWork<S, [], unknown>;
+    forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
+      schema: S,
+      hooks?: H,
+    ) => TypedUnitOfWork<S, [], unknown, H>;
     executeRetrieve: () => Promise<void>;
     executeMutate: () => Promise<void>;
     nonce: string;
@@ -401,10 +428,9 @@ export async function executeRestrictedUnitOfWork<TResult>(
       // Create a fresh UOW for this attempt
       const baseUow = options.createUnitOfWork();
 
-      // Create context object with forSchema, executeRetrieve, executeMutate, nonce, and currentAttempt
       const context = {
-        forSchema: <S extends AnySchema>(schema: S) => {
-          return baseUow.forSchema(schema);
+        forSchema: <S extends AnySchema, H extends HooksMap = THooks>(schema: S, hooks?: H) => {
+          return baseUow.forSchema(schema, hooks);
         },
         executeRetrieve: async () => {
           await baseUow.executeRetrieve();
@@ -418,9 +444,18 @@ export async function executeRestrictedUnitOfWork<TResult>(
             await baseUow.executeRetrieve();
           }
 
+          // Add hook mutations before executing
+          if (options.onBeforeMutate) {
+            options.onBeforeMutate(baseUow);
+          }
+
           const result = await baseUow.executeMutations();
           if (!result.success) {
-            throw new Error("Mutations failed due to conflict");
+            throw new ConcurrencyConflictError();
+          }
+
+          if (options.onSuccess) {
+            await options.onSuccess(baseUow);
           }
         },
         nonce: baseUow.nonce,
@@ -440,6 +475,12 @@ export async function executeRestrictedUnitOfWork<TResult>(
         throw new Error("Unit of Work execution aborted");
       }
 
+      // Only retry concurrency conflicts, not other errors
+      if (!(error instanceof ConcurrencyConflictError)) {
+        // Not a concurrency conflict - throw immediately without retry
+        throw error;
+      }
+
       if (!retryPolicy.shouldRetry(attempt, error, signal)) {
         // No more retries - check again if aborted or throw conflict error
         if (signal?.aborted) {

package/src/query/{unit-of-work-coordinator.test.ts → unit-of-work/unit-of-work-coordinator.test.ts}

@@ -1,42 +1,38 @@
 import { describe, it, expect } from "vitest";
-import { schema, idColumn, type FragnoId, referenceColumn } from "../schema/create";
+import { schema, idColumn, type FragnoId, referenceColumn } from "../../schema/create";
 import {
   type UOWCompiler,
   type UOWDecoder,
   createUnitOfWork,
-  type RetrievalOperation,
-  type MutationOperation,
   type CompiledMutation,
+  type UOWExecutor,
 } from "./unit-of-work";
-import type { AnySchema } from "../schema/create";
-
-// Mock compiler that tracks operations
-function createMockCompiler(): UOWCompiler<string> {
-  return {
-    compileRetrievalOperation: (op: RetrievalOperation<AnySchema>) => {
-      return `SELECT from ${op.table.ormName}`;
-    },
-    compileMutationOperation: (op: MutationOperation<AnySchema>) => {
-      return {
-        query: `${op.type.toUpperCase()} ${op.table}`,
-        expectedAffectedRows: op.type === "create" ? null : op.type === "check" ? null : 1,
-        expectedReturnedRows: op.type === "check" ? 1 : null,
-      };
-    },
-  };
+import { GenericSQLUOWOperationCompiler } from "../../adapters/generic-sql/query/generic-sql-uow-operation-compiler";
+import { BetterSQLite3DriverConfig } from "../../adapters/generic-sql/driver-config";
+import { createUOWCompilerFromOperationCompiler } from "../../adapters/shared/uow-operation-compiler";
+import type { CompiledQuery } from "../../sql-driver/sql-driver";
+
+// Create compiler using actual implementation
+function createCompiler(): UOWCompiler<CompiledQuery> {
+  const driverConfig = new BetterSQLite3DriverConfig();
+  const operationCompiler = new GenericSQLUOWOperationCompiler(driverConfig);
+  return createUOWCompilerFromOperationCompiler(operationCompiler);
 }
 
-// Mock executor that tracks execution
-function createMockExecutor() {
+// Mock executor that tracks execution and works with CompiledQuery
+function createMockExecutor(): UOWExecutor<CompiledQuery, unknown> & {
+  getLog: () => string[];
+  clearLog: () => void;
+} {
   const executionLog: string[] = [];
 
   return {
-    executeRetrievalPhase: async (queries: string[]) => {
+    executeRetrievalPhase: async (queries: CompiledQuery[]) => {
       executionLog.push(`RETRIEVAL: ${queries.length} queries`);
       // Return mock results for each query
       return queries.map(() => [{ id: "mock-id", name: "Mock User" }]);
     },
-    executeMutationPhase: async (mutations: CompiledMutation<string>[]) => {
+    executeMutationPhase: async (mutations: CompiledMutation<CompiledQuery>[]) => {
       executionLog.push(`MUTATION: ${mutations.length} mutations`);
       return {
         success: true,
@@ -51,11 +47,13 @@ function createMockExecutor() {
 }
 
 function createMockDecoder(): UOWDecoder {
-  return (rawResults, operations) => {
-    if (rawResults.length !== operations.length) {
-      throw new Error("rawResults and operations must have the same length");
-    }
-    return rawResults;
+  return {
+    decode(rawResults, operations) {
+      if (rawResults.length !== operations.length) {
+        throw new Error("rawResults and operations must have the same length");
+      }
+      return rawResults;
+    },
   };
 }
 
@@ -68,7 +66,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
     );
 
     const executor = createMockExecutor();
-    const parentUow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    const parentUow = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
     // Simulate service method 1: adds retrieval operation via child UOW
     const serviceMethod1 = () => {
@@ -120,7 +118,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
     );
 
     const executor = createMockExecutor();
-    const parentUow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    const parentUow = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
     // Service A: Get user by ID, awaits retrieval phase
     const getUserById = async (userId: string) => {
@@ -205,7 +203,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
     );
 
     const executor = createMockExecutor();
-    const parentUow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    const parentUow = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
     // Service A: Check if user exists
     const validateUser = async (userId: string) => {
@@ -327,7 +325,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
     );
 
     const executor = createMockExecutor();
-    const parentUow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    const parentUow = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
     // Level 1: Handler (root)
     const handler = async () => {
@@ -440,7 +438,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
     );
 
     const executor = createMockExecutor();
-    const parentUow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    const parentUow = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
     // Service method that creates TWO sibling child UOWs
     const processUserOrder = async (email: string) => {
@@ -548,13 +546,13 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
 
     // Create mock executor that returns account data with low balance
     const executionLog: string[] = [];
-    const customExecutor = {
-      executeRetrievalPhase: async (queries: string[]) => {
+    const customExecutor: UOWExecutor<CompiledQuery, unknown> = {
+      executeRetrievalPhase: async (queries: CompiledQuery[]) => {
         executionLog.push(`RETRIEVAL: ${queries.length} queries`);
         // Return mock account data with balance field set to low value
         return queries.map(() => [{ id: "mock-id", userId: "user-1", balance: 100 }]);
       },
-      executeMutationPhase: async (mutations: CompiledMutation<string>[]) => {
+      executeMutationPhase: async (mutations: CompiledMutation<CompiledQuery>[]) => {
         executionLog.push(`MUTATION: ${mutations.length} mutations`);
         return {
           success: true,
@@ -563,7 +561,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
       },
     };
 
-    const parentUow = createUnitOfWork(createMockCompiler(), customExecutor, createMockDecoder());
+    const parentUow = createUnitOfWork(createCompiler(), customExecutor, createMockDecoder());
 
     // Service: Get account balance
     const getAccountBalance = async (userId: string) => {
@@ -654,7 +652,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
     );
 
     const executor = createMockExecutor();
-    const parentUow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    const parentUow = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
     // Service A: Validates user and throws if not active
     const validateActiveUser = async (userId: string) => {
@@ -726,7 +724,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
 
   it("should inherit nonce from parent to children for idempotent operations", () => {
     const executor = createMockExecutor();
-    const parentUow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    const parentUow = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
     // Parent UOW should have a nonce
     const parentNonce = parentUow.nonce;
@@ -756,8 +754,8 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
     const executor = createMockExecutor();
 
     // Create two separate parent UOWs
-    const parentUow1 = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
-    const parentUow2 = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    const parentUow1 = createUnitOfWork(createCompiler(), executor, createMockDecoder());
+    const parentUow2 = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
     // They should have different nonces
     expect(parentUow1.nonce).not.toBe(parentUow2.nonce);
@@ -783,14 +781,14 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
     );
 
     // Create executor that throws "table does not exist" error
-    const failingExecutor = {
+    const failingExecutor: UOWExecutor<CompiledQuery, unknown> = {
       executeRetrievalPhase: async () => {
         throw new Error('relation "settings" does not exist');
       },
       executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
     };
 
-    const parentUow = createUnitOfWork(createMockCompiler(), failingExecutor, createMockDecoder());
+    const parentUow = createUnitOfWork(createCompiler(), failingExecutor, createMockDecoder());
 
     // Service method that awaits retrievalPhase (simulating settingsService.get())
     const getSettingValue = async (key: string) => {

package/src/query/{unit-of-work-types.test.ts → unit-of-work/unit-of-work-types.test.ts}

@@ -1,7 +1,7 @@
 import { describe, expectTypeOf, it } from "vitest";
-import { column, idColumn, referenceColumn, schema } from "../schema/create";
+import { column, idColumn, referenceColumn, schema } from "../../schema/create";
 import { JoinFindBuilder, UnitOfWork } from "./unit-of-work";
-import type { FragnoId, FragnoReference } from "../schema/create";
+import type { FragnoId, FragnoReference } from "../../schema/create";
 
 type Prettify<T> = {
   [K in keyof T]: T[K];
@@ -94,7 +94,9 @@ describe("UnitOfWork type tests", () => {
       executeRetrievalPhase: async () => [],
       executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
     };
-    const mockDecoder = () => [];
+    const mockDecoder = {
+      decode: () => [],
+    };
     return new UnitOfWork(mockCompiler, mockExecutor, mockDecoder).forSchema(testSchema);
   }
 

package/src/query/{unit-of-work.test.ts → unit-of-work/unit-of-work.test.ts}

@@ -1,5 +1,5 @@
 import { describe, it, expect, assert, expectTypeOf } from "vitest";
-import { column, schema, idColumn, FragnoId } from "../schema/create";
+import { column, schema, idColumn, FragnoId } from "../../schema/create";
 import {
   type UOWCompiler,
   type UOWDecoder,
@@ -7,8 +7,8 @@ import {
   type InferIdColumnName,
   type IndexColumns,
 } from "./unit-of-work";
-import { createIndexedBuilder } from "./condition-builder";
-import type { AbstractQuery } from "./query";
+import { createIndexedBuilder } from "../condition-builder";
+import type { SimpleQueryInterface } from "../simple-query-interface";
 
 // Mock compiler and executor for testing
 function createMockCompiler(): UOWCompiler<unknown> {
@@ -26,11 +26,13 @@ function createMockExecutor() {
 }
 
 function createMockDecoder(): UOWDecoder {
-  return (rawResults, operations) => {
-    if (rawResults.length !== operations.length) {
-      throw new Error("rawResults and operations must have the same length");
-    }
-    return rawResults;
+  return {
+    decode(rawResults, operations) {
+      if (rawResults.length !== operations.length) {
+        throw new Error("rawResults and operations must have the same length");
+      }
+      return rawResults;
+    },
   };
 }
 
@@ -119,6 +121,50 @@ describe("FindBuilder", () => {
     expect(op.options.pageSize).toBe(5);
   });
 
+  it("should throw RangeError for pageSize <= 0", () => {
+    const testSchema = schema((s) =>
+      s.addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", "string")),
+    );
+
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+
+    expect(() => {
+      uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary").pageSize(0));
+    }).toThrow(RangeError);
+
+    expect(() => {
+      uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary").pageSize(-1));
+    }).toThrow(RangeError);
+
+    expect(() => {
+      uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary").pageSize(-10));
+    }).toThrow(RangeError);
+  });
+
+  it("should throw RangeError for non-integer pageSize", () => {
+    const testSchema = schema((s) =>
+      s.addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", "string")),
+    );
+
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+
+    expect(() => {
+      uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary").pageSize(1.5));
+    }).toThrow(RangeError);
+
+    expect(() => {
+      uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary").pageSize(3.14));
+    }).toThrow(RangeError);
+
+    expect(() => {
+      uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary").pageSize(NaN));
+    }).toThrow(RangeError);
+
+    expect(() => {
+      uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary").pageSize(Infinity));
+    }).toThrow(RangeError);
+  });
+
   it("should throw if index doesn't exist", () => {
     const testSchema = schema((s) =>
       s.addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", "string")),
@@ -406,6 +452,51 @@ describe("FindBuilder", () => {
     expect(joinOptions.limit).toBe(5);
   });
 
+  it("should throw RangeError for invalid pageSize in join", () => {
+    const testSchema = schema((s) =>
+      s
+        .addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", "string"))
+        .addTable("posts", (t) =>
+          t
+            .addColumn("id", idColumn())
+            .addColumn("userId", column("string"))
+            .addColumn("title", "string")
+            .createIndex("idx_user", ["userId"]),
+        )
+        .addReference("user", {
+          type: "one",
+          from: { table: "posts", column: "userId" },
+          to: { table: "users", column: "id" },
+        }),
+    );
+
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+
+    expect(() => {
+      uow
+        .forSchema(testSchema)
+        .find("posts", (b) =>
+          b.whereIndex("primary").join((jb) => jb["user"]((builder) => builder.pageSize(0))),
+        );
+    }).toThrow(RangeError);
+
+    expect(() => {
+      uow
+        .forSchema(testSchema)
+        .find("posts", (b) =>
+          b.whereIndex("primary").join((jb) => jb["user"]((builder) => builder.pageSize(-5))),
+        );
+    }).toThrow(RangeError);
+
+    expect(() => {
+      uow
+        .forSchema(testSchema)
+        .find("posts", (b) =>
+          b.whereIndex("primary").join((jb) => jb["user"]((builder) => builder.pageSize(2.5))),
+        );
+    }).toThrow(RangeError);
+  });
+
   it("should support nested joins", () => {
     const testSchema = schema((s) =>
       s
@@ -648,7 +739,7 @@ describe("IndexedConditionBuilder", () => {
       );
       const uow = baseUow.forSchema(typeTestSchema);
       expectTypeOf<keyof typeof typeTestSchema.tables>().toEqualTypeOf<"users">();
-      type _Query = AbstractQuery<typeof typeTestSchema>;
+      type _Query = SimpleQueryInterface<typeof typeTestSchema>;
       expectTypeOf<Parameters<_Query["create"]>[0]>().toEqualTypeOf<"users">();
 
       expectTypeOf<Parameters<typeof uow.find>[0]>().toEqualTypeOf<"users">();