@fluidframework/tree 2.23.0 → 2.30.0

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

@@ -51,7 +51,7 @@ export type Unenforced<_DesiredExtendsConstraint> = unknown;
 /**
  * {@link Unenforced} version of `ObjectFromSchemaRecord`.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type ObjectFromSchemaRecordUnsafe<
@@ -121,7 +121,7 @@ export interface TreeNodeSchemaNonClassUnsafe<
 /**
  * {@link Unenforced} version of {@link TreeObjectNode}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type TreeObjectNodeUnsafe<
@@ -132,7 +132,7 @@ export type TreeObjectNodeUnsafe<
 /**
  * {@link Unenforced} version of {@link TreeFieldFromImplicitField}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type TreeFieldFromImplicitFieldUnsafe<TSchema extends Unenforced<ImplicitFieldSchema>> =
@@ -153,7 +153,7 @@ export type AllowedTypesUnsafe = readonly LazyItem<TreeNodeSchemaUnsafe>[];
 /**
  * {@link Unenforced} version of {@link TreeNodeFromImplicitAllowedTypes}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type TreeNodeFromImplicitAllowedTypesUnsafe<
@@ -168,7 +168,7 @@ export type TreeNodeFromImplicitAllowedTypesUnsafe<
  * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<
@@ -197,7 +197,7 @@ export type InsertableTreeNodeFromAllowedTypesUnsafe<
  * {@link Unenforced} version of {@link InsertableTypedNode}.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @privateRemarks
  * TODO:
  * This is less strict than InsertableTypedNode when given non-exact schema to avoid compilation issues.
@@ -216,7 +216,7 @@ export type InsertableTypedNodeUnsafe<
 /**
  * {@link Unenforced} version of {@link NodeFromSchema}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> =
@@ -225,7 +225,7 @@ export type NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> =
 /**
  * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =
@@ -234,7 +234,7 @@ export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =
 /**
  * {@link Unenforced} version of {@link (TreeArrayNode:interface)}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @sealed @public
  */
 export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAllowedTypes>>
@@ -247,7 +247,7 @@ export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAl
 /**
  * {@link Unenforced} version of {@link TreeMapNode}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @sealed @public
  */
 export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
@@ -271,7 +271,7 @@ export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
  * Copy of TypeScript's ReadonlyMap, but with `TreeNodeFromImplicitAllowedTypesUnsafe<T>` inlined into it.
  * Using this instead of ReadonlyMap in TreeMapNodeUnsafe is necessary to make recursive map schema not generate compile errors in the d.ts files when exported.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @privateRemarks
  * This is the same as `ReadonlyMap<K, TreeNodeFromImplicitAllowedTypesUnsafe<T>>` (Checked in test),
  * except that it avoids the above mentioned compile error.
@@ -313,7 +313,7 @@ export interface ReadonlyMapInlined<K, T extends Unenforced<ImplicitAllowedTypes
 /**
  * {@link Unenforced} version of `FieldHasDefault`.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @sealed @public
  */
 export type FieldHasDefaultUnsafe<T extends Unenforced<ImplicitFieldSchema>> =
@@ -328,7 +328,7 @@ export type FieldHasDefaultUnsafe<T extends Unenforced<ImplicitFieldSchema>> =
  * {@link Unenforced} version of `InsertableObjectFromSchemaRecord`.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type InsertableObjectFromSchemaRecordUnsafe<
@@ -350,7 +350,7 @@ export type InsertableObjectFromSchemaRecordUnsafe<
  * {@link Unenforced} version of {@link InsertableTreeFieldFromImplicitField}.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @system @public
  */
 export type InsertableTreeFieldFromImplicitFieldUnsafe<
@@ -365,7 +365,7 @@ export type InsertableTreeFieldFromImplicitFieldUnsafe<
 /**
  * {@link Unenforced} version of {@link FieldSchema}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
  * @public
  */
 export interface FieldSchemaUnsafe<

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

