@fluidframework/tree 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

package/src/simple-tree/proxies.ts

@@ -3,49 +3,33 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
 import { IFluidHandle } from "@fluidframework/core-interfaces";
-import { brand, fail, isReadonlyArray } from "../util/index.js";
+import { assert } from "@fluidframework/core-utils/internal";
+
+import {
+	EmptyKey,
+	IForestSubscription,
+	TreeNodeSchemaIdentifier,
+	TreeValue,
+	UpPath,
+} from "../core/index.js";
+
 import {
-	FlexAllowedTypes,
-	FlexFieldSchema,
-	FlexObjectNodeSchema,
-	FlexTreeNodeSchema,
-	schemaIsFieldNode,
-	schemaIsLeaf,
-	schemaIsMap,
-	schemaIsObjectNode,
-	FlexMapNodeSchema,
-	FlexFieldNodeSchema,
 	FieldKinds,
-	FlexTreeFieldNode,
-	FlexTreeMapNode,
-	FlexTreeObjectNode,
-	FlexTreeOptionalField,
-	FlexTreeRequiredField,
-	FlexTreeSequenceField,
+	FlexFieldSchema,
+	FlexTreeField,
 	FlexTreeNode,
 	FlexTreeTypedField,
-	onNextChange,
-	typeNameSymbol,
 	isFluidHandle,
-	FlexTreeField,
+	typeNameSymbol,
 } from "../feature-libraries/index.js";
-import { EmptyKey, FieldKey, TreeNodeSchemaIdentifier, TreeValue } from "../core/index.js";
-// TODO: decide how to deal with dependencies on flex-tree implementation.
-// eslint-disable-next-line import/no-internal-modules
-import { LazyObjectNode, getBoxedField } from "../feature-libraries/flex-tree/lazyNode.js";
-import {
-	type TreeNodeSchema as TreeNodeSchemaClass,
-	type InsertableTypedNode,
-	NodeKind,
-	TreeMapNode,
-} from "./schemaTypes.js";
-import { IterableTreeArrayContent, TreeArrayNode } from "./treeArrayNode.js";
-import { Unhydrated, TreeNode } from "./types.js";
-import { tryGetFlexNodeTarget, setFlexNode, getFlexNode, tryGetFlexNode } from "./flexNode.js";
-import { cursorFromFieldData, cursorFromNodeData } from "./toMapTree.js";
-import { RawTreeNode, createRawNode, extractRawNodeContent } from "./rawNode.js";
+import { Mutable, brand, fail, isReadonlyArray } from "../util/index.js";
+
+import { anchorProxy, tryGetFlexNode, tryGetProxy } from "./proxyBinding.js";
+import { extractRawNodeContent } from "./rawNode.js";
+import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
+import { NodeKind } from "./schemaTypes.js";
+import { TreeNode, Unhydrated } from "./types.js";
 
 /**
  * Detects if the given 'candidate' is a TreeNode.
@@ -101,787 +85,132 @@ export function getProxyForField(field: FlexTreeField): TreeNode | TreeValue | u
 			// this case unreachable as long as users follow the 'array recipe'.
 			fail("'sequence' field is unexpected.");
 		}
+		case FieldKinds.identifier: {
+			const identifier = field.boxedAt(0);
+			assert(identifier !== undefined, 0x91a /* identifier must exist */);
+			return getOrCreateNodeProxy(identifier);
+		}
+
 		default:
 			fail("invalid field kind");
 	}
 }
 
