jazz-tools 0.18.38 → 0.19.1

package/src/tools/tests/coMap.branch.test.ts

@@ -4,7 +4,7 @@ import { assert, beforeEach, describe, expect, test, vi } from "vitest";
 import { Group, co, subscribeToCoValue, z } from "../exports.js";
 
 import { createJazzTestAccount, setupJazzTestSync } from "../testing.js";
-import { waitFor } from "./utils.js";
+import { assertLoaded, waitFor } from "./utils.js";
 
 beforeEach(async () => {
   cojsonInternals.CO_VALUE_LOADING_CONFIG.RETRY_DELAY = 1000;
@@ -45,7 +45,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "feature-branch" },
       });
 
-      assert(branchPerson);
+      assertLoaded(branchPerson);
 
       // Edit the branch
       branchPerson.$jazz.applyDiff({
@@ -107,7 +107,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "feature-branch" },
       });
 
-      assert(branchPerson);
+      assertLoaded(branchPerson);
 
       // Edit the branch
       branchPerson.$jazz.applyDiff({
@@ -161,7 +161,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "no-changes-branch" },
       });
 
-      assert(branchPerson);
+      assertLoaded(branchPerson);
 
       // Verify branch has same values as original
       expect(branchPerson.name).toBe("John Doe");
@@ -201,7 +201,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "shared-branch" },
       });
 
-      assert(branch1);
+      assertLoaded(branch1);
 
       branch1.$jazz.applyDiff({
         name: "John Smith",
@@ -213,7 +213,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "shared-branch" },
       });
 
-      assert(branch2);
+      assertLoaded(branch2);
 
       // Both branches should have the same changes
       expect(branch1.name).toBe("John Smith");
@@ -267,7 +267,7 @@ describe("CoMap Branching", async () => {
         loadAs: alice,
       });
 
-      assert(branch1);
+      assertLoaded(branch1);
 
       originalPerson.$jazz.applyDiff({
         name: "John Smith",
@@ -280,7 +280,7 @@ describe("CoMap Branching", async () => {
         loadAs: bob,
       });
 
-      assert(branch2);
+      assertLoaded(branch2);
 
       // Both branches should have the same changes
       expect(branch1.name).toBe("John Doe");
@@ -337,7 +337,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "double-merge-branch" },
       });
 
-      assert(branch);
+      assertLoaded(branch);
 
       branch.$jazz.applyDiff({
         name: "John Smith",
@@ -392,7 +392,7 @@ describe("CoMap Branching", async () => {
         loadAs: alice,
       });
 
-      assert(branch1);
+      assertLoaded(branch1);
 
       branch1.$jazz.applyDiff({
         name: "John Smith",
@@ -404,7 +404,7 @@ describe("CoMap Branching", async () => {
         loadAs: bob,
       });
 
-      assert(branch2);
+      assertLoaded(branch2);
 
       branch2.$jazz.applyDiff({
         age: 31,
@@ -464,8 +464,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "load-by-id-branch" },
       });
 
-      assert(branch);
-
+      assertLoaded(branch);
       expect(branch.$jazz.id).toBe(originalPerson.$jazz.id);
     });
 
@@ -492,7 +491,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "conflict-branch" },
       });
 
-      assert(branch);
+      assertLoaded(branch);
 
       // User 1 creates a branch and makes changes
       branch.$jazz.applyDiff({
@@ -544,7 +543,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "align-branch" },
       });
 
-      assert(branch);
+      assertLoaded(branch);
 
       branch.$jazz.applyDiff({
         name: "John Smith",
@@ -565,7 +564,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "align-branch" },
       });
 
-      assert(loadedBranch);
+      assertLoaded(loadedBranch);
 
       expect(loadedBranch.name).toBe("John Smith");
       expect(loadedBranch.age).toBe(30);
@@ -623,7 +622,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "large-doc-edit" },
       });
 
