@fluidframework/tree 2.1.0-281041 → 2.2.0

package/src/core/tree/detachedFieldIndexTypes.ts

@@ -3,15 +3,50 @@
  * Licensed under the MIT License.
  */
 
-import type { NestedMap } from "../../util/index.js";
+import type { Brand, ReadonlyNestedMap } from "../../util/index.js";
 import type { RevisionTag } from "../rebase/index.js";
 
-import type { ForestRootId } from "./detachedFieldIndex.js";
-
 export type Major = RevisionTag | undefined;
 export type Minor = number;
 
 export interface DetachedFieldSummaryData {
-	data: NestedMap<Major, Minor, ForestRootId>;
-	maxId: ForestRootId;
+	readonly data: ReadonlyNestedMap<Major, Minor, DetachedField>;
+	readonly maxId: ForestRootId;
+}
+
+/**
+ * ID used to create a detached field key for a removed subtree.
+ *
+ * TODO: Move to Forest once forests can support multiple roots.
+ */
+export type ForestRootId = Brand<number, "tree.ForestRootId">;
+
+/**
+ * A field that is detached from the main document tree.
+ */
+export interface DetachedField {
+	/**
+	 * The atomic ID that the `DetachedFieldIndex` uses to uniquely identify the first (and only) root in the field.
+	 * This ID is scoped to the specific `DetachedFieldIndex` from witch this object was retrieved.
+	 *
+	 * The current implementation only supports a single root per field.
+	 * This will be changed in the future for performance reasons.
+	 */
+	readonly root: ForestRootId;
+	/**
+	 * The revision that last detached the root node or modified its contents (including its descendant's contents).
+	 *
+	 * Once this revision is trimmed from the ancestry on which a `TreeCheckout` is moored,
+	 * the contents of the associated subtree (and the very fact of its past existence) can be erased.
+	 *
+	 * @remarks
+	 * undefined revisions are tolerated but any roots not associated with a revision must be disposed manually.
+	 * Current usages of undefined are:
+	 * - When loading a {@link DetachedFieldIndex} from a snapshot,
+	 * until {@link DetachedFieldIndex.setRevisionsForLoadedData} is called.
+	 * - When applying a rollback changeset.
+	 * This only occurs within the context of {@link DefaultResubmitMachine} whose repair data is GC-ed when its
+	 * `DetachedField` and `Forest` are GC-ed.
+	 */
+	readonly latestRelevantRevision?: RevisionTag;
 }

package/src/core/tree/index.ts

@@ -43,7 +43,7 @@ export type {
 	DetachedNodeRename as DeltaDetachedNodeRename,
 	FieldChanges as DeltaFieldChanges,
 } from "./delta.js";
