jazz-tools 0.19.20 → 0.19.22

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

@@ -0,0 +1,305 @@
+// @vitest-environment happy-dom
+
+import {
+  Account,
+  InMemoryKVStore,
+  JazzClerkAuth,
+  KvStoreContext,
+} from "jazz-tools";
+import type { MinimalClerkClient } from "jazz-tools";
+import { render as renderSvelte, waitFor } from "@testing-library/svelte";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createJazzTestAccount,
+  createJazzTestGuest,
+  setupJazzTestSync,
+} from "../testing";
+import { render, screen } from "./testUtils";
+import TestClerkAuthWrapper from "./TestClerkAuthWrapper.svelte";
+import JazzSvelteProviderWithClerk from "../auth/JazzSvelteProviderWithClerk.svelte";
+
+KvStoreContext.getInstance().initialize(new InMemoryKVStore());
+
+function createMockClerkClient(
+  user: MinimalClerkClient["user"] = null,
+): MinimalClerkClient {
+  return {
+    user,
+    signOut: vi.fn(),
+    addListener: vi.fn(() => () => {}),
+  };
+}
+
+describe("useClerkAuth", () => {
+  let account: Account;
+
+  beforeEach(async () => {
+    await setupJazzTestSync();
+    account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+  });
+
+  it("should return anonymous state when not authenticated", async () => {
+    const mockClerk = createMockClerkClient();
+
+    render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    expect(screen.getByTestId("auth-state").textContent).toBe("anonymous");
+  });
+
+  it("should return signedIn state when authenticated", async () => {
+    const mockClerk = createMockClerkClient({
+      id: "user_123",
+      fullName: "Test User",
+      username: "testuser",
+      firstName: "Test",
+      lastName: "User",
+      primaryEmailAddress: { emailAddress: "test@example.com" },
+      unsafeMetadata: {
+        jazzAccountID: "test123",
+        jazzAccountSecret: "secret123",
+      },
+      update: vi.fn(),
+    });
+
+    render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: true },
+    );
+
+    expect(screen.getByTestId("auth-state").textContent).toBe("signedIn");
+  });
+
+  it("should register the clerk listener", async () => {
+    const mockClerk = createMockClerkClient();
+
+    render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    expect(mockClerk.addListener).toHaveBeenCalled();
+  });
+
+  it("should cleanup listener on unmount", async () => {
+    const mockUnsubscribe = vi.fn();
+    const mockClerk = createMockClerkClient();
+    mockClerk.addListener = vi.fn(() => mockUnsubscribe);
+
+    const { unmount } = render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    expect(mockClerk.addListener).toHaveBeenCalled();
+    unmount();
+    expect(mockUnsubscribe).toHaveBeenCalled();
+  });
+
+  it("should throw error in guest mode", async () => {
+    const guest = await createJazzTestGuest();
+    const mockClerk = createMockClerkClient();
+
+    expect(() => {
+      render(TestClerkAuthWrapper, { clerk: mockClerk }, { account: guest });
+    }).toThrow("Clerk auth is not supported in guest mode");
+  });
+
+  it("should call listener with clerk client events", async () => {
+    const mockClerk = createMockClerkClient();
+    let listenerCallback: ((data: unknown) => void) | undefined;
+    mockClerk.addListener = vi.fn((callback) => {
+      listenerCallback = callback;
+      return () => {};
+    });
+
+    render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    expect(mockClerk.addListener).toHaveBeenCalled();
+    expect(listenerCallback).toBeDefined();
+  });
+});
+
+describe("JazzClerkAuth.initializeAuth", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should handle initialization errors gracefully", async () => {
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const initializeAuthSpy = vi
+      .spyOn(JazzClerkAuth, "initializeAuth")
+      .mockRejectedValue(new Error("Test error"));
+
+    const mockClerk = createMockClerkClient();
+
+    // The error should be thrown by the mock
+    await expect(JazzClerkAuth.initializeAuth(mockClerk)).rejects.toThrow(
+      "Test error",
+    );
+
+    // Restore using vitest's cleanup
+    initializeAuthSpy.mockRestore();
+    consoleSpy.mockRestore();
+  });
+});
+
+describe("JazzSvelteProviderWithClerk", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should render children after successful initialization", async () => {
+    const mockClerk = createMockClerkClient();
+    vi.spyOn(JazzClerkAuth, "initializeAuth").mockResolvedValue(undefined);
+
+    const { container } = renderSvelte(JazzSvelteProviderWithClerk, {
+      props: {
+        clerk: mockClerk,
+        sync: { peer: "wss://test.example.com" },
+      },
+    });
+
+    await waitFor(() => {
+      // After initialization, the provider should render (even without children)
+      // The error div should not be present
+      expect(
+        container.querySelector('[data-testid="jazz-clerk-auth-error"]'),
+      ).toBeNull();
+    });
+  });
+
+  it("should show default error message when initialization fails", async () => {
+    const mockClerk = createMockClerkClient();
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(JazzClerkAuth, "initializeAuth").mockRejectedValue(
+      new Error("Init failed"),
+    );
+
+    const { container } = renderSvelte(JazzSvelteProviderWithClerk, {
+      props: {
+        clerk: mockClerk,
+        sync: { peer: "wss://test.example.com" },
+      },
+    });
+
+    await waitFor(() => {
+      const errorDiv = container.querySelector(
+        '[data-testid="jazz-clerk-auth-error"]',
+      );
+      expect(errorDiv).not.toBeNull();
+      expect(errorDiv?.textContent).toContain(
+        "Authentication initialization failed",
+      );
+    });
+
+    consoleSpy.mockRestore();
+  });
+
+  it("should call onAuthError callback when initialization fails", async () => {
+    const mockClerk = createMockClerkClient();
+    const onAuthError = vi.fn();
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(JazzClerkAuth, "initializeAuth").mockRejectedValue(
+      new Error("Init failed"),
+    );
+
+    renderSvelte(JazzSvelteProviderWithClerk, {
+      props: {
+        clerk: mockClerk,
+        sync: { peer: "wss://test.example.com" },
+        onAuthError,
+      },
+    });
+
+    await waitFor(() => {
+      expect(onAuthError).toHaveBeenCalledWith(expect.any(Error));
+      expect(onAuthError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: "Init failed" }),
+      );
+    });
+
+    consoleSpy.mockRestore();
+  });
+
+  it("should not update state after unmount (cancellation)", async () => {
+    const mockClerk = createMockClerkClient();
+    let resolveInit: () => void;
+    const initPromise = new Promise<void>((resolve) => {
+      resolveInit = resolve;
+    });
+    vi.spyOn(JazzClerkAuth, "initializeAuth").mockReturnValue(initPromise);
+
+    const { unmount } = renderSvelte(JazzSvelteProviderWithClerk, {
+      props: {
+        clerk: mockClerk,
+        sync: { peer: "wss://test.example.com" },
+      },
+    });
+
+    // Unmount before initialization completes
+    unmount();
+
+    // Resolve the promise after unmount - should not cause errors
+    resolveInit!();
+
+    // Give time for any potential state updates
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // If we get here without errors, the cancellation worked
+    expect(true).toBe(true);
+  });
+});
+
+describe("useClerkAuth reactive state transitions", () => {
+  let account: Account;
+
+  beforeEach(async () => {
+    await setupJazzTestSync();
+    account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should update state reactively when listener callback fires", async () => {
+    const mockClerk = createMockClerkClient();
+    let listenerCallback: ((data: unknown) => void) | undefined;
+    mockClerk.addListener = vi.fn((callback) => {
+      listenerCallback = callback;
+      return () => {};
+    });
+
+    const { container } = render(
+      TestClerkAuthWrapper,
+      { clerk: mockClerk },
+      { account, isAuthenticated: false },
+    );
+
+    // Initial state should be anonymous
+    expect(screen.getByTestId("auth-state").textContent).toBe("anonymous");
+
+    // Verify listener was registered
+    expect(listenerCallback).toBeDefined();
+
+    // Note: Full state transition testing would require more complex setup
+    // involving the actual JazzClerkAuth.onClerkUserChange flow.
+    // This test verifies the listener registration which is the foundation
+    // for reactive updates.
+  });
+});

