jazz-tools 0.19.20 → 0.19.21

package/src/react-core/tests/useCoStates.test.tsx

@@ -0,0 +1,414 @@
+// @vitest-environment happy-dom
+
+import { cojsonInternals } from "cojson";
+import { Loaded, co, z } from "jazz-tools";
+import { assertLoaded } from "jazz-tools/testing";
+import { assert, beforeEach, describe, expect, expectTypeOf, it } from "vitest";
+import React, { Suspense } from "react";
+import { useCoStates, useSuspenseCoStates } from "../hooks.js";
+import { createJazzTestAccount, setupJazzTestSync } from "../testing.js";
+import { act, renderHook, waitFor } from "./testUtils.js";
+
+const ProjectSchema = co.map({
+  name: z.string(),
+});
+
+beforeEach(async () => {
+  cojsonInternals.setCoValueLoadingRetryDelay(20);
+
+  await setupJazzTestSync({
+    asyncPeers: true,
+  });
+
+  await createJazzTestAccount({
+    isCurrentActiveAccount: true,
+  });
+});
+
+describe("useSuspenseCoStates", () => {
+  it("should return loaded values for all subscriptions", async () => {
+    const project1 = ProjectSchema.create({ name: "My Project 1" });
+    const project2 = ProjectSchema.create({ name: "My Project 2" });
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <Suspense fallback={<div>Loading...</div>}>{children}</Suspense>
+    );
+
+    const { result } = await act(async () => {
+      return renderHook(
+        () =>
+          useSuspenseCoStates(ProjectSchema, [
+            project1.$jazz.id,
+            project2.$jazz.id,
+          ]),
+        {
+          wrapper,
+        },
+      );
+    });
+
+    // Wait for any async operations to complete
+    await waitFor(() => {
+      expect(result.current).toBeDefined();
+      expect(result.current.length).toBe(2);
+    });
+
+    const [loadedProject1, loadedProject2] = result.current;
+
+    assert(loadedProject1);
+    expect(loadedProject1.name).toBe("My Project 1");
+
+    assert(loadedProject2);
+    expect(loadedProject2.name).toBe("My Project 2");
+  });
+
+  it("should have correct return types for each entry", async () => {
+    const project1 = ProjectSchema.create({ name: "Project 1" });
+    const project2 = ProjectSchema.create({ name: "Project 2" });
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <Suspense fallback={<div>Loading...</div>}>{children}</Suspense>
+    );
+
+    const ids = [project1.$jazz.id, project2.$jazz.id] as const;
+
+    const { result } = await act(async () => {
+      return renderHook(() => useSuspenseCoStates(ProjectSchema, ids), {
+        wrapper,
+      });
+    });
+
+    await waitFor(() => {
+      expect(result.current).toBeDefined();
+      expect(result.current.length).toBe(2);
+    });
+
+    expectTypeOf(result.current).toEqualTypeOf<
+      Loaded<typeof ProjectSchema>[]
+    >();
+  });
+
+  it("should re-render when any value changes", async () => {
+    const project1 = ProjectSchema.create({ name: "Project 1" });
+    const project2 = ProjectSchema.create({ name: "Project 2" });
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <Suspense fallback={<div>Loading...</div>}>{children}</Suspense>
+    );
+
+    const { result } = await act(async () => {
+      return renderHook(
+        () =>
+          useSuspenseCoStates(ProjectSchema, [
+            project1.$jazz.id,
+            project2.$jazz.id,
+          ]),
+        {
+          wrapper,
+        },
+      );
+    });
+
+    await waitFor(() => {
+      expect(result.current).toBeDefined();
+      expect(result.current.length).toBe(2);
+    });
+
+    assert(result.current[0]);
+    assert(result.current[0]);
+    expect(result.current[0].name).toBe("Project 1");
+
+    // Update one of the values
+    act(() => {
+      project1.$jazz.set("name", "updated1");
+    });
+
+    assert(result.current[0]);
+    expect(result.current[0].name).toBe("updated1");
+  });
+
+  it("should handle empty subscription array", async () => {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <Suspense fallback={<div>Loading...</div>}>{children}</Suspense>
+    );
+
+    const { result } = await act(async () => {
+      return renderHook(() => useSuspenseCoStates(ProjectSchema, []), {
+        wrapper,
+      });
+    });
+
+    await waitFor(() => {
+      expect(result.current).toBeDefined();
+    });
+
+    expect(result.current).toEqual([]);
+  });
+
+  it("supports branching CoValues", async () => {
+    const project = ProjectSchema.create({ name: "My Project" });
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <Suspense fallback={<div>Loading...</div>}>{children}</Suspense>
+    );
+
+    const branchName = "feature-branch";
+    const { result } = await act(async () => {
+      return renderHook(
+        () =>
+          useSuspenseCoStates(ProjectSchema, [project.$jazz.id], {
+            unstable_branch: { name: branchName },
+          }),
+        {
+          wrapper,
+        },
+      );
+    });
+
+    assert(result.current[0]);
+    expect(result.current[0].name).toBe("My Project");
+
+    // Updates on changes to the branched CoValue
+    act(() => {
+      result.current[0]!.$jazz.set("name", "My Project Updated");
+    });
+    assert(result.current[0]);
+    expect(result.current[0].name).toBe("My Project Updated");
+
+    // Does not update when changes are made to another branch
+    act(() => {
+      project.$jazz.set("name", "My Project Updated 2");
+    });
+    assert(result.current[0]);
+    expect(result.current[0].name).toBe("My Project Updated");
+  });
+});
+
+describe("useCoStates", () => {
+  it("should return MaybeLoaded values", async () => {
+    const project1 = ProjectSchema.create({ name: "My Project 1" });
+    const project2 = ProjectSchema.create({ name: "My Project 2" });
+
+    const { result } = renderHook(() =>
+      useCoStates(ProjectSchema, [project1.$jazz.id, project2.$jazz.id]),
+    );
+
+    await waitFor(() => {
+      expect(result.current[0]?.$isLoaded).toBe(true);
+      expect(result.current[1]?.$isLoaded).toBe(true);
+    });
+
+    const [loadedProject1, loadedProject2] = result.current;
+
+    assert(loadedProject1);
+    assert(loadedProject2);
+    assertLoaded(loadedProject1);
+    assertLoaded(loadedProject2);
+    expect(loadedProject1.name).toBe("My Project 1");
+    expect(loadedProject2.name).toBe("My Project 2");
+  });
+
+  it("should re-render when any value changes", async () => {
+    const project1 = ProjectSchema.create({ name: "Project 1" });
+    const project2 = ProjectSchema.create({ name: "Project 2" });
+
+    const { result } = renderHook(() =>
+      useCoStates(ProjectSchema, [project1.$jazz.id, project2.$jazz.id]),
+    );
+
+    await waitFor(() => {
+      expect(result.current[0]?.$isLoaded).toBe(true);
+    });
+
+    expect(result.current[0]).not.toBeNull();
+    if (result.current[0]) {
+      assertLoaded(result.current[0]);
+      expect(result.current[0].name).toBe("Project 1");
+    }
+
+    // Update one of the values
+    act(() => {
+      project1.$jazz.set("name", "updated1");
+    });
+
+    await waitFor(() => {
+      const val = result.current[0];
+      return val?.$isLoaded && val.name === "updated1";
+    });
+
+    assert(result.current[0]);
+    expect(result.current[0].name).toBe("updated1");
+  });
+
+  it("should handle empty subscription array", async () => {
+    const { result } = renderHook(() => useCoStates(ProjectSchema, []));
+
+    await waitFor(() => {
+      expect(result.current).not.toBeNull();
+    });
+
+    expect(result.current).toEqual([]);
+  });
+
+  it("should update when ids change", async () => {
+    const project1 = ProjectSchema.create({ name: "My Project 1" });
+    const project2 = ProjectSchema.create({ name: "My Project 2" });
+
+    let ids: string[] = [project1.$jazz.id, project2.$jazz.id];
+    const { result, rerender } = renderHook(
+      ({ ids }: { ids: string[] }) => useCoStates(ProjectSchema, ids),
+      {
+        initialProps: { ids },
+      },
+    );
+
+    await waitFor(() => {
+      expect(result.current[0]?.$isLoaded).toBe(true);
+      expect(result.current[1]?.$isLoaded).toBe(true);
+    });
+
+    const project3 = ProjectSchema.create({ name: "My Project 3" });
+    act(() => {
+      // Create a new array with updated IDs
+      ids = [project2.$jazz.id, project3.$jazz.id];
+      rerender({ ids });
+    });
+
+    await waitFor(() => {
+      expect(result.current[0]?.$isLoaded).toBe(true);
+      expect(result.current[1]?.$isLoaded).toBe(true);
+    });
+
+    assert(result.current[0]);
+    assert(result.current[1]);
+    assertLoaded(result.current[0]);
+    assertLoaded(result.current[1]);
+    expect(result.current[0].name).toBe("My Project 2");
+    expect(result.current[1].name).toBe("My Project 3");
+  });
+
+  it("should not update when ids are the same", async () => {
+    const project1 = ProjectSchema.create({ name: "My Project 1" });
+    const project2 = ProjectSchema.create({ name: "My Project 2" });
+
+    let ids: string[] = [project1.$jazz.id, project2.$jazz.id];
+    const { result, rerender } = renderHook(
+      ({ ids }: { ids: string[] }) => useCoStates(ProjectSchema, ids),
+      {
+        initialProps: { ids },
+      },
+    );
+
+    await waitFor(() => {
+      expect(result.current[0]?.$isLoaded).toBe(true);
+      expect(result.current[1]?.$isLoaded).toBe(true);
+    });
+
+    const firstResult = result.current;
+
+    act(() => {
+      // Create a new array with the same IDs
+      ids = [...ids];
+      rerender({ ids });
+    });
+
+    // The result should be the same reference when IDs haven't changed
+    expect(result.current).toBe(firstResult);
+    expect(result.current[0]).toBe(firstResult[0]);
+    expect(result.current[1]).toBe(firstResult[1]);
+  });
+
+  it("supports branching CoValues", async () => {
+    const project = ProjectSchema.create({ name: "My Project" });
+
+    const { result } = renderHook(() =>
+      useCoStates(ProjectSchema, [project.$jazz.id], {
+        unstable_branch: { name: "feature-branch" },
+      }),
+    );
+
+    const loadedProject = result.current[0];
+    assert(loadedProject);
+    assertLoaded(loadedProject);
+    expect(loadedProject.name).toBe("My Project");
+
+    // Updates on changes to the branched CoValue
+    act(() => {
+      loadedProject.$jazz.set("name", "My Project Updated");
+    });
+    const loadedProject2 = result.current[0];
+    assert(loadedProject2);
+    assertLoaded(loadedProject2);
+    expect(loadedProject2.name).toBe("My Project Updated");
+
+    // Does not update when changes are made to another branch
+    act(() => {
+      project.$jazz.set("name", "My Project Updated 2");
+    });
+    const loadedProject3 = result.current[0];
+    assert(loadedProject3);
+    assertLoaded(loadedProject3);
+    expect(loadedProject3.name).toBe("My Project Updated");
+  });
+
+  it("should remove subscriptions for removed ids", async () => {
+    const project1 = ProjectSchema.create({ name: "My Project 1" });
+    const project2 = ProjectSchema.create({ name: "My Project 2" });
+
+    let ids = [project1.$jazz.id, project2.$jazz.id];
+    let renderCount = 0;
+    const { result, rerender } = renderHook(
+      ({ ids }: { ids: string[] }) => {
+        renderCount++;
+        return useCoStates(ProjectSchema, ids);
+      },
+      {
+        initialProps: { ids },
+      },
+    );
+
+    await waitFor(() => {
+      expect(result.current[0]?.$isLoaded).toBe(true);
+      expect(result.current[1]?.$isLoaded).toBe(true);
+    });
+
+    assert(result.current[0]);
+    assertLoaded(result.current[0]);
+    const loadedProject1 = result.current[0];
+
+    act(() => {
+      ids.shift(); // Remove project1, keeping only project2
+      rerender({ ids });
+    });
+
+    await waitFor(() => {
+      expect(result.current.length).toBe(1);
+      expect(result.current[0]?.$isLoaded).toBe(true);
+    });
+    assert(result.current[0]);
+    assertLoaded(result.current[0]);
+    expect(result.current[0].name).toBe("My Project 2");
+
+    expect(renderCount).toBe(2);
+
+    // Modify project1. The hook should NOT re-render because project1 is no longer subscribed
+    act(() => {
+      project1.$jazz.set("name", "Modified Project 1");
+    });
+
+    // Wait a bit to ensure any potential updates would have occurred
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // The hook didn't re-render
+    expect(renderCount).toBe(2);
+
+    // project2's name is still the same
+    assert(result.current[0]);
+    assertLoaded(result.current[0]);
+    expect(result.current[0].name).toBe("My Project 2");
+
+    // project1's subscription scope is no longer subscribed to
+    const project1SubscriptionScope = loadedProject1.$jazz._subscriptionScope;
+    expect(project1SubscriptionScope?.subscribers.size).toBe(0);
+  });
+});

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

