jazz-tools 0.18.37 → 0.19.0

package/src/tools/coValues/deepLoading.ts

@@ -1,15 +1,10 @@
 import { SessionID } from "cojson";
-import { ItemsSym, TypeSym } from "../internal.js";
+import { CoValueLoadingState, ItemsSym, TypeSym } from "../internal.js";
 import { type Account } from "./account.js";
 import { CoFeedEntry } from "./coFeed.js";
 import { type CoKeys } from "./coMap.js";
 import { type CoValue, type ID } from "./interfaces.js";
 
-/**
- * Similar to {@link NonNullable}, but removes only `null` and preserves `undefined`.
- */
-export type NotNull<T> = Exclude<T, null>;
-
 /**
  * Used to check if T is a union type.
  *
@@ -22,6 +17,47 @@ type IsUnion<T, U = T> = (T extends any ? (x: T) => void : never) extends (
   ? false
   : true;
 
+/**
+ * A CoValue that may or may not be loaded.
+ */
+// T should extend CoValue. We can't enforce this because it would introduce circularity
+// into the definition of CoValues.
+export type MaybeLoaded<T> = T | NotLoaded<T>;
+
+/**
+ * A CoValue that is not loaded.
+ */
+export type NotLoaded<T> = {
+  $jazz: {
+    id: ID<T>;
+    loadingState:
+      | typeof CoValueLoadingState.LOADING
+      | typeof CoValueLoadingState.UNAVAILABLE
+      | typeof CoValueLoadingState.UNAUTHORIZED;
+  };
+  $isLoaded: false;
+};
+
+/**
+ * Narrows a maybe-loaded, optional CoValue to a loaded and required CoValue.
+ */
+export type LoadedAndRequired<T> = Exclude<T, NotLoaded<T> | undefined>;
+
+/**
+ * Narrows a maybe-loaded, optional CoValue to a loaded and optional CoValue
+ */
+export type AsLoaded<T> = Exclude<T, NotLoaded<T>>;
+
+/**
+ * By default, if a nested CoValue is not loaded, the parent CoValue will not be loaded either.
+ * When `$onError: "catch"` is used, the parent CoValue will always be loaded, and an {@link NotLoaded}
+ * value will be returned for the nested CoValue if it cannot be loaded.
+ *
+ * Use `$onError` to handle cases where some data you have requested is inaccessible,
+ * similar to a `try...catch` block in your query.
+ */
+type OnError = { $onError?: "catch" };
+
 export type RefsToResolve<
   V,
   DepthLimit extends number = 10,
@@ -31,41 +67,43 @@ export type RefsToResolve<
   | (DepthLimit extends CurrentDepth["length"]
       ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
         any
-      : IsUnion<NonNullable<V>> extends true
+      : IsUnion<LoadedAndRequired<V>> extends true
         ? true
         : // Basically V extends CoList - but if we used that we'd introduce circularity into the definition of CoList itself
           V extends ReadonlyArray<infer Item>
-          ?
-              | {
-                  $each?: RefsToResolve<
-                    NotNull<Item>,
-                    DepthLimit,
-                    [0, ...CurrentDepth]
-                  >;
-                  $onError?: null;
-                }
-              | boolean
+          ? LoadedAndRequired<Item> extends CoValue
+            ?
+                | ({
+                    $each?: RefsToResolve<
+                      AsLoaded<Item>,
+                      DepthLimit,
+                      [0, ...CurrentDepth]
+                    >;
+                  } & OnError)
+                | boolean
+            : OnError | boolean
           : // Basically V extends CoMap | Group | Account - but if we used that we'd introduce circularity into the definition of CoMap itself
             V extends { [TypeSym]: "CoMap" | "Group" | "Account" }
             ?
                 | ({
-                    [Key in CoKeys<V> as NonNullable<V[Key]> extends CoValue
+                    [Key in CoKeys<V> as LoadedAndRequired<
+                      V[Key]
+                    > extends CoValue
                       ? Key
                       : never]?: RefsToResolve<
-                      NonNullable<V[Key]>,
+                      LoadedAndRequired<V[Key]>,
                       DepthLimit,
                       [0, ...CurrentDepth]
                     >;
-                  } & { $onError?: null })
+                  } & OnError)
                 | (ItemsSym extends keyof V
                     ? {
                         $each: RefsToResolve<
-                          NonNullable<V[ItemsSym]>,
+                          LoadedAndRequired<V[ItemsSym]>,
                           DepthLimit,
                           [0, ...CurrentDepth]
                         >;
-                        $onError?: null;
-                      }
+                      } & OnError
                     : never)
                 | boolean
             : V extends {
@@ -73,18 +111,19 @@ export type RefsToResolve<
                   byMe: CoFeedEntry<infer Item> | undefined;
                 }
               ?
