jazz-tools 0.20.0 → 0.20.2

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/coList.ts

@@ -549,7 +549,7 @@ export class CoListJazzApi<L extends CoList> extends CoValueJazzApi<L> {
       "private",
     );
 
-    return this.raw.entries().length;
+    return this.raw.length();
   }
 
   /**
@@ -567,7 +567,7 @@ export class CoListJazzApi<L extends CoList> extends CoValueJazzApi<L> {
       this.raw.prepend(item);
     }
 
-    return this.raw.entries().length;
+    return this.raw.length();
   }
 
   /**
@@ -936,40 +936,65 @@ function toRawItems<Item>(
   return rawItems;
 }
 
+function getCoListItemValue(target: CoList, key: string) {
+  const rawValue = target.$jazz.raw.get(Number(key));
+
+  if (rawValue === undefined) {
+    return undefined;
+  }
+
+  const itemDescriptor: Schema = target.$jazz.schema[ItemsSym];
+
+  if (itemDescriptor === "json") {
+    return rawValue;
+  } else if ("encoded" in itemDescriptor) {
+    return itemDescriptor.encoded.decode(rawValue);
+  } else if (isRefEncoded(itemDescriptor)) {
+    if (rawValue === null) {
+      return undefined;
+    }
+
+    return accessChildByKey(target, rawValue as string, key);
+  }
+
+  return undefined;
+}
+
 const CoListProxyHandler: ProxyHandler<CoList> = {
   get(target, key, receiver) {
-    if (typeof key === "string" && !isNaN(+key)) {
-      const itemDescriptor = target.$jazz.schema[ItemsSym] as Schema;
-      const rawValue = target.$jazz.raw.get(Number(key));
-      if (itemDescriptor === "json") {
-        return rawValue;
-      } else if ("encoded" in itemDescriptor) {
-        return rawValue === undefined
-          ? undefined
-          : itemDescriptor.encoded.decode(rawValue);
-      } else if (isRefEncoded(itemDescriptor)) {
-        return rawValue === undefined || rawValue === null
-          ? undefined
-          : accessChildByKey(target, rawValue as string, key);
-      }
-    } else if (key === "length") {
-      return target.$jazz.raw.entries().length;
-    } else {
+    if (typeof key === "symbol") {
       return Reflect.get(target, key, receiver);
     }
+
+    if (!isNaN(+key)) {
+      return getCoListItemValue(target, key);
+    } else if (key === "length") {
+      return target.$jazz.raw.length();
+    }
+
+    return Reflect.get(target, key, receiver);
   },
   set(target, key, value, receiver) {
+    if (typeof key === "symbol") {
+      return Reflect.set(target, key, value, receiver);
+    }
+
     if (key === ItemsSym && typeof value === "object" && SchemaInit in value) {
-      (target.constructor as typeof CoList)._schema ||= {};
-      (target.constructor as typeof CoList)._schema[ItemsSym] =
-        value[SchemaInit];
+      const constructor = target.constructor as typeof CoList;
+
+      if (!constructor._schema) {
+        constructor._schema = {};
+      }
+
+      constructor._schema[ItemsSym] = value[SchemaInit];
       return true;
     }
-    if (typeof key === "string" && !isNaN(+key)) {
+
+    if (!isNaN(+key)) {
       throw Error("Cannot update a CoList directly. Use `$jazz.set` instead.");
-    } else {
-      return Reflect.set(target, key, value, receiver);
     }
+
+    return Reflect.set(target, key, value, receiver);
   },
   defineProperty(target, key, descriptor) {
     if (
@@ -978,9 +1003,13 @@ const CoListProxyHandler: ProxyHandler<CoList> = {
       typeof descriptor.value === "object" &&
       SchemaInit in descriptor.value
     ) {
-      (target.constructor as typeof CoList)._schema ||= {};
-      (target.constructor as typeof CoList)._schema[ItemsSym] =
-        descriptor.value[SchemaInit];
+      const constructor = target.constructor as typeof CoList;
+
+      if (!constructor._schema) {
+        constructor._schema = {};
+      }
+
+      constructor._schema[ItemsSym] = descriptor.value[SchemaInit];
       return true;
     } else {
       return Reflect.defineProperty(target, key, descriptor);
@@ -988,7 +1017,7 @@ const CoListProxyHandler: ProxyHandler<CoList> = {
   },
   has(target, key) {
     if (typeof key === "string" && !isNaN(+key)) {
-      return Number(key) < target.$jazz.raw.entries().length;
+      return Number(key) < target.$jazz.raw.length();
     } else {
       return Reflect.has(target, key);
     }
@@ -996,11 +1025,17 @@ const CoListProxyHandler: ProxyHandler<CoList> = {
   ownKeys(target) {
     const keys = Reflect.ownKeys(target);
     // Add numeric indices for all entries in the list
-    const indexKeys = target.$jazz.raw.entries().map((_entry, i) => String(i));
-    keys.push(...indexKeys);
+    const length = target.$jazz.raw.length();
+    for (let i = 0; i < length; i++) {
+      keys.push(String(i));
+    }
     return keys;
   },
   getOwnPropertyDescriptor(target, key) {
+    if (typeof key === "symbol") {
+      return Reflect.getOwnPropertyDescriptor(target, key);
+    }
+
     if (key === TypeSym) {
       // Make TypeSym non-enumerable so it doesn't show up in Object.keys()
       return {
@@ -1009,23 +1044,24 @@ const CoListProxyHandler: ProxyHandler<CoList> = {
         writable: false,
         value: target[TypeSym],
       };
-    } else if (key in target) {
-      return Reflect.getOwnPropertyDescriptor(target, key);
-    } else if (typeof key === "string" && !isNaN(+key)) {
+    } else if (!isNaN(+key)) {
       const index = Number(key);
-      if (index >= 0 && index < target.$jazz.raw.entries().length) {
+      if (index >= 0 && index < target.$jazz.raw.length()) {
         return {
           enumerable: true,
           configurable: true,
-          writable: true,
+          writable: false,
+          value: getCoListItemValue(target, key),
         };
       }
     } else if (key === "length") {
       return {
         enumerable: false,
         configurable: false,
-        writable: false,
+        writable: true, // Must be writable, otherwise JS complains
+        value: target.$jazz.raw.length(),
       };
     }
+    return Reflect.getOwnPropertyDescriptor(target, key);
   },
 };

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/implementation/zodSchema/schemaTypes/AccountSchema.ts

@@ -1,6 +1,5 @@
 import {
   Account,
-  AccountCreationProps,
   BranchDefinition,
   CoMapSchemaDefinition,
   coOptionalDefiner,
@@ -16,7 +15,6 @@ import {
 } from "../../../internal.js";
 import { AnonymousJazzAgent } from "../../anonymousJazzAgent.js";
 import { InstanceOrPrimitiveOfSchema } from "../typeConverters/InstanceOrPrimitiveOfSchema.js";
-import { InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded } from "../typeConverters/InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded.js";
 import { z } from "../zodReExport.js";
 import { AnyZodOrCoValueSchema, Loaded, ResolveQuery } from "../zodSchema.js";
 import {

package/src/tools/implementation/zodSchema/schemaTypes/CoFeedSchema.ts

@@ -42,11 +42,14 @@ export class CoFeedSchema<
    */
   resolveQuery: DefaultResolveQuery = true as DefaultResolveQuery;
 
