@fluidframework/tree 2.1.1 → 2.2.1

package/src/simple-tree/arrayNode.ts

@@ -3,53 +3,51 @@
  * Licensed under the MIT License.
  */
 
-import {
-	CursorLocationType,
-	EmptyKey,
-	type ITreeCursorSynchronous,
-	type TreeNodeSchemaIdentifier,
-} from "../core/index.js";
+import { oob } from "@fluidframework/core-utils/internal";
+import { EmptyKey, type ExclusiveMapTree } from "../core/index.js";
 import {
 	type FlexAllowedTypes,
-	type FlexFieldNodeSchema,
+	type FlexTreeNodeSchema,
 	type FlexTreeNode,
 	type FlexTreeSequenceField,
 	type MapTreeNode,
-	cursorForMapTreeField,
 	getOrCreateMapTreeNode,
 	getSchemaAndPolicy,
-	isMapTreeNode,
 	isFlexTreeNode,
+	isMapTreeSequenceField,
 } from "../feature-libraries/index.js";
 import {
 	type InsertableContent,
-	getOrCreateNodeProxy,
-	markContentType,
+	getOrCreateNodeFromFlexTreeNode,
 	prepareContentForHydration,
 } from "./proxies.js";
-import { getFlexNode, getKernel } from "./proxyBinding.js";
+import { getOrCreateInnerNode } from "./proxyBinding.js";
+// This import seems to trigger a false positive `Type import "TreeNodeFromImplicitAllowedTypes" is used by decorator metadata` lint error.
+// Other ways to import (ex: import the module with the items as type imports) give different more real errors, and auto fix to this format,
+// so there does not seem to be a clean workaround to make the linter happy.
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports
+import type {
+	ImplicitAllowedTypes,
+	InsertableTreeNodeFromImplicitAllowedTypes,
+	TreeNodeFromImplicitAllowedTypes,
+} from "./schemaTypes.js";
 import {
-	NodeKind,
-	type ImplicitAllowedTypes,
-	type InsertableTreeNodeFromImplicitAllowedTypes,
-	type TreeNodeFromImplicitAllowedTypes,
-	type TreeNodeSchemaClass,
 	type WithType,
-	type TreeNodeSchema,
+	// eslint-disable-next-line import/no-deprecated
 	typeNameSymbol,
-	normalizeFieldSchema,
-} from "./schemaTypes.js";
-import { mapTreeFromNodeData } from "./toMapTree.js";
-import {
+	NodeKind,
 	type TreeNode,
-	TreeNodeValid,
 	type InternalTreeNode,
-	type MostDerivedData,
-} from "./types.js";
+	type TreeNodeSchemaClass,
+	type TreeNodeSchema,
+	typeSchemaSymbol,
+} from "./core/index.js";
+import { mapTreeFromNodeData } from "./toMapTree.js";
 import { fail } from "../util/index.js";
 import { getFlexSchema } from "./toFlexSchema.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { assert } from "@fluidframework/core-utils/internal";
