jazz-tools 0.20.1 → 0.20.3

package/src/react-core/hooks.ts

@@ -101,6 +101,7 @@ export function useCoValueSubscription<
     resolve?: ResolveQueryStrict<S, R>;
     unstable_branch?: BranchDefinition;
   },
+  source?: string,
 ): CoValueSubscription<S, R> | null {
   const resolve = getResolveQuery(Schema, options?.resolve);
   const subscriptions = useCoValueSubscriptions(
@@ -108,6 +109,7 @@ export function useCoValueSubscription<
     [id],
     resolve,
     options?.unstable_branch,
+    source,
   );
   return (subscriptions[0] ?? null) as CoValueSubscription<S, R> | null;
 }
@@ -140,6 +142,7 @@ function useCoValueSubscriptions(
   ids: readonly (string | undefined | null)[],
   resolve: ResolveQuery<any>,
   branch?: BranchDefinition,
+  source?: string,
 ): (SubscriptionScope<CoValue> | null)[] {
   const contextManager = useJazzContext();
   const agent = useAgent();
@@ -169,6 +172,9 @@ function useCoValueSubscriptions(
         subscription.callerStack = callerStack;
       }
 
+      // Track performance for root subscriptions
+      subscription.trackLoadingPerformance(source ?? "unknown");
+
       return subscription;
     });
 
@@ -428,7 +434,12 @@ export function useCoState<
   },
 ): TSelectorReturn {
   useImportCoValueContent(id, options?.preloaded);
-  const subscription = useCoValueSubscription(Schema, id, options);
+  const subscription = useCoValueSubscription(
+    Schema,
+    id,
+    options,
+    `useCoState`,
+  );
   return useSubscriptionSelector(subscription, options);
 }
 
@@ -471,7 +482,12 @@ export function useSuspenseCoState<
 ): TSelectorReturn {
   useImportCoValueContent(id, options?.preloaded);
 
-  const subscription = useCoValueSubscription(Schema, id, options);
+  const subscription = useCoValueSubscription(
+    Schema,
+    id,
+    options,
+    "useSuspenseCoState",
+  );
 
   if (!subscription) {
     throw new Error("Subscription not found");
@@ -534,6 +550,7 @@ export function useAccountSubscription<
     resolve?: ResolveQueryStrict<S, R>;
     unstable_branch?: BranchDefinition;
   },
+  source?: string,
 ) {
   const contextManager = useJazzContext();
 
@@ -570,6 +587,9 @@ export function useAccountSubscription<
       subscription.callerStack = callerStack;
     }
 
+    // Track performance for root subscriptions
+    subscription.trackLoadingPerformance(source ?? "unknown");
+
     return {
       subscription,
       contextManager,
@@ -727,7 +747,11 @@ export function useAccount<
     unstable_branch?: BranchDefinition;
   },
 ): TSelectorReturn {
-  const subscription = useAccountSubscription(AccountSchema, options);
+  const subscription = useAccountSubscription(
+    AccountSchema,
+    options,
+    "useAccount",
+  );
   return useSubscriptionSelector(subscription, options);
 }
 
@@ -765,7 +789,11 @@ export function useSuspenseAccount<
     unstable_branch?: BranchDefinition;
   },
 ): TSelectorReturn {
-  const subscription = useAccountSubscription(AccountSchema, options);
+  const subscription = useAccountSubscription(
+    AccountSchema,
+    options,
+    "useSuspenseAccount",
+  );
 
   if (!subscription) {
     throw new Error(
@@ -1054,6 +1082,7 @@ export function useSuspenseCoStates<
     ids,
     resolve,
     options?.unstable_branch,
+    "useSuspenseCoStates",
   ) as SubscriptionScope<CoValue>[];
   useSuspendUntilLoaded(subscriptionScopes);
   return useSubscriptionsSelector(subscriptionScopes, options);
@@ -1123,6 +1152,7 @@ export function useCoStates<
     ids,
     resolve,
     options?.unstable_branch,
+    "useCoStates",
   ) as SubscriptionScope<CoValue>[];
   return useSubscriptionsSelector(subscriptionScopes, options);
 }

