jazz-tools 0.19.6 → 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 };
 
@@ -91,7 +105,11 @@ export class SubscriptionScope<D extends CoValue> {
         // - Run the migration only once
         // - Skip all the updates until the migration is done
         // - Trigger handleUpdate only with the final value
-        if (!this.migrated && value !== CoValueLoadingState.UNAVAILABLE) {
+        if (
+          !this.migrated &&
+          value !== CoValueLoadingState.UNAVAILABLE &&
+          hasAccessToCoValue(value)
+        ) {
           if (this.migrating) {
             return;
           }
@@ -122,44 +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;
     }
 
-    const ruleset = update.core.verified.header.ruleset;
-
-    // Groups and accounts are accessible by everyone, for the other coValues we use the role to check access
-    const hasAccess =
-      ruleset.type !== "ownedByGroup" ||
-      myRoleForRawValue(update) !== undefined;
-
-    if (!hasAccess) {
+    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;
@@ -299,6 +313,8 @@ export class SubscriptionScope<D extends CoValue> {
     return unloadedValue;
   }
 
+  lastErrorLogged: JazzError | undefined;
+
   getCurrentValue(): MaybeLoaded<D> {
     const rawValue = this.getCurrentRawValue();
 
@@ -307,6 +323,7 @@ export class SubscriptionScope<D extends CoValue> {
       rawValue === CoValueLoadingState.UNAVAILABLE ||
       rawValue === CoValueLoadingState.LOADING
     ) {
+      this.logError();
       return this.getUnloadedValue(rawValue);
     }
 
@@ -318,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;
     }
 
@@ -327,7 +343,6 @@ export class SubscriptionScope<D extends CoValue> {
     }
 
     if (this.errorFromChildren) {
-      console.error(this.errorFromChildren.toString());
       return this.errorFromChildren.type;
     }
 
@@ -338,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;
@@ -580,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],
                     },
@@ -645,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],
             },
@@ -684,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],
           },
@@ -759,3 +839,13 @@ export class SubscriptionScope<D extends CoValue> {
     this.childNodes.forEach((child) => child.destroy());
   }
 }
+
+function hasAccessToCoValue(rawCoValue: RawCoValue): boolean {
+  const ruleset = rawCoValue.core.verified.header.ruleset;
+
+  // Groups and accounts are accessible by everyone, for the other coValues we use the role to check access
+  return (
+    ruleset.type !== "ownedByGroup" ||
+    myRoleForRawValue(rawCoValue) !== undefined
+  );
+}

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/coDiscriminatedUnion.test.ts

@@ -1,5 +1,13 @@
-import { beforeEach, describe, expect, test, vi } from "vitest";
-import { CoPlainText, Group, Loaded, co, loadCoValue, z } from "../exports.js";
+import { assert, beforeEach, describe, expect, test, vi } from "vitest";
+import {
+  CoPlainText,
+  CoValueLoadingState,
+  Group,
+  Loaded,
+  co,
+  loadCoValue,
+  z,
+} from "../exports.js";
 import { createJazzTestAccount, setupJazzTestSync } from "../testing.js";
 import { assertLoaded, waitFor } from "./utils.js";
 import type { Account } from "jazz-tools";
@@ -713,4 +721,63 @@ describe("co.discriminatedUnion", () => {
       }
     });
   });
+
+  test("cannot create a co.discriminatedUnion member if it has no matching discriminator value", async () => {
+    const Dog = co.map({
+      type: z.literal("dog"),
+      name: z.string(),
+    });
+    const Cat = co.map({
+      type: z.literal("cat"),
+      name: z.string(),
+    });
+    const Parrot = co.map({
+      type2: z.literal("parrot"),
+      name: z.string(),
+    });
+    const Pet = co.discriminatedUnion("type", [Dog, Cat, Parrot]);
+    const Pets = co.list(Pet);
+
+    expect(() => Pets.create([{ type2: "parrot", name: "Polly" }])).toThrow(
+      "co.discriminatedUnion() of collaborative types with no matching discriminator value found",
+    );
+  });
+
+  test("can load a discriminated union CoList even if some elements are not accessible", async () => {
+    const Dog = co.map({
+      type: z.literal("dog"),
+      name: z.string(),
+    });
+    const Cat = co.map({
+      type: z.literal("cat"),
+      name: z.string(),
+    });
+    const Pet = co.discriminatedUnion("type", [Dog, Cat]);
+    const Pets = co.list(Pet);
+
+    const publicGroup = Group.create().makePublic();
+    const privateGroup = Group.create();
+    const pets = Pets.create(
+      [
+        Dog.create({ type: "dog", name: "Rex" }, publicGroup),
+        Cat.create({ type: "cat", name: "Whiskers" }, privateGroup),
+      ],
+      { owner: publicGroup },
+    );
+
+    const anotherAccount = await createJazzTestAccount();
+    const loadedPets = await Pets.load(pets.$jazz.id, {
+      resolve: { $each: { $onError: "catch" } },
+      loadAs: anotherAccount,
+    });
+
+    assertLoaded(loadedPets);
+    expect(loadedPets.length).toEqual(2);
+    assert(loadedPets[0]);
+    assertLoaded(loadedPets[0]);
+    expect(loadedPets[0].type).toEqual("dog");
+    expect(loadedPets[1]?.$jazz.loadingState).toEqual(
+      CoValueLoadingState.UNAUTHORIZED,
+    );
+  });
 });

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