@fluidframework/tree 2.1.1 → 2.2.1

package/src/simple-tree/objectNode.ts

@@ -3,11 +3,11 @@
  * Licensed under the MIT License.
  */
 
+import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { FieldKey, TreeNodeSchemaIdentifier } from "../core/index.js";
+import type { FieldKey } from "../core/index.js";
 import {
-	cursorForMapTreeNode,
 	FieldKinds,
 	type FlexAllowedTypes,
 	type FlexObjectNodeSchema,
@@ -22,36 +22,36 @@ import {
 } from "../feature-libraries/index.js";
 import {
 	type InsertableContent,
-	getProxyForField,
-	markContentType,
+	getTreeNodeForField,
 	prepareContentForHydration,
 } from "./proxies.js";
-import { getFlexNode } from "./proxyBinding.js";
+import { getOrCreateInnerNode } from "./proxyBinding.js";
 import {
-	NodeKind,
 	type ImplicitFieldSchema,
-	type TreeNodeSchemaClass,
-	type WithType,
-	type TreeNodeSchema,
 	getStoredKey,
 	getExplicitStoredKey,
 	type TreeFieldFromImplicitField,
 	type InsertableTreeFieldFromImplicitField,
 	type FieldSchema,
 	normalizeFieldSchema,
-	typeNameSymbol,
 	type ImplicitAllowedTypes,
 	FieldKind,
 } from "./schemaTypes.js";
-import { mapTreeFromNodeData } from "./toMapTree.js";
 import {
+	type TreeNodeSchema,
+	NodeKind,
+	type WithType,
+	// eslint-disable-next-line import/no-deprecated
+	typeNameSymbol,
+	typeSchemaSymbol,
 	type InternalTreeNode,
-	type MostDerivedData,
 	type TreeNode,
-	TreeNodeValid,
-} from "./types.js";
+} from "./core/index.js";
+import { mapTreeFromNodeData } from "./toMapTree.js";
 import { type RestrictiveReadonlyRecord, fail, type FlattenKeys } from "../util/index.js";
 import { getFlexSchema } from "./toFlexSchema.js";
+import type { ObjectNodeSchema, ObjectNodeSchemaInternalData } from "./objectNodeTypes.js";
+import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 
 /**
  * Helper used to produce types for object nodes.
@@ -77,7 +77,7 @@ export type ObjectFromSchemaRecord<
 export type TreeObjectNode<
 	T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,
 	TypeName extends string = string,
-> = TreeNode & ObjectFromSchemaRecord<T> & WithType<TypeName>;
+> = TreeNode & ObjectFromSchemaRecord<T> & WithType<TypeName, NodeKind.Object>;
 
 /**
  * Type utility for determining whether or not an implicit field schema has a default value.
@@ -128,7 +128,10 @@ export type InsertableObjectFromSchemaRecord<
  * Keys with symbols are currently never used, but allowed to make lookups on non-field things
  * (returning undefined) easier.
  */