package/src/react-core/subscription-provider.tsx

@@ -39,10 +39,15 @@ export function createCoValueSubscriptionContext<
       loadingFallback?: React.ReactNode;
       unavailableFallback?: React.ReactNode;
     }>) => {
-      const subscription = useCoValueSubscription(schema, id, {
-        ...options,
-        resolve: resolve,
-      });
+      const subscription = useCoValueSubscription(
+        schema,
+        id,
+        {
+          ...options,
+          resolve: resolve,
+        },
+        "CoValueSubscriptionProvider",
+      );
 
       const loadState = useSubscriptionSelector(subscription, {
         select: (value) => value.$jazz.loadingState,
@@ -104,10 +109,14 @@ export function createAccountSubscriptionContext<
       loadingFallback?: React.ReactNode;
       unavailableFallback?: React.ReactNode;
     }>) => {
-      const subscription = useAccountSubscription(schema, {
-        ...options,
-        resolve: resolve,
-      });
+      const subscription = useAccountSubscription(
+        schema,
+        {
+          ...options,
+          resolve: resolve,
+        },
+        "AccountSubscriptionProvider",
+      );
 
       const loadState = useSubscriptionSelector(subscription, {
         select: (value) => value.$jazz.loadingState,

package/src/svelte/jazz.class.svelte.ts

@@ -4,6 +4,7 @@ import type {
   AnyAccountSchema,
   BranchDefinition,
   CoValue,
+  CoValueClass,
   CoValueClassOrSchema,
   CoValueFromRaw,
   SchemaResolveQuery,
@@ -15,10 +16,11 @@ import type {
   ResolveQueryStrict,
 } from "jazz-tools";
 import {
+  captureStack,
   coValueClassFromCoValueClassOrSchema,
-  subscribeToCoValue,
   CoValueLoadingState,
   getUnloadedCoValueWithoutId,
+  SubscriptionScope,
 } from "jazz-tools";
 import { untrack } from "svelte";
 import { createSubscriber } from "svelte/reactivity";
@@ -69,6 +71,7 @@ export class CoState<
     id: CoStateId | (() => CoStateId),
     options?: CoStateOptions<V, R> | (() => CoStateOptions<V, R>),
   ) {
+    const callerStack = captureStack();
     this.#id = $derived.by(typeof id === "function" ? id : () => id);
     this.#options = $derived.by(
       typeof options === "function" ? options : () => options,
@@ -89,29 +92,36 @@ export class CoState<
             getUnloadedCoValueWithoutId(CoValueLoadingState.UNAVAILABLE),
           );
         }
+
         const agent = "me" in ctx ? ctx.me : ctx.guest;
+        const node = "node" in agent ? agent.node : agent.$jazz.localNode;
         const resolve = getResolveQuery(Schema, options?.resolve);
+        const cls = coValueClassFromCoValueClassOrSchema(Schema) as CoValueClass<Loaded<V, R>>;
 
-        const unsubscribe = subscribeToCoValue(
-          coValueClassFromCoValueClassOrSchema(Schema),
+        const subscriptionScope = new SubscriptionScope<Loaded<V, R>>(
+          node,
+          resolve,
           id,
-          {
-            // @ts-expect-error The resolve query type isn't compatible with the coValueClassFromCoValueClassOrSchema conversion
-            resolve,
-            loadAs: agent,
-            onError: (value) => {
-              this.update(value);
-            },
-            syncResolution: true,
-            unstable_branch: options?.unstable_branch,
-          },
-          (value) => {
-            this.update(value as Loaded<V, R>);
-          },
+          { ref: cls, optional: false },
+          false, // skipRetry
+          false, // bestEffortResolution
+          options?.unstable_branch,
         );
 
+        subscriptionScope.callerStack = callerStack;
+
+        // Track performance for Svelte subscriptions
+        subscriptionScope.trackLoadingPerformance("CoState");
+
+        subscriptionScope.subscribe(() => {
+          const value = subscriptionScope.getCurrentValue();
+          this.update(value);
+        });
+
+        this.update(subscriptionScope.getCurrentValue());
+
         return () => {
-          unsubscribe();
+          subscriptionScope.destroy();
         };
       });
     });
