jazz-tools 0.18.11 → 0.18.13

package/src/react-core/hooks.ts

@@ -13,6 +13,7 @@ import {
   AnyAccountSchema,
   CoValue,
   CoValueClassOrSchema,
+  Group,
   InboxSender,
   InstanceOfSchema,
   JazzContextManager,
@@ -22,10 +23,10 @@ import {
   ResolveQueryStrict,
   SubscriptionScope,
   coValueClassFromCoValueClassOrSchema,
+  type BranchDefinition,
 } from "jazz-tools";
 import { JazzContext, JazzContextManagerContext } from "./provider.js";
 import { getCurrentAccountFromContextManager } from "./utils.js";
-import { TypeSym } from "../tools/internal.js";
 
 export function useJazzContext<Acc extends Account>() {
   const value = useContext(JazzContext) as JazzContextType<Acc>;
@@ -89,6 +90,7 @@ function useCoValueSubscription<
   id: string | undefined | null,
   options?: {
     resolve?: ResolveQueryStrict<S, R>;
+    unstable_branch?: BranchDefinition;
   },
 ) {
   const contextManager = useJazzContextManager();
@@ -103,6 +105,15 @@ function useCoValueSubscription<
       };
     }
 
+    if (options?.unstable_branch?.owner === null) {
+      return {
+        subscription: null,
+        contextManager,
+        id,
+        Schema,
+      };
+    }
+
     const node = contextManager.getCurrentValue()!.node;
     const subscription = new SubscriptionScope<any>(
       node,
@@ -112,6 +123,9 @@ function useCoValueSubscription<
         ref: coValueClassFromCoValueClassOrSchema(Schema),
         optional: true,
       },
+      false,
+      false,
+      options?.unstable_branch,
     );
 
     return {
@@ -119,16 +133,23 @@ function useCoValueSubscription<
       contextManager,
       id,
       Schema,
+      branchName: options?.unstable_branch?.name,
+      branchOwnerId: options?.unstable_branch?.owner?.$jazz.id,
     };
   };
 
   const [subscription, setSubscription] = React.useState(createSubscription);
 
+  const branchName = options?.unstable_branch?.name;
+  const branchOwnerId = options?.unstable_branch?.owner?.$jazz.id;
+
   React.useLayoutEffect(() => {
     if (
       subscription.contextManager !== contextManager ||
       subscription.id !== id ||
-      subscription.Schema !== Schema
+      subscription.Schema !== Schema ||
+      subscription.branchName !== branchName ||
+      subscription.branchOwnerId !== branchOwnerId
     ) {
       subscription.subscription?.destroy();
       setSubscription(createSubscription());
@@ -138,7 +159,7 @@ function useCoValueSubscription<
       subscription.subscription?.destroy();
       setSubscription(createSubscription());
     });
-  }, [Schema, id, contextManager]);
+  }, [Schema, id, contextManager, branchName, branchOwnerId]);
 
   return subscription.subscription;
 }
