@fluidframework/tree 2.2.0 → 2.3.0

package/src/simple-tree/api/treeNodeApi.ts

@@ -5,7 +5,7 @@
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
 
-import { Multiplicity, rootFieldKey } from "../../core/index.js";
+import { EmptyKey, rootFieldKey } from "../../core/index.js";
 import {
 	type LazyItem,
 	type TreeStatus,
@@ -13,6 +13,7 @@ import {
 	isTreeValue,
 	FlexObjectNodeSchema,
 	isMapTreeNode,
+	FieldKinds,
 } from "../../feature-libraries/index.js";
 import { fail, extractFromOpaque, isReadonlyArray } from "../../util/index.js";
 
@@ -44,6 +45,7 @@ import {
 	type TreeChangeEvents,
 	tryGetTreeNodeSchema,
 } from "../core/index.js";
+import { isObjectNodeSchema } from "../objectNodeTypes.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -155,19 +157,50 @@ export const treeNodeApi: TreeNodeApi = {
 		}
 
 		// The flex-domain strictly operates in terms of "stored keys".
-		// To find the associated developer-facing "view key", we need to look up the field associated with
-		// the stored key from the flex-domain, and get view key its simple-domain counterpart was created with.
+		// To find the associated developer-facing "property key", we need to look up the field associated with
+		// the stored key from the flex-domain, and get property key its simple-domain counterpart was created with.
 		const storedKey = getStoredKey(node);
 		const parentSchema = treeNodeApi.schema(parent);
