Add Clone to SharedTree Revertible

packages/dds/tree/src/core/index.ts

@@ -206,4 +206,9 @@ export {
 	AllowedUpdateType,
 } from "./schema-view/index.js";
 
-export { type Revertible, RevertibleStatus, type RevertibleFactory } from "./revertible.js";
+export {
+	type Revertible,
+	RevertibleStatus,
+	type RevertibleFactory,
+	type RevertibleAlphaFactory,
+} from "./revertible.js";

packages/dds/tree/src/core/revertible.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import type { TreeBranch } from "../simple-tree/index.js";
+
 /**
  * Allows reversion of a change made to SharedTree.
  *
@@ -36,6 +38,13 @@ export interface Revertible {
 	dispose(): void;
 }
 
+/**
+ * @alpha
+ */
+export interface RevertibleAlpha extends Revertible {
+	clone: (forkedBranch?: TreeBranch) => RevertibleAlpha;
+}
+
 /**
  * The status of a {@link Revertible}.
  *
@@ -62,3 +71,17 @@ export enum RevertibleStatus {
 export type RevertibleFactory = (
 	onRevertibleDisposed?: (revertible: Revertible) => void,
 ) => Revertible;
+
+/**
+ * Will error if invoked outside the scope of the `commitApplied` event that provides it, or if invoked multiple times.
+ *
+ * @param onRevertibleDisposed - A callback that will be invoked when the `Revertible` generated by this factory is disposed.
+ * This happens when the `Revertible` is disposed manually, or when the `TreeView` that the `Revertible` belongs to is disposed,
+ * whichever happens first.
+ * This is typically used to clean up any resources associated with the `Revertible` in the host application.
+ *
+ * @sealed @public
+ */
+export type RevertibleAlphaFactory = (
+	onRevertibleDisposed?: (revertible: RevertibleAlpha) => void,
+) => RevertibleAlpha;

packages/dds/tree/src/shared-tree/schematizingTreeView.ts

@@ -409,7 +409,7 @@ export class SchematizingSimpleTreeView<
  * @remarks Currently, all contexts are also {@link SchematizingSimpleTreeView}s.
  * Other checkout implementations (e.g. not associated with a view) may be supported in the future.
  */