@@ -150,6 +160,7 @@ export class AccountCoState<
     Schema: A,
     options?: CoStateOptions<A, R> | (() => CoStateOptions<A, R>),
   ) {
+    const callerStack = captureStack();
     this.#options = $derived.by(
       typeof options === "function" ? options : () => options,
     );
@@ -170,27 +181,34 @@ export class AccountCoState<
         }
 
         const me = ctx.me;
+        const node = me.$jazz.localNode;
         const resolve = getResolveQuery(Schema, options?.resolve);
-
-        const unsubscribe = subscribeToCoValue(
-          coValueClassFromCoValueClassOrSchema(Schema),
+        const cls = coValueClassFromCoValueClassOrSchema(Schema) as CoValueClass<Loaded<A, R>>;
+ 
+        const subscriptionScope = new SubscriptionScope<Loaded<A, R>>(
+          node,
+          resolve,
           me.$jazz.id,
-          {
-            resolve,
-            loadAs: me,
-            onError: (value) => {
-              this.update(value);
-            },
-            syncResolution: true,
-            unstable_branch: options?.unstable_branch,
-          },
-          (value) => {
-            this.update(value as Loaded<A, R>);
-          },
+          { ref: cls, optional: false },
+          false, // skipRetry
+          false, // bestEffortResolution
+          options?.unstable_branch,
         );
 
+        subscriptionScope.callerStack = callerStack;
+
+        // Track performance for Svelte subscriptions
+        subscriptionScope.trackLoadingPerformance("AccountCoState");
+
+        subscriptionScope.subscribe(() => {
+          const value = subscriptionScope.getCurrentValue();
+          this.update(value);
+        });
+
+        this.update(subscriptionScope.getCurrentValue());
+
         return () => {
-          unsubscribe();
+          subscriptionScope.destroy();
         };
       });
     });

package/src/tools/coValues/interfaces.ts

@@ -349,6 +349,9 @@ export function subscribeToCoValue<
     options.unstable_branch,
   );
 
