jazz-tools 0.19.8 → 0.19.10

package/src/react-core/use.ts

@@ -0,0 +1,46 @@
+import React from "react";
+
+// shim from https://github.com/pmndrs/jotai/blob/f287c5d665a807e676bc731e83174c62c1fe1fc9/src/react/useAtomValue.ts#L13C1-L56C1
+const attachPromiseStatus = <T>(
+  promise: PromiseLike<T> & {
+    status?: "pending" | "fulfilled" | "rejected";
+    value?: T;
+    reason?: unknown;
+  },
+) => {
+  if (!promise.status) {
+    promise.status = "pending";
+    promise.then(
+      (v) => {
+        promise.status = "fulfilled";
+        promise.value = v;
+      },
+      (e) => {
+        promise.status = "rejected";
+        promise.reason = e;
+      },
+    );
+  }
+};
+
+export const use =
+  React.use ||
+  // A shim for older React versions
+  (<T>(
+    promise: PromiseLike<T> & {
+      status?: "pending" | "fulfilled" | "rejected";
+      value?: T;
+      reason?: unknown;
+    },
+  ): T => {
+    if (promise.status === "pending") {
+      throw promise;
+    } else if (promise.status === "fulfilled") {
+      return promise.value as T;
+    } else if (promise.status === "rejected") {
+      throw promise.reason;
+    } else {
+      attachPromiseStatus(promise);
+      throw promise;
+    }
+  });

package/src/react-native-core/crypto/RNCrypto.ts

@@ -0,0 +1 @@
+export * from "cojson/crypto/RNCrypto";

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

