@fluidframework/tree 2.22.1 → 2.23.0-325054

package/src/simple-tree/objectNode.ts

@@ -27,6 +27,8 @@ import {
 	type ImplicitAllowedTypes,
 	FieldKind,
 	type NodeSchemaMetadata,
+	type GetTypes,
+	type SchemaUnionToIntersection,
 } from "./schemaTypes.js";
 import {
 	type TreeNodeSchema,
@@ -56,11 +58,51 @@ import { getUnhydratedContext } from "./createContext.js";
  * @system @public
  */
 export type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFieldSchema>> = {
-	-readonly [Property in keyof T]: Property extends string
-		? TreeFieldFromImplicitField<T[Property]>
-		: unknown;
+	// Due to https://github.com/microsoft/TypeScript/issues/43826 we can not set the desired setter type,
+	// but we can at least remove the setter (by setting the key to never) when there should be no setter.
+	-readonly [Property in keyof T as [
+		AssignableTreeFieldFromImplicitField<T[Property & string]>,
+		// If the types we want to allow setting to are just never or undefined, remove the setter
+	] extends [never | undefined]
+		? never
+		: Property]: AssignableTreeFieldFromImplicitField<T[Property & string]>;
+} & {
+	readonly [Property in keyof T]: TreeFieldFromImplicitField<T[Property & string]>;
 };
 
+/**
+ * Type of content that can be assigned to a field of the given schema.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TSchemaInput - Schema to process.
+ * @typeparam TSchema - Do not specify: default value used as an implementation detail.
+ * @system @public
+ */
+export type AssignableTreeFieldFromImplicitField<
+	TSchemaInput extends ImplicitFieldSchema,
+	TSchema = SchemaUnionToIntersection<TSchemaInput>,
+> = [TSchema] extends [FieldSchema<infer Kind, infer Types>]
+	? ApplyKindAssignment<GetTypes<Types>["readWrite"], Kind>
+	: [TSchema] extends [ImplicitAllowedTypes]
+		? GetTypes<TSchema>["readWrite"]
+		: never;
+
+/**
+ * Suitable for assignment.
+ *
+ * @see {@link Input}
+ * @system @public
+ */
+export type ApplyKindAssignment<T, Kind extends FieldKind> = [Kind] extends [
+	FieldKind.Required,
+]
+	? T
+	: [Kind] extends [FieldKind.Optional]
+		? T | undefined
+		: // Unknown, non-exact and identifier fields are not assignable.
+			never;
+
 /**
  * A {@link TreeNode} which modules a JavaScript object.
  * @remarks
@@ -262,7 +304,7 @@ function createProxyHandler(
 			// For some reason, the getOwnPropertyDescriptor is not passed in the receiver, so use a weak map.
 			// If a refactoring is done to associated flex tree data with the target not the proxy, this extra map could be removed,
 			// and the design would be more compatible with proxyless nodes.
-			const proxy = targetToProxy.get(target) ?? fail("missing proxy");
+			const proxy = targetToProxy.get(target) ?? fail(0xadd /* missing proxy */);
 			const field = getOrCreateInnerNode(proxy).tryGetField(fieldInfo.storedKey);
 
 			const p: PropertyDescriptor = {
@@ -311,7 +353,7 @@ export function setField(
 		}
 
 		default:
-			fail("invalid FieldKind");
+			fail(0xade /* invalid FieldKind */);
 	}
 }
 
@@ -340,6 +382,9 @@ export function objectSchema<
 	metadata?: NodeSchemaMetadata<TCustomMetadata>,
 ): ObjectNodeSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> &
 	ObjectNodeSchemaInternalData {
+	// Field set can't be modified after 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/proxies.ts

@@ -56,7 +56,7 @@ export function getTreeNodeForField(field: FlexTreeField): TreeNode | TreeValue
 		}
 
 		default:
-			fail("invalid field kind");
+			fail(0xadf /* invalid field kind */);
 	}
 }
 

package/src/simple-tree/schemaTypes.ts