-/**
- * A symbol for storing TreeNodeSchemaClass on FlexTreeNode's schema.
- */
-export const simpleSchemaSymbol: unique symbol = Symbol(`simpleSchema`);
-
-export function getClassSchema(schema: FlexTreeNodeSchema): TreeNodeSchemaClass | undefined {
-	if (simpleSchemaSymbol in schema) {
-		return schema[simpleSchemaSymbol] as TreeNodeSchemaClass;
-	}
-	return undefined;
-}
-
 export function getOrCreateNodeProxy(flexNode: FlexTreeNode): TreeNode | TreeValue {
-	const cachedProxy = tryGetFlexNodeTarget(flexNode);
+	const cachedProxy = tryGetProxy(flexNode);
 	if (cachedProxy !== undefined) {
 		return cachedProxy;
 	}
 
 	const schema = flexNode.schema;
-	let output: TreeNode | TreeValue;
-	const classSchema = getClassSchema(schema);
-	if (classSchema !== undefined) {
-		if (typeof classSchema === "function") {
-			const simpleSchema = classSchema as unknown as new (dummy: FlexTreeNode) => TreeNode;
-			output = new simpleSchema(flexNode);
-		} else {
-			output = (schema as unknown as { create: (data: FlexTreeNode) => TreeNode }).create(
-				flexNode,
-			);
-		}
+	const classSchema = tryGetSimpleNodeSchema(schema);
+	assert(classSchema !== undefined, 0x91b /* node without schema */);
+	if (typeof classSchema === "function") {
+		const simpleSchema = classSchema as unknown as new (dummy: FlexTreeNode) => TreeNode;
+		return new simpleSchema(flexNode);
 	} else {
-		// Fallback to createNodeProxy if needed.
-		// TODO: maybe remove this fallback and error once migration to class based schema is done.
-		output = createNodeProxy(flexNode, false);
+		return (classSchema as { create(data: FlexTreeNode): TreeNode }).create(flexNode);
 	}
-	return output;
 }
 
-/**
- * @param flexNode - underlying tree node which this proxy should wrap.
- * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.
- * Otherwise setting of unexpected properties will error.
- * @param customTargetObject - Target object of the proxy.
- * If not provided an empty collection of the relevant type is used for the target and a separate object created to dispatch methods.
- * If provided, the customTargetObject will be used as both the dispatch object and the proxy target, and therefor must provide needed functionality depending on the schema kind.
- */
-export function createNodeProxy(
-	flexNode: FlexTreeNode,
-	allowAdditionalProperties: boolean,
-	targetObject?: object,
-): TreeNode | TreeValue {
-	const schema = flexNode.schema;
-	if (schemaIsLeaf(schema)) {
-		// Can't use `??` here since null is a valid TreeValue.
-		assert(flexNode.value !== undefined, 0x887 /* Leaf must have value */);
-		return flexNode.value;
-	}
-	let proxy: TreeNode;
-	if (schemaIsMap(schema)) {
-		proxy = createMapProxy(allowAdditionalProperties, targetObject);
-	} else if (schemaIsFieldNode(schema)) {
-		proxy = createArrayNodeProxy(allowAdditionalProperties, targetObject);
-	} else if (schemaIsObjectNode(schema)) {
-		proxy = createObjectProxy(schema, allowAdditionalProperties, targetObject);
-	} else {
-		fail("unrecognized node kind");
-	}
-	setFlexNode(proxy, flexNode);
-	return proxy;
-}
+// #region Content insertion and proxy binding
 
-/**
- * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.
- * Otherwise setting of unexpected properties will error.
- * @param customTargetObject - Target object of the proxy.
- * If not provided `{}` is used for the target.
- */
-export function createObjectProxy<TSchema extends FlexObjectNodeSchema>(
-	schema: TSchema,
-	allowAdditionalProperties: boolean,
-	targetObject: object = {},
-): TreeNode {
-	// To satisfy 'deepEquals' level scrutiny, the target of the proxy must be an object with the same
-	// prototype as an object literal '{}'.  This is because 'deepEquals' uses 'Object.getPrototypeOf'
-	// as a way to quickly reject objects with different prototype chains.
-	//
-	// (Note that the prototype of an object literal appears as '[Object: null prototype] {}', not because
-	// the prototype is null, but because the prototype object itself has a null prototype.)
-
-	// TODO: Although the target is an object literal, it's still worthwhile to try experimenting with
-	// a dispatch object to see if it improves performance.
-	const proxy = new Proxy(targetObject, {
-		get(target, key): unknown {
-			const field = getFlexNode(proxy).tryGetField(key as FieldKey);
-			if (field !== undefined) {
-				return getProxyForField(field);
-			}
-
-			// Pass the proxy as the receiver here, so that any methods on the prototype receive `proxy` as `this`.
-			return Reflect.get(target, key, proxy);
-		},
-		set(target, key, value: InsertableContent) {
-			const flexNode = getFlexNode(proxy);
-			const flexNodeSchema = flexNode.schema;
-			assert(flexNodeSchema instanceof FlexObjectNodeSchema, 0x888 /* invalid schema */);
-			const fieldSchema = flexNodeSchema.objectNodeFields.get(key as FieldKey);
-
-			if (fieldSchema === undefined) {
-				return allowAdditionalProperties ? Reflect.set(target, key, value) : false;
-			}
-
-			// TODO: Is it safe to assume 'content' is a LazyObjectNode?
-			assert(flexNode instanceof LazyObjectNode, 0x7e0 /* invalid content */);
-			assert(typeof key === "string", 0x7e1 /* invalid key */);
-			const field = getBoxedField(flexNode, brand(key), fieldSchema);
-
-			switch (field.schema.kind) {
-				case FieldKinds.required:
-				case FieldKinds.optional: {
-					const typedField = field as
-						| FlexTreeRequiredField<FlexAllowedTypes>
-						| FlexTreeOptionalField<FlexAllowedTypes>;
-
-					const { content, hydrateProxies } = extractFactoryContent(value);
-					const cursor = cursorFromNodeData(
-						content,
-						flexNode.context.schema,
-						fieldSchema.allowedTypeSet,
-					);
-					modifyChildren(
-						flexNode,
-						() => {
-							typedField.content = cursor;
-						},
-						() => hydrateProxies(typedField.boxedContent),
-					);
-					break;
-				}
-
-				default:
-					fail("invalid FieldKind");
-			}
-
-			return true;
-		},
-		has: (target, key) => {
-			return (
-				schema.objectNodeFields.has(key as FieldKey) ||
-				(allowAdditionalProperties ? Reflect.has(target, key) : false)
-			);
-		},
-		ownKeys: (target) => {
-			return [
-				...schema.objectNodeFields.keys(),
-				...(allowAdditionalProperties ? Reflect.ownKeys(target) : []),
-			];
-		},
-		getOwnPropertyDescriptor: (target, key) => {
-			const field = getFlexNode(proxy).tryGetField(key as FieldKey);
-
-			if (field === undefined) {
-				return allowAdditionalProperties
-					? Reflect.getOwnPropertyDescriptor(target, key)
-					: undefined;
-			}
-
-			const p: PropertyDescriptor = {
-				value: getProxyForField(field),
-				writable: true,
-				enumerable: true,
-				configurable: true, // Must be 'configurable' if property is absent from proxy target.
-			};
-
-			return p;
-		},
-	}) as TreeNode;
-	return proxy;
+/** The path of a proxy, relative to the root of the content tree that the proxy belongs to */
+interface RelativeProxyPath {
+	readonly path: UpPath;
+	readonly proxy: TreeNode;
 }
 
-/**
- * Given a array node proxy, returns its underlying LazySequence field.
- */
-export const getSequenceField = <TTypes extends FlexAllowedTypes>(arrayNode: TreeArrayNode) =>
-	getFlexNode(arrayNode).content as FlexTreeSequenceField<TTypes>;
-
-// Used by 'insert*()' APIs to converts new content (expressed as a proxy union) to contextually
-// typed data prior to forwarding to 'LazySequence.insert*()'.
-function contextualizeInsertedArrayContent(
-	insertedAtIndex: number,
-	content: readonly (InsertableContent | IterableTreeArrayContent<InsertableContent>)[],
-): ExtractedFactoryContent {
-	return extractFactoryContent(
-		content.flatMap((c): InsertableContent[] =>
-			c instanceof IterableTreeArrayContent ? Array.from(c) : [c],
-		),
-		insertedAtIndex,
-	);
+/** All {@link RelativeProxyPath}s that are under the given root path */
+interface RootedProxyPaths {
+	readonly rootPath: UpPath;
+	readonly proxyPaths: RelativeProxyPath[];
 }
 
-// #region Create dispatch map for array nodes
-
-// TODO: Experiment with alternative dispatch methods to see if we can improve performance.
-
 /**
- * PropertyDescriptorMap used to build the prototype for our array node dispatch object.
+ * Records any proxies in the given content tree and does the necessary bookkeeping to ensure they are synchronized with subsequent reads of the tree.
+ * @remarks If the content tree contains any proxies, this function must be called just prior to inserting the content into the tree.
+ * Specifically, no other content may be inserted into the tree between the invocation of this function and the insertion of `content`.
+ * The insertion of `content` must occur or else this function will cause memory leaks.
+ * @param content - the tree of content to be inserted, of which any of its object/map/array nodes might be a proxy
+ * @param anchors - the {@link AnchorSet} for the tree
+ * @returns The content after having all proxies replaced inline with plain javascript objects.
+ * See {@link extractFactoryContent} for more details.
  */
-export const arrayNodePrototypeProperties: PropertyDescriptorMap = {
-	// We manually add [Symbol.iterator] to the dispatch map rather than use '[fn.name] = fn' as
-	// below when adding 'Array.prototype.*' properties to this map because 'Array.prototype[Symbol.iterator].name'
-	// returns "values" (i.e., Symbol.iterator is an alias for the '.values()' function.)
-	[Symbol.iterator]: {
-		value: Array.prototype[Symbol.iterator],
-	},
-	at: {
-		value(this: TreeArrayNode, index: number): TreeNode | TreeValue | undefined {
-			const field = getSequenceField(this);
-			const val = field.boxedAt(index);
-
-			if (val === undefined) {
-				return val;
-			}
-
-			return getOrCreateNodeProxy(val);
-		},
-	},
-	insertAt: {
-		value(
-			this: TreeArrayNode,
-			index: number,
-			...value: readonly (InsertableContent | IterableTreeArrayContent<InsertableContent>)[]
-		): void {
-			const sequenceField = getSequenceField(this);
-
-			const { content, hydrateProxies } = contextualizeInsertedArrayContent(index, value);
-			const cursor = cursorFromFieldData(
-				content,
-				sequenceField.context.schema,
-				sequenceField.schema,
-			);
-
-			modifyChildren(
-				getFlexNode(this),
-				() => sequenceField.insertAt(index, cursor),
-				(listFlexNode) => hydrateProxies(listFlexNode),
-			);
-		},
-	},
-	insertAtStart: {
-		value(
-			this: TreeArrayNode,
-			...value: readonly (InsertableContent | IterableTreeArrayContent<InsertableContent>)[]
-		): void {
-			const sequenceField = getSequenceField(this);
-
-			const { content, hydrateProxies } = contextualizeInsertedArrayContent(0, value);
-			const cursor = cursorFromFieldData(
-				content,
-				sequenceField.context.schema,
-				sequenceField.schema,
-			);
-
-			modifyChildren(
-				getFlexNode(this),
-				() => sequenceField.insertAtStart(cursor),
-				(listFlexNode) => hydrateProxies(listFlexNode),
-			);
-		},
-	},
-	insertAtEnd: {
-		value(
-			this: TreeArrayNode,
-			...value: readonly (InsertableContent | IterableTreeArrayContent<InsertableContent>)[]
-		): void {
-			const sequenceField = getSequenceField(this);
-
-			const { content, hydrateProxies } = contextualizeInsertedArrayContent(
-				this.length,
-				value,
-			);
-			const cursor = cursorFromFieldData(
-				content,
-				sequenceField.context.schema,
-				sequenceField.schema,
-			);
+export function prepareContentForInsert(
+	content: InsertableContent,
+	forest: IForestSubscription,
+): FactoryContent {
+	if (isReadonlyArray(content)) {
+		return prepareArrayContentForInsert(content, forest);
+	}
 
-			modifyChildren(
-				getFlexNode(this),
-				() => sequenceField.insertAtEnd(cursor),
-				(listFlexNode) => hydrateProxies(listFlexNode),
-			);
-		},
-	},
-	removeAt: {
-		value(this: TreeArrayNode, index: number): void {
-			getSequenceField(this).removeAt(index);
-		},
-	},
-	removeRange: {
-		value(this: TreeArrayNode, start?: number, end?: number): void {
-			getSequenceField(this).removeRange(start, end);
-		},
-	},
-	moveToStart: {
-		value(this: TreeArrayNode, sourceIndex: number, source?: TreeArrayNode): void {
-			if (source !== undefined) {
-				getSequenceField(this).moveToStart(sourceIndex, getSequenceField(source));
-			} else {
-				getSequenceField(this).moveToStart(sourceIndex);
-			}
-		},
-	},
-	moveToEnd: {
-		value(this: TreeArrayNode, sourceIndex: number, source?: TreeArrayNode): void {
-			if (source !== undefined) {
-				getSequenceField(this).moveToEnd(sourceIndex, getSequenceField(source));
-			} else {
-				getSequenceField(this).moveToEnd(sourceIndex);
-			}
-		},
-	},
-	moveToIndex: {
-		value(
-			this: TreeArrayNode,
-			index: number,
-			sourceIndex: number,
-			source?: TreeArrayNode,
-		): void {
-			if (source !== undefined) {
-				getSequenceField(this).moveToIndex(index, sourceIndex, getSequenceField(source));
-			} else {
-				getSequenceField(this).moveToIndex(index, sourceIndex);
-			}
-		},
-	},
-	moveRangeToStart: {
-		value(
-			this: TreeArrayNode,
-			sourceStart: number,
-			sourceEnd: number,
-			source?: TreeArrayNode,
-		): void {
-			if (source !== undefined) {
-				getSequenceField(this).moveRangeToStart(
-					sourceStart,
-					sourceEnd,
-					getSequenceField(source),
-				);
-			} else {
-				getSequenceField(this).moveRangeToStart(sourceStart, sourceEnd);
-			}
-		},
-	},
-	moveRangeToEnd: {
-		value(
-			this: TreeArrayNode,
-			sourceStart: number,
-			sourceEnd: number,
-			source?: TreeArrayNode,
-		): void {
-			if (source !== undefined) {
-				getSequenceField(this).moveRangeToEnd(
-					sourceStart,
-					sourceEnd,
-					getSequenceField(source),
-				);
-			} else {
-				getSequenceField(this).moveRangeToEnd(sourceStart, sourceEnd);
-			}
-		},
-	},
-	moveRangeToIndex: {
-		value(
-			this: TreeArrayNode,
-			index: number,
-			sourceStart: number,
-			sourceEnd: number,
-			source?: TreeArrayNode,
-		): void {
-			if (source !== undefined) {
-				getSequenceField(this).moveRangeToIndex(
-					index,
-					sourceStart,
-					sourceEnd,
-					getSequenceField(source),
-				);
-			} else {
-				getSequenceField(this).moveRangeToIndex(index, sourceStart, sourceEnd);
-			}
+	const proxies: RootedProxyPaths = {
+		rootPath: { parent: undefined, parentField: EmptyKey, parentIndex: 0 },
+		proxyPaths: [],
+	};
+	const extractedContent = extractFactoryContent(content, {
+		path: proxies.rootPath,
+		onVisitProxy: (p, proxy) => {
+			proxies.proxyPaths.push({ path: p, proxy });
 		},
-	},
-};
-
-/* eslint-disable @typescript-eslint/unbound-method */
-
-// For compatibility, we are initially implement 'readonly T[]' by applying the Array.prototype methods
-// to the array node proxy.  Over time, we should replace these with efficient implementations on LazySequence
-// to avoid re-entering the proxy as these methods access 'length' and the indexed properties.
-//
-// For brevity, the current implementation dynamically builds a property descriptor map from a list of
-// Array functions we want to re-expose via the proxy.
-
-// TODO: This assumes 'Function.name' matches the property name on 'Array.prototype', which may be
-// dubious across JS engines.
-[
-	Array.prototype.concat,
-	// Array.prototype.copyWithin,
-	Array.prototype.entries,
-	Array.prototype.every,
-	// Array.prototype.fill,
-	Array.prototype.filter,
-	Array.prototype.find,
-	Array.prototype.findIndex,
-	Array.prototype.flat,
-	Array.prototype.flatMap,
-	Array.prototype.forEach,
-	Array.prototype.includes,
-	Array.prototype.indexOf,
-	Array.prototype.join,
-	Array.prototype.keys,
-	Array.prototype.lastIndexOf,
-	// Array.prototype.length,
-	Array.prototype.map,
-	// Array.prototype.pop,
-	// Array.prototype.push,
-	Array.prototype.reduce,
-	Array.prototype.reduceRight,
-	// Array.prototype.reverse,
-	// Array.prototype.shift,
-	Array.prototype.slice,
-	Array.prototype.some,
-	// Array.prototype.sort,
-	// Array.prototype.splice,
-	Array.prototype.toLocaleString,
-	Array.prototype.toString,
-	// Array.prototype.unshift,
-	Array.prototype.values,
-].forEach((fn) => {
-	arrayNodePrototypeProperties[fn.name] = { value: fn };
-});
-
-/* eslint-enable @typescript-eslint/unbound-method */
-
-const arrayNodePrototype = Object.create(Object.prototype, arrayNodePrototypeProperties);
-
-// #endregion
-
-/**
- * Helper to coerce property keys to integer indexes (or undefined if not an in-range integer).
- */
-function asIndex(key: string | symbol, length: number) {
-	if (typeof key === "string") {
-		// TODO: It may be worth a '0' <= ch <= '9' check before calling 'Number' to quickly
-		// reject 'length' as an index, or even parsing integers ourselves.
-		const asNumber = Number(key);
+	});
 
-		// TODO: See 'matrix/range.ts' for fast integer coercing + range check.
-		if (Number.isInteger(asNumber)) {
-			return 0 <= asNumber && asNumber < length ? asNumber : undefined;
-		}
-	}
+	bindProxies([proxies], forest);
+	return extractedContent;
 }
 
-/**
- * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.
- * Otherwise setting of unexpected properties will error.
- * @param customTargetObject - Target object of the proxy.
- * If not provided `[]` is used for the target and a separate object created to dispatch array methods.
- * If provided, the customTargetObject will be used as both the dispatch object and the proxy target, and therefor must provide `length` and the array functionality from {@link arrayNodePrototype}.
- */
-function createArrayNodeProxy(
-	allowAdditionalProperties: boolean,
-	customTargetObject?: object,
-): TreeArrayNode {
-	const targetObject = customTargetObject ?? [];
-
-	// Create a 'dispatch' object that this Proxy forwards to instead of the proxy target, because we need
-	// the proxy target to be a plain JS array (see comments below when we instantiate the Proxy).
-	// Own properties on the dispatch object are surfaced as own properties of the proxy.
-	// (e.g., 'length', which is defined below).
-	//
-	// Properties normally inherited from 'Array.prototype' are surfaced via the prototype chain.
-	const dispatch: object =
-		customTargetObject ??
-		Object.create(arrayNodePrototype, {
-			length: {
-				get(this: TreeArrayNode) {
-					return getSequenceField(this).length;
-				},
-				set() {},
-				enumerable: false,
-				configurable: false,
+function prepareArrayContentForInsert(
+	content: readonly InsertableContent[],
+	forest: IForestSubscription,
+): FactoryContent {
+	const proxies: RootedProxyPaths[] = [];
+	const extractedContent: FactoryContent[] = [];
+	for (let i = 0; i < content.length; i++) {
+		proxies.push({
+			rootPath: {
+				parent: undefined,
+				parentField: EmptyKey,
+				parentIndex: 0,
 			},
+			proxyPaths: [],
 		});
+		extractedContent.push(
+			extractFactoryContent(content[i], {
+				path: proxies[i].rootPath,
+				onVisitProxy: (p, proxy) => {
+					proxies[i].proxyPaths.push({ path: p, proxy });
+				},
+			}),
+		);
+	}
 
-	// To satisfy 'deepEquals' level scrutiny, the target of the proxy must be an array literal in order
-	// to pass 'Object.getPrototypeOf'.  It also satisfies 'Array.isArray' and 'Object.prototype.toString'
-	// requirements without use of Array[Symbol.species], which is potentially on a path ot deprecation.
-	const proxy: TreeArrayNode = new Proxy<TreeArrayNode>(targetObject as any, {
-		get: (target, key) => {
-			const field = getSequenceField(proxy);
-			const maybeIndex = asIndex(key, field.length);
-
-			if (maybeIndex === undefined) {
-				// Pass the proxy as the receiver here, so that any methods on
-				// the prototype receive `proxy` as `this`.
-				return Reflect.get(dispatch, key, proxy) as unknown;
-			}
-
-			const value = field.boxedAt(maybeIndex);
-
-			if (value === undefined) {
-				return undefined;
-			}
-
-			// TODO: Ideally, we would return leaves without first boxing them.  However, this is not
-			//       as simple as calling '.content' since this skips the node and returns the FieldNode's
-			//       inner field.
-			return getOrCreateNodeProxy(value);
-		},
-		set: (target, key, newValue, receiver) => {
-			// 'Symbol.isConcatSpreadable' may be set on an Array instance to modify the behavior of
-			// the concat method.  We allow this property to be added to the dispatch object.
-			if (key === Symbol.isConcatSpreadable) {
-				return Reflect.set(dispatch, key, newValue, proxy);
-			}
-
-			const field = getSequenceField(proxy);
-			const maybeIndex = asIndex(key, field.length);
-			if (maybeIndex !== undefined) {
-				// For MVP, we otherwise disallow setting properties (mutation is only available via the array node mutation APIs).
-				return false;
-			}
-			return allowAdditionalProperties ? Reflect.set(target, key, newValue) : false;
-		},
-		has: (target, key) => {
-			const field = getSequenceField(proxy);
-			const maybeIndex = asIndex(key, field.length);
-			return maybeIndex !== undefined || Reflect.has(dispatch, key);
-		},
-		ownKeys: (target) => {
-			const field = getSequenceField(proxy);
-
-			// TODO: Would a lazy iterator to produce the indexes work / be more efficient?
-			// TODO: Need to surface 'Symbol.isConcatSpreadable' as an own key.
-			return Array.from({ length: field.length }, (_, index) => `${index}`).concat("length");
-		},
-		getOwnPropertyDescriptor: (target, key) => {
-			const field = getSequenceField(proxy);
-			const maybeIndex = asIndex(key, field.length);
-			if (maybeIndex !== undefined) {
-				const val = field.boxedAt(maybeIndex);
-				// To satisfy 'deepEquals' level scrutiny, the property descriptor for indexed properties must
-				// be a simple value property (as opposed to using getter) and declared writable/enumerable/configurable.
-				return {
-					// TODO: Ideally, we would return leaves without first boxing them.  However, this is not
-					//       as simple as calling '.at' since this skips the node and returns the FieldNode's
-					//       inner field.
-					value: val === undefined ? val : getOrCreateNodeProxy(val),
-					writable: true, // For MVP, disallow setting indexed properties.
-					enumerable: true,
-					configurable: true,
-				};
-			} else if (key === "length") {
-				// To satisfy 'deepEquals' level scrutiny, the property descriptor for 'length' must be a simple
-				// value property (as opposed to using getter) and be declared writable / non-configurable.
-				return {
-					value: getSequenceField(proxy).length,
-					writable: true,
-					enumerable: false,
-					configurable: false,
-				};
-			}
-			return Reflect.getOwnPropertyDescriptor(dispatch, key);
-		},
-	});
-	return proxy;
+	bindProxies(proxies, forest);
+	return extractedContent;
 }
 
-// #region Create dispatch map for maps
-
-export const mapStaticDispatchMap: PropertyDescriptorMap = {
-	[Symbol.iterator]: {
-		value(this: TreeMapNode) {
-			return this.entries();
-		},
-	},
-	delete: {
-		value(this: TreeMapNode, key: string): void {
-			const node = getFlexNode(this);
-			node.delete(key);
-		},
-	},
-	entries: {
-		*value(this: TreeMapNode): IterableIterator<[string, unknown]> {
-			const node = getFlexNode(this);
-			for (const key of node.keys()) {
-				yield [key, getProxyForField(node.getBoxed(key))];
+function bindProxies(proxies: RootedProxyPaths[], forest: IForestSubscription): void {
+	// Only subscribe to the event if there is at least one proxy tree to hydrate - this is not the case when inserting an empty array [].
+	if (proxies.length > 0) {
+		// Creating a new array emits one event per element in the array, so listen to the event once for each element
+		let i = 0;
+		const off = forest.on("afterRootFieldCreated", (fieldKey) => {
+			(proxies[i].rootPath as Mutable<UpPath>).parentField = fieldKey;
+			for (const { path, proxy } of proxies[i].proxyPaths) {
+				anchorProxy(forest.anchors, path, proxy);
 			}
-		},
-	},
-	get: {
-		value(this: TreeMapNode, key: string): unknown {
-			const node = getFlexNode(this);
-			const field = node.getBoxed(key);
-			return getProxyForField(field);
-		},
-	},
-	has: {
-		value(this: TreeMapNode, key: string): boolean {
-			const node = getFlexNode(this);
-			return node.has(key);
-		},
-	},
-	keys: {
-		value(this: TreeMapNode): IterableIterator<string> {
-			const node = getFlexNode(this);
-			return node.keys();
-		},
-	},
-	set: {
-		value(
-			this: TreeMapNode,
-			key: string,
-			value: InsertableTypedNode<TreeNodeSchemaClass>,
-		): TreeMapNode {
-			const node = getFlexNode(this);
-
-			const { content, hydrateProxies } = extractFactoryContent(value as FactoryContent);
-			const cursor = cursorFromNodeData(
-				content,
-				node.context.schema,
-				node.schema.mapFields.allowedTypeSet,
-			);
-			modifyChildren(
-				node,
-				(mapNode) => mapNode.set(key, cursor),
-				(mapNode) => hydrateProxies(getMapChildNode(mapNode, key)),
-			);
-			return this;
-		},
-	},
-	size: {
-		get(this: TreeMapNode) {
-			return getFlexNode(this).size;
-		},
-	},
-	values: {
-		*value(this: TreeMapNode): IterableIterator<unknown> {
-			for (const [, value] of this.entries()) {
-				yield value;
+			if (++i === proxies.length) {
+				off();
 			}
-		},
-	},
-	// TODO: add `clear` once we have established merge semantics for it.
-};
-
-const mapPrototype = Object.create(Object.prototype, mapStaticDispatchMap);
-
-// #endregion
-
-/**
- * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.
- * Otherwise setting of unexpected properties will error.
- * @param customTargetObject - Target object of the proxy.
- * If not provided `new Map()` is used for the target and a separate object created to dispatch map methods.
- * If provided, the customTargetObject will be used as both the dispatch object and the proxy target, and therefor must provide the map functionality from {@link mapPrototype}.
- */
-function createMapProxy(
-	allowAdditionalProperties: boolean,
-	customTargetObject?: object,
-): TreeMapNode {
-	// Create a 'dispatch' object that this Proxy forwards to instead of the proxy target.
-	const dispatch: object =
-		customTargetObject ??
-		Object.create(mapPrototype, {
-			// Empty - JavaScript Maps do not expose any "own" properties.
 		});
-	const targetObject: object = customTargetObject ?? new Map<string, TreeNode>();
-
-	// TODO: Although the target is an object literal, it's still worthwhile to try experimenting with
-	// a dispatch object to see if it improves performance.
-	const proxy = new Proxy<TreeMapNode>(targetObject as TreeMapNode, {
-		get: (target, key, receiver): unknown => {
-			// Pass the proxy as the receiver here, so that any methods on the prototype receive `proxy` as `this`.
-			return Reflect.get(dispatch, key, proxy);
-		},
-		getOwnPropertyDescriptor: (target, key): PropertyDescriptor | undefined => {
-			return Reflect.getOwnPropertyDescriptor(dispatch, key);
-		},
-		has: (target, key) => {
-			return Reflect.has(dispatch, key);
-		},
-		set: (target, key, newValue): boolean => {
-			return allowAdditionalProperties ? Reflect.set(dispatch, key, newValue) : false;
-		},
-		ownKeys: (target) => {
-			// All of Map's properties are inherited via its prototype, so there is nothing to return here,
-			return [];
-		},
-	});
-	return proxy;
-}
-
-/**
- * Create a proxy to a {@link TreeObjectNode} that is backed by a raw object node (see {@link createRawNode}).
- * @param schema - the schema of the object node
- * @param content - the content to be stored in the raw node.
- * A copy of content is stored, the input `content` is not modified and can be safely reused in another call to {@link createRawObjectProxy}.
- * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.
- * Otherwise setting of unexpected properties will error.
- * @param customTargetObject - Target object of the proxy.
- * If not provided `{}` is used for the target.
- * @remarks
- * Because this proxy is backed by a raw node, it has the same limitations as the node created by {@link createRawNode}.
- * Most of its properties and methods will error if read/called.
- */
-export function createRawNodeProxy(
-	schema: FlexTreeNodeSchema,
-	content: InsertableTypedNode<TreeNodeSchemaClass> & object,
-	allowAdditionalProperties: boolean,
-	target?: object,
-): Unhydrated<TreeNode> {
-	// Shallow copy the content and then add the type name symbol to it.
-	let flexNode: RawTreeNode<FlexTreeNodeSchema, InsertableTypedNode<TreeNodeSchemaClass>>;
-	let proxy: TreeNode;
-	if (schema instanceof FlexObjectNodeSchema) {
-		const contentCopy = copyContent(schema.name, content);
-		flexNode = createRawNode(schema, contentCopy);
-		proxy = createObjectProxy(schema, allowAdditionalProperties, target);
-	} else if (schema instanceof FlexFieldNodeSchema) {
-		// simple-tree uses field nodes exclusively to represent array nodes
-		const contentCopy = copyContent(schema.name, content);
-		flexNode = createRawNode(schema, contentCopy);
-		proxy = createArrayNodeProxy(allowAdditionalProperties, target);
-	} else if (schema instanceof FlexMapNodeSchema) {
-		const contentCopy = copyContent(schema.name, content);
-		flexNode = createRawNode(schema, contentCopy);
-		proxy = createMapProxy(allowAdditionalProperties, target);
-	} else {
-		fail("Unrecognized content schema");
 	}
-
-	return setFlexNode(proxy, flexNode);
-}
-
-function copyContent<T extends object>(typeName: TreeNodeSchemaIdentifier, content: T): T {
-	const copy =
-		content instanceof Map
-			? (new Map(content) as T)
-			: Array.isArray(content)
-			? (content.slice() as T)
-			: { ...content };
-
-	return Object.defineProperty(copy, typeNameSymbol, { value: typeName });
-}
-
-type ProxyHydrator = (flexNode: FlexTreeNode | undefined) => void;
-const noopHydrator: ProxyHydrator = () => {};
-
-/** The result returned by {@link extractFactoryContent} and its related helpers. */
-interface ExtractedFactoryContent<out T = FactoryContent> {
-	/** The content with the factory subtrees replaced. */
-	readonly content: T;
-	/**
-	 * A function which walks all factory-created object that underwent replacement/extraction.
-	 * Before hydration, those objects are unusable (see {@link createRawObjectProxy}).
-	 * However, after the content is fully inserted into the tree the `hydrateProxies` function may be invoked in order to update the contents of these objects such that they become a mirror of the content in the tree.
-	 * This must be done before any calls to {@link getOrCreateNodeProxy} so that the "edit node to proxy" mapping is correctly updated (see {@link setFlexNode}).
-	 */
-	readonly hydrateProxies: ProxyHydrator;
 }
 
 /**
  * Given a content tree that is to be inserted into the shared tree, replace all subtrees that were created by factories
  * (via {@link SharedTreeObjectFactory.create}) with the content that was passed to those factories.
  * @param content - the content being inserted which may be, and/or may contain, factory-created content
+ * @param onVisitProxy - an optional callback that will run for each proxy (i.e. object created by a factory) found in the inserted content
  * @param insertedAtIndex - if the content being inserted is array node content, this must be the index in the array node at which the content is being inserted
  * @returns the result of the content replacement and a {@link ExtractedFactoryContent.hydrateProxies} function which must be invoked if present.
  * @remarks
@@ -905,10 +234,12 @@ interface ExtractedFactoryContent<out T = FactoryContent> {
  */
 export function extractFactoryContent(
 	input: InsertableContent,
-	insertedAtIndex = 0,
-): ExtractedFactoryContent {
+	visitProxies?: {
+		path: UpPath;
+		onVisitProxy: (path: UpPath, proxy: TreeNode) => void;
+	},
+): FactoryContent {
 	let content: FactoryContent;
-	let fromFactory = false;
 	const rawFlexNode = tryGetFlexNode(input);
 	if (rawFlexNode !== undefined) {
 		const factoryContent = extractRawNodeContent(rawFlexNode);
@@ -916,8 +247,8 @@ export function extractFactoryContent(
 			// We were passed a proxy, but that proxy doesn't have any raw content.
 			throw new Error("Cannot insert a node that is already in the tree");
 		}
+		visitProxies?.onVisitProxy(visitProxies.path, input as TreeNode);
 		content = factoryContent;
-		fromFactory = true;
 	} else {
 		content = input as FactoryContent;
 	}
@@ -925,151 +256,139 @@ export function extractFactoryContent(
 	assert(!isTreeNode(content), 0x844 /* Unhydrated insertion content should have FlexNode */);
 
 	let type: NodeKind;
-	let extractedContent: ExtractedFactoryContent;
+	let extractedContent: FactoryContent;
 	if (isReadonlyArray(content)) {
 		type = NodeKind.Array;
-		extractedContent = extractContentArray(
-			content as readonly FactoryContent[],
-			insertedAtIndex,
-		);
+		extractedContent = extractContentArray(content as readonly FactoryContent[], visitProxies);
 	} else if (content instanceof Map) {
 		type = NodeKind.Map;
-		extractedContent = extractContentMap(content as ReadonlyMap<string, FactoryContent>);
+		extractedContent = extractContentMap(
+			content as ReadonlyMap<string, FactoryContent>,
+			visitProxies,
+		);
 	} else if (typeof content === "object" && content !== null && !isFluidHandle(content)) {
 		type = NodeKind.Object;
-		extractedContent = extractContentObject(content as object);
+		extractedContent = extractContentObject(content as object, visitProxies);
 	} else {
-		extractedContent = { content, hydrateProxies: noopHydrator };
+		extractedContent = content;
 		type = NodeKind.Leaf;
 	}
 
-	if (isTreeNode(input)) {
-		const kindFromSchema = getNodeKind(input);
-		assert(kindFromSchema === type, 0x845 /* kind of data should match kind of schema */);
-	}
+	if (rawFlexNode !== undefined) {
+		const kindFromSchema =
+			tryGetSimpleNodeSchema(rawFlexNode.schema)?.kind ??
+			fail("NodeBase should always have class schema");
 
-	if (fromFactory) {
-		return {
-			content: extractedContent.content,
-			hydrateProxies: (flexNode) => {
-				// This makes the input proxy usable and updates the proxy cache
-				setFlexNode(input as TreeNode, flexNode ?? fail("Expected edit node"));
-				extractedContent.hydrateProxies(flexNode);
-			},
-		};
+		assert(kindFromSchema === type, 0x845 /* kind of data should match kind of schema */);
 	}
 
 	return extractedContent;
 }
 
-/**
- * @param insertedAtIndex - Supply this if the extracted array content will be inserted into an existing array node in the tree.
- */
 function extractContentArray(
 	input: readonly FactoryContent[],
-	insertedAtIndex: number,
-): ExtractedFactoryContent {
+	visitProxies:
+		| {
+				path: UpPath;
+				onVisitProxy: (path: UpPath, proxy: TreeNode) => void;
+		  }
+		| undefined,
+): FactoryContent {
 	const output: FactoryContent[] = [];
 	if (typeNameSymbol in input) {
 		Object.defineProperty(output, typeNameSymbol, { value: input[typeNameSymbol] });
 	}
-	const hydrators: [index: number, hydrate: ProxyHydrator][] = [];
 	for (let i = 0; i < input.length; i++) {
-		const { content: childContent, hydrateProxies } = extractFactoryContent(input[i]);
+		const childContent = extractFactoryContent(
+			input[i],
+			visitProxies !== undefined
+				? {
+						path: {
+							parent: visitProxies.path,
+							parentField: EmptyKey,
+							parentIndex: i,
+						},
+						onVisitProxy: visitProxies?.onVisitProxy,
+				  }
+				: undefined,
+		);
 		output.push(childContent);
-		// The conditional here is an optimization so that primitive items don't incur boxed reads for hydration
-		if (hydrateProxies !== noopHydrator) {
-			hydrators.push([i, hydrateProxies]);
-		}
 	}
-	return {
-		content: output,
-		hydrateProxies: (flexNode: FlexTreeNode | undefined) => {
-			assert(
-				flexNode !== undefined,
-				0x7f6 /* Expected edit node to be defined when hydrating array node */,
-			);
-			assert(
-				schemaIsFieldNode(flexNode.schema),
-				0x7f7 /* Expected field node when hydrating array node */,
-			);
-			hydrators.forEach(([i, hydrate]) =>
-				hydrate(
-					getArrayNodeChildNode(
-						flexNode as FlexTreeFieldNode<FlexFieldNodeSchema>,
-						insertedAtIndex + i,
-					),
-				),
-			);
-		},
-	};
+	return output;
 }
 
-function extractContentMap(input: ReadonlyMap<string, FactoryContent>): ExtractedFactoryContent {
+function extractContentMap(
+	input: ReadonlyMap<string, FactoryContent>,
+	visitProxies:
+		| {
+				path: UpPath;
+				onVisitProxy: (path: UpPath, proxy: TreeNode) => void;
+		  }
+		| undefined,
+): FactoryContent {
 	const output = new Map();
 	if (typeNameSymbol in input) {
 		Object.defineProperty(output, typeNameSymbol, { value: input[typeNameSymbol] });
 	}
-	const hydrators: [key: string, hydrate: ProxyHydrator][] = [];
 	for (const [key, value] of input) {
-		const { content: childContent, hydrateProxies } = extractFactoryContent(value);
+		const childContent = extractFactoryContent(
+			value,
+			visitProxies !== undefined
+				? {
+						path: {
+							parent: visitProxies.path,
+							parentField: brand(key),
+							parentIndex: 0,
+						},
+						onVisitProxy: visitProxies?.onVisitProxy,
+				  }
+				: undefined,
+		);
 		output.set(key, childContent);
-		// The conditional here is an optimization so that primitive values don't incur boxed reads for hydration
-		if (hydrateProxies !== noopHydrator) {
-			hydrators.push([key, hydrateProxies]);
-		}
 	}
-	return {
-		content: output,
-		hydrateProxies: (flexNode: FlexTreeNode | undefined) => {
-			assert(
-				flexNode !== undefined,
-				0x7f8 /* Expected edit node to be defined when hydrating map */,
-			);
-			assert(schemaIsMap(flexNode.schema), 0x7f9 /* Expected map node when hydrating map */);
-			hydrators.forEach(([key, hydrate]) =>
-				hydrate(getMapChildNode(flexNode as FlexTreeMapNode<FlexMapNodeSchema>, key)),
-			);
-		},
-	};
+	return output;
 }
 
-function extractContentObject(input: {
-	readonly [P in string]?: FactoryContent;
-}): ExtractedFactoryContent {
+function extractContentObject(
+	input: {
+		readonly [P in string]?: FactoryContent;
+	},
+	visitProxies:
+		| {
+				path: UpPath;
+				onVisitProxy: (path: UpPath, proxy: TreeNode) => void;
+		  }
+		| undefined,
+): FactoryContent {
 	const output: Record<string, FactoryContent> = {};
 	if (typeNameSymbol in input) {
 		Object.defineProperty(output, typeNameSymbol, { value: input[typeNameSymbol] });
 	}
-	const hydrators: [key: string, hydrate: ProxyHydrator][] = [];
 	for (const [key, value] of Object.entries(input)) {
 		// Treat undefined fields and missing fields the same.
 		// Generally tree does not require explicit undefined values at runtime despite some of the schema aware type checking currently requiring it.
 		if (value !== undefined) {
-			const { content: childContent, hydrateProxies } = extractFactoryContent(value);
+			const childContent = extractFactoryContent(
+				value,
+				visitProxies !== undefined
+					? {
+							path: {
+								parent: visitProxies.path,
+								parentField: brand(key),
+								parentIndex: 0,
+							},
+							onVisitProxy: visitProxies?.onVisitProxy,
+					  }
+					: undefined,
+			);
 			output[key] = childContent;
-			hydrators.push([key, hydrateProxies]);
 		}
 	}
-
-	return {
-		content: output,
-		hydrateProxies: (flexNode: FlexTreeNode | undefined) => {
-			assert(
-				flexNode !== undefined,
-				0x7fa /* Expected edit node to be defined when hydrating object */,
-			);
-			assert(
-				schemaIsObjectNode(flexNode.schema),
-				0x7fb /* Expected object node when hydrating object content */,
-			);
-			hydrators.forEach(([key, hydrate]) =>
-				hydrate(getObjectChildNode(flexNode as FlexTreeObjectNode, key)),
-			);
-		},
-	};
+	return output;
 }
 
+// #endregion Content insertion and proxy binding
+
 /**
  * Content which can be used to build a node.
  * @remarks
@@ -1093,63 +412,9 @@ export type FactoryContent =
  */
 export type InsertableContent = Unhydrated<TreeNode> | FactoryContent;
 
-function getArrayNodeChildNode(
-	arrayNode: FlexTreeFieldNode<FlexFieldNodeSchema>,
-	index: number,
-): FlexTreeNode | undefined {
-	const field = arrayNode.tryGetField(EmptyKey);
-	assert(
-		field?.schema.kind === FieldKinds.sequence,
-		0x7fc /* Expected sequence field when hydrating array node */,
-	);
-	return (field as FlexTreeSequenceField<FlexAllowedTypes>).boxedAt(index);
-}
-
-function getMapChildNode(
-	mapNode: FlexTreeMapNode<FlexMapNodeSchema>,
-	key: string,
-): FlexTreeNode | undefined {
-	const field = mapNode.getBoxed(key);
-	assert(
-		field.schema.kind === FieldKinds.optional,
-		0x7fd /* Sequence field kind is unsupported as map values */,
-	);
-	return (field as FlexTreeOptionalField<FlexAllowedTypes>).boxedContent;
-}
-
-function getObjectChildNode(objectNode: FlexTreeObjectNode, key: string): FlexTreeNode | undefined {
-	const field =
-		objectNode.tryGetField(brand(key)) ?? fail("Expected a field for inserted content");
-	assert(
-		field.schema.kind === FieldKinds.required || field.schema.kind === FieldKinds.optional,
-		0x7fe /* Expected required or optional field kind */,
-	);
-	return (
-		field as FlexTreeRequiredField<FlexAllowedTypes> | FlexTreeOptionalField<FlexAllowedTypes>
-	).boxedContent;
-}
-
 /**
- * Run the given function `modify`.
- * If the function results in any changes to the direct children of `parent`, `after` will be run immediately thereafter.
+ * Brand `copy` with the type (under {@link typeNameSymbol}) to avoid ambiguity when inferring types from this data.
  */
-function modifyChildren<T extends FlexTreeNode>(
-	parent: T,
-	modify: (parent: T) => void,
-	after?: (parent: T) => void,
-): void {
-	const offNextChange = parent[onNextChange](() => after?.(parent));
-	modify(parent);
-	// `onNextChange` unsubscribes itself after firing once. However, there is no guarantee that it will fire.
-	// For example, the `modify` function may result in a no-op that doesn't trigger an edit (e.g. inserting `[]` into an array node).
-	// In those cases, we must unsubscribe manually here. If `modify` was not a no-op, it does no harm to call this function anyway.
-	offNextChange();
-}
-
-// TODO: Replace this with calls to `Tree.schema(node).kind` when dependency cycles are no longer a problem.
-function getNodeKind(node: TreeNode): NodeKind {
-	return (
-		getClassSchema(getFlexNode(node).schema)?.kind ??
-		fail("NodeBase should always have class schema")
-	);
+export function markContentType(typeName: TreeNodeSchemaIdentifier, copy: object): void {
+	Object.defineProperty(copy, typeNameSymbol, { value: typeName });
 }