jazz-tools 0.18.38 → 0.19.1

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,9 +107,19 @@ 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>,
+  const R extends RefsToResolve<V> = true,
 >(
   cls: CoValueClass<V>,
   id: ID<CoValue>,
@@ -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);
   }
 
@@ -242,7 +263,7 @@ export function parseSubscribeRestArgs<
 
 export function subscribeToCoValueWithoutMe<
   V extends CoValue,
-  const R extends RefsToResolve<V>,
+  const R extends RefsToResolve<V> = true,
 >(
   cls: CoValueClass<V>,
   id: ID<CoValue>,
@@ -262,7 +283,7 @@ export function subscribeToCoValueWithoutMe<
 
 export function subscribeToCoValue<
   V extends CoValue,
-  const R extends RefsToResolve<V>,
+  const R extends RefsToResolve<V> = true,
 >(
   cls: CoValueClass<V>,
   id: ID<CoValue>,
@@ -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,9 @@ import {
   CoValueJazzApi,
   Group,
   ID,
+  MaybeLoaded,
+  RefsToResolve,
+  RefsToResolveStrict,
   Resolved,
   Simplify,
   SubscribeListenerOptions,
@@ -149,18 +152,17 @@ export abstract class SchemaUnion extends CoValueBase implements CoValue {
   /**
    * Load a `SchemaUnion` with a given ID, as a given account.
    *
-   * Note: The `resolve` option is not supported for `SchemaUnion`s due to https://github.com/garden-co/jazz/issues/2639
-   *
    * @category Subscription & Loading
    */
-  static load<M extends SchemaUnion>(
+  static load<M extends SchemaUnion, const R extends RefsToResolve<M> = true>(
     this: CoValueClass<M>,
     id: ID<M>,
     options?: {
+      resolve?: RefsToResolveStrict<M, R>;
       loadAs?: Account | AnonymousJazzAgent;
       skipRetry?: boolean;
     },
-  ): Promise<Resolved<M, true> | null> {
+  ): Promise<MaybeLoaded<Resolved<M, R>>> {
     return loadCoValueWithoutMe(this, id, options);
   }
 
@@ -173,27 +175,31 @@ export abstract class SchemaUnion extends CoValueBase implements CoValue {
    *
    * Also see the `useCoState` hook to reactively subscribe to a CoValue in a React component.
    *
-   * Note: The `resolve` option is not supported for `SchemaUnion`s due to https://github.com/garden-co/jazz/issues/2639
-   *
    * @category Subscription & Loading
    */
-  static subscribe<M extends SchemaUnion>(
+  static subscribe<
+    M extends SchemaUnion,
+    const R extends RefsToResolve<M> = true,
+  >(
     this: CoValueClass<M>,
     id: ID<M>,
-    listener: (value: Resolved<M, true>, unsubscribe: () => void) => void,
+    listener: (value: Resolved<M, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<M extends SchemaUnion>(
+  static subscribe<
+    M extends SchemaUnion,
+    const R extends RefsToResolve<M> = true,
+  >(
     this: CoValueClass<M>,
     id: ID<M>,
-    options: SubscribeListenerOptions<M, true>,
-    listener: (value: Resolved<M, true>, unsubscribe: () => void) => void,
+    options: SubscribeListenerOptions<M, R>,
+    listener: (value: Resolved<M, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<M extends SchemaUnion>(
+  static subscribe<M extends SchemaUnion, const R extends RefsToResolve<M>>(
     this: CoValueClass<M>,
     id: ID<M>,
-    ...args: SubscribeRestArgs<M, true>
+    ...args: SubscribeRestArgs<M, R>
   ): () => void {
     const { options, listener } = parseSubscribeRestArgs(args);
-    return subscribeToCoValueWithoutMe<M, true>(this, id, options, listener);
+    return subscribeToCoValueWithoutMe<M, R>(this, id, options, listener);
   }
 }

package/src/tools/exports.ts

@@ -31,6 +31,9 @@ export type {
   RefsToResolve,
   RefsToResolveStrict,
   CoMapInit_DEPRECATED as CoMapInit,
+  CoMapEdit,
+  CoMapEdits,
+  LastAndAllCoMapEdits,
   CoFeedEntry,
   SingleCoFeedEntry,
   TextPos,
@@ -49,6 +52,8 @@ export {
   CoPlainText,
   CoRichText,
   Account,
+  assertLoaded,
+  getLoadedOrUndefined,
   isControlledAccount,
   loadCoValue,
   subscribeToCoValue,
@@ -57,6 +62,7 @@ export {
   exportCoValue,
   importContentPieces,
   Ref,
+  createUnloadedCoValue,
   unstable_loadUnique,
 } from "./internal.js";
 
@@ -104,8 +110,12 @@ export type * from "./types.js";
 export {
   coValueClassFromCoValueClassOrSchema,
   type InstanceOfSchema,
-  type InstanceOfSchemaCoValuesNullable,
+  type InstanceOfSchemaCoValuesMaybeLoaded,
+  type SchemaResolveQuery,
   type CoValueClassOrSchema,
+  CoValueLoadingState,
+  type MaybeLoaded,
+  type NotLoaded,
   type Loaded,
   type BaseAccountShape,
   type DefaultAccountShape,

package/src/tools/implementation/refs.ts

@@ -5,11 +5,13 @@ import {
   ID,
   RefEncoded,
   SubscriptionScope,
-} from "../internal.js";
-import {
+  LoadedAndRequired,
   accessChildById,
+  CoValueLoadingState,
   getSubscriptionScope,
   isRefEncoded,
+  createUnloadedCoValue,
+  MaybeLoaded,
 } from "../internal.js";
 
 export class Ref<out V extends CoValue> {
@@ -24,10 +26,10 @@ export class Ref<out V extends CoValue> {
     }
   }
 
-  async load(): Promise<V | null> {
+  async load(): Promise<MaybeLoaded<V>> {
     const subscriptionScope = getSubscriptionScope(this.parent);
 
-    let node: SubscriptionScope<CoValue> | undefined | null;
+    let node: SubscriptionScope<CoValue> | undefined;
 
     /**
      * If the parent subscription scope is closed, we can't use it
@@ -51,25 +53,29 @@ export class Ref<out V extends CoValue> {
     }
 
     if (!node) {
-      return null;
+      return createUnloadedCoValue(this.id, CoValueLoadingState.LOADING);
     }
 
     const value = node.value;
 
-    if (value?.type === "loaded") {
+    if (value?.type === CoValueLoadingState.LOADED) {
       return value.value as V;
     } else {
       return new Promise((resolve) => {
         const unsubscribe = node.subscribe((value) => {
-          if (value?.type === "loaded") {
+          if (value?.type === CoValueLoadingState.LOADED) {
             unsubscribe();
             resolve(value.value as V);
-          } else if (value?.type === "unavailable") {
+          } else if (value?.type === CoValueLoadingState.UNAVAILABLE) {
             unsubscribe();
-            resolve(null);
-          } else if (value?.type === "unauthorized") {
+            resolve(
+              createUnloadedCoValue(this.id, CoValueLoadingState.UNAVAILABLE),
+            );
+          } else if (value?.type === CoValueLoadingState.UNAUTHORIZED) {
             unsubscribe();
-            resolve(null);
+            resolve(
+              createUnloadedCoValue(this.id, CoValueLoadingState.UNAUTHORIZED),
+            );
           }
 
           if (subscriptionScope.closed) {
@@ -144,6 +150,6 @@ export function makeRefs<Keys extends string | number>(
   });
 }
 
-export type RefIfCoValue<V> = NonNullable<V> extends CoValue
-  ? Ref<NonNullable<V>>
+export type RefIfCoValue<V> = LoadedAndRequired<V> extends CoValue
+  ? Ref<LoadedAndRequired<V>>
   : never;

package/src/tools/implementation/schema.ts

@@ -7,6 +7,7 @@ import {
   CoValueFromRaw,
   Group,
   ItemsSym,
+  LoadedAndRequired,
   SchemaInit,
   isCoValueClass,
 } from "../internal.js";
@@ -182,11 +183,11 @@ export function instantiateRefEncodedWithInit<V extends CoValue>(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type Schema = JsonEncoded | RefEncoded<CoValue> | EncodedAs<any>;
 
-export type SchemaFor<Field> = NonNullable<Field> extends CoValue
-  ? RefEncoded<NonNullable<Field>>
-  : NonNullable<Field> extends JsonValue
+export type SchemaFor<Field> = LoadedAndRequired<Field> extends CoValue
+  ? RefEncoded<LoadedAndRequired<Field>>
+  : LoadedAndRequired<Field> extends JsonValue
     ? JsonEncoded
-    : EncodedAs<NonNullable<Field>>;
+    : EncodedAs<LoadedAndRequired<Field>>;
 
 export type Encoder<V> = {
   encode: (value: V) => JsonValue;

package/src/tools/implementation/schemaUtils.ts

@@ -1,3 +1,5 @@
+import { CoreResolveQuery } from "./zodSchema/schemaTypes/CoValueSchema";
+
 /**
  * Remove getters from an object
  *
@@ -16,3 +18,16 @@ export function removeGetters<T extends object>(obj: T): Partial<T> {
 
   return result;
 }
+
+/**
+ * Adds a CoValue schema's resolve query to a load options object
+ * if no resolve query is provided.
+ */
+export function withSchemaResolveQuery<
+  const T extends { resolve?: CoreResolveQuery },
+>(loadOptions: T | undefined, schemaResolveQuery: CoreResolveQuery): T {
+  const newOptions: CoreResolveQuery = loadOptions ? { ...loadOptions } : {};
+  // TODO merge the schema resolve query with the user-provided resolve query
+  newOptions.resolve ||= schemaResolveQuery;
+  return newOptions as T;
+}

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

@@ -1,12 +1,14 @@
 import { RawCoList, RawCoMap } from "cojson";
 import {
   Account,
+  AccountSchema,
   CoDiscriminatedUnionSchema,
   CoFeed,
   CoFeedSchema,
   CoList,
   CoListSchema,
   CoMap,
+  CoMapSchema,
   CoPlainText,
   CoRichText,
   CoValueClass,
@@ -15,8 +17,6 @@ import {
   CoVectorSchema,
   PlainTextSchema,
   SchemaUnion,
-  enrichAccountSchema,
-  enrichCoMapSchema,
   isCoValueClass,
   Group,
   CoVector,
@@ -98,8 +98,8 @@ export function hydrateCoreCoValueSchema<S extends AnyCoreCoValueSchema>(
 
     const coValueSchema =
       ClassToExtend === Account
-        ? enrichAccountSchema(schema as any, coValueClass as any)
-        : enrichCoMapSchema(schema as any, coValueClass as any);
+        ? new AccountSchema(schema as any, coValueClass as any)
+        : new CoMapSchema(schema as any, coValueClass as any);
 
     return coValueSchema as unknown as CoValueSchemaFromCoreSchema<S>;
   } else if (schema.builtin === "CoList") {