@@ -16,19 +16,23 @@ import {
 	compareSets,
 	type requireTrue,
 	type areOnlyKeys,
+	getOrCreate,
 } from "../util/index.js";
-import type {
-	Unhydrated,
-	NodeKind,
-	TreeNodeSchema,
-	TreeNodeSchemaClass,
-	TreeNode,
-	TreeNodeSchemaCore,
-	TreeNodeSchemaNonClass,
+import {
+	type Unhydrated,
+	type NodeKind,
+	type TreeNodeSchema,
+	type TreeNodeSchemaClass,
+	type TreeNode,
+	type TreeNodeSchemaCore,
+	type TreeNodeSchemaNonClass,
+	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>[];
@@ -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 if 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,59 @@ 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} 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 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,
+	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 +559,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;
@@ -546,13 +599,27 @@ export type TreeFieldFromImplicitField<TSchema extends ImplicitFieldSchema = Fie
  */
 export type InsertableTreeFieldFromImplicitField<
 	TSchemaInput extends ImplicitFieldSchema,
-	TSchema = UnionToIntersection<TSchemaInput>,
+	TSchema = [TSchemaInput] extends [CustomizedSchemaTyping<unknown, CustomTypes>]
+		? TSchemaInput
+		: SchemaUnionToIntersection<TSchemaInput>,
 > = [TSchema] extends [FieldSchema<infer Kind, infer Types>]
 	? ApplyKindInput<InsertableTreeNodeFromImplicitAllowedTypes<Types>, Kind, true>
 	: [TSchema] extends [ImplicitAllowedTypes]
 		? InsertableTreeNodeFromImplicitAllowedTypes<TSchema>
 		: never;
 
+/**
+ * {@link UnionToIntersection} except it does not distribute over {@link CustomizedSchemaTyping}s when the original type is a union.
+ * @privateRemarks
+ * This is a workaround for TypeScript distributing over intersections over unions when distributing extends over unions.
+ * @system @public
+ */
+export type SchemaUnionToIntersection<T> = [T] extends [
+	CustomizedSchemaTyping<unknown, CustomTypes>,
+]
+	? T
+	: UnionToIntersection<T>;
+
 /**
  * {@inheritdoc (UnsafeUnknownSchema:type)}
  * @alpha
@@ -575,22 +642,228 @@ export const UnsafeUnknownSchema: unique symbol = Symbol("UnsafeUnknownSchema");
  * Any APIs which use this must produce UsageErrors when out of schema data is encountered, and never produce unrecoverable errors,
  * or silently accept invalid data.
  * This is currently only type exported from the package: the symbol is just used as a way to get a named type.
+ *
+ * TODO: This takes a very different approach than `customizeSchemaTyping` which applies to allowed types.
+ * Maybe generalize that to apply to field schema as well and replace this with it?
  * @alpha
  */
 export type UnsafeUnknownSchema = typeof UnsafeUnknownSchema;
 
+/**
+ * {@inheritdoc (CustomizedTyping:type)}
+ * @system @public
+ */
+export const CustomizedTyping: unique symbol = Symbol("CustomizedTyping");
+
+/**
+ * A type brand used by {@link customizeSchemaTyping}.
+ * @system @public
+ */
+export type CustomizedTyping = typeof CustomizedTyping;
+
+/**
+ * Collection of schema aware types.
+ * @remarks
+ * This type is only used as a type constraint.
+ * It's fields are similar to an unordered set of generic type parameters.
+ * {@link customizeSchemaTyping} applies this to {@link ImplicitAllowedTypes} via {@link CustomizedSchemaTyping}.
+ * @sealed @public
+ */
+export interface CustomTypes {
+	/**
+	 * Type used for inserting values.
+	 */
+	readonly input: unknown;
+	/**
+	 * Type used for the read+write property on object nodes.
+	 *
+	 * Set to never to disable setter.
+	 * @remarks
+	 * Due to https://github.com/microsoft/TypeScript/issues/43826 we cannot set the desired setter type.
+	 * Instead we can only control the types of the read+write property and the type of a readonly property.
+	 *
+	 * For recursive types using {@link SchemaFactory.objectRecursive}, support for using `never` to remove setters is limited:
+	 * When the customized schema is wrapped in an {@link FieldSchema}, the setter will not be fully removed.
+	 */
+	readonly readWrite: TreeLeafValue | TreeNode;
+	/**
+	 * Type for reading data.
+	 * @remarks
+	 * See limitation for read+write properties on ObjectNodes in {@link CustomTypes.readWrite}.
+	 */
+	readonly output: TreeLeafValue | TreeNode;
+}
+
+/**
+ * Type annotation which overrides the default schema derived types with customized ones.
+ * @remarks
+ * See {@link customizeSchemaTyping} for more information.
+ * @system @public
+ */
+export type CustomizedSchemaTyping<TSchema, TCustom extends CustomTypes> = TSchema & {
+	[CustomizedTyping]: TCustom;
+};
+
+/**
+ * Default strict policy.
+ *
+ * @typeparam TSchema - The schema to process
+ * @typeparam TInput - Internal: do not specify.
+ * @typeparam TOutput - Internal: do not specify.
+ * @remarks
+ * Handles input types contravariantly so any input which might be invalid is rejected.
+ * @sealed @public
+ */
+export interface StrictTypes<
+	TSchema extends ImplicitAllowedTypes,
+	TInput = DefaultInsertableTreeNodeFromImplicitAllowedTypes<TSchema>,
+	TOutput extends TreeNode | TreeLeafValue = DefaultTreeNodeFromImplicitAllowedTypes<TSchema>,
+> {
+	input: TInput;
+	readWrite: TInput extends never ? never : TOutput;
+	output: TOutput;
+}
+
+/**
+ * Customizes the types associated with `TSchema`
+ * @remarks
+ * By default, the types used when constructing, reading and writing tree nodes are derived from the schema.
+ * In some cases, it may be desirable to override these types with carefully selected alternatives.
+ * This utility allows for that customization.
+ * Note that this customization is only used for typing, and does not affect the runtime behavior at all.
+ *
+ * This can be used for a wide variety of purposes, including (but not limited to):
+ *
+ * 1. Implementing better typing for a runtime extensible set of types (e.g. a polymorphic collection).
+ * This is commonly needed when implementing containers which don't directly reference their child types, and can be done using {@link Customizer.simplified}.
+ * 2. Adding type brands to specific values to increase type safety.
+ * This can be done using {@link Customizer.simplified}.
+ * 3. Adding some (compile time only) constraints to values, like enum style unions.
+ * This can be done using {@link Customizer.simplified}.
+ * 4. Making fields readonly (for the current client).
+ * This can be done using {@link Customizer.custom} with `{ readWrite: never; }`.
+ * 5. Opting into more [compleat and less sound](https://en.wikipedia.org/wiki/Soundness#Relation_to_completeness) typing.
+ * {@link Customizer.relaxed} is an example of this.
+ *
+ * For this customization to be used, the resulting schema must be used as `ImplicitAllowedTypes`.
+ * For example applying this to a single type, then using that type in an array of allowed types will have no effect:
+ * in such a case the customization must instead be applied to the array of allowed types.
+ * @privateRemarks
+ * Once this API is more stable/final, the examples in tests such as openPolymorphism.spec.ts and schemaFactory.examples.spec.ts
+ * should be copied into examples here, or somehow linked.
+ * @alpha
+ */
+export function customizeSchemaTyping<const TSchema extends ImplicitAllowedTypes>(
+	schema: TSchema,
+): Customizer<TSchema> {
+	// This function just does type branding, and duplicating the typing here to avoid any would just make it harder to maintain not easier:
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const f = (): any => schema;
+	return { strict: f, relaxed: f, simplified: f, simplifiedUnrestricted: f, custom: f };
+}
+
+/**
+ * Utility for customizing the types used for data matching a given schema.
+ * @sealed @alpha
+ */
+export interface Customizer<TSchema extends ImplicitAllowedTypes> {
+	/**
+	 * The default {@link StrictTypes}, explicitly applied.
+	 */
+	strict(): CustomizedSchemaTyping<TSchema, StrictTypes<TSchema>>;
+	/**
+	 * Relaxed policy: allows possible invalid edits (which will err at runtime) when schema is not exact.
+	 * @remarks
+	 * Handles input types covariantly so any input which might be valid with the schema is allowed
+	 * instead of the default strict policy of only inputs with all possible schema are allowed.
+	 *
+	 * This only modifies the typing shallowly: the typing of children are not effected.
+	 */
+	relaxed(): CustomizedSchemaTyping<
+		TSchema,
+		{
+			input: TreeNodeSchema extends TSchema
+				? InsertableContent
+				: // This intentionally distributes unions over the conditional to get covariant type handling.
+					TSchema extends TreeNodeSchema
+					? InsertableTypedNode<TSchema>
+					: // This intentionally distributes unions over the conditional to get covariant type handling.
+						TSchema extends AllowedTypes
+						? TSchema[number] extends LazyItem<infer TSchemaInner extends TreeNodeSchema>
+							? InsertableTypedNode<TSchemaInner, TSchemaInner>
+							: never
+						: never;
+			readWrite: TreeNodeFromImplicitAllowedTypes<TSchema>;
+			output: TreeNodeFromImplicitAllowedTypes<TSchema>;
+		}
+	>;
+	/**
+	 * Replace typing with a single substitute which allowed types must implement.
+	 * @remarks
+	 * This is generally type safe for reading the tree, but allows instances of `T` other than those listed in the schema to be assigned,
+	 * which can be out of schema and err at runtime in the same way {@link Customizer.relaxed} does.
+	 * Until with {@link Customizer.relaxed}, implicit construction is disabled, meaning all nodes must be explicitly constructed (and thus implement `T`) before being inserted.
+	 */
+	simplified<T extends TreeNodeFromImplicitAllowedTypes<TSchema>>(): CustomizedSchemaTyping<
+		TSchema,
+		{
+			input: T;
+			readWrite: T;
+			output: T;
+		}
+	>;
+
+	/**
+	 * The same as {@link Customizer} except that more T values are allowed, even ones not known to be implemented by `TSchema`.
+	 */
+	simplifiedUnrestricted<T extends TreeNode | TreeLeafValue>(): CustomizedSchemaTyping<
+		TSchema,
+		{
+			input: T;
+			readWrite: T;
+			output: T;
+		}
+	>;
+
+	/**
+	 * Fully arbitrary customization.
+	 * Provided types override existing types.
+	 */
+	custom<T extends Partial<CustomTypes>>(): CustomizedSchemaTyping<
+		TSchema,
+		{
+			// Check if property is provided. This check is needed to early out missing values so if undefined is allowed,
+			// not providing the field doesn't overwrite the corresponding type with undefined.
+			// TODO: test this case
+			[Property in keyof CustomTypes]: Property extends keyof T
+				? T[Property] extends CustomTypes[Property]
+					? T[Property]
+					: GetTypes<TSchema>[Property]
+				: GetTypes<TSchema>[Property];
+		}
+	>;
+}
+
+/**
+ * Fetch types associated with a schema, or use the default if not customized.
+ * @system @public
+ */
+export type GetTypes<TSchema extends ImplicitAllowedTypes> = [TSchema] extends [
+	CustomizedSchemaTyping<unknown, infer TCustom>,
+]
+	? TCustom
+	: StrictTypes<TSchema>;
+
 /**
  * Content which could be inserted into a tree.
  *
  * @see {@link Input}
  * @remarks
- * Extended version of {@link InsertableTreeNodeFromImplicitAllowedTypes} that also allows {@link (UnsafeUnknownSchema:type)}.
+ * Alias of {@link InsertableTreeNodeFromImplicitAllowedTypes} with a shorter name.
  * @alpha
  */
-export type Insertable<TSchema extends ImplicitAllowedTypes | UnsafeUnknownSchema> =
-	TSchema extends ImplicitAllowedTypes
-		? InsertableTreeNodeFromImplicitAllowedTypes<TSchema>
-		: InsertableContent;
+export type Insertable<TSchema extends ImplicitAllowedTypes> =
+	InsertableTreeNodeFromImplicitAllowedTypes<TSchema>;
 
 /**
  * Content which could be inserted into a field within a tree.
@@ -664,10 +937,22 @@ export type ApplyKindInput<T, Kind extends FieldKind, DefaultsAreOptional extend
 
 /**
  * Type of tree node for a field of the given schema.
+ *
+ * @typeparam TSchema - Schema to process.
+ * @remarks
+ * Defaults to {@link DefaultTreeNodeFromImplicitAllowedTypes}.
  * @public
  */
 export type TreeNodeFromImplicitAllowedTypes<
 	TSchema extends ImplicitAllowedTypes = TreeNodeSchema,
+> = GetTypes<TSchema>["output"];
+
+/**
+ * Default type of tree node for a field of the given schema.
+ * @system @public
+ */
+export type DefaultTreeNodeFromImplicitAllowedTypes<
+	TSchema extends ImplicitAllowedTypes = TreeNodeSchema,
 > = TSchema extends TreeNodeSchema
 	? NodeFromSchema<TSchema>
 	: TSchema extends AllowedTypes
@@ -727,6 +1012,17 @@ export type TreeNodeFromImplicitAllowedTypes<
  */
 export type Input<T extends never> = T;
 
+/**
+ * Type of content that can be inserted into the tree for a node of the given schema.
+ *
+ * @typeparam TSchema - Schema to process.
+ * @remarks
+ * Defaults to {@link DefaultInsertableTreeNodeFromImplicitAllowedTypes}.
+ * @public
+ */
+export type InsertableTreeNodeFromImplicitAllowedTypes<TSchema extends ImplicitAllowedTypes> =
+	GetTypes<TSchema>["input"];
+
 /**
  * Type of content that can be inserted into the tree for a node of the given schema.
  *
@@ -736,14 +1032,15 @@ export type Input<T extends never> = T;
  *
  * @privateRemarks
  * This is a bit overly conservative, since cases like `A | [A]` give never and could give `A`.
- * @public
+ * @system @public
  */
-export type InsertableTreeNodeFromImplicitAllowedTypes<TSchema extends ImplicitAllowedTypes> =
-	[TSchema] extends [TreeNodeSchema]
-		? InsertableTypedNode<TSchema>
-		: [TSchema] extends [AllowedTypes]
-			? InsertableTreeNodeFromAllowedTypes<TSchema>
-			: never;
+export type DefaultInsertableTreeNodeFromImplicitAllowedTypes<
+	TSchema extends ImplicitAllowedTypes,
+> = [TSchema] extends [TreeNodeSchema]
+	? InsertableTypedNode<TSchema>
+	: [TSchema] extends [AllowedTypes]
+		? InsertableTreeNodeFromAllowedTypes<TSchema>
+		: never;
 
 /**
  * Type of content that can be inserted into the tree for a node of the given schema.
@@ -793,6 +1090,8 @@ export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchemaC
  * One special case this makes is if the result of NodeFromSchema contains TreeNode, this must be an under constrained schema, so the result is set to never.
  * Note that applying UnionToIntersection on the result of NodeFromSchema<T> does not work since it breaks booleans.
  *
+ * Some internal code may use second parameter to opt out of contravariant behavior, but this is not a stable API.
+ *
  * @public
  */
 export type InsertableTypedNode<

package/src/simple-tree/toMapTree.ts

@@ -196,7 +196,7 @@ function nodeDataToMapTree(
 			result = objectToMapTree(data, schema);
 			break;
 		default:
-			fail("Unrecognized schema kind");
+			fail(0xae0 /* Unrecognized schema kind */);
 	}
 
 	return result;
@@ -642,7 +642,7 @@ export function addDefaultsToMapTree(
 ): void {
 	const schema =
 		find(normalizeAllowedTypes(allowedTypes), (s) => s.identifier === mapTree.type) ??
-		fail("MapTree is incompatible with schema");
+		fail(0xae1 /* MapTree is incompatible with schema */);
 
 	if (isObjectNodeSchema(schema)) {
 		for (const [_key, fieldInfo] of schema.flexKeyMap) {
@@ -660,7 +660,7 @@ export function addDefaultsToMapTree(
 						setFieldValue(mapTree.fields, data, fieldInfo.schema, fieldInfo.storedKey);
 						// call addDefaultsToMapTree on newly inserted default values
 						for (const child of mapTree.fields.get(fieldInfo.storedKey) ??
-							fail("Expected field to be populated")) {
+							fail(0xae2 /* Expected field to be populated */)) {
 							addDefaultsToMapTree(child, fieldInfo.schema.allowedTypes, 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>();
 
@@ -71,7 +71,8 @@ export function convertField(schema: ImplicitFieldSchema): TreeFieldStoredSchema
 	let kind: FieldKindIdentifier;
 	let allowedTypes: ImplicitAllowedTypes;
 	if (schema instanceof FieldSchema) {
-		kind = convertFieldKind.get(schema.kind)?.identifier ?? fail("Invalid field kind");
+		kind =
+			convertFieldKind.get(schema.kind)?.identifier ?? fail(0xae3 /* Invalid field kind */);
 		allowedTypes = schema.allowedTypes;
 	} else {
 		kind = FieldKinds.required.identifier;
@@ -91,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)));
 }
 
 /**

package/src/simple-tree/treeNodeValid.ts

@@ -58,15 +58,17 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		instance: TreeNodeValid<T>,
 		input: T,
 	): UnhydratedFlexTreeNode {
-		return fail("Schema must override buildRawNode");
+		return fail(0xae4 /* Schema must override buildRawNode */);
 	}
 
 	/**
 	 * Schema classes can override to provide a callback that is called once when the first node is constructed.
 	 * This is a good place to perform extra validation and cache schema derived data needed for the implementation of the node.
+	 * @remarks
+	 * It is valid to dereference LazyItem schema references in this function (or anything that runs after it).
 	 */
 	protected static oneTimeSetup<T>(this: typeof TreeNodeValid<T>): Context {
-		fail("Missing oneTimeSetup");
+		fail(0xae5 /* Missing oneTimeSetup */);
 	}
 
 	/**
@@ -119,6 +121,9 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 			return this.constructorCached;
 		}
 
+		// If users trying to diagnose the cause of this error becomes a common issue, more information could be captured.
+		// The call stack to when a schema is first marked most derived could be captured in debug builds and stored in the `MostDerivedData` object:
+		// This could then be included in the error to aid in debugging this error.
 		throw new UsageError(
 			`Two schema classes were used (${this.name} and ${
 				this.constructorCached.constructor.name
@@ -143,7 +148,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 	}
 
 	/**
-	 * @see {@link TreeNodeSchemaCore.createFromInsertable}.
+	 * See {@link TreeNodeSchemaCore.createFromInsertable}.
 	 */
 	public static createFromInsertable<TInput, TOut, TThis extends new (args: TInput) => TOut>(
 		this: TThis,
@@ -152,13 +157,22 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		return new this(input);
 	}
 
+	/**
+	 * Idempotent initialization function that pre-caches data and can dereference lazy schema references.
+	 */
+	public static oneTimeInitialize(
+		this: typeof TreeNodeValid & TreeNodeSchema,
+	): Required<MostDerivedData> {
+		const cache = this.markMostDerived();
+		cache.oneTimeInitialized ??= this.oneTimeSetup();
+		// Typescript fails to narrow the type of `oneTimeInitialized` to `Context` here, so use a cast:
+		return cache as MostDerivedData & { oneTimeInitialized: Context };
+	}
+
 	public constructor(input: TInput | InternalTreeNode) {
 		super(privateToken);
 		const schema = this.constructor as typeof TreeNodeValid & TreeNodeSchema;
-		const cache = schema.markMostDerived();
-		if (cache.oneTimeInitialized === undefined) {
-			cache.oneTimeInitialized = schema.oneTimeSetup();
-		}
+		const cache = schema.oneTimeInitialize();
 
 		if (isTreeNode(input)) {
 			// TODO: update this once we have better support for deep-copying and move operations.