jazz-tools 0.19.8 → 0.19.10

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

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

@@ -33,6 +33,7 @@ import {
   getPeerConnectedToTestSyncServer,
   setupJazzTestSync,
 } from "../testing";
+import { SubscriptionCache } from "../subscribe/SubscriptionCache";
 import { createAsyncStorage, getDbPath } from "./testStorage";
 
 const Crypto = await WasmCrypto.create();
@@ -809,4 +810,88 @@ describe("ContextManager", () => {
       );
     });
   });
+
+  describe("SubscriptionCache integration", () => {
+    test("initializes cache on construction", () => {
+      const newManager = new TestJazzContextManager<Account>();
+      const cache = newManager.getSubscriptionScopeCache();
+
+      expect(cache).toBeDefined();
+      expect(cache).toBeInstanceOf(SubscriptionCache);
+    });
+
+    test("getSubscriptionScopeCache returns the cache instance", () => {
+      const cache1 = manager.getSubscriptionScopeCache();
+      const cache2 = manager.getSubscriptionScopeCache();
+
+      expect(cache1).toBe(cache2);
+      expect(cache1).toBeDefined();
+    });
+
+    test("updateContext clears the cache", async () => {
+      await manager.createContext({});
+
+      const cache = manager.getSubscriptionScopeCache();
+      const node = getCurrentValue().node;
+      const Person = co.map({ name: z.string() });
+      const person = Person.create({ name: "Test" });
+
+      // Create a subscription in the cache
+      const scope = cache.getOrCreate(
+        node,
+        Person,
+        person.$jazz.id,
+        true,
+        false,
+        false,
+      );
+
+      // Verify it's in the cache
+      const idSet = (cache as any).cache.get(person.$jazz.id);
+      expect(idSet).toBeDefined();
+      expect(idSet).toBeInstanceOf(Set);
+      expect(idSet.size).toBeGreaterThan(0);
+
+      // Update context - should clear cache
+      await manager.createContext({});
+
+      // Verify cache was cleared
+      const idSetAfter = (cache as any).cache.get(person.$jazz.id);
+      expect(idSetAfter).toBeUndefined();
+      expect(scope.closed).toBe(true);
+    });
+
+    test("logOut clears the cache", async () => {
+      await manager.createContext({});
+
+      const cache = manager.getSubscriptionScopeCache();
+      const node = getCurrentValue().node;
+      const Person = co.map({ name: z.string() });
+      const person = Person.create({ name: "Test" });
+
+      // Create a subscription in the cache
+      const scope = cache.getOrCreate(
+        node,
+        Person,
+        person.$jazz.id,
+        true,
+        false,
+        false,
+      );
+
+      // Verify it's in the cache
+      const scopeSet = (cache as any).cache.get(person.$jazz.id);
+      expect(scopeSet).toBeDefined();
+      expect(scopeSet).toBeInstanceOf(Set);
+      expect(scopeSet.size).toBeGreaterThan(0);
+
+      // Logout - should clear cache
+      await manager.logOut();
+
+      // Verify cache was cleared
+      const scopeSetAfter = (cache as any).cache.get(person.$jazz.id);
+      expect(scopeSetAfter).toBeUndefined();
+      expect(scope.closed).toBe(true);
+    });
+  });
 });

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