+  #permissions: SchemaPermissions | null = null;
   /**
    * Permissions to be used when creating or composing CoValues
    * @internal
    */
-  permissions: SchemaPermissions = DEFAULT_SCHEMA_PERMISSIONS;
+  get permissions(): SchemaPermissions {
+    return this.#permissions ?? DEFAULT_SCHEMA_PERMISSIONS;
+  }
 
   constructor(
     public element: T,
@@ -209,7 +212,7 @@ export class CoFeedSchema<
       hydrateCoreCoValueSchema(coreSchema);
     // @ts-expect-error TS cannot infer that the resolveQuery type is valid
     copy.resolveQuery = resolveQuery ?? this.resolveQuery;
-    copy.permissions = permissions ?? this.permissions;
+    copy.#permissions = permissions ?? this.#permissions;
     return copy;
   }
 }

package/src/tools/implementation/zodSchema/schemaTypes/CoListSchema.ts

@@ -44,11 +44,14 @@ export class CoListSchema<
    */
   resolveQuery: DefaultResolveQuery = true as DefaultResolveQuery;
 
+  #permissions: SchemaPermissions | null = null;
   /**
    * Permissions to be used when creating or composing CoValues
    * @internal
    */
-  permissions: SchemaPermissions = DEFAULT_SCHEMA_PERMISSIONS;
+  get permissions(): SchemaPermissions {
+    return this.#permissions ?? DEFAULT_SCHEMA_PERMISSIONS;
+  }
 
   constructor(
     public element: T,
@@ -262,7 +265,7 @@ export class CoListSchema<
       hydrateCoreCoValueSchema(coreSchema);
     // @ts-expect-error TS cannot infer that the resolveQuery type is valid
     copy.resolveQuery = resolveQuery ?? this.resolveQuery;
-    copy.permissions = permissions ?? this.permissions;
+    copy.#permissions = permissions ?? this.#permissions;
     return copy;
   }
 }