+import { getKernel } from "./core/index.js";
+import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 
 /**
  * A generic array type, used to defined types like {@link (TreeArrayNode:interface)}.
@@ -294,7 +292,7 @@ function getSequenceField<
 	TTypes extends FlexAllowedTypes,
 	TSimpleType extends ImplicitAllowedTypes,
 >(arrayNode: TreeArrayNode<TSimpleType>): FlexTreeSequenceField<TTypes> {
-	return getFlexNode(arrayNode).getBoxed(EmptyKey) as FlexTreeSequenceField<TTypes>;
+	return getOrCreateInnerNode(arrayNode).getBoxed(EmptyKey) as FlexTreeSequenceField<TTypes>;
 }
 
 // For compatibility, we are initially implement 'readonly T[]' by applying the Array.prototype methods
@@ -564,7 +562,9 @@ function createArrayNodeProxy(
 			}
 
 			const maybeContent = field.at(maybeIndex);
-			return isFlexTreeNode(maybeContent) ? getOrCreateNodeProxy(maybeContent) : maybeContent;
+			return isFlexTreeNode(maybeContent)
+				? getOrCreateNodeFromFlexTreeNode(maybeContent)
+				: maybeContent;
 		},
 		set: (target, key, newValue, receiver) => {
 			if (key === "length") {
@@ -619,15 +619,12 @@ function createArrayNodeProxy(
 			const field = getSequenceField(proxy);
 			const maybeIndex = asIndex(key, field.length);
 			if (maybeIndex !== undefined) {
-				const val = field.boxedAt(maybeIndex);
+				const val = field.at(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.
+					value: isFlexTreeNode(val) ? getOrCreateNodeFromFlexTreeNode(val) : val,
+					writable: true, // For MVP, setting indexed properties is reported as allowed here (for deep equals compatibility noted above), but not actually supported.
 					enumerable: true,
 					configurable: true,
 				};
@@ -688,15 +685,8 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		});
 	}
 
-	#cursorFromFieldData(value: Insertable<T>): ITreeCursorSynchronous {
-		if (isMapTreeNode(getFlexNode(this))) {
-			throw new UsageError(`An array cannot be mutated before being inserted into the tree`);
-		}
-
+	#mapTreesFromFieldData(value: Insertable<T>): ExclusiveMapTree[] {
 		const sequenceField = getSequenceField(this);
-		// TODO: this is not valid since this is a value field schema, not a sequence one (which does not exist in the simple tree layer),
-		// but it works since cursorFromFieldData special cases arrays.
-		const simpleFieldSchema = normalizeFieldSchema(this.simpleSchema);
 		const content = value as readonly (
 			| InsertableContent
 			| IterableTreeArrayContent<InsertableContent>
@@ -709,14 +699,17 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			.map((c) =>
 				mapTreeFromNodeData(
 					c,
-					simpleFieldSchema.allowedTypes,
-					sequenceField.context.nodeKeyManager,
+					this.simpleSchema,
+					sequenceField.context?.nodeKeyManager,
 					getSchemaAndPolicy(sequenceField),
 				),
 			);
 
-		prepareContentForHydration(mapTrees, sequenceField.context.checkout.forest);
-		return cursorForMapTreeField(mapTrees);
+		if (sequenceField.context !== undefined) {
+			prepareContentForHydration(mapTrees, sequenceField.context.checkout.forest);
+		}
+
+		return mapTrees;
 	}
 
 	public toJSON(): unknown {
@@ -754,14 +747,13 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			return val;
 		}
 
-		return getOrCreateNodeProxy(val) as TreeNodeFromImplicitAllowedTypes<T>;
+		return getOrCreateNodeFromFlexTreeNode(val) as TreeNodeFromImplicitAllowedTypes<T>;
 	}
 	public insertAt(index: number, ...value: Insertable<T>): void {
 		const field = getSequenceField(this);
 		validateIndex(index, field, "insertAt", true);
-		const content = prepareFieldCursorForInsert(this.#cursorFromFieldData(value));
-		const fieldEditor = field.sequenceEditor();
-		fieldEditor.insert(index, content);
+		const content = this.#mapTreesFromFieldData(value);
+		field.editor.insert(index, content);
 	}
 	public insertAtStart(...value: Insertable<T>): void {
 		this.insertAt(0, ...value);
@@ -772,11 +764,10 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	public removeAt(index: number): void {
 		const field = getSequenceField(this);
 		validateIndex(index, field, "removeAt");
-		field.sequenceEditor().remove(index, 1);
+		field.editor.remove(index, 1);
 	}
 	public removeRange(start?: number, end?: number): void {
 		const field = getSequenceField(this);
-		const fieldEditor = field.sequenceEditor();
 		const { length } = field;
 		const removeStart = start ?? 0;
 		const removeEnd = Math.min(length, end ?? length);
@@ -786,7 +777,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			// This catches both the case where start is > array.length and when start is > end.
 			throw new UsageError('Too large of "start" value passed to TreeArrayNode.removeRange.');
 		}
-		fieldEditor.remove(removeStart, removeEnd - removeStart);
+		field.editor.remove(removeStart, removeEnd - removeStart);
 	}
 	public moveToStart(sourceIndex: number, source?: TreeArrayNode): void {
 		const sourceArray = source ?? this;
@@ -841,29 +832,55 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		source?: TreeArrayNode,
 	): void {
 		const destinationField = getSequenceField(this);
+		const sourceField = source !== undefined ? getSequenceField(source) : destinationField;
+
 		validateIndex(destinationIndex, destinationField, "moveRangeToIndex", true);
 		validateIndexRange(sourceStart, sourceEnd, source ?? destinationField, "moveRangeToIndex");
-		const sourceField = source !== undefined ? getSequenceField(source) : destinationField;
+
 		// TODO: determine support for move across different sequence types
 		if (destinationField.schema.types !== undefined && sourceField !== destinationField) {
 			for (let i = sourceStart; i < sourceEnd; i++) {
-				const sourceNode = sourceField.boxedAt(i) ?? fail("impossible out of bounds index");
+				const sourceNode = sourceField.boxedAt(i) ?? oob();
 				if (!destinationField.schema.types.has(sourceNode.schema.name)) {
 					throw new UsageError("Type in source sequence is not allowed in destination.");
 				}
 			}
 		}
+
 		const movedCount = sourceEnd - sourceStart;
-		const sourceFieldPath = sourceField.getFieldPath();
+		if (destinationField.context === undefined) {
+			if (!isMapTreeSequenceField(sourceField)) {
+				throw new UsageError(
+					"Cannot move elements from an inserted array to an array that has not yet been inserted",
+				);
+			}
 
-		const destinationFieldPath = destinationField.getFieldPath();
-		destinationField.context.checkout.editor.move(
-			sourceFieldPath,
-			sourceStart,
-			movedCount,
-			destinationFieldPath,
-			destinationIndex,
-		);
+			if (sourceField !== destinationField || destinationIndex < sourceStart) {
+				destinationField.editor.insert(
+					destinationIndex,
+					sourceField.editor.remove(sourceStart, movedCount),
+				);
+			} else if (destinationIndex > sourceStart + movedCount) {
+				destinationField.editor.insert(
+					destinationIndex - movedCount,
+					sourceField.editor.remove(sourceStart, movedCount),
+				);
+			}
+		} else {
+			if (sourceField.context === undefined) {
+				throw new UsageError(
+					"Cannot move elements from an array that has not yet been inserted to an inserted array",
+				);
+			}
+
+			destinationField.context.checkout.editor.move(
+				sourceField.getFieldPath(),
+				sourceStart,
+				movedCount,
+				destinationField.getFieldPath(),
+				destinationIndex,
+			);
+		}
 	}
 
 	public values(): IterableIterator<TreeNodeFromImplicitAllowedTypes<T>> {
@@ -889,6 +906,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
  *
  * @param name - Unique identifier for this schema including the factory's scope.
  */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function arraySchema<
 	TName extends string,
 	const T extends ImplicitAllowedTypes,
