jazz-tools 0.18.38 → 0.19.0

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/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>;
+}

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[];