jazz-tools 0.11.8 → 0.12.0

package/src/coValues/account.ts

@@ -20,18 +20,22 @@ import {
   type CoValue,
   CoValueBase,
   CoValueClass,
-  DeeplyLoaded,
-  DepthsIn,
   ID,
   Ref,
   type RefEncoded,
   RefIfCoValue,
+  RefsToResolve,
+  RefsToResolveStrict,
+  Resolved,
   type Schema,
   SchemaInit,
+  SubscribeListenerOptions,
+  SubscribeRestArgs,
   ensureCoValueLoaded,
   inspect,
   loadCoValue,
   loadCoValueWithoutMe,
+  parseSubscribeRestArgs,
   subscribeToCoValueWithoutMe,
   subscribeToExistingCoValue,
   subscriptionsScopes,
@@ -225,7 +229,7 @@ export class Account extends CoValueBase implements CoValue {
     valueID: ID<V>,
     inviteSecret: InviteSecret,
     coValueClass: CoValueClass<V>,
-  ) {
+  ): Promise<Resolved<V, true> | null> {
     if (!this.isLocalNodeOwner) {
       throw new Error("Only a controlled account can accept invites");
     }
@@ -235,8 +239,9 @@ export class Account extends CoValueBase implements CoValue {
       inviteSecret,
     );
 
-    return loadCoValue(coValueClass, valueID, this as Account, []);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return loadCoValue(coValueClass, valueID, {
+      loadAs: this,
+    });
   }
 
   /** @private */
@@ -346,73 +351,62 @@ export class Account extends CoValueBase implements CoValue {
   }
 
   /** @category Subscription & Loading */
-  static load<A extends Account, Depth>(
-    this: CoValueClass<A>,
-    id: ID<A>,
-    depth: Depth & DepthsIn<A>,
-  ): Promise<DeeplyLoaded<A, Depth> | undefined>;
-  static load<A extends Account, Depth>(
-    this: CoValueClass<A>,
-    id: ID<A>,
-    as: Account,
-    depth: Depth & DepthsIn<A>,
-  ): Promise<DeeplyLoaded<A, Depth> | undefined>;
-  static load<A extends Account, Depth>(
+  static load<A extends Account, const R extends RefsToResolve<A> = true>(
     this: CoValueClass<A>,
     id: ID<A>,
-    asOrDepth: Account | (Depth & DepthsIn<A>),
-    depth?: Depth & DepthsIn<A>,
-  ): Promise<DeeplyLoaded<A, Depth> | undefined> {
-    return loadCoValueWithoutMe(this, id, asOrDepth, depth);
+    options?: {
+      resolve?: RefsToResolveStrict<A, R>;
+      loadAs?: Account | AnonymousJazzAgent;
+    },
+  ): Promise<Resolved<A, R> | null> {
+    return loadCoValueWithoutMe(this, id, options);
   }
 
   /** @category Subscription & Loading */
-  static subscribe<A extends Account, Depth>(
+  static subscribe<A extends Account, const R extends RefsToResolve<A> = true>(
     this: CoValueClass<A>,
     id: ID<A>,
-    depth: Depth & DepthsIn<A>,
-    listener: (value: DeeplyLoaded<A, Depth>) => void,
+    listener: (value: Resolved<A, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<A extends Account, Depth>(
+  static subscribe<A extends Account, const R extends RefsToResolve<A> = true>(
     this: CoValueClass<A>,
     id: ID<A>,
-    as: Account,
-    depth: Depth & DepthsIn<A>,
-    listener: (value: DeeplyLoaded<A, Depth>) => void,
+    options: SubscribeListenerOptions<A, R>,
+    listener: (value: Resolved<A, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<A extends Account, Depth>(
+  static subscribe<A extends Account, const R extends RefsToResolve<A>>(
     this: CoValueClass<A>,
     id: ID<A>,
-    asOrDepth: Account | (Depth & DepthsIn<A>),
-    depthOrListener:
-      | (Depth & DepthsIn<A>)
-      | ((value: DeeplyLoaded<A, Depth>) => void),
-    listener?: (value: DeeplyLoaded<A, Depth>) => void,
+    ...args: SubscribeRestArgs<A, R>
   ): () => void {
-    return subscribeToCoValueWithoutMe<A, Depth>(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener!,
-    );
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe<A, R>(this, id, options, listener);
   }
 
   /** @category Subscription & Loading */
-  ensureLoaded<A extends Account, Depth>(
+  ensureLoaded<A extends Account, const R extends RefsToResolve<A>>(
     this: A,
-    depth: Depth & DepthsIn<A>,
-  ): Promise<DeeplyLoaded<A, Depth>> {
-    return ensureCoValueLoaded(this, depth);
+    options: { resolve: RefsToResolveStrict<A, R> },
+  ): Promise<Resolved<A, R>> {
+    return ensureCoValueLoaded(this, options);
   }
 
   /** @category Subscription & Loading */
-  subscribe<A extends Account, Depth>(
+  subscribe<A extends Account, const R extends RefsToResolve<A>>(
+    this: A,
+    listener: (value: Resolved<A, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<A extends Account, const R extends RefsToResolve<A>>(
+    this: A,
+    options: { resolve?: RefsToResolveStrict<A, R> },
+    listener: (value: Resolved<A, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<A extends Account, const R extends RefsToResolve<A>>(
     this: A,
-    depth: Depth & DepthsIn<A>,
-    listener: (value: DeeplyLoaded<A, Depth>) => void,
+    ...args: SubscribeRestArgs<A, R>
   ): () => void {
-    return subscribeToExistingCoValue(this, depth, listener);
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this, options, listener);
   }
 
   /**

package/src/coValues/coFeed.ts

@@ -10,17 +10,19 @@ import type {
   SessionID,
 } from "cojson";
 import { MAX_RECOMMENDED_TX_SIZE, cojsonInternals } from "cojson";
-import { activeAccountContext } from "../implementation/activeAccountContext.js";
 import type {
   AnonymousJazzAgent,
   CoValue,
   CoValueClass,
-  DeeplyLoaded,
-  DepthsIn,
   ID,
   IfCo,
+  RefsToResolve,
+  RefsToResolveStrict,
+  Resolved,
   Schema,
   SchemaFor,
+  SubscribeListenerOptions,
+  SubscribeRestArgs,
   UnCo,
 } from "../internal.js";
 import {
@@ -31,11 +33,10 @@ import {
   co,
   ensureCoValueLoaded,
   inspect,
-  isAccountInstance,
   isRefEncoded,
   loadCoValueWithoutMe,
   parseCoValueCreateOptions,
-  subscribeToCoValue,
+  parseSubscribeRestArgs,
   subscribeToCoValueWithoutMe,
   subscribeToExistingCoValue,
 } from "../internal.js";
@@ -327,73 +328,52 @@ export class CoFeed<Item = any> extends CoValueBase implements CoValue {
    * Load a `CoFeed`
    * @category Subscription & Loading
    */
-  static load<S extends CoFeed, Depth>(
-    this: CoValueClass<S>,
-    id: ID<S>,
-    depth: Depth & DepthsIn<S>,
-  ): Promise<DeeplyLoaded<S, Depth> | undefined>;
-  static load<S extends CoFeed, Depth>(
-    this: CoValueClass<S>,
-    id: ID<S>,
-    as: Account,
-    depth: Depth & DepthsIn<S>,
-  ): Promise<DeeplyLoaded<S, Depth> | undefined>;
-  static load<S extends CoFeed, Depth>(
-    this: CoValueClass<S>,
-    id: ID<S>,
-    asOrDepth: Account | (Depth & DepthsIn<S>),
-    depth?: Depth & DepthsIn<S>,
-  ): Promise<DeeplyLoaded<S, Depth> | undefined> {
-    return loadCoValueWithoutMe(this, id, asOrDepth, depth);
+  static load<F extends CoFeed, const R extends RefsToResolve<F> = true>(
+    this: CoValueClass<F>,
+    id: ID<F>,
+    options: {
+      resolve?: RefsToResolveStrict<F, R>;
+      loadAs?: Account | AnonymousJazzAgent;
+    },
+  ): Promise<Resolved<F, R> | null> {
+    return loadCoValueWithoutMe(this, id, options);
   }
 
   /**
    * Subscribe to a `CoFeed`, when you have an ID but don't have a `CoFeed` instance yet
    * @category Subscription & Loading
    */
-  static subscribe<S extends CoFeed, Depth>(
-    this: CoValueClass<S>,
-    id: ID<S>,
-    depth: Depth & DepthsIn<S>,
-    listener: (value: DeeplyLoaded<S, Depth>) => void,
+  static subscribe<F extends CoFeed, const R extends RefsToResolve<F> = true>(
+    this: CoValueClass<F>,
+    id: ID<F>,
+    listener: (value: Resolved<F, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<S extends CoFeed, Depth>(
-    this: CoValueClass<S>,
-    id: ID<S>,
-    as: Account,
-    depth: Depth & DepthsIn<S>,
-    listener: (value: DeeplyLoaded<S, Depth>) => void,
+  static subscribe<F extends CoFeed, const R extends RefsToResolve<F> = true>(
+    this: CoValueClass<F>,
+    id: ID<F>,
+    options: SubscribeListenerOptions<F, R>,
+    listener: (value: Resolved<F, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<S extends CoFeed, Depth>(
-    this: CoValueClass<S>,
-    id: ID<S>,
-    asOrDepth: Account | (Depth & DepthsIn<S>),
-    depthOrListener:
-      | (Depth & DepthsIn<S>)
-      | ((value: DeeplyLoaded<S, Depth>) => void),
-    listener?: (value: DeeplyLoaded<S, Depth>) => void,
+  static subscribe<F extends CoFeed, const R extends RefsToResolve<F>>(
+    this: CoValueClass<F>,
+    id: ID<F>,
+    ...args: SubscribeRestArgs<F, R>
   ): () => void {
-    return subscribeToCoValueWithoutMe<S, Depth>(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener,
-    );
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe<F, R>(this, id, options, 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
+   * @returns A new instance of the same CoFeed that's loaded to the specified depth
    * @category Subscription & Loading
    */
-  ensureLoaded<S extends CoFeed, Depth>(
-    this: S,
-    depth: Depth & DepthsIn<S>,
-  ): Promise<DeeplyLoaded<S, Depth>> {
-    return ensureCoValueLoaded(this, depth);
+  ensureLoaded<F extends CoFeed, const R extends RefsToResolve<F>>(
+    this: F,
+    options?: { resolve?: RefsToResolveStrict<F, R> },
+  ): Promise<Resolved<F, R>> {
+    return ensureCoValueLoaded(this, options);
   }
 
   /**
@@ -402,12 +382,21 @@ export class CoFeed<Item = any> extends CoValueBase implements CoValue {
    * No need to provide an ID or Account since they're already part of the instance.
    * @category Subscription & Loading
    */
-  subscribe<S extends CoFeed, Depth>(
-    this: S,
-    depth: Depth & DepthsIn<S>,
-    listener: (value: DeeplyLoaded<S, Depth>) => void,
+  subscribe<F extends CoFeed, const R extends RefsToResolve<F>>(
+    this: F,
+    listener: (value: Resolved<F, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<F extends CoFeed, const R extends RefsToResolve<F>>(
+    this: F,
+    options: { resolve?: RefsToResolveStrict<F, R> },
+    listener: (value: Resolved<F, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<F extends CoFeed, const R extends RefsToResolve<F>>(
+    this: F,
+    ...args: SubscribeRestArgs<F, R>
   ): () => void {
-    return subscribeToExistingCoValue(this, depth, listener);
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this, options, listener);
   }
 
   /**
@@ -785,34 +774,10 @@ export class FileStream extends CoValueBase implements CoValue {
     id: ID<FileStream>,
     options?: {
       allowUnfinished?: boolean;
-    },
-  ): Promise<Blob | undefined>;
-  static async loadAsBlob(
-    id: ID<FileStream>,
-    as: Account,
-    options?: {
-      allowUnfinished?: boolean;
-    },
-  ): Promise<Blob | undefined>;
-  static async loadAsBlob(
-    id: ID<FileStream>,
-    asOrOptions?:
-      | Account
-      | {
-          allowUnfinished?: boolean;
-        },
-    optionsOrUndefined?: {
-      allowUnfinished?: boolean;
+      loadAs?: Account | AnonymousJazzAgent;
     },
   ): Promise<Blob | undefined> {
-    const as = isAccountInstance(asOrOptions)
-      ? asOrOptions
-      : activeAccountContext.get();
-    const options = isAccountInstance(asOrOptions)
-      ? optionsOrUndefined
-      : asOrOptions;
-
-    let stream = await this.load(id, as, []);
+    let stream = await this.load(id, options);
 
     /**
      * If the user hasn't requested an incomplete blob and the
@@ -820,12 +785,17 @@ export class FileStream extends CoValueBase implements CoValue {
      */
     if (!options?.allowUnfinished && !stream?.isBinaryStreamEnded()) {
       stream = await new Promise<FileStream>((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);
+            }
+          },
+        );
       });
     }
 
@@ -924,78 +894,36 @@ export class FileStream extends CoValueBase implements CoValue {
    * Load a `FileStream`
    * @category Subscription & Loading
    */
-  static load<C extends FileStream, Depth>(
+  static load<C extends FileStream>(
     this: CoValueClass<C>,
     id: ID<C>,
-    depth: Depth & DepthsIn<C>,
-  ): Promise<DeeplyLoaded<C, Depth> | undefined>;
-  static load<C extends FileStream, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    as: Account,
-    depth: Depth & DepthsIn<C>,
-  ): Promise<DeeplyLoaded<C, Depth> | undefined>;
-  static load<C extends FileStream, 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);
+    options?: { loadAs?: Account | AnonymousJazzAgent },
+  ): Promise<Resolved<C, true> | null> {
+    return loadCoValueWithoutMe(this, id, options);
   }
 
   /**
    * Subscribe to a `FileStream`, when you have an ID but don't have a `FileStream` instance yet
    * @category Subscription & Loading
    */
-  static subscribe<C extends FileStream, Depth>(
+  static subscribe<C extends FileStream>(
     this: CoValueClass<C>,
     id: ID<C>,
-    depth: Depth & DepthsIn<C>,
-    listener: (value: DeeplyLoaded<C, Depth>) => void,
-  ): () => void;
-  static subscribe<C extends FileStream, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    as: Account,
-    depth: Depth & DepthsIn<C>,
-    listener: (value: DeeplyLoaded<C, Depth>) => void,
-  ): () => void;
-  static subscribe<C extends FileStream, 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,
+    options: { loadAs?: Account | AnonymousJazzAgent },
+    listener: (value: Resolved<C, true>) => void,
   ): () => void {
-    return subscribeToCoValueWithoutMe<C, Depth>(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener,
-    );
-  }
-
-  ensureLoaded<B extends FileStream, Depth>(
-    this: B,
-    depth: Depth & DepthsIn<B>,
-  ): Promise<DeeplyLoaded<B, Depth> | undefined> {
-    return ensureCoValueLoaded(this, depth);
+    return subscribeToCoValueWithoutMe<C, true>(this, id, options, listener);
   }
 
   /**
    * An instance method to subscribe to an existing `FileStream`
    * @category Subscription & Loading
    */
-  subscribe<B extends FileStream, Depth>(
+  subscribe<B extends FileStream>(
     this: B,
-    depth: Depth & DepthsIn<B>,
-    listener: (value: DeeplyLoaded<B, Depth>) => void,
+    listener: (value: Resolved<B, true>) => void,
   ): () => void {
-    return subscribeToExistingCoValue(this, depth, listener);
+    return subscribeToExistingCoValue(this, {}, listener);
   }
 
   /**

package/src/coValues/coList.ts

@@ -5,12 +5,15 @@ import type {
   CoValue,
   CoValueClass,
   CoValueFromRaw,
-  DeeplyLoaded,
-  DepthsIn,
   ID,
   RefEncoded,
+  RefsToResolve,
+  RefsToResolveStrict,
+  Resolved,
   Schema,
   SchemaFor,
+  SubscribeListenerOptions,
+  SubscribeRestArgs,
   UnCo,
 } from "../internal.js";
 import {
@@ -25,6 +28,7 @@ import {
   loadCoValueWithoutMe,
   makeRefs,
   parseCoValueCreateOptions,
+  parseSubscribeRestArgs,
   subscribeToCoValueWithoutMe,
   subscribeToExistingCoValue,
   subscriptionsScopes,
@@ -419,24 +423,15 @@ export class CoList<Item = any> extends Array<Item> implements CoValue {
    *
    * @category Subscription & Loading
    */
-  static load<C extends CoList, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    depth: Depth & DepthsIn<C>,
-  ): Promise<DeeplyLoaded<C, Depth> | undefined>;
-  static load<C extends CoList, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    as: Account,
-    depth: Depth & DepthsIn<C>,
-  ): Promise<DeeplyLoaded<C, Depth> | undefined>;
-  static load<C extends CoList, 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<L extends CoList, const R extends RefsToResolve<L> = true>(
+    this: CoValueClass<L>,
+    id: ID<L>,
+    options?: {
+      resolve?: RefsToResolveStrict<L, R>;
+      loadAs?: Account | AnonymousJazzAgent;
+    },
+  ): Promise<Resolved<L, R> | null> {
+    return loadCoValueWithoutMe(this, id, options);
   }
 
   /**
@@ -467,35 +462,24 @@ export class CoList<Item = any> extends Array<Item> implements CoValue {
    *
    * @category Subscription & Loading
    */
-  static subscribe<C extends CoList, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    depth: Depth & DepthsIn<C>,
-    listener: (value: DeeplyLoaded<C, Depth>) => void,
+  static subscribe<L extends CoList, const R extends RefsToResolve<L> = true>(
+    this: CoValueClass<L>,
+    id: ID<L>,
+    listener: (value: Resolved<L, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<C extends CoList, Depth>(
-    this: CoValueClass<C>,
-    id: ID<C>,
-    as: Account,
-    depth: Depth & DepthsIn<C>,
-    listener: (value: DeeplyLoaded<C, Depth>) => void,
+  static subscribe<L extends CoList, const R extends RefsToResolve<L> = true>(
+    this: CoValueClass<L>,
+    id: ID<L>,
+    options: SubscribeListenerOptions<L, R>,
+    listener: (value: Resolved<L, R>, unsubscribe: () => void) => void,
   ): () => void;
-  static subscribe<C extends CoList, 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<L extends CoList, const R extends RefsToResolve<L>>(
+    this: CoValueClass<L>,
+    id: ID<L>,
+    ...args: SubscribeRestArgs<L, R>
   ): () => void {
-    return subscribeToCoValueWithoutMe<C, Depth>(
-      this,
-      id,
-      asOrDepth,
-      depthOrListener,
-      listener,
-    );
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe<L, R>(this, id, options, listener);
   }
 
   /**
@@ -505,11 +489,11 @@ export class CoList<Item = any> extends Array<Item> implements CoValue {
    *
    * @category Subscription & Loading
    */
-  ensureLoaded<L extends CoList, Depth>(
+  ensureLoaded<L extends CoList, const R extends RefsToResolve<L>>(
     this: L,
-    depth: Depth & DepthsIn<L>,
-  ): Promise<DeeplyLoaded<L, Depth>> {
-    return ensureCoValueLoaded(this, depth);
+    options: { resolve: RefsToResolveStrict<L, R> },
+  ): Promise<Resolved<L, R>> {
+    return ensureCoValueLoaded(this, options);
   }
 
   /**
@@ -521,12 +505,21 @@ export class CoList<Item = any> extends Array<Item> implements CoValue {
    *
    * @category Subscription & Loading
    **/
-  subscribe<L extends CoList, Depth>(
+  subscribe<L extends CoList, const R extends RefsToResolve<L> = true>(
+    this: L,
+    listener: (value: Resolved<L, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<L extends CoList, const R extends RefsToResolve<L> = true>(
+    this: L,
+    options: { resolve?: RefsToResolveStrict<L, R> },
+    listener: (value: Resolved<L, R>, unsubscribe: () => void) => void,
+  ): () => void;
+  subscribe<L extends CoList, const R extends RefsToResolve<L>>(
     this: L,
-    depth: Depth & DepthsIn<L>,
-    listener: (value: DeeplyLoaded<L, Depth>) => void,
+    ...args: SubscribeRestArgs<L, R>
   ): () => void {
-    return subscribeToExistingCoValue(this, depth, listener);
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToExistingCoValue(this, options, listener);
   }
 
   /** @category Type Helpers */