jazz-tools 0.20.1 → 0.20.3

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");
+  });
+});