jazz-tools 0.18.38 → 0.19.0

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") {

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

@@ -2,14 +2,20 @@ import {
   Account,
   AccountCreationProps,
   BranchDefinition,
+  CoMapSchemaDefinition,
   coOptionalDefiner,
   Group,
+  MaybeLoaded,
   RefsToResolveStrict,
+  RefsToResolve,
+  Resolved,
   Simplify,
+  SubscribeListenerOptions,
+  unstable_mergeBranchWithResolve,
 } from "../../../internal.js";
 import { AnonymousJazzAgent } from "../../anonymousJazzAgent.js";
 import { InstanceOrPrimitiveOfSchema } from "../typeConverters/InstanceOrPrimitiveOfSchema.js";
-import { InstanceOrPrimitiveOfSchemaCoValuesNullable } from "../typeConverters/InstanceOrPrimitiveOfSchemaCoValuesNullable.js";
+import { InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded } from "../typeConverters/InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded.js";
 import { z } from "../zodReExport.js";
 import { AnyZodOrCoValueSchema, Loaded, ResolveQuery } from "../zodSchema.js";
 import {
@@ -17,6 +23,9 @@ import {
   CoreCoMapSchema,
   createCoreCoMapSchema,
 } from "./CoMapSchema.js";
+import { CoOptionalSchema } from "./CoOptionalSchema.js";
+import { CoreResolveQuery } from "./CoValueSchema.js";
+import { withSchemaResolveQuery } from "../../schemaUtils.js";
 
 export type BaseProfileShape = {
   name: z.core.$ZodString<string>;
@@ -34,60 +43,151 @@ export type DefaultAccountShape = {
   root: CoMapSchema<{}>;
 };
 
-export interface AccountSchema<
+export class AccountSchema<
   Shape extends BaseAccountShape = DefaultAccountShape,
-> extends CoreAccountSchema<Shape>,
-    Omit<
-      CoMapSchema<Shape>,
-      | "builtin"
-      | "getDefinition"
-      | "create"
-      | "load"
-      | "withMigration"
-      | "unstable_merge"
-      | "getCoValueClass"
-    > {
-  builtin: "Account";
-
-  create: (
+  DefaultResolveQuery extends CoreResolveQuery = true,
+> implements CoreAccountSchema<Shape>
+{
+  collaborative = true as const;
+  builtin = "Account" as const;
+  shape: Shape;
+  getDefinition: () => CoMapSchemaDefinition;
+
+  /**
+   * Default resolve query to be used when loading instances of this schema.
+   * This resolve query will be used when no resolve query is provided to the load method.
+   * @default true
+   */
+  resolveQuery: DefaultResolveQuery = true as DefaultResolveQuery;
+
+  constructor(
+    coreSchema: CoreAccountSchema<Shape>,
+    private coValueClass: typeof Account,
+  ) {
+    this.shape = coreSchema.shape;
+    this.getDefinition = coreSchema.getDefinition;
+  }
+
+  create(
     options: Simplify<Parameters<(typeof Account)["create"]>[0]>,
-  ) => Promise<AccountInstance<Shape>>;
-
-  load: <R extends ResolveQuery<AccountSchema<Shape>>>(
+  ): Promise<AccountInstance<Shape>> {
+    // @ts-expect-error
+    return this.coValueClass.create(options);
+  }
+
+  load<
+    // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
+    const R extends ResolveQuery<AccountSchema<Shape>> = DefaultResolveQuery,
+  >(
     id: string,
     options?: {
       loadAs?: Account | AnonymousJazzAgent;
       resolve?: RefsToResolveStrict<AccountSchema<Shape>, R>;
     },
-  ) => Promise<Loaded<AccountSchema<Shape>, R> | null>;
+  ): Promise<MaybeLoaded<Loaded<AccountSchema<Shape>, R>>> {
+    // @ts-expect-error
+    return this.coValueClass.load(
+      id,
+      // @ts-expect-error
+      withSchemaResolveQuery(options, this.resolveQuery),
+    );
+  }
 
   /** @internal */
-  createAs: (
+  createAs(
     as: Account,
     options: {
-      creationProps?: { name: string };
+      creationProps: { name: string };
     },
-  ) => Promise<AccountInstance<Shape>>;
-
-  unstable_merge: <R extends ResolveQuery<AccountSchema<Shape>>>(
+  ): Promise<AccountInstance<Shape>> {
+    // @ts-expect-error
+    return this.coValueClass.createAs(as, options);
+  }
+
+  unstable_merge<
+    // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
+    R extends ResolveQuery<AccountSchema<Shape>> = DefaultResolveQuery,
+  >(
     id: string,
-    options?: {
+    options: {
       loadAs?: Account | AnonymousJazzAgent;
       resolve?: RefsToResolveStrict<AccountSchema<Shape>, R>;
       branch: BranchDefinition;
     },
-  ) => Promise<void>;
+  ): Promise<void> {
+    return unstable_mergeBranchWithResolve(
+      this.coValueClass,
+      id,
+      // @ts-expect-error
+      withSchemaResolveQuery(options, this.resolveQuery),
+    );
+  }
+
+  subscribe<
+    const R extends RefsToResolve<
+      Simplify<AccountInstance<Shape>>
+      // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
+    > = DefaultResolveQuery,
+  >(
+    id: string,
+    options: SubscribeListenerOptions<Simplify<AccountInstance<Shape>>, R>,
+    listener: (
+      value: Resolved<Simplify<AccountInstance<Shape>>, R>,
+      unsubscribe: () => void,
+    ) => void,
+  ): () => void {
+    return this.coValueClass.subscribe(
+      id,
+      // @ts-expect-error
+      withSchemaResolveQuery(options, this.resolveQuery),
+      listener,
+    );
+  }
 
-  getMe: () => AccountInstanceCoValuesNullable<Shape>;
+  getMe(): Loaded<this, true> {
+    // @ts-expect-error
+    return this.coValueClass.getMe();
+  }
 
   withMigration(
     migration: (
       account: Loaded<AccountSchema<Shape>>,
       creationProps?: { name: string },
     ) => void,
-  ): AccountSchema<Shape>;
-
-  getCoValueClass: () => typeof Account;
+  ): AccountSchema<Shape, DefaultResolveQuery> {
+    (this.coValueClass.prototype as Account).migrate = async function (
+      this,
+      creationProps,
+    ) {
+      // @ts-expect-error
+      await migration(this, creationProps);
+    };
+
+    return this;
+  }
+
+  getCoValueClass(): typeof Account {
+    return this.coValueClass;
+  }
+
+  optional(): CoOptionalSchema<this> {
+    return coOptionalDefiner(this);
+  }
+
+  /**
+   * Adds a default resolve query to be used when loading instances of this schema.
+   * This resolve query will be used when no resolve query is provided to the load method.
+   */
+  resolved<R extends ResolveQuery<AccountSchema<Shape>>>(
+    resolveQuery: RefsToResolveStrict<AccountSchema<Shape>, R>,
+  ): AccountSchema<Shape, R> {
+    const coreSchema: CoreAccountSchema<Shape> = createCoreAccountSchema(
+      this.shape,
+    );
+    const copy = new AccountSchema<Shape, R>(coreSchema, this.coValueClass);
+    copy.resolveQuery = resolveQuery as R;
+    return copy;
+  }
 }
 
 export function createCoreAccountSchema<Shape extends BaseAccountShape>(
@@ -99,62 +199,6 @@ export function createCoreAccountSchema<Shape extends BaseAccountShape>(
   };
 }
 
-export function enrichAccountSchema<Shape extends BaseAccountShape>(
-  schema: CoreAccountSchema<Shape>,
-  coValueClass: typeof Account,
-): AccountSchema<Shape> {
-  const enrichedSchema = Object.assign(schema, {
-    create: (...args: any[]) => {
-      // @ts-expect-error
-      return coValueClass.create(...args);
-    },
-    createAs: (...args: any[]) => {
-      // @ts-expect-error
-      return coValueClass.createAs(...args);
-    },
-    getMe: (...args: any[]) => {
-      // @ts-expect-error
-      return coValueClass.getMe(...args);
-    },
-    load: (...args: any[]) => {
-      // @ts-expect-error
-      return coValueClass.load(...args);
-    },
-    subscribe: (...args: any[]) => {
-      // @ts-expect-error
-      return coValueClass.subscribe(...args);
-    },
-    fromRaw: (...args: any[]) => {
-      // @ts-expect-error
-      return coValueClass.fromRaw(...args);
-    },
-    unstable_merge: (...args: any[]) => {
-      // @ts-expect-error
-      return unstable_mergeBranchWithResolve(coValueClass, ...args);
-    },
-    withMigration: (
-      migration: (
-        value: any,
-        creationProps?: AccountCreationProps,
-      ) => void | Promise<void>,
-    ) => {
-      (coValueClass.prototype as Account).migrate = async function (
-        this,
-        creationProps,
-      ) {
-        await migration(this, creationProps);
-      };
-
-      return enrichedSchema;
-    },
-    getCoValueClass: () => {
-      return coValueClass;
-    },
-    optional: () => coOptionalDefiner(enrichedSchema),
-  }) as unknown as AccountSchema<Shape>;
-  return enrichedSchema;
-}
-
 export type DefaultProfileShape = {
   name: z.core.$ZodString<string>;
   inbox: z.core.$ZodOptional<z.core.$ZodString>;
@@ -176,11 +220,3 @@ export interface CoreAccountSchema<
 export type AccountInstance<Shape extends z.core.$ZodLooseShape> = {
   readonly [key in keyof Shape]: InstanceOrPrimitiveOfSchema<Shape[key]>;
 } & Account;
-
-export type AccountInstanceCoValuesNullable<
-  Shape extends z.core.$ZodLooseShape,
-> = {
-  readonly [key in keyof Shape]: InstanceOrPrimitiveOfSchemaCoValuesNullable<
-    Shape[key]
-  >;
-} & Account;

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

@@ -1,9 +1,11 @@
 import {
   Account,
   AnonymousJazzAgent,
+  LoadedAndRequired,
   BranchDefinition,
   InstanceOfSchema,
-  InstanceOrPrimitiveOfSchemaCoValuesNullable,
+  InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded,
+  MaybeLoaded,
   Resolved,
   SchemaUnion,
   SchemaUnionConcreteSubclass,
@@ -47,6 +49,7 @@ export class CoDiscriminatedUnionSchema<
   readonly collaborative = true as const;
   readonly builtin = "CoDiscriminatedUnion" as const;
   readonly getDefinition: () => CoDiscriminatedUnionSchemaDefinition<Options>;
+  readonly resolveQuery = true as const;
 
   constructor(
     coreSchema: CoreCoDiscriminatedUnionSchema<Options>,
@@ -64,22 +67,26 @@ export class CoDiscriminatedUnionSchema<
       skipRetry?: boolean;
       unstable_branch?: BranchDefinition;
     },
-  ): Promise<Resolved<
-    CoDiscriminatedUnionInstanceCoValuesNullable<Options> & SchemaUnion,
-    true
-  > | null> {
+  ): Promise<
+    MaybeLoaded<
+      Resolved<
+        CoDiscriminatedUnionInstanceCoValuesMaybeLoaded<Options> & SchemaUnion,
+        true
+      >
+    >
+  > {
     return this.coValueClass.load(id, options) as any;
   }
 
   subscribe(
     id: string,
     options: SubscribeListenerOptions<
-      CoDiscriminatedUnionInstanceCoValuesNullable<Options> & SchemaUnion,
+      CoDiscriminatedUnionInstanceCoValuesMaybeLoaded<Options> & SchemaUnion,
       true
     >,
     listener: (
       value: Resolved<
-        CoDiscriminatedUnionInstanceCoValuesNullable<Options> & SchemaUnion,
+        CoDiscriminatedUnionInstanceCoValuesMaybeLoaded<Options> & SchemaUnion,
         true
       >,
       unsubscribe: () => void,
@@ -133,9 +140,12 @@ export function createCoreCoDiscriminatedUnionSchema<
         return schemas;
       },
     }),
+    resolveQuery: true as const,
   };
 }
 
-type CoDiscriminatedUnionInstanceCoValuesNullable<
+type CoDiscriminatedUnionInstanceCoValuesMaybeLoaded<
   Options extends DiscriminableCoValueSchemas,
-> = NonNullable<InstanceOrPrimitiveOfSchemaCoValuesNullable<Options[number]>>;
+> = LoadedAndRequired<
+  InstanceOrPrimitiveOfSchemaCoValuesMaybeLoaded<Options[number]>
+>;