@fluidframework/tree 2.83.0 → 2.90.0-378676

package/src/core/change-family/changeFamily.ts

@@ -14,12 +14,17 @@ export interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {
 	buildEditor(
 		mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<TChange>) => void,
+		options?: EditorOptions,
 	): TEditor;
 
 	readonly rebaser: ChangeRebaser<TChange>;
 	readonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;
 }
 
+export interface EditorOptions {
+	readonly enableDetachedRootEditing: boolean; // default is false,
+}
+
 export interface ChangeEncodingContext {
 	readonly originatorId: SessionId;
 	readonly revision: RevisionTag | undefined;

package/src/core/change-family/index.ts

@@ -8,5 +8,6 @@ export type {
 	ChangeFamilyEditor,
 	ChangeEncodingContext,
 	ChangeFamilyCodec,
+	EditorOptions,
 } from "./changeFamily.js";
 export { EditBuilder } from "./editBuilder.js";

package/src/core/index.ts

@@ -74,7 +74,7 @@ export {
 	type AnchorNode,
 	anchorSlot,
 	type UpPathDefault,
-	isDetachedUpPath,
+	isDetachedUpPathRoot,
 	inCursorField,
 	inCursorNode,
 	type AnchorEvents,
@@ -87,6 +87,7 @@ export {
 	type DetachedFieldIndexCheckpoint,
 	type ForestRootId,
 	getDetachedFieldContainingPath,
+	getDetachedFieldContainingFieldPath,
 	aboveRootPlaceholder,
 	type DeltaRoot,
 	type DeltaMark,
@@ -162,6 +163,7 @@ export {
 	type ChangeEncodingContext,
 	type ChangeFamilyEditor,
 	EditBuilder,
+	type EditorOptions,
 } from "./change-family/index.js";
 
 export {
@@ -212,6 +214,7 @@ export {
 	isAncestor,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	comparePartialRevisions,
 	compareChangesetLocalIds,
 	comparePartialChangesetLocalIds,

package/src/core/rebase/changeRebaser.ts

@@ -161,7 +161,12 @@ export function mapTaggedChange<TIn, TOut>(
 export type RevisionIndexer = (tag: RevisionTag) => number | undefined;
 
 export interface RevisionMetadataSource {
-	readonly getIndex: RevisionIndexer;
+	/**
+	 * @returns a positive number if tag2 is a later revision than tag1 or a negative number if tag2 is an earlier revision.
+	 * Returns zero is the order cannot be determined, which happens if both revisions are older
+	 * than the set of revisions handled by this metadata source.
+	 */
+	readonly compareRevisions: (tag1: RevisionTag, tag2: RevisionTag) => number;
 	readonly tryGetInfo: (tag: RevisionTag | undefined) => RevisionInfo | undefined;
 	readonly hasRollback: (tag: RevisionTag) => boolean;
 }

package/src/core/rebase/index.ts

@@ -31,6 +31,7 @@ export {
 	subtractChangeAtomIds,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	comparePartialRevisions,
 	compareChangesetLocalIds,
 	comparePartialChangesetLocalIds,

package/src/core/rebase/types.ts

@@ -296,6 +296,10 @@ export function newChangeAtomIdRangeMap<V>(
 	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetValue);
 }
 
+export function newChangeAtomIdTransform(): ChangeAtomIdRangeMap<ChangeAtomId> {
+	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetChangeAtomId);
+}
+
 export function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number {
 	const cmp = comparePartialRevisions(a.revision, b.revision);
 	if (cmp !== 0) {

package/src/core/rebase/utils.ts

@@ -327,7 +327,9 @@ export function rebaseBranch<TChange>(
 			},
 		},
 		"sourceChange",
-		() => changeRebaser.compose(editsToCompose),
+		() => {
+			return changeRebaser.compose(editsToCompose);
+		},
 	);
 }
 
@@ -375,23 +377,45 @@ export function rebaseChange<TChange>(
 export function revisionMetadataSourceFromInfo(
 	revInfos: readonly RevisionInfo[],
 ): RevisionMetadataSource {
-	const getIndex = (revision: RevisionTag): number | undefined => {
-		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
-		return index >= 0 ? index : undefined;
+	const compareRevisions = (revision1: RevisionTag, revision2: RevisionTag): number => {
+		const index1 = getIndex(revision1);
+		const index2 = getIndex(revision2);
+
+		if (index1 !== undefined) {
+			return index2 === undefined ? -1 : index2 - index1;
+		}
+
+		return index2 === undefined ? 0 : 1;
 	};
+
 	const tryGetInfo = (revision: RevisionTag | undefined): RevisionInfo | undefined => {
 		if (revision === undefined) {
 			return undefined;
 		}
-		const index = getIndex(revision);
-		return index === undefined ? undefined : revInfos[index];
+		return revInfos.find((info) => info.revision === revision);
 	};
 
 	const hasRollback = (revision: RevisionTag): boolean => {
 		return revInfos.some((info) => info.rollbackOf === revision);
 	};
 
-	return { getIndex, tryGetInfo, hasRollback };
+	const getIndex = (revision: RevisionTag): number | undefined => {
+		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
+		if (index >= 0) {
+			return index;
+		}
+
+		const rollbackIndex = revInfos.findIndex((revInfo) => revInfo.rollbackOf === revision);
+		if (rollbackIndex >= 0) {
+			// This change is the forward revision of a rollback included in revInfos, so it comes after
+			// all revisions in revInfos. Earlier rollbacks have later forward revisions.
+			return 2 * revInfos.length - rollbackIndex;
+		}
+
+		return undefined;
+	};
+
+	return { compareRevisions, tryGetInfo, hasRollback };
 }
 
 export function rebaseChangeOverChanges<TChange>(

package/src/core/tree/delta.ts

@@ -204,4 +204,10 @@ export interface FieldChanges {
 	 * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.
 	 */
 	readonly marks: readonly Mark[];
+
+	/**
+	 * Indicates whether nodes detached by this field can be safely re-attached.
+	 * Defaults to false.
+	 */
+	readonly allowReattach?: boolean;
 }

package/src/core/tree/detachedFieldIndex.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
@@ -52,6 +52,12 @@ export interface ReadOnlyDetachedFieldIndex {
 	 */
 	toFieldKey(id: ForestRootId): FieldKey;
 
+	/**
+	 * Returns a node ID for the node in the given field.
+	 * @param field - The field key where the detached node resides.
+	 */
+	fromFieldKey(field: FieldKey): Delta.DetachedNodeId;
+
 	/**
 	 * Returns the `ForestRootId` associated with the given id.
 	 * Returns undefined if no such id is known to the index.
@@ -63,6 +69,12 @@ export interface ReadOnlyDetachedFieldIndex {
 	 * Fails if no such id is known to the index.
 	 */
 	getEntry(id: Delta.DetachedNodeId): ForestRootId;
+
+	/**
+	 * Returns the source associated with the given id if any.
+	 * @param id - The detached node ID.
+	 */
+	isAttachable(id: Delta.DetachedNodeId): boolean | undefined;
 }
 
 /**
@@ -197,6 +209,16 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		return brand(`${this.name}-${id}`);
 	}
 
+	public fromFieldKey(field: FieldKey): Delta.DetachedNodeId {
+		// TODO: maintain a lookup table or use field keys that encode the detached node ID
+		for (const { id, root } of this.entries()) {
+			if (this.toFieldKey(root) === field) {
+				return id;
+			}
+		}
+		fail("No known detached roots in the given field");
+	}
+
 	public tryGetEntry(id: Delta.DetachedNodeId): ForestRootId | undefined {
 		return tryGetFromNestedMap(this.detachedNodeToField, id.major, id.minor)?.root;
 	}
@@ -207,6 +229,10 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		return key;
 	}
 
+	public isAttachable(id: Delta.DetachedNodeId): boolean | undefined {
+		return tryGetFromNestedMap(this.detachedNodeToField, id.major, id.minor)?.isAttachable;
+	}
+
 	/**
 	 * Returns the detached root IDs for all the trees that were detached or last modified by the given revision.
 	 */
@@ -259,6 +285,7 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 	public createEntry(
 		nodeId?: Delta.DetachedNodeId,
 		revision?: RevisionTag,
+		isAttachable?: boolean,
 		count: number = 1,
 	): ForestRootId {
 		const root = this.rootIdAllocator.allocate(count);
@@ -272,6 +299,7 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 				setInNestedMap(this.detachedNodeToField, nodeId.major, nodeId.minor + i, {
 					root: brand<ForestRootId>(root + i),
 					latestRelevantRevision: revision,
+					isAttachable,
 				});
 				setInNestedMap(this.latestRelevantRevisionToFields, revision, root + i, {
 					major: nodeId.major,

package/src/core/tree/detachedFieldIndexTypes.ts

@@ -49,4 +49,9 @@ export interface DetachedField {
 	 * `DetachedField` and `Forest` are GC-ed.
 	 */
 	readonly latestRelevantRevision?: RevisionTag;
+
+	/**
+	 * Indicates whether the corresponding root can safely be re-attached.
+	 */
+	readonly isAttachable?: boolean;
 }

package/src/core/tree/index.ts

@@ -30,17 +30,17 @@ export {
 	CursorMarker,
 	isCursor,
 } from "./cursor.js";
-export type {
-	ProtoNodes,
-	Root as DeltaRoot,
-	Mark as DeltaMark,
-	DetachedNodeId as DeltaDetachedNodeId,
-	FieldMap as DeltaFieldMap,
-	DetachedNodeChanges as DeltaDetachedNodeChanges,
-	DetachedNodeBuild as DeltaDetachedNodeBuild,
-	DetachedNodeDestruction as DeltaDetachedNodeDestruction,
-	DetachedNodeRename as DeltaDetachedNodeRename,
-	FieldChanges as DeltaFieldChanges,
+export {
+	type ProtoNodes,
+	type Root as DeltaRoot,
+	type Mark as DeltaMark,
+	type DetachedNodeId as DeltaDetachedNodeId,
+	type FieldMap as DeltaFieldMap,
+	type DetachedNodeChanges as DeltaDetachedNodeChanges,
+	type DetachedNodeBuild as DeltaDetachedNodeBuild,
+	type DetachedNodeDestruction as DeltaDetachedNodeDestruction,
+	type DetachedNodeRename as DeltaDetachedNodeRename,
+	type FieldChanges as DeltaFieldChanges,
 } from "./delta.js";
 export { type MapTree, type ExclusiveMapTree, deepCopyMapTree } from "./mapTree.js";
 export {
@@ -59,8 +59,9 @@ export {
 	type NodeIndex,
 	compareUpPaths,
 	compareFieldUpPaths,
-	isDetachedUpPathRoot as isDetachedUpPath,
+	isDetachedUpPathRoot,
 	getDetachedFieldContainingPath,
+	getDetachedFieldContainingFieldPath,
 	type UpPathDefault,
 } from "./pathTree.js";
 export {

package/src/core/tree/pathTree.ts

@@ -126,7 +126,7 @@ export interface FieldUpPath<TUpPath = UpPath> {
  */
 export function isDetachedUpPathRoot<T>(
 	path: UpPath<T> | NormalizedUpPath,
-): path is NormalizedUpPathRoot {
+): path is NormalizedUpPathRoot & { readonly detachedNodeId: DetachedNodeId } {
 	return (path as NormalizedUpPathRoot).detachedNodeId !== undefined;
 }
 
@@ -219,8 +219,8 @@ export function clonePath(path: UpPath | undefined): UpPath | undefined {
  * Gets the elements of the given `path`, ordered from root-most to child-most.
  * @remarks These elements are unchanged and therefore still point "up".
  */
-export function topDownPath(path: UpPath | undefined): UpPath[] {
-	const out: UpPath[] = [];
+export function topDownPath<T extends UpPath<T>>(path: T | undefined): T[] {
+	const out: T[] = [];
 	let curr = path;
 	while (curr !== undefined) {
 		out.push(curr);
@@ -262,7 +262,7 @@ export function compareFieldUpPaths(a: FieldUpPath, b: FieldUpPath): boolean {
 }
 
 /**
- * Checks whether or not a given path is parented under the root field.
+ * Returns the field key for the root field.
  * @param path - the path you want to check.
  * @returns the {@link DetachedField} which contains the path.
  */
@@ -277,3 +277,15 @@ export function getDetachedFieldContainingPath(path: UpPath): DetachedField {
 	}
 	return keyAsDetachedField(path.parentField);
 }
+
+/**
+ * Returns the field key for the root field.
+ * @param path - the path you want to check.
+ * @returns the {@link DetachedField} which contains the path.
+ */
+export function getDetachedFieldContainingFieldPath(path: FieldUpPath): DetachedField {
+	if (path.parent === undefined) {
+		return keyAsDetachedField(path.field);
+	}
+	return getDetachedFieldContainingPath(path.parent);
+}

package/src/core/tree/visitDelta.ts

@@ -166,7 +166,9 @@ function transferRoots(
 	refreshers: NestedMap<Major, Minor, ITreeCursorSynchronous>,
 	revision?: RevisionTag,
 ): void {
-	type AtomizedNodeRename = Omit<Delta.DetachedNodeRename, "count">;
+	type AtomizedNodeRename = Omit<Delta.DetachedNodeRename, "count"> & {
+		isAttachable?: boolean;
+	};
 	let nextBatch = rootTransfers.flatMap(({ oldId, newId, count }) => {
 		const atomized: AtomizedNodeRename[] = [];
 		// It's possible for a detached node to be revived transiently such that it ends up back in the same detached field.
@@ -176,7 +178,12 @@ function transferRoots(
 		// This if statement prevents that from happening.
 		if (!areDetachedNodeIdsEqual(oldId, newId)) {
 			for (let i = 0; i < count; i += 1) {
-				atomized.push({ oldId: offsetDetachId(oldId, i), newId: offsetDetachId(newId, i) });
+				const source = detachedFieldIndex.isAttachable(offsetDetachId(oldId, i));
+				atomized.push({
+					oldId: offsetDetachId(oldId, i),
+					newId: offsetDetachId(newId, i),
+					isAttachable: source,
+				});
 			}
 		}
 		return atomized;
@@ -184,30 +191,29 @@ function transferRoots(
 	while (nextBatch.length > 0) {
 		const delayed: AtomizedNodeRename[] = [];
 		const priorSize = nextBatch.length;
-		for (const { oldId, newId } of nextBatch) {
+		for (const { oldId, newId, isAttachable } of nextBatch) {
 			let oldRootId = detachedFieldIndex.tryGetEntry(oldId);
 			if (oldRootId === undefined) {
 				const tree = tryGetFromNestedMap(refreshers, oldId.major, oldId.minor);
 				if (tree !== undefined) {
-					buildTrees(oldId, [tree], detachedFieldIndex, revision, visitor);
+					buildTrees(oldId, [tree], detachedFieldIndex, revision, false, visitor);
 					oldRootId = detachedFieldIndex.getEntry(oldId);
 				}
 			}
 			if (oldRootId === undefined) {
 				// The source field is not populated.
 				// This can happen when another rename needs to be performed first.
-				delayed.push({ oldId, newId });
+				delayed.push({ oldId, newId, isAttachable });
 				continue;
 			}
 			let newRootId = detachedFieldIndex.tryGetEntry(newId);
 			if (newRootId !== undefined) {
 				// The destination field is already occupied.
 				// This can happen when another rename needs to be performed first.
-				delayed.push({ oldId, newId });
+				delayed.push({ oldId, newId, isAttachable });
 				continue;
 			}
-			// eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- intentional behavior
-			newRootId = detachedFieldIndex.createEntry(newId, revision);
+			newRootId = detachedFieldIndex.createEntry(newId, revision, isAttachable);
 			const fields = mapToUpdate.get(oldRootId);
 			if (fields !== undefined) {
 				mapToUpdate.delete(oldRootId);
@@ -413,7 +419,11 @@ function detachPass(
 		if (mark.detach !== undefined) {
 			for (let i = 0; i < mark.count; i += 1) {
 				const id = offsetDetachId(mark.detach, i);
-				const root = config.detachedFieldIndex.createEntry(id, config.latestRevision);
+				const root = config.detachedFieldIndex.createEntry(
+					id,
+					config.latestRevision,
+					fieldChanges.allowReattach,
+				);
 				if (mark.fields !== undefined) {
 					config.attachPassRoots.set(root, mark.fields);
 				}
@@ -432,13 +442,14 @@ function buildTrees(
 	trees: readonly ITreeCursorSynchronous[],
 	detachedFieldIndex: DetachedFieldIndex,
 	latestRevision: RevisionTag | undefined,
+	isAttachable: boolean,
 	visitor: DeltaVisitor,
 ): void {
 	for (const [i, tree] of trees.entries()) {
 		const offsettedId = offsetDetachId(id, i);
 		let root = detachedFieldIndex.tryGetEntry(offsettedId);
 		assert(root === undefined, 0x929 /* Unable to build tree that already exists */);
-		root = detachedFieldIndex.createEntry(offsettedId, latestRevision);
+		root = detachedFieldIndex.createEntry(offsettedId, latestRevision, isAttachable);
 		const field = detachedFieldIndex.toFieldKey(root);
 		visitor.create([tree], field);
 	}
@@ -456,6 +467,7 @@ function processBuilds(
 				nodeCursorsFromChunk(trees),
 				config.detachedFieldIndex,
 				config.latestRevision,
+				true,
 				visitor,
 			);
 		}
@@ -473,7 +485,14 @@ function processGlobal(
 			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);
+				buildTrees(
+					id,
+					[tree],
+					config.detachedFieldIndex,
+					config.latestRevision,
+					false,
+					visitor,
+				);
 				root = config.detachedFieldIndex.getEntry(id);
 			}
 			// the revision is updated for any refresher data included in the delta that is used
@@ -529,6 +548,7 @@ function attachPass(
 						[tree],
 						config.detachedFieldIndex,
 						config.latestRevision,
+						false,
 						visitor,
 					);
 					sourceRoot = config.detachedFieldIndex.getEntry(offsetAttachId);

package/src/feature-libraries/changeAtomIdBTree.ts

@@ -4,13 +4,19 @@
  */
 
 import {
+	subtractChangeAtomIds,
 	compareChangesetLocalIds,
 	comparePartialRevisions,
 	type ChangeAtomId,
 	type ChangesetLocalId,
 	type RevisionTag,
 } from "../core/index.js";
-import { createTupleComparator, newTupleBTree, type TupleBTree } from "../util/index.js";
+import {
+	createTupleComparator,
+	newTupleBTree,
+	type RangeQueryResult,
+	type TupleBTree,
+} from "../util/index.js";
 
 /**
  * A BTree which uses ChangeAtomId flattened into a tuple as the key.
@@ -42,6 +48,25 @@ export function setInChangeAtomIdMap<T>(
 	map: ChangeAtomIdBTree<T>,
 	id: ChangeAtomId,
 	value: T,
-): void {
-	map.set([id.revision, id.localId], value);
+): boolean {
+	return map.set([id.revision, id.localId], value);
+}
+
+export function rangeQueryChangeAtomIdMap<T>(
+	map: ChangeAtomIdBTree<T>,
+	id: ChangeAtomId,
+	count: number,
+): RangeQueryResult<T | undefined> {
+	const pair = map.getPairOrNextHigher([id.revision, id.localId]);
+	if (pair === undefined) {
+		return { value: undefined, length: count };
+	}
+
+	const [[revision, localId], value] = pair;
+	const lengthBefore = subtractChangeAtomIds({ revision, localId }, id);
+	if (lengthBefore === 0) {
+		return { value, length: 1 };
+	}
+
+	return { value: undefined, length: Math.min(lengthBefore, count) };
 }