@@ -6,6 +6,7 @@ import { Linking } from "react-native";
 
 export {
   useCoState,
+  useCoStates,
   experimental_useInboxSender,
   useDemoAuth,
   usePassphraseAuth,
@@ -20,6 +21,7 @@ export {
   useAccountSubscription,
   useSubscriptionSelector,
   useSuspenseCoState,
+  useSuspenseCoStates,
   useSuspenseAccount,
 } from "jazz-tools/react-core";
 

package/src/svelte/auth/ClerkAuth.svelte.ts

@@ -0,0 +1,67 @@
+import { JazzClerkAuth, type MinimalClerkClient } from "jazz-tools";
+import { getAuthSecretStorage, getJazzContext } from "../jazz.svelte.js";
+import { useIsAuthenticated } from "./useIsAuthenticated.svelte.js";
+
+/**
+ * Authentication state returned by {@link useClerkAuth}.
+ *
+ * - `"anonymous"`: User is not authenticated with Jazz (may or may not be signed into Clerk)
+ * - `"signedIn"`: User is authenticated with both Clerk and Jazz
+ */
+export type ClerkAuth = {
+  state: "anonymous" | "signedIn";
+};
+
+/**
+ * Registers a Clerk authentication listener and provides reactive auth state.
+ *
+ * Must be used within a component that is a child of `JazzSvelteProvider`.
+ * Automatically syncs Clerk authentication state with Jazz.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useClerkAuth } from "jazz-tools/svelte";
+ *
+ *   const auth = useClerkAuth(clerk);
+ * </script>
+ *
+ * {#if auth.state === "signedIn"}
+ *   <p>Welcome back!</p>
+ * {:else}
+ *   <p>Please sign in</p>
+ * {/if}
+ * ```
+ *
+ * @param clerk - The Clerk client instance
+ * @returns An object with a reactive `state` property
+ * @throws Error if used in guest mode
+ * @category Auth Providers
+ */
+export function useClerkAuth(clerk: MinimalClerkClient): ClerkAuth {
+  const context = getJazzContext();
+  const authSecretStorage = getAuthSecretStorage();
+
+  if ("guest" in context.current) {
+    throw new Error("Clerk auth is not supported in guest mode");
+  }
+
+  const authMethod = new JazzClerkAuth(
+    context.current.authenticate,
+    context.current.logOut,
+    authSecretStorage,
+  );
+
+  $effect(() => {
+    return authMethod.registerListener(clerk);
+  });
+
+  const isAuthenticated = useIsAuthenticated();
+  const state = $derived(isAuthenticated.current ? "signedIn" : "anonymous");
+
+  return {
+    get state() {
+      return state;
+    },
+  };
+}

package/src/svelte/auth/JazzSvelteProviderWithClerk.svelte

@@ -0,0 +1,156 @@
+<!--
+  @component
+  A pre-configured Jazz provider that integrates with Clerk authentication.
+
+  Use this component instead of `JazzSvelteProvider` when using Clerk for authentication.
+  It handles:
+  - Pre-loading Jazz credentials from Clerk before rendering children
+  - Registering Clerk auth state listeners
+  - Wiring up logout functionality to Clerk's signOut
+
+  @example
+  ```svelte
+  <JazzSvelteProviderWithClerk
+    {clerk}
+    sync={{ peer: "wss://cloud.jazz.tools/?key=your-key" }}
+    AccountSchema={MyAccountSchema}
+  >
+    <App />
+  </JazzSvelteProviderWithClerk>
+  ```
+
+  @category Auth Providers
+-->
+<script
+  lang="ts"
+  generics="S extends (AccountClass<Account> & CoValueFromRaw<Account>) | AnyAccountSchema"
+>
+  import {
+    Account,
+    type AccountClass,
+    type AnyAccountSchema,
+    type CoValueFromRaw,
+    InMemoryKVStore,
+    type InstanceOfSchema,
+    JazzClerkAuth,
+    KvStoreContext,
+    type MinimalClerkClient,
+    type SyncConfig,
+  } from "jazz-tools";
+  import {
+    type BaseBrowserContextOptions,
+    LocalStorageKVStore,
+  } from "jazz-tools/browser";
+  import type { Snippet } from "svelte";
+  import { JazzSvelteProvider } from "../jazz.svelte.js";
+  import RegisterClerkAuth from "./RegisterClerkAuth.svelte";
+
+  type Props = {
+    /** The Clerk client instance for authentication (can be null while Clerk is initializing) */
+    clerk: MinimalClerkClient | null;
+    /** Content to render when provider is initialized */
+    children?: Snippet;
+    /** Content to render while Clerk auth is loading */
+    fallback?: Snippet;
+    /** Content to render when authentication initialization fails */
+    errorFallback?: Snippet<[Error]>;
+    /** Callback when authentication initialization fails */
+    onAuthError?: (error: Error) => void;
+    /** Enable server-side rendering support with anonymous fallback */
+    enableSSR?: boolean;
+    /** Custom key for storing auth secrets in KvStore */
+    authSecretStorageKey?: string;
+    /** Jazz sync configuration (peer URL and key) */
+    sync: SyncConfig;
+    /** Custom storage implementation for auth secrets */
+    storage?: BaseBrowserContextOptions["storage"];
+    /** Account schema class for typed account access */
+    AccountSchema?: S;
+    /** Default profile name for new accounts */
+    defaultProfileName?: string;
+    /** Callback when an anonymous account is discarded during sign-in */
+    onAnonymousAccountDiscarded?: (
+      anonymousAccount: InstanceOfSchema<S>,
+    ) => Promise<void>;
+  };
+
+  let {
+    clerk,
+    children,
+    fallback,
+    errorFallback,
+    onAuthError,
+    ...providerProps
+  }: Props = $props();
+
+  let isLoaded = $state(false);
+  let initError = $state<Error | null>(null);
+
+  function setupKvStore() {
+    const isSSR = typeof window === "undefined";
+    if (isSSR) {
+      console.debug("[Jazz] Using InMemoryKVStore for SSR context");
+    }
+    KvStoreContext.getInstance().initialize(
+      isSSR ? new InMemoryKVStore() : new LocalStorageKVStore(),
+    );
+  }
+
+  /**
+   * Pre-loads Jazz authentication data from Clerk before mounting JazzSvelteProvider.
+   *
+   * For authenticated Clerk users with existing Jazz credentials, this populates the auth
+   * secret storage before rendering children, avoiding a flash of unauthenticated state.
+   * For unauthenticated users, the initialization completes immediately with no effect.
+   */
+  $effect(() => {
+    setupKvStore();
+
+    if (!clerk) return;
+
+    let cancelled = false;
+
+    JazzClerkAuth.initializeAuth(clerk)
+      .then(() => {
+        if (!cancelled) {
+          isLoaded = true;
+          initError = null;
+        }
+      })
+      .catch((error) => {
+        console.error(
+          "[Jazz] Clerk authentication initialization failed:",
+          error,
+        );
+        if (!cancelled) {
+          const errorObj =
+            error instanceof Error ? error : new Error(String(error));
+          initError = errorObj;
+          onAuthError?.(errorObj);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  });
+</script>
+
+{#if initError}
+  {#if errorFallback}
+    {@render errorFallback(initError)}
+  {:else}
+    <div data-testid="jazz-clerk-auth-error">
+      Authentication initialization failed. Please refresh the page or try again
+      later.
+    </div>
+  {/if}
+{:else if isLoaded && clerk}
+  <JazzSvelteProvider {...providerProps} onLogOut={clerk.signOut}>
+    <RegisterClerkAuth {clerk}>
+      {@render children?.()}
+    </RegisterClerkAuth>
+  </JazzSvelteProvider>
+{:else if fallback}
+  {@render fallback?.()}
+{/if}

package/src/svelte/auth/RegisterClerkAuth.svelte

@@ -0,0 +1,27 @@
+<!--
+  @component
+  Internal component that registers the Clerk auth listener.
+
+  This component exists because `useClerkAuth` requires access to the Jazz context,
+  which is only available inside `JazzSvelteProvider`'s children. By placing the
+  hook call in this child component, we ensure the context is properly initialized.
+-->
+<script lang="ts">
+  import type { MinimalClerkClient } from "jazz-tools";
+  import type { Snippet } from "svelte";
+  import { useClerkAuth } from "./ClerkAuth.svelte.js";
+
+  interface Props {
+    clerk: MinimalClerkClient;
+    children?: Snippet;
+  }
+
+  let { clerk, children }: Props = $props();
+
+  // Register the Clerk auth listener after JazzSvelteProvider context is available.
+  // The return value (auth state) is intentionally unused here - this component's
+  // sole purpose is to register the listener that syncs Clerk and Jazz auth state.
+  useClerkAuth(clerk);
+</script>
+
+{@render children?.()}

package/src/svelte/auth/index.ts

@@ -1,3 +1,5 @@
 export * from "./PasskeyAuth.svelte.js";
 export * from "./PassphraseAuth.svelte.js";
+export * from "./ClerkAuth.svelte.js";
 export { default as PasskeyAuthBasicUI } from "./PasskeyAuthBasicUI.svelte";
+export { default as JazzSvelteProviderWithClerk } from "./JazzSvelteProviderWithClerk.svelte";