jazz-tools 0.11.7 → 0.12.0

package/dist/{chunk-HH3Z4JSB.js → chunk-QJNU65NK.js}

@@ -38,7 +38,7 @@ var AnonymousJazzAgent = class {
 };
 
 // src/coValues/interfaces.ts
-import { RawAccount as RawAccount2 } from "cojson";
+import { RawAccount as RawAccount3 } from "cojson";
 
 // src/implementation/inspect.ts
 var inspect = Symbol.for("nodejs.util.inspect.custom");
@@ -48,19 +48,55 @@ var SchemaInit = "$SchemaInit$";
 var ItemsSym = "$items$";
 
 // src/coValues/deepLoading.ts
+function hasRefValue(value, key) {
+  return Boolean(
+    value._refs?.[key]
+  );
+}
+function hasReadAccess(value, key) {
+  return Boolean(
+    value._refs?.[key]?.hasReadAccess()
+  );
+}
+function isOptionalField(value, key) {
+  return value._schema[key]?.optional ?? false;
+}
 function fulfillsDepth(depth, value) {
+  if (depth === true || depth === void 0) {
+    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._refs[key] ? item && fulfillsDepth(depth[0], item) : value._schema[ItemsSym].optional;
-      });
+    const map = value;
+    if ("$each" in depth) {
+      let result = "fulfilled";
+      for (const [key, item] of Object.entries(value)) {
+        if (map._raw.get(key) !== void 0) {
+          if (!item) {
+            if (hasReadAccess(map, 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";
+          }
+        } else if (!isOptionalField(value, ItemsSym)) {
+          return "unfulfilled";
+        }
+      }
+      return result;
     } else {
+      let result = "fulfilled";
       for (const key of Object.keys(depth)) {
-        const map = value;
         if (map._raw.get(key) === void 0) {
           if (!map._schema?.[key]) {
             if (map._schema?.[ItemsSym]) {
-              if (map._schema[ItemsSym].optional) {
+              if (isOptionalField(map, ItemsSym)) {
                 continue;
               } else {
                 throw new Error(
@@ -72,49 +108,96 @@ function fulfillsDepth(depth, value) {
                 `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 {
             throw new Error(
               `The ref ${key} on ${map.constructor.name} is required but missing`
             );
           }
-        }
-        if (!map[key]) {
-          return false;
-        }
-        if (!fulfillsDepth(depth[key], map[key])) {
-          return false;
+        } else {
+          const item = value[key];
+          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";
+          }
         }
       }
-      return true;
+      return result;
     }
   } else if (value._type === "CoList") {
-    if (depth.length === 0) {
-      return true;
-    } else {
-      const itemDepth = depth[0];
-      return value.every(
-        (item, i) => value._refs[i] ? item && fulfillsDepth(itemDepth, item) : value._schema[ItemsSym].optional
-      );
+    if ("$each" in depth) {
+      let result = "fulfilled";
+      for (const [key, item] of value.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";
+          }
+        } 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.perSession).every(
-        (entry) => entry.ref ? entry.value && fulfillsDepth(itemDepth, entry.value) : value._schema[ItemsSym].optional
-      );
+    if ("$each" in depth) {
+      let result = "fulfilled";
+      for (const item of Object.values(value.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";
+          }
+        } 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);
   }
 }
 
+// src/implementation/refs.ts
+import { RawAccount, RawGroup } from "cojson";
+
 // src/lib/cache.ts
 var weakMap = /* @__PURE__ */ new WeakMap();
 var coValuesCache = {
@@ -140,8 +223,30 @@ var Ref = class _Ref {
       throw new Error("Ref must be constructed with a ref schema");
     }
   }
-  get value() {
-    const node = "node" in this.controlledAccount ? this.controlledAccount.node : this.controlledAccount._raw.core.node;
+  getNode() {
+    return "node" in this.controlledAccount ? this.controlledAccount.node : this.controlledAccount._raw.core.node;
+  }
+  hasReadAccess() {
+    const node = this.getNode();
+    const raw = node.getLoaded(this.id);
+    if (!raw) {
+      return true;
+    }
+    if (raw instanceof RawAccount || raw instanceof RawGroup) {
+      return true;
+    }
+    const group = raw.core.getGroup();
+    if (group instanceof RawAccount) {
+      if (node.account.id !== group.id) {
+        return false;
+      }
+    } else if (group.myRole() === void 0) {
+      return false;
+    }
+    return true;
+  }
+  getValueWithoutAccessCheck() {
+    const node = this.getNode();
     const raw = node.getLoaded(this.id);
     if (raw) {
       return coValuesCache.get(
@@ -152,6 +257,12 @@ var Ref = class _Ref {
       return null;
     }
   }
+  get value() {
+    if (!this.hasReadAccess()) {
+      return null;
+    }
+    return this.getValueWithoutAccessCheck();
+  }
   async loadHelper() {
     const node = "node" in this.controlledAccount ? this.controlledAccount.node : this.controlledAccount._raw.core.node;
     const raw = await node.load(this.id);
@@ -194,7 +305,7 @@ var Ref = class _Ref {
       } else if (this.value !== null) {
         const freshValueInstance = instantiateRefEncoded(
           this.schema,
-          this.value?._raw
+          this.value._raw
         );
         TRACE_ACCESSES && console.log("freshValueInstance", freshValueInstance);
         subScope.cachedValues[this.id] = freshValueInstance;
@@ -697,7 +808,7 @@ function isCoValueClass(value) {
 }
 var CoValueBase = class {
   get _owner() {
-    const owner = this._raw.group instanceof RawAccount2 ? RegisteredSchemas["Account"].fromRaw(this._raw.group) : RegisteredSchemas["Group"].fromRaw(this._raw.group);
+    const owner = this._raw.group instanceof RawAccount3 ? RegisteredSchemas["Account"].fromRaw(this._raw.group) : RegisteredSchemas["Group"].fromRaw(this._raw.group);
     const subScope = subscriptionsScopes.get(this);
     if (subScope) {
       subScope.onRefAccessedOrSet(this.id, owner.id);
@@ -708,7 +819,7 @@ var CoValueBase = class {
   /** @private */
   get _loadedAs() {
     const rawAccount = this._raw.core.node.account;
-    if (rawAccount instanceof RawAccount2) {
+    if (rawAccount instanceof RawAccount3) {
       return coValuesCache.get(
         rawAccount,
         () => RegisteredSchemas["Account"].fromRaw(rawAccount)
@@ -748,77 +859,90 @@ var CoValueBase = class {
     return casted;
   }
 };
-function loadCoValueWithoutMe(cls, id, asOrDepth, depth) {
-  if (isAccountInstance(asOrDepth) || isAnonymousAgentInstance(asOrDepth)) {
-    if (!depth) {
-      throw new Error(
-        "Depth is required when loading a CoValue as an Account or AnonymousJazzAgent"
-      );
-    }
-    return loadCoValue2(cls, id, asOrDepth, depth);
-  }
-  return loadCoValue2(cls, id, activeAccountContext.get(), asOrDepth);
+function loadCoValueWithoutMe(cls, id, options) {
+  return loadCoValue2(cls, id, {
+    ...options,
+    loadAs: options?.loadAs ?? activeAccountContext.get()
+  });
 }
-function loadCoValue2(cls, id, as, depth) {
+function loadCoValue2(cls, id, options) {
   return new Promise((resolve) => {
     subscribeToCoValue(
       cls,
       id,
-      as,
-      depth,
+      {
+        resolve: options.resolve,
+        loadAs: options.loadAs,
+        onUnavailable: () => {
+          resolve(null);
+        },
+        onUnauthorized: () => {
+          resolve(null);
+        }
+      },
       (value, unsubscribe) => {
         resolve(value);
         unsubscribe();
-      },
-      () => {
-        resolve(void 0);
       }
     );
   });
 }
-async function ensureCoValueLoaded(existing, depth) {
+async function ensureCoValueLoaded(existing, options) {
   const response = await loadCoValue2(
     existing.constructor,
     existing.id,
-    existing._loadedAs,
-    depth
+    {
+      loadAs: existing._loadedAs,
+      resolve: options?.resolve
+    }
   );
   if (!response) {
     throw new Error("Failed to deeply load CoValue " + existing.id);
   }
   return response;
 }
-function subscribeToCoValueWithoutMe(cls, id, asOrDepth, depthOrListener, listener) {
-  if (isAccountInstance(asOrDepth) || isAnonymousAgentInstance(asOrDepth)) {
-    if (typeof depthOrListener !== "function") {
-      return subscribeToCoValue(
-        cls,
-        id,
-        asOrDepth,
-        depthOrListener,
-        listener
-      );
+function parseSubscribeRestArgs(args) {
+  if (args.length === 2) {
+    if (typeof args[0] === "object" && args[0] && typeof args[1] === "function") {
+      return {
+        options: {
+          resolve: args[0].resolve,
+          loadAs: args[0].loadAs,
+          onUnauthorized: args[0].onUnauthorized,
+          onUnavailable: args[0].onUnavailable
+        },
+        listener: args[1]
+      };
+    } else {
+      throw new Error("Invalid arguments");
+    }
+  } else {
+    if (typeof args[0] === "function") {
+      return { options: {}, listener: args[0] };
+    } else {
+      throw new Error("Invalid arguments");
     }
-    throw new Error("Invalid arguments");
-  }
-  if (typeof depthOrListener !== "function") {
-    throw new Error("Invalid arguments");
   }
+}
+function subscribeToCoValueWithoutMe(cls, id, options, listener) {
   return subscribeToCoValue(
     cls,
     id,
-    activeAccountContext.get(),
-    asOrDepth,
-    depthOrListener
+    {
+      ...options,
+      loadAs: options.loadAs ?? activeAccountContext.get()
+    },
+    listener
   );
 }
-function subscribeToCoValue(cls, id, as, depth, listener, onUnavailable, syncResolution) {
-  const ref2 = new Ref(id, as, { ref: cls, optional: false });
+function subscribeToCoValue(cls, id, options, listener) {
+  const ref2 = new Ref(id, options.loadAs, { ref: cls, optional: false });
   let unsubscribed = false;
   let unsubscribe;
-  function subscribe(value) {
+  function subscribe() {
+    const value = ref2.getValueWithoutAccessCheck();
     if (!value) {
-      onUnavailable && onUnavailable();
+      options.onUnavailable?.();
       return;
     }
     if (unsubscribed) return;
@@ -826,27 +950,48 @@ function subscribeToCoValue(cls, id, as, depth, listener, onUnavailable, syncRes
       value,
       cls,
       (update, subscription2) => {
-        if (subscription2.syncResolution) return false;
-        subscription2.syncResolution = true;
-        const isLoaded = fulfillsDepth(depth, update);
-        subscription2.syncResolution = false;
-        if (isLoaded) {
-          listener(
-            update,
-            subscription2.unsubscribeAll
+        if (subscription2.syncResolution) return;
+        if (!ref2.hasReadAccess()) {
+          options.onUnauthorized?.();
+          return;
+        }
+        let result;
+        try {
+          subscription2.syncResolution = true;
+          result = fulfillsDepth(options.resolve, update);
+        } catch (e) {
+          console.error(
+            "Failed to load / subscribe to CoValue",
+            e,
+            e instanceof Error ? e.stack : void 0
           );
+          options.onUnavailable?.();
+          return;
+        } finally {
+          subscription2.syncResolution = false;
+        }
+        if (result === "unauthorized") {
+          options.onUnauthorized?.();
+          return;
+        }
+        if (result === "fulfilled") {
+          listener(update, subscription2.unsubscribeAll);
         }
       }
     );
     unsubscribe = subscription.unsubscribeAll;
   }
-  const sync = syncResolution ? ref2.syncLoad() : void 0;
+  const sync = options.syncResolution ? ref2.syncLoad() : void 0;
   if (sync) {
-    subscribe(sync);
+    subscribe();
   } else {
-    ref2.load().then((value) => subscribe(value)).catch((e) => {
-      console.error("Failed to load / subscribe to CoValue", e);
-      onUnavailable?.();
+    ref2.load().then(() => subscribe()).catch((e) => {
+      console.error(
+        "Failed to load / subscribe to CoValue",
+        e,
+        e instanceof Error ? e.stack : void 0
+      );
+      options.onUnavailable?.();
     });
   }
   return function unsubscribeAtAnyPoint() {
@@ -854,25 +999,31 @@ function subscribeToCoValue(cls, id, as, depth, listener, onUnavailable, syncRes
     unsubscribe && unsubscribe();
   };
 }
-function createCoValueObservable(options) {
+function createCoValueObservable() {
   let currentValue = void 0;
   let subscriberCount = 0;
-  function subscribe(cls, id, as, depth, listener, onUnavailable) {
+  function subscribe(cls, id, options, listener) {
     subscriberCount++;
     const unsubscribe = subscribeToCoValue(
       cls,
       id,
-      as,
-      depth,
+      {
+        loadAs: options.loadAs,
+        resolve: options.resolve,
+        onUnavailable: () => {
+          currentValue = null;
+          options.onUnavailable?.();
+        },
+        onUnauthorized: () => {
+          currentValue = null;
+          options.onUnauthorized?.();
+        },
+        syncResolution: options.syncResolution
+      },
       (value) => {
         currentValue = value;
         listener();
-      },
-      () => {
-        currentValue = null;
-        onUnavailable?.();
-      },
-      options?.syncResolution
+      }
     );
     return () => {
       unsubscribe();
@@ -888,12 +1039,16 @@ function createCoValueObservable(options) {
   };
   return observable;
 }
-function subscribeToExistingCoValue(existing, depth, listener) {
+function subscribeToExistingCoValue(existing, options, listener) {
   return subscribeToCoValue(
     existing.constructor,
     existing.id,
-    existing._loadedAs,
-    depth,
+    {
+      loadAs: existing._loadedAs,
+      resolve: options?.resolve,
+      onUnavailable: options?.onUnavailable,
+      onUnauthorized: options?.onUnauthorized
+    },
     listener
   );
 }
@@ -903,12 +1058,6 @@ function isAccountInstance(instance) {
   }
   return "_type" in instance && instance._type === "Account";
 }
-function isAnonymousAgentInstance(instance) {
-  if (typeof instance !== "object" || instance === null) {
-    return false;
-  }
-  return "_type" in instance && instance._type === "Anonymous";
-}
 function parseCoValueCreateOptions(options) {
   const Group2 = RegisteredSchemas["Group"];
   if (!options) {
@@ -934,7 +1083,7 @@ function parseGroupCreateOptions(options) {
 
 // src/coValues/inbox.ts
 import {
-  RawAccount as RawAccount3
+  RawAccount as RawAccount4
 } from "cojson";
 function createInboxRoot(account) {
   if (!account.isLocalNodeOwner) {
@@ -957,7 +1106,7 @@ function createInboxRoot(account) {
 }
 function createInboxMessage(payload, inboxOwner) {
   const group = payload._raw.group;
-  if (group instanceof RawAccount3) {
+  if (group instanceof RawAccount4) {
     throw new Error("Inbox messages should be owned by a group");
   }
   group.addMember(inboxOwner, "writer");
@@ -1015,12 +1164,9 @@ var Inbox = class _Inbox {
                   new Error("Unable to load inbox message " + id)
                 );
               }
-              return loadCoValue2(
-                Schema,
-                message.get("payload"),
-                account,
-                []
-              );
+              return loadCoValue2(Schema, message.get("payload"), {
+                loadAs: account
+              });
             }).then((value) => {
               if (!value) {
                 return Promise.reject(
@@ -1397,17 +1543,32 @@ var _CoMap = class _CoMap extends CoValueBase {
     }
     return RecordLikeCoMap;
   }
-  static load(id, asOrDepth, depth) {
-    return loadCoValueWithoutMe(this, id, asOrDepth, depth);
+  /**
+   * Load a `CoMap` with a given ID, as a given account.
+   *
+   * `depth` specifies which (if any) fields that reference other CoValues to load as well before resolving.
+   * The `DeeplyLoaded` return type guarantees that corresponding referenced CoValues are loaded to the specified depth.
+   *
+   * You can pass `[]` or `{}` for shallowly loading only this CoMap, or `{ fieldA: depthA, fieldB: depthB }` for recursively loading referenced CoValues.
+   *
+   * Check out the `load` methods on `CoMap`/`CoList`/`CoFeed`/`Group`/`Account` to see which depth structures are valid to nest.
+   *
+   * @example
+   * ```ts
+   * const person = await Person.load(
+   *   "co_zdsMhHtfG6VNKt7RqPUPvUtN2Ax",
+   *   { pet: {} }
+   * );
+   * ```
+   *
+   * @category Subscription & Loading
+   */
+  static load(id, options) {
+    return loadCoValueWithoutMe(this, id, options);
   }
-  static subscribe(id, asOrDepth, depthOrListener, listener) {
-    return subscribeToCoValueWithoutMe(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener
-    );
+  static subscribe(id, ...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe(this, id, options, listener);
   }
   static findUnique(unique, ownerID, as) {
     as ||= activeAccountContext.get();
@@ -1430,20 +1591,12 @@ var _CoMap = class _CoMap extends CoValueBase {
    *
    * @category Subscription & Loading
    */
-  ensureLoaded(depth) {
-    return ensureCoValueLoaded(this, depth);
+  ensureLoaded(options) {
+    return ensureCoValueLoaded(this, options);
   }
-  /**
-   * Given an already loaded `CoMap`, subscribe to updates to the `CoMap` and ensure that the specified fields are loaded to the specified depth.
-   *
-   * Works like `CoMap.subscribe()`, but you don't need to pass the ID or the account to load as again.
-   *
-   * Returns an unsubscribe function that you should call when you no longer need updates.
-   *
-   * @category Subscription & Loading
-   **/
-  subscribe(depth, listener) {
-    return subscribeToExistingCoValue(this, depth, listener);
+  subscribe(...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this, options, listener);
   }
   applyDiff(newValues) {
     for (const key in newValues) {
@@ -1625,7 +1778,7 @@ var Profile = class extends CoMap {
 // src/coValues/account.ts
 import {
   LocalNode as LocalNode2,
-  RawAccount as RawAccount4,
+  RawAccount as RawAccount5,
   cojsonInternals as cojsonInternals2
 } from "cojson";
 var _Account = class _Account extends CoValueBase {
@@ -1638,7 +1791,7 @@ var _Account = class _Account extends CoValueBase {
   get _loadedAs() {
     if (this.isLocalNodeOwner) return this;
     const rawAccount = this._raw.core.node.account;
-    if (rawAccount instanceof RawAccount4) {
+    if (rawAccount instanceof RawAccount5) {
       return coValuesCache.get(rawAccount, () => _Account.fromRaw(rawAccount));
     }
     return new AnonymousJazzAgent(this._raw.core.node);
@@ -1729,7 +1882,9 @@ var _Account = class _Account extends CoValueBase {
       valueID,
       inviteSecret
     );
-    return loadCoValue2(coValueClass, valueID, this, []);
+    return loadCoValue2(coValueClass, valueID, {
+      loadAs: this
+    });
   }
   /** @private */
   static async create(options) {
@@ -1800,25 +1955,21 @@ var _Account = class _Account extends CoValueBase {
   migrate(creationProps) {
     creationProps;
   }
-  static load(id, asOrDepth, depth) {
-    return loadCoValueWithoutMe(this, id, asOrDepth, depth);
+  /** @category Subscription & Loading */
+  static load(id, options) {
+    return loadCoValueWithoutMe(this, id, options);
   }
-  static subscribe(id, asOrDepth, depthOrListener, listener) {
-    return subscribeToCoValueWithoutMe(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener
-    );
+  static subscribe(id, ...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe(this, id, options, listener);
   }
   /** @category Subscription & Loading */
-  ensureLoaded(depth) {
-    return ensureCoValueLoaded(this, depth);
+  ensureLoaded(options) {
+    return ensureCoValueLoaded(this, options);
   }
-  /** @category Subscription & Loading */
-  subscribe(depth, listener) {
-    return subscribeToExistingCoValue(this, depth, listener);
+  subscribe(...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this, options, listener);
   }
   /**
    * Wait for the `Account` to be uploaded to the other peers.
@@ -2058,36 +2209,29 @@ var _CoFeed = class _CoFeed extends CoValueBase {
     this._schema ||= {};
     Object.assign(this._schema, def);
   }
-  static load(id, asOrDepth, depth) {
-    return loadCoValueWithoutMe(this, id, asOrDepth, depth);
-  }
-  static subscribe(id, asOrDepth, depthOrListener, listener) {
-    return subscribeToCoValueWithoutMe(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener
-    );
-  }
   /**
-   * Ensure a `CoFeed` is loaded to the specified depth
-   *
-   * @returns A new instance of the same CoFeed that's loaded to the specified depth,
-   * or undefined if it cannot be loaded that deeply
+   * Load a `CoFeed`
    * @category Subscription & Loading
    */
-  ensureLoaded(depth) {
-    return ensureCoValueLoaded(this, depth);
+  static load(id, options) {
+    return loadCoValueWithoutMe(this, id, options);
+  }
+  static subscribe(id, ...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe(this, id, options, listener);
   }
   /**
-   * An instance method to subscribe to an existing `CoFeed`
+   * Ensure a `CoFeed` is loaded to the specified depth
    *
-   * No need to provide an ID or Account since they're already part of the instance.
+   * @returns A new instance of the same CoFeed that's loaded to the specified depth
    * @category Subscription & Loading
    */
-  subscribe(depth, listener) {
-    return subscribeToExistingCoValue(this, depth, listener);
+  ensureLoaded(options) {
+    return ensureCoValueLoaded(this, options);
+  }
+  subscribe(...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this, options, listener);
   }
   /**
    * Wait for the `CoFeed` to be uploaded to the other peers.
@@ -2336,18 +2480,26 @@ var FileStream = class extends CoValueBase {
     }
     return new Blob(chunks.chunks, { type: chunks.mimeType });
   }
-  static async loadAsBlob(id, asOrOptions, optionsOrUndefined) {
-    const as = isAccountInstance(asOrOptions) ? asOrOptions : activeAccountContext.get();
-    const options = isAccountInstance(asOrOptions) ? optionsOrUndefined : asOrOptions;
-    let stream = await this.load(id, as, []);
+  /**
+   * Load a `FileStream` as a `Blob`
+   *
+   * @category Content
+   */
+  static async loadAsBlob(id, options) {
+    let stream = await this.load(id, options);
     if (!options?.allowUnfinished && !stream?.isBinaryStreamEnded()) {
       stream = await new Promise((resolve) => {
-        subscribeToCoValue(this, id, as, [], (value, unsubscribe) => {
-          if (value.isBinaryStreamEnded()) {
-            unsubscribe();
-            resolve(value);
+        subscribeToCoValueWithoutMe(
+          this,
+          id,
+          options || {},
+          (value, unsubscribe) => {
+            if (value.isBinaryStreamEnded()) {
+              unsubscribe();
+              resolve(value);
+            }
           }
-        });
+        );
       });
     }
     return stream?.toBlob({
@@ -2411,27 +2563,26 @@ var FileStream = class extends CoValueBase {
   [inspect]() {
     return this.toJSON();
   }
-  static load(id, asOrDepth, depth) {
-    return loadCoValueWithoutMe(this, id, asOrDepth, depth);
-  }
-  static subscribe(id, asOrDepth, depthOrListener, listener) {
-    return subscribeToCoValueWithoutMe(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener
-    );
+  /**
+   * Load a `FileStream`
+   * @category Subscription & Loading
+   */
+  static load(id, options) {
+    return loadCoValueWithoutMe(this, id, options);
   }
-  ensureLoaded(depth) {
-    return ensureCoValueLoaded(this, depth);
+  /**
+   * Subscribe to a `FileStream`, when you have an ID but don't have a `FileStream` instance yet
+   * @category Subscription & Loading
+   */
+  static subscribe(id, options, listener) {
+    return subscribeToCoValueWithoutMe(this, id, options, listener);
   }
   /**
    * An instance method to subscribe to an existing `FileStream`
    * @category Subscription & Loading
    */
-  subscribe(depth, listener) {
-    return subscribeToExistingCoValue(this, depth, listener);
+  subscribe(listener) {
+    return subscribeToExistingCoValue(this, {}, listener);
   }
   /**
    * Wait for the `FileStream` to be uploaded to the other peers.
@@ -2444,7 +2595,7 @@ var FileStream = class extends CoValueBase {
 };
 
 // src/coValues/coList.ts
-import { RawAccount as RawAccount5 } from "cojson";
+import { RawAccount as RawAccount6 } from "cojson";
 import { calcPatch } from "fast-myers-diff";
 var _CoList = class _CoList extends Array {
   /**
@@ -2483,7 +2634,7 @@ var _CoList = class _CoList extends Array {
   }
   /** @category Collaboration */
   get _owner() {
-    return this._raw.group instanceof RawAccount5 ? RegisteredSchemas["Account"].fromRaw(this._raw.group) : RegisteredSchemas["Group"].fromRaw(this._raw.group);
+    return this._raw.group instanceof RawAccount6 ? RegisteredSchemas["Account"].fromRaw(this._raw.group) : RegisteredSchemas["Group"].fromRaw(this._raw.group);
   }
   /**
    * If a `CoList`'s items are a `co.ref(...)`, you can use `coList._refs[i]` to access
@@ -2515,7 +2666,7 @@ var _CoList = class _CoList extends Array {
   }
   get _loadedAs() {
     const rawAccount = this._raw.core.node.account;
-    if (rawAccount instanceof RawAccount5) {
+    if (rawAccount instanceof RawAccount6) {
       return coValuesCache.get(
         rawAccount,
         () => RegisteredSchemas["Account"].fromRaw(rawAccount)
@@ -2690,39 +2841,48 @@ var _CoList = class _CoList extends Array {
     this._schema ||= {};
     Object.assign(this._schema, def);
   }
-  static load(id, asOrDepth, depth) {
-    return loadCoValueWithoutMe(this, id, asOrDepth, depth);
-  }
-  static subscribe(id, asOrDepth, depthOrListener, listener) {
-    return subscribeToCoValueWithoutMe(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener
-    );
-  }
   /**
-   * Given an already loaded `CoList`, ensure that items are loaded to the specified depth.
+   * Load a `CoList` with a given ID, as a given account.
    *
-   * Works like `CoList.load()`, but you don't need to pass the ID or the account to load as again.
+   * `depth` specifies if item CoValue references should be loaded as well before resolving.
+   * The `DeeplyLoaded` return type guarantees that corresponding referenced CoValues are loaded to the specified depth.
+   *
+   * You can pass `[]` or for shallowly loading only this CoList, or `[itemDepth]` for recursively loading referenced CoValues.
+   *
+   * Check out the `load` methods on `CoMap`/`CoList`/`CoFeed`/`Group`/`Account` to see which depth structures are valid to nest.
+   *
+   * @example
+   * ```ts
+   * const animalsWithVets =
+   *   await ListOfAnimals.load(
+   *     "co_zdsMhHtfG6VNKt7RqPUPvUtN2Ax",
+   *     me,
+   *     [{ vet: {} }]
+   *   );
+   * ```
    *
    * @category Subscription & Loading
    */
-  ensureLoaded(depth) {
-    return ensureCoValueLoaded(this, depth);
+  static load(id, options) {
+    return loadCoValueWithoutMe(this, id, options);
+  }
+  static subscribe(id, ...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe(this, id, options, listener);
   }
   /**
-   * Given an already loaded `CoList`, subscribe to updates to the `CoList` and ensure that items are loaded to the specified depth.
-   *
-   * Works like `CoList.subscribe()`, but you don't need to pass the ID or the account to load as again.
+   * Given an already loaded `CoList`, ensure that items are loaded to the specified depth.
    *
-   * Returns an unsubscribe function that you should call when you no longer need updates.
+   * Works like `CoList.load()`, but you don't need to pass the ID or the account to load as again.
    *
    * @category Subscription & Loading
-   **/
-  subscribe(depth, listener) {
-    return subscribeToExistingCoValue(this, depth, listener);
+   */
+  ensureLoaded(options) {
+    return ensureCoValueLoaded(this, options);
+  }
+  subscribe(...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this, options, listener);
   }
   /** @category Type Helpers */
   castAs(cl) {
@@ -2937,25 +3097,21 @@ var _Group = class _Group extends CoValueBase {
     await this._raw.revokeExtend(parent._raw);
     return this;
   }
-  static load(id, asOrDepth, depth) {
-    return loadCoValueWithoutMe(this, id, asOrDepth, depth);
+  /** @category Subscription & Loading */
+  static load(id, options) {
+    return loadCoValueWithoutMe(this, id, options);
   }
-  static subscribe(id, asOrDepth, depthOrListener, listener) {
-    return subscribeToCoValueWithoutMe(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener
-    );
+  static subscribe(id, ...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe(this, id, options, listener);
   }
   /** @category Subscription & Loading */
-  ensureLoaded(depth) {
-    return ensureCoValueLoaded(this, depth);
+  ensureLoaded(options) {
+    return ensureCoValueLoaded(this, options);
   }
-  /** @category Subscription & Loading */
-  subscribe(depth, listener) {
-    return subscribeToExistingCoValue(this, depth, listener);
+  subscribe(...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this, options, listener);
   }
   /**
    * Wait for the `Group` to be uploaded to the other peers.
@@ -2983,12 +3139,12 @@ function isAccountID(id) {
 
 // src/coValues/coPlainText.ts
 import {
-  RawAccount as RawAccount6,
+  RawAccount as RawAccount7,
   stringifyOpID
 } from "cojson";
 var CoPlainText = class extends String {
   get _owner() {
-    return this._raw.group instanceof RawAccount6 ? Account.fromRaw(this._raw.group) : Group.fromRaw(this._raw.group);
+    return this._raw.group instanceof RawAccount7 ? Account.fromRaw(this._raw.group) : Group.fromRaw(this._raw.group);
   }
   get _loadedAs() {
     return Account.fromNode(this._raw.core.node);
@@ -3051,34 +3207,13 @@ var CoPlainText = class extends String {
    *
    * @category Subscription & Loading
    */
-  static load(id, as) {
-    return loadCoValue2(this, id, as ?? activeAccountContext.get(), []);
+  static load(id, options) {
+    return loadCoValueWithoutMe(this, id, options);
   }
-  static subscribe(id, asOrListener, listener) {
-    if (isAccountInstance(asOrListener)) {
-      return subscribeToCoValue(this, id, asOrListener, [], listener);
-    }
-    return subscribeToCoValue(
-      this,
-      id,
-      activeAccountContext.get(),
-      [],
-      listener
-    );
+  static subscribe(id, ...args) {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe(this, id, options, listener);
   }
-  //   /**
-  //    * Effectful version of `CoMap.subscribe()` that returns a stream of updates.
-  //    *
-  //    * Needs to be run inside an `AccountCtx` context.
-  //    *
-  //    * @category Subscription & Loading
-  //    */
-  //   static subscribeEf<T extends CoPlainText>(
-  //     this: CoValueClass<T>,
-  //     id: ID<T>,
-  //   ): Stream.Stream<T, UnavailableError, AccountCtx> {
-  //     return subscribeToCoValueEf(this, id, []);
-  //   }
   /**
    * Given an already loaded `CoPlainText`, subscribe to updates to the `CoPlainText` and ensure that the specified fields are loaded to the specified depth.
    *
@@ -3089,7 +3224,7 @@ var CoPlainText = class extends String {
    * @category Subscription & Loading
    **/
   subscribe(listener) {
-    return subscribeToExistingCoValue(this, [], listener);
+    return subscribeToExistingCoValue(this, {}, listener);
   }
 };
 
@@ -3956,7 +4091,9 @@ var DemoAuth = class {
         throw new Error("No credentials found");
       }
       const currentAccount = await Account.getMe().ensureLoaded({
-        profile: {}
+        resolve: {
+          profile: true
+        }
       });
       currentAccount.profile.name = username;
       await this.authSecretStorage.set({
@@ -4097,7 +4234,9 @@ var PassphraseAuth = class {
       });
       if (name?.trim()) {
         const currentAccount = await Account.getMe().ensureLoaded({
-          profile: {}
+          resolve: {
+            profile: true
+          }
         });
         currentAccount.profile.name = name;
       }
@@ -4240,4 +4379,4 @@ export {
   consumeInviteLink
 };
 /* istanbul ignore file -- @preserve */
-//# sourceMappingURL=chunk-HH3Z4JSB.js.map
+//# sourceMappingURL=chunk-QJNU65NK.js.map