jazz-tools 0.20.0 → 0.20.2

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

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

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

package/src/tools/subscribe/types.ts

@@ -1,10 +1,4 @@
-import type {
-  Account,
-  CoValue,
-  Group,
-  RefsToResolve,
-  Resolved,
-} from "../internal.js";
+import type { Account, CoValue, Group, Resolved } from "../internal.js";
 import type { JazzError } from "./JazzError.js";
 
 export const CoValueLoadingState = {
@@ -42,10 +36,10 @@ export type NotLoadedCoValueState =
   | typeof CoValueLoadingState.LOADING
   | CoValueErrorState;
 
-export type SubscriptionValue<D extends CoValue, R extends RefsToResolve<D>> =
+export type SubscriptionValue<D> =
   | {
       type: typeof CoValueLoadingState.LOADED;
-      value: Resolved<D, R>;
+      value: D;
       id: string;
     }
   | JazzError;
@@ -55,3 +49,62 @@ export type SubscriptionValueLoading = {
 };
 
 export type BranchDefinition = { name: string; owner?: Group | Account };
+
+/**
+ * Detail structure for subscription performance marks and measures.
+ * Used by SubscriptionScope.trackLoadingPerformance() to emit performance data.
+ */
+export interface SubscriptionPerformanceDetail {
+  /** Type of performance entry */
+  type: "jazz-subscription";
+  /** Unique identifier for this subscription instance */
+  uuid: string;
+  /** CoValue ID (e.g., "co_z1234...") */
+  id: string;
+  /** Source identifier (hook name or API) */
+  source: string;
+  /** The resolve query object */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  resolve: any;
+  /** Current status of the subscription */
+  status: "pending" | "loaded" | "error";
+  /** When the subscription started loading (DOMHighResTimeStamp) */
+  startTime: number;
+  /** When loading completed (if completed) */
+  endTime?: number;
+  /** Total load time in ms (if completed) */
+  duration?: number;
+  /** Error type if status is "error" */
+  errorType?: "unavailable" | "unauthorized" | "deleted";
+  /** Stack trace captured at subscription creation time */
+  callerStack?: string;
+  devtools?: ExtensionTrackEntryPayload | ExtensionMarkerPayload;
+}
+
+type DevToolsColor =
+  | "primary"
+  | "primary-light"
+  | "primary-dark"
+  | "secondary"
+  | "secondary-light"
+  | "secondary-dark"
+  | "tertiary"
+  | "tertiary-light"
+  | "tertiary-dark"
+  | "error";
+
+interface ExtensionTrackEntryPayload {
+  dataType?: "track-entry"; // Defaults to "track-entry"
+  color?: DevToolsColor; // Defaults to "primary"
+  track: string; // Required: Name of the custom track
+  trackGroup?: string; // Optional: Group for organizing tracks
+  properties?: [string, string][]; // Key-value pairs for detailed view
+  tooltipText?: string; // Short description for tooltip
+}
+
+interface ExtensionMarkerPayload {
+  dataType: "marker"; // Required: Identifies as a marker
+  color?: DevToolsColor; // Defaults to "primary"
+  properties?: [string, string][]; // Key-value pairs for detailed view
+  tooltipText?: string; // Short description for tooltip
+}

package/src/tools/subscribe/utils.ts

@@ -24,7 +24,7 @@ export function myRoleForRawValue(raw: RawCoValue): Role | undefined {
 }
 
 export function createCoValue<D extends CoValue>(
-  ref: RefEncoded<D>,
+  ref: RefEncoded<CoValue>,
   raw: RawCoValue,
   subscriptionScope: SubscriptionScope<D>,
 ) {
@@ -39,7 +39,7 @@ export function createCoValue<D extends CoValue>(
 
   return {
     type: CoValueLoadingState.LOADED,
-    value: freshValueInstance,
+    value: freshValueInstance as unknown as D,
     id: subscriptionScope.id,
   };
 }

package/src/tools/tests/SubscriptionScope.performance.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { SubscriptionScope } from "../subscribe/SubscriptionScope.js";
+import { setupJazzTestSync } from "../testing.js";
+import { setupAccount } from "./utils.js";
+import { z } from "../index.js";
+import { co } from "../internal.js";
+import { CoID, RawCoValue, cojsonInternals } from "cojson";
+
+describe("SubscriptionScope performance profiling", () => {
+  beforeEach(async () => {
+    await setupJazzTestSync();
+    SubscriptionScope.setProfilingEnabled(true);
+    performance.clearMarks();
+    performance.clearMeasures();
+    cojsonInternals.setCoValueLoadingRetryDelay(100);
+  });
+
+  afterEach(() => {
+    SubscriptionScope.setProfilingEnabled(false);
+  });
+
+  it("emits performance entries on successful load", async () => {
+    const { me, meOnSecondPeer } = await setupAccount();
+
+    const TestMap = co.map({ name: z.string() });
+    const value = TestMap.create({ name: "test" }, { owner: me });
+
+    const loaded = await TestMap.load(value.$jazz.id, {
+      loadAs: meOnSecondPeer,
+    });
+
+    expect(loaded).toBeDefined();
+
+    const measures = performance.getEntriesByType(
+      "measure",
+    ) as PerformanceMeasure[];
+    const measure = measures.find(
+      (m) =>
+        (m as PerformanceMeasure & { detail?: { id?: string } }).detail?.id ===
+        value.$jazz.id,
+    );
+
+    expect(measure).toBeDefined();
+    const detail = (
+      measure as PerformanceMeasure & { detail: Record<string, unknown> }
+    ).detail;
+    expect(detail.type).toBe("jazz-subscription");
+    expect(detail.status).toBe("loaded");
+    expect(detail.uuid).toBeDefined();
+    expect(detail.source).toBeDefined();
+    expect(detail.resolve).toBeDefined();
+    expect(measure!.duration).toBeGreaterThan(0);
+  });
+
+  it("does not emit performance entries when profiling is disabled", async () => {
+    SubscriptionScope.setProfilingEnabled(false);
+
+    const { me, meOnSecondPeer } = await setupAccount();
+
+    const TestMap = co.map({ name: z.string() });
+    const value = TestMap.create({ name: "test" }, { owner: me });
+
+    const loaded = await TestMap.load(value.$jazz.id, {
+      loadAs: meOnSecondPeer,
+    });
+
+    expect(loaded).toBeDefined();
+
+    // Verify no jazz-subscription entries were created
+    const measures = performance.getEntriesByType(
+      "measure",
+    ) as PerformanceMeasure[];
+    const jazzMeasures = measures.filter(
+      (m) =>
+        (m as PerformanceMeasure & { detail?: { type?: string } }).detail
+          ?.type === "jazz-subscription",
+    );
+    expect(jazzMeasures.length).toBe(0);
+
+    const marks = performance.getEntriesByType("mark") as PerformanceMark[];
+    const jazzMarks = marks.filter(
+      (m) =>
+        (m as PerformanceMark & { detail?: { type?: string } }).detail?.type ===
+        "jazz-subscription",
+    );
+    expect(jazzMarks.length).toBe(0);
+  });
+
+  it("emits performance entries with error status on unavailable", async () => {
+    const { meOnSecondPeer } = await setupAccount();
+
+    const TestMap = co.map({ name: z.string() });
+    const fakeId = "co_zFAKEIDTHATDOESNOTEXIST123" as CoID<RawCoValue>;
+
+    const loaded = await TestMap.load(fakeId, { loadAs: meOnSecondPeer });
+
+    expect(loaded.$isLoaded).toBe(false);
+
+    const measures = performance.getEntriesByType(
+      "measure",
+    ) as PerformanceMeasure[];
+    const measure = measures.find(
+      (m) =>
+        (m as PerformanceMeasure & { detail?: { id?: string } }).detail?.id ===
+        fakeId,
+    );
+
+    expect(measure).toBeDefined();
+    const detail = (
+      measure as PerformanceMeasure & { detail: Record<string, unknown> }
+    ).detail;
+    expect(detail.status).toBe("error");
+    expect(detail.errorType).toBe("unavailable");
+  });
+
+  it("emits start and end marks with correct detail", async () => {
+    const { me, meOnSecondPeer } = await setupAccount();
+
+    const TestMap = co.map({ name: z.string() });
+    const value = TestMap.create({ name: "test" }, { owner: me });
+
+    await TestMap.load(value.$jazz.id, { loadAs: meOnSecondPeer });
+
+    const marks = performance.getEntriesByType("mark") as PerformanceMark[];
+    const startMark = marks.find(
+      (m) =>
+        m.name.startsWith("jazz.subscription.start:") &&
+        (m as PerformanceMark & { detail?: { id?: string } }).detail?.id ===
+          value.$jazz.id,
+    );
+    const endMark = marks.find(
+      (m) =>
+        m.name.startsWith("jazz.subscription.end:") &&
+        (m as PerformanceMark & { detail?: { id?: string } }).detail?.id ===
+          value.$jazz.id,
+    );
+
+    expect(startMark).toBeDefined();
+    expect(endMark).toBeDefined();
+    expect(
+      (startMark as PerformanceMark & { detail: { status: string } }).detail
+        .status,
+    ).toBe("pending");
+    expect(
+      (endMark as PerformanceMark & { detail: { status: string } }).detail
+        .status,
+    ).toBe("loaded");
+  });
+});