@fluidframework/tree 2.1.1 → 2.2.1

package/src/feature-libraries/flex-map-tree/mapTreeNode.ts

@@ -3,10 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import {
 	type AnchorNode,
 	EmptyKey,
+	type ExclusiveMapTree,
 	type FieldKey,
 	type FieldUpPath,
 	type MapTree,
@@ -14,12 +15,10 @@ import {
 	type TreeValue,
 	type Value,
 } from "../../core/index.js";
-import { brand, fail, mapIterable } from "../../util/index.js";
+import { brand, fail, getOrCreate, mapIterable } from "../../util/index.js";
 import {
-	type FlexTreeContext,
 	FlexTreeEntityKind,
 	type FlexTreeField,
-	type FlexTreeFieldNode,
 	type FlexTreeLeafNode,
 	type FlexTreeMapNode,
 	type FlexTreeNode,
@@ -31,20 +30,16 @@ import {
 	type FlexTreeTypedNodeUnion,
 	type FlexTreeUnboxField,
 	type FlexTreeUnboxNodeUnion,
-	type FlexibleFieldContent,
-	type FlexibleNodeSubSequence,
 	flexTreeMarker,
 	indexForAt,
 } from "../flex-tree/index.js";
 import {
 	type FlexAllowedTypes,
-	type FlexFieldNodeSchema,
 	FlexFieldSchema,
 	type FlexMapNodeSchema,
 	type FlexTreeNodeSchema,
 	type LeafNodeSchema,
 	isLazy,
-	schemaIsFieldNode,
 	schemaIsLeaf,
 	schemaIsMap,
 	schemaIsObjectNode,
@@ -72,9 +67,38 @@ export function isMapTreeNode(flexNode: FlexTreeNode): flexNode is MapTreeNode {
 	return flexNode instanceof EagerMapTreeNode;
 }
 
+/**
+ * Checks if the given {@link FlexTreeField} is a {@link MapTreeSequenceField}.
+ */
+export function isMapTreeSequenceField<T extends FlexAllowedTypes>(
+	field: FlexTreeSequenceField<T> | FlexTreeField,
+): field is MapTreeSequenceField<T> {
+	return field instanceof EagerMapTreeSequenceField;
+}
+
+/**
+ * An unhydrated {@link FlexTreeSequenceField}, which has additional editing capabilities.
+ * @remarks When doing a removal edit, a {@link MapTreeSequenceField}'s `editor` returns ownership of the removed {@link ExclusiveMapTree}s to the caller.
+ */
+export interface MapTreeSequenceField<T extends FlexAllowedTypes>
+	extends FlexTreeSequenceField<T> {
+	readonly editor: MapTreeSequenceFieldEditBuilder;
+}
+
+interface MapTreeSequenceFieldEditBuilder
+	extends SequenceFieldEditBuilder<ExclusiveMapTree[]> {
+	/**
+	 * Issues a change which removes `count` elements starting at the given `index`.
+	 * @param index - The index of the first removed element.
+	 * @param count - The number of elements to remove.
+	 * @returns the MapTrees that were removed
+	 */
+	remove(index: number, count: number): ExclusiveMapTree[];
+}
+
 /** A node's parent field and its index in that field */
 interface LocationInField {
-	readonly parent: MapTreeField<FlexAllowedTypes>;
+	readonly parent: MapTreeField;
 	readonly index: number;
 }
 
@@ -99,8 +123,8 @@ export class EagerMapTreeNode<TSchema extends FlexTreeNodeSchema> implements Map
 	public constructor(
 		public readonly schema: TSchema,
 		/** The underlying {@link MapTree} that this `MapTreeNode` reads its data from */
-		public readonly mapTree: MapTree,
-		private location: LocationInField | undefined,
+		public readonly mapTree: ExclusiveMapTree,
+		private location = unparentedLocation,
 	) {
 		assert(!nodeCache.has(mapTree), 0x98b /* A node already exists for the given MapTree */);
 		nodeCache.set(mapTree, this);
@@ -121,28 +145,35 @@ export class EagerMapTreeNode<TSchema extends FlexTreeNodeSchema> implements Map
 
 	/**
 	 * Set this node's parentage (see {@link FlexTreeNode.parentField}).
-	 * @remarks A node may only be adopted to a new parent one time, and only if it was not constructed with a parent.
+	 * @remarks The node may be given a parent if it has none, or may have its parent removed (by passing `undefined`).
+	 * However, a node with a parent may not be directly re-assigned a different parent.
+	 * That likely indicates either an attempted multi-parenting or an attempt to "move" the node, neither of which are supported.
+	 * Removing a node's parent twice in a row is also not supported, as it likely indicates a bug.
 	 */
-	public adopt(parent: MapTreeField<FlexAllowedTypes>, index: number): void {
-		assert(
-			this.location === undefined,
-			0x98c /* Node may not be adopted if it already has a parent */,
-		);
-		this.location = { parent, index };
+	public adoptBy(parent: undefined): void;
+	public adoptBy(parent: MapTreeField, index: number): void;
+	public adoptBy(parent: MapTreeField | undefined, index?: number): void {
+		if (parent !== undefined) {
+			assert(
+				this.location === unparentedLocation,
+				0x98c /* Node may not be adopted if it already has a parent */,
+			);
+			assert(index !== undefined, 0xa08 /* Expected index */);
+			this.location = { parent, index };
+		} else {
+			assert(
+				this.location !== unparentedLocation,
+				0xa09 /* Node may not be un-adopted if it does not have a parent */,
+			);
+			this.location = unparentedLocation;
+		}
 	}
 
 	/**
 	 * The field this tree is in, and the index within that field.
-	 * @remarks If this node is unparented, this method will return the special {@link rootMapTreeField} as the parent.
+	 * @remarks If this node is unparented, this method will return the special {@link unparentedLocation} as the parent.
 	 */
 	public get parentField(): LocationInField {
-		if (this.location === undefined) {
-			return {
-				parent: rootMapTreeField,
-				index: -1,
-			};
-		}
-
 		return this.location;
 	}
 
@@ -152,23 +183,22 @@ export class EagerMapTreeNode<TSchema extends FlexTreeNodeSchema> implements Map
 		return (schema as unknown) === this.schema;
 	}
 
-	public tryGetField(key: FieldKey): MapTreeField<FlexAllowedTypes> | undefined {
+	public tryGetField(key: FieldKey): EagerMapTreeField<FlexAllowedTypes> | undefined {
 		const field = this.mapTree.fields.get(key);
 		// Only return the field if it is not empty, in order to fulfill the contract of `tryGetField`.
 		if (field !== undefined && field.length > 0) {
-			return getOrCreateField(this, key, field, this.schema.getFieldSchema(key));
+			return getOrCreateField(this, key, this.schema.getFieldSchema(key));
 		}
 	}
 
 	public getBoxed(key: string): FlexTreeField {
 		const fieldKey: FieldKey = brand(key);
-		const field = this.mapTree.fields.get(fieldKey) ?? [];
-		return getOrCreateField(this, fieldKey, field, this.schema.getFieldSchema(fieldKey));
+		return getOrCreateField(this, fieldKey, this.schema.getFieldSchema(fieldKey));
 	}
 
 	public boxedIterator(): IterableIterator<FlexTreeField> {
-		return mapIterable(this.mapTree.fields.entries(), ([key, field]) =>
-			getOrCreateField(this, key, field, this.schema.getFieldSchema(key)),
+		return mapIterable(this.mapTree.fields.entries(), ([key]) =>
+			getOrCreateField(this, key, this.schema.getFieldSchema(key)),
 		);
 	}
 
@@ -176,11 +206,7 @@ export class EagerMapTreeNode<TSchema extends FlexTreeNodeSchema> implements Map
 		return this.mapTree.value;
 	}
 
-	public get context(): FlexTreeContext {
-		// This API is relevant to `LazyTreeNode`s, but not `MapTreeNode`s.
-		// TODO: Refactor the FlexTreeNode interface so that stubbing this out isn't necessary.
-		return fail("MapTreeNode does not implement context");
-	}
+	public context = undefined;
 
 	public get anchorNode(): AnchorNode {
 		// This API is relevant to `LazyTreeNode`s, but not `MapTreeNode`s.
@@ -190,10 +216,10 @@ export class EagerMapTreeNode<TSchema extends FlexTreeNodeSchema> implements Map
 
 	private walkTree(): void {
 		for (const [key, mapTrees] of this.mapTree.fields) {
-			const field = getOrCreateField(this, key, mapTrees, this.schema.getFieldSchema(key));
+			const field = getOrCreateField(this, key, this.schema.getFieldSchema(key));
 			for (let index = 0; index < field.length; index++) {
 				const child = getOrCreateChild(
-					mapTrees[index],
+					mapTrees[index] ?? oob(),
 					this.schema.getFieldSchema(key).allowedTypes,
 					{ parent: field, index },
 				);
@@ -210,26 +236,6 @@ export class EagerMapTreeNode<TSchema extends FlexTreeNodeSchema> implements Map
 	}
 }
 
-/**
- * The implementation of a field node created by {@link getOrCreateNode}.
- */
-export class EagerMapTreeFieldNode<TSchema extends FlexFieldNodeSchema>
-	extends EagerMapTreeNode<TSchema>
-	implements FlexTreeFieldNode<TSchema>
-{
-	public get content(): FlexTreeUnboxField<TSchema["info"]> {
-		const field = this.tryGetField(EmptyKey);
-		if (field === undefined) {
-			return undefined as FlexTreeUnboxField<TSchema["info"]>;
-		}
-		return unboxedField(field, EmptyKey, this.mapTree, this);
-	}
-
-	public override getBoxed(key: string): FlexTreeTypedField<TSchema["info"]> {
-		return super.getBoxed(key) as FlexTreeTypedField<TSchema["info"]>;
-	}
-}
-
 /**
  * The implementation of a map node created by {@link getOrCreateNode}.
  */
@@ -237,22 +243,6 @@ export class EagerMapTreeMapNode<TSchema extends FlexMapNodeSchema>
 	extends EagerMapTreeNode<TSchema>
 	implements FlexTreeMapNode<TSchema>
 {
-	public get size(): number {
-		return this.mapTree.fields.size;
-	}
-
-	public has(key: string): boolean {
-		return this.tryGetField(brand(key)) !== undefined;
-	}
-
-	public get(key: string): FlexTreeUnboxField<TSchema["info"]> {
-		const field = this.tryGetField(brand(key));
-		if (field === undefined) {
-			return undefined as FlexTreeUnboxField<TSchema["info"]>;
-		}
-		return unboxedField(field, brand(key), this.mapTree, this);
-	}
-
 	public keys(): IterableIterator<FieldKey> {
 		return this.mapTree.fields.keys();
 	}
@@ -302,16 +292,6 @@ export class EagerMapTreeMapNode<TSchema extends FlexMapNodeSchema>
 		return super.getBoxed(key) as FlexTreeTypedField<TSchema["info"]>;
 	}
 
-	public set(key: string, value: FlexibleFieldContent<TSchema["info"]> | undefined): void {
-		// `MapTreeNode`s cannot be mutated
-		throw unsupportedUsageError("Setting a map entry");
-	}
-
-	public delete(key: string): void {
-		// `MapTreeNode`s cannot be mutated
-		throw unsupportedUsageError("Deleting a map entry");
-	}
-
 	public [Symbol.iterator](): IterableIterator<
 		[FieldKey, FlexTreeUnboxField<TSchema["info"], "notEmpty">]
 	> {
@@ -337,62 +317,73 @@ class EagerMapTreeLeafNode<TSchema extends LeafNodeSchema>
 // #region Fields
 
 /**
- * A special singleton that is the implicit parent field of all un-parented {@link EagerMapTreeNode}s.
+ * A readonly {@link FlexTreeField} which wraps an array of {@link MapTrees}.
+ * @remarks Reading data from the MapTreeField will read the corresponding data from the {@link MapTree}s.
+ * Create a `MapTreeField` by calling {@link getOrCreateField}.
+ */
+interface MapTreeField extends FlexTreeField {
+	readonly mapTrees: readonly MapTree[];
+}
+
+/**
+ * A special singleton that is the implicit {@link LocationInField} of all un-parented {@link EagerMapTreeNode}s.
  * @remarks This exists because {@link EagerMapTreeNode.parentField} must return a field.
  * If a {@link EagerMapTreeNode} is created without a parent, its {@link EagerMapTreeNode.parentField} property will point to this object.
  * However, this field cannot be used in any practical way because it is empty, i.e. it does not actually contain the children that claim to be parented under it.
  * It has the "empty" schema and it will always contain zero children if queried.
+ * Any nodes with this location will have a dummy parent index of `-1`.
  */
-export const rootMapTreeField: MapTreeField<FlexAllowedTypes> = {
-	[flexTreeMarker]: FlexTreeEntityKind.Field as const,
-	length: 0,
-	key: EmptyKey,
-	parent: undefined,
-	is<TSchema extends FlexFieldSchema>(schema: TSchema) {
-		return schema === (FlexFieldSchema.empty as FlexFieldSchema);
-	},
-	boxedIterator(): IterableIterator<FlexTreeNode> {
-		return [].values();
-	},
-	boxedAt(index: number): FlexTreeNode | undefined {
-		return undefined;
-	},
-	schema: FlexFieldSchema.empty,
-	get context(): FlexTreeContext {
-		return fail("MapTreeField does not implement context");
+const unparentedLocation: LocationInField = {
+	parent: {
+		[flexTreeMarker]: FlexTreeEntityKind.Field as const,
+		length: 0,
+		key: EmptyKey,
+		parent: undefined,
+		is<TSchema extends FlexFieldSchema>(schema: TSchema) {
+			return schema === (FlexFieldSchema.empty as FlexFieldSchema);
+		},
+		boxedIterator(): IterableIterator<FlexTreeNode> {
+			return [].values();
+		},
+		boxedAt(index: number): FlexTreeNode | undefined {
+			return undefined;
+		},
+		schema: FlexFieldSchema.empty,
+		context: undefined,
+		mapTrees: [],
 	},
-	mapTrees: [],
+	index: -1,
 };
 
-class MapTreeField<T extends FlexAllowedTypes> implements FlexTreeField {
+class EagerMapTreeField<T extends FlexAllowedTypes> implements MapTreeField {
 	public [flexTreeMarker] = FlexTreeEntityKind.Field as const;
 
 	public constructor(
 		public readonly schema: FlexFieldSchema<FlexFieldKind, T>,
 		public readonly key: FieldKey,
-		public readonly parent: FlexTreeNode | undefined,
-		public readonly mapTrees: readonly MapTree[],
+		public readonly parent: EagerMapTreeNode<FlexTreeNodeSchema>,
 	) {
-		assert(
-			!fieldCache.has(mapTrees),
-			0x990 /* A field already exists for the given MapTrees */,
-		);
-		fieldCache.set(mapTrees, this);
+		const fieldKeyCache = getFieldKeyCache(parent);
+		assert(!fieldKeyCache.has(key), 0x990 /* A field already exists for the given MapTrees */);
+		fieldKeyCache.set(key, this);
 
 		// When this field is created (which only happens one time, because it is cached), all the children become parented for the first time.
 		// "Adopt" each child by updating its parent information to point to this field.
-		for (let i = 0; i < mapTrees.length; i++) {
-			const mapTreeNodeChild = nodeCache.get(mapTrees[i]);
+		for (const [i, mapTree] of this.mapTrees.entries()) {
+			const mapTreeNodeChild = nodeCache.get(mapTree);
 			if (mapTreeNodeChild !== undefined) {
-				assert(
-					mapTreeNodeChild.parentField.parent === rootMapTreeField,
-					0x991 /* Node is already parented under a different field */,
-				);
-				mapTreeNodeChild.adopt(this, i);
+				if (mapTreeNodeChild.parentField !== unparentedLocation) {
+					throw new UsageError("A node may not be in more than one place in the tree");
+				}
+				mapTreeNodeChild.adoptBy(this, i);
 			}
 		}
 	}
 
+	public get mapTrees(): readonly ExclusiveMapTree[] {
+		return this.parent.mapTree.fields.get(this.key) ?? [];
+	}
+
 	public get length(): number {
 		return this.mapTrees.length;
 	}
@@ -429,47 +420,116 @@ class MapTreeField<T extends FlexAllowedTypes> implements FlexTreeField {
 		}
 	}
 
-	public get context(): FlexTreeContext {
-		return fail("MapTreeField does not implement context");
-	}
-}
+	public context: undefined;
 
-class MapTreeRequiredField<T extends FlexAllowedTypes>
-	extends MapTreeField<T>
-	implements FlexTreeRequiredField<T>
-{
-	public get content(): FlexTreeUnboxNodeUnion<T> {
-		return unboxedUnion(this.schema, this.mapTrees[0], { parent: this, index: 0 });
-	}
-	public set content(_: FlexTreeUnboxNodeUnion<T>) {
-		throw unsupportedUsageError("Setting an optional field");
+	/**
+	 * Mutate this field.
+	 * @param edit - A function which receives the current `MapTree`s that comprise the contents of the field so that it may be mutated.
+	 * The function may mutate the array in place or return a new array.
+	 * If a new array is returned then it will be used as the new contents of the field, otherwise the original array will be continue to be used.
+	 * @remarks All edits to the field (i.e. mutations of the field's MapTrees) should be directed through this function.
+	 * This function ensures that the parent MapTree has no empty fields (which is an invariant of `MapTree`) after the mutation.
+	 */
+	protected edit(edit: (mapTrees: ExclusiveMapTree[]) => void | ExclusiveMapTree[]): void {
+		const oldMapTrees = this.parent.mapTree.fields.get(this.key) ?? [];
+		const newMapTrees = edit(oldMapTrees) ?? oldMapTrees;
+		if (newMapTrees.length > 0) {
+			this.parent.mapTree.fields.set(this.key, newMapTrees);
+		} else {
+			this.parent.mapTree.fields.delete(this.key);
+		}
 	}
 }
 
-class MapTreeOptionalField<T extends FlexAllowedTypes>
-	extends MapTreeField<T>
+class EagerMapTreeOptionalField<T extends FlexAllowedTypes>
+	extends EagerMapTreeField<T>
 	implements FlexTreeOptionalField<T>
 {
+	public readonly editor = {
+		set: (newContent: ExclusiveMapTree | undefined): void => {
+			// If the new content is a MapTreeNode, it needs to have its parent pointer updated
+			if (newContent !== undefined) {
+				nodeCache.get(newContent)?.adoptBy(this, 0);
+			}
+			// If the old content is a MapTreeNode, it needs to have its parent pointer unset
+			const oldContent = this.mapTrees[0];
+			if (oldContent !== undefined) {
+				nodeCache.get(oldContent)?.adoptBy(undefined);
+			}
+
+			this.edit((mapTrees) => {
+				if (newContent !== undefined) {
+					mapTrees[0] = newContent;
+				} else {
+					mapTrees.length = 0;
+				}
+			});
+		},
+	};
+
 	public get content(): FlexTreeUnboxNodeUnion<T> | undefined {
-		return this.mapTrees.length > 0
-			? unboxedUnion(this.schema, this.mapTrees[0], { parent: this, index: 0 })
-			: undefined;
+		const value = this.mapTrees[0];
+		if (value !== undefined) {
+			return unboxedUnion(this.schema, value, {
+				parent: this,
+				index: 0,
+			});
+		}
+
+		return undefined;
 	}
-	public set content(_: FlexTreeUnboxNodeUnion<T> | undefined) {
-		throw unsupportedUsageError("Setting an optional field");
+}
+
+class EagerMapTreeRequiredField<T extends FlexAllowedTypes>
+	extends EagerMapTreeOptionalField<T>
+	implements FlexTreeRequiredField<T>
+{
+	public override get content(): FlexTreeUnboxNodeUnion<T> {
+		return super.content ?? fail("Expected EagerMapTree required field to have a value");
 	}
 }
 
-class MapTreeSequenceField<T extends FlexAllowedTypes>
-	extends MapTreeField<T>
+class EagerMapTreeSequenceField<T extends FlexAllowedTypes>
+	extends EagerMapTreeField<T>
 	implements FlexTreeSequenceField<T>
 {
+	public readonly editor: MapTreeSequenceFieldEditBuilder = {
+		insert: (index, newContent): void => {
+			for (let i = 0; i < newContent.length; i++) {
+				const c = newContent[i];
+				assert(c !== undefined, 0xa0a /* Unexpected sparse array content */);
+				nodeCache.get(c)?.adoptBy(this, index + i);
+			}
+			this.edit((mapTrees) => {
+				if (newContent.length < 1000) {
+					// For "smallish arrays" (`1000` is not empirically derived), the `splice` function is appropriate...
+					mapTrees.splice(index, 0, ...newContent);
+				} else {
+					// ...but we avoid using `splice` + spread for very large input arrays since there is a limit on how many elements can be spread (too many will overflow the stack).
+					return mapTrees.slice(0, index).concat(newContent, mapTrees.slice(index));
+				}
+			});
+		},
+		remove: (index, count): ExclusiveMapTree[] => {
+			for (let i = index; i < index + count; i++) {
+				const c = this.mapTrees[i];
+				assert(c !== undefined, 0xa0b /* Unexpected sparse array */);
+				nodeCache.get(c)?.adoptBy(undefined);
+			}
+			let removed: ExclusiveMapTree[] | undefined;
+			this.edit((mapTrees) => {
+				removed = mapTrees.splice(index, count);
+			});
+			return removed ?? fail("Expected removed to be set by edit");
+		},
+	};
+
 	public at(index: number): FlexTreeUnboxNodeUnion<T> | undefined {
 		const i = indexForAt(index, this.length);
 		if (i === undefined) {
 			return undefined;
 		}
-		return unboxedUnion(this.schema, this.mapTrees[i], { parent: this, index: i });
+		return unboxedUnion(this.schema, this.mapTrees[i] ?? oob(), { parent: this, index: i });
 	}
 	public map<U>(callbackfn: (value: FlexTreeUnboxNodeUnion<T>, index: number) => U): U[] {
 		return Array.from(this, callbackfn);
@@ -479,51 +539,13 @@ class MapTreeSequenceField<T extends FlexAllowedTypes>
 	}
 
 	public *[Symbol.iterator](): IterableIterator<FlexTreeUnboxNodeUnion<T>> {
-		for (let i = 0; i < this.mapTrees.length; i++) {
-			yield unboxedUnion(this.schema, this.mapTrees[i], { parent: this, index: i });
+		for (const [i, mapTree] of this.mapTrees.entries()) {
+			yield unboxedUnion(this.schema, mapTree, { parent: this, index: i });
 		}
 	}
 
-	public sequenceEditor(): SequenceFieldEditBuilder {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public insertAt(index: number, value: FlexibleNodeSubSequence<T>): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public insertAtStart(value: FlexibleNodeSubSequence<T>): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public insertAtEnd(value: FlexibleNodeSubSequence<T>): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public removeAt(index: number): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public moveToStart(sourceIndex: unknown, source?: unknown): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public moveToEnd(sourceIndex: unknown, source?: unknown): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public moveToIndex(index: unknown, sourceIndex: unknown, source?: unknown): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public moveRangeToStart(sourceStart: unknown, sourceEnd: unknown, source?: unknown): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public moveRangeToEnd(sourceStart: unknown, sourceEnd: unknown, source?: unknown): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
-	public moveRangeToIndex(
-		index: unknown,
-		sourceStart: unknown,
-		sourceEnd: unknown,
-		source?: unknown,
-	): void {
-		throw unsupportedUsageError("Editing a sequence");
-	}
 	public getFieldPath(): FieldUpPath {
-		throw unsupportedUsageError("Editing a sequence");
+		throw unsupportedUsageError("Editing an array");
 	}
 }
 
@@ -532,7 +554,16 @@ class MapTreeSequenceField<T extends FlexAllowedTypes>
 // #region Caching and unboxing utilities
 
 const nodeCache = new WeakMap<MapTree, EagerMapTreeNode<FlexTreeNodeSchema>>();
-const fieldCache = new WeakMap<readonly MapTree[], MapTreeField<FlexAllowedTypes>>();
+/** Node Parent -\> Field Key -\> Field */
+const fieldCache = new WeakMap<
+	MapTreeNode,
+	Map<FieldKey, EagerMapTreeField<FlexAllowedTypes>>
+>();
+function getFieldKeyCache(
+	parent: MapTreeNode,
+): WeakMap<FieldKey, EagerMapTreeField<FlexAllowedTypes>> {
+	return getOrCreate(fieldCache, parent, () => new Map());
+}
 
 /**
  * If there exists a {@link EagerMapTreeNode} for the given {@link MapTree}, returns it, otherwise returns `undefined`.
@@ -543,55 +574,21 @@ export function tryGetMapTreeNode(mapTree: MapTree): MapTreeNode | undefined {
 }
 
 /**
- * Create a {@link MapTreeNode} that wraps the given {@link MapTree}, or get the node that already exists for that {@link MapTree} if there is one.
+ * Create a {@link EagerMapTreeNode} that wraps the given {@link MapTree}, or get the node that already exists for that {@link MapTree} if there is one.
  * @param nodeSchema - the {@link FlexTreeNodeSchema | schema} that the node conforms to
  * @param mapTree - the {@link MapTree} containing the data for this node.
  * @remarks It must conform to the `nodeSchema`.
  */
 export function getOrCreateMapTreeNode(
 	nodeSchema: FlexTreeNodeSchema,
-	mapTree: MapTree,
-): MapTreeNode {
-	return getOrCreateNode(nodeSchema, mapTree);
-}
-
-/**
- * Create a {@link EagerMapTreeNode} that wraps the given {@link MapTree}, or get the node that already exists for that {@link MapTree} if there is one.
- * @param nodeSchema - the {@link FlexTreeNodeSchema | schema} that the node conforms to
- * @param mapTree - the {@link MapTree} containing the data for this node.
- * @remarks It must conform to the `nodeSchema`.
- * This function is exported for the purposes of unit testing.
- */
-export function getOrCreateNode<TSchema extends LeafNodeSchema>(
-	nodeSchema: TSchema,
-	mapTree: MapTree,
-): EagerMapTreeLeafNode<TSchema>;
-export function getOrCreateNode<TSchema extends FlexMapNodeSchema>(
-	nodeSchema: TSchema,
-	mapTree: MapTree,
-): EagerMapTreeMapNode<TSchema>;
-export function getOrCreateNode<TSchema extends FlexFieldNodeSchema>(
-	nodeSchema: TSchema,
-	mapTree: MapTree,
-): EagerMapTreeFieldNode<TSchema>;
-export function getOrCreateNode<TSchema extends FlexTreeNodeSchema>(
-	nodeSchema: TSchema,
-	mapTree: MapTree,
-): EagerMapTreeNode<TSchema>;
-export function getOrCreateNode<TSchema extends FlexTreeNodeSchema>(
-	nodeSchema: TSchema,
-	mapTree: MapTree,
-): EagerMapTreeNode<TSchema> {
-	const cached = tryGetMapTreeNode(mapTree);
-	if (cached !== undefined) {
-		return cached as EagerMapTreeNode<TSchema>;
-	}
-	return createNode(nodeSchema, mapTree, undefined);
+	mapTree: ExclusiveMapTree,
+): EagerMapTreeNode<FlexTreeNodeSchema> {
+	return nodeCache.get(mapTree) ?? createNode(nodeSchema, mapTree, undefined);
 }
 
 /** Helper for creating a `MapTreeNode` given the parent field (e.g. when "walking down") */
 function getOrCreateChild(
-	mapTree: MapTree,
+	mapTree: ExclusiveMapTree,
 	implicitAllowedTypes: FlexImplicitAllowedTypes,
 	parent: LocationInField | undefined,
 ): EagerMapTreeNode<FlexTreeNodeSchema> {
@@ -613,29 +610,9 @@ function getOrCreateChild(
 }
 
 /** Always constructs a new node, therefore may not be called twice for the same `MapTree`. */
-function createNode<TSchema extends LeafNodeSchema>(
-	nodeSchema: TSchema,
-	mapTree: MapTree,
-	parentField: LocationInField | undefined,
-): EagerMapTreeLeafNode<TSchema>;
-function createNode<TSchema extends FlexMapNodeSchema>(
-	nodeSchema: TSchema,
-	mapTree: MapTree,
-	parentField: LocationInField | undefined,
-): EagerMapTreeMapNode<TSchema>;
-function createNode<TSchema extends FlexFieldNodeSchema>(
-	nodeSchema: TSchema,
-	mapTree: MapTree,
-	parentField: LocationInField | undefined,
-): EagerMapTreeFieldNode<TSchema>;
 function createNode<TSchema extends FlexTreeNodeSchema>(
 	nodeSchema: TSchema,
-	mapTree: MapTree,
-	parentField: LocationInField | undefined,
-): EagerMapTreeNode<TSchema>;
-function createNode<TSchema extends FlexTreeNodeSchema>(
-	nodeSchema: TSchema,
-	mapTree: MapTree,
+	mapTree: ExclusiveMapTree,
 	parentField: LocationInField | undefined,
 ): EagerMapTreeNode<TSchema> {
 	if (schemaIsLeaf(nodeSchema)) {
@@ -644,9 +621,6 @@ function createNode<TSchema extends FlexTreeNodeSchema>(
 	if (schemaIsMap(nodeSchema)) {
 		return new EagerMapTreeMapNode(nodeSchema, mapTree, parentField);
 	}
-	if (schemaIsFieldNode(nodeSchema)) {
-		return new EagerMapTreeFieldNode(nodeSchema, mapTree, parentField);
-	}
 	if (schemaIsObjectNode(nodeSchema)) {
 		return new EagerMapTreeNode(nodeSchema, mapTree, parentField);
 	}
@@ -655,12 +629,11 @@ function createNode<TSchema extends FlexTreeNodeSchema>(
 
 /** Creates a field with the given attributes, or returns a cached field if there is one */
 function getOrCreateField(
-	parent: FlexTreeNode,
+	parent: EagerMapTreeNode<FlexTreeNodeSchema>,
 	key: FieldKey,
-	mapTrees: readonly MapTree[],
 	schema: FlexFieldSchema,
-): MapTreeField<FlexFieldSchema["allowedTypes"]> {
-	const cached = fieldCache.get(mapTrees);
+): EagerMapTreeField<FlexFieldSchema["allowedTypes"]> {
+	const cached = getFieldKeyCache(parent).get(key);
 	if (cached !== undefined) {
 		return cached;
 	}
@@ -669,24 +642,24 @@ function getOrCreateField(
 		schema.kind.identifier === FieldKinds.required.identifier ||
 		schema.kind.identifier === FieldKinds.identifier.identifier
 	) {
-		return new MapTreeRequiredField(schema, key, parent, mapTrees);
+		return new EagerMapTreeRequiredField(schema, key, parent);
 	}
 
 	if (schema.kind.identifier === FieldKinds.optional.identifier) {
-		return new MapTreeOptionalField(schema, key, parent, mapTrees);
+		return new EagerMapTreeOptionalField(schema, key, parent);
 	}
 
 	if (schema.kind.identifier === FieldKinds.sequence.identifier) {
-		return new MapTreeSequenceField(schema, key, parent, mapTrees);
+		return new EagerMapTreeSequenceField(schema, key, parent);
 	}
 
-	return new MapTreeField(schema, key, parent, mapTrees);
+	return new EagerMapTreeField(schema, key, parent);
 }
 
 /** Unboxes non-polymorphic leaf nodes to their values, if applicable */
 function unboxedUnion<TTypes extends FlexAllowedTypes>(
 	schema: FlexFieldSchema<FlexFieldKind, TTypes>,
-	mapTree: MapTree,
+	mapTree: ExclusiveMapTree,
 	parent: LocationInField,
 ): FlexTreeUnboxNodeUnion<TTypes> {
 	const type = schema.monomorphicChildType;
@@ -706,17 +679,17 @@ function unboxedUnion<TTypes extends FlexAllowedTypes>(
 
 /** Unboxes non-polymorphic required and optional fields holding leaf nodes to their values, if applicable */
 function unboxedField<TFieldSchema extends FlexFieldSchema>(
-	field: MapTreeField<FlexAllowedTypes>,
+	field: EagerMapTreeField<FlexAllowedTypes>,
 	key: FieldKey,
-	mapTree: MapTree,
-	parentNode: FlexTreeNode,
+	mapTree: ExclusiveMapTree,
+	parentNode: EagerMapTreeNode<FlexTreeNodeSchema>,
 ): FlexTreeUnboxField<TFieldSchema> {
 	const fieldSchema = field.schema;
 	const mapTrees =
 		mapTree.fields.get(key) ?? fail("Key does not exist in unhydrated map tree");
 
 	if (fieldSchema.kind === FieldKinds.required) {
-		return unboxedUnion(fieldSchema, mapTrees[0], {
+		return unboxedUnion(fieldSchema, mapTrees[0] ?? oob(), {
 			parent: field,
 			index: 0,
 		}) as FlexTreeUnboxField<TFieldSchema>;
@@ -724,17 +697,15 @@ function unboxedField<TFieldSchema extends FlexFieldSchema>(
 	if (fieldSchema.kind === FieldKinds.optional) {
 		return (
 			mapTrees.length > 0
-				? unboxedUnion(fieldSchema, mapTrees[0], { parent: field, index: 0 })
+				? unboxedUnion(fieldSchema, mapTrees[0] ?? oob(), {
+						parent: field,
+						index: 0,
+					})
 				: undefined
 		) as FlexTreeUnboxField<TFieldSchema>;
 	}
 
-	return getOrCreateField(
-		parentNode,
-		key,
-		mapTrees,
-		fieldSchema,
-	) as FlexTreeUnboxField<TFieldSchema>;
+	return getOrCreateField(parentNode, key, fieldSchema) as FlexTreeUnboxField<TFieldSchema>;
 }
 
 // #endregion Caching and unboxing utilities