-function getCheckout(context: TreeBranch): TreeCheckout {
+export function getCheckout(context: TreeBranch): TreeCheckout {
 	if (context instanceof SchematizingSimpleTreeView) {
 		return context.checkout;
 	}

packages/dds/tree/src/shared-tree/treeCheckout.ts

@@ -38,6 +38,7 @@ import {
 	tagChange,
 	visitDelta,
 	type RevertibleFactory,
+	type RevertibleAlphaFactory,
 } from "../core/index.js";
 import {
 	type HasListeners,
@@ -68,8 +69,11 @@ import type {
 	TreeViewConfiguration,
 	UnsafeUnknownSchema,
 	ViewableTree,
+	TreeBranch,
 } from "../simple-tree/index.js";
-import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+import { getCheckout, SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+// eslint-disable-next-line import/no-internal-modules
+import type { RevertibleAlpha } from "../core/revertible.js";
 
 /**
  * Events for {@link ITreeCheckout}.
@@ -92,7 +96,10 @@ export interface CheckoutEvents {
 	 * @param getRevertible - a function provided that allows users to get a revertible for the change. If not provided,
 	 * this change is not revertible.
 	 */
-	changed(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+	changed(
+		data: CommitMetadata,
+		getRevertible?: RevertibleFactory | RevertibleAlphaFactory,
+	): void;
 }
 
 /**
@@ -397,7 +404,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	/**
 	 * Set of revertibles maintained for automatic disposal
 	 */
-	private readonly revertibles = new Set<DisposableRevertible>();
+	private readonly revertibles = new Set<RevertibleAlpha>();
 
 	/**
 	 * Each branch's head commit corresponds to a revertible commit.
@@ -536,42 +543,12 @@ export class TreeCheckout implements ITreeCheckoutFork {
 											"Cannot generate the same revertible more than once. Note that this can happen when multiple changed event listeners are registered.",
 										);
 									}
-									const revertibleCommits = this.revertibleCommitBranches;
-									const revertible: DisposableRevertible = {
-										get status(): RevertibleStatus {
-											const revertibleCommit = revertibleCommits.get(revision);
-											return revertibleCommit === undefined
-												? RevertibleStatus.Disposed
-												: RevertibleStatus.Valid;
-										},
-										revert: (release: boolean = true) => {
-											if (revertible.status === RevertibleStatus.Disposed) {
-												throw new UsageError(
-													"Unable to revert a revertible that has been disposed.",
-												);
-											}
-
-											const revertMetrics = this.revertRevertible(revision, kind);
-											this.logger?.sendTelemetryEvent({
-												eventName: TreeCheckout.revertTelemetryEventName,
-												...revertMetrics,
-											});
-
-											if (release) {
-												revertible.dispose();
-											}
-										},
-										dispose: () => {
-											if (revertible.status === RevertibleStatus.Disposed) {
-												throw new UsageError(
-													"Unable to dispose a revertible that has already been disposed.",
-												);
-											}
-											this.disposeRevertible(revertible, revision);
-											onRevertibleDisposed?.(revertible);
-										},
-									};
-
+									const revertible = this.createRevertible(
+										revision,
+										kind,
+										this,
+										onRevertibleDisposed,
+									);
 									this.revertibleCommitBranches.set(revision, _branch.fork(commit));
 									this.revertibles.add(revertible);
 									return revertible;
@@ -626,6 +603,70 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		}
 	}
 
+	private createRevertible(
+		revision: RevisionTag,
+		kind: CommitKind,
+		checkout: TreeCheckout = this,
+		onRevertibleDisposed?: (revertible: Revertible) => void,
+	): RevertibleAlpha {
+		const commitBranches = checkout.revertibleCommitBranches;
+
+		const revertible: RevertibleAlpha = {
+			get status(): RevertibleStatus {
+				const revertibleCommit = commitBranches.get(revision);
+				return revertibleCommit === undefined
+					? RevertibleStatus.Disposed
+					: RevertibleStatus.Valid;
+			},
+			revert: (release: boolean = true) => {
+				if (revertible.status === RevertibleStatus.Disposed) {
+					throw new UsageError("Unable to revert a revertible that has been disposed.");
+				}
+
+				const revertMetrics = checkout.revertRevertible(revision, kind);
+				checkout.logger?.sendTelemetryEvent({
+					eventName: TreeCheckout.revertTelemetryEventName,
+					...revertMetrics,
+				});
+
+				if (release) {
+					revertible.dispose();
+				}
+			},
+			clone: (forkedBranch?: TreeBranch) => {
+				return checkout.cloneRevertible(revision, kind, forkedBranch);
+			},
+			dispose: () => {
+				if (revertible.status === RevertibleStatus.Disposed) {
+					throw new UsageError(
+						"Unable to dispose a revertible that has already been disposed.",
+					);
+				}
+				checkout.disposeRevertible(revertible, revision);
+				onRevertibleDisposed?.(revertible);
+			},
+		};
+
+		return revertible;
+	}
+
+	private cloneRevertible(
+		revision: RevisionTag,
+		kind: CommitKind,
+		branch?: TreeBranch,
+		onRevertibleDisposed?: (revertible: Revertible) => void,
+	): RevertibleAlpha {
+		const checkout = branch ? getCheckout(branch) : this;
+
+		if (branch !== undefined) {
+			const revertibleBranch = this.revertibleCommitBranches.get(revision);
+			assert(revertibleBranch !== undefined, "SharedTreeBranch for revertible not found.");
+			checkout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
+		}
+
+		return this.createRevertible(revision, kind, checkout, onRevertibleDisposed);
+	}
+
 	// For the new TreeViewAlpha API
 	public viewWith<TRoot extends ImplicitFieldSchema | UnsafeUnknownSchema>(
 		config: TreeViewConfiguration<ReadSchema<TRoot>>,
@@ -792,7 +833,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		}
 	}
 
-	private disposeRevertible(revertible: DisposableRevertible, revision: RevisionTag): void {
+	private disposeRevertible(revertible: RevertibleAlpha, revision: RevisionTag): void {
 		this.revertibleCommitBranches.get(revision)?.dispose();
 		this.revertibleCommitBranches.delete(revision);
 		this.revertibles.delete(revertible);
@@ -890,7 +931,3 @@ export function runSynchronous(
 		? view.transaction.abort()
 		: view.transaction.commit();
 }
-
-interface DisposableRevertible extends Revertible {
-	dispose: () => void;
-}