jazz-tools 0.19.7 → 0.19.8

package/src/tools/subscribe/SubscriptionScope.ts

@@ -24,6 +24,10 @@ import type {
 } from "./types.js";
 import { CoValueLoadingState, NotLoadedCoValueState } from "./types.js";
 import { createCoValue, myRoleForRawValue } from "./utils.js";
+import {
+  captureError,
+  isCustomErrorReportingEnabled,
+} from "./errorReporting.js";
 
 export class SubscriptionScope<D extends CoValue> {
   childNodes = new Map<string, SubscriptionScope<CoValue>>();
@@ -58,6 +62,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 +77,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 };
 
@@ -126,37 +140,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;
@@ -296,6 +313,8 @@ export class SubscriptionScope<D extends CoValue> {
     return unloadedValue;
   }
 
+  lastErrorLogged: JazzError | undefined;
+
   getCurrentValue(): MaybeLoaded<D> {
     const rawValue = this.getCurrentRawValue();
 
@@ -304,6 +323,7 @@ export class SubscriptionScope<D extends CoValue> {
       rawValue === CoValueLoadingState.UNAVAILABLE ||
       rawValue === CoValueLoadingState.LOADING
     ) {
+      this.logError();
       return this.getUnloadedValue(rawValue);
     }
 
@@ -315,7 +335,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 +343,6 @@ export class SubscriptionScope<D extends CoValue> {
     }
 
     if (this.errorFromChildren) {
-      console.error(this.errorFromChildren.toString());
       return this.errorFromChildren.type;
     }
 
@@ -335,6 +353,71 @@ 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;
+  }
+
+  logError() {
+    let error: JazzError | undefined;
+
+    if (
+      this.value.type === CoValueLoadingState.UNAUTHORIZED ||
+      this.value.type === CoValueLoadingState.UNAVAILABLE
+    ) {
+      error = this.value;
+    }
+
+    if (this.errorFromChildren) {
+      error = this.errorFromChildren;
+    }
+
+    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;
@@ -577,7 +660,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 +725,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 +764,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],
           },

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

package/src/tools/tests/deepLoading.test.ts

@@ -1,6 +1,14 @@
 import { cojsonInternals } from "cojson";
 import { WasmCrypto } from "cojson/crypto/WasmCrypto";
