@fluidframework/tree 2.23.0 → 2.31.0

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

@@ -5,32 +5,35 @@
 
 import type {
 	ScopedSchemaName,
-	InsertableObjectFromSchemaRecord,
 	TreeObjectNodeUnsafe,
 	InsertableObjectFromSchemaRecordUnsafe,
 } from "../../internalTypes.js";
 import {
 	defaultSchemaFactoryObjectOptions,
 	SchemaFactory,
+	schemaStatics,
 	type SchemaFactoryObjectOptions,
 } from "./schemaFactory.js";
 import type {
 	ImplicitAllowedTypes,
 	ImplicitFieldSchema,
-	InsertableTreeNodeFromImplicitAllowedTypes,
 	NodeSchemaOptions,
 } from "../schemaTypes.js";
-import { type TreeObjectNode, objectSchema } from "../objectNode.js";
+import { objectSchema } from "../objectNode.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
-import type { NodeKind, TreeNodeSchemaClass, WithType } from "../core/index.js";
+import type { NodeKind, TreeNodeSchemaClass } from "../core/index.js";
 import type {
-	InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
-	TreeArrayNodeUnsafe,
-	TreeMapNodeUnsafe,
-	Unenforced,
+	ImplicitAllowedTypesUnsafe,
+	ImplicitFieldSchemaUnsafe,
+	ArrayNodeCustomizableSchemaUnsafe,
+	MapNodeCustomizableSchemaUnsafe,
 } from "./typesUnsafe.js";
-import { mapSchema, type MapNodeInsertableData, type TreeMapNode } from "../mapNode.js";
-import { arraySchema, type TreeArrayNode } from "../arrayNode.js";
+import { mapSchema } from "../mapNode.js";
+import { arraySchema } from "../arrayNode.js";
+import type { ObjectNodeSchema } from "../objectNodeTypes.js";
+import type { SimpleObjectNodeSchema } from "../simpleSchema.js";
+import type { ArrayNodeCustomizableSchema } from "../arrayNodeTypes.js";
+import type { MapNodeCustomizableSchema } from "../mapNodeTypes.js";
 
 /**
  * {@link SchemaFactory} with additional alpha APIs.
@@ -66,16 +69,7 @@ export class SchemaFactoryAlpha<
 		name: Name,
 		fields: T,
 		options?: SchemaFactoryObjectOptions<TCustomMetadata>,
-	): TreeNodeSchemaClass<
-		ScopedSchemaName<TScope, Name>,
-		NodeKind.Object,
-		TreeObjectNode<T, ScopedSchemaName<TScope, Name>>,
-		object & InsertableObjectFromSchemaRecord<T>,
-		true,
-		T,
-		never,
-		TCustomMetadata
-	> {
+	): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
 		return objectSchema(
 			this.scoped2(name),
 			fields,
@@ -91,7 +85,7 @@ export class SchemaFactoryAlpha<
 	 */
 	public override objectRecursive<
 		const Name extends TName,
-		const T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>,
+		const T extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,
@@ -106,7 +100,19 @@ export class SchemaFactoryAlpha<
 		T,
 		never,
 		TCustomMetadata
