jazz-tools 0.19.7 → 0.19.10

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,7 +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>>();
@@ -58,6 +69,13 @@ export class SubscriptionScope<D extends CoValue> {
 
   silenceUpdates = false;
 
+  /**
+   * Stack trace captured at subscription creation time.
+   * This helps identify which component/hook created the subscription
+   * when debugging "value unavailable" errors.
+   */
+  callerStack: Error | undefined;
+
   constructor(
     public node: LocalNode,
     resolve: RefsToResolve<D>,
@@ -66,7 +84,10 @@ export class SubscriptionScope<D extends CoValue> {
     public skipRetry = false,
     public bestEffortResolution = false,
     public unstable_branch?: BranchDefinition,
+    callerStack?: Error | undefined,
   ) {
+    // Use caller stack if provided, otherwise capture here (less useful but better than nothing)
+    this.callerStack = callerStack;
     this.resolve = resolve;
     this.value = { type: CoValueLoadingState.LOADING, id };
 
@@ -74,6 +95,7 @@ export class SubscriptionScope<D extends CoValue> {
       | RawCoValue
       | typeof CoValueLoadingState.UNAVAILABLE
       | undefined;
+
     this.subscription = new CoValueCoreSubscription(
       node,
       id,
@@ -126,37 +148,40 @@ export class SubscriptionScope<D extends CoValue> {
   handleUpdate(update: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE) {
     if (update === CoValueLoadingState.UNAVAILABLE) {
       if (this.value.type === CoValueLoadingState.LOADING) {
-        this.updateValue(
-          new JazzError(this.id, CoValueLoadingState.UNAVAILABLE, [
-            {
-              code: CoValueLoadingState.UNAVAILABLE,
-              message: "The value is unavailable",
-              params: {
-                id: this.id,
-              },
-              path: [],
+        const error = new JazzError(this.id, CoValueLoadingState.UNAVAILABLE, [
+          {
+            code: CoValueLoadingState.UNAVAILABLE,
+            message: `Jazz Unavailable Error: unable to load ${this.id}`,
+            params: {
+              id: this.id,
             },
-          ]),
-        );
+            path: [],
+          },
+        ]);
+
+        this.updateValue(error);
       }
+
       this.triggerUpdate();
       return;
     }
 
     if (!hasAccessToCoValue(update)) {
       if (this.value.type !== CoValueLoadingState.UNAUTHORIZED) {
-        this.updateValue(
-          new JazzError(this.id, CoValueLoadingState.UNAUTHORIZED, [
-            {
-              code: CoValueLoadingState.UNAUTHORIZED,
-              message: `The current user (${this.node.getCurrentAgent().id}) is not authorized to access this value`,
-              params: {
-                id: this.id,
-              },
-              path: [],
+        const message = `Jazz Authorization Error: The current user (${this.node.getCurrentAgent().id}) is not authorized to access ${this.id}`;
+
+        const error = new JazzError(this.id, CoValueLoadingState.UNAUTHORIZED, [
+          {
+            code: CoValueLoadingState.UNAUTHORIZED,
+            message,
+            params: {
+              id: this.id,
             },
-          ]),
-        );
+            path: [],
+          },
+        ]);
+
+        this.updateValue(error);
         this.triggerUpdate();
       }
       return;
@@ -284,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;
@@ -296,6 +381,8 @@ export class SubscriptionScope<D extends CoValue> {
     return unloadedValue;
   }
 
+  lastErrorLogged: JazzError | undefined;
+
   getCurrentValue(): MaybeLoaded<D> {
     const rawValue = this.getCurrentRawValue();
 
@@ -304,6 +391,7 @@ export class SubscriptionScope<D extends CoValue> {
       rawValue === CoValueLoadingState.UNAVAILABLE ||
       rawValue === CoValueLoadingState.LOADING
     ) {
+      this.logError();
       return this.getUnloadedValue(rawValue);
     }
 
@@ -315,7 +403,6 @@ export class SubscriptionScope<D extends CoValue> {
       this.value.type === CoValueLoadingState.UNAUTHORIZED ||
       this.value.type === CoValueLoadingState.UNAVAILABLE
     ) {
-      console.error(this.value.toString());
       return this.value.type;
     }
 
@@ -324,7 +411,6 @@ export class SubscriptionScope<D extends CoValue> {
     }
 
     if (this.errorFromChildren) {
-      console.error(this.errorFromChildren.toString());
       return this.errorFromChildren.type;
     }
 
@@ -335,6 +421,73 @@ export class SubscriptionScope<D extends CoValue> {
     return CoValueLoadingState.LOADING;
   }
 
+  getCreationStackLines() {
+    const stack = this.callerStack?.stack;
+
+    if (!stack) {
+      return "";
+    }
+
+    const creationStackLines = stack.split("\n").slice(2, 15);
+    const creationAppFrame = creationStackLines.find(
+      (line) =>
+        !line.includes("node_modules") &&
+        !line.includes("useCoValueSubscription") &&
+        !line.includes("useCoState") &&
+        !line.includes("useAccount") &&
+        !line.includes("jazz-tools"),
+    );
+
+    let result = "\n\n";
+
+    if (creationAppFrame) {
+      (result += "Subscription created "), (result += creationAppFrame.trim());
+    }
+
+    result += "\nFull subscription creation stack:";
+    for (const line of creationStackLines.slice(0, 8)) {
+      result += "\n    " + line.trim();
+    }
+
+    return result;
+  }
+
+  getError() {
+    if (
+      this.value.type === CoValueLoadingState.UNAUTHORIZED ||
+      this.value.type === CoValueLoadingState.UNAVAILABLE
+    ) {
+      return this.value;
+    }
+
+    if (this.errorFromChildren) {
+      return this.errorFromChildren;
+    }
+  }
+
+  logError() {
+    const error = this.getError();
+
+    if (!error || this.lastErrorLogged === error) {
+      return;
+    }
+
+    if (error.type === CoValueLoadingState.UNAVAILABLE && this.skipRetry) {
+      return;
+    }
+
+    this.lastErrorLogged = error;
+
+    if (isCustomErrorReportingEnabled()) {
+      captureError(new Error(error.toString(), { cause: this.callerStack }), {
+        getPrettyStackTrace: () => this.getCreationStackLines(),
+        jazzError: error,
+      });
+    } else {
+      console.error(`${error.toString()}${this.getCreationStackLines()}`);
+    }
+  }
+
   triggerUpdate() {
     if (!this.shouldSendUpdates()) return;
     if (!this.dirty) return;
@@ -354,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();
   }
 
@@ -577,7 +759,7 @@ export class SubscriptionScope<D extends CoValue> {
                   new JazzError(undefined, CoValueLoadingState.UNAVAILABLE, [
                     {
                       code: "validationError",
-                      message: `The ref on position ${key} requested on ${stream.constructor.name} is missing`,
+                      message: `Jazz Validation Error: The ref on position ${key} is missing`,
                       params: {},
                       path: [key],
                     },
@@ -642,7 +824,7 @@ export class SubscriptionScope<D extends CoValue> {
           new JazzError(undefined, CoValueLoadingState.UNAVAILABLE, [
             {
               code: "validationError",
-              message: `The ref ${key} requested on ${map.constructor.name} is missing`,
+              message: `Jazz Validation Error: The ref ${key} is required but missing`,
               params: {},
               path: [key],
             },
@@ -681,7 +863,7 @@ export class SubscriptionScope<D extends CoValue> {
         new JazzError(undefined, CoValueLoadingState.UNAVAILABLE, [
           {
             code: "validationError",
-            message: `The ref on position ${key} requested on ${list.constructor.name} is missing`,
+            message: `Jazz Validation Error: The ref on position ${key} is required but missing`,
             params: {},
             path: [key],
           },
@@ -752,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/errorReporting.ts

@@ -0,0 +1,67 @@
+import type { JazzError } from "./JazzError";
+
+/**
+ * A platform agnostic way to check if we're in development mode
+ *
+ * Works in Node.js and bundled code, falls back to false if process is not available
+ */
+const isDev = (function () {
+  try {
+    return process.env.NODE_ENV === "development";
+  } catch {
+    return false;
+  }
+})();
+
+type CustomErrorReporterProps = {
+  getPrettyStackTrace: () => string;
+  jazzError: JazzError;
+};
+
+type CustomErrorReporter = (
+  error: Error,
+  props: CustomErrorReporterProps,
+) => void;
+
+let customErrorReporter: CustomErrorReporter | undefined;
+let captureErrorCause: boolean = isDev;
+
+/**
+ * Turns on the additonal debug info coming from React hooks on the original subscription of the errors.
+ *
+ * Enabled by default in development mode.
+ */
+export function enableCaptureErrorCause(capture: boolean) {
+  captureErrorCause = capture;
+}
+
+/**
+ * Set a custom error reporter to be used instead of the default console.error.
+ *
+ * Useful for sending errors to a logging service or silence some annoying errors in production.
+ */
+export function setCustomErrorReporter(reporter?: CustomErrorReporter) {
+  customErrorReporter = reporter;
+}
+
+/**
+ * Check if we're in development mode.
+ * Stack traces are only captured in development to avoid overhead in production.
+ */
+export function isCustomErrorReportingEnabled(): boolean {
+  return customErrorReporter !== undefined;
+}
+
+/**
+ * Capture a stack trace only in development mode.
+ * Returns undefined in production to avoid overhead.
+ */
+export function captureStack() {
+  return captureErrorCause ? new Error() : undefined;
+}
+
+export function captureError(error: Error, props: CustomErrorReporterProps) {
+  if (customErrorReporter) {
+    customErrorReporter(error, props);
+  }
+}