@@ -19,6 +19,8 @@ export {
   useCoValueSubscription,
   useAccountSubscription,
   useSubscriptionSelector,
+  useSuspenseCoState,
+  useSuspenseAccount,
 } from "jazz-tools/react-core";
 
 export function useAcceptInviteNative<S extends CoValueClassOrSchema>({

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

@@ -24,12 +24,13 @@ import { KvStore, KvStoreContext } from "./storage/kv-store-context.js";
 import { SQLiteDatabaseDriverAsync } from "cojson";
 import { WebSocketPeerWithReconnection } from "cojson-transport-ws";
 import type { RNQuickCrypto } from "jazz-tools/react-native-core/crypto";
+import type { RNCrypto } from "cojson/crypto/RNCrypto";
 
 export type BaseReactNativeContextOptions = {
   sync: SyncConfig;
   reconnectionTimeout?: number;
   storage?: SQLiteDatabaseDriverAsync | "disabled";
-  CryptoProvider?: typeof PureJSCrypto | typeof RNQuickCrypto;
+  CryptoProvider?: typeof PureJSCrypto | typeof RNQuickCrypto | typeof RNCrypto;
   authSecretStorage: AuthSecretStorage;
 };
 

package/src/tools/coValues/interfaces.ts

@@ -4,7 +4,7 @@ import {
   type CojsonInternalTypes,
   type RawCoValue,
 } from "cojson";
-import { AvailableCoValueCore } from "cojson/dist/coValueCore/coValueCore.js";
+import { AvailableCoValueCore } from "cojson";
 import {
   Account,
   AnonymousJazzAgent,
@@ -23,7 +23,6 @@ import {
   ResolveQueryStrict,
   Resolved,
   SubscriptionScope,
-  type SubscriptionValue,
   TypeSym,
   NotLoaded,
   activeAccountContext,
@@ -31,7 +30,7 @@ import {
   inspect,
 } from "../internal.js";
 import type { BranchDefinition } from "../subscribe/types.js";
-import { CoValueHeader } from "cojson/dist/coValueCore/verifiedState.js";
+import { CoValueHeader } from "cojson";
 
 /** @category Abstract interfaces */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/tools/implementation/ContextManager.ts

@@ -9,6 +9,7 @@ import { JazzContextType } from "../types.js";
 import { AnonymousJazzAgent } from "./anonymousJazzAgent.js";
 import { createAnonymousJazzContext } from "./createContext.js";
 import { InstanceOfSchema } from "./zodSchema/typeConverters/InstanceOfSchema.js";
+import { SubscriptionCache } from "../subscribe/SubscriptionCache.js";
 
 export type JazzContextManagerAuthProps = {
   credentials?: AuthCredentials;
@@ -75,6 +76,7 @@ export class JazzContextManager<
   protected keepContextOpen = false;
   contextPromise: Promise<void> | undefined;
   protected authenticatingAccountID: string | null = null;
+  private subscriptionCache: SubscriptionCache;
 
   constructor(opts?: {
     useAnonymousFallback?: boolean;
@@ -82,6 +84,7 @@ export class JazzContextManager<
   }) {
     KvStoreContext.getInstance().initialize(this.getKvStore());
     this.authSecretStorage = new AuthSecretStorage(opts?.authSecretStorageKey);
+    this.subscriptionCache = new SubscriptionCache();
 
     if (opts?.useAnonymousFallback) {
       this.value = getAnonymousFallback();
@@ -130,6 +133,9 @@ export class JazzContextManager<
     context: PlatformSpecificContext<Acc>,
     authProps?: JazzContextManagerAuthProps,
   ) {
+    // Clear cache before updating context to prevent subscription leaks across authentication boundaries
+    this.subscriptionCache.clear();
+
     // When keepContextOpen we don't want to close the previous context
     // because we might need to handle the onAnonymousAccountDiscarded callback
     if (!this.keepContextOpen) {
@@ -178,6 +184,10 @@ export class JazzContextManager<
     return this.authenticatingAccountID;
   }
 
+  getSubscriptionScopeCache(): SubscriptionCache {
+    return this.subscriptionCache;
+  }
+
   logOut = async () => {
     if (!this.context || !this.props) {
       return;
@@ -185,6 +195,9 @@ export class JazzContextManager<
 
     this.authenticatingAccountID = null;
 
+    // Clear cache on logout to prevent subscription leaks across authentication boundaries
+    this.subscriptionCache.clear();
+
     await this.props.onLogOut?.();
 
     if (this.props.logOutReplacement) {

package/src/tools/subscribe/CoValueCoreSubscription.ts

@@ -1,6 +1,7 @@
 import {
   cojsonInternals,
   CoValueCore,
+  isRawCoID,
   LocalNode,
   RawCoID,
   RawCoValue,
@@ -67,121 +68,76 @@ export class CoValueCoreSubscription {
   private initializeSubscription(): void {
     const source = this.source;
 
-    // If the CoValue is already available, handle it immediately
-    if (source.isAvailable()) {
-      this.handleAvailableSource();
+    // If the ID is not a valid raw CoID, we immediately emit an unavailable event
+    if (!isRawCoID(source.id)) {
+      this.emit(CoValueLoadingState.UNAVAILABLE);
       return;
     }
 
-    // If a specific branch is requested while the source is not available, attempt to checkout that branch
+    // If we have a branch name, we handle branching
     if (this.branchName) {
-      this.handleBranchCheckout();
+      this.handleBranching(this.branchName, this.branchOwnerId);
       return;
     }
 
-    // If we don't have a branch requested, load the CoValue
-    this.loadCoValue();
+    // If we don't have a branch name, we subscribe to the source directly
+    this.subscribe(this.source);
   }
 
-  /**
-   * Handles the case where the CoValue source is immediately available.
-   * Either subscribes directly or attempts to get the requested branch.
-   */
-  private handleAvailableSource(): void {
-    if (!this.branchName || !cojsonInternals.canBeBranched(this.source)) {
-      this.subscribe(this.source.getCurrentContent());
+  private handleBranching(branchName: string, branchOwnerId?: RawCoID) {
+    const source = this.source;
+
+    // If the source is not available, we wait for it to become available and then try to branch
+    if (!source.isAvailable()) {
+      this.waitForSourceToBecomeAvailable(branchName, branchOwnerId);
       return;
     }
 
-    // Try to get the specific branch from the available source
-    const branch = this.source.getBranch(this.branchName, this.branchOwnerId);
-
-    if (branch.isAvailable()) {
-      // Branch is available, subscribe to it
-      this.subscribe(branch.getCurrentContent());
+    // If the source is not branchable (e.g. it is a group), we subscribe to it directly
+    if (!cojsonInternals.canBeBranched(source)) {
+      this.subscribe(source);
       return;
-      // If the branch hasn't been created, we create it directly so we can syncronously subscribe to it
-    } else if (!this.source.hasBranch(this.branchName, this.branchOwnerId)) {
-      this.source.createBranch(this.branchName, this.branchOwnerId);
-      this.subscribe(branch.getCurrentContent());
-    } else {
-      // Branch not available, fall through to checkout logic
-      this.handleBranchCheckout();
     }
-  }
 
-  /**
-   * Attempts to checkout a specific branch of the CoValue.
-   * This is called when the source isn't available but a branch is requested.
-   */
-  private handleBranchCheckout(): void {
-    this.localNode
-      .checkoutBranch(this.source.id, this.branchName!, this.branchOwnerId)
-      .then((value) => {
-        if (this.unsubscribed) return;
-
-        if (value !== CoValueLoadingState.UNAVAILABLE) {
-          // Branch checkout successful, subscribe to it
-          this.subscribe(value);
-        } else {
-          // Branch checkout failed, handle the error
-          this.handleUnavailableBranch();
-        }
-      })
-      .catch((error) => {
-        // Handle unexpected errors during branch checkout
-        console.error(error);
+    // Try to get the specific branch from the available source
+    const branch = source.getBranch(branchName, branchOwnerId);
+
+    // If the branch hasn't been created, we create it directly so we can syncronously subscribe to it
+    if (!branch.isAvailable() && !source.hasBranch(branchName, branchOwnerId)) {
+      try {
+        source.createBranch(branchName, branchOwnerId);
+      } catch (error) {
+        // If the branch creation fails (provided group is not available), we emit an unavailable event
+        console.error("error creating branch", error);
         this.emit(CoValueLoadingState.UNAVAILABLE);
-      });
-  }
-
-  /**
-   * Handles the case where a branch checkout fails.
-   * Determines whether to retry or report unavailability.
-   */
-  private handleUnavailableBranch(): void {
-    const source = this.source;
-    if (source.isAvailable()) {
-      // This should be impossible - if source is available we can create the branch and it should be available
-      throw new Error("Branch is unavailable");
+        return;
+      }
     }
 
-    // Source isn't available either, subscribe to state changes and report unavailability
-    this.subscribeToUnavailableSource();
-    this.emit(CoValueLoadingState.UNAVAILABLE);
+    this.subscribe(branch);
   }
 
   /**
-   * Loads the CoValue core from the network/storage.
-   * This is the fallback strategy when immediate availability fails.
+   * Loads a CoValue core and emits an unavailable event if it is still unavailable after the retries.
    */
-  private loadCoValue(): void {
+  load(value: CoValueCore) {
     this.localNode
-      .loadCoValueCore(this.source.id, undefined, this.skipRetry)
-      .then((value) => {
-        if (this.unsubscribed) return;
-
-        if (value.isAvailable()) {
-          // Loading successful, subscribe to the loaded value
-          this.subscribe(value.getCurrentContent());
-        } else {
-          // Loading failed, subscribe to state changes and report unavailability
-          this.subscribeToUnavailableSource();
+      .loadCoValueCore(value.id, undefined, this.skipRetry)
+      .then(() => {
+        // If after the retries the value is still unavailable, we emit an unavailable event
+        if (!value.isAvailable()) {
           this.emit(CoValueLoadingState.UNAVAILABLE);
         }
-      })
-      .catch((error) => {
-        // Handle unexpected errors during loading
-        console.error(error);
-        this.emit(CoValueLoadingState.UNAVAILABLE);
       });
   }
 
   /**
-   * Subscribes to state changes of an unavailable CoValue source.
-   * This allows the subscription to become active when the source becomes available after a first loading attempt.
+   * Waits for the source to become available and then tries to branch.
    */
-  private subscribeToUnavailableSource(): void {
+  private waitForSourceToBecomeAvailable(
+    branchName: string,
+    branchOwnerId?: RawCoID,
+  ): void {
     const source = this.source;
 
     const handleStateChange = (
@@ -197,41 +153,60 @@ export class CoValueCoreSubscription {
 
       unsubFromStateChange();
 
-      if (this.branchName) {
-        // Branch was requested, attempt checkout again
-        this.handleBranchCheckout();
-      } else {
-        // No branch requested, subscribe directly and cleanup state subscription
-        this.subscribe(source.getCurrentContent());
-      }
+      this.handleBranching(branchName, branchOwnerId);
     };
 
     // Subscribe to state changes and store the unsubscribe function
     this._unsubscribe = source.subscribe(handleStateChange);
+
+    this.load(source);
   }
 
   /**
    * Subscribes to a specific CoValue and notifies the listener.
    * This is the final step where we actually start receiving updates.
    */
-  private subscribe(value: RawCoValue): void {
+  private subscribe(value: CoValueCore): void {
     if (this.unsubscribed) return;
 
     // Subscribe to the value and store the unsubscribe function
     this._unsubscribe = value.subscribe((value) => {
-      this.emit(value);
+      if (value.isAvailable()) {
+        this.emit(value.getCurrentContent());
+      }
     });
+
+    if (!value.isAvailable()) {
+      this.load(value);
+    }
   }
 
+  lastState: CoValueLoadingState | undefined;
+
   emit(value: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE): void {
     if (this.unsubscribed) return;
-    if (!isReadyForEmit(value)) {
+    if (!this.isReadyForEmit(value)) {
       return;
     }
 
     this.listener(value);
   }
 
+  isReadyForEmit(
+    value: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE,
+  ): boolean {
+    if (value === CoValueLoadingState.UNAVAILABLE) {
+      return true;
+    }
+
+    // If the value is not completely downloaded, we don't emit it to avoid providing partial data to the listener.
+    if (!isCompletelyDownloaded(value)) {
+      return false;
+    }
+
+    return true;
+  }
+
   /**
    * Unsubscribes from all active subscriptions and marks the instance as unsubscribed.
    * This prevents any further operations and ensures proper cleanup.
@@ -246,11 +221,7 @@ export class CoValueCoreSubscription {
 /**
  * This is true if the value is unavailable, or if the value is a binary coValue or a completely downloaded coValue.
  */
-function isReadyForEmit(value: RawCoValue | "unavailable") {
-  if (value === "unavailable") {
-    return true;
-  }
-
+function isCompletelyDownloaded(value: RawCoValue) {
   return (
     value.core.verified?.header.meta?.type === "binary" ||
     value.core.isCompletelyDownloaded()

package/src/tools/subscribe/SubscriptionCache.ts

@@ -0,0 +1,272 @@
+import { LocalNode } from "cojson";
+import type {
+  CoValue,
+  CoValueClassOrSchema,
+  RefEncoded,
+  RefsToResolve,
+  ResolveQuery,
+} from "../internal.js";
+import { coValueClassFromCoValueClassOrSchema } from "../internal.js";
+import { SubscriptionScope } from "./SubscriptionScope.js";
+import type { BranchDefinition } from "./types.js";
+import { isEqualRefsToResolve } from "./utils.js";
+
+interface CacheEntry {
+  subscriptionScope: SubscriptionScope<any>;
+  schema: CoValueClassOrSchema;
+  resolve: RefsToResolve<any>;
+  branch?: BranchDefinition;
+  subscriberCount: number;
+  cleanupTimeoutId?: ReturnType<typeof setTimeout>;
+  unsubscribeFromScope: () => void;
+}
+
+export class SubscriptionCache {
+  // Nested cache: outer map keyed by id, inner set of CacheEntry
+  private cache: Map<string, Set<CacheEntry>>;
+  private cleanupTimeout: number;
+
+  constructor(cleanupTimeout: number = 5000) {
+    this.cache = new Map();
+    this.cleanupTimeout = cleanupTimeout;
+  }
+
+  /**
+   * Get the inner set for a given id (read-only access)
+   */
+  private getIdSet(id: string): Set<CacheEntry> | undefined {
+    return this.cache.get(id);
+  }
+
+  /**
+   * Get the inner set for a given id, creating it if it doesn't exist
+   */
+  private getIdSetOrCreate(id: string): Set<CacheEntry> {
+    let idSet = this.cache.get(id);
+    if (!idSet) {
+      idSet = new Set();
+      this.cache.set(id, idSet);
+    }
+    return idSet;
+  }
+
+  /**
+   * Check if an entry matches the provided parameters
+   */
+  private matchesEntry(
+    entry: CacheEntry,
+    schema: CoValueClassOrSchema,
+    resolve: RefsToResolve<any>,
+    branch?: BranchDefinition,
+  ): boolean {
+    // Compare schema by object identity
+    if (entry.schema !== schema) {
+      return false;
+    }
+
+    // Compare resolve queries using isEqualRefsToResolve
+    if (!isEqualRefsToResolve(entry.resolve, resolve)) {
+      return false;
+    }
+
+    // Compare branch names by string equality
+    const branchName = branch?.name;
+    if (entry.branch?.name !== branchName) {
+      return false;
+    }
+
+    // Compare branch owner ids by string equality
+    const branchOwnerId = branch?.owner?.$jazz.id;
+    if (entry.branch?.owner?.$jazz.id !== branchOwnerId) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Find a matching cache entry by comparing against entry properties
+   * Uses id-based nesting to quickly filter candidates
+   */
+  private findMatchingEntry(
+    schema: CoValueClassOrSchema,
+    id: string,
+    resolve: RefsToResolve<any>,
+    branch?: BranchDefinition,
+  ): CacheEntry | undefined {
+    // Get the inner set for this id (quick filter)
+    const idSet = this.getIdSet(id);
+    if (!idSet) {
+      return undefined;
+    }
+
+    // Search only within entries for this id
+    for (const entry of idSet) {
+      if (this.matchesEntry(entry, schema, resolve, branch)) {
+        return entry;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Handle subscriber count changes from SubscriptionScope
+   */
+  private handleSubscriberChange(entry: CacheEntry, count: number): void {
+    entry.subscriberCount = count;
+
+    if (count === 0) {
+      // Schedule cleanup when subscriber count reaches zero
+      this.scheduleCleanup(entry);
+    } else {
+      // Cancel cleanup if count increases from zero
+      this.cancelCleanup(entry);
+    }
+  }
+
+  /**
+   * Schedule cleanup timeout for an entry
+   */
+  private scheduleCleanup(entry: CacheEntry): void {
+    // Cancel any existing cleanup timeout
+    this.cancelCleanup(entry);
+
+    entry.cleanupTimeoutId = setTimeout(() => {
+      this.destroyEntry(entry);
+    }, this.cleanupTimeout);
+  }
+
+  /**
+   * Cancel pending cleanup timeout for an entry
+   */
+  private cancelCleanup(entry: CacheEntry): void {
+    if (entry.cleanupTimeoutId !== undefined) {
+      clearTimeout(entry.cleanupTimeoutId);
+      entry.cleanupTimeoutId = undefined;
+    }
+  }
+
+  /**
+   * Destroy a cache entry and its SubscriptionScope
+   */
+  private destroyEntry(entry: CacheEntry): void {
+    // Cancel any pending cleanup
+    this.cancelCleanup(entry);
+
+    // Unsubscribe from subscriber changes
+    entry.unsubscribeFromScope();
+
+    // Destroy the SubscriptionScope
+    try {
+      entry.subscriptionScope.destroy();
+    } catch (error) {
+      // Log error but don't throw - we still want to remove the entry
+      console.error("Error destroying SubscriptionScope:", error);
+    }
+
+    // Remove from nested cache structure
+    const id = entry.subscriptionScope.id;
+    const idSet = this.getIdSet(id);
+    if (idSet) {
+      idSet.delete(entry);
+      // Clean up empty inner set to prevent memory leaks
+      if (idSet.size === 0) {
+        this.cache.delete(id);
+      }
+    }
+  }
+
+  /**
+   * Get or create a SubscriptionScope from the cache
+   */
+  getOrCreate<S extends CoValueClassOrSchema>(
+    node: LocalNode,
+    schema: S,
+    id: string,
+    resolve: ResolveQuery<S>,
+    skipRetry?: boolean,
+    bestEffortResolution?: boolean,
+    branch?: BranchDefinition,
+  ): SubscriptionScope<CoValue> {
+    // Handle undefined/null id case
+    if (!id) {
+      throw new Error("Cannot create subscription with undefined or null id");
+    }
+
+    // Search for matching entry
+    const matchingEntry = this.findMatchingEntry(schema, id, resolve, branch);
+
+    if (matchingEntry) {
+      // Found existing entry - cancel any pending cleanup since we're reusing it
+      this.cancelCleanup(matchingEntry);
+
+      return matchingEntry.subscriptionScope as SubscriptionScope<CoValue>;
+    }
+
+    // Create new SubscriptionScope
+    // Transform schema to RefEncoded format
+    const refEncoded: RefEncoded<CoValue> = {
+      ref: coValueClassFromCoValueClassOrSchema(schema) as any,
+      optional: true,
+    };
+
+    // Create new SubscriptionScope with all required parameters
+    const subscriptionScope = new SubscriptionScope<CoValue>(
+      node,
+      // @ts-expect-error the SubscriptionScope is too generic for TS to infer its instances are CoValues
+      resolve,
+      id,
+      refEncoded,
+      skipRetry ?? false,
+      bestEffortResolution ?? false,
+      branch,
+    );
+
+    const handleSubscriberChange = (count: number) => {
+      const idSet = this.getIdSet(id);
+      if (idSet && idSet.has(entry)) {
+        this.handleSubscriberChange(entry, count);
+      }
+    };
+
+    // Create cache entry with initial subscriber count (starts at 0)
+    const entry: CacheEntry = {
+      subscriptionScope,
+      schema,
+      resolve,
+      branch,
+      subscriberCount: subscriptionScope.subscribers.size,
+      unsubscribeFromScope: subscriptionScope.onSubscriberChange(
+        handleSubscriberChange,
+      ),
+    };
+
+    // Store in nested cache structure
+    const idSet = this.getIdSetOrCreate(id);
+    idSet.add(entry);
+
+    return subscriptionScope;
+  }
+
+  /**
+   * Clear all cache entries and destroy all SubscriptionScope instances
+   */
+  clear(): void {
+    // Collect all entries first to avoid iteration issues during deletion
+    const entriesToDestroy: CacheEntry[] = [];
+    for (const idSet of this.cache.values()) {
+      for (const entry of idSet) {
+        entriesToDestroy.push(entry);
+      }
+    }
+
+    // Destroy all entries
+    for (const entry of entriesToDestroy) {
+      this.destroyEntry(entry);
+    }
+
+    // Clear the cache map (should already be empty, but ensure it)
+    this.cache.clear();
+  }
+}