-                  | {
+                  | ({
                       $each: RefsToResolve<
-                        NotNull<Item>,
+                        AsLoaded<Item>,
                         DepthLimit,
                         [0, ...CurrentDepth]
                       >;
-                      $onError?: null;
-                    }
+                    } & OnError)
                   | boolean
-              : boolean);
+              : V extends { [TypeSym]: "CoPlainText" | "BinaryCoStream" }
+                ? boolean | OnError
+                : boolean);
 
-export type RefsToResolveStrict<T, V> = V extends RefsToResolve<T>
+export type RefsToResolveStrict<T, V> = [V] extends [RefsToResolve<T>]
   ? RefsToResolve<T>
   : V;
 
@@ -93,8 +132,12 @@ export type Resolved<
   R extends RefsToResolve<T> | undefined = true,
 > = DeeplyLoaded<T, R, 10, []>;
 
-type onErrorNullEnabled<Depth> = Depth extends { $onError: null }
-  ? null
+/**
+ * If the resolve query contains `$onError: "catch"`, we return a not loaded value for this nested CoValue.
+ * Otherwise, the whole load operation returns a not-loaded value.
+ */
+type OnErrorResolvedValue<V, Depth> = Depth extends { $onError: "catch" }
+  ? NotLoaded<V>
   : never;
 
 type CoMapLikeLoaded<
@@ -104,16 +147,16 @@ type CoMapLikeLoaded<
   CurrentDepth extends number[],
 > = {
   readonly [Key in keyof Omit<Depth, "$onError">]-?: Key extends CoKeys<V>
-    ? NonNullable<V[Key]> extends CoValue
+    ? LoadedAndRequired<V[Key]> extends CoValue
       ?
           | DeeplyLoaded<
-              NonNullable<V[Key]>,
+              LoadedAndRequired<V[Key]>,
               Depth[Key],
               DepthLimit,
               [0, ...CurrentDepth]
             >
           | (undefined extends V[Key] ? undefined : never)
-          | onErrorNullEnabled<Depth[Key]>
+          | OnErrorResolvedValue<V[Key], Depth[Key]>
       : never
     : never;
 } & V;
@@ -125,22 +168,23 @@ export type DeeplyLoaded<
   CurrentDepth extends number[] = [],
 > = DepthLimit extends CurrentDepth["length"]
   ? V
-  : Depth extends boolean | undefined // Checking against boolean instead of true because the inference from RefsToResolveStrict transforms true into boolean
+  : Depth extends true | undefined
     ? V
     : // Basically V extends CoList - but if we used that we'd introduce circularity into the definition of CoList itself
       [V] extends [ReadonlyArray<infer Item>]
-      ? NotNull<Item> extends CoValue
+      ? // `& {}` forces TypeScript to simplify the type before performing the `extends CoValue` check.
+        // Without it, the check would fail even when it should succeed.
+        AsLoaded<Item & {}> extends CoValue
         ? Depth extends { $each: infer ItemDepth }
           ? // Deeply loaded CoList
             ReadonlyArray<
-              | (NotNull<Item> &
-                  DeeplyLoaded<
-                    NotNull<Item>,
-                    ItemDepth,
-                    DepthLimit,
-                    [0, ...CurrentDepth]
-                  >)
-              | onErrorNullEnabled<Depth["$each"]>
+              | DeeplyLoaded<
+                  AsLoaded<Item>,
+                  ItemDepth,
+                  DepthLimit,
+                  [0, ...CurrentDepth]
+                >
+              | OnErrorResolvedValue<AsLoaded<Item>, Depth["$each"]>
             > &
               V // the CoList base type needs to be intersected after so that built-in methods return the correct narrowed array type
           : never
@@ -152,17 +196,20 @@ export type DeeplyLoaded<
           ? V
           : // 1. Record-like CoMap
             ItemsSym extends keyof V
