@fluidframework/tree 2.1.0-276326 → 2.1.0-281041

package/src/simple-tree/arrayNode.ts

@@ -19,6 +19,7 @@ import {
 	getOrCreateMapTreeNode,
 	getSchemaAndPolicy,
 	isMapTreeNode,
+	isFlexTreeNode,
 } from "../feature-libraries/index.js";
 import {
 	type InsertableContent,
@@ -39,7 +40,12 @@ import {
 	normalizeFieldSchema,
 } from "./schemaTypes.js";
 import { mapTreeFromNodeData } from "./toMapTree.js";
-import { type TreeNode, TreeNodeValid } from "./types.js";
+import {
+	type TreeNode,
+	TreeNodeValid,
+	type InternalTreeNode,
+	type MostDerivedData,
+} from "./types.js";
 import { fail } from "../util/index.js";
 import { getFlexSchema } from "./toFlexSchema.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
@@ -215,6 +221,11 @@ export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom>
 		sourceEnd: number,
 		source: TMoveFrom,
 	): void;
+
+	/**
+	 * Returns a custom IterableIterator which throws usage errors if concurrent editing and iteration occurs.
+	 */
+	values(): IterableIterator<T>;
 }
 
 /**
@@ -315,7 +326,6 @@ const arrayPrototypeKeys = [
 	"some",
 	"toLocaleString",
 	"toString",
-	"values",
 
 	// "copyWithin",
 	// "fill",
@@ -489,7 +499,6 @@ declare abstract class NodeWithArrayFeatures<Input, T>
 	): boolean;
 	toLocaleString(): string;
 	toString(): string;
-	values(): IterableIterator<T>;
 }
 /* eslint-enable @typescript-eslint/explicit-member-accessibility, @typescript-eslint/no-explicit-any */
 
@@ -554,16 +563,8 @@ function createArrayNodeProxy(
 				return Reflect.get(dispatchTarget, key, receiver) as unknown;
 			}
 
-			const value = field.boxedAt(maybeIndex);
-
-			if (value === undefined) {
-				return undefined;
-			}
-
-			// TODO: Ideally, we would return leaves without first boxing them.  However, this is not
-			//       as simple as calling '.content' since this skips the node and returns the FieldNode's
-			//       inner field.
-			return getOrCreateNodeProxy(value);
+			const maybeContent = field.at(maybeIndex);
+			return isFlexTreeNode(maybeContent) ? getOrCreateNodeProxy(maybeContent) : maybeContent;
 		},
 		set: (target, key, newValue, receiver) => {
 			if (key === "length") {
@@ -590,7 +591,7 @@ function createArrayNodeProxy(
 					"Cannot set indexed properties on array nodes. Use array node mutation APIs to alter the array.",
 				);
 			}
-			return allowAdditionalProperties ? Reflect.set(target, key, newValue) : false;
+			return allowAdditionalProperties ? Reflect.set(target, key, newValue, receiver) : false;
 		},
 		has: (target, key) => {
 			const field = getSequenceField(proxy);
@@ -672,6 +673,21 @@ 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);
+		getFlexNode(this).on("nodeChanged", () => {
+			this.#generationNumber += 1;
+		});
+	}
+
 	#cursorFromFieldData(value: Insertable<T>): ITreeCursorSynchronous {
 		if (isMapTreeNode(getFlexNode(this))) {
 			throw new UsageError(`An array cannot be mutated before being inserted into the tree`);
@@ -827,13 +843,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		const destinationField = getSequenceField(this);
 		validateIndex(destinationIndex, destinationField, "moveRangeToIndex", true);
 		validateIndexRange(sourceStart, sourceEnd, source ?? destinationField, "moveRangeToIndex");
-		const sourceField =
-			source !== undefined
-				? destinationField.isSameAs(getSequenceField(source))
-					? destinationField
-					: getSequenceField(source)
-				: destinationField;
-
+		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++) {
@@ -855,6 +865,23 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			destinationIndex,
 		);
 	}