@@ -0,0 +1,237 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Account, Group, co, z } from "../exports.js";
+import { SubscriptionCache } from "../subscribe/SubscriptionCache.js";
+import { createJazzTestAccount, setupJazzTestSync } from "../testing.js";
+
+describe("SubscriptionCache", () => {
+  const Person = co.map({
+    name: co.plainText(),
+  });
+
+  beforeEach(async () => {
+    await setupJazzTestSync();
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+      creationProps: { name: "Hermes Puggington" },
+    });
+  });
+
+  describe("cache key comparison logic", () => {
+    it("matches entries with identical schema, id, resolve, and branch", () => {
+      const person = Person.create({ name: "John" });
+      const node = person.$jazz.raw.core.node;
+      const id = person.$jazz.id;
+      const cache = new SubscriptionCache();
+
+      const scope1 = cache.getOrCreate(node, Person, id, true, false, false);
+      const scope2 = cache.getOrCreate(node, Person, id, true, false, false);
+
+      expect(scope1).toBe(scope2);
+      cache.clear();
+    });
+
+    it("creates different entries for different resolve queries", () => {
+      const person = Person.create({ name: "John" });
+      const node = person.$jazz.raw.core.node;
+      const id = person.$jazz.id;
+      const cache = new SubscriptionCache();
+
+      const scope1 = cache.getOrCreate(node, Person, id, true, false, false);
+      const scope2 = cache.getOrCreate(
+        node,
+        Person,
+        id,
+        { name: true },
+        false,
+        false,
+      );
+
+      expect(scope1).not.toBe(scope2);
+      cache.clear();
+    });
+
+    it("creates different entries for different branch definitions", () => {
+      const person = Person.create({ name: "John" });
+      const group = Group.create();
+      const node = person.$jazz.raw.core.node;
+      const id = person.$jazz.id;
+      const cache = new SubscriptionCache();
+
+      const scope1 = cache.getOrCreate(node, Person, id, true, false, false, {
+        name: "branch1",
+        owner: group,
+      });
+      const scope2 = cache.getOrCreate(node, Person, id, true, false, false, {
+        name: "branch2",
+        owner: group,
+      });
+
+      expect(scope1).not.toBe(scope2);
+      cache.clear();
+    });
+
+    it("matches entries with same branch name but different owner references", () => {
+      const person = Person.create({ name: "John" });
+      const group1 = Group.create();
+      const group2 = Group.create();
+      const node = person.$jazz.raw.core.node;
+      const id = person.$jazz.id;
+      const cache = new SubscriptionCache();
+
+      const scope1 = cache.getOrCreate(node, Person, id, true, false, false, {
+        name: "branch",
+        owner: group1,
+      });
+      const scope2 = cache.getOrCreate(node, Person, id, true, false, false, {
+        name: "branch",
+        owner: group2,
+      });
+
+      expect(scope1).not.toBe(scope2);
+      cache.clear();
+    });
+  });
+
+  describe("subscriber count tracking", () => {
+    it("tracks subscriber count changes via onSubscriberChange", () => {
+      const person = Person.create({ name: "John" });
+      const node = person.$jazz.raw.core.node;
+      const id = person.$jazz.id;
+      const cache = new SubscriptionCache();
+
+      const scope = cache.getOrCreate(node, Person, id, true, false, false);
+
+      expect(scope.subscribers.size).toBe(0);
+
+      const unsubscribe1 = scope.subscribe(() => {});
+      expect(scope.subscribers.size).toBe(1);
+
+      const unsubscribe2 = scope.subscribe(() => {});
+      expect(scope.subscribers.size).toBe(2);
+
+      unsubscribe1();
+      expect(scope.subscribers.size).toBe(1);
+
+      unsubscribe2();
+      expect(scope.subscribers.size).toBe(0);
+
+      cache.clear();
+    });
+  });
+
+  describe("cleanup lifecycle", () => {
+    it("schedules cleanup when subscriber count reaches zero", async () => {
+      vi.useFakeTimers();
+      const person = Person.create({ name: "John" });
+      const node = person.$jazz.raw.core.node;
+      const id = person.$jazz.id;
+      const cache = new SubscriptionCache(100); // 100ms timeout
+
+      const scope = cache.getOrCreate(node, Person, id, true, false, false);
+
+      const unsubscribe = scope.subscribe(() => {});
+      unsubscribe();
+
+      await vi.advanceTimersByTimeAsync(110);
+
+      expect(scope.closed).toBe(true);
+
+      cache.clear();
+      vi.useRealTimers();
+    });
+
+    it("cancels cleanup when new subscription arrives during pending cleanup", async () => {
+      vi.useFakeTimers();
+      const person = Person.create({ name: "John" });
+      const node = person.$jazz.raw.core.node;
+      const id = person.$jazz.id;
+      const cache = new SubscriptionCache(100); // 100ms timeout
+
+      const scope1 = cache.getOrCreate(node, Person, id, true, false, false);
+
+      const unsubscribe = scope1.subscribe(() => {});
+      unsubscribe();
+
+      await vi.advanceTimersByTimeAsync(50);
+
+      // Request again before cleanup
+      const scope2 = cache.getOrCreate(node, Person, id, true, false, false);
+
+      expect(scope2).toBe(scope1);
+      await vi.advanceTimersByTimeAsync(60);
+
+      cache.clear();
+      vi.useRealTimers();
+    });
+
+    it("executes cleanup after timeout", async () => {
+      vi.useFakeTimers();
+      const person = Person.create({ name: "John" });
+      const node = person.$jazz.raw.core.node;
+      const id = person.$jazz.id;
+      const cache = new SubscriptionCache(100); // 100ms timeout
+
+      const scope = cache.getOrCreate(node, Person, id, true, false, false);
+
+      const unsubscribe = scope.subscribe(() => {});
+      unsubscribe();
+
+      await vi.advanceTimersByTimeAsync(150);
+
+      const idSet = (cache as any).cache.get(id);
+      expect(idSet).toBeUndefined();
+
+      cache.clear();
+      vi.useRealTimers();
+    });
+  });
+
+  describe("clear method", () => {
+    it("destroys all entries", () => {
+      const person1 = Person.create({ name: "John" });
+      const person2 = Person.create({ name: "Jane" });
+      const node = person1.$jazz.raw.core.node;
+      const cache = new SubscriptionCache();
+
+      const scope1 = cache.getOrCreate(
+        node,
+        Person,
+        person1.$jazz.id,
+        true,
+        false,
+        false,
+      );
+      const scope2 = cache.getOrCreate(
+        node,
+        Person,
+        person2.$jazz.id,
+        true,
+        false,
+        false,
+      );
+
+      cache.clear();
+
+      expect(scope1.closed).toBe(true);
+      expect(scope2.closed).toBe(true);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("throws error for null/undefined id", () => {
+      const person = Person.create({ name: "John" });
+      const node = person.$jazz.raw.core.node;
+      const cache = new SubscriptionCache();
+
+      expect(() => {
+        cache.getOrCreate(node, Person, null as any, true, false, false);
+      }).toThrow("Cannot create subscription with undefined or null id");
+
+      expect(() => {
+        cache.getOrCreate(node, Person, undefined as any, true, false, false);
+      }).toThrow("Cannot create subscription with undefined or null id");
+
+      cache.clear();
+    });
+  });
+});