@fluid-experimental/tree 0.58.2001 → 0.59.2000-61729

package/src/Forest.ts

@@ -4,28 +4,44 @@
  */
 
 import BTree from 'sorted-btree';
-import { fail, assert, comparePayloads, copyPropertyIfDefined } from './Common';
-import { NodeData, Payload } from './generic';
+import { fail, assert, copyPropertyIfDefined, compareBtrees, compareFiniteNumbers } from './Common';
 import { NodeId, TraitLabel } from './Identifiers';
-import { compareStrings } from './SnapshotUtilities';
-
-type Optional<T> = {
-	[P in keyof T]: T[P] | undefined;
-};
+import { comparePayloads } from './PayloadUtilities';
+import { NodeData, Payload } from './persisted-types';
 
 /**
- * A node that can be contained within a Forest.
+ * A node that can be contained within a Forest
+ *
+ * @public
  */
-export interface ForestNode extends NodeData {
+export interface ForestNode extends NodeData<NodeId> {
 	readonly traits: ReadonlyMap<TraitLabel, readonly NodeId[]>;
 }
 
-interface ForestNodeWithParentage extends ForestNode, Optional<ParentData> {
-	readonly _brand: unique symbol;
+/**
+ * A node within a Forest that has a parent (and is therefore not the root node)
+ *
+ * @public
+ */
+export interface ParentedForestNode extends ForestNode, ParentData {}
+
+/**
+ * Check whether or not the given node in a forest is parented
+ *
+ * @public
+ */
+export function isParentedForestNode(node: ForestNode): node is ParentedForestNode {
+	const parentedNode = node as ForestNode & Partial<ParentedForestNode>;
+	const hasParent = parentedNode.parentId !== undefined;
+	const hasTraitParent = parentedNode.traitParent !== undefined;
+	assert(hasParent === hasTraitParent, 'node must have either both parent and traitParent set or neither');
+	return hasParent;
 }
 
 /**
  * Information about a ForestNode's parent
+ *
+ * @public
  */
 export interface ParentData {
 	readonly parentId: NodeId;
@@ -51,20 +67,22 @@ export interface Delta<NodeId> {
 }
 
 interface ForestState {
-	nodes: BTree<NodeId, ForestNodeWithParentage>;
+	nodes: BTree<NodeId, ForestNode>;
 	expensiveValidation: boolean;
 }
 
 /**
  * An immutable forest of ForestNode.
  * Enforces single parenting, and allows querying the parent.
+ *
+ * @public
  */
 export class Forest {
 	/**
 	 * Contains the nodes in the forest.
 	 * Used as an immutable data-structure: must not be modified.
 	 */
-	private readonly nodes: BTree<NodeId, ForestNodeWithParentage>;
+	private readonly nodes: BTree<NodeId, ForestNode>;
 
 	/**
 	 * If true, consistency checks will be applied after forest operations.
@@ -87,7 +105,7 @@ export class Forest {
 			this.nodes = data.nodes;
 			this.expensiveValidation = data.expensiveValidation;
 		} else {
-			this.nodes = new BTree<NodeId, ForestNodeWithParentage>(undefined, compareStrings);
+			this.nodes = new BTree<NodeId, ForestNode>(undefined, compareFiniteNumbers);
 			this.expensiveValidation = data ?? false;
 		}
 		if (this.expensiveValidation) {
@@ -110,14 +128,21 @@ export class Forest {
 	}
 
 	/**
-	 * Adds the supplied nodes to the forest. The IDs must be unique in the forest.
+	 * Adds the supplied nodes to the forest. The nodes' IDs must be unique in the forest.
 	 * @param nodes - the sequence of nodes to add to the forest. If any of them have children which exist in the forest already, those
-	 * children will be parented. Any trait arrays present in a node must be non-empty.
+	 * children will be parented. Any trait arrays present in a node must be non-empty. The nodes may be provided in any order.
 	 */
 	public add(nodes: Iterable<ForestNode>): Forest {
 		const newNodes = [...nodes];
-		const childToParent = new Map<NodeId, ParentData>();
 		const mutableNodes = this.nodes.clone();
+
+		// This method iterates through the supplied nodes in two passes, first looking only at children and second actually adding the
+		// nodes. This allows nodes to be passed in any order, e.g. a parent followed by a child or a child followed by a parent.
+
+		const childToParent = new Map<NodeId, ParentData>(); // Temporarily records the parentage of children that don't exist yet
+
+		// First, inspect the children of each node. If the child is already in the forest, update its parentage. If it is not in the
+		// forest, it may be about to be added in the second loop below so record its parentage temporarily for when that happens.
 		for (const node of newNodes) {
 			const { identifier } = node;
 			for (const [traitLabel, trait] of node.traits) {
@@ -125,8 +150,8 @@ export class Forest {
 				for (const childId of trait) {
 					const child = mutableNodes.get(childId);
 					if (child !== undefined) {
-						assert(child.parentId === undefined, 'can not give a child multiple parents');
 						// A child already exists in the forest, and its parent is now being added
+						assert(!isParentedForestNode(child), 'can not give a child multiple parents');
 						const parentedChild = {
 							definition: child.definition,
 							identifier: child.identifier,
@@ -135,19 +160,22 @@ export class Forest {
 							traitParent: traitLabel,
 						};
 						copyPropertyIfDefined(child, parentedChild, 'payload');
-						mutableNodes.set(childId, parentedChild as ForestNodeWithParentage);
+						// Overwrite the existing child with its parented version
+						mutableNodes.set(childId, parentedChild);
 					} else {
+						// The child hasn't been added yet, so record its parentage to use when it is added below
 						childToParent.set(childId, { parentId: identifier, traitParent: traitLabel });
 					}
 				}
 			}
 		}
 
+		// Now add each node to the forest and apply any parentage information that was recorded above
 		for (const node of newNodes) {
 			const parentData = childToParent.get(node.identifier);
 			assert(!mutableNodes.has(node.identifier), 'can not add node with already existing id');
 			if (parentData !== undefined) {
-				// A parent and child have both been added for the first time
+				// This is a child whom we haven't added yet, but whose parent we already added above. Supply the recorded parentage info.
 				const child = {
 					definition: node.definition,
 					identifier: node.identifier,
@@ -155,10 +183,10 @@ export class Forest {
 					...parentData,
 				};
 				copyPropertyIfDefined(node, child, 'payload');
-				mutableNodes.set(node.identifier, child as ForestNodeWithParentage);
+				mutableNodes.set(node.identifier, child);
 			} else {
-				// A root node (no parent) has been added to the forest
-				mutableNodes.set(node.identifier, node as ForestNodeWithParentage);
+				// This is a node that has no parent. Add it with no parentage information.
+				mutableNodes.set(node.identifier, node);
 			}
 		}
 
@@ -200,8 +228,8 @@ export class Forest {
 
 		for (const childId of childIds) {
 			mutableNodes.editRange(childId, childId, true, (_, n) => {
-				assert(n.parentId === undefined, 'can not attach node that already has a parent');
-				const breakVal: { value: ForestNodeWithParentage } = {
+				assert(!isParentedForestNode(n), 'can not attach node that already has a parent');
+				const breakVal: { value: ParentedForestNode } = {
 					value: {
 						...n,
 						parentId,
@@ -255,13 +283,14 @@ export class Forest {
 		mutableNodes.set(parentId, { ...parentNode, traits });
 		for (const childId of detached) {
 			mutableNodes.editRange(childId, childId, true, (_, n) => {
-				const breakVal: { value: ForestNodeWithParentage } = {
+				const breakVal: { value: ForestNode } = {
 					value: {
-						...n,
-						parentId: undefined,
-						traitParent: undefined,
+						definition: n.definition,
+						identifier: n.identifier,
+						traits: n.traits,
 					},
 				};
+				copyPropertyIfDefined(n, breakVal.value, 'payload');
 				return breakVal;
 			});
 		}
@@ -280,6 +309,7 @@ export class Forest {
 	 * @param nodeId - the id of the node
 	 * @param value - the new value
 	 */
+	// eslint-disable-next-line @rushstack/no-new-null
 	public setValue(nodeId: NodeId, value: Payload | null): Forest {
 		const node = this.nodes.get(nodeId);
 		assert(node, 'can not replace payload for node that does not exist');
@@ -290,13 +320,20 @@ export class Forest {
 		} else {
 			delete newNode.payload;
 		}
-		mutableNodes.set(nodeId, newNode as ForestNodeWithParentage);
+		mutableNodes.set(nodeId, newNode);
 		return new Forest({
 			nodes: mutableNodes,
 			expensiveValidation: this.expensiveValidation,
 		});
 	}
 
+	/**
+	 * @returns true if the node associated with `id` exists in this forest, otherwise false
+	 */
+	public has(id: NodeId): boolean {
+		return this.nodes.has(id);
+	}
+
 	/**
 	 * @returns the node associated with `id`. Should not be used if there is no node with the provided id.
 	 */
@@ -328,24 +365,21 @@ export class Forest {
 		});
 	}
 
-	private deleteRecursive(
-		mutableNodes: BTree<NodeId, ForestNodeWithParentage>,
-		id: NodeId,
-		deleteChildren: boolean
-	): void {
+	private deleteRecursive(mutableNodes: BTree<NodeId, ForestNode>, id: NodeId, deleteChildren: boolean): void {
 		const node = mutableNodes.get(id) ?? fail('node to delete must exist');
-		assert(node.parentId === undefined && node.traitParent === undefined, 'deleted nodes must be unparented');
+		assert(!isParentedForestNode(node), 'deleted nodes must be unparented');
 		mutableNodes.delete(id);
 		for (const trait of node.traits.values()) {
 			for (const childId of trait) {
 				mutableNodes.editRange(childId, childId, true, (_, n) => {
-					const breakVal: { value: ForestNodeWithParentage } = {
+					const breakVal: { value: ForestNode } = {
 						value: {
-							...n,
-							parentId: undefined,
-							traitParent: undefined,
+							definition: n.definition,
+							identifier: n.identifier,
+							traits: n.traits,
 						},
 					};
+					copyPropertyIfDefined(n, breakVal.value, 'payload');
 					return breakVal;
 				});
 
@@ -363,12 +397,7 @@ export class Forest {
 	public assertConsistent(): void {
 		const checkedChildren = new Set<NodeId>([]);
 		for (const [nodeId, node] of this.nodes.entries(undefined, [])) {
-			assert(
-				(node.parentId === undefined) === (node.traitParent === undefined),
-				'node must have either both parent and traitParent set or neither'
-			);
-
-			if (node.parentId !== undefined && node.traitParent !== undefined) {
+			if (isParentedForestNode(node)) {
 				const parent = this.get(node.parentId);
 				const trait = parent.traits.get(node.traitParent);
 				assert(trait !== undefined);
@@ -380,6 +409,7 @@ export class Forest {
 				for (const childId of trait) {
 					const child = this.nodes.get(childId);
 					assert(child, 'child in trait is not in forest');
+					assert(isParentedForestNode(child), 'child is not parented');
 					assert(child.parentId === node.identifier, 'child parent pointer is incorrect');
 					assert(
 						!checkedChildren.has(childId),
@@ -404,10 +434,8 @@ export class Forest {
 			fail('NodeId not found');
 		}
 
-		return {
-			parentId: child.parentId ?? fail('Node is not parented'),
-			traitParent: child.traitParent ?? fail('Node is not parented'),
-		};
+		assert(isParentedForestNode(child), 'Node is not parented');
+		return { parentId: child.parentId, traitParent: child.traitParent };
 	}
 
 	/**
@@ -415,11 +443,7 @@ export class Forest {
 	 */
 	public tryGetParent(id: NodeId): ParentData | undefined {
 		const child = this.nodes.get(id);
-		if (child === undefined) {
-			return undefined;
-		}
-
-		if (child.parentId === undefined || child.traitParent === undefined) {
+		if (child === undefined || !isParentedForestNode(child)) {
 			return undefined;
 		}
 
@@ -429,10 +453,6 @@ export class Forest {
 		};
 	}
 
-	private static breakOnDifference(): { break: boolean } {
-		return { break: true };
-	}
-
 	/**
 	 * Compares two forests for equality.
 	 * @param forest - the other forest to compare to this one
@@ -448,19 +468,7 @@ export class Forest {
 			return false;
 		}
 
-		const diff = this.nodes.diffAgainst(
-			forest.nodes,
-			Forest.breakOnDifference,
-			Forest.breakOnDifference,
-			(_, nodeThis, nodeOther) => {
-				if (!compareForestNodes(nodeThis, nodeOther)) {
-					return { break: true };
-				}
-				return undefined;
-			}
-		);
-
-		return diff === undefined;
+		return compareBtrees(this.nodes, forest.nodes, compareForestNodes);
 	}
 
 	/**
@@ -496,7 +504,7 @@ export class Forest {
 }
 
 /**
- * @returns true iff two `SnapshotNodes` are equivalent.
+ * @returns true iff two `ForestNodes` are equivalent.
  * May return false for nodes they contain equivalent payloads encoded differently.
  */
 export function compareForestNodes(nodeA: ForestNode, nodeB: ForestNode): boolean {

package/src/{default-edits/HistoryEditFactory.ts → HistoryEditFactory.ts}

@@ -3,49 +3,72 @@
  * Licensed under the MIT License.
  */
 
-import { DetachedSequenceId, NodeId } from '../Identifiers';
-import { assert, fail } from '../Common';
-import { Snapshot, Side } from '../Snapshot';
-import { BuildNode, TreeNode } from '../generic';
-import { Change, ChangeType, Detach, Insert, SetValue, StableRange, StablePlace } from './PersistedTypes';
-import { Transaction } from './Transaction';
-import { rangeFromStableRange } from './EditUtilities';
+import { DetachedSequenceId, isDetachedSequenceId, NodeId } from './Identifiers';
+import { assert, fail } from './Common';
+import { rangeFromStableRange } from './TreeViewUtilities';
+import {
+	ChangeInternal,
+	ChangeTypeInternal,
+	DetachInternal,
+	SetValueInternal,
+	InsertInternal,
+	BuildNodeInternal,
+	Side,
+	StableRangeInternal,
+} from './persisted-types';
+import { TransactionInternal } from './TransactionInternal';
+import { RangeValidationResultKind, validateStableRange } from './EditUtilities';
+import { StablePlace } from './ChangeTypes';
+import { RevisionView } from './RevisionView';
+import { TreeView } from './TreeView';
+import { getChangeNodeFromViewNode } from './SerializationUtilities';
 
 /**
  * Given a sequence of changes, produces an inverse sequence of changes, i.e. the minimal changes required to revert the given changes
  * @param changes - the changes for which to produce an inverse.
- * @param before - a snapshot of the tree state before `changes` are/were applied - used as a basis for generating the inverse.
- * @returns a sequence of changes _r_ that will produce `before` if applied to a snapshot _A_, where _A_ is the result of
- * applying `changes` to `before`. Applying _r_ to snapshots other than _A_ is legal but may cause the changes to fail to apply or may
- * not be a true semantic inverse.
+ * @param before - a view of the tree state before `changes` are/were applied - used as a basis for generating the inverse.
+ * @returns if the changes could be reverted, a sequence of changes _r_ that will produce `before` if applied to a view _A_, where _A_ is the result of
+ * applying `changes` to `before`. Applying _r_ to views other than _A_ is legal but may cause the changes to fail to apply or may
+ * not be a true semantic inverse. If the changes could not be reverted given the state of `before`, returns undefined.
  *
  * TODO: what should this do if `changes` fails to apply to `before`?
- * @public
+ * TODO:#68574: Pass a view that corresponds to the appropriate Fluid reference sequence number rather than the view just before
+ * @internal
  */
-export function revert(changes: readonly Change[], before: Snapshot): Change[] {
-	const result: Change[] = [];
+export function revert(changes: readonly ChangeInternal[], before: RevisionView): ChangeInternal[] | undefined {
+	const result: ChangeInternal[] = [];
 
 	const builtNodes = new Map<DetachedSequenceId, NodeId[]>();
 	const detachedNodes = new Map<DetachedSequenceId, NodeId[]>();
 
 	// Open edit on revision to update it as changes are walked through
-	const editor = new Transaction(before);
+	const editor = TransactionInternal.factory(before);
 	// Apply `edit`, generating an inverse as we go.
 	for (const change of changes) {
 		// Generate an inverse of each change
 		switch (change.type) {
-			case ChangeType.Build: {
+			case ChangeTypeInternal.Build: {
 				// Save nodes added to the detached state for use in future changes
 				const { destination, source } = change;
 				assert(!builtNodes.has(destination), `Cannot revert Build: destination is already used by a Build`);
 				assert(!detachedNodes.has(destination), `Cannot revert Build: destination is already used by a Detach`);
 				builtNodes.set(
 					destination,
-					source.map((node) => (node as TreeNode<BuildNode>).identifier)
+					source.reduce((ids: NodeId[], curr: BuildNodeInternal) => {
+						if (isDetachedSequenceId(curr)) {
+							const nodesForDetachedSequence =
+								builtNodes.get(curr) ?? fail('detached sequence must have associated built nodes');
+
+							ids.push(...nodesForDetachedSequence);
+						} else {
+							ids.push(curr.identifier);
+						}
+						return ids;
+					}, [])
 				);
 				break;
 			}
-			case ChangeType.Insert: {
+			case ChangeTypeInternal.Insert: {
 				const { source } = change;
 				const nodesBuilt = builtNodes.get(source);
 				const nodesDetached = detachedNodes.get(source);
@@ -57,37 +80,46 @@ export function revert(changes: readonly Change[], before: Snapshot): Change[] {
 					result.unshift(createInvertedInsert(change, nodesDetached, true));
 					detachedNodes.delete(source);
 				} else {
-					fail('Cannot revert Insert: source has not been built or detached.');
+					// Cannot revert an insert whose source is no longer available for inserting (i.e. not just built, and not detached)
+					return undefined;
 				}
 
 				break;
 			}
-			case ChangeType.Detach: {
+			case ChangeTypeInternal.Detach: {
 				const { destination } = change;
-				const { invertedDetach, detachedNodeIds } = createInvertedDetach(change, editor.view);
+				const invert = createInvertedDetach(change, editor.view);
+				if (invert === undefined) {
+					// Cannot revert a detach whose source does not exist in the tree
+					// TODO:68574: May not be possible once associated todo in `createInvertedDetach` is addressed
+					return undefined;
+				}
+				const { invertedDetach, detachedNodeIds } = invert;
 
 				if (destination !== undefined) {
-					assert(
-						!builtNodes.has(destination),
-						`Cannot revert Detach: destination is already used by a Build`
-					);
-					assert(
-						!detachedNodes.has(destination),
-						`Cannot revert Detach: destination is already used by a Detach`
-					);
+					if (builtNodes.has(destination) || detachedNodes.has(destination)) {
+						// Malformed: destination was already used by a prior build or detach
+						return undefined;
+					}
 					detachedNodes.set(destination, detachedNodeIds);
 				}
 
 				result.unshift(...invertedDetach);
 				break;
 			}
-			case ChangeType.SetValue:
-				result.unshift(...createInvertedSetValue(change, editor.view));
+			case ChangeTypeInternal.SetValue: {
+				const invert = createInvertedSetValue(change, editor.view);
+				if (invert === undefined) {
+					// Cannot revert a set for a node that does not exist in the tree
+					// TODO:68574: May not be possible once associated todo in `createInvertedSetValue` is addressed
+					return undefined;
+				}
+				result.unshift(...invert);
 				break;
-			case ChangeType.Constraint:
+			}
+			case ChangeTypeInternal.Constraint:
 				// TODO:#46759: Support Constraint in reverts
 				fail('Revert currently does not support Constraints');
-				break;
 			default:
 				fail('Revert does not support the change type.');
 		}
@@ -101,13 +133,17 @@ export function revert(changes: readonly Change[], before: Snapshot): Change[] {
 }
 
 /**
- * Inverse of an Insert is a Detach that starts before the leftmost node inserted and ends after the rightmost.
+ * The inverse of an Insert is a Detach that starts before the leftmost node inserted and ends after the rightmost.
  */
-function createInvertedInsert(insert: Insert, nodesInserted: readonly NodeId[], saveDetached = false): Change {
+function createInvertedInsert(
+	insert: InsertInternal,
+	nodesInserted: readonly NodeId[],
+	saveDetached = false
+): ChangeInternal {
 	const leftmostNode = nodesInserted[0];
 	const rightmostNode = nodesInserted[nodesInserted.length - 1];
 
-	const source: StableRange = {
+	const source: StableRangeInternal = {
 		start: {
 			referenceSibling: leftmostNode,
 			side: Side.Before,
@@ -118,7 +154,7 @@ function createInvertedInsert(insert: Insert, nodesInserted: readonly NodeId[],
 		},
 	};
 
-	return Change.detach(source, saveDetached ? insert.source : undefined);
+	return ChangeInternal.detach(source, saveDetached ? insert.source : undefined);
 }
 
 /**
@@ -150,17 +186,21 @@ function createInvertedInsert(insert: Insert, nodesInserted: readonly NodeId[],
  *  anchor to the left of the originally detached nodes is chosen.
  */
 function createInvertedDetach(
-	detach: Detach,
-	snapshotBeforeEdit: Snapshot
-): { invertedDetach: Change[]; detachedNodeIds: NodeId[] } {
-	const { source } = detach;
+	detach: DetachInternal,
+	viewBeforeChange: TreeView
+): { invertedDetach: ChangeInternal[]; detachedNodeIds: NodeId[] } | undefined {
+	const validatedSource = validateStableRange(viewBeforeChange, detach.source);
+	if (validatedSource.result !== RangeValidationResultKind.Valid) {
+		// TODO:#68574: having the reference view would potentially allow us to revert some detaches that currently conflict
+		return undefined;
+	}
 
-	const { start, end } = rangeFromStableRange(snapshotBeforeEdit, source);
+	const { start, end } = rangeFromStableRange(viewBeforeChange, validatedSource);
 	const { trait: referenceTrait } = start;
-	const nodes = snapshotBeforeEdit.getTrait(referenceTrait);
+	const nodes = viewBeforeChange.getTrait(referenceTrait);
 
-	const startIndex = snapshotBeforeEdit.findIndexWithinTrait(start);
-	const endIndex = snapshotBeforeEdit.findIndexWithinTrait(end);
+	const startIndex = viewBeforeChange.findIndexWithinTrait(start);
+	const endIndex = viewBeforeChange.findIndexWithinTrait(end);
 	const detachedNodeIds: NodeId[] = nodes.slice(startIndex, endIndex);
 
 	const leftOfDetached = nodes.slice(0, startIndex);
@@ -188,7 +228,7 @@ function createInvertedDetach(
 
 	if (detach.destination !== undefined) {
 		return {
-			invertedDetach: [Change.insert(detach.destination, insertDestination)],
+			invertedDetach: [ChangeInternal.insert(detach.destination, insertDestination)],
 			detachedNodeIds,
 		};
 	}
@@ -196,20 +236,30 @@ function createInvertedDetach(
 	const detachedSequenceId = 0 as DetachedSequenceId;
 	return {
 		invertedDetach: [
-			Change.build(snapshotBeforeEdit.getChangeNodes(detachedNodeIds), detachedSequenceId),
-			Change.insert(detachedSequenceId, insertDestination),
+			ChangeInternal.build(
+				detachedNodeIds.map((id) => getChangeNodeFromViewNode(viewBeforeChange, id)),
+				detachedSequenceId
+			),
+			ChangeInternal.insert(detachedSequenceId, insertDestination),
 		],
 		detachedNodeIds,
 	};
 }
 
-function createInvertedSetValue(setValue: SetValue, revisionBeforeEdit: Snapshot): Change[] {
+/**
+ * The inverse of a SetValue is a SetValue that sets the value to what it was prior to the change.
+ */
+function createInvertedSetValue(setValue: SetValueInternal, viewBeforeChange: TreeView): ChangeInternal[] | undefined {
 	const { nodeToModify } = setValue;
-	const oldPayload = revisionBeforeEdit.getSnapshotNode(nodeToModify).payload;
+	const node = viewBeforeChange.tryGetViewNode(nodeToModify);
+	if (node === undefined) {
+		// TODO:68574: With a reference view, may be able to better resolve conflicting sets
+		return undefined;
+	}
 
 	// Rationale: 'undefined' is reserved for future use (see 'SetValue' interface)
-	if (oldPayload !== null) {
-		return [Change.setPayload(nodeToModify, oldPayload)];
+	if (node.payload !== null) {
+		return [ChangeInternal.setPayload(nodeToModify, node.payload)];
 	}
-	return [Change.clearPayload(nodeToModify)];
+	return [ChangeInternal.clearPayload(nodeToModify)];
 }