@@ -240,6 +261,22 @@ export function useCoState<
   options?: {
     /** Resolve query to specify which nested CoValues to load */
     resolve?: ResolveQueryStrict<S, R>;
+    /**
+     * Create or load a branch for isolated editing.
+     *
+     * Branching lets you take a snapshot of the current state and start modifying it without affecting the canonical/shared version.
+     * It's a fork of your data graph: the same schema, but with diverging values.
+     *
+     * The checkout of the branch is applied on all the resolved values.
+     *
+     * @param name - A unique name for the branch. This identifies the branch
+     *   and can be used to switch between different branches of the same CoValue.
+     * @param owner - The owner of the branch. Determines who can access and modify
+     *   the branch. If not provided, the branch is owned by the current user.
+     *
+     * For more info see the [branching](https://jazz.tools/docs/react/using-covalues/version-control) documentation.
+     */
+    unstable_branch?: BranchDefinition;
   },
 ): Loaded<S, R> | undefined | null {
   const subscription = useCoValueSubscription(Schema, id, options);
@@ -398,6 +435,22 @@ export function useCoStateWithSelector<
     select: (value: Loaded<S, R> | undefined | null) => TSelectorReturn;
     /** Equality function to determine if the selected value has changed, defaults to `Object.is` */
     equalityFn?: (a: TSelectorReturn, b: TSelectorReturn) => boolean;
+    /**
+     * Create or load a branch for isolated editing.
+     *
+     * Branching lets you take a snapshot of the current state and start modifying it without affecting the canonical/shared version.
+     * It's a fork of your data graph: the same schema, but with diverging values.
+     *
+     * The checkout of the branch is applied on all the resolved values.
+     *
+     * @param name - A unique name for the branch. This identifies the branch
+     *   and can be used to switch between different branches of the same CoValue.
+     * @param owner - The owner of the branch. Determines who can access and modify
+     *   the branch. If not provided, the branch is owned by the current user.
+     *
+     * For more info see the [branching](https://jazz.tools/docs/react/using-covalues/version-control) documentation.
+     */
+    unstable_branch?: BranchDefinition;
   },
 ): TSelectorReturn {
   const subscription = useCoValueSubscription(Schema, id, options);
@@ -430,6 +483,7 @@ function useAccountSubscription<
   Schema: S,
   options?: {
     resolve?: ResolveQueryStrict<S, R>;
+    unstable_branch?: BranchDefinition;
   },
 ) {
   const contextManager = useJazzContextManager();
@@ -437,7 +491,7 @@ function useAccountSubscription<
   const createSubscription = () => {
     const agent = getCurrentAccountFromContextManager(contextManager);
 
-    if (agent[TypeSym] === "Anonymous") {
+    if (agent.$type$ === "Anonymous") {
       return {
         subscription: null,
         contextManager,
@@ -457,21 +511,31 @@ function useAccountSubscription<
         ref: coValueClassFromCoValueClassOrSchema(Schema),
         optional: true,
       },
+      false,
+      false,
+      options?.unstable_branch,
     );
 
     return {
       subscription,
       contextManager,
       Schema,
+      branchName: options?.unstable_branch?.name,
+      branchOwnerId: options?.unstable_branch?.owner?.$jazz.id,
     };
   };
 
   const [subscription, setSubscription] = React.useState(createSubscription);
 
+  const branchName = options?.unstable_branch?.name;
+  const branchOwnerId = options?.unstable_branch?.owner?.$jazz.id;
+
   React.useLayoutEffect(() => {
     if (
       subscription.contextManager !== contextManager ||
-      subscription.Schema !== Schema
+      subscription.Schema !== Schema ||
+      subscription.branchName !== options?.unstable_branch?.name ||
+      subscription.branchOwnerId !== options?.unstable_branch?.owner?.$jazz.id
     ) {
       subscription.subscription?.destroy();
       setSubscription(createSubscription());
@@ -481,7 +545,7 @@ function useAccountSubscription<
       subscription.subscription?.destroy();
       setSubscription(createSubscription());
     });
-  }, [Schema, contextManager]);
+  }, [Schema, contextManager, branchName, branchOwnerId]);
 
   return subscription.subscription;
 }