-      assert(branch);
+      assertLoaded(branch);
 
       // Make extensive changes to the branch
       branch.$jazz.applyDiff({
@@ -646,7 +645,7 @@ describe("CoMap Branching", async () => {
         },
       });
 
-      assert(loadedLargeDoc);
+      assertLoaded(loadedLargeDoc);
 
       // Verify original is unchanged
       expect(loadedLargeDoc.title).toBe("Large Document");
@@ -703,7 +702,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "subscribe-branch" },
       });
 
-      assert(branch);
+      assertLoaded(branch);
 
       const spy = vi.fn();
       branch.$jazz.subscribe(
@@ -774,7 +773,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "ensure-loaded-branch" },
       });
 
-      assert(branch);
+      assertLoaded(branch);
 
       branch.$jazz.applyDiff({
         name: "John Smith",
@@ -834,7 +833,7 @@ describe("CoMap Branching", async () => {
         unstable_branch: { name: "schema-subscribe-branch" },
       });
 
-      assert(branch);
+      assertLoaded(branch);
 
       branch.$jazz.applyDiff({
         name: "John Smith",

package/src/tools/tests/coMap.record.test-d.ts

@@ -1,7 +1,8 @@
 import { describe, expectTypeOf, test } from "vitest";
 import { Group, co, z } from "../exports.js";
 import { Account } from "../index.js";
-import { Loaded } from "../internal.js";
+import { Loaded, MaybeLoaded, LoadedAndRequired } from "../internal.js";
+import { assertLoaded } from "./utils.js";
 
 describe("CoMap.Record", () => {
   describe("init", () => {
@@ -180,9 +181,9 @@ describe("CoMap.Record", () => {
         },
       });
 
-      type ExpectedType = {
+      type ExpectedType = MaybeLoaded<{
         [key: string]: Loaded<typeof Dog>;
-      } | null;
+      }>;
 
       function matches(value: ExpectedType) {
         return value;
@@ -210,17 +211,16 @@ describe("CoMap.Record", () => {
         },
       });
 
-      type Expect = NonNullable<typeof loadedPerson> extends never
+      type Expect = LoadedAndRequired<typeof loadedPerson> extends never
         ? "error: is never"
         : "ok";
 
       expectTypeOf("ok" as const).toEqualTypeOf<Expect>();
 
-      expectTypeOf(loadedPerson?.pet1).toEqualTypeOf<
-        Loaded<typeof Dog> | undefined
-      >();
-      expectTypeOf(loadedPerson?.pet3).toEqualTypeOf<
-        Loaded<typeof Dog> | undefined | null
+      assertLoaded(loadedPerson);
+      expectTypeOf(loadedPerson.pet1).toEqualTypeOf<Loaded<typeof Dog>>();
+      expectTypeOf(loadedPerson.pet3).branded.toEqualTypeOf<
+        MaybeLoaded<Loaded<typeof Dog>> | undefined
       >();
     });
 
@@ -245,25 +245,26 @@ describe("CoMap.Record", () => {
           [userId]: true,
           pet2: true,
           [userId2]: {
-            $onError: null,
+            $onError: "catch",
           },
         },
       });
 
-      type Expect = NonNullable<typeof loadedPerson> extends never
+      type Expect = LoadedAndRequired<typeof loadedPerson> extends never
         ? "error: is never"
         : "ok";
 
       expectTypeOf("ok" as const).toEqualTypeOf<Expect>();
 
-      expectTypeOf(loadedPerson?.pet1).toEqualTypeOf<
-        Loaded<typeof Dog> | undefined | null
+      assertLoaded(loadedPerson);
+      expectTypeOf(loadedPerson.pet1).branded.toEqualTypeOf<
+        MaybeLoaded<Loaded<typeof Dog>> | undefined
       >();
-      expectTypeOf(loadedPerson?.pet2).toEqualTypeOf<
-        Loaded<typeof Dog> | undefined | null
+      expectTypeOf(loadedPerson.pet2).branded.toEqualTypeOf<
+        MaybeLoaded<Loaded<typeof Dog>> | undefined
       >();
-      expectTypeOf(loadedPerson?.pet3).toEqualTypeOf<
-        Loaded<typeof Dog> | undefined | null
+      expectTypeOf(loadedPerson.pet3).branded.toEqualTypeOf<
+        MaybeLoaded<Loaded<typeof Dog>> | undefined
       >();
     });
 
@@ -282,17 +283,18 @@ describe("CoMap.Record", () => {
 
       const loadedPerson = await Person.load(person.$jazz.id);
 
-      type Expect = NonNullable<typeof loadedPerson> extends never
+      type Expect = LoadedAndRequired<typeof loadedPerson> extends never
         ? "error: is never"
         : "ok";
 
       expectTypeOf("ok" as const).toEqualTypeOf<Expect>();
 
-      expectTypeOf(loadedPerson?.pet1).toEqualTypeOf<
-        Loaded<typeof Dog> | undefined | null
+      assertLoaded(loadedPerson);
+      expectTypeOf(loadedPerson.pet1).branded.toEqualTypeOf<
+        MaybeLoaded<Loaded<typeof Dog>> | undefined
       >();
-      expectTypeOf(loadedPerson?.pet3).toEqualTypeOf<
-        Loaded<typeof Dog> | undefined | null
+      expectTypeOf(loadedPerson.pet3).branded.toEqualTypeOf<
+        MaybeLoaded<Loaded<typeof Dog>> | undefined
       >();
     });
 
@@ -311,13 +313,13 @@ describe("CoMap.Record", () => {
 
       const loadedPerson = await Person.load(person.$jazz.id, {
         resolve: {
-          $each: { $onError: null },
+          $each: { $onError: "catch" },
         },
       });
 
-      type ExpectedType = {
-        [key: string]: Loaded<typeof Dog> | null;
-      } | null;
+      type ExpectedType = MaybeLoaded<{
+        [key: string]: MaybeLoaded<Loaded<typeof Dog>>;
+      }>;
 
       function matches(value: ExpectedType) {
         return value;

package/src/tools/tests/coMap.record.test.ts

@@ -12,8 +12,8 @@ import { FileStream, Group, co, z } from "../exports.js";
 import { Loaded } from "../implementation/zodSchema/zodSchema.js";
 import { Account } from "../index.js";
 import { createJazzTestAccount, setupJazzTestSync } from "../testing.js";
-import { waitFor } from "./utils.js";
-import { TypeSym } from "../internal.js";
+import { assertLoaded, waitFor } from "./utils.js";
+import { CoValueLoadingState, TypeSym } from "../internal.js";
 
 const Crypto = await WasmCrypto.create();
 
@@ -216,7 +216,7 @@ describe("CoMap.Record", async () => {
         },
       });
 
-      assert(loadedPerson);
+      assertLoaded(loadedPerson);
       expect(loadedPerson.pet1?.name).toEqual("Rex");
       expect(loadedPerson.pet2?.name).toEqual("Fido");
     });
@@ -240,7 +240,7 @@ describe("CoMap.Record", async () => {
         },
       });
 
-      assert(loadedPerson);
+      assertLoaded(loadedPerson);
       expect(loadedPerson.pet1?.name).toEqual("Rex");
     });
 