+
+	public values(): IterableIterator<TreeNodeFromImplicitAllowedTypes<T>> {
+		return this.generateValues(this.#generationNumber);
+	}
+	private *generateValues(
+		initialLastUpdatedStamp: number,
+	): Generator<TreeNodeFromImplicitAllowedTypes<T>> {
+		if (initialLastUpdatedStamp !== this.#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) {
+				throw new UsageError(`Concurrent editing and iteration is not allowed.`);
+			}
+		}
+	}
 }
 
 /**
@@ -921,7 +948,7 @@ export function arraySchema<
 			);
 		}
 
-		protected static override constructorCached: typeof TreeNodeValid | undefined = undefined;
+		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;

package/src/simple-tree/leafNodeSchema.ts

@@ -32,7 +32,7 @@ type UnbrandedName<T extends FlexLeafNodeSchema> = T["name"] extends TreeNodeSch
  * @privateRemarks
  * This class refers to the underlying flex tree schema in its constructor, so this class can't be included in the package API.
  */
-class LeafNodeSchema<T extends FlexLeafNodeSchema>
+export class LeafNodeSchema<T extends FlexLeafNodeSchema>
 	implements TreeNodeSchemaNonClass<UnbrandedName<T>, NodeKind.Leaf, TreeValue<T["info"]>>
 {
 	public readonly identifier: UnbrandedName<T>;

package/src/simple-tree/mapNode.ts

@@ -32,7 +32,7 @@ import {
 	typeNameSymbol,
 } from "./schemaTypes.js";
 import { mapTreeFromNodeData } from "./toMapTree.js";
-import { type TreeNode, TreeNodeValid } from "./types.js";
+import { type MostDerivedData, type TreeNode, TreeNodeValid } from "./types.js";
 import { getFlexSchema } from "./toFlexSchema.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -246,7 +246,7 @@ export function mapSchema<
 			);
 		}
 
-		protected static override constructorCached: typeof TreeNodeValid | undefined = undefined;
+		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 FlexMapNodeSchema;

package/src/simple-tree/objectNode.ts

@@ -44,7 +44,12 @@ import {
 	FieldKind,
 } from "./schemaTypes.js";
 import { mapTreeFromNodeData } from "./toMapTree.js";
-import { type InternalTreeNode, type TreeNode, TreeNodeValid } from "./types.js";
+import {
+	type InternalTreeNode,
+	type MostDerivedData,
+	type TreeNode,
+	TreeNodeValid,
+} from "./types.js";
 import { type RestrictiveReadonlyRecord, fail, type FlattenKeys } from "../util/index.js";
 import { getFlexSchema } from "./toFlexSchema.js";
 
@@ -187,7 +192,8 @@ function createProxyHandler(
 		set(target, viewKey, value: InsertableContent | undefined, proxy) {
 			const fieldInfo = flexKeyMap.get(viewKey);
 			if (fieldInfo === undefined) {
-				return allowAdditionalProperties ? Reflect.set(target, viewKey, value) : false;
+				// Pass the proxy as the receiver here, so that setters on the prototype receive `proxy` as `this`.
+				return allowAdditionalProperties ? Reflect.set(target, viewKey, value, proxy) : false;
 			}
 
 			const flexNode = getFlexNode(proxy);
@@ -359,7 +365,7 @@ export function objectSchema<
 			);
 		}
 