@@ -898,15 +916,16 @@ export function arraySchema<
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
 	customizable: boolean,
-): TreeNodeSchemaClass<
-	TName,
-	NodeKind.Array,
-	TreeArrayNode<T> & WithType<TName>,
-	Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
-	ImplicitlyConstructable,
-	T
-> {
-	let flexSchema: FlexFieldNodeSchema;
+) {
+	type Output = TreeNodeSchemaClass<
+		TName,
+		NodeKind.Array,
+		TreeArrayNode<T> & WithType<TName, NodeKind.Array>,
+		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
+		ImplicitlyConstructable,
+		T
+	>;
+	let flexSchema: FlexTreeNodeSchema;
 
 	// This class returns a proxy from its constructor to handle numeric indexing.
 	// Alternatively it could extend a normal class which gets tons of numeric properties added.
@@ -938,20 +957,14 @@ export function arraySchema<
 		): MapTreeNode {
 			return getOrCreateMapTreeNode(
 				flexSchema,
-				mapTreeFromNodeData(
-					copyContent(
-						flexSchema.name,
-						input as Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
-					) as object,
-					this as unknown as ImplicitAllowedTypes,
-				),
+				mapTreeFromNodeData(input as object, this as unknown as ImplicitAllowedTypes),
 			);
 		}
 
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup<T2>(this: typeof TreeNodeValid<T2>): void {
-			flexSchema = getFlexSchema(this as unknown as TreeNodeSchema) as FlexFieldNodeSchema;
+			flexSchema = getFlexSchema(this as unknown as TreeNodeSchema);
 
 			// First run, do extra validation.
 			// TODO: provide a way for TreeConfiguration to trigger this same validation to ensure it gets run early.
@@ -984,22 +997,21 @@ export function arraySchema<
 		public static readonly implicitlyConstructable: ImplicitlyConstructable =
 			implicitlyConstructable;
 
+		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}
+		public get [typeSchemaSymbol](): Output {
+			return schema.constructorCached?.constructor as unknown as Output;
+		}
 
 		protected get simpleSchema(): T {
 			return info;
 		}
 	}
 