-	> {
+	> &
+		SimpleObjectNodeSchema<TCustomMetadata> &
+		// We can't just use non generic `ObjectNodeSchema` here since "Base constructors must all have the same return type".
+		// We also can't just use generic `ObjectNodeSchema` here and not `TreeNodeSchemaClass` since that doesn't work with unsafe recursive types.
+		// ObjectNodeSchema<
+		// 	ScopedSchemaName<TScope, Name>,
+		// 	//  T & RestrictiveStringRecord<ImplicitFieldSchema> would be nice to use here, but it breaks the recursive type self references.
+		// 	RestrictiveStringRecord<ImplicitFieldSchema>,
+		// 	false,
+		// 	TCustomMetadata
+		// >
+		Pick<ObjectNodeSchema, "fields"> {
+		// TODO: syntax highting is vs code is broken here. Don't trust it. Use the compiler instead.
 		type TScopedName = ScopedSchemaName<TScope, Name>;
 		return this.object(
 			name,
@@ -121,9 +127,35 @@ export class SchemaFactoryAlpha<
 			T,
 			never,
 			TCustomMetadata
-		>;
+		> &
+			ObjectNodeSchema<
+				ScopedSchemaName<TScope, Name>,
+				RestrictiveStringRecord<ImplicitFieldSchema>,
+				false,
+				TCustomMetadata
+			>;
 	}
 
+	/**
+	 * {@inheritDoc SchemaStatics.optional}
+	 */
+	public static override readonly optional = schemaStatics.optional;
+
+	/**
+	 * {@inheritDoc SchemaStatics.required}
+	 */
+	public static override readonly required = schemaStatics.required;
+
+	/**
+	 * {@inheritDoc SchemaStatics.optionalRecursive}
+	 */
+	public static override readonly optionalRecursive = schemaStatics.optionalRecursive;
+
+	/**
+	 * Like {@link SchemaFactory.identifier} but static and a factory function that can be provided {@link FieldProps}.
+	 */
+	public static readonly identifier = schemaStatics.identifier;
+
 	/**
 	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
 	 *
@@ -146,16 +178,7 @@ export class SchemaFactoryAlpha<
 		name: Name,
 		allowedTypes: T,
 		options?: NodeSchemaOptions<TCustomMetadata>,
-	): TreeNodeSchemaClass<
-		ScopedSchemaName<TScope, Name>,
-		NodeKind.Map,
-		TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
-		MapNodeInsertableData<T>,
-		true,
-		T,
-		undefined,
-		TCustomMetadata
-	> {
+	): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
 		return mapSchema(this.scoped2(name), allowedTypes, true, true, options?.metadata);
 	}
 
@@ -165,28 +188,16 @@ export class SchemaFactoryAlpha<
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	public override mapRecursive<
 		Name extends TName,
-		const T extends Unenforced<ImplicitAllowedTypes>,
+		const T extends ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
 	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
 		return this.mapAlpha(
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,
 			options,
-		) as unknown as TreeNodeSchemaClass<
+		) as unknown as MapNodeCustomizableSchemaUnsafe<
 			ScopedSchemaName<TScope, Name>,
-			NodeKind.Map,
-			TreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
-			| {
-					[Symbol.iterator](): Iterator<
-						[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
-					>;
-			  }
-			| {
-					readonly [P in string]: InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
-			  },
-			false,
 			T,
-			undefined,
 			TCustomMetadata
 		>;
 	}
@@ -200,7 +211,7 @@ export class SchemaFactoryAlpha<
 	 *
 	 * @example
 	 * ```typescript
-	 * class NamedArray extends factory.array("name", factory.number) {}
+	 * class NamedArray extends factory.arrayAlpha("name", factory.number) {}
 	 * ```
 	 */
 	public arrayAlpha<
@@ -211,16 +222,7 @@ export class SchemaFactoryAlpha<
 		name: Name,
 		allowedTypes: T,
 		options?: NodeSchemaOptions<TCustomMetadata>,
-	): TreeNodeSchemaClass<
-		ScopedSchemaName<TScope, Name>,
-		NodeKind.Array,
-		TreeArrayNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,
-		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
-		true,
-		T,
-		undefined,
-		TCustomMetadata
-	> {
+	): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
 		return arraySchema(this.scoped2(name), allowedTypes, true, true, options?.metadata);
 	}
 
@@ -230,24 +232,29 @@ export class SchemaFactoryAlpha<
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	public override arrayRecursive<
 		const Name extends TName,
-		const T extends Unenforced<ImplicitAllowedTypes>,
+		const T extends ImplicitAllowedTypesUnsafe,
 		const TCustomMetadata = unknown,
 	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
 		return this.arrayAlpha(
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,
 			options,
-		) as unknown as TreeNodeSchemaClass<
+		) as unknown as ArrayNodeCustomizableSchemaUnsafe<
 			ScopedSchemaName<TScope, Name>,
-			NodeKind.Array,
-			TreeArrayNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,
-			{
-				[Symbol.iterator](): Iterator<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>;
-			},
-			false,
 			T,
-			undefined,
 			TCustomMetadata
 		>;
 	}