@@ -547,6 +611,22 @@ export function useAccount<
   options?: {
     /** Resolve query to specify which nested CoValues to load from the account */
     resolve?: ResolveQueryStrict<A, R>;
+    /**
+     * Create or load a branch for isolated editing.
+     *
+     * Branching lets you take a snapshot of the current state and start modifying it without affecting the canonical/shared version.
+     * It's a fork of your data graph: the same schema, but with diverging values.
+     *
+     * The checkout of the branch is applied on all the resolved values.
+     *
+     * @param name - A unique name for the branch. This identifies the branch
+     *   and can be used to switch between different branches of the same CoValue.
+     * @param owner - The owner of the branch. Determines who can access and modify
+     *   the branch. If not provided, the branch is owned by the current user.
+     *
+     * For more info see the [branching](https://jazz.tools/docs/react/using-covalues/version-control) documentation.
+     */
+    unstable_branch?: BranchDefinition;
   },
 ): {
   me: Loaded<A, R> | undefined | null;

package/src/react-core/tests/useAccount.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 
-import { RefsToResolve, co, z } from "jazz-tools";
-import { beforeEach, describe, expect, it } from "vitest";
+import { Group, RefsToResolve, co, z } from "jazz-tools";
+import { assert, beforeEach, describe, expect, it } from "vitest";
 import { useAccount, useJazzContextManager } from "../hooks.js";
 import { useIsAuthenticated } from "../index.js";
 import {
@@ -219,4 +219,96 @@ describe("useAccount", () => {
     expect(result.current.me).toBe(null);
     expect(result.current.agent).toBe(account.guest);
   });
+
+  it("should work with branches - create branch, edit and merge", async () => {
+    const AccountRoot = co.map({
+      name: z.string(),
+      age: z.number(),
+      email: z.string(),
+    });
+
+    const AccountSchema = co
+      .account({
+        root: AccountRoot,
+        profile: co.profile(),
+      })
+      .withMigration((account, creationProps) => {
+        if (!account.$jazz.refs.root) {
+          account.$jazz.set("root", {
+            name: "John Doe",
+            age: 30,
+            email: "john@example.com",
+          });
+        }
+      });
+
+    const account = await createJazzTestAccount({
+      AccountSchema,
+      isCurrentActiveAccount: true,
+    });
+
+    const group = Group.create();
+    group.addMember("everyone", "writer");
+    // Use useAccount with the branch
+    const { result } = renderHook(
+      () => {
+        const branchAccount = useAccount(AccountSchema, {
+          resolve: {
+            root: true,
+          },
+          unstable_branch: { name: "feature-branch" },
+        });
+
+        const mainAccount = useAccount(AccountSchema, {
+          resolve: {
+            root: true,
+          },
+        });
+
+        return { branchAccount, mainAccount };
+      },
+      {
+        account,
+      },
+    );
+
+    await act(async () => {
+      // Wait for the account to be loaded
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    });
+
+    expect(result.current).not.toBeNull();
+
+    const branchAccount = result.current.branchAccount;
+    const mainAccount = result.current.mainAccount;
+
+    assert(branchAccount?.me);
+    assert(mainAccount?.me);
+
+    act(() => {
+      branchAccount.me?.root.$jazz.applyDiff({
+        name: "John Smith",
+        age: 31,
+        email: "john.smith@example.com",
+      });
+    });
+
+    // Verify the branch has the changes
+    expect(branchAccount.me.root?.name).toBe("John Smith");
+    expect(branchAccount.me.root?.age).toBe(31);
+    expect(branchAccount.me.root?.email).toBe("john.smith@example.com");
+
+    // Verify the original is unchanged
+    expect(mainAccount.me.root?.name).toBe("John Doe");
+    expect(mainAccount.me.root?.age).toBe(30);
+    expect(mainAccount.me.root?.email).toBe("john@example.com");
+
+    // Merge the branch back
+    branchAccount.me.root.$jazz.unstable_merge();
+
+    // Verify the original now has the merged changes
+    expect(mainAccount.me.root?.name).toBe("John Smith");
+    expect(mainAccount.me.root?.age).toBe(31);
+    expect(mainAccount.me.root?.email).toBe("john.smith@example.com");
+  });
 });

package/src/react-core/tests/useCoState.test.ts

@@ -559,4 +559,78 @@ describe("useCoState", () => {
 
     expect(renderings).toEqual([true]);
   });
+
+  it("should work with branches - create branch, edit and merge", async () => {
+    const Person = co.map({
+      name: z.string(),
+      age: z.number(),
+      email: z.string(),
+    });
+
+    const group = Group.create();
+    group.addMember("everyone", "writer");
+
+    const originalPerson = Person.create(
+      {
+        name: "John Doe",
+        age: 30,
+        email: "john@example.com",
+      },
+      group,
+    );
+
+    const account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    // Use useCoState with the branch
+    const { result } = renderHook(
+      () => {
+        const branch = useCoState(Person, originalPerson.$jazz.id, {
+          unstable_branch: { name: "feature-branch" },
+        });
+
+        const main = useCoState(Person, originalPerson.$jazz.id);
+
+        return { branch, main };
+      },
+      {
+        account,
+      },
+    );
+
+    await waitFor(() => {
+      expect(result.current).not.toBeNull();
+    });
+
+    const branchPerson = result.current.branch;
+
+    assert(branchPerson);
+
+    act(() => {
+      branchPerson.$jazz.applyDiff({
+        name: "John Smith",
+        age: 31,
+        email: "john.smith@example.com",
+      });
+    });
+
+    // Verify the branch has the changes
+    expect(result.current?.branch?.name).toBe("John Smith");
+    expect(result.current?.branch?.age).toBe(31);
+    expect(result.current?.branch?.email).toBe("john.smith@example.com");
+
+    // Verify the original is unchanged
+    expect(result.current?.main?.name).toBe("John Doe");
+    expect(result.current?.main?.age).toBe(30);
+    expect(result.current?.main?.email).toBe("john@example.com");
+
+    // Merge the branch back
+    await branchPerson.$jazz.unstable_merge();
+
+    // Verify the original now has the merged changes
+    expect(result.current?.main?.name).toBe("John Smith");
+    expect(result.current?.main?.age).toBe(31);
+    expect(result.current?.main?.email).toBe("john.smith@example.com");
+  });
 });

package/src/react-native-core/index.ts

