jazz-tools 0.18.37 → 0.19.0

package/src/tools/coValues/account.ts

@@ -27,6 +27,7 @@ import {
   Group,
   ID,
   InstanceOrPrimitiveOfSchema,
+  MaybeLoaded,
   Profile,
   Ref,
   type RefEncoded,
@@ -53,6 +54,8 @@ import {
   parseSubscribeRestArgs,
   subscribeToCoValueWithoutMe,
   subscribeToExistingCoValue,
+  InstanceOfSchemaCoValuesMaybeLoaded,
+  LoadedAndRequired,
 } from "../internal.js";
 
 export type AccountCreationProps = {
@@ -84,8 +87,8 @@ export class Account extends CoValueBase implements CoValue {
     } satisfies RefEncoded<CoMap>,
   };
 
-  declare readonly profile: Profile | null;
-  declare readonly root: CoMap | null;
+  declare readonly profile: MaybeLoaded<Profile>;
+  declare readonly root: MaybeLoaded<CoMap>;
 
   constructor(options: { fromRaw: RawAccount }) {
     super();
@@ -128,7 +131,9 @@ export class Account extends CoValueBase implements CoValue {
     valueID: string,
     inviteSecret: InviteSecret,
     coValueClass?: S,
-  ): Promise<Resolved<InstanceOrPrimitiveOfSchema<S>, true> | null> {
+  ): Promise<
+    MaybeLoaded<Resolved<InstanceOfSchemaCoValuesMaybeLoaded<S>, true>>
+  > {
     if (!this.$jazz.isLocalNodeOwner) {
       throw new Error("Only a controlled account can accept invites");
     }
@@ -144,7 +149,7 @@ export class Account extends CoValueBase implements CoValue {
       {
         loadAs: this,
       },
-    ) as Resolved<InstanceOrPrimitiveOfSchema<S>, true> | null;
+    ) as Resolved<InstanceOfSchemaCoValuesMaybeLoaded<S>, true>;
   }
 
   getRoleOf(member: Everyone | ID<Account> | "me"): "admin" | undefined {
@@ -351,7 +356,7 @@ export class Account extends CoValueBase implements CoValue {
       resolve?: RefsToResolveStrict<A, R>;
       loadAs?: Account | AnonymousJazzAgent;
     },
-  ): Promise<Resolved<A, R> | null> {
+  ): Promise<MaybeLoaded<Resolved<A, R>>> {
     return loadCoValueWithoutMe(this, id, options);
   }
 
@@ -419,7 +424,7 @@ class AccountJazzApi<A extends Account> extends CoValueJazzApi<A> {
    */
   set<K extends "root" | "profile">(
     key: K,
-    value: CoFieldInit<NonNullable<A[K]>>,
+    value: CoFieldInit<LoadedAndRequired<A[K]>>,
   ) {
     if (value) {
       let refId = (value as unknown as CoValue).$jazz?.id as
@@ -470,10 +475,10 @@ class AccountJazzApi<A extends Account> extends CoValueJazzApi<A> {
     root: RefIfCoValue<CoMap> | undefined;
   } {
     const profileID = this.raw.get("profile") as unknown as
-      | ID<NonNullable<(typeof this.account)["profile"]>>
+      | ID<LoadedAndRequired<(typeof this.account)["profile"]>>
       | undefined;
     const rootID = this.raw.get("root") as unknown as
-      | ID<NonNullable<(typeof this.account)["root"]>>
+      | ID<LoadedAndRequired<(typeof this.account)["root"]>>
       | undefined;
 
     return {
@@ -482,20 +487,20 @@ class AccountJazzApi<A extends Account> extends CoValueJazzApi<A> {
             profileID,
             this.loadedAs,
             this.schema.profile as RefEncoded<
-              NonNullable<(typeof this.account)["profile"]> & CoValue
+              LoadedAndRequired<(typeof this.account)["profile"]> & CoValue
             >,
             this.account,
-          ) as unknown as RefIfCoValue<(typeof this.account)["profile"]>)
+          ) as unknown as RefIfCoValue<Profile> | undefined)
         : undefined,
       root: rootID
         ? (new Ref(
             rootID,
             this.loadedAs,
             this.schema.root as RefEncoded<
-              NonNullable<(typeof this.account)["root"]> & CoValue
+              LoadedAndRequired<(typeof this.account)["root"]> & CoValue
             >,
             this.account,
-          ) as unknown as RefIfCoValue<(typeof this.account)["root"]>)
+          ) as unknown as RefIfCoValue<CoMap> | undefined)
         : undefined,
     };
   }

