jazz-tools 0.18.38 → 0.19.1

package/src/tools/subscribe/CoValueCoreSubscription.ts

@@ -6,6 +6,7 @@ import {
   RawCoValue,
 } from "cojson";
 import type { BranchDefinition } from "./types.js";
+import { CoValueLoadingState } from "./types.js";
 
 /**
  * Manages subscriptions to CoValue cores, handling both direct subscriptions
@@ -21,13 +22,17 @@ export class CoValueCoreSubscription {
   private branchName?: string;
   private source: CoValueCore;
   private localNode: LocalNode;
-  private listener: (value: RawCoValue | "unavailable") => void;
+  private listener: (
+    value: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE,
+  ) => void;
   private skipRetry?: boolean;
 
   constructor(
     localNode: LocalNode,
     id: string,
-    listener: (value: RawCoValue | "unavailable") => void,
+    listener: (
+      value: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE,
+    ) => void,
     skipRetry?: boolean,
     branch?: BranchDefinition,
   ) {
@@ -115,7 +120,7 @@ export class CoValueCoreSubscription {
       .then((value) => {
         if (this.unsubscribed) return;
 
-        if (value !== "unavailable") {
+        if (value !== CoValueLoadingState.UNAVAILABLE) {
           // Branch checkout successful, subscribe to it
           this.subscribe(value);
         } else {
@@ -126,7 +131,7 @@ export class CoValueCoreSubscription {
       .catch((error) => {
         // Handle unexpected errors during branch checkout
         console.error(error);
-        this.emit("unavailable");
+        this.emit(CoValueLoadingState.UNAVAILABLE);
       });
   }
 
@@ -143,7 +148,7 @@ export class CoValueCoreSubscription {
 
     // Source isn't available either, subscribe to state changes and report unavailability
     this.subscribeToUnavailableSource();
-    this.emit("unavailable");
+    this.emit(CoValueLoadingState.UNAVAILABLE);
   }
 
   /**
@@ -162,13 +167,13 @@ export class CoValueCoreSubscription {
         } else {
           // Loading failed, subscribe to state changes and report unavailability
           this.subscribeToUnavailableSource();
-          this.emit("unavailable");
+          this.emit(CoValueLoadingState.UNAVAILABLE);
         }
       })
       .catch((error) => {
         // Handle unexpected errors during loading
         console.error(error);
-        this.emit("unavailable");
+        this.emit(CoValueLoadingState.UNAVAILABLE);
       });
   }
 
@@ -218,7 +223,7 @@ export class CoValueCoreSubscription {
     });
   }
 
-  emit(value: RawCoValue | "unavailable"): void {
+  emit(value: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE): void {
     if (this.unsubscribed) return;
     if (!isReadyForEmit(value)) {
       return;

package/src/tools/subscribe/JazzError.ts

@@ -1,9 +1,12 @@
 import type { CoValue, ID } from "../internal.js";
+import { CoValueLoadingState } from "./types.js";
 
 export class JazzError {
   constructor(
     public id: ID<CoValue> | undefined,
-    public type: "unavailable" | "unauthorized",
+    public type:
+      | typeof CoValueLoadingState.UNAVAILABLE
+      | typeof CoValueLoadingState.UNAUTHORIZED,
     public issues: JazzErrorIssue[],
   ) {}
 
@@ -41,7 +44,10 @@ export class JazzError {
   }
 }
 export type JazzErrorIssue = {
-  code: "unavailable" | "unauthorized" | "validationError";
+  code:
+    | typeof CoValueLoadingState.UNAVAILABLE
+    | typeof CoValueLoadingState.UNAUTHORIZED
+    | "validationError";
   message: string;
   params: Record<string, any>;
   path: string[];

package/src/tools/subscribe/SubscriptionScope.ts

@@ -5,6 +5,7 @@ import {
   CoMap,
   type CoValue,
   type ID,
+  MaybeLoaded,
   type RefEncoded,
   type RefsToResolve,
   TypeSym,
@@ -14,7 +15,12 @@ import {
 import { applyCoValueMigrations } from "../lib/migration.js";
 import { CoValueCoreSubscription } from "./CoValueCoreSubscription.js";
 import { JazzError, type JazzErrorIssue } from "./JazzError.js";
-import type { BranchDefinition, SubscriptionValue, Unloaded } from "./types.js";
+import type {
+  BranchDefinition,
+  SubscriptionValue,
+  SubscriptionValueLoading,
+} from "./types.js";
+import { CoValueLoadingState, NotLoadedCoValueState } from "./types.js";
 import { createCoValue, myRoleForRawValue } from "./utils.js";
 
 export class SubscriptionScope<D extends CoValue> {
@@ -31,7 +37,7 @@ export class SubscriptionScope<D extends CoValue> {
    * Autoloaded child ids that are unloaded
    */
   pendingAutoloadedChildren: Set<string> = new Set();
