jazz-tools 0.11.8 → 0.12.0

package/src/coValues/deepLoading.ts

@@ -6,94 +6,208 @@ import { type CoList } from "./coList.js";
 import { type CoKeys, type CoMap } from "./coMap.js";
 import { type CoValue, type ID } from "./interfaces.js";
 
+function hasRefValue(value: CoValue, key: string | number) {
+  return Boolean(
+    (
+      value as unknown as {
+        _refs: { [key: string]: Ref<CoValue> | undefined };
+      }
+    )._refs?.[key],
+  );
+}
+
+function hasReadAccess(value: CoValue, key: string | number) {
+  return Boolean(
+    (
+      value as unknown as {
+        _refs: { [key: string]: Ref<CoValue> | undefined };
+      }
+    )._refs?.[key]?.hasReadAccess(),
+  );
+}
+
+function isOptionalField(value: CoValue, key: string): boolean {
+  return (
+    ((value as CoMap)._schema[key] as RefEncoded<CoValue>)?.optional ?? false
+  );
+}
+
+type FulfillsDepthResult = "unauthorized" | "fulfilled" | "unfulfilled";
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function fulfillsDepth(depth: any, value: CoValue): boolean {
+export function fulfillsDepth(depth: any, value: CoValue): FulfillsDepthResult {
+  if (depth === true || depth === undefined) {
+    return "fulfilled";
+  }
+
   if (
     value._type === "CoMap" ||
     value._type === "Group" ||
     value._type === "Account"
   ) {
-    if (Array.isArray(depth) && depth.length === 1) {
-      return Object.entries(value).every(([key, item]) => {
-        return (
-          value as unknown as {
-            _refs: { [key: string]: Ref<CoValue> | undefined };
+    const map = value as CoMap;
+
+    if ("$each" in depth) {
+      let result: FulfillsDepthResult = "fulfilled";
+
+      for (const [key, item] of Object.entries(value)) {
+        if (map._raw.get(key) !== undefined) {
+          if (!item) {
+            if (hasReadAccess(map, key)) {
+              result = "unfulfilled";
+              continue;
+            } else {
+              return "unauthorized";
+            }
           }
-        )._refs[key]
-          ? item && fulfillsDepth(depth[0], item)
-          : ((value as CoMap)._schema[ItemsSym] as RefEncoded<CoValue>)!
-              .optional;
-      });
+
+          const innerResult = fulfillsDepth(depth.$each, item);
+
+          if (innerResult === "unfulfilled") {
+            result = "unfulfilled";
+          } else if (
+            innerResult === "unauthorized" &&
+            !isOptionalField(value, ItemsSym)
+          ) {
+            return "unauthorized"; // If any item is unauthorized, the whole thing is unauthorized
+          }
+        } else if (!isOptionalField(value, ItemsSym)) {
+          return "unfulfilled";
+        }
+      }
+
+      return result;
     } else {
-      for (const key of Object.keys(depth)) {
-        const map = value as unknown as {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          [key: string]: any;
-        };
+      let result: FulfillsDepthResult = "fulfilled";
 
+      for (const key of Object.keys(depth)) {
         if (map._raw.get(key) === undefined) {
           if (!map._schema?.[key]) {
+            // Field not defined in schema
             if (map._schema?.[ItemsSym]) {
               // CoMap.Record
-              if (map._schema[ItemsSym].optional) {
+              if (isOptionalField(map, ItemsSym)) {
                 continue;
               } else {
+                // All fields are required, so the returned type is not optional and we must comply
                 throw new Error(
                   `The ref ${key} requested on ${map.constructor.name} is missing`,
                 );
               }
             } else {
+              // Field not defined in CoMap schema
               throw new Error(
                 `The ref ${key} requested on ${map.constructor.name} is not defined in the schema`,
               );
             }
-          } else if (map._schema[key].optional) {
+          } else if (isOptionalField(map, key)) {
             continue;
           } else {
+            // Field is required but has never been set
             throw new Error(
               `The ref ${key} on ${map.constructor.name} is required but missing`,
             );
           }
-        }
+        } else {
+          const item = (value as Record<string, any>)[key];
 
-        if (!map[key]) {
-          return false;
-        }
-        if (!fulfillsDepth(depth[key], map[key])) {
-          return false;
+          if (!item) {
+            if (hasReadAccess(map, key)) {
+              result = "unfulfilled";
+              continue;
+            } else {
+              return "unauthorized";
+            }
+          }
+
+          const innerResult = fulfillsDepth(depth[key], item);
+
+          if (innerResult === "unfulfilled") {
+            result = "unfulfilled";
+          } else if (
+            innerResult === "unauthorized" &&
+            !isOptionalField(value, key)
+          ) {
+            return "unauthorized"; // If any item is unauthorized, the whole thing is unauthorized
+          }
         }
       }
-      return true;
+
+      return result;
     }
   } else if (value._type === "CoList") {
-    if (depth.length === 0) {
-      return true;
-    } else {
-      const itemDepth = depth[0];
-      return (value as CoList).every((item, i) =>
-        (value as CoList)._refs[i]
-          ? item && fulfillsDepth(itemDepth, item)
-          : ((value as CoList)._schema[ItemsSym] as RefEncoded<CoValue>)
-              .optional,
-      );
+    if ("$each" in depth) {
+      let result: FulfillsDepthResult = "fulfilled";
+
+      for (const [key, item] of (value as CoList).entries()) {
+        if (hasRefValue(value, key)) {
+          if (!item) {
+            if (hasReadAccess(value, key)) {
+              result = "unfulfilled";
+              continue;
+            } else {
+              return "unauthorized";
+            }
+          }
+
+          const innerResult = fulfillsDepth(depth.$each, item);
+
+          if (innerResult === "unfulfilled") {
+            result = "unfulfilled";
+          } else if (
+            innerResult === "unauthorized" &&
+            !isOptionalField(value, ItemsSym)
+          ) {
+            return "unauthorized"; // If any item is unauthorized, the whole thing is unauthorized
+          }
+        } else if (!isOptionalField(value, ItemsSym)) {
+          return "unfulfilled";
+        }
+      }
+
+      return result;
     }
+
+    return "fulfilled";
   } else if (value._type === "CoStream") {
-    if (depth.length === 0) {
-      return true;
-    } else {
-      const itemDepth = depth[0];
-      return Object.values((value as CoFeed).perSession).every((entry) =>
-        entry.ref
-          ? entry.value && fulfillsDepth(itemDepth, entry.value)
-          : ((value as CoFeed)._schema[ItemsSym] as RefEncoded<CoValue>)
-              .optional,
-      );
+    if ("$each" in depth) {
+      let result: FulfillsDepthResult = "fulfilled";
+
+      for (const item of Object.values((value as CoFeed).perSession)) {
+        if (item.ref) {
+          if (!item.value) {
+            if (item.ref.hasReadAccess()) {
+              result = "unfulfilled";
+              continue;
+            } else {
+              return "unauthorized";
+            }
+          }
+
+          const innerResult = fulfillsDepth(depth.$each, item.value);
+
+          if (innerResult === "unfulfilled") {
+            result = "unfulfilled";
+          } else if (
+            innerResult === "unauthorized" &&
+            !isOptionalField(value, ItemsSym)
+          ) {
+            return "unauthorized"; // If any item is unauthorized, the whole thing is unauthorized
+          }
+        } else if (!isOptionalField(value, ItemsSym)) {
+          return "unfulfilled";
+        }
+      }
+
+      return result;
     }
+
+    return "fulfilled";
   } else if (
     value._type === "BinaryCoStream" ||
     value._type === "CoPlainText"
   ) {
-    return true;
+    return "fulfilled";
   } else {
     console.error(value);
     throw new Error("Unexpected value type: " + value._type);
@@ -101,101 +215,119 @@ export function fulfillsDepth(depth: any, value: CoValue): boolean {
 }
 
 type UnCoNotNull<T> = UnCo<Exclude<T, null>>;
-type Clean<T> = UnCo<NonNullable<T>>;
+export type Clean<T> = UnCo<NonNullable<T>>;
 
-export type DepthsIn<
+export type RefsToResolve<
   V,
-  DepthLimit extends number = 5,
+  DepthLimit extends number = 10,
   CurrentDepth extends number[] = [],
 > =
+  | boolean
   | (DepthLimit extends CurrentDepth["length"]
       ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
         any
       : // Basically V extends CoList - but if we used that we'd introduce circularity into the definition of CoList itself
         V extends Array<infer Item>
         ?
-            | [DepthsIn<UnCoNotNull<Item>, DepthLimit, [0, ...CurrentDepth]>]
-            | never[]
+            | {
+                $each: RefsToResolve<
+                  UnCoNotNull<Item>,
+                  DepthLimit,
+                  [0, ...CurrentDepth]
+                >;
+              }
+            | boolean
         : // Basically V extends CoMap | Group | Account - but if we used that we'd introduce circularity into the definition of CoMap itself
           V extends { _type: "CoMap" | "Group" | "Account" }
           ?
               | {
                   [Key in CoKeys<V> as Clean<V[Key]> extends CoValue
                     ? Key
-                    : never]?: DepthsIn<
+                    : never]?: RefsToResolve<
                     Clean<V[Key]>,
                     DepthLimit,
                     [0, ...CurrentDepth]
                   >;
                 }
               | (ItemsSym extends keyof V
-                  ? [
-                      DepthsIn<
+                  ? {
+                      $each: RefsToResolve<
                         Clean<V[ItemsSym]>,
                         DepthLimit,
                         [0, ...CurrentDepth]
-                      >,
-                    ]
+                      >;
+                    }
                   : never)
-              | never[]
+              | boolean
           : V extends {
                 _type: "CoStream";
                 byMe: CoFeedEntry<infer Item> | undefined;
               }
             ?
-                | [
-                    DepthsIn<
+                | {
+                    $each: RefsToResolve<
                       UnCoNotNull<Item>,
                       DepthLimit,
                       [0, ...CurrentDepth]
-                    >,
-                  ]
-                | never[]
-            : never[])
-  | never[];
+                    >;
+                  }
+                | boolean
+            : boolean);
+
+export type RefsToResolveStrict<T, V> = V extends RefsToResolve<T>
+  ? RefsToResolve<T>
+  : V;
+
+export type Resolved<T, R extends RefsToResolve<T> | undefined> = DeeplyLoaded<
+  T,
+  R,
+  10,
+  []
+>;
 
 export type DeeplyLoaded<
   V,
   Depth,
-  DepthLimit extends number = 5,
+  DepthLimit extends number = 10,
   CurrentDepth extends number[] = [],
 > = DepthLimit extends CurrentDepth["length"]
   ? V
-  : // Basically V extends CoList - but if we used that we'd introduce circularity into the definition of CoList itself
-    [V] extends [Array<infer Item>]
-    ? Depth extends never[] // []
-      ? V
-      : UnCoNotNull<Item> extends CoValue
-        ? Depth extends Array<infer ItemDepth> // [item-depth]
-          ? (UnCoNotNull<Item> &
+  : Depth extends boolean | undefined // Checking against boolean instead of true because the inference from RefsToResolveStrict transforms true into boolean
+    ? V
+    : // Basically V extends CoList - but if we used that we'd introduce circularity into the definition of CoList itself
+      [V] extends [Array<infer Item>]
+      ? UnCoNotNull<Item> extends CoValue
+        ? Depth extends { $each: infer ItemDepth }
+          ? // Deeply loaded CoList
+            (UnCoNotNull<Item> &
               DeeplyLoaded<
                 UnCoNotNull<Item>,
                 ItemDepth,
                 DepthLimit,
                 [0, ...CurrentDepth]
               >)[] &
-              V
+              V // the CoList base type needs to be intersected after so that built-in methods return the correct narrowed array type
           : never
         : V
-    : // Basically V extends CoMap | Group | Account - but if we used that we'd introduce circularity into the definition of CoMap itself
-      [V] extends [{ _type: "CoMap" | "Group" | "Account" }]
-      ? Depth extends never[]
-        ? V
-        : Depth extends Array<infer ItemDepth>
-          ? ItemsSym extends keyof V
-            ? V & {
+      : // Basically V extends CoMap | Group | Account - but if we used that we'd introduce circularity into the definition of CoMap itself
+        [V] extends [{ _type: "CoMap" | "Group" | "Account" }]
+        ? ItemsSym extends keyof V
+          ? Depth extends { $each: infer ItemDepth }
+            ? // Deeply loaded Record-like CoMap
+              {
                 [key: string]: DeeplyLoaded<
                   Clean<V[ItemsSym]>,
                   ItemDepth,
                   DepthLimit,
                   [0, ...CurrentDepth]
                 >;
-              }
+              } & V // same reason as in CoList
             : never
-          : keyof Depth extends never
+          : keyof Depth extends never // Depth = {}
             ? V
-            : {
-                [Key in keyof Depth]-?: Key extends CoKeys<V>
+            : // Deeply loaded CoMap
+              {
+                -readonly [Key in keyof Depth]-?: Key extends CoKeys<V>
                   ? Clean<V[Key]> extends CoValue
                     ?
                         | DeeplyLoaded<
@@ -207,32 +339,31 @@ export type DeeplyLoaded<
                         | (undefined extends V[Key] ? undefined : never)
                     : never
                   : never;
-              } & V
-      : [V] extends [
+              } & V // same reason as in CoList
+        : [V] extends [
+              {
+                _type: "CoStream";
+                byMe: CoFeedEntry<infer Item> | undefined;
+              },
+            ]
+          ? // Deeply loaded CoStream
             {
-              _type: "CoStream";
-              byMe: CoFeedEntry<infer Item> | undefined;
-            },
-          ]
-        ? Depth extends never[]
-          ? V
-          : V & {
               byMe?: { value: UnCoNotNull<Item> };
               inCurrentSession?: { value: UnCoNotNull<Item> };
               perSession: {
                 [key: SessionID]: { value: UnCoNotNull<Item> };
               };
-            } & { [key: ID<Account>]: { value: UnCoNotNull<Item> } }
-        : [V] extends [
-              {
-                _type: "BinaryCoStream";
-              },
-            ]
-          ? V
+            } & { [key: ID<Account>]: { value: UnCoNotNull<Item> } } & V // same reason as in CoList
           : [V] extends [
                 {
-                  _type: "CoPlainText";
+                  _type: "BinaryCoStream";
                 },
               ]
             ? V
-            : never;
+            : [V] extends [
+                  {
+                    _type: "CoPlainText";
+                  },
+                ]
+              ? V
+              : never;

package/src/coValues/group.ts

@@ -10,11 +10,14 @@ import { activeAccountContext } from "../implementation/activeAccountContext.js"
 import type {
   CoValue,
   CoValueClass,
-  DeeplyLoaded,
-  DepthsIn,
   ID,
   RefEncoded,
+  RefsToResolve,
+  RefsToResolveStrict,
+  Resolved,
   Schema,
+  SubscribeListenerOptions,
+  SubscribeRestArgs,
 } from "../internal.js";
 import {
   CoValueBase,
@@ -23,6 +26,7 @@ import {
   ensureCoValueLoaded,
   loadCoValueWithoutMe,
   parseGroupCreateOptions,
+  parseSubscribeRestArgs,
   subscribeToCoValueWithoutMe,
   subscribeToExistingCoValue,
 } from "../internal.js";
@@ -229,73 +233,59 @@ export class Group extends CoValueBase implements CoValue {
   }
 
   /** @category Subscription & Loading */
-  static load<C extends Group, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    depth: Depth & DepthsIn<C>,
-  ): Promise<DeeplyLoaded<C, Depth> | undefined>;
-  static load<C extends Group, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    as: Account,
-    depth: Depth & DepthsIn<C>,
-  ): Promise<DeeplyLoaded<C, Depth> | undefined>;
-  static load<C extends Group, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    asOrDepth: Account | (Depth & DepthsIn<C>),
-    depth?: Depth & DepthsIn<C>,
-  ): Promise<DeeplyLoaded<C, Depth> | undefined> {
-    return loadCoValueWithoutMe(this, id, asOrDepth, depth);
+  static load<G extends Group, const R extends RefsToResolve<G>>(
+    this: CoValueClass<G>,
+    id: ID<G>,
+    options?: { resolve?: RefsToResolveStrict<G, R>; loadAs?: Account },
+  ): Promise<Resolved<G, R> | null> {
+    return loadCoValueWithoutMe(this, id, options);
   }
 
   /** @category Subscription & Loading */
-  static subscribe<C extends Group, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    depth: Depth & DepthsIn<C>,
-    listener: (value: DeeplyLoaded<C, Depth>) => void,
+  static subscribe<G extends Group, const R extends RefsToResolve<G>>(
+    this: CoValueClass<G>,
+    id: ID<G>,
+    listener: (value: Resolved<G, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<C extends Group, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    as: Account,
-    depth: Depth & DepthsIn<C>,
-    listener: (value: DeeplyLoaded<C, Depth>) => void,
+  static subscribe<G extends Group, const R extends RefsToResolve<G>>(
+    this: CoValueClass<G>,
+    id: ID<G>,
+    options: SubscribeListenerOptions<G, R>,
+    listener: (value: Resolved<G, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<C extends Group, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    asOrDepth: Account | (Depth & DepthsIn<C>),
-    depthOrListener:
-      | (Depth & DepthsIn<C>)
-      | ((value: DeeplyLoaded<C, Depth>) => void),
-    listener?: (value: DeeplyLoaded<C, Depth>) => void,
+  static subscribe<G extends Group, const R extends RefsToResolve<G>>(
+    this: CoValueClass<G>,
+    id: ID<G>,
+    ...args: SubscribeRestArgs<G, R>
   ): () => void {
-    return subscribeToCoValueWithoutMe<C, Depth>(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener,
-    );
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe<G, R>(this, id, options, listener);
   }
 
   /** @category Subscription & Loading */
-  ensureLoaded<G extends Group, Depth>(
+  ensureLoaded<G extends Group, const R extends RefsToResolve<G>>(
     this: G,
-    depth: Depth & DepthsIn<G>,
-  ): Promise<DeeplyLoaded<G, Depth>> {
-    return ensureCoValueLoaded(this, depth);
+    options?: { resolve?: RefsToResolveStrict<G, R> },
+  ): Promise<Resolved<G, R>> {
+    return ensureCoValueLoaded(this, options);
   }
 
   /** @category Subscription & Loading */
-  subscribe<G extends Group, Depth>(
+  subscribe<G extends Group, const R extends RefsToResolve<G>>(
+    this: G,
+    listener: (value: Resolved<G, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<G extends Group, const R extends RefsToResolve<G>>(
+    this: G,
+    options: { resolve?: RefsToResolveStrict<G, R> },
+    listener: (value: Resolved<G, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<G extends Group, const R extends RefsToResolve<G>>(
     this: G,
-    depth: Depth & DepthsIn<G>,
-    listener: (value: DeeplyLoaded<G, Depth>) => void,
+    ...args: SubscribeRestArgs<G, R>
   ): () => void {
-    return subscribeToExistingCoValue(this, depth, listener);
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this, options, listener);
   }
 
   /**

package/src/coValues/inbox.ts

@@ -167,12 +167,9 @@ export class Inbox {
                   );
                 }
 
-                return loadCoValue(
-                  Schema,
-                  message.get("payload") as ID<I>,
-                  account,
-                  [],
-                );
+                return loadCoValue(Schema, message.get("payload") as ID<I>, {
+                  loadAs: account,
+                });
               })
               .then((value) => {
                 if (!value) {