package/src/tools/coValues/coFeed.ts

@@ -15,9 +15,12 @@ import {
   CoFieldInit,
   CoValue,
   CoValueClass,
+  CoValueLoadingState,
   getCoValueOwner,
   Group,
   ID,
+  MaybeLoaded,
+  LoadedAndRequired,
   unstable_mergeBranch,
   RefsToResolve,
   RefsToResolveStrict,
@@ -60,8 +63,12 @@ export type CoFeedEntry<Item> = SingleCoFeedEntry<Item> & {
 export type SingleCoStreamEntry<Item> = SingleCoFeedEntry<Item>;
 
 export type SingleCoFeedEntry<Item> = {
-  value: NonNullable<Item> extends CoValue ? NonNullable<Item> | null : Item;
-  ref: NonNullable<Item> extends CoValue ? Ref<NonNullable<Item>> : never;
+  value: LoadedAndRequired<Item> extends CoValue
+    ? MaybeLoaded<LoadedAndRequired<Item>>
+    : Item;
+  ref: LoadedAndRequired<Item> extends CoValue
+    ? Ref<LoadedAndRequired<Item>>
+    : never;
   by: Account | null;
   madeAt: Date;
   tx: CojsonInternalTypes.TransactionID;
@@ -290,7 +297,7 @@ export class CoFeed<out Item = any> extends CoValueBase implements CoValue {
       resolve?: RefsToResolveStrict<F, R>;
       loadAs?: Account | AnonymousJazzAgent;
     },
-  ): Promise<Resolved<F, R> | null> {
+  ): Promise<MaybeLoaded<Resolved<F, R>>> {
     return loadCoValueWithoutMe(this, id, options ?? {});
   }
 
@@ -466,12 +473,12 @@ function entryFromRawEntry<Item>(
   itemField: Schema,
 ): Omit<CoFeedEntry<Item>, "all"> {
   return {
-    get value(): NonNullable<Item> extends CoValue
-      ? (CoValue & Item) | null
+    get value(): LoadedAndRequired<Item> extends CoValue
+      ? MaybeLoaded<CoValue & Item>
       : Item {
       if (itemField === "json") {
-        return rawEntry.value as NonNullable<Item> extends CoValue
-          ? (CoValue & Item) | null
+        return rawEntry.value as LoadedAndRequired<Item> extends CoValue
+          ? MaybeLoaded<CoValue & Item>
           : Item;
       } else if ("encoded" in itemField) {
         return itemField.encoded.decode(rawEntry.value);
@@ -480,13 +487,15 @@ function entryFromRawEntry<Item>(
           accessFrom,
           rawEntry.value as string,
           itemField,
-        ) as NonNullable<Item> extends CoValue ? (CoValue & Item) | null : Item;
+        ) as LoadedAndRequired<Item> extends CoValue
+          ? MaybeLoaded<CoValue & Item>
+          : Item;
       } else {
         throw new Error("Invalid item field schema");
       }
     },
-    get ref(): NonNullable<Item> extends CoValue
-      ? Ref<NonNullable<Item>>
+    get ref(): LoadedAndRequired<Item> extends CoValue
+      ? Ref<LoadedAndRequired<Item>>
       : never {
       if (itemField !== "json" && isRefEncoded(itemField)) {
         const rawId = rawEntry.value;
@@ -495,7 +504,9 @@ function entryFromRawEntry<Item>(
           loadedAs,
           itemField,
           accessFrom,
-        ) as NonNullable<Item> extends CoValue ? Ref<NonNullable<Item>> : never;
+        ) as LoadedAndRequired<Item> extends CoValue
+          ? Ref<LoadedAndRequired<Item>>
+          : never;
       } else {
         return undefined as never;
       }
@@ -787,7 +798,11 @@ export class FileStream extends CoValueBase implements CoValue {
   ): Promise<Blob | undefined> {
     let stream = await this.load(id, options);
 
-    return stream?.toBlob({
+    if (!stream.$isLoaded) {
+      return undefined;
+    }
+
+    return stream.toBlob({
       allowUnfinished: options?.allowUnfinished,
     });
   }
@@ -802,7 +817,11 @@ export class FileStream extends CoValueBase implements CoValue {
   ): Promise<string | undefined> {
     const stream = await this.load(id, options);
 
-    return stream?.asBase64(options);
+    if (!stream.$isLoaded) {
+      return undefined;
+    }
+
+    return stream.asBase64(options);
   }
 
   asBase64(options?: {
@@ -961,14 +980,18 @@ export class FileStream extends CoValueBase implements CoValue {
       loadAs?: Account | AnonymousJazzAgent;
       allowUnfinished?: boolean;
     },
-  ): Promise<FileStream | null> {
+  ): Promise<MaybeLoaded<FileStream>> {
     const stream = await loadCoValueWithoutMe(this, id, options);
 
     /**
      * If the user hasn't requested an incomplete blob and the
      * stream isn't complete wait for the stream download before progressing
      */
-    if (!options?.allowUnfinished && !stream?.isBinaryStreamEnded()) {
+    if (
+      !options?.allowUnfinished &&
+      stream.$isLoaded &&
+      !stream.isBinaryStreamEnded()
+    ) {
       return new Promise<FileStream>((resolve) => {
         subscribeToCoValueWithoutMe(
           this,

package/src/tools/coValues/coList.ts

@@ -10,6 +10,8 @@ import {
   getCoValueOwner,
   Group,
   ID,
+  AsLoaded,
+  MaybeLoaded,
   unstable_mergeBranch,
   RefEncoded,
   RefsToResolve,
@@ -23,6 +25,7 @@ import {
   BranchDefinition,
   getIdFromHeader,
   internalLoadUnique,
+  CoValueLoadingState,
 } from "../internal.js";
 import {
   AnonymousJazzAgent,
@@ -71,6 +74,7 @@ export class CoList<out Item = any>
   implements ReadonlyArray<Item>, CoValue
 {
   declare $jazz: CoListJazzApi<this>;
+  declare $isLoaded: true;
 
   /**
    * Declare a `CoList` by subclassing `CoList.Of(...)` and passing the item schema using `co`.
@@ -128,6 +132,7 @@ export class CoList<out Item = any>
           value: new CoListJazzApi(proxy, () => options.fromRaw),
           enumerable: false,
         },
+        $isLoaded: { value: true, enumerable: false },
       });
     }
 
@@ -175,6 +180,7 @@ export class CoList<out Item = any>
         value: new CoListJazzApi(instance, () => raw),
         enumerable: false,
       },
+      $isLoaded: { value: true, enumerable: false },
     });
 
     const raw = owner.$jazz.raw.createList(
@@ -262,7 +268,7 @@ export class CoList<out Item = any>
       resolve?: RefsToResolveStrict<L, R>;
       loadAs?: Account | AnonymousJazzAgent;
     },
-  ): Promise<Resolved<L, R> | null> {
+  ): Promise<MaybeLoaded<Resolved<L, R>>> {
     return loadCoValueWithoutMe(this, id, options);
   }
 
@@ -346,7 +352,7 @@ export class CoList<out Item = any>
   /**
    * Given some data, updates an existing CoList or initialises a new one if none exists.
    *
-   * Note: This method respects resolve options, and thus can return `null` if the references cannot be resolved.
+   * Note: This method respects resolve options, and thus can return a not-loaded value if the references cannot be resolved.
    *
    * @example
    * ```ts
@@ -374,7 +380,7 @@ export class CoList<out Item = any>
       owner: Account | Group;
       resolve?: RefsToResolveStrict<L, R>;
     },
-  ): Promise<Resolved<L, R> | null> {
+  ): Promise<MaybeLoaded<Resolved<L, R>>> {
     const header = CoList._getUniqueHeader(
       options.unique,
       options.owner.$jazz.id,
@@ -401,7 +407,7 @@ export class CoList<out Item = any>
    * @param unique The unique identifier of the CoList to load.
    * @param ownerID The ID of the owner of the CoList.
    * @param options Additional options for loading the CoList.
-   * @returns The loaded CoList, or null if unavailable.
+   * @returns The loaded CoList, or an not-loaded value if unavailable.
    */
   static async loadUnique<
     L extends CoList,
@@ -414,14 +420,13 @@ export class CoList<out Item = any>
       resolve?: RefsToResolveStrict<L, R>;
       loadAs?: Account | AnonymousJazzAgent;
     },
-  ): Promise<Resolved<L, R> | null> {
+  ): Promise<MaybeLoaded<Resolved<L, R>>> {
     const header = CoList._getUniqueHeader(unique, ownerID);
 
     const owner = await Group.load(ownerID, {
       loadAs: options?.loadAs,
     });
-
-    if (!owner) return owner;
+    if (!owner.$isLoaded) return owner;
 
     return internalLoadUnique(this, {
       header,
@@ -839,14 +844,14 @@ export class CoListJazzApi<L extends CoList> extends CoValueJazzApi<L> {
    * @category Content
    **/
   get refs(): {
-    [idx: number]: Exclude<CoListItem<L>, null> extends CoValue
-      ? Ref<Exclude<CoListItem<L>, null>>
+    [idx: number]: AsLoaded<CoListItem<L>> extends CoValue
+      ? Ref<AsLoaded<CoListItem<L>>>
       : never;
   } & {
     length: number;
     [Symbol.iterator](): IterableIterator<
-      Exclude<CoListItem<L>, null> extends CoValue
-        ? Ref<Exclude<CoListItem<L>, null>>
+      AsLoaded<CoListItem<L>> extends CoValue
+        ? Ref<AsLoaded<CoListItem<L>>>
         : never
     >;
   } {

package/src/tools/coValues/coMap.ts

@@ -10,12 +10,15 @@ import {
 } from "cojson";
 import {
   AnonymousJazzAgent,
+  AsLoaded,
+  LoadedAndRequired,
   CoFieldInit,
   CoValue,
   CoValueClass,
   getCoValueOwner,
   Group,
   ID,
+  MaybeLoaded,
   PartialOnUndefined,
   RefEncoded,
   RefIfCoValue,
@@ -30,13 +33,11 @@ import {
   BranchDefinition,
   getIdFromHeader,
   internalLoadUnique,
-} from "../internal.js";
-import {
   Account,
   CoValueBase,
   CoValueJazzApi,
+  CoValueLoadingState,
   ItemsSym,
-  NotNull,
   Ref,
   RegisteredSchemas,
   SchemaInit,
@@ -55,7 +56,7 @@ import {
   subscribeToExistingCoValue,
 } from "../internal.js";
 
-type CoMapEdit<V> = {
+export type CoMapEdit<V> = {
   value?: V;
   ref?: RefIfCoValue<V>;
   by: Account | null;
@@ -63,9 +64,9 @@ type CoMapEdit<V> = {
   key?: string;
 };
 
-type LastAndAllCoMapEdits<V> = CoMapEdit<V> & { all: CoMapEdit<V>[] };
+export type LastAndAllCoMapEdits<V> = CoMapEdit<V> & { all: CoMapEdit<V>[] };
 
-type CoMapEdits<M extends CoMap> = {
+export type CoMapEdits<M extends CoMap> = {
   [Key in CoKeys<M>]?: LastAndAllCoMapEdits<M[Key]>;
 };
 
@@ -376,7 +377,7 @@ export class CoMap extends CoValueBase implements CoValue {
       loadAs?: Account | AnonymousJazzAgent;
       skipRetry?: boolean;
     },
-  ): Promise<Resolved<M, R> | null> {
+  ): Promise<MaybeLoaded<Resolved<M, R>>> {
     return loadCoValueWithoutMe(this, id, options);
   }
 
@@ -460,7 +461,7 @@ export class CoMap extends CoValueBase implements CoValue {
   /**
    * Given some data, updates an existing CoMap or initialises a new one if none exists.
    *
-   * Note: This method respects resolve options, and thus can return `null` if the references cannot be resolved.
+   * Note: This method respects resolve options, and thus can return a not-loaded value if the references cannot be resolved.
    *
    * @example
    * ```ts
@@ -493,7 +494,7 @@ export class CoMap extends CoValueBase implements CoValue {
       owner: Account | Group;
       resolve?: RefsToResolveStrict<M, R>;
     },
-  ): Promise<Resolved<M, R> | null> {
+  ): Promise<MaybeLoaded<Resolved<M, R>>> {
     const header = CoMap._getUniqueHeader(
       options.unique,
       options.owner.$jazz.id,
@@ -520,7 +521,7 @@ export class CoMap extends CoValueBase implements CoValue {
    * @param unique The unique identifier of the CoMap to load.
    * @param ownerID The ID of the owner of the CoMap.
    * @param options Additional options for loading the CoMap.
-   * @returns The loaded CoMap, or null if unavailable.
+   * @returns The loaded CoMap, or an not-loaded value if unavailable.
    *
    * @deprecated Use `co.map(...).loadUnique` instead.
    */
@@ -535,14 +536,14 @@ export class CoMap extends CoValueBase implements CoValue {
       resolve?: RefsToResolveStrict<M, R>;
       loadAs?: Account | AnonymousJazzAgent;
     },
-  ): Promise<Resolved<M, R> | null> {
+  ): Promise<MaybeLoaded<Resolved<M, R>>> {
     const header = CoMap._getUniqueHeader(unique, ownerID);
 
     const owner = await Group.load(ownerID, {
       loadAs: options?.loadAs,
     });
 
-    if (!owner) return owner;
+    if (!owner.$isLoaded) return owner;
 
     return internalLoadUnique(this, {
       header,
@@ -757,12 +758,12 @@ class CoMapJazzApi<M extends CoMap> extends CoValueJazzApi<M> {
    **/
   get refs(): Simplify<
     {
-      [Key in CoKeys<M> as NonNullable<M[Key]> extends CoValue
+      [Key in CoKeys<M> as LoadedAndRequired<M[Key]> extends CoValue
         ? Key
         : never]?: RefIfCoValue<M[Key]>;
     } & {
       // Non-loaded CoValue refs (i.e. refs with type CoValue | null) are still required refs
-      [Key in CoKeys<M> as NotNull<M[Key]> extends CoValue
+      [Key in CoKeys<M> as AsLoaded<M[Key]> extends CoValue
         ? Key
         : never]: RefIfCoValue<M[Key]>;
     }

package/src/tools/coValues/coPlainText.ts

@@ -5,15 +5,15 @@ import {
   CoValue,
   CoValueClass,
   CoValueJazzApi,
+  CoValueLoadingState,
   ID,
+  MaybeLoaded,
   Resolved,
   SubscribeListenerOptions,
   SubscribeRestArgs,
   TypeSym,
   unstable_mergeBranch,
   parseCoValueCreateOptions,
-} from "../internal.js";
-import {
   inspect,
   loadCoValueWithoutMe,
   parseSubscribeRestArgs,
@@ -29,6 +29,7 @@ export class CoPlainText extends String implements CoValue {
   declare [TypeSym]: "CoPlainText";
 
   declare $jazz: CoTextJazzApi<this>;
+  declare $isLoaded: true;
 
   /** @internal */
   constructor(
@@ -51,6 +52,7 @@ export class CoPlainText extends String implements CoValue {
           value: new CoTextJazzApi(this, raw),
           enumerable: false,
         },
+        $isLoaded: { value: true, enumerable: false },
       });
       return;
     }
@@ -64,6 +66,7 @@ export class CoPlainText extends String implements CoValue {
           value: new CoTextJazzApi(this, raw),
           enumerable: false,
         },
+        $isLoaded: { value: true, enumerable: false },
       });
       return;
     }
@@ -161,7 +164,7 @@ export class CoPlainText extends String implements CoValue {
     this: CoValueClass<T>,
     id: ID<T>,
     options?: { loadAs?: Account | AnonymousJazzAgent },
-  ): Promise<T | null> {
+  ): Promise<MaybeLoaded<T>> {
     return loadCoValueWithoutMe(this, id, options);
   }
 

package/src/tools/coValues/coVector.ts

@@ -11,8 +11,7 @@ import {
   SubscribeListenerOptions,
   SubscribeRestArgs,
   TypeSym,
-} from "../internal.js";
-import {
+  MaybeLoaded,
   Account,
   CoValueJazzApi,
   inspect,
@@ -33,6 +32,7 @@ export class CoVector
   implements Readonly<Float32Array>, CoValue
 {
   declare $jazz: CoVectorJazzApi<this>;
+  declare $isLoaded: true;
 
   /** @category Type Helpers */
   declare [TypeSym]: "BinaryCoStream";
@@ -79,6 +79,7 @@ export class CoVector
         value: new CoVectorJazzApi(this, raw),
         enumerable: false,
       },
+      $isLoaded: { value: true, enumerable: false },
       _isVectorLoaded: { value: false, enumerable: false, writable: true },
       _requiredDimensionsCount: {
         value: dimensionsCount,
@@ -231,15 +232,15 @@ export class CoVector
     options?: {
       loadAs?: Account | AnonymousJazzAgent;
     },
-  ): Promise<C | null> {
+  ): Promise<MaybeLoaded<C>> {
     const coVector = await loadCoValueWithoutMe(this, id, options);
 
     /**
      * We are only interested in the entire vector. Since most vectors are small (<15kB),
      * we can wait for the stream to be complete before returning the vector
      */
-    if (!coVector?.$jazz.raw.isBinaryStreamEnded()) {
-      return new Promise<C | null>((resolve) => {
+    if (!coVector.$isLoaded || !coVector.$jazz.raw.isBinaryStreamEnded()) {
+      return new Promise((resolve) => {
         subscribeToCoValueWithoutMe(
           this,
           id,