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

package/src/simple-tree/toMapTree.ts

@@ -3,35 +3,39 @@
  * Licensed under the MIT License.
  */
 
-import { IFluidHandle } from "@fluidframework/core-interfaces";
-import { assert } from "@fluidframework/core-utils";
-import { UsageError } from "@fluidframework/telemetry-utils";
-
-import { EmptyKey, type FieldKey, type MapTree } from "../core/index.js";
-// Drilling into `domains` to reduce the magnitude of cycles introduced here
-// eslint-disable-next-line import/no-internal-modules
-import { leaf } from "../domains/leafDomain.js";
+import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import {
+	EmptyKey,
+	type FieldKey,
+	type MapTree,
+	type TreeValue,
+	ValueSchema,
+} from "../core/index.js";
 import {
-	allowsValue,
+	type CursorWithNode,
 	cursorForMapTreeField,
 	cursorForMapTreeNode,
-	type CursorWithNode,
-	isFluidHandle,
-	Multiplicity,
-	type FlexTreeNodeSchema,
-	FlexTreeSchema,
-	type AllowedTypeSet,
-	FlexFieldSchema,
-	Any,
-	FlexFieldNodeSchema,
 	isTreeValue,
-	LeafNodeSchema,
-	FlexMapNodeSchema,
-	getAllowedTypes,
 	typeNameSymbol,
+	valueSchemaAllows,
 } from "../feature-libraries/index.js";
-import { brand, isReadonlyArray } from "../util/index.js";
+import { brand, fail, isReadonlyArray } from "../util/index.js";
+
+import { nullSchema } from "./leafNodeSchema.js";
 import { InsertableContent } from "./proxies.js";
+import {
+	FieldKind,
+	FieldSchema,
+	type ImplicitAllowedTypes,
+	type ImplicitFieldSchema,
+	NodeKind,
+	type TreeNodeSchema,
+	normalizeAllowedTypes,
+	normalizeFieldSchema,
+	getStoredKey,
+} from "./schemaTypes.js";
 
 /**
  * Module notes:
@@ -47,36 +51,33 @@ import { InsertableContent } from "./proxies.js";
 /**
  * Transforms an input {@link TypedNode} tree to a {@link MapTree}, and wraps the tree in a {@link CursorWithNode}.
  * @param data - The input tree to be converted.
- * @param globalSchema - Schema for the whole tree for interperting `Any`.
- * @param typeSet - The set of types allowed by the parent context. Used to validate the input tree.
+ * @param allowedTypes - The set of types allowed by the parent context. Used to validate the input tree.
  *
  * @returns A cursor (in nodes mode) for the mapped tree if the input data was defined. Otherwise, returns `undefined`.
  */
 export function cursorFromNodeData(
 	data: InsertableContent,
-	globalSchema: FlexTreeSchema,
-	typeSet: AllowedTypeSet,
+	allowedTypes: ImplicitAllowedTypes,
 ): CursorWithNode<MapTree> | undefined {
 	if (data === undefined) {
 		return undefined;
 	}
-	const mappedContent = nodeDataToMapTree(data, globalSchema, typeSet);
+	const mappedContent = nodeDataToMapTree(data, normalizeAllowedTypes(allowedTypes));
 	return cursorForMapTreeNode(mappedContent);
 }
 
-type InsertableTreeField = InsertableContent | undefined | InsertableContent[];
-
 /**
- * Transforms an input {@link TreeField} tree to an array of {@link MapTree}s, and wraps the tree in a {@link CursorWithNode}.
+ * Transforms an input {@link InsertableContent} tree to an array of {@link MapTree}s, and wraps the tree in a {@link CursorWithNode}.
  * @param data - The input tree to be converted.
- * @param globalSchema - Schema for the whole tree for interperting `Any`.
+ * @param schema - Schema of the field with which the input `data` is associated.
  */
 export function cursorFromFieldData(
-	data: InsertableTreeField,
-	globalSchema: FlexTreeSchema,
-	fieldSchema: FlexFieldSchema,
+	data: InsertableContent,
+	schema: FieldSchema,
 ): CursorWithNode<MapTree> {
-	const mappedContent = fieldDataToMapTrees(data, globalSchema, fieldSchema);
+	const mappedContent = Array.isArray(data)
+		? arrayToMapTreeFields(data, schema.allowedTypeSet)
+		: [nodeDataToMapTree(data, schema.allowedTypeSet)];
 	return cursorForMapTreeField(mappedContent);
 }
 