+  // Track performance for API subscriptions
+  rootNode.trackLoadingPerformance("subscribe");
+
   const handleUpdate = () => {
     if (unsubscribed) return;
 

package/src/tools/exports.ts

@@ -41,6 +41,7 @@ export type {
   AccountCreationProps,
   BaseProfileShape,
   ExportedCoValue,
+  SubscriptionPerformanceDetail,
 } from "./internal.js";
 
 export {

package/src/tools/implementation/zodSchema/runtimeConverters/coValueSchemaTransformation.ts

@@ -39,6 +39,19 @@ import {
   schemaFieldToCoFieldDef,
 } from "./schemaFieldToCoFieldDef.js";
 
+/**
+ * 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;
+  }
+})();
+
 // Note: if you're editing this function, edit the `isAnyCoValueSchema`
 // function in `zodReExport.ts` as well
 export function isAnyCoValueSchema(

package/src/tools/subscribe/SubscriptionCache.ts

@@ -2,6 +2,7 @@ import { LocalNode } from "cojson";
 import type {
   CoValue,
   CoValueClassOrSchema,
+  Loaded,
   RefEncoded,
   RefsToResolve,
   ResolveQuery,
@@ -188,7 +189,7 @@ export class SubscriptionCache {
     skipRetry?: boolean,
     bestEffortResolution?: boolean,
     branch?: BranchDefinition,
-  ): SubscriptionScope<CoValue> {
+  ): SubscriptionScope<Loaded<S, ResolveQuery<S>>> {
     // Handle undefined/null id case
     if (!id) {
       throw new Error("Cannot create subscription with undefined or null id");
@@ -201,7 +202,9 @@ export class SubscriptionCache {
       // Found existing entry - cancel any pending cleanup since we're reusing it
       this.cancelCleanup(matchingEntry);
 
-      return matchingEntry.subscriptionScope as SubscriptionScope<CoValue>;
+      return matchingEntry.subscriptionScope as SubscriptionScope<
+        Loaded<S, ResolveQuery<S>>
+      >;
     }
 
     // Create new SubscriptionScope
@@ -212,9 +215,8 @@ export class SubscriptionCache {
     };
 
     // Create new SubscriptionScope with all required parameters
-    const subscriptionScope = new SubscriptionScope<CoValue>(
+    const subscriptionScope = new SubscriptionScope<Loaded<S, ResolveQuery<S>>>(
       node,
-      // @ts-expect-error the SubscriptionScope is too generic for TS to infer its instances are CoValues
       resolve,
       id,
       refEncoded,

package/src/tools/subscribe/SubscriptionScope.ts

@@ -4,7 +4,6 @@ import {
   CoList,
   CoMap,
   type CoValue,
-  type ID,
   MaybeLoaded,
   NotLoaded,
   type RefEncoded,
@@ -23,6 +22,7 @@ import {
 } from "./JazzError.js";
 import type {
   BranchDefinition,
+  SubscriptionPerformanceDetail,
   SubscriptionValue,
   SubscriptionValueLoading,
 } from "./types.js";
@@ -30,6 +30,7 @@ import { CoValueLoadingState, NotLoadedCoValueState } from "./types.js";
 import {
   captureError,
   isCustomErrorReportingEnabled,
+  isDev,
 } from "./errorReporting.js";
 import {
   createCoValue,
@@ -40,11 +41,21 @@ import {
 } from "./utils.js";
 
 export class SubscriptionScope<D extends CoValue> {
+  static isProfilingEnabled = isDev;
+
+  static setProfilingEnabled(enabled: boolean) {
+    this.isProfilingEnabled = enabled;
+  }
+
+  static enableProfiling() {
+    this.isProfilingEnabled = true;
+  }
+
+  private performanceUuid: string | undefined;
+  private performanceSource: string | undefined;
+
   childNodes = new Map<string, SubscriptionScope<CoValue>>();
-  childValues: Map<string, SubscriptionValue<any, any>> = new Map<
-    string,
-    SubscriptionValue<D, any>
-  >();
+  childValues: Map<string, SubscriptionValue<CoValue>> = new Map();
   /**
    * Explicitly-loaded child ids that are unloaded
    */
@@ -53,7 +64,7 @@ export class SubscriptionScope<D extends CoValue> {
    * Autoloaded child ids that are unloaded
    */
   private pendingAutoloadedChildren: Set<string> = new Set();
-  value: SubscriptionValue<D, any> | SubscriptionValueLoading;
+  value: SubscriptionValue<D> | SubscriptionValueLoading;
   private childErrors: Map<string, JazzError> = new Map();
   private validationErrors: Map<string, JazzError> = new Map();
   errorFromChildren: JazzError | undefined;
@@ -81,9 +92,9 @@ export class SubscriptionScope<D extends CoValue> {
 
   constructor(
     public node: LocalNode,
-    resolve: RefsToResolve<D>,
-    public id: ID<D>,
-    public schema: RefEncoded<D>,
+    resolve: RefsToResolve<any>,
+    public id: string,
+    public schema: RefEncoded<CoValue>,
     public skipRetry = false,
     public bestEffortResolution = false,
     public unstable_branch?: BranchDefinition,
@@ -141,7 +152,110 @@ export class SubscriptionScope<D extends CoValue> {
     );
   }
 
-  updateValue(value: SubscriptionValue<D, any>) {
+  trackLoadingPerformance(source: string) {
+    if (!SubscriptionScope.isProfilingEnabled) {
+      return;
+    }
+
+    // Already tracking this subscription
+    if (this.performanceUuid) {
+      return;
+    }
+
+    const currentState = this.getCurrentRawValue();
+
+    this.performanceUuid = crypto.randomUUID();
+    this.performanceSource = source;
+
+    const detail: SubscriptionPerformanceDetail = {
+      type: "jazz-subscription",
+      uuid: this.performanceUuid,
+      id: this.id,
+      source,
+      resolve: this.resolve,
+      status: "pending",
+      startTime: performance.now(),
+      callerStack: this.callerStack?.stack,
+    };
+
+    performance.mark(`jazz.subscription.start:${this.performanceUuid}`, {
+      detail,
+    });
+
+    if (currentState !== CoValueLoadingState.LOADING) {
+      this.emitLoadingComplete(currentState);
+      return;
+    }
+
+    // Subscribe to get notified when loading completes
+    const unsubscribe = this.subscribe(() => {
+      const rawValue = this.getCurrentRawValue();
+
+      if (rawValue === CoValueLoadingState.LOADING) {
+        return;
+      }
+
+      this.emitLoadingComplete(rawValue);
+      unsubscribe();
+    });
+  }
+
+  private emitLoadingComplete(rawValue: D | NotLoadedCoValueState) {
+    if (!this.performanceUuid) return;
+
+    const isError = typeof rawValue === "string";
+    const endTime = performance.now();
+
+    let errorType: SubscriptionPerformanceDetail["errorType"];
+    if (isError) {
+      if (
+        rawValue === CoValueLoadingState.UNAVAILABLE ||
+        rawValue === CoValueLoadingState.UNAUTHORIZED ||
+        rawValue === CoValueLoadingState.DELETED
+      ) {
+        errorType = rawValue;
+      }
+    }
+
+    const detail: SubscriptionPerformanceDetail = {
+      type: "jazz-subscription",
+      uuid: this.performanceUuid,
+      id: this.id,
+      source: this.performanceSource ?? "unknown",
+      resolve: this.resolve,
+      status: isError ? "error" : "loaded",
+      startTime: 0, // Will be calculated from measure
+      endTime,
+      errorType,
+      devtools: {
+        track: "Jazz 🎶",
+        properties: [
+          ["id", this.id],
+          ["source", this.performanceSource ?? "unknown"],
+        ],
+        tooltipText: this.getCreationStackLines(false),
+      },
+    };
+
+    performance.mark(`jazz.subscription.end:${this.performanceUuid}`, {
+      detail,
+    });
+
+    try {
+      performance.measure(
+        `${detail.source}(${this.id}, ${JSON.stringify(this.resolve)})`,
+        {
+          start: `jazz.subscription.start:${this.performanceUuid}`,
+          end: `jazz.subscription.end:${this.performanceUuid}`,
+          detail,
+        },
+      );
+    } catch {
+      // Marks may have been cleared
+    }
+  }
+
+  updateValue(value: SubscriptionValue<D>) {
     this.value = value;
 
     // Flags that the value has changed and we need to trigger an update
@@ -285,7 +399,7 @@ export class SubscriptionScope<D extends CoValue> {
 
   handleChildUpdate(
     id: string,
-    value: SubscriptionValue<any, any> | SubscriptionValueLoading,
+    value: SubscriptionValue<CoValue> | SubscriptionValueLoading,
     key?: string,
   ) {
     if (value.type === CoValueLoadingState.LOADING) {
@@ -469,7 +583,7 @@ export class SubscriptionScope<D extends CoValue> {
     return CoValueLoadingState.LOADING;
   }
 
-  private getCreationStackLines() {
+  private getCreationStackLines(fullFrame: boolean = true) {
     const stack = this.callerStack?.stack;
 
     if (!stack) {
@@ -492,6 +606,10 @@ export class SubscriptionScope<D extends CoValue> {
       (result += "Subscription created "), (result += creationAppFrame.trim());
     }
 
+    if (!fullFrame) {
+      return result;
+    }
+
     result += "\nFull subscription creation stack:";
     for (const line of creationStackLines.slice(0, 8)) {
       result += "\n    " + line.trim();
@@ -555,7 +673,7 @@ export class SubscriptionScope<D extends CoValue> {
     this.dirty = false;
   }
 
-  subscribers = new Set<(value: SubscriptionValue<D, any>) => void>();
+  subscribers = new Set<(value: SubscriptionValue<D>) => void>();
   subscriberChangeCallbacks = new Set<(count: number) => void>();
 
   /**
@@ -578,7 +696,7 @@ export class SubscriptionScope<D extends CoValue> {
     });
   }
 
-  subscribe(listener: (value: SubscriptionValue<D, any>) => void) {
+  subscribe(listener: (value: SubscriptionValue<D>) => void) {
     this.subscribers.add(listener);
     this.notifySubscriberChange();
 
@@ -588,7 +706,7 @@ export class SubscriptionScope<D extends CoValue> {
     };
   }
 
-  setListener(listener: (value: SubscriptionValue<D, any>) => void) {
+  setListener(listener: (value: SubscriptionValue<D>) => void) {
     const hadListener = this.subscribers.has(listener);
     this.subscribers.add(listener);
     // Only notify if this is a new listener (count actually changed)
@@ -624,11 +742,11 @@ export class SubscriptionScope<D extends CoValue> {
     this.silenceUpdates = true;
 
     if (value[TypeSym] === "CoMap" || value[TypeSym] === "Account") {
-      const map = value as CoMap;
+      const map = value as unknown as CoMap;
 
       this.loadCoMapKey(map, key, true);
     } else if (value[TypeSym] === "CoList") {
-      const list = value as CoList;
+      const list = value as unknown as CoList;
 
       this.loadCoListKey(list, key, true);
     }
@@ -650,7 +768,7 @@ export class SubscriptionScope<D extends CoValue> {
    *
    * Used to make the autoload work on closed subscription scopes
    */
-  pullValue(listener: (value: SubscriptionValue<D, any>) => void) {
+  pullValue(listener: (value: SubscriptionValue<D>) => void) {
     if (!this.closed) {
       throw new Error("Cannot pull a non-closed subscription scope");
     }
@@ -707,7 +825,7 @@ export class SubscriptionScope<D extends CoValue> {
     const child = new SubscriptionScope(
       this.node,
       true,
-      id as ID<any>,
+      id,
       descriptor,
       this.skipRetry,
       this.bestEffortResolution,
@@ -751,7 +869,7 @@ export class SubscriptionScope<D extends CoValue> {
         coValueType === "Account" ||
         coValueType === "Group"
       ) {
-        const map = value as CoMap;
+        const map = value as unknown as CoMap;
         const keys =
           "$each" in depth ? map.$jazz.raw.keys() : Object.keys(depth);
 
@@ -763,7 +881,7 @@ export class SubscriptionScope<D extends CoValue> {
           }
         }
       } else if (value[TypeSym] === "CoList") {
-        const list = value as CoList;
+        const list = value as unknown as CoList;
 
         const descriptor = list.$jazz.getItemsDescriptor();
 
@@ -782,7 +900,7 @@ export class SubscriptionScope<D extends CoValue> {
           }
         }
       } else if (value[TypeSym] === "CoStream") {
-        const stream = value as CoFeed;
+        const stream = value as unknown as CoFeed;
         const descriptor = stream.$jazz.getItemsDescriptor();
 
         if (descriptor && isRefEncoded(descriptor)) {
@@ -969,7 +1087,7 @@ export class SubscriptionScope<D extends CoValue> {
     const child = new SubscriptionScope(
       this.node,
       resolve,
-      id as ID<any>,
+      id,
       descriptor,
       this.skipRetry,
       this.bestEffortResolution,

package/src/tools/subscribe/errorReporting.ts

@@ -5,7 +5,7 @@ import type { JazzError } from "./JazzError";
  *
  * Works in Node.js and bundled code, falls back to false if process is not available
  */
-const isDev = (function () {
+export const isDev = (function () {
   try {
     return process.env.NODE_ENV === "development";
   } catch {

package/src/tools/subscribe/index.ts

@@ -100,7 +100,7 @@ export function accessChildById<D extends CoValue>(
 
   // TODO: this doesn't check the subscription tree loading state
   if (value?.type === CoValueLoadingState.LOADED) {
-    return value.value;
+    return value.value as D;
   }
 
   const childNode = subscriptionScope.childNodes.get(childId);