-            ? // 1.1. Deeply loaded Record-like CoMap with { $each: true | {$onError: null} }
+            ? // 1.1. Deeply loaded Record-like CoMap with { $each: true | { $onError: 'catch' } }
               Depth extends { $each: infer ItemDepth }
               ? {
                   readonly [key: string]:
                     | DeeplyLoaded<
-                        NonNullable<V[ItemsSym]>,
+                        LoadedAndRequired<V[ItemsSym]>,
                         ItemDepth,
                         DepthLimit,
                         [0, ...CurrentDepth]
                       >
-                    | onErrorNullEnabled<Depth["$each"]>;
+                    | OnErrorResolvedValue<
+                        LoadedAndRequired<V[ItemsSym]>,
+                        Depth["$each"]
+                      >;
                 } & V // same reason as in CoList
               : // 1.2. Deeply loaded Record-like CoMap with { [key: string]: true }
                 string extends keyof Depth
@@ -180,12 +227,12 @@ export type DeeplyLoaded<
             ]
           ? // Deeply loaded CoStream
             {
-              byMe?: { value: NotNull<Item> };
-              inCurrentSession?: { value: NotNull<Item> };
+              byMe?: { value: AsLoaded<Item> };
+              inCurrentSession?: { value: AsLoaded<Item> };
               perSession: {
-                [key: SessionID]: { value: NotNull<Item> };
+                [key: SessionID]: { value: AsLoaded<Item> };
               };
-            } & { [key: ID<Account>]: { value: NotNull<Item> } } & V // same reason as in CoList
+            } & { [key: ID<Account>]: { value: AsLoaded<Item> } } & V // same reason as in CoList
           : [V] extends [
                 {
                   [TypeSym]: "BinaryCoStream";

package/src/tools/coValues/group.ts

@@ -14,6 +14,7 @@ import {
   CoValue,
   CoValueClass,
   ID,
+  MaybeLoaded,
   RefEncoded,
   RefsToResolve,
   RefsToResolveStrict,
@@ -278,7 +279,7 @@ export class Group extends CoValueBase implements CoValue {
       resolve?: RefsToResolveStrict<G, R>;
       loadAs?: Account | AnonymousJazzAgent;
     },
-  ): Promise<Resolved<G, R> | null> {
+  ): Promise<MaybeLoaded<Resolved<G, R>>> {
     return loadCoValueWithoutMe(this, id, options);
   }
 
@@ -323,7 +324,7 @@ export class Group extends CoValueBase implements CoValue {
     const group = await loadCoValueWithoutMe(this, id, {
       loadAs: options?.loadAs,
     });
-    if (!group) {
+    if (!group.$isLoaded) {
       throw new Error(`Group with id ${id} not found`);
     }
     return group.$jazz.createInvite(options?.role ?? "reader");

package/src/tools/coValues/inbox.ts

@@ -11,13 +11,14 @@ import {
   type Account,
   CoValue,
   CoValueClassOrSchema,
+  CoValueLoadingState,
   ID,
   InstanceOfSchema,
   activeAccountContext,
   coValueClassFromCoValueClassOrSchema,
   loadCoValue,
 } from "../internal.js";
-import { isCoValueId } from "../lib/id.js";
+import { isCoValueId } from "../lib/utils.js";
 
 export type InboxInvite = `${CoID<MessagesStream>}/${InviteSecret}`;
 type TxKey = `${SessionID}/${number}`;
@@ -224,7 +225,7 @@ export class Inbox {
       messageId: CoID<InboxMessage<CoValue, any>>,
     ) => {
       const message = await node.load(messageId);
-      if (message === "unavailable") {
+      if (message === CoValueLoadingState.UNAVAILABLE) {
         throw new Error(`Inbox: message ${messageId} is unavailable`);
       }
 
@@ -331,7 +332,7 @@ export class Inbox {
   static async load(account: Account) {
     const profile = account.profile;
 
-    if (!profile) {
+    if (!profile.$isLoaded) {
       throw new Error("Account profile should already be loaded");
     }
 
@@ -343,7 +344,7 @@ export class Inbox {
 
     const root = await node.load(profile.inbox as CoID<InboxRoot>);
 
-    if (root === "unavailable") {
+    if (root === CoValueLoadingState.UNAVAILABLE) {
       throw new Error("Inbox not found");
     }
 
@@ -354,9 +355,9 @@ export class Inbox {
     ]);
 
     if (
-      messages === "unavailable" ||
-      processed === "unavailable" ||
-      failed === "unavailable"
+      messages === CoValueLoadingState.UNAVAILABLE ||
+      processed === CoValueLoadingState.UNAVAILABLE ||
+      failed === CoValueLoadingState.UNAVAILABLE
     ) {
       throw new Error("Inbox not found");
     }
@@ -421,13 +422,13 @@ export class InboxSender<I extends CoValue, O extends CoValue | undefined> {
       inboxOwnerID as unknown as CoID<RawAccount>,
     );
 
-    if (inboxOwnerRaw === "unavailable") {
+    if (inboxOwnerRaw === CoValueLoadingState.UNAVAILABLE) {
       throw new Error("Failed to load the inbox owner");
     }
 
     const inboxOwnerProfileRaw = await node.load(inboxOwnerRaw.get("profile")!);
 
-    if (inboxOwnerProfileRaw === "unavailable") {
+    if (inboxOwnerProfileRaw === CoValueLoadingState.UNAVAILABLE) {
       throw new Error("Failed to load the inbox owner profile");
     }
 
@@ -453,7 +454,7 @@ export class InboxSender<I extends CoValue, O extends CoValue | undefined> {
 
     const messages = await node.load(id);
 
-    if (messages === "unavailable") {
+    if (messages === CoValueLoadingState.UNAVAILABLE) {
       throw new Error("Inbox not found");
     }
 

package/src/tools/coValues/interfaces.ts

@@ -9,8 +9,11 @@ import {
   Account,
   AnonymousJazzAgent,
   CoValueClassOrSchema,
+  CoValueLoadingState,
+  NotLoadedCoValueState,
   type Group,
   Loaded,
+  MaybeLoaded,
   RefsToResolve,
   RefsToResolveStrict,
   RegisteredSchemas,
@@ -20,6 +23,7 @@ import {
   SubscriptionScope,
   type SubscriptionValue,
   TypeSym,
+  NotLoaded,
   activeAccountContext,
   coValueClassFromCoValueClassOrSchema,
   getSubscriptionScope,
@@ -49,6 +53,8 @@ export interface CoValue {
   $jazz: {
     /** @category Content */
     readonly id: ID<CoValue>;
+    /** @category Content */
+    loadingState: typeof CoValueLoadingState.LOADED;
     /** @category Collaboration */
     owner?: Group;
     /** @internal */
@@ -61,6 +67,11 @@ export interface CoValue {
     branchName: string | undefined;
     unstable_merge: () => void;
   };
+  /**
+   * Whether the CoValue is loaded. Can be used to distinguish between loaded and {@link NotLoaded} CoValues.
+   * For more information about the CoValue's loading state, use {@link $jazz.loadingState}.
+   */
+  $isLoaded: true;
 
   /** @category Stringifying & Inspection */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -96,6 +107,16 @@ export function isCoValueClass<V extends CoValue>(
  */
 export type ID<T> = string;
 
+export function createUnloadedCoValue<T extends CoValue>(
+  id: ID<T>,
+  loadingState: NotLoadedCoValueState,
+): NotLoaded<T> {
+  return {
+    $jazz: { id, loadingState },
+    $isLoaded: false,
+  };
+}
+
 export function loadCoValueWithoutMe<
   V extends CoValue,
   const R extends RefsToResolve<V>,
@@ -108,7 +129,7 @@ export function loadCoValueWithoutMe<
     skipRetry?: boolean;
     unstable_branch?: BranchDefinition;
   },
-): Promise<Resolved<V, R> | null> {
+): Promise<MaybeLoaded<Resolved<V, R>>> {
   return loadCoValue(cls, id, {
     ...options,
     loadAs: options?.loadAs ?? activeAccountContext.get(),
@@ -128,7 +149,7 @@ export function loadCoValue<
     skipRetry?: boolean;
     unstable_branch?: BranchDefinition;
   },
-): Promise<Resolved<V, R> | null> {
+): Promise<MaybeLoaded<Resolved<V, R>>> {
   return new Promise((resolve) => {
     subscribeToCoValue<V, R>(
       cls,
@@ -139,10 +160,10 @@ export function loadCoValue<
         syncResolution: true,
         skipRetry: options.skipRetry,
         onUnavailable: () => {
-          resolve(null);
+          resolve(createUnloadedCoValue(id, CoValueLoadingState.UNAVAILABLE));
         },
         onUnauthorized: () => {
-          resolve(null);
+          resolve(createUnloadedCoValue(id, CoValueLoadingState.UNAUTHORIZED));
         },
         unstable_branch: options.unstable_branch,
       },
@@ -176,7 +197,7 @@ export async function ensureCoValueLoaded<
     },
   );
 
-  if (!response) {
+  if (!response.$isLoaded) {
     throw new Error("Failed to deeply load CoValue " + existing.$jazz.id);
   }
 
@@ -300,18 +321,18 @@ export function subscribeToCoValue<
   const handleUpdate = (value: SubscriptionValue<V, any>) => {
     if (unsubscribed) return;
 
-    if (value.type === "unavailable") {
+    if (value.type === CoValueLoadingState.UNAVAILABLE) {
       options.onUnavailable?.();
 
       // Don't log unavailable errors when `loadUnique` or `upsertUnique` are used
       if (!options.skipRetry) {
         console.error(value.toString());
       }
-    } else if (value.type === "unauthorized") {
+    } else if (value.type === CoValueLoadingState.UNAUTHORIZED) {
       options.onUnauthorized?.();
 
       console.error(value.toString());
-    } else if (value.type === "loaded") {
+    } else if (value.type === CoValueLoadingState.LOADED) {
       listener(value.value as Resolved<V, R>, unsubscribe);
     }
   };
@@ -472,7 +493,7 @@ export async function unstable_loadUnique<
     owner: Account | Group;
     resolve?: ResolveQueryStrict<S, R>;
   },
-): Promise<Loaded<S, R> | null> {
+): Promise<MaybeLoaded<Loaded<S, R>>> {
   const cls = coValueClassFromCoValueClassOrSchema(schema);
 
   if (
@@ -484,15 +505,14 @@ export async function unstable_loadUnique<
 
   const header = cls._getUniqueHeader(options.unique, options.owner.$jazz.id);
 
+  // @ts-expect-error the CoValue class is too generic for TS to infer its instances are CoValues
   return internalLoadUnique(cls, {
     header,
     onCreateWhenMissing: options.onCreateWhenMissing,
-    // @ts-expect-error loaded is not compatible with Resolved at type level, but they are the same thing
     onUpdateWhenFound: options.onUpdateWhenFound,
     owner: options.owner,
-    // @ts-expect-error loaded is not compatible with Resolved at type level, but they are the same thing
     resolve: options.resolve,
-  }) as unknown as Loaded<S, R> | null;
+  }) as unknown as MaybeLoaded<Loaded<S, R>>;
 }
 
 export async function internalLoadUnique<
@@ -507,7 +527,7 @@ export async function internalLoadUnique<
     owner: Account | Group;
     resolve?: RefsToResolveStrict<V, R>;
   },
-): Promise<Resolved<V, R> | null> {
+): Promise<MaybeLoaded<Resolved<V, R>>> {
   const loadAs = options.owner.$jazz.loadedAs;
 
   const node =
@@ -519,7 +539,7 @@ export async function internalLoadUnique<
   // retrying failures
   // This way when we want to upsert we are sure that, if the load failed
   // it failed because the unique value was missing
-  await loadCoValueWithoutMe(cls, id, {
+  const maybeLoadedCoValue = await loadCoValueWithoutMe(cls, id, {
     skipRetry: true,
     loadAs,
   });
@@ -539,7 +559,9 @@ export async function internalLoadUnique<
   }
 
   if (!isAvailable) {
-    return null;
+    // @ts-expect-error the resolve query of the loaded values is not necessarily the same,
+    // but we're only returning not-loaded values
+    return maybeLoadedCoValue;
   }
 
   if (options.onUpdateWhenFound) {
@@ -549,7 +571,7 @@ export async function internalLoadUnique<
       resolve: options.resolve,
     });
 
-    if (loaded) {
+    if (loaded.$isLoaded) {
       // we don't return the update result because
       // we want to run another load to backfill any possible partially loaded
       // values that have been set in the update
@@ -642,13 +664,13 @@ export async function exportCoValue<
 
   const value = await new Promise<Loaded<S, R> | null>((resolve) => {
     rootNode.setListener((value) => {
-      if (value.type === "unavailable") {
+      if (value.type === CoValueLoadingState.UNAVAILABLE) {
         resolve(null);
         console.error(value.toString());
-      } else if (value.type === "unauthorized") {
+      } else if (value.type === CoValueLoadingState.UNAUTHORIZED) {
         resolve(null);
         console.error(value.toString());
-      } else if (value.type === "loaded") {
+      } else if (value.type === CoValueLoadingState.LOADED) {
         resolve(value.value as Loaded<S, R>);
       }
 
@@ -679,10 +701,10 @@ function loadContentPiecesFromSubscription(
 
   valuesExported.add(subscription.id);
 
-  const core = subscription.getCurrentValue()?.$jazz.raw
-    .core as AvailableCoValueCore;
+  const currentValue = subscription.getCurrentValue();
 
-  if (core) {
+  if (typeof currentValue !== "string") {
+    const core = currentValue.$jazz.raw.core as AvailableCoValueCore;
     loadContentPiecesFromCoValue(core, valuesExported, contentPieces);
   }
 
@@ -742,7 +764,7 @@ export function unstable_mergeBranch(
   }
 
   function handleMerge(subscriptionNode: SubscriptionScope<CoValue>) {
-    if (subscriptionNode.value.type === "loaded") {
+    if (subscriptionNode.value.type === CoValueLoadingState.LOADED) {
       subscriptionNode.value.value.$jazz.raw.core.mergeBranch();
     }
 
@@ -762,7 +784,7 @@ export async function unstable_mergeBranchWithResolve<
   id: ID<CoValue>,
   options: {
     resolve?: ResolveQueryStrict<S, R>;
-    loadAs: Account | AnonymousJazzAgent;
+    loadAs?: Account | AnonymousJazzAgent;
     branch: BranchDefinition;
   },
 ) {
@@ -786,11 +808,11 @@ export async function unstable_mergeBranchWithResolve<
 
   await new Promise<void>((resolve, reject) => {
     rootNode.setListener((value) => {
-      if (value.type === "unavailable") {
+      if (value.type === CoValueLoadingState.UNAVAILABLE) {
         reject(new Error("Unable to load the branch. " + value.toString()));
-      } else if (value.type === "unauthorized") {
+      } else if (value.type === CoValueLoadingState.UNAUTHORIZED) {
         reject(new Error("Unable to load the branch. " + value.toString()));
-      } else if (value.type === "loaded") {
+      } else if (value.type === CoValueLoadingState.LOADED) {
         resolve();
       }
 

package/src/tools/coValues/request.ts

@@ -14,6 +14,8 @@ import {
   CoMapSchemaInit,
   CoValueClass,
   CoreCoMapSchema,
+  CoValueLoadingState,
+  createUnloadedCoValue,
   Group,
   Loaded,
   ResolveQuery,
@@ -25,7 +27,7 @@ import {
   importContentPieces,
   loadCoValue,
 } from "../internal.js";
-import { isCoValueId } from "../lib/id.js";
+import { isCoValueId } from "../lib/utils.js";
 import { Account } from "./account.js";
 
 type MessageShape = Record<string, AnyZodOrCoValueSchema>;
@@ -289,7 +291,7 @@ async function handleMessagePayload({
     loadAs,
   });
 
-  if (!madeBy) {
+  if (!madeBy.$isLoaded) {
     throw new JazzRequestError("Creator account not found", 400);
   }
 
@@ -301,7 +303,7 @@ async function handleMessagePayload({
     loadAs,
   });
 
-  if (!value) {
+  if (!value.$isLoaded) {
     throw new JazzRequestError("Value not found", 400);
   }
 
@@ -375,7 +377,7 @@ export class HttpRoute<
     const as = options?.owner ?? Account.getMe();
 
     const target = await loadWorkerAccountOrGroup(this.workerId, as);
-    if (!target) {
+    if (!target.$isLoaded) {
       throw new JazzRequestError("Worker account not found", 400);
     }
 
@@ -619,7 +621,7 @@ async function loadWorkerAccountOrGroup(id: string, loadAs: Account) {
   const coValue = await node.loadCoValueCore(id as `co_z${string}`);
 
   if (!coValue.isAvailable()) {
-    return null;
+    return createUnloadedCoValue(id, CoValueLoadingState.UNAVAILABLE);
   }
 
   const content = coValue.getCurrentContent();
@@ -782,7 +784,7 @@ export async function parseAuthToken(
 
   const account = await Account.load(id, { loadAs: options?.loadAs });
 
-  if (!account) {
+  if (!account.$isLoaded) {
     return {
       error: {
         message: "Failed to load account",

package/src/tools/coValues/schemaUnion.ts

@@ -10,6 +10,7 @@ import {
   CoValueJazzApi,
   Group,
   ID,
+  MaybeLoaded,
   Resolved,
   Simplify,
   SubscribeListenerOptions,
@@ -160,7 +161,7 @@ export abstract class SchemaUnion extends CoValueBase implements CoValue {
       loadAs?: Account | AnonymousJazzAgent;
       skipRetry?: boolean;
     },
-  ): Promise<Resolved<M, true> | null> {
+  ): Promise<MaybeLoaded<Resolved<M, true>>> {
     return loadCoValueWithoutMe(this, id, options);
   }