jazz-tools 0.18.37 → 0.19.0

package/src/react-core/tests/useSubscriptionSelector.test.ts

@@ -1,7 +1,8 @@
 // @vitest-environment happy-dom
 
 import { cojsonInternals } from "cojson";
-import { co, z } from "jazz-tools";
+import { co, z, CoValueLoadingState } from "jazz-tools";
+import { assertLoaded } from "jazz-tools/testing";
 import { beforeEach, describe, expect, expectTypeOf, it } from "vitest";
 import {
   useCoValueSubscription,
@@ -47,7 +48,8 @@ describe("useSubscriptionSelector", () => {
       return useSubscriptionSelector(subscription);
     });
 
-    expect(result.current?.value).toBe("123");
+    assertLoaded(result.current);
+    expect(result.current.value).toBe("123");
   });
 
   it("should resolve nested coValues", () => {
@@ -72,10 +74,12 @@ describe("useSubscriptionSelector", () => {
       return useSubscriptionSelector(subscription);
     });
 
-    expect(result.current?.nested?.content).toBe("456");
+    assertLoaded(result.current);
+    assertLoaded(result.current.nested);
+    expect(result.current.nested.content).toBe("456");
   });
 
-  it("should return null on invalid coValue id", async () => {
+  it("should return 'unavailable' on invalid coValue id", async () => {
     const TestMap = co.map({
       value: z.string(),
     });
@@ -85,10 +89,12 @@ describe("useSubscriptionSelector", () => {
       return useSubscriptionSelector(subscription);
     });
 
-    expect(result.current).toBeUndefined();
+    expect(result.current.$jazz.loadingState).toBe(CoValueLoadingState.LOADING);
 
     await waitFor(() => {
-      expect(result.current).toBeNull();
+      expect(result.current.$jazz.loadingState).toBe(
+        CoValueLoadingState.UNAVAILABLE,
+      );
     });
   });
 
@@ -120,7 +126,12 @@ describe("useSubscriptionSelector", () => {
     const { result } = renderHook(() => {
       const subscription = useCoValueSubscription(TestMap, map.$jazz.id);
       return useSubscriptionSelector(subscription, {
-        select: (v) => v?.value,
+        select: (v) => {
+          if (!v.$isLoaded) {
+            return "Loading...";
+          }
+          return v.value;
+        },
       });
     });
 
@@ -134,9 +145,18 @@ describe("useSubscriptionSelector", () => {
 
     const { result } = renderHook(
       () => {
-        const subscription = useAccountSubscription(co.account());
+        const subscription = useAccountSubscription(co.account(), {
+          resolve: {
+            profile: true,
+          },
+        });
         return useSubscriptionSelector(subscription, {
-          select: (v) => v?.profile?.name,
+          select: (v) => {
+            if (!v.$isLoaded) {
+              return "Loading...";
+            }
+            return v.profile.name;
+          },
         });
       },
       {
@@ -159,7 +179,12 @@ describe("useSubscriptionSelector", () => {
     const { result } = renderHook(() => {
       const subscription = useCoValueSubscription(TestMap, map.$jazz.id);
       return useSubscriptionSelector(subscription, {
-        select: (v) => v?.value,
+        select: (v) => {
+          if (!v.$isLoaded) {
+            return "Loading...";
+          }
+          return v.value;
+        },
       });
     });
 
@@ -187,7 +212,12 @@ describe("useSubscriptionSelector", () => {
       useRenderCount(() => {
         const subscription = useCoValueSubscription(TestMap, map.$jazz.id);
         return useSubscriptionSelector(subscription, {
-          select: (v) => v?.value,
+          select: (v) => {
+            if (!v.$isLoaded) {
+              return "Loading...";
+            }
+            return v.value;
+          },
         });
       }),
     );
@@ -218,10 +248,14 @@ describe("useSubscriptionSelector", () => {
       useRenderCount(() => {
         const subscription = useCoValueSubscription(TestMap, map.$jazz.id);
         return useSubscriptionSelector(subscription, {
-          select: (v) =>
-            v
+          select: (v) => {
+            if (!v.$isLoaded) {
+              return [];
+            }
+            return v
               ? [Math.floor(v.value / 5), Math.floor(v.other / 5)].toSorted()
-              : [],
+              : [];
+          },
           equalityFn: (a, b) => a.every((v, i) => v === b[i]),
         });
       }),

package/src/react-native-core/hooks.tsx

@@ -13,8 +13,8 @@ export {
   useAuthSecretStorage,
   useIsAuthenticated,
   useAccount,
-  useCoStateWithSelector,
-  useAccountWithSelector,
+  useAgent,
+  useLogOut,
   useSyncConnectionStatus,
   useCoValueSubscription,
   useAccountSubscription,

package/src/react-native-core/media/image.tsx

@@ -76,7 +76,9 @@ export const Image = forwardRef<RNImage, ImageProps>(function Image(
   { imageId, width, height, placeholder, ...props },
   ref,
 ) {
-  const image = useCoState(ImageDefinition, imageId);
+  const image = useCoState(ImageDefinition, imageId, {
+    select: (image) => (image.$isLoaded ? image : null),
+  });
   const [src, setSrc] = useState<string | undefined>(
     image?.placeholderDataURL ??
       "data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==",

package/src/svelte/jazz.class.svelte.ts

@@ -3,24 +3,33 @@ import type {
   AccountClass,
   AnyAccountSchema,
   BranchDefinition,
+  CoValue,
   CoValueClassOrSchema,
   CoValueFromRaw,
+  SchemaResolveQuery,
   InstanceOfSchema,
   Loaded,
+  MaybeLoaded,
+  NotLoaded,
   ResolveQuery,
   ResolveQueryStrict,
 } from "jazz-tools";
 import {
   coValueClassFromCoValueClassOrSchema,
   subscribeToCoValue,
+  createUnloadedCoValue,
+  CoValueLoadingState,
 } from "jazz-tools";
 import { untrack } from "svelte";
 import { createSubscriber } from "svelte/reactivity";
 import { useIsAuthenticated } from "./auth/useIsAuthenticated.svelte.js";
 import { getJazzContext } from "./jazz.svelte";
 
-type CoStateOptions<V extends CoValueClassOrSchema, R extends ResolveQuery<V>> = { 
-  resolve?: ResolveQueryStrict<V, R>,
+type CoStateOptions<
+  V extends CoValueClassOrSchema,
+  R extends ResolveQuery<V>,
+> = {
+  resolve?: ResolveQueryStrict<V, R>;
   /**
    * Create or load a branch for isolated editing.
    *
@@ -35,17 +44,22 @@ type CoStateOptions<V extends CoValueClassOrSchema, R extends ResolveQuery<V>> =
    *   the branch. If not provided, the branch is owned by the current user.
    *
    * For more info see the [branching](https://jazz.tools/docs/svelte/using-covalues/version-control) documentation.
-  */
-  unstable_branch?: BranchDefinition
+   */
+  unstable_branch?: BranchDefinition;
 };
 
 type CoStateId = string | undefined | null;
 
 export class CoState<
   V extends CoValueClassOrSchema,
-  R extends ResolveQuery<V> = true,
+  // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
+  R extends ResolveQuery<V> = SchemaResolveQuery<V>,
 > {
-  #value: Loaded<V, R> | undefined | null = undefined;
+  #value: MaybeLoaded<Loaded<V, R>> = createUnloadedCoValue(
+    "",
+    CoValueLoadingState.LOADING,
+  );
+  #previousValue: MaybeLoaded<CoValue> | undefined = undefined;
   #ctx = getJazzContext<InstanceOfSchema<AccountClass<Account>>>();
   #id: CoStateId;
   #subscribe: () => void;
@@ -58,7 +72,9 @@ export class CoState<
     options?: CoStateOptions<V, R> | (() => CoStateOptions<V, R>),
   ) {
     this.#id = $derived.by(typeof id === "function" ? id : () => id);
-    this.#options = $derived.by(typeof options === "function" ? options : () => options);
+    this.#options = $derived.by(
+      typeof options === "function" ? options : () => options,
+    );
 
     this.#subscribe = createSubscriber((update) => {
       this.#update = update;
@@ -71,22 +87,29 @@ export class CoState<
 
       return untrack(() => {
         if (!ctx || !id) {
-          return this.update(undefined);
+          return this.update(
+            createUnloadedCoValue(id ?? "", CoValueLoadingState.UNAVAILABLE),
+          );
         }
         const agent = "me" in ctx ? ctx.me : ctx.guest;
+        const resolve = getResolveQuery(Schema, options?.resolve);
 
         const unsubscribe = subscribeToCoValue(
           coValueClassFromCoValueClassOrSchema(Schema),
           id,
           {
             // @ts-expect-error The resolve query type isn't compatible with the coValueClassFromCoValueClassOrSchema conversion
-            resolve: options?.resolve,
+            resolve,
             loadAs: agent,
             onUnavailable: () => {
-              this.update(null);
+              this.update(
+                createUnloadedCoValue(id, CoValueLoadingState.UNAVAILABLE),
+              );
             },
             onUnauthorized: () => {
-              this.update(null);
+              this.update(
+                createUnloadedCoValue(id, CoValueLoadingState.UNAUTHORIZED),
+              );
             },
             syncResolution: true,
             unstable_branch: options?.unstable_branch,
@@ -103,8 +126,11 @@ export class CoState<
     });
   }
 
-  update(value: Loaded<V, R> | undefined | null) {
-    if (this.#value === value) return;
+  update(value: MaybeLoaded<Loaded<V, R>>) {
+    if (shouldSkipUpdate(value, this.#value)) {
+      return;
+    }
+    this.#previousValue = value;
     this.#value = value;
     this.#update();
   }
@@ -117,18 +143,27 @@ export class CoState<
 
 export class AccountCoState<
   A extends
-  | (AccountClass<Account> & CoValueFromRaw<Account>)
-  | AnyAccountSchema,
-  R extends ResolveQuery<A> = true,
+    | (AccountClass<Account> & CoValueFromRaw<Account>)
+    | AnyAccountSchema,
+  // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
+  R extends ResolveQuery<A> = SchemaResolveQuery<A>,
 > {
-  #value: Loaded<A, R> | undefined | null = undefined;
+  #value: MaybeLoaded<Loaded<A, R>> = createUnloadedCoValue(
+    "",
+    CoValueLoadingState.LOADING,
+  );
   #ctx = getJazzContext<InstanceOfSchema<A>>();
   #subscribe: () => void;
   #options: CoStateOptions<A, R> | undefined;
-  #update = () => { };
+  #update = () => {};
 
-  constructor(Schema: A, options?: CoStateOptions<A, R> | (() => CoStateOptions<A, R>)) {
-    this.#options = $derived.by(typeof options === "function" ? options : () => options);
+  constructor(
+    Schema: A,
+    options?: CoStateOptions<A, R> | (() => CoStateOptions<A, R>),
+  ) {
+    this.#options = $derived.by(
+      typeof options === "function" ? options : () => options,
+    );
 
     this.#subscribe = createSubscriber((update) => {
       this.#update = update;
@@ -140,23 +175,35 @@ export class AccountCoState<
 
       return untrack(() => {
         if (!ctx || !("me" in ctx)) {
-          return this.update(undefined);
+          return this.update(
+            createUnloadedCoValue("", CoValueLoadingState.UNAVAILABLE),
+          );
         }
 
         const me = ctx.me;
+        const resolve = getResolveQuery(Schema, options?.resolve);
 
         const unsubscribe = subscribeToCoValue(
           coValueClassFromCoValueClassOrSchema(Schema),
           me.$jazz.id,
           {
-            // @ts-expect-error The resolve query type isn't compatible with the coValueClassFromCoValueClassOrSchema conversion
-            resolve: options?.resolve,
+            resolve,
             loadAs: me,
             onUnavailable: () => {
-              this.update(null);
+              this.update(
+                createUnloadedCoValue(
+                  me.$jazz.id,
+                  CoValueLoadingState.UNAVAILABLE,
+                ),
+              );
             },
             onUnauthorized: () => {
-              this.update(null);
+              this.update(
+                createUnloadedCoValue(
+                  me.$jazz.id,
+                  CoValueLoadingState.UNAUTHORIZED,
+                ),
+              );
             },
             syncResolution: true,
             unstable_branch: options?.unstable_branch,
@@ -173,8 +220,8 @@ export class AccountCoState<
     });
   }
 
-  update(value: Loaded<A, R> | undefined | null) {
-    if (this.#value === value) return;
+  update(value: MaybeLoaded<Loaded<A, R>>) {
+    if (shouldSkipUpdate(value, this.#value)) return;
     this.#value = value;
     this.#update();
   }
@@ -206,6 +253,20 @@ export class AccountCoState<
   }
 }
 
+function shouldSkipUpdate(
+  newValue: MaybeLoaded<CoValue>,
+  previousValue: MaybeLoaded<CoValue>,
+) {
+  if (previousValue === newValue) return true;
+  // Avoid re-renders if the value is not loaded and didn't change
+  return (
+    previousValue.$jazz.id === newValue.$jazz.id &&
+    !previousValue.$isLoaded &&
+    !newValue.$isLoaded &&
+    previousValue.$jazz.loadingState === newValue.$jazz.loadingState
+  );
+}
+
 /**
  * Class that provides the current connection status to the Jazz sync server.
  *
@@ -249,3 +310,18 @@ export class SyncConnectionStatus {
     return this.#ctx.current?.connected() ?? false;
   }
 }
+
+function getResolveQuery(
+  Schema: CoValueClassOrSchema,
+  // We don't need type validation here, since this is an internal API
+  resolveQuery?: ResolveQuery<any>,
+): ResolveQuery<any> {
+  if (resolveQuery) {
+    return resolveQuery;
+  }
+  // Check the schema is a CoValue schema (and not a CoValue class)
+  if ("resolveQuery" in Schema) {
+    return Schema.resolveQuery;
+  }
+  return true;
+}

package/src/svelte/media/image.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { ImageDefinition } from "jazz-tools";
+  import { CoValueLoadingState, ImageDefinition } from "jazz-tools";
   import { highestResAvailable } from "jazz-tools/media";
   import { onDestroy } from "svelte";
   import { CoState } from "../jazz.class.svelte";
@@ -25,8 +25,9 @@
     width: number | undefined;
     height: number | undefined;
   }>(() => {
-    const originalWidth = imageState.current?.originalSize?.[0];
-    const originalHeight = imageState.current?.originalSize?.[1];
+    const originalSize = imageState.current.$isLoaded ? imageState.current.originalSize : undefined;
+    const originalWidth = originalSize?.[0];
+    const originalHeight = originalSize?.[1];
 
     // Both width and height are "original"
     if (width === "original" && height === "original") {
@@ -68,13 +69,13 @@
     }
 
     const image = imageState.current;
-    if (image === undefined)
+    if (image.$jazz.loadingState === CoValueLoadingState.LOADING)
       return (
         placeholder ??
         "data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
       );
 
-    if (!image) return undefined;
+    if (!image.$isLoaded) return undefined;
 
     const bestImage = highestResAvailable(
       image,

package/src/svelte/tests/AccountCoState.svelte.test-d.ts

@@ -0,0 +1,23 @@
+import { co, CoPlainText } from "jazz-tools";
+import { assertLoaded, createJazzTestAccount, setupJazzTestSync } from "jazz-tools/testing";
+import { beforeEach, describe, expectTypeOf, test } from "vitest";
+import { AccountCoState } from "../jazz.class.svelte";
+
+describe("AccountCoState", () => {
+  beforeEach(async () => {
+    await setupJazzTestSync();
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+      creationProps: { name: "Hermes Puggington" },
+    });
+  });
+
+  test("should use the schema's resolve query if no resolve query is provided", async () => {
+    const AccountWithProfile = co.account().resolved({ profile: true });
+
+    const loadedAccount = new AccountCoState(AccountWithProfile);
+
+    assertLoaded(loadedAccount.current);
+    expectTypeOf<typeof loadedAccount.current.profile.name>().toEqualTypeOf<string>();
+  });
+});

package/src/svelte/tests/CoState.svelte.test-d.ts

@@ -0,0 +1,20 @@
+import { co, CoPlainText } from "jazz-tools";
+import { assertLoaded } from "jazz-tools/testing";
+import { describe, expectTypeOf, test } from "vitest";
+import { CoState } from "../jazz.class.svelte";
+
+describe("CoState", () => {
+  test("should use the schema's resolve query if no resolve query is provided", async () => {
+    const Person = co.map({
+      name: co.plainText(),
+    });
+
+    const PersonWithName = Person.resolved({ name: true });
+    const person = Person.create({ name: "John Doe" });
+
+    const loadedPerson = new CoState(PersonWithName, person.$jazz.id);
+
+    assertLoaded(loadedPerson.current);
+    expectTypeOf<typeof loadedPerson.current.name>().toEqualTypeOf<CoPlainText>();
+  });
+});

package/src/svelte/tests/CoState.svelte.test.ts

@@ -0,0 +1,57 @@
+// @vitest-environment happy-dom
+
+import { co, Account, CoValueLoadingState, Group } from "jazz-tools";
+import { beforeEach, describe, expect, it } from "vitest";
+import { createJazzTestAccount, setupJazzTestSync } from "../testing";
+import { render, screen, waitFor } from "./testUtils";
+import TestCoStateWrapper from "./TestCoStateWrapper.svelte";
+
+describe("CoState", () => {
+  let serverAccount: Account;
+  let clientAccount: Account;
+  let publicGroup: Group;
+
+  beforeEach(async () => {
+    await setupJazzTestSync();
+    await createJazzTestAccount({
+      creationProps: { name: "Server" },
+      isCurrentActiveAccount: true,
+    });
+
+    serverAccount = Account.getMe();
+    clientAccount = await createJazzTestAccount({
+      creationProps: { name: "Client" },
+    });
+    publicGroup = Group.create(serverAccount).makePublic("reader");
+  });
+
+  it("should use the schema's resolve query if no resolve query is provided", async () => {
+    const Person = co.map({
+      name: co.plainText(),
+    });
+    const PersonWithName = Person.resolved({ name: true });
+    const person = Person.create({ name: "John Doe" }, publicGroup);
+
+    render(
+      TestCoStateWrapper,
+      {
+        Schema: PersonWithName,
+        id: person.$jazz.id,
+      },
+      {
+        account: clientAccount,
+      },
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("loading-state").textContent).toBe(
+        CoValueLoadingState.LOADED,
+      );
+    });
+    expect(screen.getByTestId("is-loaded").textContent).toBe("true");
+    const stateValue = JSON.parse(
+      screen.getByTestId("state-value").textContent ?? "",
+    );
+    expect(stateValue.name).toBe("John Doe");
+  });
+});

package/src/svelte/tests/TestCoStateWrapper.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+  import type { CoValueClassOrSchema, ResolveQuery } from 'jazz-tools';
+  import { CoState } from '../jazz.class.svelte';
+
+  type Props<V extends CoValueClassOrSchema, R extends ResolveQuery<V>> = {
+    Schema: V;
+    id: string;
+    options?: { resolve?: R };
+  };
+
+  let { Schema, id, options }: Props<any, any> = $props();
+
+  const state = new CoState(Schema, id, options);
+</script>
+
+<div data-testid="costate-wrapper">
+  <div data-testid="loading-state">{state.current.$jazz.loadingState}</div>
+  <div data-testid="is-loaded">{state.current.$isLoaded ? 'true' : 'false'}</div>
+  {#if state.current.$isLoaded}
+    <div data-testid="state-value">{JSON.stringify(state.current.toJSON())}</div>
+  {/if}
+</div>
+

package/src/tools/coValues/CoValueBase.ts

@@ -3,6 +3,7 @@ import {
   AnonymousJazzAgent,
   CoValue,
   CoValueClass,
+  CoValueLoadingState,
   ID,
   RegisteredSchemas,
   type SubscriptionScope,
@@ -18,6 +19,13 @@ export abstract class CoValueBase implements CoValue {
   declare [TypeSym]: string;
 
   declare abstract $jazz: CoValueJazzApi<this>;
+  declare $isLoaded: true;
+
+  constructor() {
+    Object.defineProperties(this, {
+      $isLoaded: { value: true, enumerable: false },
+    });
+  }
 
   /** @category Internals */
   static fromRaw<V extends CoValue>(this: CoValueClass<V>, raw: RawCoValue): V {
@@ -60,6 +68,10 @@ export abstract class CoValueJazzApi<V extends CoValue> {
     return this.raw.id;
   }
 
+  get loadingState(): typeof CoValueLoadingState.LOADED {
+    return CoValueLoadingState.LOADED;
+  }
+
   abstract get raw(): RawCoValue;
   abstract get owner(): Group | undefined;