@fragno-dev/db 0.1.13 → 0.1.15

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

@@ -1,7 +1,6 @@
 import { describe, it, expect, assert, expectTypeOf } from "vitest";
-import { column, schema, idColumn } from "../schema/create";
+import { column, schema, idColumn, FragnoId } from "../schema/create";
 import {
-  UnitOfWork,
   type UOWCompiler,
   type UOWDecoder,
   createUnitOfWork,
@@ -9,14 +8,10 @@ import {
   type IndexColumns,
 } from "./unit-of-work";
 import { createIndexedBuilder } from "./condition-builder";
-import type { AnySchema } from "../schema/create";
 import type { AbstractQuery } from "./query";
 
 // Mock compiler and executor for testing
-function createMockCompiler<TSchema extends AnySchema = AnySchema>(): UOWCompiler<
-  TSchema,
-  unknown
-> {
+function createMockCompiler(): UOWCompiler<unknown> {
   return {
     compileRetrievalOperation: () => null,
     compileMutationOperation: () => null,
@@ -30,7 +25,7 @@ function createMockExecutor() {
   };
 }
 
-function createMockDecoder<TSchema extends AnySchema = AnySchema>(): UOWDecoder<TSchema> {
+function createMockDecoder(): UOWDecoder {
   return (rawResults, operations) => {
     if (rawResults.length !== operations.length) {
       throw new Error("rawResults and operations must have the same length");
@@ -53,13 +48,8 @@ describe("FindBuilder", () => {
       ),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
-    uow.find("users", (b) => b.whereIndex("primary"));
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+    uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary"));
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -77,15 +67,12 @@ describe("FindBuilder", () => {
       ),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
-    uow.find("users", (b) =>
-      b.whereIndex("idx_email", (eb) => eb("email", "=", "test@example.com")),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+    uow
+      .forSchema(testSchema)
+      .find("users", (b) =>
+        b.whereIndex("idx_email", (eb) => eb("email", "=", "test@example.com")),
+      );
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -97,15 +84,12 @@ describe("FindBuilder", () => {
       s.addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", "string")),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
     const cursor = "eyJpbmRleFZhbHVlcyI6eyJpZCI6InVzZXIxMjMifSwiZGlyZWN0aW9uIjoiZm9yd2FyZCJ9";
-    uow.find("users", (b) => b.whereIndex("primary").after(cursor).pageSize(10));
+    uow
+      .forSchema(testSchema)
+      .find("users", (b) => b.whereIndex("primary").after(cursor).pageSize(10));
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -120,15 +104,12 @@ describe("FindBuilder", () => {
       s.addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", "string")),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
     const cursor = "eyJpbmRleFZhbHVlcyI6eyJpZCI6InVzZXI0NTYifSwiZGlyZWN0aW9uIjoiYmFja3dhcmQifQ==";
-    uow.find("users", (b) => b.whereIndex("primary").before(cursor).pageSize(5));
+    uow
+      .forSchema(testSchema)
+      .find("users", (b) => b.whereIndex("primary").before(cursor).pageSize(5));
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -143,14 +124,9 @@ describe("FindBuilder", () => {
       s.addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", "string")),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
     expect(() => {
-      uow.find("users", (b) => b.whereIndex("nonexistent" as "primary"));
+      uow.forSchema(testSchema).find("users", (b) => b.whereIndex("nonexistent" as "primary"));
     }).toThrow('Index "nonexistent" not found on table "users"');
   });
 
@@ -159,14 +135,9 @@ describe("FindBuilder", () => {
       s.addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", "string")),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
     expect(() => {
-      uow.find("users", (b) => b);
+      uow.forSchema(testSchema).find("users", (b) => b);
     }).toThrow(
       'Must specify an index using .whereIndex() before finalizing find operation on table "users"',
     );
@@ -179,13 +150,8 @@ describe("FindBuilder", () => {
       ),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
-    uow.find("users", (b) => b.whereIndex("primary").selectCount());
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+    uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary").selectCount());
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -197,27 +163,21 @@ describe("FindBuilder", () => {
       s.addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", "string")),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
     // select() then selectCount()
     expect(() => {
-      uow.find("users", (b) => b.whereIndex("primary").select(["name"]).selectCount());
+      uow
+        .forSchema(testSchema)
+        .find("users", (b) => b.whereIndex("primary").select(["name"]).selectCount());
     }).toThrow(/cannot call selectCount/i);
 
     // selectCount() then select()
-    const uow2 = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow2 = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
     expect(() => {
-      uow2.find("users", (b) => b.whereIndex("primary").selectCount().select(["name"]));
+      uow2
+        .forSchema(testSchema)
+        .find("users", (b) => b.whereIndex("primary").selectCount().select(["name"]));
     }).toThrow(/cannot call select/i);
   });
 
@@ -232,13 +192,10 @@ describe("FindBuilder", () => {
       ),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
-    uow.find("users", (b) => b.whereIndex("primary").orderByIndex("idx_created", "desc"));
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+    uow
+      .forSchema(testSchema)
+      .find("users", (b) => b.whereIndex("primary").orderByIndex("idx_created", "desc"));
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -271,16 +228,13 @@ describe("FindBuilder", () => {
         }),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
-    uow.find("posts", (b) =>
-      b.whereIndex("primary").join((jb) => jb["user"]((builder) => builder.select(["name"]))),
-    );
+    uow
+      .forSchema(testSchema)
+      .find("posts", (b) =>
+        b.whereIndex("primary").join((jb) => jb["user"]((builder) => builder.select(["name"]))),
+      );
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -308,15 +262,10 @@ describe("FindBuilder", () => {
         }),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
     // Join without builder function should use default options
-    uow.find("posts", (b) => b.whereIndex("primary").join((jb) => jb.user()));
+    uow.forSchema(testSchema).find("posts", (b) => b.whereIndex("primary").join((jb) => jb.user()));
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -352,22 +301,19 @@ describe("FindBuilder", () => {
         }),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
-
-    uow.find("posts", (b) =>
-      b
-        .whereIndex("primary")
-        .join((jb) =>
-          jb["user"]((builder) =>
-            builder.whereIndex("idx_name", (eb) => eb("name", "=", "Alice")).select(["name"]),
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+
+    uow
+      .forSchema(testSchema)
+      .find("posts", (b) =>
+        b
+          .whereIndex("primary")
+          .join((jb) =>
+            jb["user"]((builder) =>
+              builder.whereIndex("idx_name", (eb) => eb("name", "=", "Alice")).select(["name"]),
+            ),
           ),
-        ),
-    );
+      );
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -404,18 +350,15 @@ describe("FindBuilder", () => {
         }),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
-    uow.find("posts", (b) =>
-      b
-        .whereIndex("primary")
-        .join((jb) => jb["user"]((builder) => builder.orderByIndex("idx_created", "desc"))),
-    );
+    uow
+      .forSchema(testSchema)
+      .find("posts", (b) =>
+        b
+          .whereIndex("primary")
+          .join((jb) => jb["user"]((builder) => builder.orderByIndex("idx_created", "desc"))),
+      );
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -446,16 +389,13 @@ describe("FindBuilder", () => {
         }),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
-    uow.find("posts", (b) =>
-      b.whereIndex("primary").join((jb) => jb["user"]((builder) => builder.pageSize(5))),
-    );
+    uow
+      .forSchema(testSchema)
+      .find("posts", (b) =>
+        b.whereIndex("primary").join((jb) => jb["user"]((builder) => builder.pageSize(5))),
+      );
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -498,24 +438,21 @@ describe("FindBuilder", () => {
         }),
     );
 
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
-
-    uow.find("comments", (b) =>
-      b
-        .whereIndex("primary")
-        .join((jb) =>
-          jb["post"]((postBuilder) =>
-            postBuilder
-              .select(["title"])
-              .join((jb2) => jb2["user"]((userBuilder) => userBuilder.select(["name"]))),
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+
+    uow
+      .forSchema(testSchema)
+      .find("comments", (b) =>
+        b
+          .whereIndex("primary")
+          .join((jb) =>
+            jb["post"]((postBuilder) =>
+              postBuilder
+                .select(["title"])
+                .join((jb2) => jb2["user"]((userBuilder) => userBuilder.select(["name"]))),
+            ),
           ),
-        ),
-    );
+      );
 
     const ops = uow.getRetrievalOperations();
     expect(ops).toHaveLength(1);
@@ -704,18 +641,17 @@ describe("IndexedConditionBuilder", () => {
       >;
       expectTypeOf<_IndexColumnNames>().toEqualTypeOf<"name" | "age">();
 
-      const uow = createUnitOfWork(
-        typeTestSchema,
-        createMockCompiler<typeof typeTestSchema>(),
+      const baseUow = createUnitOfWork(
+        createMockCompiler(),
         createMockExecutor(),
-        createMockDecoder<typeof typeTestSchema>(),
+        createMockDecoder(),
       );
-      expectTypeOf(uow.schema).toEqualTypeOf(typeTestSchema);
+      const uow = baseUow.forSchema(typeTestSchema);
       expectTypeOf<keyof typeof typeTestSchema.tables>().toEqualTypeOf<"users">();
       type _Query = AbstractQuery<typeof typeTestSchema>;
       expectTypeOf<Parameters<_Query["create"]>[0]>().toEqualTypeOf<"users">();
 
-      expectTypeOf(uow.find).parameter(0).toEqualTypeOf<"users">();
+      expectTypeOf<Parameters<typeof uow.find>[0]>().toEqualTypeOf<"users">();
 
       uow.find("users", (b) =>
         b.whereIndex("primary", (eb) => {
@@ -748,15 +684,10 @@ describe("UpdateBuilder with string ID", () => {
   );
 
   it("should allow update with string ID", async () => {
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
     // Should work with string ID
-    uow.update("users", "user-123", (b) => b.set({ name: "New Name" }));
+    uow.forSchema(testSchema).update("users", "user-123", (b) => b.set({ name: "New Name" }));
 
     const ops = uow.getMutationOperations();
     expect(ops).toHaveLength(1);
@@ -770,16 +701,13 @@ describe("UpdateBuilder with string ID", () => {
   });
 
   it("should throw when using check() with string ID", async () => {
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
     // Should throw because check() is not allowed with string ID
     expect(() => {
-      uow.update("users", "user-123", (b) => b.set({ name: "New Name" }).check());
+      uow
+        .forSchema(testSchema)
+        .update("users", "user-123", (b) => b.set({ name: "New Name" }).check());
     }).toThrow(
       'Cannot use check() with a string ID on table "users". Version checking requires a FragnoId with version information.',
     );
@@ -792,15 +720,10 @@ describe("DeleteBuilder with string ID", () => {
   );
 
   it("should allow delete with string ID", async () => {
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
     // Should work with string ID
-    uow.delete("users", "user-123");
+    uow.forSchema(testSchema).delete("users", "user-123");
 
     const ops = uow.getMutationOperations();
     expect(ops).toMatchObject([
@@ -813,16 +736,11 @@ describe("DeleteBuilder with string ID", () => {
   });
 
   it("should throw when using check() with string ID", async () => {
-    const uow = new UnitOfWork(
-      testSchema,
-      createMockCompiler(),
-      createMockExecutor(),
-      createMockDecoder(),
-    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
 
     // Should throw because check() is not allowed with string ID
     expect(() => {
-      uow.delete("users", "user-123", (b) => b.check());
+      uow.forSchema(testSchema).delete("users", "user-123", (b) => b.check());
     }).toThrow(
       'Cannot use check() with a string ID on table "users". Version checking requires a FragnoId with version information.',
     );
@@ -845,10 +763,10 @@ describe("getCreatedIds", () => {
       }),
     };
 
-    const uow = new UnitOfWork(testSchema, createMockCompiler(), executor, createMockDecoder());
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
 
-    uow.create("users", { email: "user1@example.com", name: "User 1" });
-    uow.create("users", { email: "user2@example.com", name: "User 2" });
+    uow.forSchema(testSchema).create("users", { email: "user1@example.com", name: "User 1" });
+    uow.forSchema(testSchema).create("users", { email: "user2@example.com", name: "User 2" });
 
     await uow.executeMutations();
     const createdIds = uow.getCreatedIds();
@@ -871,10 +789,10 @@ describe("getCreatedIds", () => {
       }),
     };
 
-    const uow = new UnitOfWork(testSchema, createMockCompiler(), executor, createMockDecoder());
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
 
-    uow.create("users", { email: "user1@example.com", name: "User 1" });
-    uow.create("users", { email: "user2@example.com", name: "User 2" });
+    uow.forSchema(testSchema).create("users", { email: "user1@example.com", name: "User 1" });
+    uow.forSchema(testSchema).create("users", { email: "user2@example.com", name: "User 2" });
 
     await uow.executeMutations();
     const createdIds = uow.getCreatedIds();
@@ -895,9 +813,11 @@ describe("getCreatedIds", () => {
       }),
     };
 
-    const uow = new UnitOfWork(testSchema, createMockCompiler(), executor, createMockDecoder());
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
 
-    uow.create("users", { id: "my-custom-id", email: "user@example.com", name: "User" });
+    uow
+      .forSchema(testSchema)
+      .create("users", { id: "my-custom-id", email: "user@example.com", name: "User" });
 
     await uow.executeMutations();
     const createdIds = uow.getCreatedIds();
@@ -916,11 +836,11 @@ describe("getCreatedIds", () => {
       }),
     };
 
-    const uow = new UnitOfWork(testSchema, createMockCompiler(), executor, createMockDecoder());
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
 
-    uow.create("users", { email: "user@example.com", name: "User" });
-    uow.update("users", "existing-id", (b) => b.set({ name: "Updated" }));
-    uow.delete("users", "other-id");
+    uow.forSchema(testSchema).create("users", { email: "user@example.com", name: "User" });
+    uow.forSchema(testSchema).update("users", "existing-id", (b) => b.set({ name: "Updated" }));
+    uow.forSchema(testSchema).delete("users", "other-id");
 
     await uow.executeMutations();
     const createdIds = uow.getCreatedIds();
@@ -931,17 +851,775 @@ describe("getCreatedIds", () => {
   });
 
   it("should throw when called before executeMutations", () => {
-    const uow = new UnitOfWork(
-      testSchema,
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+
+    uow.forSchema(testSchema).create("users", { email: "user@example.com", name: "User" });
+
+    expect(() => uow.getCreatedIds()).toThrow(
+      "getCreatedIds() can only be called after executeMutations()",
+    );
+  });
+});
+
+describe("Phase promises with multiple views", () => {
+  it("should return only operations added to the current view when using retrievalPhase promise", async () => {
+    // Create two separate schemas
+    const schema1 = schema((s) =>
+      s.addTable("users", (t) =>
+        t.addColumn("id", idColumn()).addColumn("name", "string").addColumn("email", "string"),
+      ),
+    );
+
+    const schema2 = schema((s) =>
+      s.addTable("posts", (t) =>
+        t.addColumn("id", idColumn()).addColumn("title", "string").addColumn("content", "string"),
+      ),
+    );
+
+    // Create a schema namespace map
+    const schemaNamespaceMap = new WeakMap<typeof schema1 | typeof schema2, string>();
+    schemaNamespaceMap.set(schema1, "namespace1");
+    schemaNamespaceMap.set(schema2, "namespace2");
+
+    // Mock executor that returns distinct results
+    const executor = {
+      executeRetrievalPhase: async () => {
+        return [
+          [{ id: "user1", name: "Alice", email: "alice@example.com" }],
+          [{ id: "user2", name: "Bob", email: "bob@example.com" }],
+          [{ id: "post1", title: "Post 1", content: "Content 1" }],
+        ];
+      },
+      executeMutationPhase: async () => ({
+        success: true,
+        createdInternalIds: [],
+      }),
+    };
+
+    // Create parent UOW
+    const parentUow = createUnitOfWork(
       createMockCompiler(),
-      createMockExecutor(),
+      executor,
       createMockDecoder(),
+      schemaNamespaceMap,
+      "test-uow",
     );
 
-    uow.create("users", { email: "user@example.com", name: "User" });
+    // Add a find operation via a schema1 view (but don't keep a reference to this view)
+    parentUow.forSchema(schema1).find("users", (b) => b.whereIndex("primary"));
 
-    expect(() => uow.getCreatedIds()).toThrow(
-      "getCreatedIds() can only be called after executeMutations()",
+    // Create a view for schema1 and add another find operation
+    const view1 = parentUow.forSchema(schema1).find("users", (b) => b.whereIndex("primary"));
+
+    // Create a view for schema2 and add a find operation
+    const view2 = parentUow.forSchema(schema2).find("posts", (b) => b.whereIndex("primary"));
+
+    // Execute retrieval phase on parent
+    const parentResults = await parentUow.executeRetrieve();
+
+    // Parent should have all 3 results
+    expect(parentResults).toHaveLength(3);
+
+    // View1's retrievalPhase promise should only contain results from operations added through view1
+    // (which is index 1 in the parent's operations)
+    const view1Results = await view1.retrievalPhase;
+    expect(view1Results).toHaveLength(1);
+    expect(view1Results[0]).toEqual([{ id: "user2", name: "Bob", email: "bob@example.com" }]);
+
+    // View2's retrievalPhase promise should only contain results from operations added through view2
+    // (which is index 2 in the parent's operations)
+    const view2Results = await view2.retrievalPhase;
+    expect(view2Results).toHaveLength(1);
+    expect(view2Results[0]).toEqual([{ id: "post1", title: "Post 1", content: "Content 1" }]);
+  });
+
+  it("should isolate operations when getUnitOfWork is called multiple times with same schema", async () => {
+    const testSchema = schema((s) =>
+      s.addTable("users", (t) =>
+        t.addColumn("id", idColumn()).addColumn("name", "string").addColumn("email", "string"),
+      ),
+    );
+
+    const executor = {
+      executeRetrievalPhase: async () => {
+        return [
+          [{ id: "user1", name: "Alice", email: "alice@example.com" }],
+          [{ id: "user2", name: "Bob", email: "bob@example.com" }],
+        ];
+      },
+      executeMutationPhase: async () => ({
+        success: true,
+        createdInternalIds: [],
+      }),
+    };
+
+    const parentUow = createUnitOfWork(
+      createMockCompiler(),
+      executor,
+      createMockDecoder(),
+      undefined,
+      "test-uow",
+    );
+
+    // Simulate what happens in db-fragment-definition-builder when getUnitOfWork(schema) is called twice
+    const view1 = parentUow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary"));
+
+    const view2 = parentUow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary"));
+
+    // Execute retrieval
+    await parentUow.executeRetrieve();
+
+    // Each view should only see its own operation's results
+    const view1Results = await view1.retrievalPhase;
+    expect(view1Results).toHaveLength(1);
+    expect(view1Results[0]).toEqual([{ id: "user1", name: "Alice", email: "alice@example.com" }]);
+
+    const view2Results = await view2.retrievalPhase;
+    expect(view2Results).toHaveLength(1);
+    expect(view2Results[0]).toEqual([{ id: "user2", name: "Bob", email: "bob@example.com" }]);
+  });
+
+  it("should show that getCreatedIds returns ALL created IDs regardless of which view created them", async () => {
+    const schema1 = schema((s) =>
+      s.addTable("users", (t) =>
+        t.addColumn("id", idColumn()).addColumn("name", "string").addColumn("email", "string"),
+      ),
+    );
+
+    const schema2 = schema((s) =>
+      s.addTable("posts", (t) =>
+        t.addColumn("id", idColumn()).addColumn("title", "string").addColumn("content", "string"),
+      ),
     );
+
+    const schemaNamespaceMap = new WeakMap<typeof schema1 | typeof schema2, string>();
+    schemaNamespaceMap.set(schema1, "namespace1");
+    schemaNamespaceMap.set(schema2, "namespace2");
+
+    const executor = {
+      executeRetrievalPhase: async () => [],
+      executeMutationPhase: async () => ({
+        success: true,
+        createdInternalIds: [1n, 2n],
+      }),
+    };
+
+    const parentUow = createUnitOfWork(
+      createMockCompiler(),
+      executor,
+      createMockDecoder(),
+      schemaNamespaceMap,
+      "test-uow",
+    );
+
+    // View1 creates one user
+    const view1 = parentUow.forSchema(schema1);
+    view1.create("users", { name: "Alice", email: "alice@example.com" });
+
+    // View2 creates one post
+    const view2 = parentUow.forSchema(schema2);
+    view2.create("posts", { title: "Post 1", content: "Content 1" });
+
+    // Execute mutations
+    await parentUow.executeMutations();
+
+    // Both views see ALL created IDs (not filtered by view)
+    const view1Ids = view1.getCreatedIds();
+    const view2Ids = view2.getCreatedIds();
+
+    expect(view1Ids).toHaveLength(2); // Sees both IDs, not just the one it created
+    expect(view2Ids).toHaveLength(2); // Sees both IDs, not just the one it created
+
+    // They're the same array
+    expect(view1Ids).toEqual(view2Ids);
+  });
+
+  it("should generate unique IDs when multiple views create items", async () => {
+    const schema1 = schema((s) =>
+      s.addTable("users", (t) =>
+        t.addColumn("id", idColumn()).addColumn("name", "string").addColumn("email", "string"),
+      ),
+    );
+
+    const schema2 = schema((s) =>
+      s.addTable("posts", (t) =>
+        t.addColumn("id", idColumn()).addColumn("title", "string").addColumn("content", "string"),
+      ),
+    );
+
+    const schemaNamespaceMap = new WeakMap<typeof schema1 | typeof schema2, string>();
+    schemaNamespaceMap.set(schema1, "namespace1");
+    schemaNamespaceMap.set(schema2, "namespace2");
+
+    const executor = {
+      executeRetrievalPhase: async () => [],
+      executeMutationPhase: async () => ({
+        success: true,
+        createdInternalIds: [1n, 2n],
+      }),
+    };
+
+    const parentUow = createUnitOfWork(
+      createMockCompiler(),
+      executor,
+      createMockDecoder(),
+      schemaNamespaceMap,
+      "test-uow",
+    );
+
+    // View1 creates a user
+    const view1 = parentUow.forSchema(schema1);
+    const userId = view1.create("users", { name: "Alice", email: "alice@example.com" });
+
+    // View2 creates a post
+    const view2 = parentUow.forSchema(schema2);
+    const postId = view2.create("posts", { title: "Post 1", content: "Content 1" });
+
+    // IDs should be unique before execution
+    expect(userId.externalId).not.toBe(postId.externalId);
+    expect(userId.externalId).toBeTruthy();
+    expect(postId.externalId).toBeTruthy();
+    expect(userId.internalId).toBeUndefined();
+    expect(postId.internalId).toBeUndefined();
+
+    // Execute mutations
+    await parentUow.executeMutations();
+
+    // Get the created IDs after execution
+    const createdIds = parentUow.getCreatedIds();
+    expect(createdIds).toHaveLength(2);
+
+    // Both should have external IDs set (from create operation)
+    expect(createdIds[0].externalId).toBe(userId.externalId);
+    expect(createdIds[1].externalId).toBe(postId.externalId);
+
+    // Both should now have internal IDs (from database)
+    expect(createdIds[0].internalId).toBe(1n);
+    expect(createdIds[1].internalId).toBe(2n);
+
+    // IDs should still be unique
+    expect(createdIds[0].externalId).not.toBe(createdIds[1].externalId);
+  });
+});
+
+describe("Error Handling", () => {
+  const testSchema = schema((s) =>
+    s.addTable("users", (t) =>
+      t.addColumn("id", idColumn()).addColumn("name", "string").addColumn("email", "string"),
+    ),
+  );
+
+  it("should throw error from executeRetrieve() when retrieval fails", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        throw new Error("Database connection failed");
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary"));
+
+    await expect(uow.executeRetrieve()).rejects.toThrow("Database connection failed");
+  });
+
+  it("should throw error from executeMutations() when mutation fails", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => [],
+      executeMutationPhase: async () => {
+        throw new Error("Write conflict");
+      },
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).create("users", { name: "Alice", email: "alice@example.com" });
+
+    await expect(uow.executeMutations()).rejects.toThrow("Write conflict");
+  });
+
+  it("should reject retrievalPhase promise when executeRetrieve() fails", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        throw new Error("Query timeout");
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary"));
+
+    // Start executing (this will fail)
+    const executePromise = uow.executeRetrieve().catch((e) => {
+      return (e as Error).message;
+    });
+
+    uow.retrievalPhase
+      .then(() => {
+        throw new Error("Should not be called");
+      })
+      .catch(() => {
+        throw new Error("Should not be called");
+      });
+
+    // uow.retrievalPhase should not be settled yet
+
+    // Wait for execute to complete
+    expect(await executePromise).toBe("Query timeout");
+  });
+
+  it("should reject mutationPhase promise when executeMutations() fails", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => [],
+      executeMutationPhase: async () => {
+        throw new Error("Constraint violation");
+      },
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).create("users", { name: "Alice", email: "alice@example.com" });
+
+    // Start executing (this will fail)
+    const executePromise = uow.executeMutations().catch((e) => {
+      return (e as Error).message;
+    });
+
+    uow.mutationPhase
+      .then(() => {
+        throw new Error("Should not be called");
+      })
+      .catch(() => {
+        throw new Error("Should not be called");
+      });
+    // Wait for execute to complete
+    expect(await executePromise).toBe("Constraint violation");
+  });
+
+  it("should not cause unhandled promise rejection when executeRetrieve() fails and coordination promise is not awaited", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        throw new Error("Table does not exist");
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary"));
+
+    // Access the retrievalPhase promise but don't await it
+    // This simulates the internal coordination promise that might not be awaited
+    const _retrievalPhase = uow.retrievalPhase;
+
+    const errorResolver = Promise.withResolvers<void>();
+
+    // Execute and catch the error from executeRetrieve()
+    try {
+      await uow.executeRetrieve();
+    } catch (error) {
+      // Error is caught, this is expected
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toBe("Table does not exist");
+      errorResolver.resolve();
+    }
+
+    await errorResolver.promise;
+  });
+
+  it("should not cause unhandled promise rejection when executeMutations() fails and coordination promise is not awaited", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => [],
+      executeMutationPhase: async () => {
+        throw new Error("Deadlock detected");
+      },
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).create("users", { name: "Alice", email: "alice@example.com" });
+
+    // Access the mutationPhase promise but don't await it
+    // This simulates the internal coordination promise that might not be awaited
+    const _mutationPhase = uow.mutationPhase;
+
+    const errorResolver = Promise.withResolvers<void>();
+
+    // Execute and catch the error from executeMutations()
+    try {
+      await uow.executeMutations();
+    } catch (error) {
+      // Error is caught, this is expected
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toBe("Deadlock detected");
+      errorResolver.resolve();
+    }
+
+    await errorResolver.promise;
+  });
+
+  it("should handle error in executeRetrieve() when coordination promise is never accessed", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        throw new Error("Connection lost");
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary"));
+
+    // Don't access retrievalPhase at all - this is the most common case
+    // The internal coordination promise should not cause unhandled rejection
+    const errorResolver = Promise.withResolvers<void>();
+
+    // Execute and catch the error
+    try {
+      await uow.executeRetrieve();
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toBe("Connection lost");
+      errorResolver.resolve();
+    }
+
+    await errorResolver.promise;
+  });
+
+  it("should handle error in executeMutations() when coordination promise is never accessed", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => [],
+      executeMutationPhase: async () => {
+        throw new Error("Transaction aborted");
+      },
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).create("users", { name: "Alice", email: "alice@example.com" });
+
+    // Don't access mutationPhase at all - this is the most common case
+    // The internal coordination promise should not cause unhandled rejection
+    const errorResolver = Promise.withResolvers<void>();
+    // Execute and catch the error
+    try {
+      await uow.executeMutations();
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toBe("Transaction aborted");
+      errorResolver.resolve();
+    }
+
+    await errorResolver.promise;
+  });
+
+  it("should handle reset() after retrieval error", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        throw new Error("First attempt failed");
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).find("users", (b) => b.whereIndex("primary"));
+
+    // First attempt fails
+    const errorResolver = Promise.withResolvers<void>();
+    try {
+      await uow.executeRetrieve();
+    } catch (error) {
+      expect((error as Error).message).toBe("First attempt failed");
+      errorResolver.resolve();
+    }
+
+    // Reset the UOW
+    uow.reset();
+
+    // The UOW should be in a clean state
+    expect(uow.state).toBe("building-retrieval");
+    expect(uow.getRetrievalOperations()).toHaveLength(0);
+
+    await errorResolver.promise;
+  });
+
+  it("should handle reset() after mutation error", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => [],
+      executeMutationPhase: async () => {
+        throw new Error("First mutation failed");
+      },
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    uow.forSchema(testSchema).create("users", { name: "Alice", email: "alice@example.com" });
+
+    // First attempt fails
+    const errorResolver = Promise.withResolvers<void>();
+    try {
+      await uow.executeMutations();
+    } catch (error) {
+      expect((error as Error).message).toBe("First mutation failed");
+      errorResolver.resolve();
+    }
+
+    // Reset the UOW
+    uow.reset();
+
+    // The UOW should be in a clean state
+    expect(uow.state).toBe("building-retrieval");
+    expect(uow.getMutationOperations()).toHaveLength(0);
+
+    await errorResolver.promise;
+  });
+
+  it("should support standalone check() operation", () => {
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+    const typedUow = uow.forSchema(testSchema);
+
+    // Create a FragnoId for testing
+    const userId = FragnoId.fromExternal("user-123", 5);
+
+    typedUow.check("users", userId);
+
+    const mutationOps = uow.getMutationOperations();
+    expect(mutationOps).toHaveLength(1);
+
+    const checkOp = mutationOps[0];
+    assert(checkOp);
+    assert(checkOp.type === "check");
+    expect(checkOp.table).toBe("users");
+    expect(checkOp.id).toBe(userId);
+  });
+});
+
+describe("findFirst convenience method", () => {
+  const testSchema = schema((s) =>
+    s
+      .addTable("users", (t) =>
+        t
+          .addColumn("id", idColumn())
+          .addColumn("name", "string")
+          .addColumn("email", "string")
+          .createIndex("idx_email", ["email"])
+          .createIndex("idx_name", ["name"]),
+      )
+      .addTable("posts", (t) =>
+        t
+          .addColumn("id", idColumn())
+          .addColumn("userId", "string")
+          .addColumn("title", "string")
+          .createIndex("idx_user", ["userId"]),
+      ),
+  );
+
+  it("should return a single result instead of an array", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        return [[{ id: "mock-id", name: "Mock User", email: "mock@example.com" }]];
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+
+    // Use findFirst instead of find
+    const typedUow = uow.forSchema(testSchema).findFirst("users", (b) => b.whereIndex("primary"));
+
+    // Execute retrieval
+    await uow.executeRetrieve();
+    const results = await typedUow.retrievalPhase;
+
+    // Result should be a single object, not an array
+    const [user] = results;
+    expect(user).toEqual({ id: "mock-id", name: "Mock User", email: "mock@example.com" });
+    expect(Array.isArray(user)).toBe(false);
+  });
+
+  it("should return null when no results are found", async () => {
+    // Create executor that returns empty results
+    const emptyExecutor = {
+      executeRetrievalPhase: async () => {
+        return [[]]; // Empty array for no results
+      },
+      executeMutationPhase: async () => {
+        return { success: true, createdInternalIds: [] };
+      },
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), emptyExecutor, createMockDecoder());
+
+    const typedUow = uow.forSchema(testSchema).findFirst("users", (b) => b.whereIndex("primary"));
+
+    await uow.executeRetrieve();
+    const results = await typedUow.retrievalPhase;
+    const [user] = results;
+
+    // Should be null when no results
+    expect(user).toBeNull();
+  });
+
+  it("should automatically set pageSize to 1", () => {
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+
+    uow.forSchema(testSchema).findFirst("users", (b) => b.whereIndex("primary"));
+
+    // Check that pageSize was set to 1 in the operation
+    const ops = uow.getRetrievalOperations();
+    expect(ops).toHaveLength(1);
+    expect(ops[0]?.type).toBe("find");
+    if (ops[0]?.type === "find") {
+      expect(ops[0].options.pageSize).toBe(1);
+    }
+  });
+
+  it("should work with custom select clause", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        return [[{ id: "mock-id", name: "Mock User" }]];
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+
+    const typedUow = uow
+      .forSchema(testSchema)
+      .findFirst("users", (b) => b.whereIndex("primary").select(["id", "name"] as const));
+
+    await uow.executeRetrieve();
+    const results = await typedUow.retrievalPhase;
+    const [user] = results;
+
+    expect(user).toBeDefined();
+    expect(user).not.toBeNull();
+    expect(user).toEqual({ id: "mock-id", name: "Mock User" });
+  });
+
+  it("should work with where conditions", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        return [[{ id: "mock-id", name: "Mock User", email: "test@example.com" }]];
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+
+    const typedUow = uow
+      .forSchema(testSchema)
+      .findFirst("users", (b) =>
+        b.whereIndex("idx_email", (eb) => eb("email", "=", "test@example.com")),
+      );
+
+    await uow.executeRetrieve();
+    const results = await typedUow.retrievalPhase;
+    const [user] = results;
+
+    expect(user).toEqual({ id: "mock-id", name: "Mock User", email: "test@example.com" });
+  });
+
+  it("should handle multiple findFirst operations in the same UOW", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        return [
+          [{ id: "user-1", name: "User 1", email: "user1@example.com" }],
+          [{ id: "post-1", userId: "user-1", title: "Post 1" }],
+        ];
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+
+    const typedUow = uow
+      .forSchema(testSchema)
+      .findFirst("users", (b) => b.whereIndex("primary"))
+      .findFirst("posts", (b) => b.whereIndex("primary"));
+
+    await uow.executeRetrieve();
+    const results = await typedUow.retrievalPhase;
+    const [user, post] = results;
+
+    // Both should be single objects, not arrays
+    expect(user).toEqual({ id: "user-1", name: "User 1", email: "user1@example.com" });
+    expect(post).toEqual({ id: "post-1", userId: "user-1", title: "Post 1" });
+    expect(Array.isArray(user)).toBe(false);
+    expect(Array.isArray(post)).toBe(false);
+  });
+
+  it("should handle mix of find and findFirst operations", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        return [
+          [{ id: "user-1", name: "User 1", email: "user1@example.com" }],
+          [
+            { id: "post-1", userId: "user-1", title: "Post 1" },
+            { id: "post-2", userId: "user-1", title: "Post 2" },
+          ],
+        ];
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+
+    const typedUow = uow
+      .forSchema(testSchema)
+      .findFirst("users", (b) => b.whereIndex("primary")) // Single result
+      .find("posts", (b) => b.whereIndex("primary")); // Array of results
+
+    await uow.executeRetrieve();
+    const results = await typedUow.retrievalPhase;
+    const [user, posts] = results;
+
+    // User should be a single object
+    expect(user).toEqual({ id: "user-1", name: "User 1", email: "user1@example.com" });
+    expect(Array.isArray(user)).toBe(false);
+
+    // Posts should be an array
+    expect(Array.isArray(posts)).toBe(true);
+    expect(posts).toHaveLength(2);
+  });
+
+  it("should work with orderByIndex", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        return [[{ id: "user-1", name: "Alice", email: "alice@example.com" }]];
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+
+    const typedUow = uow
+      .forSchema(testSchema)
+      .findFirst("users", (b) => b.whereIndex("idx_name").orderByIndex("idx_name", "asc"));
+
+    await uow.executeRetrieve();
+    const results = await typedUow.retrievalPhase;
+    const [user] = results;
+
+    expect(user).toEqual({ id: "user-1", name: "Alice", email: "alice@example.com" });
+    expect(Array.isArray(user)).toBe(false);
+  });
+
+  it("should work without explicit builder function", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => {
+        return [[{ id: "user-1", name: "User 1", email: "user1@example.com" }]];
+      },
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+
+    // findFirst without builder function should use primary index by default
+    const typedUow = uow.forSchema(testSchema).findFirst("users");
+
+    await uow.executeRetrieve();
+    const results = await typedUow.retrievalPhase;
+    const [user] = results;
+
+    expect(user).toEqual({ id: "user-1", name: "User 1", email: "user1@example.com" });
+    expect(Array.isArray(user)).toBe(false);
+
+    // Verify the operation used the primary index
+    const ops = uow.getRetrievalOperations();
+    expect(ops[0]?.indexName).toBe("_primary");
   });
 });