jazz-tools 0.19.14 → 0.19.16

package/dist/tools/subscribe/SubscriptionScope.d.ts

@@ -1,9 +1,7 @@
-import { LocalNode, RawCoValue } from "cojson";
-import { CoList, CoMap, type CoValue, type ID, MaybeLoaded, NotLoaded, type RefEncoded, type RefsToResolve } from "../internal.js";
-import { CoValueCoreSubscription } from "./CoValueCoreSubscription.js";
+import { LocalNode } from "cojson";
+import { type CoValue, type ID, MaybeLoaded, NotLoaded, type RefEncoded, type RefsToResolve } from "../internal.js";
 import { JazzError } from "./JazzError.js";
 import type { BranchDefinition, SubscriptionValue, SubscriptionValueLoading } from "./types.js";
-import { CoValueLoadingState, NotLoadedCoValueState } from "./types.js";
 import { PromiseWithStatus } from "./utils.js";
 export declare class SubscriptionScope<D extends CoValue> {
     node: LocalNode;
@@ -21,24 +19,24 @@ export declare class SubscriptionScope<D extends CoValue> {
     /**
      * Autoloaded child ids that are unloaded
      */
-    pendingAutoloadedChildren: Set<string>;
+    private pendingAutoloadedChildren;
     value: SubscriptionValue<D, any> | SubscriptionValueLoading;
-    childErrors: Map<string, JazzError>;
-    validationErrors: Map<string, JazzError>;
+    private childErrors;
+    private validationErrors;
     errorFromChildren: JazzError | undefined;
-    subscription: CoValueCoreSubscription;
-    dirty: boolean;
-    resolve: RefsToResolve<any>;
-    idsSubscribed: Set<string>;
-    autoloaded: Set<string>;
-    autoloadedKeys: Set<string>;
-    skipInvalidKeys: Set<string>;
-    totalValidTransactions: number;
-    version: number;
-    migrated: boolean;
-    migrating: boolean;
+    private subscription;
+    private dirty;
+    private resolve;
+    private idsSubscribed;
+    private autoloaded;
+    private autoloadedKeys;
+    private skipInvalidKeys;
+    private totalValidTransactions;
+    private version;
+    private migrated;
+    private migrating;
     closed: boolean;
-    silenceUpdates: boolean;
+    private silenceUpdates;
     /**
      * Stack trace captured at subscription creation time.
      * This helps identify which component/hook created the subscription
@@ -47,22 +45,22 @@ export declare class SubscriptionScope<D extends CoValue> {
     callerStack: Error | undefined;
     constructor(node: LocalNode, resolve: RefsToResolve<D>, id: ID<D>, schema: RefEncoded<D>, skipRetry?: boolean, bestEffortResolution?: boolean, unstable_branch?: BranchDefinition | undefined, callerStack?: Error | undefined);
     updateValue(value: SubscriptionValue<D, any>): void;
-    handleUpdate(update: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE): void;
-    computeChildErrors(): JazzError | undefined;
-    handleChildUpdate: (id: string, value: SubscriptionValue<any, any> | SubscriptionValueLoading, key?: string) => void;
-    shouldSendUpdates(): boolean;
+    private handleUpdate;
+    private computeChildErrors;
+    handleChildUpdate(id: string, value: SubscriptionValue<any, any> | SubscriptionValueLoading, key?: string): void;
+    private shouldSendUpdates;
     unloadedValue: NotLoaded<D> | undefined;
-    lastPromise: PromiseWithStatus<D> | undefined;
-    getPromise(): PromiseWithStatus<D>;
+    private lastPromise;
+    private getPromise;
     getCachedPromise(): PromiseWithStatus<D>;
     private getUnloadedValue;
-    lastErrorLogged: JazzError | undefined;
+    private lastErrorLogged;
     getCurrentValue(): MaybeLoaded<D>;
-    getCurrentRawValue(): D | NotLoadedCoValueState;
-    getCreationStackLines(): string;
-    getError(): JazzError | undefined;
-    logError(): void;
-    triggerUpdate(): void;
+    private getCurrentRawValue;
+    private getCreationStackLines;
+    private getError;
+    private logError;
+    private triggerUpdate;
     subscribers: Set<(value: SubscriptionValue<D, any>) => void>;
     subscriberChangeCallbacks: Set<(count: number) => void>;
     /**
@@ -83,10 +81,10 @@ export declare class SubscriptionScope<D extends CoValue> {
      */
     pullValue(listener: (value: SubscriptionValue<D, any>) => void): void;
     subscribeToId(id: string, descriptor: RefEncoded<any>): void;
-    loadChildren(): boolean;
-    loadCoMapKey(map: CoMap, key: string, depth: Record<string, any> | true): string | undefined;
-    loadCoListKey(list: CoList, key: string, depth: Record<string, any> | true): string | undefined;
-    loadChildNode(id: string, query: RefsToResolve<any>, descriptor: RefEncoded<any>, key?: string): void;
+    private loadChildren;
+    private loadCoMapKey;
+    private loadCoListKey;
+    private loadChildNode;
     destroy(): void;
 }
 //# sourceMappingURL=SubscriptionScope.d.ts.map

package/dist/tools/subscribe/SubscriptionScope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SubscriptionScope.d.ts","sourceRoot":"","sources":["../../../src/tools/subscribe/SubscriptionScope.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SubscriptionScope.d.ts","sourceRoot":"","sources":["../../../src/tools/subscribe/SubscriptionScope.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -205,7 +205,7 @@
   },
   "type": "module",
   "license": "MIT",
