jazz-tools 0.18.38 → 0.19.1

package/src/tools/implementation/zodSchema/schemaTypes/CoValueSchema.ts

@@ -15,4 +15,11 @@ export interface CoreCoValueSchema {
    * Used for discriminating between different CoValue schemas.
    */
   builtin: string;
+
+  resolveQuery: CoreResolveQuery;
 }
+
+/**
+ * Simplified type for {@link ResolveQuery}, used to avoid circularity issues.
+ */
+export type CoreResolveQuery = boolean | Record<string, any>;

package/src/tools/implementation/zodSchema/schemaTypes/CoVectorSchema.ts

@@ -4,7 +4,7 @@ import {
   CoVector,
   Group,
   InstanceOrPrimitiveOfSchema,
-  InstanceOrPrimitiveOfSchemaCoValuesNullable,
+  InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded,
   coOptionalDefiner,
 } from "../../../internal.js";
 import { CoOptionalSchema } from "./CoOptionalSchema.js";
@@ -22,12 +22,14 @@ export function createCoreCoVectorSchema(
     collaborative: true as const,
     builtin: "CoVector" as const,
     dimensions,
+    resolveQuery: true as const,
   };
 }
 
 export class CoVectorSchema implements CoreCoVectorSchema {
   readonly collaborative = true as const;
   readonly builtin = "CoVector" as const;
+  readonly resolveQuery = true as const;
 
   constructor(
     public dimensions: number,
@@ -63,7 +65,7 @@ export class CoVectorSchema implements CoreCoVectorSchema {
   load(
     id: string,
     options?: { loadAs: Account | AnonymousJazzAgent },
-  ): Promise<CoVectorInstanceNullable> {
+  ): Promise<MaybeLoadedCoVectorInstance> {
     return this.coValueClass.load(id, options);
   }
 
@@ -74,14 +76,14 @@ export class CoVectorSchema implements CoreCoVectorSchema {
     id: string,
     options: { loadAs: Account | AnonymousJazzAgent },
     listener: (
-      value: CoVectorInstanceNullable,
+      value: MaybeLoadedCoVectorInstance,
       unsubscribe: () => void,
     ) => void,
   ): () => void;
   subscribe(
     id: string,
     listener: (
-      value: CoVectorInstanceNullable,
+      value: MaybeLoadedCoVectorInstance,
       unsubscribe: () => void,
     ) => void,
   ): () => void;
@@ -101,5 +103,5 @@ export class CoVectorSchema implements CoreCoVectorSchema {
 
 export type CoVectorInstance = InstanceOrPrimitiveOfSchema<CoVectorSchema>;
 
-export type CoVectorInstanceNullable =
-  InstanceOrPrimitiveOfSchemaCoValuesNullable<CoVectorSchema>;
+export type MaybeLoadedCoVectorInstance =
+  InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<CoVectorSchema>;

package/src/tools/implementation/zodSchema/schemaTypes/FileStreamSchema.ts

@@ -3,6 +3,7 @@ import {
   AnonymousJazzAgent,
   FileStream,
   Group,
+  MaybeLoaded,
   coOptionalDefiner,
   unstable_mergeBranchWithResolve,
 } from "../../../internal.js";
@@ -17,12 +18,14 @@ export function createCoreFileStreamSchema(): CoreFileStreamSchema {
   return {
     collaborative: true as const,
     builtin: "FileStream" as const,
+    resolveQuery: true as const,
   };
 }
 
 export class FileStreamSchema implements CoreFileStreamSchema {
   readonly collaborative = true as const;
   readonly builtin = "FileStream" as const;
+  readonly resolveQuery = true as const;
 
   constructor(private coValueClass: typeof FileStream) {}
 
@@ -79,7 +82,7 @@ export class FileStreamSchema implements CoreFileStreamSchema {
   load(
     id: string,
     options?: { loadAs?: Account | AnonymousJazzAgent },
-  ): Promise<FileStream | null> {
+  ): Promise<MaybeLoaded<FileStream>> {
     return this.coValueClass.load(id, options);
   }
 

package/src/tools/implementation/zodSchema/schemaTypes/GroupSchema.ts

@@ -6,6 +6,7 @@ import {
 } from "../../../coValues/interfaces.js";
 import {
   Account,
+  MaybeLoaded,
   RefsToResolve,
   RefsToResolveStrict,
   Resolved,
@@ -24,12 +25,14 @@ export function createCoreGroupSchema(): CoreGroupSchema {
   return {
     collaborative: true as const,
     builtin: "Group" as const,
+    resolveQuery: true as const,
   };
 }
 
 export class GroupSchema implements CoreGroupSchema {
   readonly collaborative = true as const;
   readonly builtin = "Group" as const;
+  readonly resolveQuery = true as const;
 
   getCoValueClass(): typeof Group {
     return Group;
@@ -49,7 +52,7 @@ export class GroupSchema implements CoreGroupSchema {
       loadAs?: Account;
       resolve?: RefsToResolveStrict<Group, R>;
     },
-  ): Promise<Group | null> {
+  ): Promise<MaybeLoaded<Group>> {
     return Group.load(id, options);
   }
   createInvite<G extends Group>(

package/src/tools/implementation/zodSchema/schemaTypes/PlainTextSchema.ts

@@ -4,6 +4,7 @@ import {
   BranchDefinition,
   CoPlainText,
   Group,
+  MaybeLoaded,
   coOptionalDefiner,
   unstable_mergeBranchWithResolve,
 } from "../../../internal.js";
@@ -19,12 +20,14 @@ export function createCoreCoPlainTextSchema(): CorePlainTextSchema {
   return {
     collaborative: true as const,
     builtin: "CoPlainText" as const,
+    resolveQuery: true as const,
   };
 }
 
 export class PlainTextSchema implements CorePlainTextSchema {
   readonly collaborative = true as const;
   readonly builtin = "CoPlainText" as const;
+  readonly resolveQuery = true as const;
 
   constructor(private coValueClass: typeof CoPlainText) {}
 
@@ -47,7 +50,7 @@ export class PlainTextSchema implements CorePlainTextSchema {
       loadAs: Account | AnonymousJazzAgent;
       unstable_branch?: BranchDefinition;
     },
-  ): Promise<CoPlainText | null> {
+  ): Promise<MaybeLoaded<CoPlainText>> {
     return this.coValueClass.load(id, options);
   }
 

package/src/tools/implementation/zodSchema/schemaTypes/RichTextSchema.ts

@@ -3,6 +3,7 @@ import {
   BranchDefinition,
   CoRichText,
   Group,
+  MaybeLoaded,
   coOptionalDefiner,
   unstable_mergeBranchWithResolve,
 } from "../../../internal.js";
@@ -18,12 +19,14 @@ export function createCoreCoRichTextSchema(): CoreRichTextSchema {
   return {
     collaborative: true as const,
     builtin: "CoRichText" as const,
+    resolveQuery: true as const,
   };
 }
 
 export class RichTextSchema implements CoreRichTextSchema {
   readonly collaborative = true as const;
   readonly builtin = "CoRichText" as const;
+  readonly resolveQuery = true as const;
 
   constructor(private coValueClass: typeof CoRichText) {}
 
@@ -46,7 +49,7 @@ export class RichTextSchema implements CoreRichTextSchema {
       loadAs: Account | AnonymousJazzAgent;
       unstable_branch?: BranchDefinition;
     },
-  ): Promise<CoRichText | null> {
+  ): Promise<MaybeLoaded<CoRichText>> {
     return this.coValueClass.load(id, options);
   }
 

package/src/tools/implementation/zodSchema/typeConverters/InstanceOfSchema.ts

@@ -27,6 +27,9 @@ import { CoreRichTextSchema } from "../schemaTypes/RichTextSchema.js";
 import { z } from "../zodReExport.js";
 import { InstanceOrPrimitiveOfSchema } from "./InstanceOrPrimitiveOfSchema.js";
 
+/**
+ * A loaded CoValue whose references are also loaded.
+ */
 export type InstanceOfSchema<S extends CoValueClass | AnyZodOrCoValueSchema> =
   S extends CoreCoValueSchema
     ? S extends CoreAccountSchema<infer Shape>

package/src/tools/implementation/zodSchema/typeConverters/{InstanceOfSchemaCoValuesNullable.ts → InstanceOfSchemaCoValuesMaybeLoaded.ts}

@@ -17,6 +17,7 @@ import {
   CoVector,
   FileStream,
   Group,
+  MaybeLoaded,
 } from "../../../internal.js";
 import { CoreCoOptionalSchema } from "../schemaTypes/CoOptionalSchema.js";
 import { CoreCoValueSchema } from "../schemaTypes/CoValueSchema.js";
@@ -25,66 +26,73 @@ import { CorePlainTextSchema } from "../schemaTypes/PlainTextSchema.js";
 import { CoreRichTextSchema } from "../schemaTypes/RichTextSchema.js";
 import { CoreGroupSchema } from "../schemaTypes/GroupSchema.js";
 import { z } from "../zodReExport.js";
-import { InstanceOrPrimitiveOfSchemaCoValuesNullable } from "./InstanceOrPrimitiveOfSchemaCoValuesNullable.js";
+import { InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded } from "./InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded.js";
 
-export type InstanceOfSchemaCoValuesNullable<
+/**
+ * A loaded CoValue whose references may or may not be loaded.
+ */
+export type InstanceOfSchemaCoValuesMaybeLoaded<
   S extends CoValueClass | AnyZodOrCoValueSchema,
 > = S extends CoreCoValueSchema
   ? S extends CoreAccountSchema<infer Shape>
-    ?
-        | ({
-            readonly [key in keyof Shape]: InstanceOrPrimitiveOfSchemaCoValuesNullable<
-              Shape[key]
-            >;
-          } & Account)
-        | null
+    ? MaybeLoaded<
+        {
+          readonly [key in keyof Shape]: InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<
+            Shape[key]
+          >;
+        } & Account
+      >
     : S extends CoreGroupSchema
-      ? Group | null
+      ? MaybeLoaded<Group>
       : S extends CoreCoRecordSchema<infer K, infer V>
-        ?
-            | ({
-                readonly [key in z.output<K> &
-                  string]: InstanceOrPrimitiveOfSchemaCoValuesNullable<V>;
-              } & CoMap)
-            | null
+        ? MaybeLoaded<
+            {
+              readonly [key in z.output<K> &
+                string]: InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<V>;
+            } & CoMap
+          >
         : S extends CoreCoMapSchema<infer Shape, infer CatchAll>
-          ?
-              | ({
-                  readonly [key in keyof Shape]: InstanceOrPrimitiveOfSchemaCoValuesNullable<
-                    Shape[key]
-                  >;
-                } & (CatchAll extends AnyZodOrCoValueSchema
-                  ? {
-                      readonly [
-                        key: string
-                      ]: InstanceOrPrimitiveOfSchemaCoValuesNullable<CatchAll>;
-                    }
-                  : {}) &
-                  CoMap)
-              | null
+          ? MaybeLoaded<
+              {
+                readonly [key in keyof Shape]: InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<
+                  Shape[key]
+                >;
+              } & (CatchAll extends AnyZodOrCoValueSchema
+                ? {
+                    readonly [
+                      key: string
+                    ]: InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<CatchAll>;
+                  }
+                : {}) &
+                CoMap
+            >
           : S extends CoreCoListSchema<infer T>
-            ? CoList<InstanceOrPrimitiveOfSchemaCoValuesNullable<T>> | null
+            ? MaybeLoaded<
+                CoList<InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<T>>
+              >
             : S extends CoreCoFeedSchema<infer T>
-              ? CoFeed<InstanceOrPrimitiveOfSchemaCoValuesNullable<T>> | null
+              ? MaybeLoaded<
+                  CoFeed<InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<T>>
+                >
               : S extends CorePlainTextSchema
-                ? CoPlainText | null
+                ? MaybeLoaded<CoPlainText>
                 : S extends CoreRichTextSchema
-                  ? CoRichText | null
+                  ? MaybeLoaded<CoRichText>
                   : S extends CoreFileStreamSchema
-                    ? FileStream | null
+                    ? MaybeLoaded<FileStream>
                     : S extends CoreCoVectorSchema
-                      ? Readonly<CoVector> | null
+                      ? MaybeLoaded<Readonly<CoVector>>
                       : S extends CoreCoOptionalSchema<infer Inner>
                         ?
-                            | InstanceOrPrimitiveOfSchemaCoValuesNullable<Inner>
+                            | InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<Inner>
                             | undefined
                         : S extends CoreCoDiscriminatedUnionSchema<
                               infer Members
                             >
-                          ? InstanceOrPrimitiveOfSchemaCoValuesNullable<
+                          ? InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<
                               Members[number]
                             >
                           : never
   : S extends CoValueClass
-    ? InstanceType<S> | null
+    ? MaybeLoaded<InstanceType<S>>
     : never;

package/src/tools/implementation/zodSchema/typeConverters/InstanceOrPrimitiveOfSchema.ts

@@ -6,6 +6,10 @@ import {
 import { z } from "../zodReExport.js";
 import { TypeOfZodSchema } from "./TypeOfZodSchema.js";
 
+/**
+ * A loaded CoValue or primitive type.
+ * If it's a CoValue, its references to other CoValues are also loaded.
+ */
 export type InstanceOrPrimitiveOfSchema<
   S extends CoValueClass | AnyZodOrCoValueSchema,
 > = S extends z.core.$ZodType ? TypeOfZodSchema<S> : InstanceOfSchema<S>;

package/src/tools/implementation/zodSchema/typeConverters/{InstanceOrPrimitiveOfSchemaCoValuesNullable.ts → InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded.ts}

@@ -1,13 +1,17 @@
 import {
   AnyZodOrCoValueSchema,
   CoValueClass,
-  InstanceOfSchemaCoValuesNullable,
+  InstanceOfSchemaCoValuesMaybeLoaded,
 } from "../../../internal.js";
 import { z } from "../zodReExport.js";
 import { TypeOfZodSchema } from "./TypeOfZodSchema.js";
 
-export type InstanceOrPrimitiveOfSchemaCoValuesNullable<
+/**
+ * A loaded CoValue or primitive type.
+ * If it's a CoValue, its references to other CoValues may or may not be loaded.
+ */
+export type InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<
   S extends CoValueClass | AnyZodOrCoValueSchema,
 > = S extends z.core.$ZodType
   ? TypeOfZodSchema<S>
-  : InstanceOfSchemaCoValuesNullable<S>;
+  : InstanceOfSchemaCoValuesMaybeLoaded<S>;

package/src/tools/implementation/zodSchema/unionUtils.ts

@@ -7,6 +7,7 @@ import {
   DiscriminableCoValueSchemas,
   DiscriminableCoreCoValueSchema,
   SchemaUnionDiscriminator,
+  coField,
 } from "../../internal.js";
 import {
   hydrateCoreCoValueSchema,
@@ -59,13 +60,23 @@ export function schemaUnionDiscriminatorFor(
     const determineSchema: SchemaUnionDiscriminator<CoMap> = (
       discriminable,
     ) => {
+      // collect all keys of nested CoValues
+      const allNestedRefKeys = new Set<string>();
+      for (const option of availableOptions) {
+        const coMapShape = (option as CoreCoMapSchema).getDefinition().shape;
+        for (const [key, value] of Object.entries(coMapShape)) {
+          if (isAnyCoValueSchema(value)) {
+            allNestedRefKeys.add(key);
+          }
+        }
+      }
+
       for (const option of availableOptions) {
         let match = true;
+        const optionDef = (option as CoreCoMapSchema).getDefinition();
 
         for (const key of Object.keys(discriminatorMap)) {
-          const discriminatorDef = (option as CoreCoMapSchema).getDefinition()
-            .shape[key];
-
+          const discriminatorDef = optionDef.shape[key];
           const discriminatorValue = discriminable.get(key);
 
           if (discriminatorValue && typeof discriminatorValue === "object") {
@@ -95,7 +106,27 @@ export function schemaUnionDiscriminatorFor(
 
         if (match) {
           const coValueSchema = hydrateCoreCoValueSchema(option as any);
-          return coValueSchema.getCoValueClass() as typeof CoMap;
+          const coValueClass = coValueSchema.getCoValueClass() as typeof CoMap;
+
+          const dummyFieldNames = allNestedRefKeys
+            .keys()
+            .filter((key) => !optionDef.shape[key])
+            .toArray();
+
+          if (dummyFieldNames.length === 0) {
+            return coValueClass;
+          }
+
+          // inject dummy fields
+          return class extends coValueClass {
+            constructor(...args: ConstructorParameters<typeof coValueClass>) {
+              super(...args);
+
+              for (const key of dummyFieldNames) {
+                (this as any)[key] = coField.null;
+              }
+            }
+          };
         }
       }
 

package/src/tools/implementation/zodSchema/zodSchema.ts

@@ -2,6 +2,7 @@ import { LocalNode, RawAccount } from "cojson";
 import {
   Account,
   AccountClass,
+  LoadedAndRequired,
   CoRecordSchema,
   CoValueClass,
   CoValueFromRaw,
@@ -45,7 +46,7 @@ import {
   CoreRichTextSchema,
   RichTextSchema,
 } from "./schemaTypes/RichTextSchema.js";
-import { InstanceOfSchemaCoValuesNullable } from "./typeConverters/InstanceOfSchemaCoValuesNullable.js";
+import { InstanceOfSchemaCoValuesMaybeLoaded } from "./typeConverters/InstanceOfSchemaCoValuesMaybeLoaded.js";
 import { z } from "./zodReExport.js";
 import { CoreGroupSchema } from "./schemaTypes/GroupSchema.js";
 import { GroupSchema } from "./schemaTypes/GroupSchema.js";
@@ -92,8 +93,8 @@ export type CoValueSchemaFromCoreSchema<S extends CoreCoValueSchema> =
 export type CoValueClassFromAnySchema<S extends CoValueClassOrSchema> =
   S extends CoValueClass<any>
     ? S
-    : CoValueClass<NonNullable<InstanceOfSchema<S>>> &
-        CoValueFromRaw<NonNullable<InstanceOfSchema<S>>> &
+    : CoValueClass<LoadedAndRequired<InstanceOfSchema<S>>> &
+        CoValueFromRaw<LoadedAndRequired<InstanceOfSchema<S>>> &
         (S extends CoreAccountSchema ? AccountClassEssentials : {});
 
 type AccountClassEssentials = {
@@ -121,14 +122,21 @@ export type AnyZodOrCoValueSchema = AnyZodSchema | CoreCoValueSchema;
 
 export type Loaded<
   T extends CoValueClassOrSchema,
-  R extends ResolveQuery<T> = true,
-> = Resolved<NonNullable<InstanceOfSchemaCoValuesNullable<T>>, R>;
+  // @ts-expect-error
+  R extends ResolveQuery<T> = SchemaResolveQuery<T>,
+> = Resolved<LoadedAndRequired<InstanceOfSchemaCoValuesMaybeLoaded<T>>, R>;
 
 export type ResolveQuery<T extends CoValueClassOrSchema> = RefsToResolve<
-  NonNullable<InstanceOfSchemaCoValuesNullable<T>>
+  LoadedAndRequired<InstanceOfSchemaCoValuesMaybeLoaded<T>>
 >;
 
 export type ResolveQueryStrict<
   T extends CoValueClassOrSchema,
   R extends ResolveQuery<T>,
-> = RefsToResolveStrict<NonNullable<InstanceOfSchemaCoValuesNullable<T>>, R>;
+> = RefsToResolveStrict<
+  LoadedAndRequired<InstanceOfSchemaCoValuesMaybeLoaded<T>>,
+  R
+>;
+
+export type SchemaResolveQuery<T extends CoValueClassOrSchema> =
+  T extends CoreCoValueSchema ? T["resolveQuery"] : true;

package/src/tools/internal.ts

@@ -23,13 +23,13 @@ export type * from "./subscribe/types.js";
 export * from "./coValues/deepLoading.js";
 export * from "./implementation/anonymousJazzAgent.js";
 export * from "./implementation/activeAccountContext.js";
-export * from "./implementation/errors.js";
 export * from "./implementation/refs.js";
 export * from "./implementation/schema.js";
 export * from "./subscribe/SubscriptionScope.js";
 export * from "./subscribe/types.js";
 export * from "./subscribe/index.js";
 export * from "./lib/cache.js";
+export * from "./lib/utils.js";
 export * from "./lib/utilityTypes.js";
 export * from "./implementation/createContext.js";
 
@@ -47,9 +47,9 @@ export * from "./implementation/zodSchema/schemaTypes/FileStreamSchema.js";
 export * from "./implementation/zodSchema/schemaTypes/CoVectorSchema.js";
 export * from "./implementation/zodSchema/schemaTypes/PlainTextSchema.js";
 export * from "./implementation/zodSchema/typeConverters/InstanceOrPrimitiveOfSchema.js";
-export * from "./implementation/zodSchema/typeConverters/InstanceOrPrimitiveOfSchemaCoValuesNullable.js";
+export * from "./implementation/zodSchema/typeConverters/InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded.js";
 export * from "./implementation/zodSchema/typeConverters/InstanceOfSchema.js";
-export * from "./implementation/zodSchema/typeConverters/InstanceOfSchemaCoValuesNullable.js";
+export * from "./implementation/zodSchema/typeConverters/InstanceOfSchemaCoValuesMaybeLoaded.js";
 export * from "./implementation/zodSchema/typeConverters/CoFieldSchemaInit.js";
 export * from "./implementation/zodSchema/runtimeConverters/coValueSchemaTransformation.js";
 export * from "./implementation/zodSchema/runtimeConverters/schemaFieldToCoFieldDef.js";

package/src/tools/lib/utils.test.ts

@@ -0,0 +1,56 @@
+import { beforeAll, describe, test, expect } from "vitest";
+import {
+  assertLoaded,
+  co,
+  createUnloadedCoValue,
+  CoValueLoadingState,
+  getLoadedOrUndefined,
+} from "../internal";
+import { createJazzTestAccount, setupJazzTestSync } from "../testing";
+
+beforeAll(async () => {
+  await setupJazzTestSync();
+  await createJazzTestAccount({
+    isCurrentActiveAccount: true,
+  });
+});
+
+describe("assertLoaded", () => {
+  test("should throw an error if the CoValue is not loaded", () => {
+    const coValue = createUnloadedCoValue(
+      "id",
+      CoValueLoadingState.UNAVAILABLE,
+    );
+    expect(() => assertLoaded(coValue)).toThrow("CoValue is not loaded");
+  });
+
+  test("should narrow the value if it is loaded", () => {
+    const coValue = co.plainText().create("value");
+    assertLoaded(coValue);
+    expect(coValue.$isLoaded).toBe(true);
+    expect(coValue.toUpperCase()).toBe("VALUE");
+  });
+});
+
+describe("getLoadedOrUndefined", () => {
+  test("should return undefined if the CoValue is not loaded", () => {
+    const coValue = createUnloadedCoValue(
+      "id",
+      CoValueLoadingState.UNAVAILABLE,
+    );
+    expect(getLoadedOrUndefined(coValue)).toBeUndefined();
+  });
+
+  test("should return the CoValue if it is loaded", () => {
+    const coValue = co.plainText().create("value");
+    expect(getLoadedOrUndefined(coValue)).toBe(coValue);
+  });
+
+  test("should return undefined if the CoValue is null", () => {
+    expect(getLoadedOrUndefined(null)).toBeUndefined();
+  });
+
+  test("should return undefined if the CoValue is undefined", () => {
+    expect(getLoadedOrUndefined(undefined)).toBeUndefined();
+  });
+});

package/src/tools/lib/utils.ts

@@ -0,0 +1,32 @@
+import type { CoValue, LoadedAndRequired, MaybeLoaded } from "../internal.js";
+
+export function isCoValueId(id: unknown): id is `co_z${string}` {
+  return typeof id === "string" && id.startsWith("co_z");
+}
+
+/**
+ * Assert that a CoValue is loaded, otherwise throw an error
+ */
+export function assertLoaded<T extends MaybeLoaded<CoValue>>(
+  coValue: T,
+): asserts coValue is LoadedAndRequired<T> {
+  if (!coValue.$isLoaded) {
+    throw new Error("CoValue is not loaded");
+  }
+}
+
+/**
+ * Get a loaded CoValue or `undefined` if it is not loaded.
+ *
+ * Can be used to ease the transition between nullable loading states from Jazz 0.18
+ * and explicit loading states from Jazz 0.19.
+ */
+export function getLoadedOrUndefined<T extends MaybeLoaded<CoValue>>(
+  coValue: T | undefined | null,
+): LoadedAndRequired<T> | undefined {
+  if (!coValue?.$isLoaded) {
+    return undefined;
+  }
+
+  return coValue as LoadedAndRequired<T>;
+}