package/src/tools/implementation/zodSchema/schemaTypes/CoMapSchema.ts

@@ -59,11 +59,14 @@ export class CoMapSchema<
    */
   resolveQuery: DefaultResolveQuery = true as DefaultResolveQuery;
 
+  #permissions: SchemaPermissions | null = null;
   /**
    * Permissions to be used when creating or composing CoValues
    * @internal
    */
-  permissions: SchemaPermissions = DEFAULT_SCHEMA_PERMISSIONS;
+  get permissions(): SchemaPermissions {
+    return this.#permissions ?? DEFAULT_SCHEMA_PERMISSIONS;
+  }
 
   constructor(
     coreSchema: CoreCoMapSchema<Shape, CatchAll>,
@@ -406,7 +409,7 @@ export class CoMapSchema<
     copy.coValueClass.prototype.migrate = this.coValueClass.prototype.migrate;
     // @ts-expect-error TS cannot infer that the resolveQuery type is valid
     copy.resolveQuery = resolveQuery ?? this.resolveQuery;
-    copy.permissions = permissions ?? this.permissions;
+    copy.#permissions = permissions ?? this.#permissions;
     return copy;
   }
 }

package/src/tools/implementation/zodSchema/schemaTypes/CoVectorSchema.ts

@@ -36,10 +36,14 @@ export class CoVectorSchema implements CoreCoVectorSchema {
   readonly builtin = "CoVector" as const;
   readonly resolveQuery = true as const;
 
+  #permissions: SchemaPermissions | null = null;
   /**
    * Permissions to be used when creating or composing CoValues
+   * @internal
    */
-  permissions: SchemaPermissions = DEFAULT_SCHEMA_PERMISSIONS;
+  get permissions(): SchemaPermissions {
+    return this.#permissions ?? DEFAULT_SCHEMA_PERMISSIONS;
+  }
 
   constructor(
     public dimensions: number,
@@ -119,7 +123,7 @@ export class CoVectorSchema implements CoreCoVectorSchema {
    */
   withPermissions(permissions: SchemaPermissions): CoVectorSchema {
     const copy = new CoVectorSchema(this.dimensions, this.coValueClass);
-    copy.permissions = permissions;
+    copy.#permissions = permissions;
     return copy;
   }
 }

package/src/tools/implementation/zodSchema/schemaTypes/FileStreamSchema.ts

@@ -32,10 +32,14 @@ export class FileStreamSchema implements CoreFileStreamSchema {
   readonly builtin = "FileStream" as const;
   readonly resolveQuery = true as const;
 
+  #permissions: SchemaPermissions | null = null;
   /**
    * Permissions to be used when creating or composing CoValues
+   * @internal
    */
-  permissions: SchemaPermissions = DEFAULT_SCHEMA_PERMISSIONS;
+  get permissions(): SchemaPermissions {
+    return this.#permissions ?? DEFAULT_SCHEMA_PERMISSIONS;
+  }
 
   constructor(private coValueClass: typeof FileStream) {}
 
@@ -159,7 +163,7 @@ export class FileStreamSchema implements CoreFileStreamSchema {
     permissions: Omit<SchemaPermissions, "onInlineCreate">,
   ): FileStreamSchema {
     const copy = new FileStreamSchema(this.coValueClass);
-    copy.permissions = permissions;
+    copy.#permissions = permissions;
     return copy;
   }
 }

package/src/tools/implementation/zodSchema/schemaTypes/PlainTextSchema.ts

@@ -34,11 +34,14 @@ export class PlainTextSchema implements CorePlainTextSchema {
   readonly builtin = "CoPlainText" as const;
   readonly resolveQuery = true as const;
 
+  #permissions: SchemaPermissions | null = null;
   /**
    * Permissions to be used when creating or composing CoValues
    * @internal
    */
-  permissions: SchemaPermissions = DEFAULT_SCHEMA_PERMISSIONS;
+  get permissions(): SchemaPermissions {
+    return this.#permissions ?? DEFAULT_SCHEMA_PERMISSIONS;
+  }
 
   constructor(private coValueClass: typeof CoPlainText) {}
 
@@ -111,7 +114,7 @@ export class PlainTextSchema implements CorePlainTextSchema {
    */
   withPermissions(permissions: SchemaPermissions): PlainTextSchema {
     const copy = new PlainTextSchema(this.coValueClass);
-    copy.permissions = permissions;
+    copy.#permissions = permissions;
     return copy;
   }
 }