@@ -94,107 +95,62 @@ export function cursorFromFieldData(
  *
  * * `-0` =\> `+0`
  *
- * @param globalSchema - Schema for the whole tree for interperting `Any`.
- * @param typeSet - The set of types allowed by the parent context. Used to validate the input tree.
+ * @param data - The tree data being transformed.
+ * @param allowedTypes - The set of types allowed by the parent context. Used to validate the input tree.
  */
 export function nodeDataToMapTree(
 	data: InsertableContent,
-	globalSchema: FlexTreeSchema,
-	typeSet: AllowedTypeSet,
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
 ): MapTree {
 	assert(data !== undefined, 0x846 /* Cannot map undefined tree. */);
 
-	if (data === null) {
-		return valueToMapTree(data, globalSchema, typeSet);
-	}
-	switch (typeof data) {
-		case "number":
-		case "string":
-		case "boolean":
-			return valueToMapTree(data, globalSchema, typeSet);
-		default: {
-			if (isFluidHandle(data)) {
-				return valueToMapTree(data, globalSchema, typeSet);
-			} else if (Array.isArray(data)) {
-				return arrayToMapTree(data, globalSchema, typeSet);
-			} else if (data instanceof Map) {
-				return mapToMapTree(data, globalSchema, typeSet);
-			} else {
-				// Assume record-like object
-				return recordToMapTree(
-					data as Record<string, InsertableContent>,
-					globalSchema,
-					typeSet,
-				);
-			}
-		}
+	const schema = getType(data, allowedTypes);
+
+	switch (schema.kind) {
+		case NodeKind.Leaf:
+			return leafToMapTree(data, schema, allowedTypes);
+		case NodeKind.Array:
+			return arrayToMapTree(data, schema);
+		case NodeKind.Map:
+			return mapToMapTree(data, schema);
+		case NodeKind.Object:
+			return objectToMapTree(data, schema);
+		default:
+			fail(`Unrecognized schema kind: ${schema.kind}.`);
 	}
 }
 
 /**
- * Transforms an input {@link TreeField} tree to an array of {@link MapTree}s.
- * @param data - The input tree to be converted.
- * If the input is a sequence containing 1 or more `undefined` values, those values will be mapped as `null` if supported.
- * Othewise, an error will be thrown.
- * @param globalSchema - Schema for the whole tree. Used to select the valid types when encountering `any`.
+ * Transforms data under a Leaf schema.
+ * @param data - The tree data to be transformed. Must be a {@link TreeValue}.
+ * @param schema - The schema associated with the value.
+ * @param allowedTypes - The allowed types specified by the parent.
+ * Used to determine which fallback values may be appropriate.
  */
-export function fieldDataToMapTrees(
-	data: InsertableTreeField,
-	globalSchema: FlexTreeSchema,
-	fieldSchema: FlexFieldSchema,
-): MapTree[] {
-	const multiplicity = fieldSchema.kind.multiplicity;
-	if (data === undefined) {
-		assert(
-			multiplicity === Multiplicity.Forbidden || multiplicity === Multiplicity.Optional,
-			0x847 /* `undefined` provided for a field that does not support `undefined` */,
-		);
-		return [];
-	}
-
-	const typeSet = fieldSchema.allowedTypeSet;
-
-	if (multiplicity === Multiplicity.Sequence) {
-		assert(Array.isArray(data), 0x848 /* Expected an array as sequence input. */);
-		const children = Array.from(data, (child) => {
-			// We do not support undefined sequence entries.
-			// If we encounter an undefined entry, use null instead if supported by the schema, otherwise throw.
-			let childWithFallback = child;
-			if (child === undefined) {
-				if (typeSet === Any || typeSet.has(leaf.null)) {
-					childWithFallback = null;
-				} else {
-					throw new TypeError(`Received unsupported array entry value: ${child}.`);
-				}
-			}
-			return nodeDataToMapTree(childWithFallback, globalSchema, typeSet);
-		});
-		return children;
+function leafToMapTree(
+	data: InsertableContent,
+	schema: TreeNodeSchema,
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
+): MapTree {
+	assert(schema.kind === NodeKind.Leaf, 0x921 /* Expected a leaf schema. */);
+	if (!isTreeValue(data)) {
+		// This rule exists to protect against useless `toString` output like `[object Object]`.
+		// In this case, that's actually reasonable behavior, since object input is not compatible with Leaf schemas.
+		// eslint-disable-next-line @typescript-eslint/no-base-to-string
+		throw new UsageError(`Input data is incompatible with leaf schema: ${data}`);
 	}
-	assert(
-		multiplicity === Multiplicity.Single || multiplicity === Multiplicity.Optional,
-		0x849 /* A single value was provided for an unsupported field */,
-	);
-	return [nodeDataToMapTree(data, globalSchema, typeSet)];
-}
 
-function valueToMapTree(
-	// eslint-disable-next-line @rushstack/no-new-null
-	value: boolean | number | string | IFluidHandle | null,
-	globalSchema: FlexTreeSchema,
-	typeSet: AllowedTypeSet,
-): MapTree {
-	const mappedValue = mapValueWithFallbacks(value, typeSet);
+	const mappedValue = mapValueWithFallbacks(data, allowedTypes);
+	const mappedSchema = getType(mappedValue, allowedTypes);
 
-	const schema = getType(mappedValue, globalSchema, typeSet);
 	assert(
-		schema instanceof LeafNodeSchema && allowsValue(schema.leafValue, mappedValue),
+		allowsValue(mappedSchema, mappedValue),
 		0x84a /* Unsupported schema for provided primitive. */,
 	);
 
 	return {
 		value: mappedValue,
-		type: schema.name,
+		type: brand(mappedSchema.identifier),
 		fields: new Map(),
 	};
 }
@@ -206,11 +162,9 @@ function valueToMapTree(
  * For supported values, return the input.
  */
 function mapValueWithFallbacks(
-	// eslint-disable-next-line @rushstack/no-new-null
-	value: boolean | number | string | IFluidHandle | null,
-	typeSet: AllowedTypeSet,
-	// eslint-disable-next-line @rushstack/no-new-null
-): boolean | number | string | IFluidHandle | null {
+	value: TreeValue,
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
+): TreeValue {
 	switch (typeof value) {
 		case "number": {
 			if (Object.is(value, -0)) {
@@ -221,7 +175,7 @@ function mapValueWithFallbacks(
 				// Our serialized data format does not support NaN nor +/-∞.
 				// If the schema supports `null`, fall back to that. Otherwise, throw.
 				// This is intended to match JSON's behavior for such values.
-				if (typeSet === Any || typeSet.has(leaf.null)) {
+				if (allowedTypes.has(nullSchema)) {
 					return null;
 				} else {
 					throw new TypeError(`Received unsupported numeric value: ${value}.`);
@@ -235,94 +189,151 @@ function mapValueWithFallbacks(
 	}
 }
 
-function arrayToMapTree(
-	data: InsertableContent[],
-	globalSchema: FlexTreeSchema,
-	typeSet: AllowedTypeSet,
-): MapTree {
-	const schema = getType(data, globalSchema, typeSet);
-	assert(
-		schema instanceof FlexFieldNodeSchema,
-		0x84b /* Array data reported comparable with the schema without a primary field. */,
-	);
+function arrayToMapTreeFields(
+	data: readonly InsertableContent[],
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
+): MapTree[] {
+	const mappedData: MapTree[] = [];
+	for (const child of data) {
+		// We do not support undefined sequence entries.
+		// If we encounter an undefined entry, use null instead if supported by the schema, otherwise throw.
+		let childWithFallback = child;
+		if (child === undefined) {
+			if (allowedTypes.has(nullSchema)) {
+				childWithFallback = null;
+			} else {
+				throw new TypeError(`Received unsupported array entry value: ${child}.`);
+			}
+		}
+		const mappedChild = nodeDataToMapTree(childWithFallback, allowedTypes);
+		mappedData.push(mappedChild);
+	}
 
-	const mappedChildren = fieldDataToMapTrees(data, globalSchema, schema.info);
-	const fieldsEntries: [FieldKey, MapTree[]][] =
-		mappedChildren.length === 0 ? [] : [[EmptyKey, mappedChildren]];
+	return mappedData;
+}
+
+/**
+ * Transforms data under an Array schema.
+ * @param data - The tree data to be transformed. Must be an array.
+ * @param schema - The schema associated with the value.
+ * @param allowedTypes - The allowed types specified by the parent.
+ * Used to determine which fallback values may be appropriate.
+ */
+function arrayToMapTree(data: InsertableContent, schema: TreeNodeSchema): MapTree {
+	assert(schema.kind === NodeKind.Array, 0x922 /* Expected an array schema. */);
+	if (!isReadonlyArray(data)) {
+		throw new UsageError(`Input data is incompatible with Array schema: ${data}`);
+	}
+
+	const allowedChildTypes = normalizeAllowedTypes(schema.info as ImplicitAllowedTypes);
+
+	const mappedData = arrayToMapTreeFields(data, allowedChildTypes);
 
 	// Array node children are represented as a single field entry denoted with `EmptyKey`
+	const fieldsEntries: [FieldKey, MapTree[]][] =
+		mappedData.length === 0 ? [] : [[EmptyKey, mappedData]];
 	const fields = new Map<FieldKey, MapTree[]>(fieldsEntries);
 
 	return {
-		type: schema.name,
+		type: brand(schema.identifier),
 		fields,
 	};
 }
 
-function mapToMapTree(
-	data: Map<string, InsertableContent>,
-	globalSchema: FlexTreeSchema,
-	typeSet: AllowedTypeSet,
-): MapTree {
-	const schema = getType(data, globalSchema, typeSet);
+/**
+ * Transforms data under a Map schema.
+ * @param data - The tree data to be transformed. Must be a TypeScript Map.
+ * @param schema - The schema associated with the value.
+ * @param allowedTypes - The allowed types specified by the parent.
+ * Used to determine which fallback values may be appropriate.
+ */
+function mapToMapTree(data: InsertableContent, schema: TreeNodeSchema): MapTree {
+	assert(schema.kind === NodeKind.Map, 0x923 /* Expected a Map schema. */);
+	if (!(data instanceof Map)) {
+		throw new UsageError(`Input data is incompatible with Map schema: ${data}`);
+	}
 
-	const fields = new Map<FieldKey, MapTree[]>();
+	const allowedChildTypes = normalizeAllowedTypes(schema.info as ImplicitAllowedTypes);
+
+	const transformedFields = new Map<FieldKey, MapTree[]>();
 	for (const [key, value] of data) {
-		assert(!fields.has(brand(key)), 0x84c /* Keys should not be duplicated */);
+		assert(!transformedFields.has(brand(key)), 0x84c /* Keys should not be duplicated */);
 
-		// Omit undefined record entries - an entry with an undefined key is equivalent to no entry
+		// Omit undefined values - an entry with an undefined value is equivalent to one that has been removed or omitted
 		if (value !== undefined) {
-			const childSchema = schema.getFieldSchema(brand(key));
-			const mappedField = fieldDataToMapTrees(value, globalSchema, childSchema);
-			fields.set(brand(key), mappedField);
+			const mappedField = nodeDataToMapTree(value, allowedChildTypes);
+			transformedFields.set(brand(key), [mappedField]);
 		}
 	}
+
 	return {
-		type: schema.name,
-		fields,
+		type: brand(schema.identifier),
+		fields: transformedFields,
 	};
 }
 
-function recordToMapTree(
-	data: Record<string | number | symbol, InsertableContent>,
-	globalSchema: FlexTreeSchema,
-	typeSet: AllowedTypeSet,
-): MapTree {
-	const schema = getType(data, globalSchema, typeSet);
+/**
+ * Transforms data under an Object schema.
+ * @param data - The tree data to be transformed. Must be a Record-like object.
+ * @param schema - The schema associated with the value.
+ * @param allowedTypes - The allowed types specified by the parent.
+ * Used to determine which fallback values may be appropriate.
+ */
+function objectToMapTree(data: InsertableContent, schema: TreeNodeSchema): MapTree {
+	assert(schema.kind === NodeKind.Object, 0x924 /* Expected an Object schema. */);
+	if (typeof data !== "object" || data === null) {
+		throw new UsageError(`Input data is incompatible with Object schema: ${data}`);
+	}
 
 	const fields = new Map<FieldKey, MapTree[]>();
 
 	// Filter keys to only those that are strings - our trees do not support symbol or numeric property keys
 	const keys = Reflect.ownKeys(data).filter((key) => typeof key === "string") as FieldKey[];
 
-	for (const key of keys) {
-		assert(!fields.has(key), 0x84d /* Keys should not be duplicated */);
-		const value = data[key];
+	for (const viewKey of keys) {
+		const fieldValue = (data as Record<FieldKey, InsertableContent>)[viewKey];
 
 		// Omit undefined record entries - an entry with an undefined key is equivalent to no entry
-		if (value !== undefined) {
-			const childSchema = schema.getFieldSchema(key);
-			const mappedChildTree = fieldDataToMapTrees(value, globalSchema, childSchema);
-			fields.set(brand(key), mappedChildTree);
+		if (fieldValue !== undefined) {
+			const fieldSchema = getObjectFieldSchema(schema, viewKey);
+			const mappedChildTree = nodeDataToMapTree(fieldValue, fieldSchema.allowedTypeSet);
+			const flexKey: FieldKey = brand(getStoredKey(viewKey, fieldSchema));
+
+			// Note: SchemaFactory validates this at schema creation time, with a user-friendly error.
+			// So we don't expect to hit this, and if we do it is likely an internal bug.
+			assert(!fields.has(flexKey), 0x925 /* Keys must not be duplicated */);
+			fields.set(flexKey, [mappedChildTree]);
 		}
 	}
 
 	return {
-		type: schema.name,
+		type: brand(schema.identifier),
 		fields,
 	};
 }
 
+function getObjectFieldSchema(schema: TreeNodeSchema, key: FieldKey): FieldSchema {
+	assert(schema.kind === NodeKind.Object, 0x926 /* Expected an Object schema. */);
+	const fields = schema.info as Record<string, ImplicitFieldSchema>;
+	if (fields[key] === undefined) {
+		fail(`Field "${key}" not found in schema "${schema.identifier}".`);
+	} else {
+		return normalizeFieldSchema(fields[key]);
+	}
+}
+
 function getType(
 	data: InsertableContent,
-	globalSchema: FlexTreeSchema,
-	typeSet: AllowedTypeSet,
-): FlexTreeNodeSchema {
-	const possibleTypes = getPossibleTypes(
-		globalSchema,
-		typeSet,
-		data as ContextuallyTypedNodeData,
-	);
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
+): TreeNodeSchema {
+	const possibleTypes = getPossibleTypes(allowedTypes, data as ContextuallyTypedNodeData);
+	if (possibleTypes.length === 0) {
+		throw new UsageError(
+			`The provided data is incompatible with all of the types allowed by the schema. The set of allowed types is: ${JSON.stringify(
+				[...allowedTypes].map((schema) => schema.identifier),
+			)}.`,
+		);
+	}
 	assert(
 		possibleTypes.length !== 0,
 		0x84e /* data is incompatible with all types allowed by the schema */,
@@ -331,7 +342,9 @@ function getType(
 		possibleTypes.length === 1,
 		() =>
 			`The provided data is compatible with more than one type allowed by the schema.
-The set of possible types is ${JSON.stringify([...possibleTypes.map((n) => n.name)], undefined)}.
+The set of possible types is ${JSON.stringify([
+				...possibleTypes.map((schema) => schema.identifier),
+			])}.
 Explicitly construct an unhydrated node of the desired type to disambiguate.
 For class-based schema, this can be done by replacing an expression like "{foo: 1}" with "new MySchema({foo: 1})".`,
 	);
@@ -356,17 +369,13 @@ function checkInput(condition: boolean, message: string | (() => string)): asser
  * @returns all types for which the data is schema-compatible.
  */
 export function getPossibleTypes(
-	globalSchema: FlexTreeSchema,
-	typeSet: AllowedTypeSet,
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
 	data: ContextuallyTypedNodeData,
 ) {
-	// All types allowed by schema
-	const allowedTypes = getAllowedTypes(globalSchema, typeSet);
-
-	const possibleTypes: FlexTreeNodeSchema[] = [];
-	for (const allowed of allowedTypes) {
-		if (shallowCompatibilityTest(allowed, data)) {
-			possibleTypes.push(allowed);
+	const possibleTypes: TreeNodeSchema[] = [];
+	for (const schema of allowedTypes) {
+		if (shallowCompatibilityTest(schema, data)) {
+			possibleTypes.push(schema);
 		}
 	}
 	return possibleTypes;
@@ -380,40 +389,71 @@ export function getPossibleTypes(
  * Note that this may return true for cases where data is incompatible, but it must not return false in cases where the data is compatible.
  */
 function shallowCompatibilityTest(
-	schema: FlexTreeNodeSchema,
+	schema: TreeNodeSchema,
 	data: ContextuallyTypedNodeData,
 ): boolean {
 	assert(
 		data !== undefined,
 		0x889 /* undefined cannot be used as contextually typed data. Use ContextuallyTypedFieldData. */,
 	);
+
 	if (isTreeValue(data)) {
-		return schema instanceof LeafNodeSchema && allowsValue(schema.leafValue, data);
+		return allowsValue(schema, data);
 	}
-	if (schema instanceof LeafNodeSchema) {
+	if (schema.kind === NodeKind.Leaf) {
 		return false;
 	}
+
 	if (typeNameSymbol in data) {
-		return data[typeNameSymbol] === schema.name;
+		return data[typeNameSymbol] === schema.identifier;
 	}
+
 	if (isReadonlyArray(data)) {
-		if (schema instanceof FlexFieldNodeSchema) {
-			const field = schema.getFieldSchema();
-			return field.kind.multiplicity === Multiplicity.Sequence;
-		} else {
-			return false;
-		}
+		return schema.kind === NodeKind.Array;
 	}
+	if (schema.kind === NodeKind.Array) {
+		return false;
+	}
+
 	if (data instanceof Map) {
-		return schema instanceof FlexMapNodeSchema;
+		return schema.kind === NodeKind.Map;
+	}
+	if (schema.kind === NodeKind.Map) {
+		return false;
+	}
+
+	// Assume record-like object
+	if (schema.kind !== NodeKind.Object) {
+		return false;
 	}
 
-	// For now, consider all not explicitly typed objects shallow compatible.
-	// This will require explicit differentiation in polymorphic cases rather than automatic structural differentiation.
+	const fields = schema.info as Record<string, ImplicitFieldSchema>;
+
+	// TODO: Improve type inference by making this logic more thorough. Handle at least:
+	// * Types which are strict subsets of other types in the same polymorphic union
+	// * Types which have the same keys but different types for those keys in the polymorphic union
+	// * Types which have the same required fields but different optional fields and enough of those optional fields are populated to disambiguate
+
+	// TODO#7441: Consider allowing data to be inserted which has keys that are extraneous/unknown to the schema (those keys are ignored)
+
+	// If the schema has a required key which is not present in the input object, reject it.
+	for (const [fieldKey, fieldSchema] of Object.entries(fields)) {
+		const normalizedFieldSchema = normalizeFieldSchema(fieldSchema);
+		if (data[fieldKey] === undefined && normalizedFieldSchema.kind === FieldKind.Required) {
+			return false;
+		}
+	}
 
 	return true;
 }
 
+function allowsValue(schema: TreeNodeSchema, value: TreeValue): boolean {
+	if (schema.kind === NodeKind.Leaf) {
+		return valueSchemaAllows(schema.info as ValueSchema, value);
+	}
+	return false;
+}
+
 /**
  * Content of a tree which needs external schema information to interpret.
  *
@@ -452,7 +492,7 @@ export interface ContextuallyTypedNodeDataObject {
 	/**
 	 * Fields of this node, indexed by their field keys.
 	 *
-	 * Allow explicit undefined for compatibility with EditableTree, and type-safety on read.
+	 * Allow explicit undefined for compatibility with FlexTree, and type-safety on read.
 	 */
 	// TODO: make sure explicit undefined is actually handled correctly.
 	[key: FieldKey]: ContextuallyTypedFieldData;

package/src/simple-tree/tree.ts

@@ -4,8 +4,12 @@
  */
 
 import { IChannel } from "@fluidframework/datastore-definitions";
+
+import { CommitMetadata } from "../core/index.js";
 import { ISubscribable } from "../events/index.js";
+import { RevertibleFactory } from "../shared-tree/index.js";
 import { IDisposable } from "../util/index.js";
+
 import {
 	ImplicitFieldSchema,
 	InsertableTreeFieldFromImplicitField,
@@ -57,7 +61,7 @@ export interface ITree extends IChannel {
 	 */
 	schematize<TRoot extends ImplicitFieldSchema>(
 		config: TreeConfiguration<TRoot>,
-	): TreeView<TreeFieldFromImplicitField<TRoot>>;
+	): TreeView<TRoot>;
 }
 
 /**
@@ -95,7 +99,7 @@ export class TreeConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFie
  * it could be mitigated by adding a `rootOrError` member and deprecating `root` to give users a warning if they might be missing the error checking.
  * @public
  */
-export interface TreeView<in out TRoot> extends IDisposable {
+export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposable {
 	/**
 	 * The current root of the tree.
 	 *
@@ -105,7 +109,9 @@ export interface TreeView<in out TRoot> extends IDisposable {
 	 * To get notified about changes to this field (including to it being in an `error` state),
 	 * use {@link TreeViewEvents.rootChanged} via `view.events.on("rootChanged", callback)`.
 	 */
-	readonly root: TRoot;
+	get root(): TreeFieldFromImplicitField<TSchema>;
+
+	set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);
 
 	/**
 	 * Description of the error state, if any.
@@ -171,4 +177,19 @@ export interface TreeViewEvents {
 	 * This does NOT include changes to the content (fields/children) of the root node: for that case subscribe to events on the root node.
 	 */
 	rootChanged(): void;
+
+	/**
+	 * Fired when:
+	 * - a local commit is applied outside of a transaction
+	 * - a local transaction is committed
+	 *
+	 * The event is not fired when:
+	 * - a local commit is applied within a transaction
+	 * - a remote commit is applied
+	 *
+	 * @param data - information about the commit that was applied
+	 * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,
+	 * this commit is not revertible.
+	 */
+	commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
 }