-  "version": "0.19.14",
+  "version": "0.19.16",
   "dependencies": {
     "@manuscripts/prosemirror-recreate-steps": "^0.1.4",
     "@scure/base": "1.2.1",
@@ -222,9 +222,9 @@
     "prosemirror-transform": "^1.9.0",
     "use-sync-external-store": "^1.5.0",
     "zod": "4.1.11",
-    "cojson": "0.19.14",
-    "cojson-storage-indexeddb": "0.19.14",
-    "cojson-transport-ws": "0.19.14"
+    "cojson": "0.19.16",
+    "cojson-storage-indexeddb": "0.19.16",
+    "cojson-transport-ws": "0.19.16"
   },
   "devDependencies": {
     "@scure/bip39": "^1.3.0",

package/src/react-native-core/ReactNativeSessionProvider.ts

@@ -6,6 +6,8 @@ import {
 } from "jazz-tools";
 import { AgentID, RawAccountID } from "cojson";
 
+const lockedSessions = new Set<SessionID>();
+
 export class ReactNativeSessionProvider implements SessionProvider {
   async acquireSession(
     accountID: string,
@@ -14,11 +16,29 @@ export class ReactNativeSessionProvider implements SessionProvider {
     const kvStore = KvStoreContext.getInstance().getStorage();
     const existingSession = await kvStore.get(accountID as string);
 
+    // Check if the session is already in use, should happen only if the dev
+    // mounts multiple providers at the same time
+    if (lockedSessions.has(existingSession as SessionID)) {
+      const newSessionID = crypto.newRandomSessionID(
+        accountID as RawAccountID | AgentID,
+      );
+
+      console.error("Existing session in use, creating new one", newSessionID);
+
+      return Promise.resolve({
+        sessionID: newSessionID,
+        sessionDone: () => {},
+      });
+    }
+
     if (existingSession) {
       console.log("Using existing session", existingSession);
+      lockedSessions.add(existingSession as SessionID);
       return Promise.resolve({
         sessionID: existingSession as SessionID,
-        sessionDone: () => {},
+        sessionDone: () => {
+          lockedSessions.delete(existingSession as SessionID);
+        },
       });
     }
 
@@ -30,12 +50,15 @@ export class ReactNativeSessionProvider implements SessionProvider {
       accountID as RawAccountID | AgentID,
     );
     await kvStore.set(accountID, newSessionID);
+    lockedSessions.add(newSessionID);
 
     console.error("Created new session", newSessionID);
 
     return Promise.resolve({
       sessionID: newSessionID,
-      sessionDone: () => {},
+      sessionDone: () => {
+        lockedSessions.delete(newSessionID);
+      },
     });
   }
 
@@ -45,8 +68,11 @@ export class ReactNativeSessionProvider implements SessionProvider {
   ): Promise<{ sessionDone: () => void }> {
     const kvStore = KvStoreContext.getInstance().getStorage();
     await kvStore.set(accountID, sessionID);
+    lockedSessions.add(sessionID);
     return Promise.resolve({
-      sessionDone: () => {},
+      sessionDone: () => {
+        lockedSessions.delete(sessionID);
+      },
     });
   }
 }

package/src/react-native-core/tests/ReactNativeSessionProvider.test.ts

@@ -1,5 +1,5 @@
 import { WasmCrypto } from "cojson/crypto/WasmCrypto";
-import { SessionID } from "cojson";
+import { RawAccountID, SessionID } from "cojson";
 import { beforeEach, describe, expect, test } from "vitest";
 import { InMemoryKVStore } from "jazz-tools";
 import { KvStoreContext, type KvStore } from "jazz-tools";
@@ -51,6 +51,9 @@ describe("ReactNativeSessionProvider", () => {
       const storedSession = await kvStore.get(accountID);
       expect(storedSession).toBeDefined();
       expect(storedSession).toBe(result.sessionID);
+
+      // Clean up
+      result.sessionDone();
     });
 
     test("returns existing session when one exists", async () => {
@@ -77,6 +80,89 @@ describe("ReactNativeSessionProvider", () => {
       const sessionAfter = await kvStore.get(accountID);
       expect(sessionAfter).toBe(existingSessionID);
       expect(sessionAfter).toBe(result.sessionID);
+
+      // Clean up
+      result.sessionDone();
+    });
+
+    test("creates new session when existing session is locked", async () => {
+      const accountID = account.$jazz.id;
+      const existingSessionID = Crypto.newRandomSessionID(
+        accountID as RawAccountID,
+      );
+
+      // Pre-populate KvStore with a session ID
+      await kvStore.set(accountID, existingSessionID);
+
+      // Acquire the session (this locks it)
+      const firstResult = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+      expect(firstResult.sessionID).toBe(existingSessionID);
+
+      // Try to acquire session again while the first is still locked
+      const secondResult = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+
+      // Should get a different (new) session since the existing one is locked
+      expect(secondResult.sessionID).not.toBe(existingSessionID);
+      expect(secondResult.sessionID).toBeDefined();
+
+      // Clean up
+      firstResult.sessionDone();
+      secondResult.sessionDone();
+    });
+
+    test("reuses session after sessionDone is called", async () => {
+      const accountID = account.$jazz.id;
+
+      // Acquire initial session
+      const firstResult = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+      const firstSessionID = firstResult.sessionID;
+
+      // Release the session
+      firstResult.sessionDone();
+
+      // Acquire session again - should reuse the same session
+      const secondResult = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+
+      expect(secondResult.sessionID).toBe(firstSessionID);
+
+      // Clean up
+      secondResult.sessionDone();
+    });
+
+    test("sessionDone can be called multiple times safely", async () => {
+      const accountID = account.$jazz.id;
+
+      const result = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+
+      // Call sessionDone multiple times - should not throw
+      result.sessionDone();
+      result.sessionDone();
+      result.sessionDone();
+
+      // Should still be able to acquire the session
+      const secondResult = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+      expect(secondResult.sessionID).toBe(result.sessionID);
+
+      // Clean up
+      secondResult.sessionDone();
     });
   });
 
@@ -90,7 +176,10 @@ describe("ReactNativeSessionProvider", () => {
       expect(sessionBefore).toBeNull();
 
       // Persist session
-      await sessionProvider.persistSession(accountID, sessionID);
+      const { sessionDone } = await sessionProvider.persistSession(
+        accountID,
+        sessionID,
+      );
 
       // Verify the session ID is stored in KvStore
       const storedSession = await kvStore.get(accountID);
@@ -98,6 +187,9 @@ describe("ReactNativeSessionProvider", () => {
 
       // Verify the stored value matches the provided session ID
       expect(storedSession).toBe(sessionID);
+
+      // Clean up
+      sessionDone();
     });
 
     test("overwrites existing session", async () => {
@@ -113,12 +205,92 @@ describe("ReactNativeSessionProvider", () => {
       expect(sessionBefore).toBe(initialSessionID);
 
       // Persist a different session ID
-      await sessionProvider.persistSession(accountID, newSessionID);
+      const { sessionDone } = await sessionProvider.persistSession(
+        accountID,
+        newSessionID,
+      );
 
       // Verify the new session ID replaces the old one
       const sessionAfter = await kvStore.get(accountID);
       expect(sessionAfter).toBe(newSessionID);
       expect(sessionAfter).not.toBe(initialSessionID);
+
+      // Clean up
+      sessionDone();
+    });
+
+    test("locks session when persisting", async () => {
+      const accountID = account.$jazz.id;
+      const sessionID = Crypto.newRandomSessionID(accountID as RawAccountID);
+
+      // Persist session - this should lock the session
+      const { sessionDone } = await sessionProvider.persistSession(
+        accountID,
+        sessionID,
+      );
+
+      // Try to acquire session while it's locked by persistSession
+      const result = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+
+      // Should get a different session since the persisted one is locked
+      expect(result.sessionID).not.toBe(sessionID);
+
+      // Clean up
+      sessionDone();
+      result.sessionDone();
+    });
+
+    test("allows session reuse after sessionDone is called", async () => {
+      const accountID = account.$jazz.id;
+      const sessionID = Crypto.newRandomSessionID(accountID as RawAccountID);
+
+      // Persist session
+      const { sessionDone } = await sessionProvider.persistSession(
+        accountID,
+        sessionID,
+      );
+
+      // Release the session
+      sessionDone();
+
+      // Acquire session - should reuse the persisted session
+      const result = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+
+      expect(result.sessionID).toBe(sessionID);
+
+      // Clean up
+      result.sessionDone();
+    });
+
+    test("sessionDone can be called multiple times safely", async () => {
+      const accountID = account.$jazz.id;
+      const sessionID = Crypto.newRandomSessionID(accountID as RawAccountID);
+
+      const { sessionDone } = await sessionProvider.persistSession(
+        accountID,
+        sessionID,
+      );
+
+      // Call sessionDone multiple times - should not throw
+      sessionDone();
+      sessionDone();
+      sessionDone();
+
+      // Should still be able to acquire the session
+      const result = await sessionProvider.acquireSession(
+        accountID,
+        Crypto as CryptoProvider,
+      );
+      expect(result.sessionID).toBe(sessionID);
+
+      // Clean up
+      result.sessionDone();
     });
   });
 });

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

@@ -53,18 +53,21 @@ export class JazzClerkAuth {
   }
 
   private isFirstCall = true;
+  private previousUser: Pick<
+    NonNullable<MinimalClerkClient["user"]>,
+    "unsafeMetadata"
+  > | null = null;
 
   registerListener(clerkClient: MinimalClerkClient) {
-    let previousUser: MinimalClerkClient["user"] | null =
-      clerkClient.user ?? null;
+    this.previousUser = clerkClient.user ?? null;
 
     // Need to use addListener because the clerk user object is not updated when the user logs in
     return clerkClient.addListener((event) => {
       const user = (event as Pick<MinimalClerkClient, "user">).user ?? null;
 
-      if (!isClerkAuthStateEqual(previousUser, user) || this.isFirstCall) {
+      if (!isClerkAuthStateEqual(this.previousUser, user) || this.isFirstCall) {
+        this.previousUser = user;
         this.onClerkUserChange({ user });
-        previousUser = user;
         this.isFirstCall = false;
       }
     });
@@ -137,13 +140,20 @@ export class JazzClerkAuth {
       ? Array.from(credentials.secretSeed)
       : undefined;
 
-    await clerkClient.user?.update({
-      unsafeMetadata: {
-        jazzAccountID: credentials.accountID,
-        jazzAccountSecret: credentials.accountSecret,
-        jazzAccountSeed,
-      } satisfies ClerkCredentials,
-    });
+    const clerkCredentials = {
+      jazzAccountID: credentials.accountID,
+      jazzAccountSecret: credentials.accountSecret,
+      jazzAccountSeed,
+    };
+    // user.update will cause the Clerk user change listener to fire; updating this.previousUser beforehand
+    // ensures the listener sees the new credentials and does not trigger an unnecessary logIn operation
+    this.previousUser = { unsafeMetadata: clerkCredentials };
+
+    if (clerkClient.user) {
+      await clerkClient.user.update({
+        unsafeMetadata: clerkCredentials,
+      });
+    }
 
     const currentAccount = await Account.getMe().$jazz.ensureLoaded({
       resolve: {

package/src/tools/auth/clerk/tests/JazzClerkAuth.test.ts

@@ -282,6 +282,83 @@ describe("JazzClerkAuth", () => {
 
       expect(onClerkUserChangeSpy).toHaveBeenCalledTimes(1);
     });
+
+    it("should complete signup flow when new Clerk user is detected", async () => {
+      // 1. Setup local credentials (simulating anonymous user)
+      await authSecretStorage.set({
+        accountID: "test-account-id" as ID<Account>,
+        secretSeed: new Uint8Array([1, 2, 3]),
+        accountSecret: "test-secret" as AgentSecret,
+        provider: "anonymous",
+      });
+
+      const { client, triggerUserChange } = setupMockClerk(null);
+
+      const auth = new JazzClerkAuth(
+        mockAuthenticate,
+        mockLogOut,
+        authSecretStorage,
+      );
+
+      // 2. Register listener with null user (no one logged in yet)
+      auth.registerListener(client);
+
+      // Initial trigger with no user
+      triggerUserChange(null);
+
+      // 3. Trigger event with new Clerk user (no Jazz credentials yet)
+      const mockUserUpdate = vi.fn((data) => {
+        triggerUserChange(data);
+      });
+
+      const signInSpy = vi.spyOn(auth, "signIn");
+      const logInSpy = vi.spyOn(auth, "logIn");
+
+      const newClerkUser = {
+        fullName: "Test User",
+        firstName: "Test",
+        lastName: "User",
+        username: "testuser",
+        id: "clerk-user-123",
+        primaryEmailAddress: { emailAddress: "test@example.com" },
+        unsafeMetadata: {}, // No Jazz credentials yet
+        update: mockUserUpdate,
+      };
+
+      triggerUserChange(newClerkUser);
+
+      // Wait for async operations to complete
+      await vi.waitFor(() => {
+        expect(mockUserUpdate).toHaveBeenCalled();
+      });
+
+      // 4. Verify credentials synced to Clerk
+      expect(mockUserUpdate).toHaveBeenCalledWith({
+        unsafeMetadata: {
+          jazzAccountID: "test-account-id",
+          jazzAccountSecret: "test-secret",
+          jazzAccountSeed: [1, 2, 3],
+        },
+      });
+
+      // Verify profile name was updated from Clerk username
+      const me = await Account.getMe().$jazz.ensureLoaded({
+        resolve: { profile: true },
+      });
+      expect(me.profile.name).toBe("Test User");
+
+      // Verify authSecretStorage is updated with provider "clerk"
+      const storedCredentials = await authSecretStorage.get();
+      expect(storedCredentials).toEqual({
+        accountID: "test-account-id",
+        accountSecret: "test-secret",
+        secretSeed: new Uint8Array([1, 2, 3]),
+        provider: "clerk",
+      });
+
+      expect(signInSpy).toHaveBeenCalled();
+      expect(logInSpy).not.toHaveBeenCalled();
+    });
   });
 
   describe("initializeAuth", () => {