@@ -39,9 +39,10 @@ import {
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
 import {
 	customFromCursor,
+	replaceHandles,
 	type CustomTreeNode,
-	type CustomTreeValue,
 	type EncodeOptions,
+	type HandleConverter,
 } from "./customTree.js";
 import { getUnhydratedContext } from "../createContext.js";
 
@@ -110,20 +111,10 @@ export interface VerboseTreeNode<THandle = IFluidHandle> {
 }
 
 /**
- * Options for how to interpret a `VerboseTree<TCustom>` when schema information is available.
+ * Options for how to interpret a `VerboseTree` when schema information is available.
  * @alpha
  */
-export interface ParseOptions<TCustom> {
-	/**
-	 * Fixup custom input formats.
-	 * @remarks
-	 * Main usage is to handle IFluidHandles.
-	 * When targeting JSON compatibility,
-	 * this may be by throwing an error or including a placeholder.
-	 * Since IFluidHandles are special references to FLuid data which is garbage collected when not referenced by the container for long enough,
-	 * any scheme for encoding handles for storage outside the container (or in formats the container does not understand) is unreliable.
-	 */
-	valueConverter(data: VerboseTree<TCustom>): TreeLeafValue | VerboseTreeNode<TCustom>;
+export interface ParseOptions {
 	/**
 	 * If true, interpret the input keys of object nodes as stored keys.
 	 * If false, interpret them as property keys.
@@ -133,15 +124,9 @@ export interface ParseOptions<TCustom> {
 }
 
 /**
- * Options for how to interpret a `VerboseTree<TCustom>` without relying on schema.
+ * Options for how to interpret a `VerboseTree` without relying on schema.
  */
-export interface SchemalessParseOptions<TCustom> {
-	/**
-	 * Fixup custom input formats.
-	 * @remarks
-	 * See note on {@link ParseOptions.valueConverter}.
-	 */
-	valueConverter(data: VerboseTree<TCustom>): TreeLeafValue | VerboseTreeNode<TCustom>;
+export interface SchemalessParseOptions {
 	/**
 	 * Converts stored keys into whatever key the tree is using in its encoding.
 	 */
@@ -154,11 +139,11 @@ export interface SchemalessParseOptions<TCustom> {
 /**
  * Use info from `schema` to convert `options` to {@link SchemalessParseOptions}.
  */
-export function applySchemaToParserOptions<TCustom>(
+export function applySchemaToParserOptions(
 	schema: ImplicitFieldSchema,
-	options: ParseOptions<TCustom>,
-): SchemalessParseOptions<TCustom> {
-	const config: Required<ParseOptions<TCustom>> = {
+	options: ParseOptions,
+): SchemalessParseOptions {
+	const config: Required<ParseOptions> = {
 		useStoredKeys: false,
 		...options,
 	};
@@ -166,7 +151,6 @@ export function applySchemaToParserOptions<TCustom>(
 	const context = getUnhydratedContext(schema);
 
 	return {
-		valueConverter: config.valueConverter,
 		keyConverter: config.useStoredKeys
 			? undefined
 			: {
@@ -213,9 +197,9 @@ export function applySchemaToParserOptions<TCustom>(
  *
  * @returns an {@link ITreeCursorSynchronous} for a single node in nodes mode.
  */
-export function cursorFromVerbose<TCustom>(
-	data: VerboseTree<TCustom>,
-	options: SchemalessParseOptions<TCustom>,
+export function cursorFromVerbose(
+	data: VerboseTree,
+	options: SchemalessParseOptions,
 ): ITreeCursorSynchronous {
 	return stackTreeNodeCursor(verboseTreeAdapter(options), data);
 }
@@ -225,9 +209,9 @@ export function cursorFromVerbose<TCustom>(
  *
  * @returns an {@link ITreeCursorSynchronous} for a single field in fields mode.
  */
-export function fieldCursorFromVerbose<TCustom>(
-	data: VerboseTree<TCustom>[],
-	options: SchemalessParseOptions<TCustom>,
+export function fieldCursorFromVerbose(
+	data: VerboseTree[],
+	options: SchemalessParseOptions,
 ): ITreeCursorSynchronous {
 	return stackTreeFieldCursor(
 		verboseTreeAdapter(options),
@@ -236,16 +220,12 @@ export function fieldCursorFromVerbose<TCustom>(
 	);
 }
 
-function verboseTreeAdapter<TCustom>(
-	options: SchemalessParseOptions<TCustom>,
-): CursorAdapter<VerboseTree<TCustom>> {
+function verboseTreeAdapter(options: SchemalessParseOptions): CursorAdapter<VerboseTree> {
 	return {
-		value: (input: VerboseTree<TCustom>) => {
-			const node = options.valueConverter(input);
+		value: (node: VerboseTree) => {
 			return isTreeValue(node) ? node : undefined;
 		},
-		type: (input: VerboseTree<TCustom>) => {
-			const node = options.valueConverter(input);
+		type: (node: VerboseTree) => {
 			switch (typeof node) {
 				case "number":
 					return numberSchema.identifier as TreeNodeSchemaIdentifier;
@@ -263,8 +243,7 @@ function verboseTreeAdapter<TCustom>(
 					return node.type as TreeNodeSchemaIdentifier;
 			}
 		},
-		keysFromNode: (input: VerboseTree<TCustom>): readonly FieldKey[] => {
-			const node = options.valueConverter(input);
+		keysFromNode: (node: VerboseTree): readonly FieldKey[] => {
 			switch (typeof node) {
 				case "object": {
 					if (node === null) {
@@ -288,11 +267,7 @@ function verboseTreeAdapter<TCustom>(
 					return [];
 			}
 		},
-		getFieldFromNode: (
-			input: VerboseTree<TCustom>,
-			key: FieldKey,
-		): readonly VerboseTree<TCustom>[] => {
-			const node = options.valueConverter(input);
+		getFieldFromNode: (node: VerboseTree, key: FieldKey): readonly VerboseTree[] => {
 			// Object.prototype.hasOwnProperty can return true for strings (ex: with key "0"), so we have to filter them out.
 			// Rather than just special casing strings, we can handle them with an early return for all primitives.
 			if (typeof node !== "object") {
@@ -327,12 +302,12 @@ function verboseTreeAdapter<TCustom>(
 /**
  * Used to read a node cursor as a VerboseTree.
  */
-export function verboseFromCursor<TCustom>(
+export function verboseFromCursor(
 	reader: ITreeCursor,
 	rootSchema: ImplicitAllowedTypes,
-	options: EncodeOptions<TCustom>,
-): VerboseTree<TCustom> {
-	const config: Required<EncodeOptions<TCustom>> = {
+	options: EncodeOptions,
+): VerboseTree {
+	const config: Required<EncodeOptions> = {
 		useStoredKeys: false,
 		...options,
 	};
@@ -342,20 +317,33 @@ export function verboseFromCursor<TCustom>(
 	return verboseFromCursorInner(reader, config, schemaMap);
 }
 
-function verboseFromCursorInner<TCustom>(
+function verboseFromCursorInner(
 	reader: ITreeCursor,
-	options: Required<EncodeOptions<TCustom>>,
+	options: Required<EncodeOptions>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
-): VerboseTree<TCustom> {
+): VerboseTree {
 	const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);
 	const nodeSchema =
 		schema.get(reader.type) ?? fail(0xb3c /* missing schema for type in cursor */);
 	if (nodeSchema.kind === NodeKind.Leaf) {
-		return fields as CustomTreeValue<TCustom>;
+		return fields as TreeLeafValue;
 	}
 
 	return {
 		type: reader.type,
-		fields: fields as CustomTreeNode<TCustom>,
+		fields: fields as CustomTreeNode<VerboseTree>,
 	};
 }
+
+/**
+ * Clones tree, replacing any handles.
+ * @remarks
+ * A strongly types version of {@link replaceHandles}.
+ * @alpha
+ */
+export function replaceVerboseTreeHandles<T>(
+	tree: VerboseTree,
+	replacer: HandleConverter<T>,
+): VerboseTree<T> {
+	return replaceHandles(tree, replacer) as VerboseTree<T>;
+}

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

@@ -15,10 +15,10 @@ import {
 	type ExclusiveMapTree,
 	type FieldKey,
 	type FieldKindIdentifier,
-	type FieldUpPath,
 	forbiddenFieldKindIdentifier,
 	type ITreeCursorSynchronous,
 	type MapTree,
+	type NormalizedFieldUpPath,
 	type SchemaPolicy,
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
@@ -394,7 +394,7 @@ class UnhydratedFlexTreeField implements FlexTreeField {
 		this.onEdit?.();
 	}
 
-	public getFieldPath(): FieldUpPath {
+	public getFieldPath(): NormalizedFieldUpPath {
 		throw unsupportedUsageError("Editing an array");
 	}
 

package/src/simple-tree/flexList.ts

@@ -44,28 +44,18 @@ export function markEager<T>(t: T): T {
  * By default, items that are of type `"function"` will be considered lazy and all other items will be considered eager.
  * To force a `"function"` item to be treated as an eager item, call `markEager` before putting it in the list.
  * This is necessary e.g. when the eager list items are function types and the lazy items are functions that _return_ function types.
- * `FlexList`s are processed by `normalizeFlexList` and `normalizeFlexListEager`.
+ * Our one use of FlexList has some special normalization logic, see {@link normalizeAllowedTypes}.
  * @system @public
  */
 export type FlexList<Item = unknown> = readonly LazyItem<Item>[];
 
-/**
- * Given a `FlexList` of eager and lazy items, return an equivalent list where all items are eager.
- */
-export function normalizeFlexListEager<T>(t: FlexList<T>): T[] {
-	const data: T[] = t.map((value: LazyItem<T>) => {
-		if (isLazy(value)) {
-			return value();
-		}
-		return value;
-	});
-	return data;
-}
-
 /**
  * An "eager" or "lazy" Item in a `FlexList`.
  * Lazy items are wrapped in a function to allow referring to themselves before they are declared.
  * This makes recursive and co-recursive items possible.
+ * @privateRemarks
+ * `schemaTypes.ts`'s `evaluateLazySchema` (via {@link normalizeAllowedTypes})
+ * applies caching for the only current use of this type.
  * @public
  */
 export type LazyItem<Item = unknown> = Item | (() => Item);

package/src/simple-tree/index.ts

@@ -136,6 +136,11 @@ export {
 	type TransactionResultSuccess,
 	type TransactionResultFailed,
 	rollback,
+	generateSchemaFromSimpleSchema,
+	replaceConciseTreeHandles,
+	replaceHandles,
+	replaceVerboseTreeHandles,
+	type HandleConverter,
 } from "./api/index.js";
 export {
 	type NodeFromSchema,
@@ -170,6 +175,7 @@ export {
 	type ReadSchema,
 	type NodeSchemaOptions,
 	type NodeSchemaMetadata,
+	evaluateLazySchema,
 } from "./schemaTypes.js";
 export {
 	getTreeNodeForField,

package/src/simple-tree/objectNode.ts

@@ -340,6 +340,9 @@ export function objectSchema<
 	metadata?: NodeSchemaMetadata<TCustomMetadata>,
 ): ObjectNodeSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> &
 	ObjectNodeSchemaInternalData {
+	// Field set can't be modified after this since derived data is stored in maps.
+	Object.freeze(info);
+
 	// Ensure no collisions between final set of property keys, and final set of stored keys (including those
 	// implicitly derived from property keys)
 	assertUniqueKeys(identifier, info);

package/src/simple-tree/schemaTypes.ts

@@ -7,7 +7,7 @@ import type { ErasedType, IFluidHandle } from "@fluidframework/core-interfaces";
 import { Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { NodeKeyManager } from "../feature-libraries/index.js";
+import type { NodeIdentifierManager } from "../feature-libraries/index.js";
 import {
 	type MakeNominal,
 	brand,
@@ -16,6 +16,7 @@ import {
 	compareSets,
 	type requireTrue,
 	type areOnlyKeys,
+	getOrCreate,
 } from "../util/index.js";
 import type {
 	Unhydrated,
@@ -26,9 +27,12 @@ import type {
 	TreeNodeSchemaCore,
 	TreeNodeSchemaNonClass,
 } from "./core/index.js";
+import { inPrototypeChain } from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
 import type { InsertableContent } from "./toMapTree.js";
 import { isLazy, type FlexListToUnion, type LazyItem } from "./flexList.js";
+import { LeafNodeSchema } from "./leafNodeSchema.js";
+import { TreeNodeValid } from "./treeNodeValid.js";
 
 /**
  * Returns true if the given schema is a {@link TreeNodeSchemaClass}, or otherwise false if it is a {@link TreeNodeSchemaNonClass}.
@@ -69,6 +73,8 @@ export function isTreeNodeSchemaClass<
  * way to declare and manipulate unordered sets of types in TypeScript.
  *
  * Not intended for direct use outside of package.
+ * @privateRemarks
+ * Code reading data from this should use `normalizeAllowedTypes` to ensure consistent handling, caching, nice errors etc.
  * @system @public
  */
 export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
@@ -202,7 +208,7 @@ export interface FieldProps<TCustomMetadata = unknown> {
  * A {@link FieldProvider} which requires additional context in order to produce its content
  */
 export type ContextualFieldProvider = (
-	context: NodeKeyManager,
+	context: NodeIdentifierManager,
 ) => InsertableContent | undefined;
 /**
  * A {@link FieldProvider} which can produce its content in a vacuum
@@ -379,6 +385,8 @@ export function normalizeAllowedTypes(
 ): ReadonlySet<TreeNodeSchema> {
 	const normalized = new Set<TreeNodeSchema>();
 	if (isReadonlyArray(types)) {
+		// Types array must not be modified after it is normalized since that would result in the user of the normalized data having wrong (out of date) content.
+		Object.freeze(types);
 		for (const lazyType of types) {
 			normalized.add(evaluateLazySchema(lazyType));
 		}
@@ -469,16 +477,72 @@ function areMetadataEqual(
 	return a?.custom === b?.custom && a?.description === b?.description;
 }
 
-function evaluateLazySchema(value: LazyItem<TreeNodeSchema>): TreeNodeSchema {
-	const evaluatedSchema = isLazy(value) ? value() : value;
+const cachedLazyItem = new WeakMap<() => unknown, unknown>();
+
+/**
+ * Returns the schema referenced by the {@link LazyItem}.
+ * @remarks
+ * Caches results to handle {@link LazyItem}s which compute their resulting schema.
+ * @alpha
+ */
+export function evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>): T {
+	const evaluatedSchema = isLazy(value)
+		? (getOrCreate(cachedLazyItem, value, value) as T)
+		: value;
 	if (evaluatedSchema === undefined) {
 		throw new UsageError(
 			`Encountered an undefined schema. This could indicate that some referenced schema has not yet been instantiated.`,
 		);
 	}
+	markSchemaMostDerived(evaluatedSchema);
 	return evaluatedSchema;
 }
 
+/**
+ * Indicates that the provided schema is the "most derived" version in its class hierarchy.
+ *
+ * @param oneTimeInitialize - If true this runs {@link TreeNodeValid.oneTimeInitialize} which does even more initialization and validation.
+ * `oneTimeInitialize` can't safely be run until all transitively referenced schema are defined, so which cases can safely use it are more limited.
+ * When legal for the caller to set this to true, it is preferred, but it is often not safe due to possible forward references.
+ * @remarks
+ * See {@link MostDerivedData} and {@link SchemaFactory} for details on what a "most derived" schema is and why it matters.
+ *
+ * This is a helper for invoking {@link TreeNodeValid.markMostDerived} for {@link TreeNodeSchema}.
+ *
+ * Calling this helps with error messages about invalid schema usage (See {@link SchemaFactory} for the rules, some of which this helps validate).
+ * Typically this should be called for each schema as early as practical to improve error reporting for invalid usages of schema
+ * (using two different schema derived from the same {@link SchemaFactory} produced base class).
+ *
+ * Note that construction of actual {@link TreeNode} instances or use of a schema transitively in a {@link TreeViewConfiguration} already do this,
+ * so any calls to this that is unconditionally after that point for the given schema is not needed.
+ * Instead most usages of this should be from those cases, and from miscellaneous cases where a schema is passed into an public API where theoretically someone could accidentally
+ * pass in a base class of a schema instead of the most derived one.
+ */
+export function markSchemaMostDerived(
+	schema: TreeNodeSchema,
+	oneTimeInitialize = false,
+): 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.`,
+		);
+	}
+
+	const schemaValid = schema as typeof TreeNodeValid & TreeNodeSchema;
+	if (oneTimeInitialize) {
+		schemaValid.oneTimeInitialize();
+	} else {
+		schemaValid.markMostDerived();
+	}
+}
+
 /**
  * Types of {@link TreeNode|TreeNodes} or {@link TreeLeafValue|TreeLeafValues} allowed at a location in a tree.
  * @remarks
@@ -508,6 +572,8 @@ function evaluateLazySchema(value: LazyItem<TreeNodeSchema>): TreeNodeSchema {
  * class A extends sf.array("example", [() => B]) {}
  * class B extends sf.array("Inner", sf.number) {}
  * ```
+ * @privateRemarks
+ * Code reading data from this should use `normalizeAllowedTypes` to ensure consistent handling, caching, nice errors etc.
  * @public
  */
 export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;

package/src/simple-tree/toMapTree.ts

@@ -19,7 +19,7 @@ import {
 import {
 	isTreeValue,
 	valueSchemaAllows,
-	type NodeKeyManager,
+	type NodeIdentifierManager,
 } from "../feature-libraries/index.js";
 import { brand, fail, isReadonlyArray, find, hasSome, hasSingle } from "../util/index.js";
 
@@ -104,19 +104,19 @@ import type { IFluidHandle } from "@fluidframework/core-interfaces";
 export function mapTreeFromNodeData(
 	data: InsertableContent,
 	allowedTypes: ImplicitAllowedTypes,
-	context?: NodeKeyManager,
+	context?: NodeIdentifierManager,
 	schemaValidationPolicy?: SchemaAndPolicy,
 ): ExclusiveMapTree;
 export function mapTreeFromNodeData(
 	data: InsertableContent | undefined,
 	allowedTypes: ImplicitFieldSchema,
-	context?: NodeKeyManager,
+	context?: NodeIdentifierManager,
 	schemaValidationPolicy?: SchemaAndPolicy,
 ): ExclusiveMapTree | undefined;
 export function mapTreeFromNodeData(
 	data: InsertableContent | undefined,
 	allowedTypes: ImplicitFieldSchema,
-	context?: NodeKeyManager,
+	context?: NodeIdentifierManager,
 	schemaValidationPolicy?: SchemaAndPolicy,
 ): ExclusiveMapTree | undefined {
 	const normalizedFieldSchema = normalizeFieldSchema(allowedTypes);
@@ -638,7 +638,7 @@ function allowsValue(schema: TreeNodeSchema, value: TreeValue): boolean {
 export function addDefaultsToMapTree(
 	mapTree: ExclusiveMapTree,
 	allowedTypes: ImplicitAllowedTypes,
-	context: NodeKeyManager | undefined,
+	context: NodeIdentifierManager | undefined,
 ): void {
 	const schema =
 		find(normalizeAllowedTypes(allowedTypes), (s) => s.identifier === mapTree.type) ??
@@ -695,7 +695,7 @@ export function addDefaultsToMapTree(
  */
 function provideDefault(
 	fieldProvider: FieldProvider,
-	context: NodeKeyManager | undefined,
+	context: NodeIdentifierManager | undefined,
 ): InsertableContent | undefined {
 	if (context !== undefined) {
 		return fieldProvider(context);

package/src/simple-tree/toStoredSchema.ts

@@ -20,18 +20,18 @@ import {
 	type TreeTypeSet,
 } from "../core/index.js";
 import { FieldKinds, type FlexFieldKind } from "../feature-libraries/index.js";
-import { brand, fail, getOrCreate, isReadonlyArray } from "../util/index.js";
+import { brand, fail, getOrCreate } from "../util/index.js";
 import { NodeKind, type TreeNodeSchema } from "./core/index.js";
 import {
 	FieldKind,
 	FieldSchema,
+	normalizeAllowedTypes,
 	type ImplicitAllowedTypes,
 	type ImplicitFieldSchema,
 } from "./schemaTypes.js";
 import { walkFieldSchema } from "./walkFieldSchema.js";
 import { LeafNodeSchema } from "./leafNodeSchema.js";
 import { isObjectNodeSchema } from "./objectNodeTypes.js";
-import { normalizeFlexListEager } from "./flexList.js";
 
 const viewToStoredCache = new WeakMap<ImplicitFieldSchema, TreeStoredSchema>();
 
@@ -92,10 +92,7 @@ const convertFieldKind = new Map<FieldKind, FlexFieldKind>([
  * Normalizes an {@link ImplicitAllowedTypes} into an {@link TreeTypeSet}.
  */
 export function convertAllowedTypes(schema: ImplicitAllowedTypes): TreeTypeSet {
-	if (isReadonlyArray(schema)) {
-		return new Set(normalizeFlexListEager(schema).map((item) => brand(item.identifier)));
-	}
-	return new Set([brand(schema.identifier)]);
+	return new Set([...normalizeAllowedTypes(schema)].map((item) => brand(item.identifier)));
 }
 
 /**