-type SimpleKeyMap = ReadonlyMap<string | symbol, { storedKey: FieldKey; schema: FieldSchema }>;
+export type SimpleKeyMap = ReadonlyMap<
+	string | symbol,
+	{ storedKey: FieldKey; schema: FieldSchema }
+>;
 
 /**
  * Caches the mappings from view keys to stored keys for the provided object field schemas in {@link simpleKeyToFlexKeyCache}.
@@ -168,10 +171,10 @@ function createProxyHandler(
 			const fieldInfo = flexKeyMap.get(viewKey);
 
 			if (fieldInfo !== undefined) {
-				const flexNode = getFlexNode(proxy);
+				const flexNode = getOrCreateInnerNode(proxy);
 				const field = flexNode.tryGetField(fieldInfo.storedKey);
 				if (field !== undefined) {
-					return getProxyForField(field);
+					return getTreeNodeForField(field);
 				}
 
 				// Check if the user is trying to read an identifier field of an unhydrated node, but the identifier is not present.
@@ -196,14 +199,11 @@ function createProxyHandler(
 				return allowAdditionalProperties ? Reflect.set(target, viewKey, value, proxy) : false;
 			}
 
-			const flexNode = getFlexNode(proxy);
-			if (isMapTreeNode(flexNode)) {
-				throw new UsageError(
-					`An object cannot be mutated before being inserted into the tree`,
-				);
-			}
-
-			setField(flexNode.getBoxed(fieldInfo.storedKey), fieldInfo.schema, value);
+			setField(
+				getOrCreateInnerNode(proxy).getBoxed(fieldInfo.storedKey),
+				fieldInfo.schema,
+				value,
+			);
 			return true;
 		},
 		deleteProperty(target, viewKey): boolean {
@@ -237,10 +237,10 @@ function createProxyHandler(
 			// If a refactoring is done to associated flex tree data with the target not the proxy, this extra map could be removed,
 			// and the design would be more compatible with proxyless nodes.
 			const proxy = targetToProxy.get(target) ?? fail("missing proxy");
-			const field = getFlexNode(proxy).tryGetField(fieldInfo.storedKey);
+			const field = getOrCreateInnerNode(proxy).tryGetField(fieldInfo.storedKey);
 
 			const p: PropertyDescriptor = {
-				value: field === undefined ? undefined : getProxyForField(field),
+				value: field === undefined ? undefined : getTreeNodeForField(field),
 				writable: true,
 				// Report empty fields as own properties so they shadow inherited properties (even when empty) to match TypeScript typing.
 				// Make empty fields not enumerable so they get skipped when iterating over an object to better align with
@@ -260,22 +260,27 @@ export function setField(
 	simpleFieldSchema: FieldSchema,
 	value: InsertableContent | undefined,
 ): void {
+	const mapTree = mapTreeFromNodeData(
+		value,
+		simpleFieldSchema,
+		field.context?.nodeKeyManager,
+		getSchemaAndPolicy(field),
+	);
+
+	if (field.context !== undefined) {
+		prepareContentForHydration(mapTree, field.context.checkout.forest);
+	}
+
 	switch (field.schema.kind) {
-		case FieldKinds.required:
+		case FieldKinds.required: {
+			assert(mapTree !== undefined, 0xa04 /* Cannot set a required field to undefined */);
+			const typedField = field as FlexTreeRequiredField<FlexAllowedTypes>;
+			typedField.editor.set(mapTree);
+			break;
+		}
 		case FieldKinds.optional: {
-			const typedField = field as
-				| FlexTreeRequiredField<FlexAllowedTypes>
-				| FlexTreeOptionalField<FlexAllowedTypes>;
-
-			const mapTree = mapTreeFromNodeData(
-				value,
-				simpleFieldSchema.allowedTypes,
-				field.context.nodeKeyManager,
-				getSchemaAndPolicy(field),
-			);
-
-			prepareContentForHydration(mapTree, field.context.checkout.forest);
-			typedField.content = mapTree !== undefined ? cursorForMapTreeNode(mapTree) : undefined;
+			const typedField = field as FlexTreeOptionalField<FlexAllowedTypes>;
+			typedField.editor.set(mapTree, typedField.length === 0);
 			break;
 		}
 
@@ -304,7 +309,7 @@ export function objectSchema<
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
-): ObjectNodeSchema<TName, T, ImplicitlyConstructable> {
+): ObjectNodeSchema<TName, T, ImplicitlyConstructable> & ObjectNodeSchemaInternalData {
 	// Ensure no collisions between final set of view keys, and final set of stored keys (including those
 	// implicitly derived from view keys)
 	assertUniqueKeys(identifier, info);
@@ -318,7 +323,17 @@ export function objectSchema<
 
 	class CustomObjectNode extends CustomObjectNodeBase<T> {
 		public static readonly fields: ReadonlyMap<string, FieldSchema> = new Map(
-			[...flexKeyMap].map(([key, value]) => [key as string, value.schema]),
+			Array.from(flexKeyMap, ([key, value]) => [key as string, value.schema]),
+		);
+		public static readonly flexKeyMap: SimpleKeyMap = flexKeyMap;
+		public static readonly storedKeyToPropertyKey: ReadonlyMap<FieldKey, string> = new Map<
+			FieldKey,
+			string
+		>(
+			Array.from(flexKeyMap, ([key, value]): [FieldKey, string] => [
+				value.storedKey,
+				key as string,
+			]),
 		);
 
 		public static override prepareInstance<T2>(
@@ -358,10 +373,7 @@ export function objectSchema<
 		): MapTreeNode {
 			return getOrCreateMapTreeNode(
 				flexSchema,
-				mapTreeFromNodeData(
-					copyContent(flexSchema.name, input as object),
-					this as unknown as ImplicitAllowedTypes,
-				),
+				mapTreeFromNodeData(input as object, this as unknown as ImplicitAllowedTypes),
 			);
 		}
 
@@ -404,15 +416,19 @@ export function objectSchema<
 		public static readonly implicitlyConstructable: ImplicitlyConstructable =
 			implicitlyConstructable;
 
+		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}
+		public get [typeSchemaSymbol](): Output {
+			return CustomObjectNode.constructorCached?.constructor as unknown as Output;
+		}
 	}