+
+	/**
+	 * Create a {@link SchemaFactory} with a {@link SchemaFactory.scope|scope} which is a combination of this factory's scope and the provided name.
+	 * @remarks
+	 * The main use-case for this is when creating a collection of related schema (for example using a function that creates multiple schema).
+	 * Creating such related schema using a sub-scope helps ensure they won't collide with other schema in the parent scope.
+	 */
+	public scopedFactory<const T extends TName, TNameInner extends number | string = string>(
+		name: T,
+	): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner> {
+		return new SchemaFactoryAlpha(this.scoped2(name));
+	}
 }

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

@@ -21,26 +21,24 @@ import type {
 	WithType,
 	TreeNode,
 } from "../core/index.js";
-import type { FieldSchemaUnsafe, Unenforced } from "./typesUnsafe.js";
+import type { FieldSchemaAlphaUnsafe, ImplicitAllowedTypesUnsafe } from "./typesUnsafe.js";
 
 export function createFieldSchemaUnsafe<
 	Kind extends FieldKind,
-	Types extends Unenforced<ImplicitAllowedTypes>,
+	Types extends ImplicitAllowedTypesUnsafe,
+	TCustomMetadata = unknown,
 >(
 	kind: Kind,
 	allowedTypes: Types,
-	props: FieldProps | undefined,
-): FieldSchemaUnsafe<Kind, Types> {
+	props?: FieldProps<TCustomMetadata>,
+): FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata> {
 	// At runtime, we still want this to be a FieldSchema instance, but we can't satisfy its extends clause, so just return it as an FieldSchemaUnsafe
-	return createFieldSchema(
-		kind,
-		allowedTypes as ImplicitAllowedTypes,
-		props,
-	) as FieldSchemaUnsafe<Kind, Types>;
+	return createFieldSchema(kind, allowedTypes as ImplicitAllowedTypes & Types, props);
 }
 
 /**
  * Compile time check for validity of a recursive schema.
+ * This type also serves as a central location for documenting the requirements and issues related to recursive schema.
  *
  * @example
  * ```typescript
@@ -50,13 +48,37 @@ export function createFieldSchemaUnsafe<
  * }
  * ```
  * @remarks
- * The type of a recursive schema can be passed to this, and a compile error will be produced for some of the cases of malformed schema.
+ * In this context recursive schema are defined as all {@link FieldSchema} and {@link TreeNodeSchema} schema which are part of a cycle such that walking down through each {@link TreeNodeSchemaCore.childTypes} the given starting schema can be reached again.
+ * Schema referencing the recursive schema and schema they reference that are not part of a cycle are not considered recursive.
+ *
+ * TypeScript puts a lot of limitations on the typing of recursive schema.
+ * To help avoid running into these limitations and thus getting schema that do not type check (or only type checks sometimes!),
+ * {@link SchemaFactory} provides APIs (postfixed with `Recursive`) for writing recursive schema.
+ * These APIs when combined with the patterns documented below should ensure that the schema provide robust type checking.
+ * These special patterns (other than {@link LazyItem} forward references which are not recursion specific)
+ * are not required for correct runtime behavior: they exist entirely to mitigate TypeScript type checking limitations and bugs.
+ * Ideally TypeScript's type checker would be able to handle all of these cases and more, removing the need for recursive type specific guidance, rules and APIs.
+ * Currently however there are open issues preventing this:
+ * {@link https://github.com/microsoft/TypeScript/issues/59550 | 1},
+ * {@link https://github.com/microsoft/TypeScript/issues/55832 | 2},
+ * {@link https://github.com/microsoft/TypeScript/issues/55758 | 3}.
+ * Note that the proposed resolution to some of these issues is for the compiler to error rather than allow the case,
+ * so even if these are all resolved the recursive type workarounds may still be needed.
+ *
+ * # Patterns
+ *
+ * Below are patterns for how to use recursive schema.
+ *
+ * ## General Patterns
+ *
+ * When defining a recursive {@link TreeNodeSchema}, use the `*Recursive` {@link SchemaFactory} methods.
+ * The returned class should be used as the base class for the recursive schema, which should then be passed to {@link ValidateRecursiveSchema}.
+ *
+ * Using {@link ValidateRecursiveSchema} will provide compile error for some of the cases of malformed schema.
  * This can be used to help mitigate the issue that recursive schema definitions are {@link Unenforced}.
  * If an issue is encountered where a mistake in a recursive schema is made which produces an invalid schema but is not rejected by this checker,
  * it should be considered a bug and this should be updated to handle that case (or have a disclaimer added to these docs that it misses that case).
  *
- * # Recursive Schema
- *
  * The non-recursive versions of the schema building methods will run into several issues when used recursively.
  * Consider the following example:
  *
@@ -110,12 +132,22 @@ export function createFieldSchemaUnsafe<
  * }
  * ```
  *
+ * ## Object Schema
+ *
+ * When defining fields, if the fields is part of the recursive cycle, use the `*Recursive` {@link SchemaFactory} methods for defining the {@link FieldSchema}.
+ *
+ * ## Array Schema
+ *
+ * See {@link FixRecursiveArraySchema} for array specific details.
+ *
  * @privateRemarks
  * There are probably mistakes this misses: it's hard to guess all the wrong things people will accidentally do and defend against them.
  * Hopefully over time this can grow toward being robust, at least for common mistakes.
  *
  * This check duplicates logic that ideally would be entirely decided by the actual schema building methods.
  * Therefore changes to those methods may require updating `ValidateRecursiveSchema`.
+ *
+ * TODO: this currently does not reject `any`, but ideally should.
  * @public
  */
 export type ValidateRecursiveSchema<

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

