@fluidframework/tree 2.12.0 → 2.20.0

package/src/core/tree/index.ts

@@ -104,8 +104,6 @@ export { SparseNode, getDescendant } from "./sparseTree.js";
 
 export {
 	deltaForRootInitialization,
-	emptyFieldChanges,
-	isEmptyFieldChanges,
 	makeDetachedNodeId,
 	offsetDetachId,
 	emptyDelta,

package/src/core/tree/visitDelta.ts

@@ -105,6 +105,8 @@ export function visitDelta(
 		rootDestructions,
 	};
 	processBuilds(delta.build, detachConfig, visitor);
+	processGlobal(delta.global, detachConfig, visitor);
+	processRename(delta.rename, detachConfig);
 	visitFieldMarks(delta.fields, visitor, detachConfig);
 	fixedPointVisitOfRoots(visitor, detachPassRoots, detachConfig);
 	transferRoots(
@@ -420,52 +422,32 @@ function visitNode(
  * (because we want to wait until we are sure content to attach is available as a root)
  */
 function detachPass(
-	delta: Delta.FieldChanges,
+	fieldChanges: Delta.FieldChanges,
 	visitor: DeltaVisitor,
 	config: PassConfig,
 ): void {
-	if (delta.global !== undefined) {
-		for (const { id, fields } of delta.global) {
-			let root = config.detachedFieldIndex.tryGetEntry(id);
-			if (root === undefined) {
-				const tree = tryGetFromNestedMap(config.refreshers, id.major, id.minor);
-				assert(tree !== undefined, 0x928 /* refresher data not found */);
-				buildTrees(id, [tree], config.detachedFieldIndex, config.latestRevision, visitor);
-				root = config.detachedFieldIndex.getEntry(id);
-			}
-			// the revision is updated for any refresher data included in the delta that is used
-			config.detachedFieldIndex.updateLatestRevision(id, config.latestRevision);
-			config.detachPassRoots.set(root, fields);
-			config.attachPassRoots.set(root, fields);
+	let index = 0;
+	for (const mark of fieldChanges) {
+		if (mark.fields !== undefined) {
+			assert(
+				mark.attach === undefined || mark.detach !== undefined,
+				0x7d0 /* Invalid nested changes on an additive mark */,
+			);
+			visitNode(index, mark.fields, visitor, config);
 		}
-	}
-	if (delta.rename !== undefined) {
-		config.rootTransfers.push(...delta.rename);
-	}
-	if (delta.local !== undefined) {
-		let index = 0;
-		for (const mark of delta.local) {
-			if (mark.fields !== undefined) {
-				assert(
-					mark.attach === undefined || mark.detach !== undefined,
-					0x7d0 /* Invalid nested changes on an additive mark */,
-				);
-				visitNode(index, mark.fields, visitor, config);
-			}
-			if (isDetachMark(mark)) {
-				for (let i = 0; i < mark.count; i += 1) {
-					// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-					const id = offsetDetachId(mark.detach!, i);
-					const root = config.detachedFieldIndex.createEntry(id, config.latestRevision);
-					if (mark.fields !== undefined) {
-						config.attachPassRoots.set(root, mark.fields);
-					}
-					const field = config.detachedFieldIndex.toFieldKey(root);
-					visitor.detach({ start: index, end: index + 1 }, field);
+		if (isDetachMark(mark)) {
+			for (let i = 0; i < mark.count; i += 1) {
+				// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+				const id = offsetDetachId(mark.detach!, i);
+				const root = config.detachedFieldIndex.createEntry(id, config.latestRevision);
+				if (mark.fields !== undefined) {
+					config.attachPassRoots.set(root, mark.fields);
 				}
-			} else if (!isAttachMark(mark)) {
-				index += mark.count;
+				const field = config.detachedFieldIndex.toFieldKey(root);
+				visitor.detach({ start: index, end: index + 1 }, field);
 			}
+		} else if (!isAttachMark(mark)) {
+			index += mark.count;
 		}
 	}
 }
@@ -499,6 +481,37 @@ function processBuilds(
 	}
 }
 
+function processGlobal(
+	global: readonly Delta.DetachedNodeChanges[] | undefined,
+	config: PassConfig,
+	visitor: DeltaVisitor,
+): void {
+	if (global !== undefined) {
+		for (const { id, fields } of global) {
+			let root = config.detachedFieldIndex.tryGetEntry(id);
+			if (root === undefined) {
+				const tree = tryGetFromNestedMap(config.refreshers, id.major, id.minor);
+				assert(tree !== undefined, 0x928 /* refresher data not found */);
+				buildTrees(id, [tree], config.detachedFieldIndex, config.latestRevision, visitor);
+				root = config.detachedFieldIndex.getEntry(id);
+			}
+			// the revision is updated for any refresher data included in the delta that is used
+			config.detachedFieldIndex.updateLatestRevision(id, config.latestRevision);
+			config.detachPassRoots.set(root, fields);
+			config.attachPassRoots.set(root, fields);
+		}
+	}
+}
+
+function processRename(
+	rename: readonly Delta.DetachedNodeRename[] | undefined,
+	config: PassConfig,
+): void {
+	if (rename !== undefined) {
+		config.rootTransfers.push(...rename);
+	}
+}
+
 function collectDestroys(
 	destroys: readonly Delta.DetachedNodeDestruction[] | undefined,
 	config: PassConfig,
@@ -515,69 +528,67 @@ function collectDestroys(
  * - Collects detached roots (from replaces) that need an attach pass
  */
 function attachPass(
-	delta: Delta.FieldChanges,
+	fieldChanges: Delta.FieldChanges,
 	visitor: DeltaVisitor,
 	config: PassConfig,
 ): void {
-	if (delta.local !== undefined) {
-		let index = 0;
-		for (const mark of delta.local) {
-			if (isAttachMark(mark) || isReplaceMark(mark)) {
-				for (let i = 0; i < mark.count; i += 1) {
-					// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-					const offsetAttachId = offsetDetachId(mark.attach!, i);
-					let sourceRoot = config.detachedFieldIndex.tryGetEntry(offsetAttachId);
-					if (sourceRoot === undefined) {
-						const tree = tryGetFromNestedMap(
-							config.refreshers,
-							offsetAttachId.major,
-							offsetAttachId.minor,
-						);
-						assert(tree !== undefined, 0x92a /* refresher data not found */);
-						buildTrees(
-							offsetAttachId,
-							[tree],
-							config.detachedFieldIndex,
-							config.latestRevision,
-							visitor,
-						);
-						sourceRoot = config.detachedFieldIndex.getEntry(offsetAttachId);
-					}
-					const sourceField = config.detachedFieldIndex.toFieldKey(sourceRoot);
-					const offsetIndex = index + i;
-					if (isReplaceMark(mark)) {
-						const rootDestination = config.detachedFieldIndex.createEntry(
-							// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-							offsetDetachId(mark.detach!, i),
-							config.latestRevision,
-						);
-						const destinationField = config.detachedFieldIndex.toFieldKey(rootDestination);
-						visitor.replace(
-							sourceField,
-							{ start: offsetIndex, end: offsetIndex + 1 },
-							destinationField,
-						);
-						// We may need to do a second pass on the detached nodes
-						if (mark.fields !== undefined) {
-							config.attachPassRoots.set(rootDestination, mark.fields);
-						}
-					} else {
-						// This a simple attach
-						visitor.attach(sourceField, 1, offsetIndex);
-					}
-					config.detachedFieldIndex.deleteEntry(offsetAttachId);
-					const fields = config.attachPassRoots.get(sourceRoot);
-					if (fields !== undefined) {
-						config.attachPassRoots.delete(sourceRoot);
-						visitNode(offsetIndex, fields, visitor, config);
+	let index = 0;
+	for (const mark of fieldChanges) {
+		if (isAttachMark(mark) || isReplaceMark(mark)) {
+			for (let i = 0; i < mark.count; i += 1) {
+				// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+				const offsetAttachId = offsetDetachId(mark.attach!, i);
+				let sourceRoot = config.detachedFieldIndex.tryGetEntry(offsetAttachId);
+				if (sourceRoot === undefined) {
+					const tree = tryGetFromNestedMap(
+						config.refreshers,
+						offsetAttachId.major,
+						offsetAttachId.minor,
+					);
+					assert(tree !== undefined, 0x92a /* refresher data not found */);
+					buildTrees(
+						offsetAttachId,
+						[tree],
+						config.detachedFieldIndex,
+						config.latestRevision,
+						visitor,
+					);
+					sourceRoot = config.detachedFieldIndex.getEntry(offsetAttachId);
+				}
+				const sourceField = config.detachedFieldIndex.toFieldKey(sourceRoot);
+				const offsetIndex = index + i;
+				if (isReplaceMark(mark)) {
+					const rootDestination = config.detachedFieldIndex.createEntry(
+						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+						offsetDetachId(mark.detach!, i),
+						config.latestRevision,
+					);
+					const destinationField = config.detachedFieldIndex.toFieldKey(rootDestination);
+					visitor.replace(
+						sourceField,
+						{ start: offsetIndex, end: offsetIndex + 1 },
+						destinationField,
+					);
+					// We may need to do a second pass on the detached nodes
+					if (mark.fields !== undefined) {
+						config.attachPassRoots.set(rootDestination, mark.fields);
 					}
+				} else {
+					// This a simple attach
+					visitor.attach(sourceField, 1, offsetIndex);
+				}
+				config.detachedFieldIndex.deleteEntry(offsetAttachId);
+				const fields = config.attachPassRoots.get(sourceRoot);
+				if (fields !== undefined) {
+					config.attachPassRoots.delete(sourceRoot);
+					visitNode(offsetIndex, fields, visitor, config);
 				}
-			} else if (!isDetachMark(mark) && mark.fields !== undefined) {
-				visitNode(index, mark.fields, visitor, config);
-			}
-			if (!isDetachMark(mark)) {
-				index += mark.count;
 			}
+		} else if (!isDetachMark(mark) && mark.fields !== undefined) {
+			visitNode(index, mark.fields, visitor, config);
+		}
+		if (!isDetachMark(mark)) {
+			index += mark.count;
 		}
 	}
 }

package/src/feature-libraries/default-schema/defaultEditBuilder.ts

@@ -160,8 +160,17 @@ export interface IDefaultEditBuilder {
 		destinationIndex: number,
 	): void;
 
-	// TODO: document
+	/**
+	 * Add a constraint that the node at the given path must exist.
+	 * @param path - The path to the node that must exist.
+	 */
 	addNodeExistsConstraint(path: UpPath): void;
+
+	/**
+	 * Add a constraint that the node at the given path must exist when reverting a change.
+	 * @param path - The path to the node that must exist when reverting a change.
+	 */
+	addNodeExistsConstraintOnRevert(path: UpPath): void;
 }
 
 /**
@@ -191,6 +200,10 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		this.modularBuilder.addNodeExistsConstraint(path, this.mintRevisionTag());
 	}
 
+	public addNodeExistsConstraintOnRevert(path: UpPath): void {
+		this.modularBuilder.addNodeExistsConstraintOnRevert(path, this.mintRevisionTag());
+	}
+
 	public valueField(field: FieldUpPath): ValueFieldEditBuilder<ITreeCursorSynchronous> {
 		return {
 			set: (newContent: ITreeCursorSynchronous): void => {

package/src/feature-libraries/default-schema/defaultFieldKinds.ts

@@ -6,13 +6,13 @@
 import {
 	type ChangeAtomId,
 	type DeltaDetachedNodeId,
-	type DeltaFieldChanges,
 	type FieldKindIdentifier,
 	forbiddenFieldKindIdentifier,
 	Multiplicity,
 } from "../../core/index.js";
 import { fail } from "../../util/index.js";
 import {
+	type FieldChangeDelta,
 	type FieldChangeHandler,
 	type FieldEditor,
 	type FieldKindConfiguration,
@@ -43,7 +43,7 @@ export const noChangeHandler: FieldChangeHandler<0> = {
 	}),
 	codecsFactory: () => noChangeCodecFamily,
 	editor: { buildChildChange: (index, change) => fail("Child changes not supported") },
-	intoDelta: (change, deltaFromChild: ToDelta): DeltaFieldChanges => ({}),
+	intoDelta: (change, deltaFromChild: ToDelta): FieldChangeDelta => ({}),
 	relevantRemovedRoots: (change): Iterable<DeltaDetachedNodeId> => [],
 	isEmpty: (change: 0) => true,
 	getNestedChanges: (change: 0) => [],

package/src/feature-libraries/deltaUtils.ts

@@ -39,5 +39,18 @@ export function mapRootChanges<TIn, TOut>(
 			trees: trees.map(func),
 		}));
 	}
+	if (root.global !== undefined) {
+		out.global = root.global.map(({ id, fields }) => ({
+			id,
+			fields,
+		}));
+	}
+	if (root.rename !== undefined) {
+		out.rename = root.rename.map(({ count, oldId, newId }) => ({
+			count,
+			oldId,
+			newId,
+		}));
+	}
 	return out;
 }

package/src/feature-libraries/forest-summary/forestSummarizer.ts

@@ -150,12 +150,7 @@ export class ForestSummarizer implements Summarizable {
 					id: buildId,
 					trees: nodeCursors,
 				});
-				fieldChanges.push([
-					fieldKey,
-					{
-						local: [{ count: nodeCursors.length, attach: buildId }],
-					},
-				]);
+				fieldChanges.push([fieldKey, [{ count: nodeCursors.length, attach: buildId }]]);
 			}
 
 			assert(this.forest.isEmpty, 0x797 /* forest must be empty */);

package/src/feature-libraries/index.ts

@@ -16,7 +16,6 @@ export {
 	mapTreeFromCursor,
 	mapTreeFieldFromCursor,
 } from "./mapTreeCursor.js";
-export { MemoizedIdRangeAllocator, type IdRange } from "./memoizedIdRangeAllocator.js";
 export { buildForest } from "./object-forest/index.js";
 export { SchemaSummarizer, encodeTreeSchema, makeSchemaCodec } from "./schema-index/index.js";
 export {

package/src/feature-libraries/modular-schema/crossFieldQueries.ts

@@ -3,17 +3,16 @@
  * Licensed under the MIT License.
  */
 
-import type { ChangesetLocalId, RevisionTag } from "../../core/index.js";
-import {
-	type RangeMap,
-	type RangeQueryResult,
-	getFromRangeMap,
-	getOrAddInMap,
-	setInRangeMap,
-} from "../../util/index.js";
+import type {
+	ChangeAtomId,
+	ChangeAtomIdRangeMap,
+	ChangesetLocalId,
+	RevisionTag,
+} from "../../core/index.js";
+import type { RangeQueryResult } from "../../util/index.js";
 import type { NodeId } from "./modularChangeTypes.js";
 
-export type CrossFieldMap<T> = Map<RevisionTag | undefined, RangeMap<T>>;
+export type CrossFieldMap<T> = ChangeAtomIdRangeMap<T>;
 export type CrossFieldQuerySet = CrossFieldMap<boolean>;
 
 export function addCrossFieldQuery(
@@ -32,7 +31,7 @@ export function setInCrossFieldMap<T>(
 	count: number,
 	value: T,
 ): void {
-	setInRangeMap(getOrAddInMap(map, revision, []), id, count, value);
+	map.set({ revision, localId: id }, count, value);
 }
 
 export function getFirstFromCrossFieldMap<T>(
@@ -40,8 +39,8 @@ export function getFirstFromCrossFieldMap<T>(
 	revision: RevisionTag | undefined,
 	id: ChangesetLocalId,
 	count: number,
-): RangeQueryResult<T> {
-	return getFromRangeMap(map.get(revision) ?? [], id, count);
+): RangeQueryResult<ChangeAtomId, T> {
+	return map.getFirst({ revision, localId: id }, count);
 }
 
 /**
@@ -66,7 +65,7 @@ export interface CrossFieldManager<T = unknown> {
 		id: ChangesetLocalId,
 		count: number,
 		addDependency: boolean,
-	): RangeQueryResult<T>;
+	): RangeQueryResult<ChangeAtomId, T>;
 
 	/**
 	 * Sets the range of keys to `newValue`.

package/src/feature-libraries/modular-schema/fieldChangeHandler.ts

@@ -6,7 +6,9 @@
 import type { ICodecFamily, IJsonCodec } from "../../codec/index.js";
 import type {
 	ChangeEncodingContext,
+	DeltaDetachedNodeChanges,
 	DeltaDetachedNodeId,
+	DeltaDetachedNodeRename,
 	DeltaFieldChanges,
 	DeltaFieldMap,
 	EncodedRevisionTag,
@@ -14,12 +16,35 @@ import type {
 	RevisionTag,
 } from "../../core/index.js";
 import type { IdAllocator, Invariant } from "../../util/index.js";
-import type { MemoizedIdRangeAllocator } from "../memoizedIdRangeAllocator.js";
 
 import type { CrossFieldManager } from "./crossFieldQueries.js";
 import type { CrossFieldKeyRange, NodeId } from "./modularChangeTypes.js";
 import type { EncodedNodeChangeset } from "./modularChangeFormat.js";
 
+export type NestedChangesIndices = [
+	NodeId,
+	number | undefined /* inputIndex */,
+	number | undefined /* outputIndex */,
+][];
+
+/**
+ * The return value of calling {@link FieldChangeHandler.intoDelta}.
+ */
+export interface FieldChangeDelta {
+	/**
+	 * {@inheritdoc DeltaFieldChanges}
+	 */
+	readonly local?: DeltaFieldChanges;
+	/**
+	 * {@inheritdoc DeltaRoot.global}
+	 */
+	readonly global?: readonly DeltaDetachedNodeChanges[];
+	/**
+	 * {@inheritdoc DeltaRoot.rename}
+	 */
+	readonly rename?: readonly DeltaDetachedNodeRename[];
+}
+
 /**
  * Functionality provided by a field kind which will be composed with other `FieldChangeHandler`s to
  * implement a unified ChangeFamily supporting documents with multiple field kinds.
@@ -39,11 +64,7 @@ export interface FieldChangeHandler<
 		>,
 	) => ICodecFamily<TChangeset, FieldChangeEncodingContext>;
 	readonly editor: TEditor;
-	intoDelta(
-		change: TChangeset,
-		deltaFromChild: ToDelta,
-		idAllocator: MemoizedIdRangeAllocator,
-	): DeltaFieldChanges;
+	intoDelta(change: TChangeset, deltaFromChild: ToDelta): FieldChangeDelta;
 	/**
 	 * Returns the set of removed roots that should be in memory for the given change to be applied.
 	 * A removed root is relevant if any of the following is true:
@@ -75,13 +96,16 @@ export interface FieldChangeHandler<
 	 * @param change - The field change to get the child changes from.
 	 *
 	 * @returns The set of `NodeId`s that correspond to nested changes in the given `change`.
-	 * Each `NodeId` is associated with the index of the node in the field in the input context of the changeset
-	 * (or `undefined` if the node is not attached in the input context).
+	 * Each `NodeId` is associated with the following:
+	 * - index of the node in the field in the input context of the changeset (or `undefined` if the node is not
+	 * attached in the input context).
+	 * - index of the node in the field in the output context of the changeset (or `undefined` if the node is not
+	 * attached in the output context).
 	 * For all returned entries where the index is defined,
 	 * the indices are are ordered from smallest to largest (with no duplicates).
 	 * The returned array is owned by the caller.
 	 */
-	getNestedChanges(change: TChangeset): [NodeId, number | undefined][];
+	getNestedChanges(change: TChangeset): NestedChangesIndices;
 
 	/**
 	 * @returns A list of all cross-field keys contained in the change.

package/src/feature-libraries/modular-schema/genericFieldKind.ts

@@ -5,7 +5,6 @@
 
 import {
 	type DeltaDetachedNodeId,
-	type DeltaFieldChanges,
 	type DeltaMark,
 	type RevisionMetadataSource,
 	Multiplicity,
@@ -16,7 +15,9 @@ import { type IdAllocator, fail } from "../../util/index.js";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { CrossFieldManager } from "./crossFieldQueries.js";
 import type {
+	FieldChangeDelta,
 	FieldChangeHandler,
+	NestedChangesIndices,
 	NodeChangeComposer,
 	NodeChangePruner,
 	NodeChangeRebaser,
@@ -46,7 +47,7 @@ export const genericChangeHandler: FieldChangeHandler<GenericChangeset> = {
 			return newGenericChangeset([[index, change]]);
 		},
 	},
-	intoDelta: (change: GenericChangeset, deltaFromChild: ToDelta): DeltaFieldChanges => {
+	intoDelta: (change: GenericChangeset, deltaFromChild: ToDelta): FieldChangeDelta => {
 		let nodeIndex = 0;
 		const markList: DeltaMark[] = [];
 		for (const [index, nodeChange] of change.entries()) {
@@ -82,8 +83,9 @@ function compose(
 	return composed;
 }
 
-function getNestedChanges(change: GenericChangeset): [NodeId, number | undefined][] {
-	return change.toArray().map(([index, nodeChange]) => [nodeChange, index]);
+function getNestedChanges(change: GenericChangeset): NestedChangesIndices {
+	// For generic changeset, the indices in the input and output contexts are the same.
+	return change.toArray().map(([index, nodeChange]) => [nodeChange, index, index]);
 }
 
 function rebaseGenericChange(

package/src/feature-libraries/modular-schema/index.ts

@@ -29,6 +29,7 @@ export { FlexFieldKind, type FullSchemaPolicy } from "./fieldKind.js";
 export { FieldKindWithEditor } from "./fieldKindWithEditor.js";
 export {
 	type FieldChangeHandler,
+	type FieldChangeDelta,
 	type FieldChangeRebaser,
 	type FieldEditor,
 	type NodeChangeComposer,
@@ -41,8 +42,10 @@ export {
 	type ToDelta,
 	NodeAttachState,
 	type FieldChangeEncodingContext,
+	type NestedChangesIndices,
 } from "./fieldChangeHandler.js";
 export type {
+	CrossFieldKey,
 	CrossFieldKeyRange,
 	FieldChange,
 	FieldChangeMap,

package/src/feature-libraries/modular-schema/modularChangeCodecs.ts

@@ -32,6 +32,7 @@ import {
 	brand,
 	fail,
 	idAllocatorFromMaxId,
+	newTupleBTree,
 } from "../../util/index.js";
 import {
 	type FieldBatchCodec,
@@ -55,17 +56,17 @@ import {
 	type EncodedNodeChangeset,
 	type EncodedRevisionInfo,
 } from "./modularChangeFormat.js";
-import type {
-	ChangeAtomIdBTree,
-	FieldChangeMap,
-	FieldChangeset,
-	FieldId,
-	ModularChangeset,
-	NodeChangeset,
-	NodeId,
+import {
+	newCrossFieldKeyTable,
+	type ChangeAtomIdBTree,
+	type FieldChangeMap,
+	type FieldChangeset,
+	type FieldId,
+	type ModularChangeset,
+	type NodeChangeset,
+	type NodeId,
 } from "./modularChangeTypes.js";
 import type { FieldChangeEncodingContext, FieldChangeHandler } from "./fieldChangeHandler.js";
-import { newCrossFieldKeyTable, newTupleBTree } from "./modularChangeFamily.js";
 
 export function makeModularChangeCodecFamily(
 	fieldKindConfigurations: ReadonlyMap<number, FieldKindConfiguration>,
@@ -276,8 +277,8 @@ function makeModularChangeCodec(
 				fieldChangeset,
 			);
 
-			for (const crossFieldKey of crossFieldKeys) {
-				decoded.crossFieldKeys.set(crossFieldKey, fieldId);
+			for (const { key, count } of crossFieldKeys) {
+				decoded.crossFieldKeys.set(key, count, fieldId);
 			}
 
 			const fieldKey: FieldKey = brand<FieldKey>(field.fieldKey);