-
-	return CustomObjectNode as typeof CustomObjectNode &
+	type Output = typeof CustomObjectNode &
 		(new (
 			input: InsertableObjectFromSchemaRecord<T> | InternalTreeNode,
 		) => TreeObjectNode<T, TName>);
+	return CustomObjectNode as Output;
 }
 
 const targetToProxy: WeakMap<object, TreeNode> = new WeakMap();
@@ -454,43 +470,3 @@ function assertUniqueKeys<
 		derivedStoredKeys.add(storedKey);
 	}
 }
-
-function copyContent<T extends object>(typeName: TreeNodeSchemaIdentifier, content: T): T {
-	const copy = { ...content };
-	markContentType(typeName, copy);
-	return copy;
-}
-
-/**
- * A schema for {@link TreeObjectNode}s.
- * @privateRemarks
- * This is a candidate for being promoted to the public package API.
- */
-export interface ObjectNodeSchema<
-	TName extends string = string,
-	T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema> = RestrictiveReadonlyRecord<
-		string,
-		ImplicitFieldSchema
-	>,
-	ImplicitlyConstructable extends boolean = boolean,
-> extends TreeNodeSchemaClass<
-		TName,
-		NodeKind.Object,
-		TreeObjectNode<T, TName>,
-		object & InsertableObjectFromSchemaRecord<T>,
-		ImplicitlyConstructable,
-		T
-	> {
-	readonly fields: ReadonlyMap<string, FieldSchema>;
-}
-
-export const ObjectNodeSchema = {
-	// instanceof-based narrowing support for Javascript and TypeScript 5.3 or newer.
-	[Symbol.hasInstance](value: TreeNodeSchema): value is ObjectNodeSchema {
-		return isObjectNodeSchema(value);
-	},
-} as const;
-
-export function isObjectNodeSchema(schema: TreeNodeSchema): schema is ObjectNodeSchema {
-	return schema.kind === NodeKind.Object;
-}

package/src/simple-tree/objectNodeTypes.ts

@@ -0,0 +1,68 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { RestrictiveReadonlyRecord } from "../util/index.js";
+import type {
+	TreeObjectNode,
+	InsertableObjectFromSchemaRecord,
+	SimpleKeyMap,
+} from "./objectNode.js";
+import type { ImplicitFieldSchema, FieldSchema } from "./schemaTypes.js";
+import { NodeKind, type TreeNodeSchemaClass, type TreeNodeSchema } from "./core/index.js";
+import type { FieldKey } from "../core/index.js";
+
+/**
+ * A schema for {@link TreeObjectNode}s.
+ * @privateRemarks
+ * This is a candidate for being promoted to the public package API.
+ */
+export interface ObjectNodeSchema<
+	TName extends string = string,
+	T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema> = RestrictiveReadonlyRecord<
+		string,
+		ImplicitFieldSchema
+	>,
+	ImplicitlyConstructable extends boolean = boolean,
+> extends TreeNodeSchemaClass<
+		TName,
+		NodeKind.Object,
+		TreeObjectNode<T, TName>,
+		object & InsertableObjectFromSchemaRecord<T>,
+		ImplicitlyConstructable,
+		T
+	> {
+	/**
+	 * From property keys to the associated schema.
+	 */
+	readonly fields: ReadonlyMap<string, FieldSchema>;
+}
+
+/**
+ * Extra data provided on all {@link ObjectNodeSchema} that is not included in the (soon possibly public) ObjectNodeSchema type.
+ */
+export interface ObjectNodeSchemaInternalData {
+	/**
+	 * {@inheritdoc SimpleKeyMap}
+	 */
+	readonly flexKeyMap: SimpleKeyMap;
+
+	/**
+	 * Lookup the property keys from the stored keys.
+	 */
+	readonly storedKeyToPropertyKey: ReadonlyMap<FieldKey, string>;
+}
+
+export const ObjectNodeSchema = {
+	// instanceof-based narrowing support for Javascript and TypeScript 5.3 or newer.
+	[Symbol.hasInstance](value: TreeNodeSchema): value is ObjectNodeSchema {
+		return isObjectNodeSchema(value);
+	},
+} as const;
+
+export function isObjectNodeSchema(
+	schema: TreeNodeSchema,
+): schema is ObjectNodeSchema & ObjectNodeSchemaInternalData {
+	return schema.kind === NodeKind.Object;
+}