@@ -0,0 +1,96 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
+import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import {
+	type FieldSchema,
+	type AllowedTypes,
+	type FieldSchemaAlpha,
+	FieldKind,
+} from "../schemaTypes.js";
+import { SchemaFactory } from "./schemaFactory.js";
+import type {
+	SimpleFieldSchema,
+	SimpleNodeSchema,
+	SimpleTreeSchema,
+} from "../simpleSchema.js";
+import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
+
+const factory = new SchemaFactoryAlpha(undefined);
+
+/**
+ * Create {@link FieldSchema} from a SimpleTreeSchema.
+ * @remarks
+ * Only use this API if hand written schema (produced using {@link SchemaFactory} cannot be provided.
+ *
+ * Using generated schema with schema aware APIs (designed to work with strongly typed schema) like {@link TreeViewConfiguration}
+ * will produce a poor TypeScript typing experience which is subject to change.
+ *
+ * Editing through a view produced using this schema can easily violate invariants other users of the document might expect and must be done with great care.
+ * @alpha
+ */
+export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): FieldSchemaAlpha {
+	const context: Context = new Map(
+		[...simple.definitions].map(([id, schema]): [string, () => TreeNodeSchema] => [
+			id,
+			// This relies on the caching in evaluateLazySchema so that it only runs once.
+			() => generateNode(id, schema, context),
+		]),
+	);
+	return generateFieldSchema(simple, context);
+}
+
+type Context = ReadonlyMap<string, () => TreeNodeSchema>;
+
+function generateFieldSchema(simple: SimpleFieldSchema, context: Context): FieldSchemaAlpha {
+	const allowed = generateAllowedTypes(simple.allowedTypesIdentifiers, context);
+	// Using createFieldSchema could work, but would require setting up the default providers.
+	switch (simple.kind) {
+		case FieldKind.Identifier:
+			return SchemaFactoryAlpha.identifier({ metadata: simple.metadata });
+		case FieldKind.Optional:
+			return SchemaFactoryAlpha.optional(allowed, { metadata: simple.metadata });
+		case FieldKind.Required:
+			return SchemaFactoryAlpha.required(allowed, { metadata: simple.metadata });
+		default:
+			return unreachableCase(simple.kind);
+	}
+}
+
+function generateAllowedTypes(allowed: ReadonlySet<string>, context: Context): AllowedTypes {
+	return [...allowed].map((id) => context.get(id) ?? fail(0xb5a /* Missing schema */));
+}
+
+function generateNode(id: string, schema: SimpleNodeSchema, context: Context): TreeNodeSchema {
+	switch (schema.kind) {
+		case NodeKind.Object: {
+			const fields: Record<string, FieldSchema> = {};
+			for (const [key, field] of schema.fields) {
+				fields[key] = generateFieldSchema(field, context);
+			}
+			return factory.object(id, fields, { metadata: schema.metadata });
+		}
+		case NodeKind.Array:
+			return factory.arrayAlpha(
+				id,
+				generateAllowedTypes(schema.allowedTypesIdentifiers, context),
+				{ metadata: schema.metadata },
+			);
+		case NodeKind.Map:
+			return factory.mapAlpha(
+				id,
+				generateAllowedTypes(schema.allowedTypesIdentifiers, context),
+				{ metadata: schema.metadata },
+			);
+		case NodeKind.Leaf:
+			return (
+				SchemaFactory.leaves.find((leaf) => leaf.identifier === id) ??
+				fail(0xb5b /* Missing schema */)
+			);
+		default:
+			return unreachableCase(schema);
+	}
+}

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