@@ -7,3 +7,7 @@ export * from "./media/image.js";
 export { SQLiteDatabaseDriverAsync } from "cojson";
 export { parseInviteLink } from "jazz-tools";
 export { createInviteLink, setupKvStore } from "./platform.js";
+export {
+  ReactNativeContextManager,
+  type JazzContextManagerProps,
+} from "./ReactNativeContextManager.js";

package/src/svelte/jazz.class.svelte.ts

@@ -2,6 +2,7 @@ import type {
   Account,
   AccountClass,
   AnyAccountSchema,
+  BranchDefinition,
   CoValueClassOrSchema,
   CoValueFromRaw,
   InstanceOfSchema,
@@ -18,22 +19,46 @@ import { createSubscriber } from "svelte/reactivity";
 import { useIsAuthenticated } from "./auth/useIsAuthenticated.svelte.js";
 import { getJazzContext } from "./jazz.svelte";
 
+type CoStateOptions<V extends CoValueClassOrSchema, R extends ResolveQuery<V>> = { 
+  resolve?: ResolveQueryStrict<V, R>,
+  /**
+   * Create or load a branch for isolated editing.
+   *
+   * Branching lets you take a snapshot of the current state and start modifying it without affecting the canonical/shared version.
+   * It's a fork of your data graph: the same schema, but with diverging values.
+   *
+   * The checkout of the branch is applied on all the resolved values.
+   *
+   * @param name - A unique name for the branch. This identifies the branch
+   *   and can be used to switch between different branches of the same CoValue.
+   * @param owner - The owner of the branch. Determines who can access and modify
+   *   the branch. If not provided, the branch is owned by the current user.
+   *
+   * For more info see the [branching](https://jazz.tools/docs/svelte/using-covalues/version-control) documentation.
+  */
+  unstable_branch?: BranchDefinition
+};
+
+type CoStateId = string | undefined | null;
+
 export class CoState<
   V extends CoValueClassOrSchema,
   R extends ResolveQuery<V> = true,
 > {
   #value: Loaded<V, R> | undefined | null = undefined;
   #ctx = getJazzContext<InstanceOfSchema<AccountClass<Account>>>();
-  #id: string | undefined | null;
+  #id: CoStateId;
   #subscribe: () => void;
   #update = () => {};
+  #options: CoStateOptions<V, R> | undefined;
 
   constructor(
     Schema: V,
-    id: string | undefined | null | (() => string | undefined | null),
-    options?: { resolve?: ResolveQueryStrict<V, R> },
+    id: CoStateId | (() => CoStateId),
+    options?: CoStateOptions<V, R> | (() => CoStateOptions<V, R>),
   ) {
     this.#id = $derived.by(typeof id === "function" ? id : () => id);
+    this.#options = $derived.by(typeof options === "function" ? options : () => options);
 
     this.#subscribe = createSubscriber((update) => {
       this.#update = update;
@@ -42,6 +67,7 @@ export class CoState<
     $effect.pre(() => {
       const ctx = this.#ctx.current;
       const id = this.#id;
+      const options = this.#options;
 
       return untrack(() => {
         if (!ctx || !id) {
@@ -63,6 +89,7 @@ export class CoState<
               this.update(null);
             },
             syncResolution: true,
+            unstable_branch: options?.unstable_branch,
           },
           (value) => {
             this.update(value as Loaded<V, R>);
@@ -90,22 +117,26 @@ export class CoState<
 
 export class AccountCoState<
   A extends
-    | (AccountClass<Account> & CoValueFromRaw<Account>)
-    | AnyAccountSchema,
+  | (AccountClass<Account> & CoValueFromRaw<Account>)
+  | AnyAccountSchema,
   R extends ResolveQuery<A> = true,
 > {
   #value: Loaded<A, R> | undefined | null = undefined;
   #ctx = getJazzContext<InstanceOfSchema<A>>();
   #subscribe: () => void;
-  #update = () => {};
+  #options: CoStateOptions<A, R> | undefined;
+  #update = () => { };
+
+  constructor(Schema: A, options?: CoStateOptions<A, R> | (() => CoStateOptions<A, R>)) {
+    this.#options = $derived.by(typeof options === "function" ? options : () => options);
 
-  constructor(Schema: A, options?: { resolve?: ResolveQueryStrict<A, R> }) {
     this.#subscribe = createSubscriber((update) => {
       this.#update = update;
     });
 
     $effect.pre(() => {
       const ctx = this.#ctx.current;
+      const options = this.#options;
 
       return untrack(() => {
         if (!ctx || !("me" in ctx)) {
@@ -128,6 +159,7 @@ export class AccountCoState<
               this.update(null);
             },
             syncResolution: true,
+            unstable_branch: options?.unstable_branch,
           },
           (value) => {
             this.update(value as Loaded<A, R>);

package/src/tools/coValues/CoValueBase.ts

@@ -1,22 +1,17 @@
 import { ControlledAccount, LocalNode, type RawCoValue } from "cojson";
-import { CoreCoValueSchema } from "../implementation/zodSchema/schemaTypes/CoValueSchema.js";
 import {
   AnonymousJazzAgent,
   CoValue,
   CoValueClass,
-  CoValueFromRaw,
   ID,
   RegisteredSchemas,
+  type SubscriptionScope,
   coValueClassFromCoValueClassOrSchema,
   coValuesCache,
   inspect,
+  unstable_mergeBranch,
 } from "../internal.js";
-import {
-  CoValueClassOrSchema,
-  Group,
-  InstanceOfSchemaCoValuesNullable,
-  TypeSym,
-} from "../internal.js";
+import { Group, TypeSym } from "../internal.js";
 
 /** @internal */
 export abstract class CoValueBase implements CoValue {
@@ -46,6 +41,7 @@ export abstract class CoValueBase implements CoValue {
 export abstract class CoValueJazzApi<V extends CoValue> {
   /** @category Internals */
   declare _instanceID: string;
+  declare _subscriptionScope: SubscriptionScope<CoValue> | undefined;
 
   constructor(private coValue: V) {
     Object.defineProperty(this, "_instanceID", {
@@ -54,7 +50,16 @@ export abstract class CoValueJazzApi<V extends CoValue> {
     });
   }
 
-  abstract get id(): ID<V>;
+  get id(): string {
+    const sourceId = this.raw.core.getCurrentBranchSourceId();
+
+    if (sourceId) {
+      return sourceId;
+    }
+
+    return this.raw.id;
+  }
+
   abstract get raw(): RawCoValue;
   abstract get owner(): Group | undefined;
 
@@ -109,4 +114,34 @@ export abstract class CoValueJazzApi<V extends CoValue> {
 
     return value;
   }
+
+  /**
+   * The name of the active branch of the CoValue
+   */
+  get branchName(): string | undefined {
+    const subscriptionScope = this._subscriptionScope;
+
+    return subscriptionScope?.unstable_branch?.name;
+  }
+
+  get isBranched(): boolean {
+    const subscriptionScope = this._subscriptionScope;
+
+    return Boolean(subscriptionScope?.unstable_branch);
+  }
+
+  /**
+   * Deeply merge the current branch into the main CoValues.
+   *
+   * Doesn't have any effect when there are no changes to merge, or the current CoValue is not a branch
+   */
+  unstable_merge() {
+    const subscriptionScope = this._subscriptionScope;
+
+    if (!subscriptionScope) {
+      return;
+    }
+
+    unstable_mergeBranch(subscriptionScope);
+  }
 }

package/src/tools/coValues/account.ts

@@ -15,6 +15,7 @@ import {
 } from "cojson";
 import {
   AnonymousJazzAgent,
+  BranchDefinition,
   CoFieldInit,
   type CoMap,
   type CoValue,
@@ -376,14 +377,6 @@ class AccountJazzApi<A extends Account> extends CoValueJazzApi<A> {
     }
   }
 
-  /**
-   * The ID of this `Account`
-   * @category Content
-   */
-  get id(): ID<A> {
-    return this.raw.id;
-  }
-
   /**
    * Accounts have no owner. They can be accessed by everyone.
    */
@@ -487,6 +480,7 @@ class AccountJazzApi<A extends Account> extends CoValueJazzApi<A> {
     this: AccountJazzApi<A>,
     options: {
       resolve: RefsToResolveStrict<A, R>;
+      unstable_branch?: BranchDefinition;
     },
   ): Promise<Resolved<A, R>> {
     return ensureCoValueLoaded(this.account as unknown as A, options);
@@ -499,7 +493,10 @@ class AccountJazzApi<A extends Account> extends CoValueJazzApi<A> {
   ): () => void;
   subscribe<A extends Account, const R extends RefsToResolve<A>>(
     this: AccountJazzApi<A>,
-    options: { resolve?: RefsToResolveStrict<A, R> },
+    options: {
+      resolve?: RefsToResolveStrict<A, R>;
+      unstable_branch?: BranchDefinition;
+    },
     listener: (value: Resolved<A, R>, unsubscribe: () => void) => void,
   ): () => void;
   subscribe<A extends Account, const R extends RefsToResolve<A>>(