Refactor forest's applyDelta to return a visitor (#17163)

api-report/tree2.api.md

@@ -71,7 +71,7 @@ export type AnchorsCompare = CompareFunction<UpPath>;
 
 // @alpha @sealed
 export class AnchorSet implements ISubscribable<AnchorSetRootEvents>, AnchorLocator {
-    applyDelta(delta: Delta.Root): void;
+    acquireVisitor(): DeltaVisitor;
     // (undocumented)
     forget(anchor: Anchor): void;
     internalizePath(originalPath: UpPath): UpPath;
@@ -428,6 +428,28 @@ declare namespace Delta {
 }
 export { Delta }
 
+// @alpha
+export interface DeltaVisitor {
+    // (undocumented)
+    enterField(key: FieldKey): void;
+    // (undocumented)
+    enterNode(index: number): void;
+    // (undocumented)
+    exitField(key: FieldKey): void;
+    // (undocumented)
+    exitNode(index: number): void;
+    // (undocumented)
+    free(): void;
+    // (undocumented)
+    onDelete(index: number, count: number): void;
+    // (undocumented)
+    onInsert(index: number, content: Delta.ProtoNodes): void;
+    // (undocumented)
+    onMoveIn(index: number, count: number, id: Delta.MoveId): void;
+    // (undocumented)
+    onMoveOut(index: number, count: number, id: Delta.MoveId): void;
+}
+
 // @alpha
 export interface Dependee extends NamedComputation {
     registerDependent(dependent: Dependent): boolean;
@@ -747,8 +769,8 @@ export const forbiddenFieldKindIdentifier = "Forbidden";
 
 // @alpha
 export interface ForestEvents {
-    afterDelta(delta: Delta.Root): void;
-    beforeDelta(delta: Delta.Root): void;
+    afterChange(): void;
+    beforeChange(): void;
 }
 
 // @alpha
@@ -849,8 +871,9 @@ export interface IdRange {
 
 // @alpha
 export interface IEditableForest extends IForestSubscription {
+    // (undocumented)
+    acquireVisitor(): DeltaVisitor;
     readonly anchors: AnchorSet;
-    applyDelta(delta: Delta.Root): void;
 }
 
 // @alpha

experimental/dds/tree2/src/core/forest/editableForest.ts

@@ -12,6 +12,8 @@ import {
 	Anchor,
 	ITreeCursorSynchronous,
 	rootFieldKey,
+	DeltaVisitor,
+	applyDelta,
 } from "../tree";
 import { IForestSubscription, ITreeSubscriptionCursor } from "./forest";
 
@@ -31,10 +33,13 @@ export interface IEditableForest extends IForestSubscription {
 	readonly anchors: AnchorSet;
 
 	/**
-	 * Applies the supplied Delta to the forest.
-	 * Does NOT update anchors.
+	 * @returns a visitor that can be used to mutate the forest.
+	 *
+	 * Mutating the forest does NOT update anchors.
+	 * The visitor must be released after use.
+	 * It is invalid to acquire a visitor without releasing the previous one.
 	 */
-	applyDelta(delta: Delta.Root): void;
+	acquireVisitor(): DeltaVisitor;
 }
 
 /**
@@ -50,7 +55,7 @@ export function initializeForest(
 ): void {
 	assert(forest.isEmpty, 0x747 /* forest must be empty */);
 	const insert: Delta.Insert = { type: Delta.MarkType.Insert, content };
-	forest.applyDelta(new Map([[rootFieldKey, [insert]]]));
+	applyDelta(new Map([[rootFieldKey, [insert]]]), forest);
 }
 
 // TODO: Types below here may be useful for input into edit building APIs, but are no longer used here directly.

experimental/dds/tree2/src/core/forest/forest.ts

@@ -10,7 +10,6 @@ import { StoredSchemaRepository, FieldKey } from "../schema-stored";
 import {
 	Anchor,
 	AnchorSet,
-	Delta,
 	DetachedField,
 	detachedFieldAsKey,
 	ITreeCursor,
@@ -35,14 +34,16 @@ import type { IEditableForest } from "./editableForest";
  */
 export interface ForestEvents {
 	/**
-	 * Delta is about to be applied to forest.
+	 * The forest is about to be changed.
+	 * Emitted before the first change in a batch of changes.
 	 */
-	beforeDelta(delta: Delta.Root): void;
+	beforeChange(): void;
 
 	/**
-	 * Delta was just applied to forest.
+	 * The forest was just changed.
+	 * Emitted after the last change in a batch of changes.
 	 */
-	afterDelta(delta: Delta.Root): void;
+	afterChange(): void;
 }
 
 /**

experimental/dds/tree2/src/core/index.ts

@@ -55,6 +55,7 @@ export {
 	detachedFieldAsKey,
 	keyAsDetachedField,
 	visitDelta,
+	applyDelta,
 	setGenericTreeField,
 	DeltaVisitor,
 	PathVisitor,