-export type { MapTree } from "./mapTree.js";
+export { type MapTree, type ExclusiveMapTree, deepCopyMapTree } from "./mapTree.js";
 export {
 	clonePath,
 	topDownPath,
@@ -110,4 +110,5 @@ export {
 	emptyDelta,
 } from "./deltaUtil.js";
 
-export { DetachedFieldIndex, type ForestRootId } from "./detachedFieldIndex.js";
+export { DetachedFieldIndex } from "./detachedFieldIndex.js";
+export { type ForestRootId } from "./detachedFieldIndexTypes.js";

package/src/core/tree/mapTree.ts

@@ -8,14 +8,55 @@ import type { FieldKey } from "../schema-stored/index.js";
 import type { NodeData } from "./types.js";
 
 /**
- * This modules provides a simple in memory tree format.
+ * This module provides a simple in-memory tree format.
  */
 
 /**
- * Simple in memory tree representation based on Maps.
- * MapTrees should not store empty fields.
- * @internal
+ * Simple in-memory tree representation based on Maps.
+ * @remarks MapTrees should not store empty fields.
  */
 export interface MapTree extends NodeData {
 	readonly fields: ReadonlyMap<FieldKey, readonly MapTree[]>;
 }
+
+/**
+ * A {@link MapTree} which is owned by a single reference, and therefore allowed to be mutated.
+ *
+ * @remarks
+ * To ensure unexpected mutations, this object should have a single owner/context.
+ * Though this type does implement MapTree, it should not be used as a MapTree while it can possibly be mutated.
+ * If it is shared to other contexts, it should first be upcast to a {@link MapTree} and further mutations should be avoided.
+ */
+export interface ExclusiveMapTree extends NodeData, MapTree {
+	fields: Map<FieldKey, ExclusiveMapTree[]>;
+}
+
+/**
+ * Returns a deep copy of the given {@link MapTree}.
+ * @privateRemarks This is implemented iteratively (rather than recursively, which is much simpler)
+ * to avoid the possibility of a stack overflow for very deep trees.
+ */
+export function deepCopyMapTree(mapTree: MapTree): ExclusiveMapTree {
+	type Next = [fields: ExclusiveMapTree["fields"], sourceFields: MapTree["fields"]];
+	const rootFields: ExclusiveMapTree["fields"] = new Map();
+	const nexts: Next[] = [[rootFields, mapTree.fields]];
+	for (let next = nexts.pop(); next !== undefined; next = nexts.pop()) {
+		const [fields, sourceFields] = next;
+		for (const [key, field] of sourceFields) {
+			if (field.length > 0) {
+				const newField: ExclusiveMapTree[] = [];
+				for (const child of field) {
+					const childClone: ExclusiveMapTree = { ...child, fields: new Map() };
+					newField.push(childClone);
+					nexts.push([childClone.fields, child.fields]);
+				}
+				fields.set(key, newField);
+			}
+		}
+	}
+
+	return {
+		...mapTree,
+		fields: rootFields,
+	};
+}

package/src/core/tree/pathTree.ts

@@ -11,8 +11,6 @@ import { type DetachedField, keyAsDetachedField } from "./types.js";
 /**
  * Identical to {@link UpPath}, but a duplicate declaration is needed to make
  * the default type parameter compile.
- *
- * @internal
  */
 export type UpPathDefault = UpPath;
 
@@ -27,7 +25,6 @@ export type UpPathDefault = UpPath;
  *
  * UpPaths can be mutated over time and should be considered to be invalidated when any edits occurs:
  * Use of an UpPath that was acquired before the most recent edit is undefined behavior.
- * @internal
  */
 export interface UpPath<TParent = UpPathDefault> {
 	/**
@@ -49,7 +46,6 @@ export interface UpPath<TParent = UpPathDefault> {
  * Path from a field in the tree upward.
  *
  * See {@link UpPath}.
- * @internal
  */
 export interface FieldUpPath<TUpPath extends UpPath = UpPath> {
 	/**
@@ -68,13 +64,11 @@ export interface FieldUpPath<TUpPath extends UpPath = UpPath> {
  * A range of nodes in a detached field.
  * Unlike RangeUpPath, such ranges are generated by create and detach operations,
  * as well as consumed by destroy and attach operations.
- * @internal
  */
 export type DetachedRangeUpPath = Brand<Omit<RangeUpPath, "parent">, "DetachedRangeUpPath">;
 
 /**
  * Delimits the extend of a range.
- * @internal
  */
 export interface Range {
 	/**
@@ -92,7 +86,6 @@ export interface Range {
 /**
  * A possibly empty range of nodes in a field.
  * This object only characterizes the location of the range, it does not own/contain the nodes in the range.
- * @internal
  */
 export interface RangeUpPath<TUpPath extends UpPath = UpPath>
 	extends FieldUpPath<TUpPath>,
@@ -100,7 +93,6 @@ export interface RangeUpPath<TUpPath extends UpPath = UpPath>
 
 /**
  * A place in a field.
- * @internal
  */
 export interface PlaceUpPath<TUpPath extends UpPath = UpPath> extends FieldUpPath<TUpPath> {
 	/**
@@ -111,21 +103,18 @@ export interface PlaceUpPath<TUpPath extends UpPath = UpPath> extends FieldUpPat
 
 /**
  * A place in a detached field.
- * @internal
  */
 export type DetachedPlaceUpPath = Brand<Omit<PlaceUpPath, "parent">, "DetachedRangeUpPath">;
 
 /**
  * Indicates the index of a node in a field.
  * Zero indicates the first node in a field.
- * @internal
  */
 export type NodeIndex = number;
 
 /**
  * Indicates a place between nodes in a field or at the extremity of a field.
  * Zero indicates the place at the start of the field (before the first node if any).
- * @internal
  */
 export type PlaceIndex = number;
 

package/src/core/tree/treeTextFormat.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { fail } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type { NodeData } from "./types.js";
@@ -94,7 +95,7 @@ export function getGenericTreeField<T>(
 
 	// Do not just read field and check for undefined: see warning on FieldMapObject.
 	if (Object.prototype.hasOwnProperty.call(children, key)) {
-		return children[key];
+		return children[key] ?? fail("This wont be undefined due to the check above");
 	}
 	// Handle missing field:
 	if (createIfMissing === false) {
@@ -169,7 +170,7 @@ export function genericTreeDeleteIfEmpty<T>(
 ): void {
 	const children = getGenericTreeFieldMap(node, false);
 	if (Object.prototype.hasOwnProperty.call(children, key)) {
-		if (children[key].length === 0) {
+		if (children[key]?.length === 0) {
 			// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
 			delete children[key];
 			if (removeMapObject) {

package/src/core/tree/types.ts

@@ -19,7 +19,6 @@ import type {
 } from "../schema-stored/index.js";
 
 /**
- * @internal
  */
 export type TreeType = TreeNodeSchemaIdentifier;
 
@@ -42,19 +41,15 @@ export const EmptyKey: FieldKey = brand("");
  * FieldKey to use for the root of documents in places that need to refer to detached sequences or the root.
  * TODO: if we do want to standardize on a single value for this,
  * it likely should be namespaced or a UUID to avoid risk of collisions.
- * @internal
  */
 export const rootFieldKey: FieldKey = brand("rootFieldKey");
 
 /**
- * @internal
  */
 export const rootField = keyAsDetachedField(rootFieldKey);
 
 /**
  * Location of a tree relative to is parent container (which can be a tree or forest).
- *
- * @internal
  */
 export interface ChildLocation {
 	readonly container: ChildCollection;
@@ -63,7 +58,6 @@ export interface ChildLocation {
 
 /**
  * Wrapper around DetachedField that can be detected at runtime.
- * @internal
  */
 export interface RootField {
 	readonly key: DetachedField;
@@ -71,7 +65,6 @@ export interface RootField {
 
 /**
  * Identifier for a child collection, either on a node/tree or at the root of a forest.
- * @internal
  */
 export type ChildCollection = FieldKey | RootField;
 
@@ -87,7 +80,6 @@ export type ChildCollection = FieldKey | RootField;
  *
  * In some APIs DetachedFields are used as FieldKeys on a special implicit root node
  * to simplify the APIs and implementation.
- * @internal
  */
 export interface DetachedField extends Opaque<Brand<string, "tree.DetachedField">> {}
 
@@ -96,7 +88,6 @@ export interface DetachedField extends Opaque<Brand<string, "tree.DetachedField"
  * This maps detached field to field keys for thus use.
  *
  * @returns `field` as a {@link FieldKey} usable on a special root node serving as a parent of detached fields.
- * @internal
  */
 export function detachedFieldAsKey(field: DetachedField): FieldKey {
 	return brand(extractFromOpaque(field));
@@ -106,7 +97,6 @@ export function detachedFieldAsKey(field: DetachedField): FieldKey {
  * The inverse of {@link detachedFieldAsKey}.
  * Thus must only be used on {@link FieldKey}s which were produced via {@link detachedFieldAsKey},
  * and with the same scope (ex: forest) as the detachedFieldAsKey was originally from.
- * @internal
  */
 export function keyAsDetachedField(key: FieldKey): DetachedField {
 	return brand(key);
@@ -116,7 +106,6 @@ export function keyAsDetachedField(key: FieldKey): DetachedField {
  * TODO: integrate this into Schema. Decide how to persist them (need stable Id?). Maybe allow updating field kinds?.
  * TODO: make families of changes per field kind. Build editing APIs from that.
  * TODO: factor ChangeRebaser implementations to support adding new field kinds.
- * @internal
  */
 export interface FieldKind {
 	readonly name: string;

package/src/core/tree/visitDelta.ts

@@ -21,9 +21,10 @@ import {
 	isReplaceMark,
 	offsetDetachId,
 } from "./deltaUtil.js";
-import type { DetachedFieldIndex, ForestRootId } from "./detachedFieldIndex.js";
-import type { Major, Minor } from "./detachedFieldIndexTypes.js";
+import type { DetachedFieldIndex } from "./detachedFieldIndex.js";
+import type { ForestRootId, Major, Minor } from "./detachedFieldIndexTypes.js";
 import type { NodeIndex, PlaceIndex, Range } from "./pathTree.js";
+import type { RevisionTag } from "../index.js";
 
 /**
  * Implementation notes:
@@ -74,11 +75,13 @@ import type { NodeIndex, PlaceIndex, Range } from "./pathTree.js";
  * @param delta - The delta to be crawled.
  * @param visitor - The object to notify of the changes encountered.
  * @param detachedFieldIndex - Index responsible for keeping track of the existing detached fields.
+ * @param latestRevision - The latest revision tag associated with this delta.
  */
 export function visitDelta(
 	delta: Delta.Root,
 	visitor: DeltaVisitor,
 	detachedFieldIndex: DetachedFieldIndex,
+	latestRevision: RevisionTag | undefined,
 ): void {
 	const detachPassRoots: Map<ForestRootId, Delta.FieldMap> = new Map();
 	const attachPassRoots: Map<ForestRootId, Delta.FieldMap> = new Map();
@@ -93,6 +96,7 @@ export function visitDelta(
 	});
 	const detachConfig: PassConfig = {
 		func: detachPass,
+		latestRevision,
 		refreshers,
 		detachedFieldIndex,
 		detachPassRoots,
@@ -103,9 +107,17 @@ export function visitDelta(
 	processBuilds(delta.build, detachConfig, visitor);
 	visitFieldMarks(delta.fields, visitor, detachConfig);
 	fixedPointVisitOfRoots(visitor, detachPassRoots, detachConfig);
-	transferRoots(rootTransfers, attachPassRoots, detachedFieldIndex, visitor);
+	transferRoots(
+		rootTransfers,
+		attachPassRoots,
+		detachedFieldIndex,
+		visitor,
+		refreshers,
+		latestRevision,
+	);
 	const attachConfig: PassConfig = {
 		func: attachPass,
+		latestRevision,
 		refreshers,
 		detachedFieldIndex,
 		detachPassRoots,
@@ -154,6 +166,10 @@ function fixedPointVisitOfRoots(
 
 /**
  * Transfers roots from one detached field to another.
+ * This occurs in the following circumstances:
+ * - A changeset moves then removes a node
+ * - A changeset restores then moves a node
+ * - A changeset restores then removes a node
  * TODO#5481: update the DetachedFieldIndex instead of moving the nodes around.
  *
  * @param rootTransfers - The transfers to perform.
@@ -166,6 +182,8 @@ function transferRoots(
 	mapToUpdate: Map<ForestRootId, unknown>,
 	detachedFieldIndex: DetachedFieldIndex,
 	visitor: DeltaVisitor,
+	refreshers: NestedMap<Major, Minor, ITreeCursorSynchronous>,
+	revision?: RevisionTag,
 ): void {
 	type AtomizedNodeRename = Omit<Delta.DetachedNodeRename, "count">;
 	let nextBatch = rootTransfers.flatMap(({ oldId, newId, count }) => {
@@ -186,7 +204,14 @@ function transferRoots(
 		const delayed: AtomizedNodeRename[] = [];
 		const priorSize = nextBatch.length;
 		for (const { oldId, newId } of nextBatch) {
-			const oldRootId = detachedFieldIndex.tryGetEntry(oldId);
+			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);
+					oldRootId = detachedFieldIndex.getEntry(oldId);
+				}
+			}
 			if (oldRootId === undefined) {
 				// The source field is not populated.
 				// This can happen when another rename needs to be performed first.
@@ -200,7 +225,7 @@ function transferRoots(
 				delayed.push({ oldId, newId });
 				continue;
 			}
-			newRootId = detachedFieldIndex.createEntry(newId);
+			newRootId = detachedFieldIndex.createEntry(newId, revision);
 			const fields = mapToUpdate.get(oldRootId);
 			if (fields !== undefined) {
 				mapToUpdate.delete(oldRootId);
@@ -221,7 +246,6 @@ function transferRoots(
 /**
  * Visitor for changes in a delta.
  * Must be freed after use.
- * @internal
  */
 export interface DeltaVisitor {
 	/**
@@ -311,6 +335,13 @@ export interface DeltaVisitor {
 
 interface PassConfig {
 	readonly func: Pass;
+
+	/**
+	 * The latest revision tag associated with the given delta. This is used to keep track
+	 * of when repair data should be garbage collected.
+	 */
+	readonly latestRevision: RevisionTag | undefined;
+
 	readonly detachedFieldIndex: DetachedFieldIndex;
 	/**
 	 * A mapping between forest root id and trees that represent refresher data. Each entry is only
@@ -394,9 +425,11 @@ function detachPass(
 			if (root === undefined) {
 				const tree = tryGetFromNestedMap(config.refreshers, id.major, id.minor);
 				assert(tree !== undefined, 0x928 /* refresher data not found */);
-				buildTrees(id, [tree], config, visitor);
+				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);
 		}
@@ -416,10 +449,9 @@ function detachPass(
 			}
 			if (isDetachMark(mark)) {
 				for (let i = 0; i < mark.count; i += 1) {
-					const root = config.detachedFieldIndex.createEntry(
-						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-						offsetDetachId(mark.detach!, i),
-					);
+					// 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);
 					}
@@ -436,16 +468,17 @@ function detachPass(
 function buildTrees(
 	id: Delta.DetachedNodeId,
 	trees: readonly ITreeCursorSynchronous[],
-	config: PassConfig,
+	detachedFieldIndex: DetachedFieldIndex,
+	latestRevision: RevisionTag | undefined,
 	visitor: DeltaVisitor,
 ): void {
-	for (let i = 0; i < trees.length; i += 1) {
+	for (const [i, tree] of trees.entries()) {
 		const offsettedId = offsetDetachId(id, i);
-		let root = config.detachedFieldIndex.tryGetEntry(offsettedId);
+		let root = detachedFieldIndex.tryGetEntry(offsettedId);
 		assert(root === undefined, 0x929 /* Unable to build tree that already exists */);
-		root = config.detachedFieldIndex.createEntry(offsettedId);
-		const field = config.detachedFieldIndex.toFieldKey(root);
-		visitor.create([trees[i]], field);
+		root = detachedFieldIndex.createEntry(offsettedId, latestRevision);
+		const field = detachedFieldIndex.toFieldKey(root);
+		visitor.create([tree], field);
 	}
 }
 
@@ -456,7 +489,7 @@ function processBuilds(
 ): void {
 	if (builds !== undefined) {
 		for (const { id, trees } of builds) {
-			buildTrees(id, trees, config, visitor);
+			buildTrees(id, trees, config.detachedFieldIndex, config.latestRevision, visitor);
 		}
 	}
 }
@@ -496,7 +529,13 @@ function attachPass(
 							offsetAttachId.minor,
 						);
 						assert(tree !== undefined, 0x92a /* refresher data not found */);
-						buildTrees(offsetAttachId, [tree], config, visitor);
+						buildTrees(
+							offsetAttachId,
+							[tree],
+							config.detachedFieldIndex,
+							config.latestRevision,
+							visitor,
+						);
 						sourceRoot = config.detachedFieldIndex.getEntry(offsetAttachId);
 					}
 					const sourceField = config.detachedFieldIndex.toFieldKey(sourceRoot);
@@ -505,6 +544,7 @@ function attachPass(
 						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(

package/src/core/tree/visitPath.ts

@@ -17,8 +17,6 @@ import type {
  *
  * For any of these events, the paths are guaranteed to be valid at the time of the event,
  * and it is valid to read from the Forest at that path.
- *
- * @internal
  */
 export interface PathVisitor {
 	/**

package/src/core/tree/visitorUtils.ts

@@ -7,11 +7,12 @@ import { assert } from "@fluidframework/core-utils/internal";
 
 import type { ICodecOptions } from "../../codec/index.js";
 import { type IdAllocator, idAllocatorFromMaxId } from "../../util/index.js";
-import type { RevisionTagCodec } from "../rebase/index.js";
+import type { RevisionTag, RevisionTagCodec } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type { ProtoNodes, Root } from "./delta.js";
-import { DetachedFieldIndex, type ForestRootId } from "./detachedFieldIndex.js";
+import { DetachedFieldIndex } from "./detachedFieldIndex.js";
+import type { ForestRootId } from "./detachedFieldIndexTypes.js";
 import type { PlaceIndex, Range } from "./pathTree.js";
 import { type DeltaVisitor, visitDelta } from "./visitDelta.js";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
@@ -33,21 +34,23 @@ export function makeDetachedFieldIndex(
 
 export function applyDelta(
 	delta: Root,
+	latestRevision: RevisionTag | undefined,
 	deltaProcessor: { acquireVisitor: () => DeltaVisitor },
 	detachedFieldIndex: DetachedFieldIndex,
 ): void {
 	const visitor = deltaProcessor.acquireVisitor();
-	visitDelta(delta, visitor, detachedFieldIndex);
+	visitDelta(delta, visitor, detachedFieldIndex, latestRevision);
 	visitor.free();
 }
 
 export function announceDelta(
 	delta: Root,
+	latestRevision: RevisionTag | undefined,
 	deltaProcessor: { acquireVisitor: () => DeltaVisitor & AnnouncedVisitor },
 	detachedFieldIndex: DetachedFieldIndex,
 ): void {
 	const visitor = deltaProcessor.acquireVisitor();
-	visitDelta(delta, combineVisitors([visitor], [visitor]), detachedFieldIndex);
+	visitDelta(delta, combineVisitors([visitor], [visitor]), detachedFieldIndex, latestRevision);
 	visitor.free();
 }
 
@@ -112,7 +115,6 @@ export function combineVisitors(
 /**
  * Visitor that is notified of changes before, after, and when changes are made.
  * Must be freed after use.
- * @internal
  */
 export interface AnnouncedVisitor extends DeltaVisitor {
 	/**

package/src/domains/index.ts

@@ -11,6 +11,9 @@ export {
 	jsonRoot,
 	jsonSchema,
 	singleJsonCursor,
+	typedJsonCursor,
+	type TypedJsonCompatible,
+	type TypedJsonCompatibleObject,
 } from "./json/index.js";
 
 export { leaf } from "./leafDomain.js";

package/src/domains/json/index.ts

@@ -3,5 +3,11 @@
  * Licensed under the MIT License.
  */
 
-export { singleJsonCursor, cursorToJsonObject } from "./jsonCursor.js";
+export {
+	singleJsonCursor,
+	cursorToJsonObject,
+	typedJsonCursor,
+	type TypedJsonCompatible,
+	type TypedJsonCompatibleObject,
+} from "./jsonCursor.js";
 export { jsonSchema, jsonObject, jsonArray, jsonRoot } from "./jsonDomainSchema.js";