-		const viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);
-		return viewKey;
+		const propertyKey = getPropertyKeyFromStoredKey(parentSchema, storedKey);
+		return propertyKey;
 	},
 	on<K extends keyof TreeChangeEvents>(
 		node: TreeNode,
 		eventName: K,
 		listener: TreeChangeEvents[K],
 	): Off {
-		return getKernel(node).on(eventName, listener);
+		const kernel = getKernel(node);
+		switch (eventName) {
+			case "nodeChanged": {
+				const nodeSchema = kernel.schema;
+				if (isObjectNodeSchema(nodeSchema)) {
+					return kernel.on("childrenChangedAfterBatch", ({ changedFields }) => {
+						const changedProperties = new Set(
+							Array.from(
+								changedFields,
+								(field) =>
+									nodeSchema.storedKeyToPropertyKey.get(field) ??
+									fail(`Could not find stored key '${field}' in schema.`),
+							),
+						);
+						listener({ changedProperties });
+					});
+				} else if (nodeSchema.kind === NodeKind.Array) {
+					return kernel.on("childrenChangedAfterBatch", () => {
+						listener({ changedProperties: undefined });
+					});
+				} else {
+					return kernel.on("childrenChangedAfterBatch", ({ changedFields }) => {
+						listener({ changedProperties: changedFields });
+					});
+				}
+			}
+			case "treeChanged": {
+				return kernel.on("subtreeChangedAfterBatch", () => listener({}));
+			}
+			default:
+				throw new UsageError(`No event named ${JSON.stringify(eventName)}.`);
+		}
 	},
 	status(node: TreeNode): TreeStatus {
 		return getKernel(node).getStatus();
@@ -199,7 +232,7 @@ export const treeNodeApi: TreeNodeApi = {
 	},
 	shortId(node: TreeNode): number | string | undefined {
 		const flexNode = getOrCreateInnerNode(node);
-		const flexSchema = flexNode.schema;
+		const flexSchema = flexNode.flexSchema;
 		const identifierFieldKeys =
 			flexSchema instanceof FlexObjectNodeSchema ? flexSchema.identifierFieldKeys : [];
 
@@ -216,7 +249,10 @@ export const treeNodeApi: TreeNodeApi = {
 					}
 					return identifier.value as string;
 				}
-				assert(identifier?.context !== undefined, 0xa12 /* Expected LazyIdentifierField */);
+				assert(
+					identifier?.context.isHydrated() === true,
+					0xa27 /* Expected hydrated identifier */,
+				);
 				const identifierValue = identifier.value as string;
 
 				const localNodeKey =
@@ -245,7 +281,7 @@ export function tryGetSchema(value: unknown): undefined | TreeNodeSchema {
 			return booleanSchema;
 		case "object": {
 			if (isTreeNode(value)) {
-				// This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.
+				// TODO: This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.
 				return tryGetTreeNodeSchema(value);
 			}
 			if (value === null) {
@@ -265,26 +301,31 @@ export function tryGetSchema(value: unknown): undefined | TreeNodeSchema {
  */
 function getStoredKey(node: TreeNode): string | number {
 	// Note: the flex domain strictly works with "stored keys", and knows nothing about the developer-facing
-	// "view keys".
+	// "property keys".
 	const parentField = getOrCreateInnerNode(node).parentField;
-	if (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {
+	if (parentField.parent.schema.kind === FieldKinds.sequence.identifier) {
 		// The parent of `node` is an array node
+		assert(
+			parentField.parent.key === EmptyKey,
+			0xa28 /* When using index as key, field should use EmptyKey */,
+		);
 		return parentField.index;
 	}
 
 	// The parent of `node` is an object, a map, or undefined. If undefined, then `node` is a root/detached node.
+	assert(parentField.index === 0, 0xa29 /* When using field key as key, index should be 0 */);
 	return parentField.parent.key;
 }
 
 /**
- * Given a node schema, gets the view key corresponding with the provided {@link FieldProps.key | stored key}.
+ * Given a node schema, gets the property key corresponding with the provided {@link FieldProps.key | stored key}.
  */
-function getViewKeyFromStoredKey(
+function getPropertyKeyFromStoredKey(
 	schema: TreeNodeSchema,
 	storedKey: string | number,
 ): string | number {
-	// Only object nodes have the concept of a "stored key", differentiated from the developer-facing "view key".
-	// For any other kind of node, the stored key and the view key are the same.
+	// Only object nodes have the concept of a "stored key", differentiated from the developer-facing "property key".
+	// For any other kind of node, the stored key and the property key are the same.
 	if (schema.kind !== NodeKind.Object) {
 		return storedKey;
 	}
@@ -292,18 +333,18 @@ function getViewKeyFromStoredKey(
 	const fields = schema.info as Record<string, ImplicitFieldSchema>;
 
 	// Invariants:
-	// - The set of all view keys under an object must be unique.
-	// - The set of all stored keys (including those implicitly created from view keys) must be unique.
-	// To find the view key associated with the provided stored key, first check for any stored key matches (which are optionally populated).
-	// If we don't find any, then search for a matching view key.
-	for (const [viewKey, fieldSchema] of Object.entries(fields)) {
+	// - The set of all property keys under an object must be unique.
+	// - The set of all stored keys (including those implicitly created from property keys) must be unique.
+	// To find the property key associated with the provided stored key, first check for any stored key matches (which are optionally populated).
+	// If we don't find any, then search for a matching property key.
+	for (const [propertyKey, fieldSchema] of Object.entries(fields)) {
 		if (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {
-			return viewKey;
+			return propertyKey;
 		}
 	}
 
 	if (fields[storedKey] === undefined) {
-		fail("Existing stored key should always map to a view key");
+		fail("Existing stored key should always map to a property key");
 	}
 
 	return storedKey;

package/src/simple-tree/api/verboseTree.ts

@@ -41,7 +41,7 @@ import {
 } from "../leafNodeSchema.js";
 import { toFlexSchema } from "../toFlexSchema.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
-import { walkFieldSchema } from "./tree.js";
+import { walkFieldSchema } from "../walkSchema.js";
 
 /**
  * Verbose encoding of a {@link TreeNode} or {@link TreeValue}.

package/src/simple-tree/{viewSchemaToSimpleSchema.ts → api/viewSchemaToSimpleSchema.ts}

@@ -8,7 +8,7 @@ import {
 	normalizeFieldSchema,
 	type FieldSchema,
 	type ImplicitAllowedTypes,
-} from "./schemaTypes.js";
+} from "../schemaTypes.js";
 import type {
 	SimpleArrayNodeSchema,
 	SimpleFieldSchema,
@@ -18,10 +18,10 @@ import type {
 	SimpleObjectNodeSchema,
 	SimpleTreeSchema,
 } from "./simpleSchema.js";
-import type { ValueSchema } from "../core/index.js";
-import { getOrCreate } from "../util/index.js";
-import { isObjectNodeSchema, type ObjectNodeSchema } from "./objectNodeTypes.js";
-import { NodeKind, type TreeNodeSchema } from "./core/index.js";
+import type { ValueSchema } from "../../core/index.js";
+import { getOrCreate } from "../../util/index.js";
+import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js";
+import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 
 /**
  * Converts a "view" schema to a "simple" schema representation.

package/src/simple-tree/arrayNode.ts

@@ -4,9 +4,10 @@
  */
 
 import { oob } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
 import { EmptyKey, type ExclusiveMapTree } from "../core/index.js";
 import {
-	type FlexAllowedTypes,
 	type FlexTreeNodeSchema,
 	type FlexTreeNode,
 	type FlexTreeSequenceField,
@@ -15,12 +16,9 @@ import {
 	getSchemaAndPolicy,
 	isFlexTreeNode,
 	isMapTreeSequenceField,
+	UnhydratedContext,
 } from "../feature-libraries/index.js";
-import {
-	type InsertableContent,
-	getOrCreateNodeFromFlexTreeNode,
-	prepareContentForHydration,
-} from "./proxies.js";
+import { getOrCreateNodeFromFlexTreeNode, prepareContentForHydration } from "./proxies.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,
@@ -42,10 +40,9 @@ import {
 	type TreeNodeSchema,
 	typeSchemaSymbol,
 } from "./core/index.js";
-import { mapTreeFromNodeData } from "./toMapTree.js";
+import { type InsertableContent, mapTreeFromNodeData } from "./toMapTree.js";
 import { fail } from "../util/index.js";
-import { getFlexSchema } from "./toFlexSchema.js";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { getFlexSchema, toFlexSchema } from "./toFlexSchema.js";
 import { getKernel } from "./core/index.js";
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 
@@ -55,7 +52,7 @@ import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
  * @privateRemarks
  * Inlining this into TreeArrayNode causes recursive array use to stop compiling.
  *
- * @sealed @public
+ * @system @sealed @public
  */
 export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom>
 	extends ReadonlyArray<T>,
@@ -288,11 +285,10 @@ export class IterableTreeArrayContent<T> implements Iterable<T> {
 /**
  * Given a array node proxy, returns its underlying LazySequence field.
  */
-function getSequenceField<
-	TTypes extends FlexAllowedTypes,
-	TSimpleType extends ImplicitAllowedTypes,
->(arrayNode: TreeArrayNode<TSimpleType>): FlexTreeSequenceField<TTypes> {
-	return getOrCreateInnerNode(arrayNode).getBoxed(EmptyKey) as FlexTreeSequenceField<TTypes>;
+function getSequenceField<TSimpleType extends ImplicitAllowedTypes>(
+	arrayNode: TreeArrayNode<TSimpleType>,
+): FlexTreeSequenceField {
+	return getOrCreateInnerNode(arrayNode).getBoxed(EmptyKey) as FlexTreeSequenceField;
 }
 
 // For compatibility, we are initially implement 'readonly T[]' by applying the Array.prototype methods
@@ -670,19 +666,10 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 
 	protected abstract get simpleSchema(): T;
 
-	/**
-	 * Generation number which is incremented any time we have an edit on the node.
-	 * Used during iteration to make sure there has been no edits that were concurrently made.
-	 */
-	#generationNumber: number = 0;
-
 	public constructor(
 		input: Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>> | InternalTreeNode,
 	) {
 		super(input);
-		getKernel(this).on("nodeChanged", () => {
-			this.#generationNumber += 1;
-		});
 	}
 
 	#mapTreesFromFieldData(value: Insertable<T>): ExclusiveMapTree[] {
@@ -700,12 +687,14 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 				mapTreeFromNodeData(
 					c,
 					this.simpleSchema,
-					sequenceField.context?.nodeKeyManager,
+					sequenceField.context.isHydrated()
+						? sequenceField.context.nodeKeyManager
+						: undefined,
 					getSchemaAndPolicy(sequenceField),
 				),
 			);
 
-		if (sequenceField.context !== undefined) {
+		if (sequenceField.context.isHydrated()) {
 			prepareContentForHydration(mapTrees, sequenceField.context.checkout.forest);
 		}
 
@@ -838,20 +827,20 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		validateIndexRange(sourceStart, sourceEnd, source ?? destinationField, "moveRangeToIndex");
 
 		// TODO: determine support for move across different sequence types
-		if (destinationField.schema.types !== undefined && sourceField !== destinationField) {
+		if (sourceField !== destinationField) {
 			for (let i = sourceStart; i < sourceEnd; i++) {
 				const sourceNode = sourceField.boxedAt(i) ?? oob();
-				if (!destinationField.schema.types.has(sourceNode.schema.name)) {
+				if (!destinationField.schema.types.has(sourceNode.schema)) {
 					throw new UsageError("Type in source sequence is not allowed in destination.");
 				}
 			}
 		}
 
 		const movedCount = sourceEnd - sourceStart;
-		if (destinationField.context === undefined) {
+		if (!destinationField.context.isHydrated()) {
 			if (!isMapTreeSequenceField(sourceField)) {
 				throw new UsageError(
-					"Cannot move elements from an inserted array to an array that has not yet been inserted",
+					"Cannot move elements from an unhydrated array to a hydrated array.",
 				);
 			}
 
@@ -867,11 +856,14 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 				);
 			}
 		} else {
-			if (sourceField.context === undefined) {
+			if (!sourceField.context.isHydrated()) {
 				throw new UsageError(
-					"Cannot move elements from an array that has not yet been inserted to an inserted array",
+					"Cannot move elements from an unhydrated array to a hydrated array.",
 				);
 			}
+			if (sourceField.context !== destinationField.context) {
+				throw new UsageError("Cannot move elements between two different TreeViews.");
+			}
 
 			destinationField.context.checkout.editor.move(
 				sourceField.getFieldPath(),
@@ -884,17 +876,18 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	}
 
 	public values(): IterableIterator<TreeNodeFromImplicitAllowedTypes<T>> {
-		return this.generateValues(this.#generationNumber);
+		return this.generateValues(getKernel(this).generationNumber);
 	}
 	private *generateValues(
 		initialLastUpdatedStamp: number,
 	): Generator<TreeNodeFromImplicitAllowedTypes<T>> {
-		if (initialLastUpdatedStamp !== this.#generationNumber) {
+		const kernel = getKernel(this);
+		if (initialLastUpdatedStamp !== kernel.generationNumber) {
 			throw new UsageError(`Concurrent editing and iteration is not allowed.`);
 		}
 		for (let i = 0; i < this.length; i++) {
 			yield this.at(i) ?? fail("Index is out of bounds");
-			if (initialLastUpdatedStamp !== this.#generationNumber) {
+			if (initialLastUpdatedStamp !== kernel.generationNumber) {
 				throw new UsageError(`Concurrent editing and iteration is not allowed.`);
 			}
 		}
@@ -926,10 +919,11 @@ export function arraySchema<
 		T
 	>;
 	let flexSchema: FlexTreeNodeSchema;
+	let unhydratedContext: UnhydratedContext;
 
 	// 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.
-	class schema extends CustomArrayNodeBase<T> {
+	class Schema extends CustomArrayNodeBase<T> {
 		public static override prepareInstance<T2>(
 			this: typeof TreeNodeValid<T2>,
 			instance: TreeNodeValid<T2>,
@@ -947,7 +941,7 @@ export function arraySchema<
 					configurable: false,
 				});
 			}
-			return createArrayNodeProxy(customizable, proxyTarget, instance) as unknown as schema;
+			return createArrayNodeProxy(customizable, proxyTarget, instance) as unknown as Schema;
 		}
 
 		public static override buildRawNode<T2>(
@@ -956,6 +950,7 @@ export function arraySchema<
 			input: T2,
 		): MapTreeNode {
 			return getOrCreateMapTreeNode(
+				unhydratedContext,
 				flexSchema,
 				mapTreeFromNodeData(input as object, this as unknown as ImplicitAllowedTypes),
 			);
@@ -964,7 +959,9 @@ export function arraySchema<
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup<T2>(this: typeof TreeNodeValid<T2>): void {
-			flexSchema = getFlexSchema(this as unknown as TreeNodeSchema);
+			const schema = this as unknown as TreeNodeSchema;
+			flexSchema = getFlexSchema(schema);
+			unhydratedContext = new UnhydratedContext(toFlexSchema(schema));
 
 			// First run, do extra validation.
 			// TODO: provide a way for TreeConfiguration to trigger this same validation to ensure it gets run early.
@@ -972,7 +969,7 @@ export function arraySchema<
 			{
 				let prototype: object = this.prototype;
 				// There isn't a clear cleaner way to author this loop.
-				while (prototype !== schema.prototype) {
+				while (prototype !== Schema.prototype) {
 					// Search prototype keys and check for positive integers. Throw if any are found.
 					// Shadowing of index properties on array nodes is not supported.
 					for (const key of Object.getOwnPropertyNames(prototype)) {
@@ -1002,7 +999,7 @@ export function arraySchema<
 			return identifier;
 		}
 		public get [typeSchemaSymbol](): Output {
-			return schema.constructorCached?.constructor as unknown as Output;
+			return Schema.constructorCached?.constructor as unknown as Output;
 		}
 
 		protected get simpleSchema(): T {
@@ -1010,7 +1007,7 @@ export function arraySchema<
 		}
 	}
 
-	const output: Output = schema;
+	const output: Output = Schema;
 	return output;
 }
 

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

@@ -8,6 +8,9 @@ export {
 	TreeNodeKernel,
 	getKernel,
 	tryGetTreeNodeSchema,
+	type InnerNode,
+	tryGetCachedTreeNode,
+	tryDisposeTreeNode,
 } from "./treeNodeKernel.js";
 export { type WithType, typeNameSymbol, typeSchemaSymbol } from "./withType.js";
 export {
@@ -30,4 +33,5 @@ export {
 	setFlexSchemaFromClassSchema,
 	tryGetSimpleNodeSchema,
 	cachedFlexSchemaFromClassSchema,
+	getSimpleNodeSchemaFromNode,
 } from "./schemaCaching.js";

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

@@ -9,6 +9,7 @@ import type { FlexTreeNodeSchema, TreeNodeSchemaBase } from "../../feature-libra
 import { fail } from "../../util/index.js";
 
 import type { TreeNodeSchema } from "./treeNodeSchema.js";
+import type { InnerNode } from "./treeNodeKernel.js";
 
 /**
  * A symbol for storing FlexTreeSchema on TreeNodeSchema.
@@ -60,3 +61,12 @@ export function tryGetSimpleNodeSchema(
 export function getSimpleNodeSchema(flexSchema: FlexTreeNodeSchema): TreeNodeSchema {
 	return tryGetSimpleNodeSchema(flexSchema) ?? fail("missing simple schema");
 }
+
+/**
+ * Gets the {@link TreeNodeSchema} for the {@link InnerNode}.
+ */
+export function getSimpleNodeSchemaFromNode(innerNode: InnerNode): TreeNodeSchema {
+	// TODO: to make this work without depending on flex tree schema, a new caching/lookup mechanism will be required, likely leveraging the FlexTreeContext:
+	// A SimpleTreeContext could be defined and associated with the FlexTreeContext, and used to look up simple-tree schema by identifier.
+	return getSimpleNodeSchema(innerNode.flexSchema);
+}