jazz-tools 0.19.8 → 0.19.11

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();
+  }
+}

package/src/tools/subscribe/SubscriptionScope.ts

@@ -1,4 +1,4 @@
-import type { LocalNode, RawCoValue } from "cojson";
+import { LocalNode, RawCoValue } from "cojson";
 import {
   CoFeed,
   CoList,
@@ -23,11 +23,18 @@ import type {
   SubscriptionValueLoading,
 } from "./types.js";
 import { CoValueLoadingState, NotLoadedCoValueState } from "./types.js";
-import { createCoValue, myRoleForRawValue } from "./utils.js";
 import {
   captureError,
   isCustomErrorReportingEnabled,
 } from "./errorReporting.js";
+import {
+  createCoValue,
+  isEqualRefsToResolve,
+  myRoleForRawValue,
+  PromiseWithStatus,
+  rejectedPromise,
+  resolvedPromise,
+} from "./utils.js";
 
 export class SubscriptionScope<D extends CoValue> {
   childNodes = new Map<string, SubscriptionScope<CoValue>>();
@@ -88,6 +95,7 @@ export class SubscriptionScope<D extends CoValue> {
       | RawCoValue
       | typeof CoValueLoadingState.UNAVAILABLE
       | undefined;
+
     this.subscription = new CoValueCoreSubscription(
       node,
       id,
@@ -301,6 +309,66 @@ export class SubscriptionScope<D extends CoValue> {
 
   unloadedValue: NotLoaded<D> | undefined;
 
+  lastPromise:
+    | {
+        value: MaybeLoaded<D> | undefined;
+        promise: PromiseWithStatus<MaybeLoaded<D>>;
+      }
+    | undefined;
+
+  cachePromise(value: MaybeLoaded<D>, callback: () => PromiseWithStatus<D>) {
+    if (this.lastPromise?.value === value) {
+      return this.lastPromise.promise;
+    }
+
+    const promise = callback();
+    this.lastPromise = { value, promise };
+
+    return promise;
+  }
+
+  getPromise() {
+    const currentValue = this.getCurrentValue();
+
+    if (currentValue.$isLoaded) {
+      return resolvedPromise(currentValue);
+    }
+
+    if (currentValue.$jazz.loadingState !== CoValueLoadingState.LOADING) {
+      const error = this.getError();
+      return rejectedPromise(
+        new Error(error?.toString() ?? "Unknown error", {
+          cause: this.callerStack,
+        }),
+      );
+    }
+
+    // We need to cache rejected promises to make React Suspense happy
+    return this.cachePromise(currentValue, () => {
+      return new Promise<D>((resolve, reject) => {
+        const unsubscribe = this.subscribe(() => {
+          const currentValue = this.getCurrentValue();
+
+          if (currentValue.$jazz.loadingState === CoValueLoadingState.LOADING) {
+            return;
+          }
+
+          if (currentValue.$isLoaded) {
+            resolve(currentValue);
+          } else {
+            reject(
+              new Error(this.getError()?.toString() ?? "Unknown error", {
+                cause: this.callerStack,
+              }),
+            );
+          }
+
+          unsubscribe();
+        });
+      });
+    });
+  }
+
   private getUnloadedValue(reason: NotLoadedCoValueState): NotLoaded<D> {
     if (this.unloadedValue?.$jazz.loadingState === reason) {
       return this.unloadedValue;
@@ -384,19 +452,21 @@ export class SubscriptionScope<D extends CoValue> {
     return result;
   }
 
-  logError() {
-    let error: JazzError | undefined;
-
+  getError() {
     if (
       this.value.type === CoValueLoadingState.UNAUTHORIZED ||
       this.value.type === CoValueLoadingState.UNAVAILABLE
     ) {
-      error = this.value;
+      return this.value;
     }
 
     if (this.errorFromChildren) {
-      error = this.errorFromChildren;
+      return this.errorFromChildren;
     }
+  }
+
+  logError() {
+    const error = this.getError();
 
     if (!error || this.lastErrorLogged === error) {
       return;
@@ -437,16 +507,45 @@ export class SubscriptionScope<D extends CoValue> {
   }
 
   subscribers = new Set<(value: SubscriptionValue<D, any>) => void>();
+  subscriberChangeCallbacks = new Set<(count: number) => void>();
+
+  /**
+   * Subscribe to subscriber count changes
+   * Callback receives the total number of subscribers
+   * Returns an unsubscribe function
+   */
+  onSubscriberChange(callback: (count: number) => void): () => void {
+    this.subscriberChangeCallbacks.add(callback);
+
+    return () => {
+      this.subscriberChangeCallbacks.delete(callback);
+    };
+  }
+
+  private notifySubscriberChange() {
+    const count = this.subscribers.size;
+    this.subscriberChangeCallbacks.forEach((callback) => {
+      callback(count);
+    });
+  }
+
   subscribe(listener: (value: SubscriptionValue<D, any>) => void) {
     this.subscribers.add(listener);
+    this.notifySubscriberChange();
 
     return () => {
       this.subscribers.delete(listener);
+      this.notifySubscriberChange();
     };
   }
 
   setListener(listener: (value: SubscriptionValue<D, any>) => void) {
+    const hadListener = this.subscribers.has(listener);
     this.subscribers.add(listener);
+    // Only notify if this is a new listener (count actually changed)
+    if (!hadListener) {
+      this.notifySubscriberChange();
+    }
     this.triggerUpdate();
   }
 
@@ -835,7 +934,14 @@ export class SubscriptionScope<D extends CoValue> {
     this.closed = true;
 
     this.subscription.unsubscribe();
+    const hadSubscribers = this.subscribers.size > 0;
     this.subscribers.clear();
+    // Notify callbacks that subscriber count is now 0 if there were subscribers before
+    if (hadSubscribers) {
+      this.notifySubscriberChange();
+    }
+    // Clear subscriber change callbacks to prevent memory leaks
+    this.subscriberChangeCallbacks.clear();
     this.childNodes.forEach((child) => child.destroy());
   }
 }

package/src/tools/subscribe/utils.ts

@@ -3,6 +3,7 @@ import { RegisteredSchemas } from "../coValues/registeredSchemas.js";
 import {
   CoValue,
   RefEncoded,
+  RefsToResolve,
   accountOrGroupToGroup,
   instantiateRefEncodedFromRaw,
 } from "../internal.js";
@@ -42,3 +43,79 @@ export function createCoValue<D extends CoValue>(
     id: subscriptionScope.id,
   };
 }
+
+export type PromiseWithStatus<T> = PromiseLike<T> & {
+  status?: "pending" | "fulfilled" | "rejected";
+  value?: T;
+  reason?: unknown;
+};
+
+export function resolvedPromise<T>(value: T): PromiseWithStatus<T> {
+  const promise = Promise.resolve(value) as PromiseWithStatus<T>;
+  promise.status = "fulfilled";
+  promise.value = value;
+  return promise;
+}
+
+export function rejectedPromise<T>(reason: unknown): PromiseWithStatus<T> {
+  const promise = Promise.reject(reason) as PromiseWithStatus<T>;
+  promise.status = "rejected";
+  promise.reason = reason;
+  return promise;
+}
+
+export function isEqualRefsToResolve(
+  a: RefsToResolve<any>,
+  b: RefsToResolve<any>,
+) {
+  // Fast path: same reference
+  if (a === b) {
+    return true;
+  }
+
+  // Fast path: both are boolean
+  if (typeof a === "boolean" && typeof b === "boolean") {
+    return a === b;
+  }
+
+  // One is boolean, the other is not
+  if (typeof a === "boolean" || typeof b === "boolean") {
+    return false;
+  }
+
+  // Both must be objects at this point
+  if (
+    typeof a !== "object" ||
+    typeof b !== "object" ||
+    a === null ||
+    b === null
+  ) {
+    return false;
+  }
+
+  // Get all keys from both objects
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+
+  // Different number of keys means not equal
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+
+  // Check each key
+  for (const key of keysA) {
+    if (!(key in b)) {
+      return false;
+    }
+
+    const valueA = (a as any)[key];
+    const valueB = (b as any)[key];
+
+    // Recursively compare nested RefsToResolve values
+    if (!isEqualRefsToResolve(valueA, valueB)) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/tools/testing.ts

@@ -16,9 +16,6 @@ import {
   coValueClassFromCoValueClassOrSchema,
   createAnonymousJazzContext,
   createJazzContext,
-  CoValue,
-  LoadedAndRequired,
-  MaybeLoaded,
   randomSessionProvider,
 } from "./internal.js";
 

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

@@ -14,6 +14,7 @@ import {
   setupJazzTestSync,
 } from "../testing.js";
 import { waitFor } from "../tests/utils.js";
+import { cojsonInternals } from "cojson";
 
 beforeEach(async () => {
   await setupJazzTestSync();
@@ -25,6 +26,8 @@ beforeEach(async () => {
   });
 });
 
+cojsonInternals.setCoValueLoadingRetryDelay(10);
+
 describe("CoValueCoreSubscription", async () => {
   /**
    * Tests scenarios where the CoValue is immediately available
@@ -444,7 +447,7 @@ describe("CoValueCoreSubscription", async () => {
   });
 
   describe("error handling scenarios", () => {
-    test("should handle return unavailable when the id is invalid", async () => {
+    test("should synchronously emit unavailable when an invalid id is provided", async () => {
       const bob = await createJazzTestAccount();
       const invalidId = "invalid-co-value-id";
 
@@ -461,13 +464,50 @@ describe("CoValueCoreSubscription", async () => {
         },
       );
 
-      // Should not call listener immediately since ID is invalid
-      expect(listener).not.toHaveBeenCalled();
+      // Should call listener synchronously since ID is invalid (doesn't start with "co_z")
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(lastResult).toBe(CoValueLoadingState.UNAVAILABLE);
+
+      subscription.unsubscribe();
+    });
+
+    test("should emit unavailable when subscribing to a CoValue that has already been marked as unavailable", async () => {
+      const Person = co.map({
+        name: z.string(),
+        age: z.number(),
+      });
+
+      // Create a person that bob can access
+      const person = Person.create(
+        { name: "John", age: 30 },
+        Group.create().makePublic("writer"),
+      );
+
+      // Create a new sync server, this way the CoValue is not available for new accounts
+      await setupJazzTestSync();
+      const bob = await createJazzTestAccount();
+
+      // Try to load it first, to mark the value as unavailable
+      await Person.load(person.$jazz.id, {
+        loadAs: bob,
+      });
+
+      let lastResult: any = null;
+      const listener = vi.fn();
+
+      // Subscribe to the unavailable CoValue
+      const subscription = new CoValueCoreSubscription(
+        bob.$jazz.localNode,
+        person.$jazz.id,
+        (result) => {
+          lastResult = result;
+          listener(result);
+        },
+      );
 
-      // Wait for the error handling to complete
       await waitFor(() => expect(listener).toHaveBeenCalled());
 
-      // Should report unavailable when loading fails
+      expect(listener).toHaveBeenCalledTimes(1);
       expect(lastResult).toBe(CoValueLoadingState.UNAVAILABLE);
 
       subscription.unsubscribe();
@@ -492,13 +532,7 @@ describe("CoValueCoreSubscription", async () => {
         { name: "main", owner: bob },
       );
 
-      // Should not call listener immediately since ID is invalid
-      expect(listener).not.toHaveBeenCalled();
-
-      // Wait for the error handling to complete
-      await waitFor(() => expect(listener).toHaveBeenCalled());
-
-      // Should report unavailable when loading fails
+      expect(listener).toHaveBeenCalledTimes(1);
       expect(lastResult).toBe(CoValueLoadingState.UNAVAILABLE);
 
       subscription.unsubscribe();