jazz-tools 0.19.7 → 0.19.10

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

@@ -6,7 +6,7 @@ import {
   DiscriminableCoValueSchemaDefinition,
   DiscriminableCoreCoValueSchema,
   Group,
-  MaybeLoaded,
+  Settled,
   RefsToResolve,
   RefsToResolveStrict,
   Resolved,
@@ -97,7 +97,7 @@ export class CoMapSchema<
       unstable_branch?: BranchDefinition;
     },
   ): Promise<
-    MaybeLoaded<
+    Settled<
       Resolved<Simplify<CoMapInstanceCoValuesMaybeLoaded<Shape>> & CoMap, R>
     >
   > {
@@ -183,7 +183,7 @@ export class CoMapSchema<
       R
     >;
   }): Promise<
-    MaybeLoaded<
+    Settled<
       Resolved<Simplify<CoMapInstanceCoValuesMaybeLoaded<Shape>> & CoMap, R>
     >
   > {
@@ -210,7 +210,7 @@ export class CoMapSchema<
       loadAs?: Account | AnonymousJazzAgent;
     },
   ): Promise<
-    MaybeLoaded<
+    Settled<
       Resolved<Simplify<CoMapInstanceCoValuesMaybeLoaded<Shape>> & CoMap, R>
     >
   > {

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

@@ -6,7 +6,7 @@ import {
   CoMapSchemaDefinition,
   Group,
   ID,
-  MaybeLoaded,
+  Settled,
   RefsToResolve,
   RefsToResolveStrict,
   Resolved,
@@ -64,9 +64,7 @@ export interface CoRecordSchema<
       loadAs?: Account | AnonymousJazzAgent;
       unstable_branch?: BranchDefinition;
     },
-  ): Promise<
-    MaybeLoaded<Resolved<CoRecordInstanceCoValuesMaybeLoaded<K, V>, R>>
-  >;
+  ): Promise<Settled<Resolved<CoRecordInstanceCoValuesMaybeLoaded<K, V>, R>>>;
 
   unstable_merge<
     const R extends RefsToResolve<
@@ -119,9 +117,7 @@ export interface CoRecordSchema<
     unique: CoValueUniqueness["uniqueness"];
     owner: Account | Group;
     resolve?: RefsToResolveStrict<CoRecordInstanceCoValuesMaybeLoaded<K, V>, R>;
-  }): Promise<
-    MaybeLoaded<Resolved<CoRecordInstanceCoValuesMaybeLoaded<K, V>, R>>
-  >;
+  }): Promise<Settled<Resolved<CoRecordInstanceCoValuesMaybeLoaded<K, V>, R>>>;
 
   loadUnique<
     const R extends RefsToResolve<
@@ -138,9 +134,7 @@ export interface CoRecordSchema<
       >;
       loadAs?: Account | AnonymousJazzAgent;
     },
-  ): Promise<
-    MaybeLoaded<Resolved<CoRecordInstanceCoValuesMaybeLoaded<K, V>, R>>
-  >;
+  ): Promise<Settled<Resolved<CoRecordInstanceCoValuesMaybeLoaded<K, V>, R>>>;
 
   getCoValueClass: () => typeof CoMap;
 

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

@@ -3,7 +3,7 @@ import {
   AnonymousJazzAgent,
   FileStream,
   Group,
-  MaybeLoaded,
+  Settled,
   coOptionalDefiner,
   unstable_mergeBranchWithResolve,
 } from "../../../internal.js";
@@ -82,7 +82,7 @@ export class FileStreamSchema implements CoreFileStreamSchema {
   load(
     id: string,
     options?: { loadAs?: Account | AnonymousJazzAgent },
-  ): Promise<MaybeLoaded<FileStream>> {
+  ): Promise<Settled<FileStream>> {
     return this.coValueClass.load(id, options);
   }
 

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

@@ -6,7 +6,7 @@ import {
 } from "../../../coValues/interfaces.js";
 import {
   Account,
-  MaybeLoaded,
+  Settled,
   RefsToResolve,
   RefsToResolveStrict,
   Resolved,
@@ -52,7 +52,7 @@ export class GroupSchema implements CoreGroupSchema {
       loadAs?: Account;
       resolve?: RefsToResolveStrict<Group, R>;
     },
-  ): Promise<MaybeLoaded<Group>> {
+  ): Promise<Settled<Group>> {
     return Group.load(id, options);
   }
   createInvite<G extends Group>(

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

@@ -4,7 +4,7 @@ import {
   BranchDefinition,
   CoPlainText,
   Group,
-  MaybeLoaded,
+  Settled,
   coOptionalDefiner,
   unstable_mergeBranchWithResolve,
 } from "../../../internal.js";
@@ -50,7 +50,7 @@ export class PlainTextSchema implements CorePlainTextSchema {
       loadAs: Account | AnonymousJazzAgent;
       unstable_branch?: BranchDefinition;
     },
-  ): Promise<MaybeLoaded<CoPlainText>> {
+  ): Promise<Settled<CoPlainText>> {
     return this.coValueClass.load(id, options);
   }
 

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

@@ -3,7 +3,7 @@ import {
   BranchDefinition,
   CoRichText,
   Group,
-  MaybeLoaded,
+  Settled,
   coOptionalDefiner,
   unstable_mergeBranchWithResolve,
 } from "../../../internal.js";
@@ -49,7 +49,7 @@ export class RichTextSchema implements CoreRichTextSchema {
       loadAs: Account | AnonymousJazzAgent;
       unstable_branch?: BranchDefinition;
     },
-  ): Promise<MaybeLoaded<CoRichText>> {
+  ): Promise<Settled<CoRichText>> {
     return this.coValueClass.load(id, options);
   }
 