-		protected static override constructorCached: typeof TreeNodeValid | undefined = undefined;
+		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup<T2>(this: typeof TreeNodeValid<T2>): void {
 			// One time initialization that required knowing the most derived type (from this.constructor) and thus has to be lazy.

package/src/simple-tree/proxies.ts

@@ -61,10 +61,8 @@ export function getProxyForField(field: FlexTreeField): TreeNode | TreeValue | u
 			FlexFieldSchema<typeof FieldKinds.required | typeof FieldKinds.optional>
 		>,
 	): TreeNode | TreeValue | undefined {
-		const maybeUnboxedContent = flexField.content;
-		return isFlexTreeNode(maybeUnboxedContent)
-			? getOrCreateNodeProxy(maybeUnboxedContent)
-			: maybeUnboxedContent;
+		const maybeContent = flexField.content;
+		return isFlexTreeNode(maybeContent) ? getOrCreateNodeProxy(maybeContent) : maybeContent;
 	}
 	switch (field.schema.kind) {
 		case FieldKinds.required: {

package/src/simple-tree/schemaFactory.ts

@@ -8,6 +8,8 @@ import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 // which degrades the API-Extractor report quality since API-Extractor can not tell the inline import is the same as the non-inline one.
 // eslint-disable-next-line unused-imports/no-unused-imports
 import type { IFluidHandle as _dummyImport } from "@fluidframework/core-interfaces";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
 import type { TreeValue } from "../core/index.js";
 import { type NodeKeyManager, type Unenforced, isLazy } from "../feature-libraries/index.js";
@@ -20,6 +22,7 @@ import {
 import {
 	booleanSchema,
 	handleSchema,
+	LeafNodeSchema,
 	nullSchema,
 	numberSchema,
 	stringSchema,
@@ -40,7 +43,6 @@ import {
 	getDefaultProvider,
 } from "./schemaTypes.js";
 import { type TreeArrayNode, arraySchema } from "./arrayNode.js";
-import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import {
 	type InsertableObjectFromSchemaRecord,
 	type TreeObjectNode,
@@ -64,6 +66,7 @@ import type {
 	TreeObjectNodeUnsafe,
 } from "./typesUnsafe.js";
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
+import { inPrototypeChain, TreeNodeValid } from "./types.js";
 /**
  * Gets the leaf domain schema compatible with a given {@link TreeValue}.
  */
@@ -161,9 +164,24 @@ export class SchemaFactory<
 	out TScope extends string | undefined = string | undefined,
 	TName extends number | string = string,
 > {
+	/**
+	 * TODO:
+	 * If users of this generate the same name because two different schema with the same identifier were used,
+	 * the second use can get a cache hit, and reference the wrong schema.
+	 * Such usage should probably return a distinct type or error but currently does not.
+	 * The use of markSchemaMostDerived in structuralName at least ensure an error in the case where the collision is from two types extending the same schema factor class.
+	 */
 	private readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();
 
 	/**
+	 * Construct a SchemaFactory with a given scope.
+	 * @remarks
+	 * There are no restrictions on mixing schema from different schema factories:
+	 * this is encouraged when a single schema references schema from different libraries.
+	 * If each library exporting schema picks its own globally unique scope for its SchemaFactory,
+	 * then all schema an application might depend on, directly or transitively,
+	 * will end up with a unique fully qualified name which is required to refer to it in persisted data and errors.
+	 *
 	 * @param scope - Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.
 	 * Use of [Reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) or a UUIDv4 is recommended to avoid collisions.
 	 * You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.
@@ -228,7 +246,7 @@ export class SchemaFactory<
 	public readonly handle = handleSchema;
 
 	/**
-	 * Define a {@link TreeNodeSchema} for a {@link TreeObjectNode}.
+	 * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
 	 * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
@@ -721,6 +739,7 @@ export function structuralName<const T extends string>(
 		const names = allowedTypes.map((t): string => {
 			// Ensure that lazy types (functions) don't slip through here.
 			assert(!isLazy(t), 0x83d /* invalid type provided */);
+			markSchemaMostDerived(t);
 			return t.identifier;
 		});
 		// Ensure name is order independent
@@ -732,3 +751,27 @@ export function structuralName<const T extends string>(
 	}
 	return `${collectionName}<${inner}>`;
 }
+
+/**
+ * Indicates that a schema is the "most derived" version which is allowed to be used, see {@link MostDerivedData}.
+ * Calling helps with error messages about invalid schema usage (using more than one type from single schema factor produced type,
+ * and thus calling this for one than one subclass).
+ * @remarks
+ * Helper for invoking {@link TreeNodeValid.markMostDerived} for any {@link TreeNodeSchema} if it needed.
+ */
+export function markSchemaMostDerived(schema: TreeNodeSchema): void {
+	if (schema instanceof LeafNodeSchema) {
+		return;
+	}
+
+	if (!inPrototypeChain(schema, TreeNodeValid)) {
+		// Use JSON.stringify to quote and escape identifier string.
+		throw new UsageError(
+			`Schema for ${JSON.stringify(
+				schema.identifier,
+			)} does not extend a SchemaFactory generated class. This is invalid.`,
+		);
+	}
+
+	(schema as typeof TreeNodeValid & TreeNodeSchema).markMostDerived();
+}

package/src/simple-tree/schemaTypes.ts

@@ -67,6 +67,41 @@ export interface TreeNodeSchemaNonClass<
  *
  * Using classes in this way allows introducing a named type and a named value at the same time, helping keep the runtime and compile time information together and easy to refer to un a uniform way.
  * Additionally, this works around https://github.com/microsoft/TypeScript/issues/55832 which causes similar patterns with less explicit types to infer "any" in the d.ts file.
+ *
+ * When sub-classing a a `TreeNodeSchemaClass`, some extra rules must be followed:
+ *
+ * - Only ever use a single class from the schema's class hierarchy within a document and its schema.
+ * For example, if using {@link SchemaFactory.object} you can do:
+ * ```typescript
+ * // Recommended "customizable" object schema pattern.
+ * class Good extends schemaFactory.object("A", {
+ * 	exampleField: schemaFactory.number,
+ * }) {
+ * 	public exampleCustomMethod(): void {
+ * 		this.exampleField++;
+ * 	}
+ * }
+ * ```
+ * But should avoid:
+ * ```typescript
+ * // This by itself is ok, and opts into "POJO mode".
+ * const base = schemaFactory.object("A", {});
+ * // This is a bad pattern since it leaves two classes in scope which derive from the same SchemaFactory defined class.
+ * // If both get used, its an error!
+ * class Invalid extends base {}
+ * ```
+ * - Do not modify the constructor input parameter types or values:
+ * ```typescript
+ * class Invalid extends schemaFactory.object("A", {
+ * 	exampleField: schemaFactory.number,
+ * }) {
+ * 	// This Modifies the type of the constructor input.
+ * 	// This is unsupported due to programmatic access to the constructor being used internally.
+ * 	public constructor(a: number) {
+ * 		super({ exampleField: a });
+ * 	}
+ * }
+ * ```
  * @sealed @public
  */
 export interface TreeNodeSchemaClass<
@@ -81,7 +116,7 @@ export interface TreeNodeSchemaClass<
 	 * Constructs an {@link Unhydrated} node with this schema.
 	 * @remarks
 	 * This constructor is also used internally to construct hydrated nodes with a different parameter type.
-	 * Therefor overriding this constructor is not type-safe and is not supported.
+	 * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.
 	 * @sealed
 	 */
 	new (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;

package/src/simple-tree/toFlexSchema.ts

@@ -5,6 +5,7 @@
 
 /* eslint-disable import/no-internal-modules */
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type {
 	ITreeCursorSynchronous,
@@ -75,8 +76,8 @@ export function cursorFromUnhydratedRoot(
 }
 
 interface SchemaInfo {
-	toFlex: () => FlexTreeNodeSchema;
-	original: TreeNodeSchema;
+	readonly toFlex: () => FlexTreeNodeSchema;
+	readonly original: TreeNodeSchema;
 }
 
 type SchemaMap = Map<TreeNodeSchemaIdentifier, SchemaInfo>;
@@ -180,8 +181,8 @@ export function convertNodeSchema(
 	const fromMap = schemaMap.get(brand(schema.identifier));
 	if (fromMap !== undefined) {
 		if (fromMap.original !== schema) {
-			// Use JSON.stringify to quote and escape string.
-			throw new Error(
+			// Use JSON.stringify to quote and escape identifier string.
+			throw new UsageError(
 				`Multiple schema encountered with the identifier ${JSON.stringify(
 					schema.identifier,
 				)}. Remove or rename them to avoid the collision.`,

package/src/simple-tree/tree.ts

@@ -9,11 +9,20 @@ import type { CommitMetadata } from "../core/index.js";
 import type { Listenable } from "../events/index.js";
 import type { RevertibleFactory } from "../shared-tree/index.js";
 
-import type {
-	ImplicitFieldSchema,
-	InsertableTreeFieldFromImplicitField,
-	TreeFieldFromImplicitField,
+import {
+	type ImplicitAllowedTypes,
+	NodeKind,
+	normalizeFieldSchema,
+	type ImplicitFieldSchema,
+	type InsertableTreeFieldFromImplicitField,
+	type TreeFieldFromImplicitField,
+	type TreeNodeSchema,
 } from "./schemaTypes.js";
+import { toFlexSchema } from "./toFlexSchema.js";
+import { LeafNodeSchema } from "./leafNodeSchema.js";
+import { assert } from "@fluidframework/core-utils/internal";
+import { isObjectNodeSchema } from "./objectNode.js";
+import { markSchemaMostDerived } from "./schemaFactory.js";
 
 /**
  * Channel for a Fluid Tree DDS.
@@ -130,6 +139,58 @@ export class TreeViewConfiguration<TSchema extends ImplicitFieldSchema = Implici
 		const config = { ...defaultTreeConfigurationOptions, ...props };
 		this.schema = config.schema;
 		this.enableSchemaValidation = config.enableSchemaValidation;
+
+		// Ensure all reachable schema are marked as most derived.
+		// 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.
+		walkFieldSchema(config.schema, markSchemaMostDerived);
+		// Eagerly perform this conversion to surface errors sooner.
+		toFlexSchema(config.schema);
+	}
+}
+
+export function walkNodeSchema(
+	schema: TreeNodeSchema,
+	visitor: (schema: TreeNodeSchema) => void,
+	visitedSet: Set<TreeNodeSchema>,
+): void {
+	if (visitedSet.has(schema)) {
+		return;
+	}
+	visitedSet.add(schema);
+	if (schema instanceof LeafNodeSchema) {
+		// nothing to do
+	} else if (isObjectNodeSchema(schema)) {
+		for (const field of schema.fields.values()) {
+			walkAllowedTypes(field.allowedTypeSet, visitor, visitedSet);
+		}
+	} else {
+		assert(schema.kind === NodeKind.Array || schema.kind === NodeKind.Map, "invalid schema");
+		const childTypes = schema.info as ImplicitAllowedTypes;
+		walkFieldSchema(childTypes, visitor, visitedSet);
+	}
+	// This visit is done at the end so the traversal order is most inner types first.
+	// This was picked since when fixing errors,
+	// working from the inner types out to the types that use them will probably go better than the reverse.
+	// This does not however ensure all types referenced by a type are visited before it, since in recursive cases thats impossible.
+	visitor(schema);
+}
+
+export function walkFieldSchema(
+	schema: ImplicitFieldSchema,
+	visitor: (schema: TreeNodeSchema) => void,
+	visitedSet: Set<TreeNodeSchema> = new Set(),
+): void {
+	walkAllowedTypes(normalizeFieldSchema(schema).allowedTypeSet, visitor, visitedSet);
+}
+
+export function walkAllowedTypes(
+	allowedTypes: Iterable<TreeNodeSchema>,
+	visitor: (schema: TreeNodeSchema) => void,
+	visitedSet: Set<TreeNodeSchema>,
+): void {
+	for (const childType of allowedTypes) {
+		walkNodeSchema(childType, visitor, visitedSet);
 	}
 }
 

package/src/simple-tree/treeNodeApi.ts

@@ -7,11 +7,11 @@ import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import { Multiplicity, rootFieldKey } from "../core/index.js";
 import {
-	FieldKinds,
 	type LazyItem,
 	type TreeStatus,
 	isLazy,
 	isTreeValue,
+	FlexObjectNodeSchema,
 } from "../feature-libraries/index.js";
 import { fail, extractFromOpaque, isReadonlyArray } from "../util/index.js";
 
@@ -201,26 +201,26 @@ export const treeNodeApi: TreeNodeApi = {
 	},
 	shortId(node: TreeNode): number | string | undefined {
 		const flexNode = getFlexNode(node);
-		let shortId: number | string | undefined;
-		for (const field of flexNode.boxedIterator()) {
-			if (field.schema.kind === FieldKinds.identifier) {
-				if (shortId !== undefined) {
-					throw new UsageError(
-						"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.",
-					);
-				}
-				const identifier = field.boxedAt(0);
+		const flexSchema = flexNode.schema;
+		const identifierFieldKeys =
+			flexSchema instanceof FlexObjectNodeSchema ? flexSchema.identifierFieldKeys : [];
+
+		switch (identifierFieldKeys.length) {
+			case 0:
+				return undefined;
+			case 1: {
+				const identifier = flexNode.tryGetField(identifierFieldKeys[0])?.boxedAt(0);
 				assert(identifier !== undefined, 0x927 /* The identifier must exist */);
 				const identifierValue = identifier.value as string;
 				const localNodeKey =
 					identifier.context.nodeKeyManager.tryLocalizeNodeKey(identifierValue);
-
-				shortId =
-					localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;
+				return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;
 			}
+			default:
+				throw new UsageError(
+					"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.",
+				);
 		}
-
-		return shortId;
 	},
 };
 

package/src/simple-tree/types.ts

@@ -208,51 +208,65 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 	 * Also used to detect if oneTimeSetup has run.
 	 *
 	 * @privateRemarks
-	 * This defaults to TreeNodeValid, which is used to trigger an error if not overridden in the derived class.
+	 * This defaults to "default", which is used to trigger an error if not overridden in the derived class.
 	 *
 	 * The value of this on TreeNodeValid must only be overridden by base classes and never modified.
 	 * Ways to enforce this immutability prevent it from being overridden,
 	 * so code modifying constructorCached should be extra careful to avoid accidentally modifying the base/inherited value.
 	 */
-	protected static constructorCached: typeof TreeNodeValid | undefined = TreeNodeValid;
+	protected static constructorCached: MostDerivedData | "default" | undefined = "default";
+
+	/**
+	 * Indicate that `this` is the most derived version of a schema, and thus the only one allowed to be used (other than by being subclassed a single time).
+	 */
+	public static markMostDerived(this: typeof TreeNodeValid & TreeNodeSchema): MostDerivedData {
+		assert(this.constructorCached !== "default", 0x95f /* invalid schema class */);
+
+		if (this.constructorCached === undefined) {
+			// Set the constructorCached on the layer of the prototype chain that declared it.
+			// This is necessary to ensure there is only one subclass of that type used:
+			// if constructorCached was simply set on `schema`,
+			// then a base classes between `schema` (exclusive) and where `constructorCached` is set (inclusive) and other subclasses of them
+			// would not see the stored `constructorCached`, and the validation above against multiple derived classes would not work.
+
+			// This is not just an alias of `this`, but a reference to the item in the prototype chain being walked, which happens to start at `this`.
+			// eslint-disable-next-line @typescript-eslint/no-this-alias
+			let schemaBase: typeof TreeNodeValid = this;
+			while (!Object.prototype.hasOwnProperty.call(schemaBase, "constructorCached")) {
+				schemaBase = Reflect.getPrototypeOf(schemaBase) as typeof TreeNodeValid;
+			}
+			assert(schemaBase.constructorCached === undefined, 0x962 /* overwriting wrong cache */);
+			schemaBase.constructorCached = { constructor: this, oneTimeInitialized: false };
+			assert(
+				this.constructorCached === schemaBase.constructorCached,
+				"Inheritance should work",
+			);
+			return this.constructorCached;
+		} else if (this.constructorCached.constructor === this) {
+			return this.constructorCached;
+		}
+
+		throw new UsageError(
+			`Two schema classes were used (${this.name} and ${
+				this.constructorCached.constructor.name
+			}) which derived from the same SchemaFactory generated class (${JSON.stringify(
+				this.identifier,
+			)}). This is invalid.`,
+		);
+	}
 
 	public constructor(input: TInput | InternalTreeNode) {
 		super();
 		const schema = this.constructor as typeof TreeNodeValid & TreeNodeSchema;
-		assert("constructorCached" in schema, 0x95f /* invalid schema class */);
-		if (schema.constructorCached !== schema) {
-			if (schema.constructorCached !== undefined) {
-				assert(
-					schema.constructorCached !== TreeNodeValid,
-					0x960 /* Schema class schema must override static constructorCached member */,
-				);
-				throw new UsageError(
-					`Two schema classes were instantiated (${schema.name} and ${schema.constructorCached.name}) which derived from the same SchemaFactory generated class. This is invalid`,
-				);
-			}
-
+		const cache = schema.markMostDerived();
+		if (!cache.oneTimeInitialized) {
 			const flexSchema = getFlexSchema(schema);
 			assert(
 				tryGetSimpleNodeSchema(flexSchema) === schema,
 				0x961 /* Schema class not properly configured */,
 			);
 			schema.oneTimeSetup();
-			// Set the constructorCached on the layer of the prototype chain that declared it.
-			// This is necessary to ensure there is only one subclass of that type used:
-			// if constructorCached was simply set on `schema`,
-			// then a base classes between `schema` (exclusive) and where `constructorCached` is set (inclusive) and other subclasses of them
-			// would not see the stored `constructorCached`, and the validation above against multiple derived classes would not work.
-			{
-				let schemaBase: typeof TreeNodeValid = schema;
-				while (!Object.prototype.hasOwnProperty.call(schemaBase, "constructorCached")) {
-					schemaBase = Reflect.getPrototypeOf(schemaBase) as typeof TreeNodeValid;
-				}
-				assert(
-					schemaBase.constructorCached === undefined,
-					0x962 /* overwriting wrong cache */,
-				);
-				schemaBase.constructorCached = schema;
-			}
+			cache.oneTimeInitialized = true;
 		}
 
 		if (isTreeNode(input)) {
@@ -278,6 +292,22 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 // Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.
 markEager(TreeNodeValid);
 
+/**
+ * Data cached about the most derived type in a schema's class hierarchy.
+ * @remarks
+ * The most derived type is the only one allowed to be referenced by other schema or constructed as a node.
+ * It has to be discovered lazily (when a node is constructed or when a {@link TreeViewConfiguration} is made),
+ * since JavaScript provides no way to find derived classes, or inject static class initialization time logic into base classes.
+ * Additionally since schema can reference other schema through lazy references which might be forward or recursive references,
+ * this can not be evaluated for one schema when referenced by another schema.
+ *
+ * See {@link TreeNodeValid.constructorCached} and {@link TreeNodeValid.markMostDerived}.
+ */
+export interface MostDerivedData {
+	readonly constructor: typeof TreeNodeValid & TreeNodeSchema;
+	oneTimeInitialized: boolean;
+}
+
 /**
  * A node type internal to `@fluidframework/tree`.
  * @remarks