jazz-tools 0.18.2 → 0.18.4

package/src/tools/subscribe/CoValueCoreSubscription.ts

@@ -1,76 +1,212 @@
-import { CoValueCore, LocalNode, RawCoMap, RawCoValue } from "cojson";
+import { CoValueCore, LocalNode, RawCoID, RawCoValue } from "cojson";
+import type { Account, Group } from "../internal.js";
 
+export type BranchDefinition = { name: string; owner?: Group | Account };
+
+/**
+ * Manages subscriptions to CoValue cores, handling both direct subscriptions
+ * and branch-based subscriptions with automatic loading and error handling.
+ *
+ * It tries to resolve the value immediately if already available in memory.
+ */
 export class CoValueCoreSubscription {
-  _unsubscribe: () => void = () => {};
-  unsubscribed = false;
+  private _unsubscribe: () => void = () => {};
+  private unsubscribed = false;
 
-  value: RawCoMap | undefined;
+  private branchOwnerId?: RawCoID;
+  private branchName?: string;
+  private source: CoValueCore;
+  private localNode: LocalNode;
+  private listener: (value: RawCoValue | "unavailable") => void;
+  private skipRetry?: boolean;
 
   constructor(
-    public node: LocalNode,
-    public id: string,
-    public listener: (value: RawCoValue | "unavailable") => void,
-    public skipRetry?: boolean,
+    localNode: LocalNode,
+    id: string,
+    listener: (value: RawCoValue | "unavailable") => void,
+    skipRetry?: boolean,
+    branch?: BranchDefinition,
   ) {
-    const entry = this.node.getCoValue(this.id as any);
+    this.localNode = localNode;
+    this.listener = listener;
+    this.skipRetry = skipRetry;
+    this.branchName = branch?.name;
+    this.branchOwnerId = branch?.owner?.$jazz.raw.id;
+    this.source = localNode.getCoValue(id as RawCoID);
+
+    this.initializeSubscription();
+  }
+
+  /**
+   * Main entry point for subscription initialization.
+   * Determines the subscription strategy based on current availability and branch requirements.
+   */
+  private initializeSubscription(): void {
+    const source = this.source;
+
+    // If the CoValue is already available, handle it immediately
+    if (source.isAvailable()) {
+      this.handleAvailableSource(source);
+      return;
+    }
+
+    // If a specific branch is requested while the source is not available, attempt to checkout that branch
+    if (this.branchName) {
+      this.handleBranchCheckout();
+      return;
+    }
 
-    if (entry?.isAvailable()) {
-      this.subscribe(entry.getCurrentContent());
+    // If we don't have a branch requested, load the CoValue
+    this.loadCoValue();
+  }
+
+  /**
+   * Handles the case where the CoValue source is immediately available.
+   * Either subscribes directly or attempts to get the requested branch.
+   */
+  private handleAvailableSource(source: CoValueCore): void {
+    if (!this.branchName) {
+      this.subscribe(source.getCurrentContent());
+      return;
+    }
+
+    // Try to get the specific branch from the available source
+    const branch = source.getBranch(this.branchName, this.branchOwnerId);
+
+    if (branch.isAvailable()) {
+      // Branch is available, subscribe to it
+      this.subscribe(branch.getCurrentContent());
+      return;
     } else {
-      this.node
-        .loadCoValueCore(this.id as any, undefined, skipRetry)
-        .then((value) => {
-          if (this.unsubscribed) return;
-
-          if (value.isAvailable()) {
-            this.subscribe(value.getCurrentContent());
-          } else {
-            this.subscribeToState();
-            this.listener("unavailable");
-          }
-        })
-        .catch((error) => {
-          console.error("Unexpected error loading CoValue: ", error);
-          this.listener("unavailable");
-        });
+      // 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 !== "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);
+        this.emit("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");
     }
+
+    // Source isn't available either, subscribe to state changes and report unavailability
+    this.subscribeToUnavailableSource();
+    this.emit("unavailable");
   }
 
-  subscribeToState() {
-    const entry = this.node.getCoValue(this.id as any);
+  /**
+   * Loads the CoValue core from the network/storage.
+   * This is the fallback strategy when immediate availability fails.
+   */
+  private loadCoValue(): void {
+    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();
+          this.emit("unavailable");
+        }
+      })
+      .catch((error) => {
+        // Handle unexpected errors during loading
+        console.error(error);
+        this.emit("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.
+   */
+  private subscribeToUnavailableSource(): void {
+    const source = this.source;
+
     const handleStateChange = (
-      core: CoValueCore,
+      _: CoValueCore,
       unsubFromStateChange: () => void,
     ) => {
-      if (this.unsubscribed) {
-        unsubFromStateChange();
+      // We are waiting for the source to become available, it's ok to wait indefinitiely
+      // until either this becomes available or we unsubscribe, because we have already
+      // emitted an "unavailable" event.
+      if (!source.isAvailable()) {
         return;
       }
 
-      if (core.isAvailable()) {
-        this.subscribe(core.getCurrentContent());
-        unsubFromStateChange();
+      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());
       }
     };
 
-    const unsubFromStateChange = entry.subscribe(handleStateChange);
-
-    this._unsubscribe = () => {
-      unsubFromStateChange();
-    };
+    // Subscribe to state changes and store the unsubscribe function
+    this._unsubscribe = source.subscribe(handleStateChange);
   }
 
-  subscribe(value: RawCoValue) {
+  /**
+   * 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 {
     if (this.unsubscribed) return;
 
+    // Subscribe to the value and store the unsubscribe function
     this._unsubscribe = value.subscribe((value) => {
-      this.listener(value);
+      this.emit(value);
     });
+  }
+
+  emit(value: RawCoValue | "unavailable"): void {
+    if (this.unsubscribed) return;
 
     this.listener(value);
   }
 
-  unsubscribe() {
+  /**
+   * Unsubscribes from all active subscriptions and marks the instance as unsubscribed.
+   * This prevents any further operations and ensures proper cleanup.
+   */
+  unsubscribe(): void {
     if (this.unsubscribed) return;
     this.unsubscribed = true;
     this._unsubscribe();

package/src/tools/tests/account.test.ts

@@ -393,3 +393,15 @@ describe("account.$jazz.has", () => {
     expect(account.root.settings).toBe("default");
   });
 });
+
+describe("account.toJSON", () => {
+  test("returns only the acccount's Jazz id", async () => {
+    const account = await createJazzTestAccount({
+      creationProps: { name: "John" },
+    });
+
+    expect(account.toJSON()).toEqual({
+      $jazz: { id: account.$jazz.id },
+    });
+  });
+});

package/src/tools/tests/coFeed.test.ts

@@ -105,6 +105,15 @@ describe("Simple CoFeed operations", async () => {
     expect(stream.perSession[me.$jazz.sessionID]?.value).toEqual("milk");
   });
 
+  test("toJSON", () => {
+    expect(stream.toJSON()).toEqual({
+      $jazz: { id: stream.$jazz.id },
+      in: {
+        [me.$jazz.sessionID]: stream.perSession[me.$jazz.sessionID]?.value,
+      },
+    });
+  });
+
   describe("Mutation", () => {
     test("push element into CoFeed of non-collaborative values", () => {
       stream.$jazz.push("bread");
@@ -304,6 +313,22 @@ describe("Simple FileStream operations", async () => {
       expect(stream.getChunks()).toBe(undefined);
     });
 
+    test("toJSON", () => {
+      stream.start({ mimeType: "text/plain" });
+      stream.push(new Uint8Array([1, 2, 3]));
+      stream.push(new Uint8Array([4, 5, 6]));
+      stream.end();
+
+      expect(stream.toJSON()).toEqual({
+        $jazz: { id: stream.$jazz.id },
+        mimeType: "text/plain",
+        chunks: [new Uint8Array([1, 2, 3]), new Uint8Array([4, 5, 6])],
+        filename: undefined,
+        finished: true,
+        totalSizeBytes: undefined,
+      });
+    });
+
     test("Mutation", () => {
       stream.start({ mimeType: "text/plain" });
       stream.push(new Uint8Array([1, 2, 3]));

package/src/tools/tests/coList.test.ts

@@ -243,6 +243,26 @@ describe("Simple CoList operations", async () => {
         list.$jazz.push("cheese");
         expect(list[3]?.toString()).toBe("cheese");
       });
+
+      test("cannot push a shallowly-loaded CoValue into a deeply-loaded CoList", async () => {
+        const Task = co.map({ title: co.plainText() });
+        const TaskList = co.list(Task);
+
+        const task = Task.create({ title: "Do the dishes" });
+        const taskList = TaskList.create([]);
+
+        const loadedTask = await Task.load(task.$jazz.id);
+        const loadedTaskList = await TaskList.load(taskList.$jazz.id, {
+          resolve: { $each: { title: true } },
+        });
+
+        assert(loadedTask);
+        assert(loadedTaskList);
+        // @ts-expect-error loadedTask may not have its `title` loaded
+        loadedTaskList.$jazz.push(loadedTask);
+        // In this case the title is loaded, so the assertion passes
+        expect(loadedTaskList.at(-1)?.title.toString()).toBe("Do the dishes");
+      });
     });
 
     describe("unshift", () => {

package/src/tools/tests/coMap.record.test.ts

@@ -140,6 +140,7 @@ describe("CoMap.Record", async () => {
       expect("age" in person).toEqual(false);
 
       expect(person.toJSON()).toEqual({
+        $jazz: { id: person.$jazz.id },
         name: "John",
       });
     });

package/src/tools/tests/coMap.test.ts

@@ -281,14 +281,16 @@ describe("CoMap", async () => {
       expect(person.friend?.age).toEqual(21);
     });
 
-    test("JSON.stringify should not include internal properties", () => {
+    test("JSON.stringify should include user-defined properties + $jazz.id", () => {
       const Person = co.map({
         name: z.string(),
       });
 
       const person = Person.create({ name: "John" });
 
-      expect(JSON.stringify(person)).toEqual('{"name":"John"}');
+      expect(JSON.stringify(person)).toEqual(
+        `{"$jazz":{"id":"${person.$jazz.id}"},"name":"John"}`,
+      );
     });
 
     test("toJSON should not fail when there is a key in the raw value not represented in the schema", () => {
@@ -302,6 +304,7 @@ describe("CoMap", async () => {
       person.$jazz.raw.set("extra", "extra");
 
       expect(person.toJSON()).toEqual({
+        $jazz: { id: person.$jazz.id },
         name: "John",
         age: 20,
       });
@@ -323,9 +326,11 @@ describe("CoMap", async () => {
       });
 
       expect(person.toJSON()).toEqual({
+        $jazz: { id: person.$jazz.id },
         name: "John",
         age: 20,
         friend: {
+          $jazz: { id: person.friend?.$jazz.id },
           name: "Jane",
           age: 21,
         },
@@ -349,6 +354,7 @@ describe("CoMap", async () => {
       person.$jazz.set("friend", person);
 
       expect(person.toJSON()).toEqual({
+        $jazz: { id: person.$jazz.id },
         name: "John",
         age: 20,
         friend: {
@@ -373,6 +379,7 @@ describe("CoMap", async () => {
       });
 
       expect(john.toJSON()).toMatchObject({
+        $jazz: { id: john.$jazz.id },
         name: "John",
         age: 20,
         birthday: birthday.toISOString(),
@@ -407,6 +414,7 @@ describe("CoMap", async () => {
       const john = Person.create({ name: "John", age: 30, x: 1 });
 
       expect(john.toJSON()).toEqual({
+        $jazz: { id: john.$jazz.id },
         name: "John",
         age: 30,
       });
@@ -510,6 +518,7 @@ describe("CoMap", async () => {
       expect(john.age).toEqual(undefined);
 
       expect(john.toJSON()).toEqual({
+        $jazz: { id: john.$jazz.id },
         name: "John",
       });
       // The CoMap proxy hides the age property from the `in` operator
@@ -541,6 +550,7 @@ describe("CoMap", async () => {
       expect(john.age).not.toBeDefined();
       expect(john.pet).not.toBeDefined();
       expect(john.toJSON()).toEqual({
+        $jazz: { id: john.$jazz.id },
         name: "John",
       });
       expect("age" in john).toEqual(false);

package/tsup.config.ts

@@ -32,6 +32,7 @@ export default defineConfig([
       index: "src/media/index.ts",
       "index.browser": "src/media/index.browser.ts",
       "index.native": "src/media/index.native.ts",
+      "index.server": "src/media/index.server.ts",
     },
     outDir: "dist/media",
   },