@@ -263,7 +263,9 @@ describe("CoMap.Record", async () => {
         },
       });
 
-      expect(loadedPerson).toEqual(null);
+      expect(loadedPerson.$jazz.loadingState).toBe(
+        CoValueLoadingState.UNAVAILABLE,
+      );
     });
 
     test("loading a locally available record using autoload for the refs", async () => {
@@ -281,8 +283,12 @@ describe("CoMap.Record", async () => {
 
       const loadedPerson = await Person.load(person.$jazz.id);
 
-      assert(loadedPerson);
+      assertLoaded(loadedPerson);
+      assert(loadedPerson.pet1);
+      assertLoaded(loadedPerson.pet1);
       expect(loadedPerson.pet1?.name).toEqual("Rex");
+      assert(loadedPerson.pet2);
+      assertLoaded(loadedPerson.pet2);
       expect(loadedPerson.pet2?.name).toEqual("Fido");
     });
 
@@ -484,12 +490,13 @@ describe("CoRecord unique methods", () => {
       "test-record",
       group.$jazz.id,
     );
+    assertLoaded(foundRecord);
     expect(foundRecord).toEqual(originalRecord);
-    expect(foundRecord?.item1).toBe(1);
-    expect(foundRecord?.item2).toBe(2);
+    expect(foundRecord.item1).toBe(1);
+    expect(foundRecord.item2).toBe(2);
   });
 
-  test("loadUnique returns null for non-existent record", async () => {
+  test("loadUnique returns 'unavailable' for non-existent record", async () => {
     const ItemRecord = co.record(z.string(), z.number());
     const group = Group.create();
 
@@ -497,7 +504,9 @@ describe("CoRecord unique methods", () => {
       "non-existent",
       group.$jazz.id,
     );
-    expect(foundRecord).toBeNull();
+    expect(foundRecord.$jazz.loadingState).toBe(
+      CoValueLoadingState.UNAVAILABLE,
+    );
   });
 
   test("upsertUnique creates new record when none exists", async () => {
@@ -512,10 +521,10 @@ describe("CoRecord unique methods", () => {
       owner: group,
     });
 
-    expect(result).not.toBeNull();
-    expect(result?.item1).toBe(1);
-    expect(result?.item2).toBe(2);
-    expect(result?.item3).toBe(3);
+    assertLoaded(result);
+    expect(result.item1).toBe(1);
+    expect(result.item2).toBe(2);
+    expect(result.item3).toBe(3);
   });
 
   test("upsertUnique updates existing record", async () => {
@@ -535,10 +544,11 @@ describe("CoRecord unique methods", () => {
       owner: group,
     });
 
+    assertLoaded(updatedRecord);
     expect(updatedRecord).toEqual(originalRecord); // Should be the same instance
-    expect(updatedRecord?.updated1).toBe(10);
-    expect(updatedRecord?.updated2).toBe(20);
-    expect(updatedRecord?.updated3).toBe(30);
+    expect(updatedRecord.updated1).toBe(10);
+    expect(updatedRecord.updated2).toBe(20);
+    expect(updatedRecord.updated3).toBe(30);
   });
 
   test("upsertUnique with CoValue items", async () => {
@@ -561,9 +571,9 @@ describe("CoRecord unique methods", () => {
       resolve: { first: true, second: true },
     });
 
-    expect(result).not.toBeNull();
-    expect(result?.first?.name).toBe("First");
-    expect(result?.second?.name).toBe("Second");
+    assertLoaded(result);
+    expect(result.first?.name).toBe("First");
+    expect(result.second?.name).toBe("Second");
   });
 
   test("findUnique returns correct ID", async () => {

package/src/tools/tests/coMap.test-d.ts

@@ -2,7 +2,8 @@ import { assert, describe, expectTypeOf, test } from "vitest";
 import { ZodNumber, ZodOptional, ZodString } from "zod/v4";
 import { Group, co, z } from "../exports.js";
 import { Account } from "../index.js";
-import { CoMap, Loaded } from "../internal.js";
+import { CoMap, Loaded, MaybeLoaded } from "../internal.js";
+import { assertLoaded } from "./utils.js";
 
 describe("CoMap", async () => {
   describe("init", () => {
@@ -562,12 +563,12 @@ describe("CoMap resolution", async () => {
       },
     });
 
-    type ExpectedType = {
+    type ExpectedType = MaybeLoaded<{
       name: string;
       age: number;
       dog1: Loaded<typeof Dog>;
-      dog2: Loaded<typeof Dog> | null;
-    } | null;
+      dog2: MaybeLoaded<Loaded<typeof Dog>>;
+    }>;
 
     function matches(value: ExpectedType) {
       return value;
@@ -575,11 +576,11 @@ describe("CoMap resolution", async () => {
 
     matches(loadedPerson);
 
-    assert(loadedPerson);
+    assertLoaded(loadedPerson);
     expectTypeOf<typeof loadedPerson.dog1.name>().toEqualTypeOf<string>();
-    expectTypeOf<typeof loadedPerson.dog2>().toEqualTypeOf<Loaded<
-      typeof Dog
-    > | null>();
+    expectTypeOf<typeof loadedPerson.dog2>().branded.toEqualTypeOf<
+      MaybeLoaded<Loaded<typeof Dog>>
+    >();
   });
 
   test("partial loading a map with string resolve", async () => {
@@ -610,12 +611,12 @@ describe("CoMap resolution", async () => {
       },
     });
 
-    type ExpectedType = {
+    type ExpectedType = MaybeLoaded<{
       name: string;
       age: number;
-      dog1: Loaded<typeof Dog> | null;
-      dog2: Loaded<typeof Dog> | null;
-    } | null;
+      dog1: MaybeLoaded<Loaded<typeof Dog>>;
+      dog2: MaybeLoaded<Loaded<typeof Dog>>;
+    }>;
 
     function matches(value: ExpectedType) {
       return value;
@@ -623,13 +624,13 @@ describe("CoMap resolution", async () => {
 
     matches(loadedPerson);
 
-    assert(loadedPerson);
-    expectTypeOf<typeof loadedPerson.dog1>().toEqualTypeOf<Loaded<
-      typeof Dog
-    > | null>();
-    expectTypeOf<typeof loadedPerson.dog2>().toEqualTypeOf<Loaded<
-      typeof Dog
-    > | null>();
+    assertLoaded(loadedPerson);
+    expectTypeOf<typeof loadedPerson.dog1>().branded.toEqualTypeOf<
+      MaybeLoaded<Loaded<typeof Dog>>
+    >();
+    expectTypeOf<typeof loadedPerson.dog2>().branded.toEqualTypeOf<
+      MaybeLoaded<Loaded<typeof Dog>>
+    >();
   });
 
   test("loading a map with deep resolve and $onError", async () => {
@@ -655,16 +656,16 @@ describe("CoMap resolution", async () => {
     const loadedPerson = await Person.load(person.$jazz.id, {
       resolve: {
         dog1: true,
-        dog2: { $onError: null },
+        dog2: { $onError: "catch" },
       },
     });
 
-    type ExpectedType = {
+    type ExpectedType = MaybeLoaded<{
       name: string;
       age: number;
       dog1: Loaded<typeof Dog>;
-      dog2: Loaded<typeof Dog> | null;
-    } | null;
+      dog2: MaybeLoaded<Loaded<typeof Dog>>;
+    }>;
 
     function matches(value: ExpectedType) {
       return value;
@@ -672,11 +673,11 @@ describe("CoMap resolution", async () => {
 
     matches(loadedPerson);
 
-    assert(loadedPerson);
+    assertLoaded(loadedPerson);
     expectTypeOf<typeof loadedPerson.dog1.name>().toEqualTypeOf<string>();
-    expectTypeOf<typeof loadedPerson.dog2>().branded.toEqualTypeOf<Loaded<
-      typeof Dog
-    > | null>();
+    expectTypeOf<typeof loadedPerson.dog2>().branded.toEqualTypeOf<
+      MaybeLoaded<Loaded<typeof Dog>>
+    >();
   });
 
   test("loading a map with a nullable field", async () => {
@@ -698,11 +699,12 @@ describe("CoMap resolution", async () => {
 
     const loadedPerson = await Person.load(person.$jazz.id);
 
-    expectTypeOf(loadedPerson!).toEqualTypeOf<
+    assertLoaded(loadedPerson);
+    expectTypeOf(loadedPerson).branded.toEqualTypeOf<
       {
         readonly name: string;
         readonly age: number | null;
-        readonly dog: Loaded<typeof Dog> | null;
+        readonly dog: MaybeLoaded<Loaded<typeof Dog>>;
       } & CoMap
     >();
   });