package/src/simple-tree/proxies.ts

@@ -4,13 +4,13 @@
  */
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { assert } from "@fluidframework/core-utils/internal";
 
 import {
 	EmptyKey,
 	type IForestSubscription,
 	type MapTree,
-	type TreeNodeSchemaIdentifier,
 	type TreeValue,
 	type UpPath,
 } from "../core/index.js";
@@ -22,44 +22,26 @@ import {
 	type FlexTreeNode,
 	type FlexTreeTypedField,
 	tryGetMapTreeNode,
-	typeNameSymbol,
 	isFlexTreeNode,
 } from "../feature-libraries/index.js";
 import { type Mutable, fail, isReadonlyArray } from "../util/index.js";
 
-import { anchorProxy, tryGetFlexNode, tryGetProxy } from "./proxyBinding.js";
-import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
-import type { TreeNode, Unhydrated } from "./types.js";
+import { anchorProxy, tryGetCachedTreeNode } from "./proxyBinding.js";
+import { tryGetSimpleNodeSchema, type TreeNode, type Unhydrated } from "./core/index.js";
 
 /**
- * Detects if the given 'candidate' is a TreeNode.
- *
- * @remarks
- * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.
- *
- * Because the common usage is to check if a value being inserted/set is a TreeNode,
- * this function permits calling with primitives as well as objects.
- *
- * Primitives will always return false (as they are copies of data, not references to nodes).
- *
- * @param candidate - Value which may be a TreeNode
- * @returns true if the given 'candidate' is a hydrated TreeNode.
+ * Retrieve the associated {@link TreeNode} for the given field's content.
  */
-export function isTreeNode(candidate: unknown): candidate is TreeNode | Unhydrated<TreeNode> {
-	return tryGetFlexNode(candidate) !== undefined;
-}
-
-/**
- * Retrieve the associated proxy for the given field.
- * */
-export function getProxyForField(field: FlexTreeField): TreeNode | TreeValue | undefined {
+export function getTreeNodeForField(field: FlexTreeField): TreeNode | TreeValue | undefined {
 	function tryToUnboxLeaves(
 		flexField: FlexTreeTypedField<
 			FlexFieldSchema<typeof FieldKinds.required | typeof FieldKinds.optional>
 		>,
 	): TreeNode | TreeValue | undefined {
 		const maybeContent = flexField.content;
-		return isFlexTreeNode(maybeContent) ? getOrCreateNodeProxy(maybeContent) : maybeContent;
+		return isFlexTreeNode(maybeContent)
+			? getOrCreateNodeFromFlexTreeNode(maybeContent)
+			: maybeContent;
 	}
 	switch (field.schema.kind) {
 		case FieldKinds.required: {
@@ -74,12 +56,6 @@ export function getProxyForField(field: FlexTreeField): TreeNode | TreeValue | u
 			>;
 			return tryToUnboxLeaves(typedField);
 		}
-		// TODO: Remove if/when 'FieldNode' is removed.
-		case FieldKinds.sequence: {
-			// 'getProxyForNode' handles FieldNodes by unconditionally creating a array node proxy, making
-			// this case unreachable as long as users follow the 'array recipe'.
-			fail("'sequence' field is unexpected.");
-		}
 		case FieldKinds.identifier: {
 			// Identifier fields are just value fields that hold strings
 			return (field as FlexTreeTypedField<FlexFieldSchema<typeof FieldKinds.required>>)
@@ -91,8 +67,8 @@ export function getProxyForField(field: FlexTreeField): TreeNode | TreeValue | u
 	}
 }
 
-export function getOrCreateNodeProxy(flexNode: FlexTreeNode): TreeNode | TreeValue {
-	const cachedProxy = tryGetProxy(flexNode);
+export function getOrCreateNodeFromFlexTreeNode(flexNode: FlexTreeNode): TreeNode | TreeValue {
+	const cachedProxy = tryGetCachedTreeNode(flexNode);
 	if (cachedProxy !== undefined) {
 		return cachedProxy;
 	}
@@ -158,22 +134,23 @@ function prepareArrayContentForHydration(
 	content: readonly MapTree[],
 	forest: IForestSubscription,
 ): void {
-	const proxies: RootedProxyPaths[] = [];
-	for (let i = 0; i < content.length; i++) {
-		proxies.push({
+	const proxyPaths: RootedProxyPaths[] = [];
+	for (const item of content) {
+		const proxyPath: RootedProxyPaths = {
 			rootPath: {
 				parent: undefined,
 				parentField: EmptyKey,
 				parentIndex: 0,
 			},
 			proxyPaths: [],
-		});
-		walkMapTree(content[i], proxies[i].rootPath, (p, proxy) => {
-			proxies[i].proxyPaths.push({ path: p, proxy });
+		};
+		proxyPaths.push(proxyPath);
+		walkMapTree(item, proxyPath.rootPath, (p, proxy) => {
+			proxyPath.proxyPaths.push({ path: p, proxy });
 		});
 	}
 
-	bindProxies(proxies, forest);
+	bindProxies(proxyPaths, forest);
 }
 
 function walkMapTree(
@@ -181,25 +158,35 @@ function walkMapTree(
 	path: UpPath,
 	onVisitTreeNode: (path: UpPath, treeNode: TreeNode) => void,
 ): void {
-	const mapTreeNode = tryGetMapTreeNode(mapTree);
-	if (mapTreeNode !== undefined) {
-		const treeNode = tryGetProxy(mapTreeNode);
-		if (treeNode !== undefined) {
-			onVisitTreeNode(path, treeNode);
-		}
+	if (tryGetMapTreeNode(mapTree)?.parentField.parent.parent !== undefined) {
+		throw new UsageError(
+			"Attempted to insert a node which is already under a parent. If this is desired, remove the node from its parent before inserting it elsewhere.",
+		);
 	}
 
-	for (const [key, field] of mapTree.fields) {
-		for (let i = 0; i < field.length; i++) {
-			walkMapTree(
-				field[i],
-				{
-					parent: path,
-					parentField: key,
-					parentIndex: i,
-				},
-				onVisitTreeNode,
-			);
+	type Next = [path: UpPath, tree: MapTree];
+	const nexts: Next[] = [];
+	for (let next: Next | undefined = [path, mapTree]; next !== undefined; next = nexts.pop()) {
+		const [p, m] = next;
+		const mapTreeNode = tryGetMapTreeNode(m);
+		if (mapTreeNode !== undefined) {
+			const treeNode = tryGetCachedTreeNode(mapTreeNode);
+			if (treeNode !== undefined) {
+				onVisitTreeNode(p, treeNode);
+			}
+		}
+
+		for (const [key, field] of m.fields) {
+			for (const [i, child] of field.entries()) {
+				nexts.push([
+					{
+						parent: p,
+						parentField: key,
+						parentIndex: i,
+					},
+					child,
+				]);
+			}
 		}
 	}
 }
@@ -210,8 +197,12 @@ function bindProxies(proxies: RootedProxyPaths[], forest: IForestSubscription):
 		// 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) {
+			// Non null asserting here because of the length check above
+			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+			(proxies[i]!.rootPath as Mutable<UpPath>).parentField = fieldKey;
+			// Non null asserting here because of the length check above
+			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+			for (const { path, proxy } of proxies[i]!.proxyPaths) {
 				anchorProxy(forest.anchors, path, proxy);
 			}
 			if (++i === proxies.length) {
@@ -235,7 +226,7 @@ export type FactoryContent =
 	| boolean
 	// eslint-disable-next-line @rushstack/no-new-null
 	| null
-	| ReadonlyMap<string, InsertableContent>
+	| Iterable<readonly [string, InsertableContent]>
 	| readonly InsertableContent[]
 	| {
 			readonly [P in string]?: InsertableContent;
@@ -245,10 +236,3 @@ export type FactoryContent =
  * Content which can be inserted into a tree.
  */
 export type InsertableContent = Unhydrated<TreeNode> | FactoryContent;
-
-/**
- * Brand `copy` with the type (under {@link typeNameSymbol}) to avoid ambiguity when inferring types from this data.
- */
-export function markContentType(typeName: TreeNodeSchemaIdentifier, copy: object): void {
-	Object.defineProperty(copy, typeNameSymbol, { value: typeName });
-}