package/src/svelte/tests/TestClerkAuthWrapper.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import type { MinimalClerkClient } from "jazz-tools";
+  import { useClerkAuth } from "../auth/ClerkAuth.svelte.js";
+
+  type Props = {
+    clerk: MinimalClerkClient;
+  };
+
+  let { clerk }: Props = $props();
+
+  const auth = useClerkAuth(clerk);
+</script>
+
+<div data-testid="clerk-auth-wrapper">
+  <div data-testid="auth-state">{auth.state}</div>
+</div>

package/src/svelte/tests/testUtils.ts

@@ -6,6 +6,7 @@ import { JAZZ_AUTH_CTX, JAZZ_CTX } from "../jazz.svelte";
 
 type JazzExtendedOptions = {
   account: Account | { guest: AnonymousJazzAgent };
+  isAuthenticated?: boolean;
 };
 
 const render = <T extends Component>(
@@ -13,7 +14,9 @@ const render = <T extends Component>(
   props: ComponentProps<T>,
   jazzOptions: JazzExtendedOptions,
 ) => {
-  const ctx = TestJazzContextManager.fromAccountOrGuest(jazzOptions.account);
+  const ctx = TestJazzContextManager.fromAccountOrGuest(jazzOptions.account, {
+    isAuthenticated: jazzOptions.isAuthenticated,
+  });
 
   return renderSvelte(
     // @ts-expect-error Svelte new Component type is not compatible with @testing-library/svelte

package/src/tools/auth/clerk/types.ts

@@ -47,7 +47,7 @@ type PermissiveClerkUser = Omit<ClerkUser, "unsafeMetadata" | "update"> & {
 export type MinimalClerkClient = {
   user: PermissiveClerkUser | null | undefined;
   signOut: () => Promise<void>;
-  addListener: (listener: (data: unknown) => void) => void;
+  addListener: (listener: (data: unknown) => void) => (() => void) | void;
 };
 
 export type ClerkCredentials = {

package/src/tools/exports.ts

@@ -144,3 +144,8 @@ export * from "./ssr/index.js";
 export { captureStack } from "./subscribe/errorReporting.js";
 
 export * as jazzConfig from "./config.js";
+
+export {
+  JazzMessageChannel as experimental_JazzMessageChannel,
+  type JazzMessageChannelExposeOptions,
+} from "../worker/JazzMessageChannel.js";

package/src/tools/subscribe/types.ts

@@ -49,4 +49,4 @@ export type SubscriptionValueLoading = {
   id: string;
 };
 
-export type BranchDefinition = { name: string; owner?: Group | Account | null };
+export type BranchDefinition = { name: string; owner?: Group | Account };

package/src/tools/tests/inbox.test.ts

@@ -604,16 +604,16 @@ describe("Inbox", () => {
         Message.create({ text: `Message ${i}`, value: i }, group),
       );
 
-      // Subscribe with concurrency limit of 1
+      // Subscribe with concurrency limit of 3
       const unsubscribe = receiverInbox.subscribe(
         Message,
         async (message) => {
           const messageText = message.text;
           processingOrder.push(`start-${messageText}`);
 
-          // Simulate processing time
+          // Simulate processing time (later messages take longer to ensure deterministic ordering)
           await new Promise((resolve) =>
-            setTimeout(resolve, 20 - message.value * 10),
+            setTimeout(resolve, 10 + message.value * 10),
           );
 
           processingOrder.push(`end-${messageText}`);
@@ -633,13 +633,13 @@ describe("Inbox", () => {
           "start-Message 0",
           "start-Message 1",
           "start-Message 2",
-          "end-Message 2",
+          "end-Message 0",
           "start-Message 3",
-          "end-Message 3",
+          "end-Message 1",
           "start-Message 4",
+          "end-Message 2",
+          "end-Message 3",
           "end-Message 4",
-          "end-Message 1",
-          "end-Message 0",
         ]
       `);
       unsubscribe();

package/src/tools/tests/testStorage.ts

@@ -50,8 +50,8 @@ export async function createAsyncStorage({ filename }: { filename?: string }) {
     new LibSQLSqliteAsyncDriver(getDbPath(filename)),
   );
 
-  onTestFinished(() => {
-    storage.close();
+  onTestFinished(async () => {
+    await storage.close();
   });
 
   return storage;

package/src/worker/JazzMessageChannel.ts

@@ -0,0 +1,73 @@
+import { CojsonMessageChannel, type Peer } from "cojson";
+import type {
+  WaitForConnectionOptions,
+  ExposeOptions,
+  PostMessageTarget,
+} from "cojson/src/CojsonMessageChannel/types.js";
+import { Account, AnonymousJazzAgent } from "jazz-tools";
+import { activeAccountContext } from "../tools/implementation/activeAccountContext.js";
+
+/**
+ * Options for JazzMessageChannel.expose()
+ */
+export interface JazzMessageChannelExposeOptions extends ExposeOptions {
+  /**
+   * The account or anonymous agent to use for the connection.
+   * If not provided, falls back to the active account context.
+   */
+  loadAs?: Account | AnonymousJazzAgent;
+}
+
+/**
+ * JazzMessageChannel provides a high-level API for creating Jazz connections
+ * via the MessageChannel API. It wraps cojson's CojsonMessageChannel and
+ * automatically manages the node connection.
+ */
+export class JazzMessageChannel {
+  /**
+   * Expose a Jazz connection to a target.
+   * This is the host-side API, typically called from the main thread.
+   *
+   * @param target - Any object with a postMessage method (Worker, Window, etc.)
+   * @param opts - Configuration options including the account to use
+   * @returns A promise that resolves once the connection is established
+   */
+  static async expose(
+    target: PostMessageTarget,
+    opts: JazzMessageChannelExposeOptions = {},
+  ): Promise<void> {
+    const { loadAs, ...cojsonOpts } = opts;
+
+    // Get account from loadAs or fall back to active account context
+    const accountOrAgent = loadAs ?? activeAccountContext.maybeGet();
+
+    if (!accountOrAgent) {
+      throw new Error(
+        "No account provided and no active account context available",
+      );
+    }
+
+    const node =
+      accountOrAgent instanceof AnonymousJazzAgent
+        ? accountOrAgent.node
+        : accountOrAgent.$jazz.localNode;
+
+    const peer = await CojsonMessageChannel.expose(target, cojsonOpts);
+
+    node.syncManager.addPeer(peer);
+  }
+
+  /**
+   * Accept an incoming Jazz connection.
+   * Same as cojson CojsonMessageChannel.waitForConnection().
+   */
+  static waitForConnection(opts?: WaitForConnectionOptions): Promise<Peer> {
+    return CojsonMessageChannel.waitForConnection(opts);
+  }
+}
+
+// Re-export types for convenience
+export type {
+  WaitForConnectionOptions,
+  AcceptFromPortOptions,
+} from "cojson/src/CojsonMessageChannel/types.js";

package/src/worker/index.ts

@@ -29,6 +29,11 @@ type WorkerOptions<
 > = {
   accountID?: string;
   accountSecret?: string;
+  /**
+   * A peer to connect to for synchronization.
+   * If provided, syncServer is ignored.
+   */
+  peer?: Peer;
   syncServer?: string;
   WebSocket?: AnyWebSocketConstructor;
   AccountSchema?: S;
@@ -63,21 +68,28 @@ export async function startWorker<
 
   const peers: Peer[] = [];
 
-  const wsPeer = new WebSocketPeerWithReconnection({
-    peer: syncServer,
-    reconnectionTimeout: 100,
-    addPeer: (peer) => {
-      if (node) {
-        node.syncManager.addPeer(peer);
-      } else {
-        peers.push(peer);
-      }
-    },
-    removePeer: () => {},
-    WebSocketConstructor: options.WebSocket,
-  });
-
-  wsPeer.enable();
+  // If a peer is provided directly, use it instead of WebSocket
+  let wsPeer: WebSocketPeerWithReconnection | undefined;
+
+  if (options.peer) {
+    peers.push(options.peer);
+  } else {
+    wsPeer = new WebSocketPeerWithReconnection({
+      peer: syncServer,
+      reconnectionTimeout: 100,
+      addPeer: (peer) => {
+        if (node) {
+          node.syncManager.addPeer(peer);
+        } else {
+          peers.push(peer);
+        }
+      },
+      removePeer: () => {},
+      WebSocketConstructor: options.WebSocket,
+    });
+
+    wsPeer.enable();
+  }
 
   if (!accountID) {
     throw new Error("No accountID provided");
@@ -117,7 +129,7 @@ export async function startWorker<
   async function done() {
     await context.account.$jazz.waitForAllCoValuesSync();
 
-    wsPeer.disable();
+    wsPeer?.disable();
     context.done();
   }
 
@@ -146,11 +158,18 @@ export async function startWorker<
      * Wait for the connection to the sync server to be established.
      *
      * If already connected, it will resolve immediately.
+     * Returns immediately if using a custom peer.
      */
     waitForConnection() {
-      return wsPeer.waitUntilConnected();
+      return wsPeer?.waitUntilConnected() ?? Promise.resolve();
     },
     subscribeToConnectionChange(listener: (connected: boolean) => void) {
+      if (!wsPeer) {
+        // For custom peers, immediately notify as connected
+        listener(true);
+        return () => {};
+      }
+
       wsPeer.subscribe(listener);
 
       return () => {