@@ -27,7 +27,7 @@ import type {
 	SimpleNodeSchema,
 	SimpleObjectNodeSchema,
 	SimpleTreeSchema,
-} from "./simpleSchema.js";
+} from "../simpleSchema.js";
 import { NodeKind } from "../core/index.js";
 
 /**
@@ -38,7 +38,7 @@ export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
 	const definitions = convertDefinitions(schema.definitions);
 
 	const allowedTypes: JsonSchemaRef[] = [];
-	for (const allowedType of schema.allowedTypes) {
+	for (const allowedType of schema.allowedTypesIdentifiers) {
 		allowedTypes.push(createSchemaRef(allowedType));
 	}
 
@@ -92,7 +92,7 @@ function convertNodeSchema(schema: SimpleNodeSchema): JsonNodeSchema {
 
 function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSchema {
 	const allowedTypes: JsonSchemaRef[] = [];
-	schema.allowedTypes.forEach((type) => {
+	schema.allowedTypesIdentifiers.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
 
@@ -138,12 +138,12 @@ function convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema
 	};
 }
 
-function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {
+export function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {
 	const properties: Record<string, JsonFieldSchema> = {};
 	const required: string[] = [];
-	for (const [key, fieldSchema] of Object.entries(schema.fields)) {
+	for (const [key, fieldSchema] of schema.fields) {
 		const allowedTypes: JsonSchemaRef[] = [];
-		for (const allowedType of fieldSchema.allowedTypes) {
+		for (const allowedType of fieldSchema.allowedTypesIdentifiers) {
 			allowedTypes.push(createSchemaRef(allowedType));
 		}
 
@@ -176,7 +176,7 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 
 function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 	const allowedTypes: JsonSchemaRef[] = [];
-	schema.allowedTypes.forEach((type) => {
+	schema.allowedTypesIdentifiers.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
 

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

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { fail } from "@fluidframework/core-utils/internal";
 import type {
 	AnchorNode,
 	FieldKey,
@@ -18,7 +19,7 @@ import {
 	type TreeIndexKey,
 	type KeyFinder,
 } from "../../feature-libraries/index.js";
-import { brand, fail } from "../../util/index.js";
+import { brand } from "../../util/index.js";
 import type { ImplicitFieldSchema, NodeFromSchema } from "../schemaTypes.js";
 import { treeNodeFromAnchor, type TreeNode, type TreeNodeSchema } from "../core/index.js";
 import { treeNodeApi } from "./treeNodeApi.js";

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

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IFluidLoadable, IDisposable, Listenable } from "@fluidframework/core-interfaces";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -27,18 +28,17 @@ import {
 	type TreeFieldFromImplicitField,
 	type UnsafeUnknownSchema,
 	FieldKind,
+	markSchemaMostDerived,
 } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import { toStoredSchema } from "../toStoredSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
-import { assert } from "@fluidframework/core-utils/internal";
 import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js";
-import { markSchemaMostDerived } from "./schemaFactory.js";
-import { fail, getOrCreate } from "../../util/index.js";
+import { getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
 import type { VerboseTree } from "./verboseTree.js";
-import type { SimpleTreeSchema } from "./simpleSchema.js";
+import type { SimpleTreeSchema } from "../simpleSchema.js";
 import type {
 	RunTransactionParams,
 	TransactionCallbackStatus,
@@ -264,7 +264,17 @@ export class TreeViewConfiguration<
 	public readonly preventAmbiguity: boolean;
 
 	/**
+	 * Construct a new {@link TreeViewConfiguration}.
+	 *
 	 * @param props - Property bag of configuration options.
+	 *
+	 * @remarks
+	 * Performing this construction deeply validates the provided schema.
+	 * This means that when this constructor is called, all {@link LazyItem} {@link TreeNodeSchema} references will be evaluated (using {@link evaluateLazySchema}).
+	 * This means that the declarations for all transitively reachable {@link TreeNodeSchema} must be available at this time.
+	 *
+	 * For example, a schema reachable from this configuration cannot reference this configuration during its declaration,
+	 * since this would be a cyclic dependency that will cause an error when constructing this configuration.
 	 */
 	public constructor(props: ITreeViewConfiguration<TSchema>) {
 		const config = { ...defaultTreeConfigurationOptions, ...props };
@@ -280,7 +290,7 @@ export class TreeViewConfiguration<
 			// This ensures if multiple schema extending the same schema factory generated class are present (or have been constructed, or get constructed in the future),
 			// an error is reported.
 
-			node: markSchemaMostDerived,
+			node: (schema) => markSchemaMostDerived(schema, true),
 			allowedTypes(types): void {
 				if (config.preventAmbiguity) {
 					checkUnion(types, ambiguityErrors);
@@ -725,12 +735,7 @@ export interface SchemaCompatibilityStatus {
  * Events for {@link TreeBranch}.
  * @sealed @alpha
  */
-export interface TreeBranchEvents {
-	/**
-	 * The stored schema for the document has changed.
-	 */
-	schemaChanged(): void;
-
+export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied"> {
 	/**
 	 * Fired when a change is made to the branch. Includes data about the change that is made which listeners
 	 * can use to filter on changes they care about (e.g. local vs. remote changes).

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

@@ -3,17 +3,18 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail } from "@fluidframework/core-utils/internal";
 
 import { EmptyKey, rootFieldKey } from "../../core/index.js";
 import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
-import { fail, extractFromOpaque, isReadonlyArray } from "../../util/index.js";
+import { extractFromOpaque } from "../../util/index.js";
 import {
 	type TreeLeafValue,
 	type ImplicitFieldSchema,
 	FieldSchema,
 	type ImplicitAllowedTypes,
 	type TreeNodeFromImplicitAllowedTypes,
+	normalizeAllowedTypes,
 } from "../schemaTypes.js";
 import {
 	booleanSchema,
@@ -39,8 +40,6 @@ import {
 	getOrCreateInnerNode,
 } from "../core/index.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
-import { isLazy, type LazyItem } from "../flexList.js";
-import { markSchemaMostDerived } from "./schemaFactory.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -212,19 +211,7 @@ export const treeNodeApi: TreeNodeApi = {
 		if (actualSchema === undefined) {
 			return false;
 		}
-		if (isReadonlyArray<LazyItem<TreeNodeSchema>>(schema)) {
-			for (const singleSchema of schema) {
-				const testSchema = isLazy(singleSchema) ? singleSchema() : singleSchema;
-				markSchemaMostDerived(testSchema);
-				if (testSchema === actualSchema) {
-					return true;
-				}
-			}
-			return false;
-		} else {
-			markSchemaMostDerived(schema);
-			return schema === actualSchema;
-		}
+		return normalizeAllowedTypes(schema).has(actualSchema);
 	},
 	schema(node: TreeNode | TreeLeafValue): TreeNodeSchema {
 		return tryGetSchema(node) ?? fail(0xb37 /* Not a tree node */);
@@ -258,7 +245,7 @@ export const treeNodeApi: TreeNodeApi = {
 				const identifierValue = identifier.value as string;
 
 				const localNodeKey =
-					identifier.context.nodeKeyManager.tryLocalizeNodeKey(identifierValue);
+					identifier.context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
 				return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;
 			}
 			default: