@fluidframework/tree 2.1.0 → 2.3.0-288113

package/src/simple-tree/mapNode.ts

@@ -3,38 +3,42 @@
  * Licensed under the MIT License.
  */
 
-import type { TreeNodeSchemaIdentifier } from "../core/index.js";
 import {
 	type FlexMapNodeSchema,
 	type FlexTreeNode,
 	type MapTreeNode,
-	cursorForMapTreeNode,
 	getOrCreateMapTreeNode,
 	getSchemaAndPolicy,
-	isMapTreeNode,
 } from "../feature-libraries/index.js";
 import {
+	type FactoryContent,
 	type InsertableContent,
-	getProxyForField,
-	markContentType,
+	getTreeNodeForField,
 	prepareContentForHydration,
 } from "./proxies.js";
-import { getFlexNode } from "./proxyBinding.js";
-import { getSimpleNodeSchema } from "./schemaCaching.js";
+import { getOrCreateInnerNode } from "./proxyBinding.js";
+import { getSimpleNodeSchema } from "./core/index.js";
 import {
-	NodeKind,
+	createFieldSchema,
+	FieldKind,
 	type ImplicitAllowedTypes,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
+	type TreeNodeFromImplicitAllowedTypes,
+} from "./schemaTypes.js";
+import {
+	NodeKind,
 	type TreeNodeSchemaClass,
-	type WithType,
 	type TreeNodeSchema,
-	type TreeNodeFromImplicitAllowedTypes,
+	type WithType,
+	// eslint-disable-next-line import/no-deprecated
 	typeNameSymbol,
-} from "./schemaTypes.js";
+	type TreeNode,
+	typeSchemaSymbol,
+} from "./core/index.js";
 import { mapTreeFromNodeData } from "./toMapTree.js";
-import { type MostDerivedData, type TreeNode, TreeNodeValid } from "./types.js";
 import { getFlexSchema } from "./toFlexSchema.js";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { brand, count, type RestrictiveReadonlyRecord } from "../util/index.js";
+import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 
 /**
  * A map of string keys to tree objects.
@@ -127,7 +131,7 @@ const handler: ProxyHandler<TreeMapNode> = {
 };
 
 abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends TreeNodeValid<
-	Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>
+	MapNodeInsertableData<T>
 > {
 	public static readonly kind = NodeKind.Map;
 
@@ -135,53 +139,50 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 		return this.entries();
 	}
 	public delete(key: string): void {
-		const node = getFlexNode(this);
-		if (isMapTreeNode(node)) {
-			throw new UsageError(`A map cannot be mutated before being inserted into the tree`);
-		}
-
-		node.delete(key);
+		const field = getOrCreateInnerNode(this).getBoxed(key);
+		field.editor.set(undefined, field.length === 0);
 	}
 	public *entries(): IterableIterator<[string, TreeNodeFromImplicitAllowedTypes<T>]> {
-		const node = getFlexNode(this);
+		const node = getOrCreateInnerNode(this);
 		for (const key of node.keys()) {
-			yield [key, getProxyForField(node.getBoxed(key)) as TreeNodeFromImplicitAllowedTypes<T>];
+			yield [
+				key,
+				getTreeNodeForField(node.getBoxed(key)) as TreeNodeFromImplicitAllowedTypes<T>,
+			];
 		}
 	}
 	public get(key: string): TreeNodeFromImplicitAllowedTypes<T> {
-		const node = getFlexNode(this);
+		const node = getOrCreateInnerNode(this);
 		const field = node.getBoxed(key);
-		return getProxyForField(field) as TreeNodeFromImplicitAllowedTypes<T>;
+		return getTreeNodeForField(field) as TreeNodeFromImplicitAllowedTypes<T>;
 	}
 	public has(key: string): boolean {
-		const node = getFlexNode(this);
-		return node.has(key);
+		return getOrCreateInnerNode(this).tryGetField(brand(key)) !== undefined;
 	}
 	public keys(): IterableIterator<string> {
-		const node = getFlexNode(this);
+		const node = getOrCreateInnerNode(this);
 		return node.keys();
 	}
 	public set(key: string, value: InsertableTreeNodeFromImplicitAllowedTypes<T>): TreeMapNode {
-		const node = getFlexNode(this);
-		if (isMapTreeNode(node)) {
-			throw new UsageError(`A map cannot be mutated before being inserted into the tree`);
-		}
-
+		const node = getOrCreateInnerNode(this);
 		const classSchema = getSimpleNodeSchema(node.schema);
 		const mapTree = mapTreeFromNodeData(
-			value as InsertableContent,
-			classSchema.info as ImplicitAllowedTypes,
-			node.context.nodeKeyManager,
+			value as InsertableContent | undefined,
+			createFieldSchema(FieldKind.Optional, classSchema.info as ImplicitAllowedTypes),
+			node.context?.nodeKeyManager,
 			getSchemaAndPolicy(node),
 		);
 
-		prepareContentForHydration(mapTree, node.context.checkout.forest);
-		const cursor = mapTree !== undefined ? cursorForMapTreeNode(mapTree) : undefined;
-		node.set(key, cursor);
+		const field = node.getBoxed(key);
+		if (node.context !== undefined) {
+			prepareContentForHydration(mapTree, node.context.checkout.forest);
+		}
+
+		field.editor.set(mapTree, field.length === 0);
 		return this;
 	}
 	public get size(): number {
-		return getFlexNode(this).size;
+		return count(getOrCreateInnerNode(this).keys());
 	}
 	public *values(): IterableIterator<TreeNodeFromImplicitAllowedTypes<T>> {
 		for (const [, value] of this.entries()) {
@@ -193,8 +194,8 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 		callbackFn: (value: TreeNodeFromImplicitAllowedTypes<T>, key: string, map: TThis) => void,
 		thisArg?: unknown,
 	): void {
-		for (const field of getFlexNode(this).boxedIterator()) {
-			const node = getProxyForField(field) as TreeNodeFromImplicitAllowedTypes<T>;
+		for (const field of getOrCreateInnerNode(this).boxedIterator()) {
+			const node = getTreeNodeForField(field) as TreeNodeFromImplicitAllowedTypes<T>;
 			callbackFn.call(thisArg, node, field.key, this);
 		}
 	}
@@ -239,10 +240,7 @@ export function mapSchema<
 		): MapTreeNode {
 			return getOrCreateMapTreeNode(
 				flexSchema,
-				mapTreeFromNodeData(
-					copyContent(flexSchema.name, input as Iterable<[string, InsertableContent]>),
-					this as unknown as ImplicitAllowedTypes,
-				),
+				mapTreeFromNodeData(input as FactoryContent, this as unknown as ImplicitAllowedTypes),
 			);
 		}
 
@@ -257,26 +255,29 @@ export function mapSchema<
 		public static readonly implicitlyConstructable: ImplicitlyConstructable =
 			implicitlyConstructable;
 
+		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}
+		public get [typeSchemaSymbol](): typeof schemaErased {
+			return schema.constructorCached?.constructor as unknown as typeof schemaErased;
+		}
 	}
 	const schemaErased: TreeNodeSchemaClass<
 		TName,
 		NodeKind.Map,
-		TreeMapNode<T> & WithType<TName>,
-		Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,
+		TreeMapNode<T> & WithType<TName, NodeKind.Map>,
+		MapNodeInsertableData<T>,
 		ImplicitlyConstructable,
 		T
 	> = schema;
 	return schemaErased;
 }
 
-function copyContent<T>(
-	typeName: TreeNodeSchemaIdentifier,
-	content: Iterable<[string, T]>,
-): Map<string, T> {
-	const copy = new Map(content);
-	markContentType(typeName, copy);
-	return copy;
-}
+/**
+ * Content which can be used to construct a Map node, explicitly or implicitly.
+ * @system @public
+ */
+export type MapNodeInsertableData<T extends ImplicitAllowedTypes> =
+	| Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>
+	| RestrictiveReadonlyRecord<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>;

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;
+}