Forkable Revertible

packages/dds/tree/api-report/tree.alpha.api.md

@@ -26,6 +26,17 @@ type ApplyKind<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> =
     [FieldKind.Identifier]: DefaultsAreOptional extends true ? T | undefined : T;
 }[Kind];
 
+// @public
+export interface ClonableRevertible extends Revertible {
+    // (undocumented)
+    clone: (forkedBranch?: TreeBranch | TreeBranchFork) => ClonableRevertible;
+    // (undocumented)
+    dispose: () => void;
+}
+
+// @public @sealed
+export type ClonableRevertibleFactory = (onRevertibleDisposed?: (revertible: ClonableRevertible) => void) => ClonableRevertible;
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -782,7 +793,7 @@ export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = I
 
 // @public @sealed
 export interface TreeViewEvents {
-    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory | ClonableRevertibleFactory): void;
     rootChanged(): void;
     schemaChanged(): void;
 }

packages/dds/tree/api-report/tree.beta.api.md

@@ -17,6 +17,17 @@ type ApplyKind<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> =
     [FieldKind.Identifier]: DefaultsAreOptional extends true ? T | undefined : T;
 }[Kind];
 
+// @public
+export interface ClonableRevertible extends Revertible {
+    // (undocumented)
+    clone: (forkedBranch?: TreeBranch | TreeBranchFork) => ClonableRevertible;
+    // (undocumented)
+    dispose: () => void;
+}
+
+// @public @sealed
+export type ClonableRevertibleFactory = (onRevertibleDisposed?: (revertible: ClonableRevertible) => void) => ClonableRevertible;
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -575,7 +586,7 @@ export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = I
 
 // @public @sealed
 export interface TreeViewEvents {
-    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory | ClonableRevertibleFactory): void;
     rootChanged(): void;
     schemaChanged(): void;
 }

packages/dds/tree/api-report/tree.legacy.alpha.api.md

@@ -17,6 +17,17 @@ type ApplyKind<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> =
     [FieldKind.Identifier]: DefaultsAreOptional extends true ? T | undefined : T;
 }[Kind];
 
+// @public
+export interface ClonableRevertible extends Revertible {
+    // (undocumented)
+    clone: (forkedBranch?: TreeBranch | TreeBranchFork) => ClonableRevertible;
+    // (undocumented)
+    dispose: () => void;
+}
+
+// @public @sealed
+export type ClonableRevertibleFactory = (onRevertibleDisposed?: (revertible: ClonableRevertible) => void) => ClonableRevertible;
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -562,7 +573,7 @@ export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = I
 
 // @public @sealed
 export interface TreeViewEvents {
-    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory | ClonableRevertibleFactory): void;
     rootChanged(): void;
     schemaChanged(): void;
 }

packages/dds/tree/api-report/tree.legacy.public.api.md

@@ -17,6 +17,17 @@ type ApplyKind<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> =
     [FieldKind.Identifier]: DefaultsAreOptional extends true ? T | undefined : T;
 }[Kind];
 
+// @public
+export interface ClonableRevertible extends Revertible {
+    // (undocumented)
+    clone: (forkedBranch?: TreeBranch | TreeBranchFork) => ClonableRevertible;
+    // (undocumented)
+    dispose: () => void;
+}
+
+// @public @sealed
+export type ClonableRevertibleFactory = (onRevertibleDisposed?: (revertible: ClonableRevertible) => void) => ClonableRevertible;
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -559,7 +570,7 @@ export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = I
 
 // @public @sealed
 export interface TreeViewEvents {
-    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory | ClonableRevertibleFactory): void;
     rootChanged(): void;
     schemaChanged(): void;
 }

packages/dds/tree/api-report/tree.public.api.md

@@ -17,6 +17,17 @@ type ApplyKind<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> =
     [FieldKind.Identifier]: DefaultsAreOptional extends true ? T | undefined : T;
 }[Kind];
 
+// @public
+export interface ClonableRevertible extends Revertible {
+    // (undocumented)
+    clone: (forkedBranch?: TreeBranch | TreeBranchFork) => ClonableRevertible;
+    // (undocumented)
+    dispose: () => void;
+}
+
+// @public @sealed
+export type ClonableRevertibleFactory = (onRevertibleDisposed?: (revertible: ClonableRevertible) => void) => ClonableRevertible;
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -559,7 +570,7 @@ export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = I
 
 // @public @sealed
 export interface TreeViewEvents {
-    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory | ClonableRevertibleFactory): void;
     rootChanged(): void;
     schemaChanged(): void;
 }

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 ClonableRevertibleFactory,
+} from "./revertible.js";

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

@@ -3,6 +3,9 @@
  * Licensed under the MIT License.
  */
 
+// eslint-disable-next-line import/no-internal-modules
+import type { ClonableRevertible } from "../shared-tree/treeCheckout.js";
+
 /**
  * Allows reversion of a change made to SharedTree.
  *
@@ -62,3 +65,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 ClonableRevertibleFactory = (
+	onRevertibleDisposed?: (revertible: ClonableRevertible) => void,
+) => ClonableRevertible;

packages/dds/tree/src/index.ts

@@ -29,6 +29,7 @@ export {
 	MapNodeStoredSchema,
 	LeafNodeStoredSchema,
 	type RevertibleFactory,
+	type ClonableRevertibleFactory,
 } from "./core/index.js";
 export { type Brand } from "./util/index.js";
 
@@ -60,6 +61,7 @@ export {
 	getBranch,
 	type TreeBranch,
 	type TreeBranchFork,
+	type ClonableRevertible,
 } from "./shared-tree/index.js";
 
 export {

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

@@ -28,6 +28,7 @@ export {
 	type ITreeCheckoutFork,
 	type TreeBranch,
 	type TreeBranchFork,
+	type ClonableRevertible,
 } from "./treeCheckout.js";
 
 export { type TreeStoredContent } from "./schematizeTree.js";