package/src/tools/subscribe/CoValueCoreSubscription.ts

@@ -1,6 +1,7 @@
 import {
   cojsonInternals,
   CoValueCore,
+  isRawCoID,
   LocalNode,
   RawCoID,
   RawCoValue,
@@ -67,121 +68,76 @@ export class CoValueCoreSubscription {
   private initializeSubscription(): void {
     const source = this.source;
 
-    // If the CoValue is already available, handle it immediately
-    if (source.isAvailable()) {
-      this.handleAvailableSource();
+    // If the ID is not a valid raw CoID, we immediately emit an unavailable event
+    if (!isRawCoID(source.id)) {
+      this.emit(CoValueLoadingState.UNAVAILABLE);
       return;
     }
 
-    // If a specific branch is requested while the source is not available, attempt to checkout that branch
+    // If we have a branch name, we handle branching
     if (this.branchName) {
-      this.handleBranchCheckout();
+      this.handleBranching(this.branchName, this.branchOwnerId);
       return;
     }
 
-    // If we don't have a branch requested, load the CoValue
-    this.loadCoValue();
+    // If we don't have a branch name, we subscribe to the source directly
+    this.subscribe(this.source);
   }
 
-  /**
-   * Handles the case where the CoValue source is immediately available.
-   * Either subscribes directly or attempts to get the requested branch.
-   */
-  private handleAvailableSource(): void {
-    if (!this.branchName || !cojsonInternals.canBeBranched(this.source)) {
-      this.subscribe(this.source.getCurrentContent());
+  private handleBranching(branchName: string, branchOwnerId?: RawCoID) {
+    const source = this.source;
+
+    // If the source is not available, we wait for it to become available and then try to branch
+    if (!source.isAvailable()) {
+      this.waitForSourceToBecomeAvailable(branchName, branchOwnerId);
       return;
     }
 
-    // Try to get the specific branch from the available source
-    const branch = this.source.getBranch(this.branchName, this.branchOwnerId);
-
-    if (branch.isAvailable()) {
-      // Branch is available, subscribe to it
-      this.subscribe(branch.getCurrentContent());
+    // If the source is not branchable (e.g. it is a group), we subscribe to it directly
+    if (!cojsonInternals.canBeBranched(source)) {
+      this.subscribe(source);
       return;
-      // If the branch hasn't been created, we create it directly so we can syncronously subscribe to it
-    } else if (!this.source.hasBranch(this.branchName, this.branchOwnerId)) {
-      this.source.createBranch(this.branchName, this.branchOwnerId);
-      this.subscribe(branch.getCurrentContent());
-    } else {
-      // Branch not available, fall through to checkout logic
-      this.handleBranchCheckout();
     }
-  }
 
-  /**
-   * Attempts to checkout a specific branch of the CoValue.
-   * This is called when the source isn't available but a branch is requested.
-   */
-  private handleBranchCheckout(): void {
-    this.localNode
-      .checkoutBranch(this.source.id, this.branchName!, this.branchOwnerId)
-      .then((value) => {
-        if (this.unsubscribed) return;
-
-        if (value !== CoValueLoadingState.UNAVAILABLE) {
-          // Branch checkout successful, subscribe to it
-          this.subscribe(value);
-        } else {
-          // Branch checkout failed, handle the error
-          this.handleUnavailableBranch();
-        }
-      })
-      .catch((error) => {
-        // Handle unexpected errors during branch checkout
-        console.error(error);
+    // Try to get the specific branch from the available source
+    const branch = source.getBranch(branchName, branchOwnerId);
+
+    // If the branch hasn't been created, we create it directly so we can syncronously subscribe to it
+    if (!branch.isAvailable() && !source.hasBranch(branchName, branchOwnerId)) {
+      try {
+        source.createBranch(branchName, branchOwnerId);
+      } catch (error) {
+        // If the branch creation fails (provided group is not available), we emit an unavailable event
+        console.error("error creating branch", error);
         this.emit(CoValueLoadingState.UNAVAILABLE);
-      });
-  }
-
-  /**
-   * Handles the case where a branch checkout fails.
-   * Determines whether to retry or report unavailability.
-   */
-  private handleUnavailableBranch(): void {
-    const source = this.source;
-    if (source.isAvailable()) {
-      // This should be impossible - if source is available we can create the branch and it should be available
-      throw new Error("Branch is unavailable");
+        return;
+      }
     }
 
-    // Source isn't available either, subscribe to state changes and report unavailability
-    this.subscribeToUnavailableSource();
-    this.emit(CoValueLoadingState.UNAVAILABLE);
+    this.subscribe(branch);
   }
 
   /**
-   * Loads the CoValue core from the network/storage.
-   * This is the fallback strategy when immediate availability fails.
+   * Loads a CoValue core and emits an unavailable event if it is still unavailable after the retries.
    */
-  private loadCoValue(): void {
+  load(value: CoValueCore) {
     this.localNode
-      .loadCoValueCore(this.source.id, undefined, this.skipRetry)
-      .then((value) => {
-        if (this.unsubscribed) return;
-
-        if (value.isAvailable()) {
-          // Loading successful, subscribe to the loaded value
-          this.subscribe(value.getCurrentContent());
-        } else {
-          // Loading failed, subscribe to state changes and report unavailability
-          this.subscribeToUnavailableSource();
+      .loadCoValueCore(value.id, undefined, this.skipRetry)
+      .then(() => {
+        // If after the retries the value is still unavailable, we emit an unavailable event
+        if (!value.isAvailable()) {
           this.emit(CoValueLoadingState.UNAVAILABLE);
         }
-      })
-      .catch((error) => {
-        // Handle unexpected errors during loading
-        console.error(error);
-        this.emit(CoValueLoadingState.UNAVAILABLE);
       });
   }
 
   /**
-   * Subscribes to state changes of an unavailable CoValue source.
-   * This allows the subscription to become active when the source becomes available after a first loading attempt.
+   * Waits for the source to become available and then tries to branch.
    */
-  private subscribeToUnavailableSource(): void {
+  private waitForSourceToBecomeAvailable(
+    branchName: string,
+    branchOwnerId?: RawCoID,
+  ): void {
     const source = this.source;
 
     const handleStateChange = (
@@ -197,41 +153,60 @@ export class CoValueCoreSubscription {
 
       unsubFromStateChange();
 
-      if (this.branchName) {
-        // Branch was requested, attempt checkout again
-        this.handleBranchCheckout();
-      } else {
-        // No branch requested, subscribe directly and cleanup state subscription
-        this.subscribe(source.getCurrentContent());
-      }
+      this.handleBranching(branchName, branchOwnerId);
     };
 
     // Subscribe to state changes and store the unsubscribe function
     this._unsubscribe = source.subscribe(handleStateChange);
+
+    this.load(source);
   }
 
   /**
    * Subscribes to a specific CoValue and notifies the listener.
    * This is the final step where we actually start receiving updates.
    */
-  private subscribe(value: RawCoValue): void {
+  private subscribe(value: CoValueCore): void {
     if (this.unsubscribed) return;
 
     // Subscribe to the value and store the unsubscribe function
     this._unsubscribe = value.subscribe((value) => {
-      this.emit(value);
+      if (value.isAvailable()) {
+        this.emit(value.getCurrentContent());
+      }
     });
+
+    if (!value.isAvailable()) {
+      this.load(value);
+    }
   }
 
+  lastState: CoValueLoadingState | undefined;
+
   emit(value: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE): void {
     if (this.unsubscribed) return;
-    if (!isReadyForEmit(value)) {
+    if (!this.isReadyForEmit(value)) {
       return;
     }
 
     this.listener(value);
   }
 
+  isReadyForEmit(
+    value: RawCoValue | typeof CoValueLoadingState.UNAVAILABLE,
+  ): boolean {
+    if (value === CoValueLoadingState.UNAVAILABLE) {
+      return true;
+    }
+
+    // If the value is not completely downloaded, we don't emit it to avoid providing partial data to the listener.
+    if (!isCompletelyDownloaded(value)) {
+      return false;
+    }
+
+    return true;
+  }
+
   /**
    * Unsubscribes from all active subscriptions and marks the instance as unsubscribed.
    * This prevents any further operations and ensures proper cleanup.
@@ -246,11 +221,7 @@ export class CoValueCoreSubscription {
 /**
  * This is true if the value is unavailable, or if the value is a binary coValue or a completely downloaded coValue.
  */
-function isReadyForEmit(value: RawCoValue | "unavailable") {
-  if (value === "unavailable") {
-    return true;
-  }
-
+function isCompletelyDownloaded(value: RawCoValue) {
   return (
     value.core.verified?.header.meta?.type === "binary" ||
     value.core.isCompletelyDownloaded()

package/src/tools/subscribe/JazzError.ts

@@ -11,21 +11,24 @@ export class JazzError {
   ) {}
 
   toString() {
-    return this.issues
+    // Build the main error message with inline stack info so it shows even if truncated
+    let result = this.issues
       .map((issue) => {
         let message = `${issue.message}`;
 
-        if (this.id) {
-          message += ` from ${this.id}`;
-        }
-
         if (issue.path.length > 0) {
-          message += ` on path ${issue.path.join(".")}`;
+          if (this.id) {
+            message += `. Subscription starts from ${this.id}`;
+          }
+
+          message += ` and the value is on path ${issue.path.join(".")}`;
         }
 
         return message;
       })
       .join("\n");
+
+    return result;
   }
 
   prependPath(item: string) {