-  value: SubscriptionValue<D, any> | Unloaded;
+  value: SubscriptionValue<D, any> | SubscriptionValueLoading;
   childErrors: Map<string, JazzError> = new Map();
   validationErrors: Map<string, JazzError> = new Map();
   errorFromChildren: JazzError | undefined;
@@ -43,6 +49,7 @@ export class SubscriptionScope<D extends CoValue> {
   autoloadedKeys = new Set<string>();
   skipInvalidKeys = new Set<string>();
   totalValidTransactions = 0;
+  version = 0;
   migrated = false;
   migrating = false;
   closed = false;
@@ -59,16 +66,19 @@ export class SubscriptionScope<D extends CoValue> {
     public unstable_branch?: BranchDefinition,
   ) {
     this.resolve = resolve;
-    this.value = { type: "unloaded", id };
+    this.value = { type: CoValueLoadingState.LOADING, id };
 
-    let lastUpdate: RawCoValue | "unavailable" | undefined;
+    let lastUpdate:
+      | RawCoValue
+      | typeof CoValueLoadingState.UNAVAILABLE
+      | undefined;
     this.subscription = new CoValueCoreSubscription(
       node,
       id,
       (value) => {
         lastUpdate = value;
 
-        if (skipRetry && value === "unavailable") {
+        if (skipRetry && value === CoValueLoadingState.UNAVAILABLE) {
           this.handleUpdate(value);
           return;
         }
@@ -79,7 +89,7 @@ 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 !== "unavailable") {
+        if (!this.migrated && value !== CoValueLoadingState.UNAVAILABLE) {
           if (this.migrating) {
             return;
           }
@@ -107,13 +117,13 @@ export class SubscriptionScope<D extends CoValue> {
     this.dirty = true;
   }
 
-  handleUpdate(update: RawCoValue | "unavailable") {
-    if (update === "unavailable") {
-      if (this.value.type === "unloaded") {
+  handleUpdate(update: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE) {
+    if (update === CoValueLoadingState.UNAVAILABLE) {
+      if (this.value.type === CoValueLoadingState.LOADING) {
         this.updateValue(
-          new JazzError(this.id, "unavailable", [
+          new JazzError(this.id, CoValueLoadingState.UNAVAILABLE, [
             {
-              code: "unavailable",
+              code: CoValueLoadingState.UNAVAILABLE,
               message: "The value is unavailable",
               params: {
                 id: this.id,
@@ -135,11 +145,11 @@ export class SubscriptionScope<D extends CoValue> {
       myRoleForRawValue(update) !== undefined;
 
     if (!hasAccess) {
-      if (this.value.type !== "unauthorized") {
+      if (this.value.type !== CoValueLoadingState.UNAUTHORIZED) {
         this.updateValue(
-          new JazzError(this.id, "unauthorized", [
+          new JazzError(this.id, CoValueLoadingState.UNAUTHORIZED, [
             {
-              code: "unauthorized",
+              code: CoValueLoadingState.UNAUTHORIZED,
               message: `The current user (${this.node.getCurrentAgent().id}) is not authorized to access this value`,
               params: {
                 id: this.id,
@@ -157,15 +167,13 @@ export class SubscriptionScope<D extends CoValue> {
     // after loading all the children, not one per children
     this.silenceUpdates = true;
 
-    if (this.value.type !== "loaded") {
+    if (this.value.type !== CoValueLoadingState.LOADED) {
       this.updateValue(createCoValue(this.schema, update, this));
       this.loadChildren();
     } else {
       const hasChanged =
         update.totalValidTransactions !== this.totalValidTransactions ||
-        // Checking the identity of the raw value makes us cover the cases where the group
-        // has been updated and the coValues that don't update the totalValidTransactions value (e.g. FileStream)
-        this.value.value.$jazz.raw !== update;
+        update.version !== this.version;
 
       if (this.loadChildren()) {
         this.updateValue(createCoValue(this.schema, update, this));
@@ -175,6 +183,7 @@ export class SubscriptionScope<D extends CoValue> {
     }
 
     this.totalValidTransactions = update.totalValidTransactions;
+    this.version = update.version;
 
     this.silenceUpdates = false;
     this.triggerUpdate();
@@ -182,7 +191,7 @@ export class SubscriptionScope<D extends CoValue> {
 
   computeChildErrors() {
     let issues: JazzErrorIssue[] = [];
-    let errorType: JazzError["type"] = "unavailable";
+    let errorType: JazzError["type"] = CoValueLoadingState.UNAVAILABLE;
 
     if (this.childErrors.size === 0 && this.validationErrors.size === 0) {
       return undefined;
@@ -228,10 +237,10 @@ export class SubscriptionScope<D extends CoValue> {
 
   handleChildUpdate = (
     id: string,
-    value: SubscriptionValue<any, any> | Unloaded,
+    value: SubscriptionValue<any, any> | SubscriptionValueLoading,
     key?: string,
   ) => {
-    if (value.type === "unloaded") {
+    if (value.type === CoValueLoadingState.LOADING) {
       return;
     }
 
@@ -239,7 +248,10 @@ export class SubscriptionScope<D extends CoValue> {
     this.pendingAutoloadedChildren.delete(id);
     this.childValues.set(id, value);
 
-    if (value.type === "unavailable" || value.type === "unauthorized") {
+    if (
+      value.type === CoValueLoadingState.UNAVAILABLE ||
+      value.type === CoValueLoadingState.UNAUTHORIZED
+    ) {
       this.childErrors.set(id, value.prependPath(key ?? id));
 
       this.errorFromChildren = this.computeChildErrors();
@@ -250,7 +262,7 @@ export class SubscriptionScope<D extends CoValue> {
     }
 
     if (this.shouldSendUpdates()) {
-      if (this.value.type === "loaded") {
+      if (this.value.type === CoValueLoadingState.LOADED) {
         // On child updates, we re-create the value instance to make the updates
         // seamless-immutable and so be compatible with React and the React compiler
         this.updateValue(
@@ -263,37 +275,37 @@ export class SubscriptionScope<D extends CoValue> {
   };
 
   shouldSendUpdates() {
-    if (this.value.type === "unloaded") return false;
+    if (this.value.type === CoValueLoadingState.LOADING) return false;
 
     // If the value is in error, we send the update regardless of the children statuses
-    if (this.value.type !== "loaded") return true;
+    if (this.value.type !== CoValueLoadingState.LOADED) return true;
 
     return this.pendingLoadedChildren.size === 0;
   }
 
-  getCurrentValue() {
+  getCurrentValue(): D | NotLoadedCoValueState {
     if (
-      this.value.type === "unauthorized" ||
-      this.value.type === "unavailable"
+      this.value.type === CoValueLoadingState.UNAUTHORIZED ||
+      this.value.type === CoValueLoadingState.UNAVAILABLE
     ) {
       console.error(this.value.toString());
-      return null;
+      return this.value.type;
     }
 
     if (!this.shouldSendUpdates()) {
-      return undefined;
+      return CoValueLoadingState.LOADING;
     }
 
     if (this.errorFromChildren) {
       console.error(this.errorFromChildren.toString());
-      return null;
+      return this.errorFromChildren.type;
     }
 
-    if (this.value.type === "loaded") {
+    if (this.value.type === CoValueLoadingState.LOADED) {
       return this.value.value;
     }
 
-    return undefined;
+    return CoValueLoadingState.LOADING;
   }
 
   triggerUpdate() {
@@ -307,7 +319,7 @@ export class SubscriptionScope<D extends CoValue> {
 
     if (error) {
       this.subscribers.forEach((listener) => listener(error));
-    } else if (value.type !== "unloaded") {
+    } else if (value.type !== CoValueLoadingState.LOADING) {
       this.subscribers.forEach((listener) => listener(value));
     }
 
@@ -333,16 +345,15 @@ export class SubscriptionScope<D extends CoValue> {
       this.resolve = {};
     }
 
-    if (!this.resolve.$each && !(key in this.resolve)) {
-      const resolve = this.resolve as Record<string, any>;
-
+    const resolve: Record<string, any> = this.resolve;
+    if (!resolve.$each && !(key in resolve)) {
       // Adding the key to the resolve object to resolve the key when calling loadChildren
       resolve[key] = true;
       // Track the keys that are autoloaded to flag any id on that key as autoloaded
       this.autoloadedKeys.add(key);
     }
 
-    if (this.value.type !== "loaded") {
+    if (this.value.type !== CoValueLoadingState.LOADED) {
       return;
     }
 
@@ -386,7 +397,7 @@ export class SubscriptionScope<D extends CoValue> {
       throw new Error("Cannot pull a non-closed subscription scope");
     }
 
-    if (this.value.type === "loaded") {
+    if (this.value.type === CoValueLoadingState.LOADED) {
       return;
     }
 
@@ -398,9 +409,9 @@ export class SubscriptionScope<D extends CoValue> {
     const value = this.getCurrentValue();
 
     // If the value is available, trigger the listener
-    if (value) {
+    if (typeof value !== "string") {
       listener({
-        type: "loaded",
+        type: CoValueLoadingState.LOADED,
         value,
         id: this.id,
       });
@@ -461,7 +472,7 @@ export class SubscriptionScope<D extends CoValue> {
   loadChildren() {
     const { resolve } = this;
 
-    if (this.value.type !== "loaded") {
+    if (this.value.type !== CoValueLoadingState.LOADED) {
       return false;
     }
 
@@ -536,7 +547,7 @@ export class SubscriptionScope<D extends CoValue> {
               } else if (!descriptor.optional) {
                 this.validationErrors.set(
                   key,
-                  new JazzError(undefined, "unavailable", [
+                  new JazzError(undefined, CoValueLoadingState.UNAVAILABLE, [
                     {
                       code: "validationError",
                       message: `The ref on position ${key} requested on ${stream.constructor.name} is missing`,
@@ -583,17 +594,6 @@ export class SubscriptionScope<D extends CoValue> {
     const descriptor = map.$jazz.getDescriptor(key);
 
     if (!descriptor) {
-      this.childErrors.set(
-        key,
-        new JazzError(undefined, "unavailable", [
-          {
-            code: "validationError",
-            message: `The ref ${key} requested on ${map.constructor.name} is not defined in the schema`,
-            params: {},
-            path: [key],
-          },
-        ]),
-      );
       return undefined;
     }
 
@@ -606,7 +606,7 @@ export class SubscriptionScope<D extends CoValue> {
       } else if (!descriptor.optional) {
         this.validationErrors.set(
           key,
-          new JazzError(undefined, "unavailable", [
+          new JazzError(undefined, CoValueLoadingState.UNAVAILABLE, [
             {
               code: "validationError",
               message: `The ref ${key} requested on ${map.constructor.name} is missing`,
@@ -645,7 +645,7 @@ export class SubscriptionScope<D extends CoValue> {
     } else if (!descriptor.optional) {
       this.validationErrors.set(
         key,
-        new JazzError(undefined, "unavailable", [
+        new JazzError(undefined, CoValueLoadingState.UNAVAILABLE, [
           {
             code: "validationError",
             message: `The ref on position ${key} requested on ${list.constructor.name} is missing`,
@@ -674,7 +674,7 @@ export class SubscriptionScope<D extends CoValue> {
       this.autoloaded.add(id);
     }
 
-    const skipInvalid = typeof query === "object" && query.$onError === null;
+    const skipInvalid = typeof query === "object" && query.$onError === "catch";
 
     if (skipInvalid) {
       if (key) {

package/src/tools/subscribe/index.ts

@@ -1,5 +1,7 @@
 import type { CoValue, CoValueClass, RefEncoded } from "../internal.js";
+import { createUnloadedCoValue } from "../internal.js";
 import { SubscriptionScope } from "./SubscriptionScope.js";
+import { CoValueLoadingState } from "./types.js";
 
 export function getSubscriptionScope<D extends CoValue>(value: D) {
   const subscriptionScope = value.$jazz._subscriptionScope;
@@ -56,10 +58,13 @@ export function accessChildByKey<D extends CoValue>(
 
   const value = subscriptionScope.childValues.get(childId);
 
-  if (value?.type === "loaded") {
+  if (value?.type === CoValueLoadingState.LOADED) {
     return value.value;
   } else {
-    return null;
+    return createUnloadedCoValue(
+      childId,
+      value?.type ?? CoValueLoadingState.LOADING,
+    );
   }
 }
 
@@ -82,9 +87,12 @@ export function accessChildById<D extends CoValue>(
 
   const value = subscriptionScope.childValues.get(childId);
 
-  if (value?.type === "loaded") {
+  if (value?.type === CoValueLoadingState.LOADED) {
     return value.value;
   } else {
-    return null;
+    return createUnloadedCoValue(
+      childId,
+      value?.type ?? CoValueLoadingState.LOADING,
+    );
   }
 }

package/src/tools/subscribe/types.ts

@@ -7,9 +7,43 @@ import type {
 } from "../internal.js";
 import type { JazzError } from "./JazzError.js";
 
+export const CoValueLoadingState = {
+  /**
+   * The coValue is loaded.
+   */
+  LOADED: "loaded",
+  /**
+   * The coValue is being loaded.
+   */
+  LOADING: "loading",
+  /**
+   * The coValue was loaded but the account is not authorized to access it.
+   */
+  UNAUTHORIZED: "unauthorized",
+  /**
+   * Tried to load the coValue but failed.
+   */
+  UNAVAILABLE: "unavailable",
+} as const;
+
+export type CoValueLoadingState =
+  (typeof CoValueLoadingState)[keyof typeof CoValueLoadingState];
+
+export type NotLoadedCoValueState =
+  | typeof CoValueLoadingState.LOADING
+  | typeof CoValueLoadingState.UNAUTHORIZED
+  | typeof CoValueLoadingState.UNAVAILABLE;
+
 export type SubscriptionValue<D extends CoValue, R extends RefsToResolve<D>> =
-  | { type: "loaded"; value: Resolved<D, R>; id: string }
+  | {
+      type: typeof CoValueLoadingState.LOADED;
+      value: Resolved<D, R>;
+      id: string;
+    }
   | JazzError;
-export type Unloaded = { type: "unloaded"; id: string };
+export type SubscriptionValueLoading = {
+  type: typeof CoValueLoadingState.LOADING;
+  id: string;
+};
 
 export type BranchDefinition = { name: string; owner?: Group | Account | null };

package/src/tools/subscribe/utils.ts

@@ -8,6 +8,7 @@ import {
 } from "../internal.js";
 import { coValuesCache } from "../lib/cache.js";
 import { SubscriptionScope } from "./SubscriptionScope.js";
+import { CoValueLoadingState } from "./types.js";
 
 export function myRoleForRawValue(raw: RawCoValue): Role | undefined {
   const rawOwner = raw.group;
@@ -36,7 +37,7 @@ export function createCoValue<D extends CoValue>(
   });
 
   return {
-    type: "loaded" as const,
+    type: CoValueLoadingState.LOADED,
     value: freshValueInstance,
     id: subscriptionScope.id,
   };

package/src/tools/testing.ts

@@ -16,9 +16,14 @@ import {
   coValueClassFromCoValueClassOrSchema,
   createAnonymousJazzContext,
   createJazzContext,
+  CoValue,
+  LoadedAndRequired,
+  MaybeLoaded,
   randomSessionProvider,
 } from "./internal.js";
 
+export { assertLoaded } from "./lib/utils.js";
+
 const syncServer: { current: LocalNode | null; asyncPeers: boolean } = {
   current: null,
   asyncPeers: false,

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

@@ -1,5 +1,11 @@
 import { assert, beforeEach, describe, expect, test, vi } from "vitest";
-import { Group, co, exportCoValue, z } from "../exports.js";
+import {
+  CoValueLoadingState,
+  Group,
+  co,
+  exportCoValue,
+  z,
+} from "../exports.js";
 import { CoValueCoreSubscription } from "../subscribe/CoValueCoreSubscription.js";
 import {
   createJazzTestAccount,
@@ -462,7 +468,7 @@ describe("CoValueCoreSubscription", async () => {
       await waitFor(() => expect(listener).toHaveBeenCalled());
 
       // Should report unavailable when loading fails
-      expect(lastResult).toBe("unavailable");
+      expect(lastResult).toBe(CoValueLoadingState.UNAVAILABLE);
 
       subscription.unsubscribe();
     });
@@ -493,7 +499,7 @@ describe("CoValueCoreSubscription", async () => {
       await waitFor(() => expect(listener).toHaveBeenCalled());
 
       // Should report unavailable when loading fails
-      expect(lastResult).toBe("unavailable");
+      expect(lastResult).toBe(CoValueLoadingState.UNAVAILABLE);
 
       subscription.unsubscribe();
     });
@@ -542,7 +548,7 @@ describe("CoValueCoreSubscription", async () => {
       await waitFor(() => expect(listener).toHaveBeenCalled());
 
       // Should report unavailable when loading fails
-      expect(lastResult).toBe("unavailable");
+      expect(lastResult).toBe(CoValueLoadingState.UNAVAILABLE);
 
       subscription.unsubscribe();
     });

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

@@ -1,6 +1,6 @@
 import { StorageAPI } from "cojson";
 import { WasmCrypto } from "cojson/crypto/WasmCrypto";
-import { beforeEach, describe, expect, test, vi } from "vitest";
+import { assert, beforeEach, describe, expect, test, vi } from "vitest";
 import {
   Account,
   AccountClass,
@@ -28,6 +28,7 @@ import {
   coValueClassFromCoValueClassOrSchema,
 } from "../internal";
 import {
+  assertLoaded,
   createJazzTestAccount,
   getPeerConnectedToTestSyncServer,
   setupJazzTestSync,
@@ -101,7 +102,8 @@ describe("ContextManager", () => {
 
     const context = getCurrentValue();
 
-    expect(context.me.profile?.name).toBe("Anonymous user");
+    assertLoaded(context.me.profile);
+    expect(context.me.profile.name).toBe("Anonymous user");
     expect(context.node).toBeDefined();
     expect(manager.getCurrentValue()).toBeDefined();
   });
@@ -113,7 +115,8 @@ describe("ContextManager", () => {
 
     const context = getCurrentValue();
 
-    expect(context.me.profile?.name).toBe("Test User");
+    assertLoaded(context.me.profile);
+    expect(context.me.profile.name).toBe("Test User");
     expect(context.node).toBeDefined();
     expect(manager.getCurrentValue()).toBeDefined();
   });
@@ -489,7 +492,10 @@ describe("ContextManager", () => {
       },
     });
 
-    expect(me.root.transferredRoot?.value).toBe("Hello");
+    const transferredRoot = me.root.transferredRoot;
+    assert(transferredRoot);
+    assertLoaded(transferredRoot);
+    expect(transferredRoot.value).toBe("Hello");
   });
 
   test("handles registration of new account", async () => {
@@ -501,7 +507,8 @@ describe("ContextManager", () => {
 
     expect(accountId).toBeDefined();
     const context = getCurrentValue();
-    expect(context.me.profile?.name).toBe("Test User");
+    assertLoaded(context.me.profile);
+    expect(context.me.profile.name).toBe("Test User");
     expect(context.me.$jazz.id).toBe(accountId);
   });