-import { assert, describe, expect, expectTypeOf, test, vi } from "vitest";
+import {
+  assert,
+  beforeEach,
+  describe,
+  expect,
+  expectTypeOf,
+  test,
+  vi,
+} from "vitest";
 import {
   Group,
   ID,
@@ -11,17 +19,17 @@ import {
 } from "../index.js";
 import {
   Account,
-  CoList,
   Loaded,
   MaybeLoaded,
-  NotLoaded,
+  Settled,
   co,
   randomSessionProvider,
   CoValueLoadingState,
-  NotLoadedCoValueState,
+  CoValueErrorState,
 } from "../internal.js";
 import { createJazzTestAccount, linkAccounts } from "../testing.js";
 import { assertLoaded, waitFor } from "./utils.js";
+import { setCustomErrorReporter } from "../config.js";
 
 const Crypto = await WasmCrypto.create();
 const { connectedPeers } = cojsonInternals;
@@ -43,6 +51,15 @@ const TestMap = co.map({
   optionalRef: co.optional(InnermostMap),
 });
 
+let lastError: Error | undefined;
+
+beforeEach(() => {
+  lastError = undefined;
+  setCustomErrorReporter((error) => {
+    lastError = error;
+  });
+});
+
 describe("Deep loading with depth arg", async () => {
   const me = await Account.create({
     creationProps: { name: "Hermes Puggington" },
@@ -345,7 +362,7 @@ test("Deep loading a record-like coMap", async () => {
     },
   });
   expectTypeOf(recordLoaded).branded.toEqualTypeOf<
-    MaybeLoaded<
+    Settled<
       Loaded<typeof RecordLike> & {
         readonly [key: string]: Loaded<typeof TestMap> & {
           readonly list: Loaded<typeof TestList> &
@@ -494,17 +511,14 @@ describe("Deep loading with unauthorized account", async () => {
       CoValueLoadingState.UNAUTHORIZED,
     );
 
-    expect(errorSpy).toHaveBeenCalledWith(
-      `The current user (${alice.$jazz.id}) is not authorized to access this value from ${map.$jazz.id}`,
+    expect(lastError?.message).toBe(
+      `Jazz Authorization Error: The current user (${alice.$jazz.id}) is not authorized to access ${map.$jazz.id}`,
     );
-
-    errorSpy.mockReset();
   });
 
   test("unaccessible list", async () => {
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-
-    const map = TestMap.create({ list: TestList.create([], onlyBob) }, group);
+    const innerList = TestList.create([], onlyBob);
+    const map = TestMap.create({ list: innerList }, group);
 
     const mapOnAlice = await TestMap.load(map.$jazz.id, { loadAs: alice });
     expect(mapOnAlice).toBeTruthy();
@@ -518,16 +532,12 @@ describe("Deep loading with unauthorized account", async () => {
       CoValueLoadingState.UNAUTHORIZED,
     );
 
-    expect(errorSpy).toHaveBeenCalledWith(
-      `The current user (${alice.$jazz.id}) is not authorized to access this value from ${map.$jazz.id} on path list`,
+    expect(lastError?.message).toBe(
+      `Jazz Authorization Error: The current user (${alice.$jazz.id}) is not authorized to access ${innerList.$jazz.id}. Subscription starts from ${map.$jazz.id} and the value is on path list`,
     );
-
-    errorSpy.mockReset();
   });
 
   test("unaccessible list element", async () => {
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-
     const map = TestMap.create(
       {
         list: TestList.create(
@@ -554,16 +564,12 @@ describe("Deep loading with unauthorized account", async () => {
       CoValueLoadingState.UNAUTHORIZED,
     );
 
-    expect(errorSpy).toHaveBeenCalledWith(
-      `The current user (${alice.$jazz.id}) is not authorized to access this value from ${map.$jazz.id} on path list.0`,
+    expect(lastError?.message).toBe(
+      `Jazz Authorization Error: The current user (${alice.$jazz.id}) is not authorized to access ${map.list[0]!.$jazz.id}. Subscription starts from ${map.$jazz.id} and the value is on path list.0`,
     );
-
-    errorSpy.mockReset();
   });
 
   test("unaccessible optional element", async () => {
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-
     const map = TestMap.create(
       {
         list: TestList.create([], group),
@@ -579,11 +585,9 @@ describe("Deep loading with unauthorized account", async () => {
     expect(mapOnAlice.$jazz.loadingState).toBe(
       CoValueLoadingState.UNAUTHORIZED,
     );
-    expect(errorSpy).toHaveBeenCalledWith(
-      `The current user (${alice.$jazz.id}) is not authorized to access this value from ${map.$jazz.id} on path optionalRef`,
+    expect(lastError?.message).toBe(
+      `Jazz Authorization Error: The current user (${alice.$jazz.id}) is not authorized to access ${map.optionalRef!.$jazz.id}. Subscription starts from ${map.$jazz.id} and the value is on path optionalRef`,
     );
-
-    errorSpy.mockReset();
   });
 
   test("unaccessible optional element via autoload", async () => {
@@ -611,17 +615,20 @@ describe("Deep loading with unauthorized account", async () => {
       });
 
     expect(result?.$jazz.loadingState).toBe(CoValueLoadingState.UNAUTHORIZED);
+    expect(lastError?.message).toBe(
+      `Jazz Authorization Error: The current user (${alice.$jazz.id}) is not authorized to access ${map.optionalRef!.$jazz.id}`,
+    );
   });
 
   test("unaccessible stream", async () => {
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const stream = TestFeed.create([], onlyBob);
     const map = TestMap.create(
       {
         list: TestList.create(
           [
             InnerMap.create(
               {
-                stream: TestFeed.create([], onlyBob),
+                stream,
               },
               group,
             ),
@@ -641,16 +648,12 @@ describe("Deep loading with unauthorized account", async () => {
       CoValueLoadingState.UNAUTHORIZED,
     );
 
-    expect(errorSpy).toHaveBeenCalledWith(
-      `The current user (${alice.$jazz.id}) is not authorized to access this value from ${map.$jazz.id} on path list.0.stream`,
+    expect(lastError?.message).toBe(
+      `Jazz Authorization Error: The current user (${alice.$jazz.id}) is not authorized to access ${stream.$jazz.id}. Subscription starts from ${map.$jazz.id} and the value is on path list.0.stream`,
     );
-
-    errorSpy.mockReset();
   });
 
   test("unaccessible stream element", async () => {
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-
     const value = InnermostMap.create({ value: "hello" }, onlyBob);
 
     const map = TestMap.create(
@@ -679,11 +682,9 @@ describe("Deep loading with unauthorized account", async () => {
       CoValueLoadingState.UNAUTHORIZED,
     );
 
-    expect(errorSpy).toHaveBeenCalledWith(
-      `The current user (${alice.$jazz.id}) is not authorized to access this value from ${map.$jazz.id} on path list.0.stream.${value.$jazz.id}`,
+    expect(lastError?.message).toBe(
+      `Jazz Authorization Error: The current user (${alice.$jazz.id}) is not authorized to access ${value.$jazz.id}. Subscription starts from ${map.$jazz.id} and the value is on path list.0.stream.${value.$jazz.id}`,
     );
-
-    errorSpy.mockReset();
   });
 
   test("setting undefined via proxy", async () => {
@@ -1229,7 +1230,7 @@ describe("$isLoaded", async () => {
 
   const map = TestMap.create({ list: [] }, { owner: me });
 
-  test("$isLoaded narrows MaybeLoaded to loaded CoValue", async () => {
+  test("$isLoaded narrows a maybe-loaded CoValue to a loaded CoValue", async () => {
     const maybeLoadedMap = await TestMap.load(map.$jazz.id, {
       loadAs: me,
     });
@@ -1244,19 +1245,18 @@ describe("$isLoaded", async () => {
     } else {
       expectTypeOf(
         maybeLoadedMap.$jazz.loadingState,
-      ).toEqualTypeOf<NotLoadedCoValueState>();
+      ).toEqualTypeOf<CoValueErrorState>();
     }
   });
 
-  test("$isLoaded narrows MaybeLoaded to not loaded CoValue", async () => {
+  test("$isLoaded narrows a maybe-loaded CoValue to a not loaded CoValue", async () => {
     const otherAccount = await Account.create({
       creationProps: { name: "Other Account" },
       crypto: Crypto,
     });
-    const unloadedMap: MaybeLoaded<Loaded<typeof TestMap>> = await TestMap.load(
-      map.$jazz.id,
-      { loadAs: otherAccount },
-    );
+    const unloadedMap = await TestMap.load(map.$jazz.id, {
+      loadAs: otherAccount,
+    });
 
     expect(unloadedMap.$isLoaded).toBe(false);
     if (!unloadedMap.$isLoaded) {

package/src/tools/tests/errorReporting.test.ts

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { Group, z } from "../index.js";
+import { setCustomErrorReporter } from "../config.js";
+import { CoValueLoadingState } from "../internal.js";
+import { createJazzTestAccount, linkAccounts } from "../testing.js";
+import { co } from "../exports.js";
+
+const TestMap = co.map({
+  value: z.string(),
+});
+
+describe("Custom error reporter", () => {
+  beforeEach(() => {
+    // Clean up error reporter before each test
+    setCustomErrorReporter(undefined);
+  });
+
+  test("with custom error reporter enabled, console.error is not called", async () => {
+    const bob = await createJazzTestAccount({
+      creationProps: { name: "Bob" },
+    });
+
+    const alice = await createJazzTestAccount({
+      creationProps: { name: "Alice" },
+    });
+
+    linkAccounts(bob, alice);
+
+    await alice.$jazz.waitForAllCoValuesSync();
+
+    const onlyBob = bob;
+    const group = Group.create(bob);
+
+    group.addMember(alice, "reader");
+
+    let capturedError: Error | undefined;
+    let capturedProps: { jazzError: any } | undefined;
+
+    setCustomErrorReporter((error, props) => {
+      capturedError = error;
+      capturedProps = props;
+    });
+
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    const map = TestMap.create({ value: "hello" }, onlyBob);
+
+    const mapOnAlice = await TestMap.load(map.$jazz.id, { loadAs: alice });
+
+    // Access the value to trigger error logging
+    expect(mapOnAlice.$jazz.loadingState).toBe(
+      CoValueLoadingState.UNAUTHORIZED,
+    );
+
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+    expect(capturedError).toBeDefined();
+    expect(capturedProps).toBeDefined();
+    expect(capturedProps?.jazzError).toBeDefined();
+
+    consoleErrorSpy.mockRestore();
+  });
+
+  test("without custom error reporter, console.error is called", async () => {
+    const bob = await createJazzTestAccount({
+      creationProps: { name: "Bob" },
+    });
+
+    const alice = await createJazzTestAccount({
+      creationProps: { name: "Alice" },
+    });
+
+    linkAccounts(bob, alice);
+
+    await alice.$jazz.waitForAllCoValuesSync();
+
+    const onlyBob = bob;
+    const group = Group.create(bob);
+
+    group.addMember(alice, "reader");
+
+    // Ensure no custom error reporter is set
+    setCustomErrorReporter(undefined);
+
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    const map = TestMap.create({ value: "hello" }, onlyBob);
+
+    const mapOnAlice = await TestMap.load(map.$jazz.id, { loadAs: alice });
+
+    // Access the value to trigger error logging
+    expect(mapOnAlice.$jazz.loadingState).toBe(
+      CoValueLoadingState.UNAUTHORIZED,
+    );
+
+    expect(consoleErrorSpy).toHaveBeenCalled();
+
+    consoleErrorSpy.mockRestore();
+  });
+});

package/src/tools/tests/load.test.ts

@@ -1,6 +1,13 @@
 import { cojsonInternals, emptyKnownState } from "cojson";
 import { assert, beforeEach, expect, test } from "vitest";
-import { Account, Group, co, exportCoValue, z } from "../exports.js";
+import {
+  Account,
+  Group,
+  co,
+  exportCoValue,
+  jazzConfig,
+  z,
+} from "../exports.js";
 import { CoValueLoadingState } from "../internal.js";
 import {
   createJazzTestAccount,
@@ -12,6 +19,13 @@ import { assertLoaded, waitFor } from "./utils.js";
 
 cojsonInternals.CO_VALUE_LOADING_CONFIG.RETRY_DELAY = 10;
 
+let lastError: Error | undefined;
+beforeEach(() => {
+  lastError = undefined;
+  jazzConfig.setCustomErrorReporter((error) => {
+    lastError = error;
+  });
+});
 beforeEach(async () => {
   await setupJazzTestSync();
   await createJazzTestAccount({
@@ -42,6 +56,9 @@ test("return 'unavailable' if id is invalid", async () => {
 
   const john = await Person.load("test");
   expect(john.$jazz.loadingState).toBe(CoValueLoadingState.UNAVAILABLE);
+  expect(lastError?.message).toBe(
+    "Jazz Unavailable Error: unable to load test",
+  );
 });
 
 test("load a missing optional value (co.optional)", async () => {
@@ -185,6 +202,9 @@ test("returns 'unavailable' if the value is unavailable after retries", async ()
   const john = await Person.load(map.$jazz.id, { loadAs: alice });
 
   expect(john.$jazz.loadingState).toBe(CoValueLoadingState.UNAVAILABLE);
+  expect(lastError?.message).toBe(
+    "Jazz Unavailable Error: unable to load " + map.$jazz.id,
+  );
 });
 
 test("load works even when the coValue access is granted after the creation", async () => {

package/src/tools/tests/request.test.ts

@@ -14,6 +14,7 @@ import {
   CoValueLoadingState,
   exportCoValue,
   importContentPieces,
+  Inaccessible,
 } from "../internal.js";
 import { createJazzTestAccount, linkAccounts } from "../testing.js";
 
@@ -663,7 +664,7 @@ describe("JazzRequestError handling", () => {
             createUnloadedCoValue(
               "some-covalue-id",
               CoValueLoadingState.UNAVAILABLE,
-            ),
+            ) as Inaccessible<Account>,
           );
 
           return userRequest.handle(request, worker, async () => {