-	return schema;
-}
-
-function copyContent<T>(typeName: TreeNodeSchemaIdentifier, content: Iterable<T>): T[] {
-	const copy = Array.from(content);
-	markContentType(typeName, copy);
-	return copy;
+	const output: Output = schema;
+	return output;
 }
 
 function validateSafeInteger(index: number): void {
@@ -1051,13 +1063,3 @@ function validateIndexRange(
 		);
 	}
 }
-
-/**
- * Prepare a fields cursor (holding a sequence of nodes) for inserting.
- */
-function prepareFieldCursorForInsert(cursor: ITreeCursorSynchronous): ITreeCursorSynchronous {
-	// TODO: optionally validate content against schema.
-
-	assert(cursor.mode === CursorLocationType.Fields, 0x9a8 /* should be in fields mode */);
-	return cursor;
-}

package/src/simple-tree/core/README.md

@@ -0,0 +1,11 @@
+# simple-tree core
+
+Core logic for simple tree.
+This is what the rest of simple-tree is build on, and thus to avoid cyclic deps, this should not depend on other parts of simple-tree.
+
+This specifically does not contain any logic specific to field kinds or node kinds (other than the NodeKinds enum definition which is required as part of TreeNodeSchema since the set of NodeKinds is not extensible): everything here should generically apply all of simple-tree's cases.
+
+## Status
+
+More content should be moved into this directory as its disentangled from node kind specific logic.
+`proxyBinding.ts` is a good candidate to work toward moving here to.

package/src/simple-tree/core/index.ts

@@ -0,0 +1,33 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	isTreeNode,
+	TreeNodeKernel,
+	getKernel,
+	tryGetTreeNodeSchema,
+} from "./treeNodeKernel.js";
+export { type WithType, typeNameSymbol, typeSchemaSymbol } from "./withType.js";
+export {
+	type TreeChangeEvents,
+	TreeNode,
+	type Unhydrated,
+	inPrototypeChain,
+	type InternalTreeNode,
+	privateToken,
+} from "./types.js";
+export {
+	type TreeNodeSchema,
+	NodeKind,
+	type TreeNodeSchemaClass,
+	type TreeNodeSchemaNonClass,
+	type TreeNodeSchemaCore,
+} from "./treeNodeSchema.js";
+export {
+	getSimpleNodeSchema,
+	setFlexSchemaFromClassSchema,
+	tryGetSimpleNodeSchema,
+	cachedFlexSchemaFromClassSchema,
+} from "./schemaCaching.js";

package/src/simple-tree/{schemaCaching.ts → core/schemaCaching.ts}

@@ -5,19 +5,10 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 
-import type {
-	FlexFieldSchema,
-	FlexTreeNodeSchema,
-	TreeNodeSchemaBase,
-} from "../feature-libraries/index.js";
-import { fail } from "../util/index.js";
+import type { FlexTreeNodeSchema, TreeNodeSchemaBase } from "../../feature-libraries/index.js";
+import { fail } from "../../util/index.js";
 
-import {
-	type FieldSchema,
-	type ImplicitFieldSchema,
-	type TreeNodeSchema,
-	normalizeFieldSchema,
-} from "./schemaTypes.js";
+import type { TreeNodeSchema } from "./treeNodeSchema.js";
 
 /**
  * A symbol for storing FlexTreeSchema on TreeNodeSchema.
@@ -30,11 +21,6 @@ const flexSchemaSymbol: unique symbol = Symbol(`flexSchema`);
  */
 const simpleNodeSchemaSymbol: unique symbol = Symbol(`simpleNodeSchema`);
 
-/**
- * A symbol for storing {@link FieldSchema}s on a {@link FlexFieldSchema}.
- */
-const simpleFieldSchemaSymbol: unique symbol = Symbol(`simpleFieldSchema`);
-
 export function cachedFlexSchemaFromClassSchema(
 	schema: TreeNodeSchema,
 ): TreeNodeSchemaBase | undefined {
@@ -74,23 +60,3 @@ export function tryGetSimpleNodeSchema(
 export function getSimpleNodeSchema(flexSchema: FlexTreeNodeSchema): TreeNodeSchema {
 	return tryGetSimpleNodeSchema(flexSchema) ?? fail("missing simple schema");
 }
-
-/**
- * Gets the {@link FieldSchema} which corresponds with the provided {@link FlexFieldSchema | flexSchema}.
- * Caches the result on the provided `flexSchema` for future access.
- * @param flexSchema - The flex schema on which the result will be cached.
- * @param implicitSimpleSchema - The allowed types from which the `FieldSchema` will be derived.
- */
-export function getSimpleFieldSchema(
-	flexSchema: FlexFieldSchema,
-	implicitSimpleSchema: ImplicitFieldSchema,
-): FieldSchema {
-	if (simpleFieldSchemaSymbol in flexSchema) {
-		return flexSchema[simpleFieldSchemaSymbol] as FieldSchema;
-	}
-
-	const fieldSchema = normalizeFieldSchema(implicitSimpleSchema);
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	(flexSchema as any)[simpleFieldSchemaSymbol] = fieldSchema;
-	return fieldSchema;
-}

package/src/simple-tree/{treeNodeKernel.ts → core/treeNodeKernel.ts}

@@ -4,16 +4,55 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { createEmitter, type Listenable, type Off } from "../events/index.js";
-import type { TreeChangeEvents, TreeNode } from "./types.js";
-import type { AnchorNode } from "../core/index.js";
+import { createEmitter, type Listenable, type Off } from "../../events/index.js";
+import type { TreeChangeEvents, TreeNode, Unhydrated } from "./types.js";
+import type { AnchorNode } from "../../core/index.js";
 import {
 	flexTreeSlot,
 	isFreedSymbol,
 	LazyEntity,
 	TreeStatus,
 	treeStatusFromAnchorCache,
-} from "../feature-libraries/index.js";
+} from "../../feature-libraries/index.js";
+import type { TreeNodeSchema } from "./treeNodeSchema.js";
+
+const treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();
+
+export function getKernel(node: TreeNode): TreeNodeKernel {
+	const kernel = treeNodeToKernel.get(node);
+	assert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);
+	return kernel;
+}
+
+/**
+ * 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.
+ */
+export function isTreeNode(candidate: unknown): candidate is TreeNode | Unhydrated<TreeNode> {
+	return treeNodeToKernel.has(candidate as TreeNode);
+}
+
+/**
+ * Returns a schema for a value if the value is a {@link TreeNode}.
+ *
+ * Returns undefined for other values.
+ * @remarks
+ * Does not give schema for a {@link TreeLeafValue}.
+ */
+export function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema {
+	const kernel = treeNodeToKernel.get(value as TreeNode);
+	return kernel?.schema;
+}
 
 /**
  * Contains state and an internal API for managing {@link TreeNode}s.
@@ -28,7 +67,18 @@ export class TreeNodeKernel implements Listenable<TreeChangeEvents> {
 	};
 	#events = createEmitter<TreeChangeEvents>();
 
-	public constructor(public readonly node: TreeNode) {}
+	/**
+	 * Create a TreeNodeKernel which can be looked up with {@link getKernel}.
+	 * @remarks
+	 * Exactly one kernel per TreeNode should be created.
+	 */
+	public constructor(
+		public readonly node: TreeNode,
+		public readonly schema: TreeNodeSchema,
+	) {
+		assert(!treeNodeToKernel.has(node), 0xa1a /* only one kernel per node can be made */);
+		treeNodeToKernel.set(node, this);
+	}
 
 	public hydrate(anchorNode: AnchorNode): void {
 		const offChildrenChanged = anchorNode.on("childrenChangedAfterBatch", () => {