@fluidframework/tree 2.23.0 → 2.31.0

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,13 @@ 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";
+import type { SimpleFieldSchema, SimpleObjectFieldSchema } from "./simpleSchema.js";
 
 /**
  * Returns true if the given schema is a {@link TreeNodeSchemaClass}, or otherwise false if it is a {@link TreeNodeSchemaNonClass}.
@@ -69,6 +74,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 +209,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
@@ -274,14 +281,14 @@ export let createFieldSchema: <
 	kind: Kind,
 	allowedTypes: Types,
 	props?: FieldProps<TCustomMetadata>,
-) => FieldSchema<Kind, Types, TCustomMetadata>;
+) => FieldSchemaAlpha<Kind, Types, TCustomMetadata>;
 
 /**
  * All policy for a specific field,
  * including functionality that does not have to be kept consistent across versions or deterministic.
  *
  * This can include policy for how to use this schema for "view" purposes, and well as how to expose editing APIs.
- * Use {@link SchemaFactory} to create the FieldSchema instances, for example {@link schemaStatics.optional}.
+ * Use {@link SchemaFactory} to create the FieldSchema instances, for example {@link SchemaStatics.optional}.
  * @privateRemarks
  * Public access to the constructor is removed to prevent creating expressible but unsupported (or not stable) configurations.
  * {@link createFieldSchema} can be used internally to create instances.
@@ -289,6 +296,9 @@ export let createFieldSchema: <
  * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
  * See {@link FieldSchemaMetadata.custom}.
  *
+ * @remarks
+ * All implementations of this are actually {@link FieldSchemaAlpha} which exposes some additional alpha APIs.
+ *
  * @sealed @public
  */
 export class FieldSchema<
@@ -296,17 +306,6 @@ export class FieldSchema<
 	out Types extends ImplicitAllowedTypes = ImplicitAllowedTypes,
 	out TCustomMetadata = unknown,
 > {
-	static {
-		createFieldSchema = <
-			Kind2 extends FieldKind = FieldKind,
-			Types2 extends ImplicitAllowedTypes = ImplicitAllowedTypes,
-			TCustomMetadata2 = unknown,
-		>(
-			kind: Kind2,
-			allowedTypes: Types2,
-			props?: FieldProps<TCustomMetadata2>,
-		) => new FieldSchema(kind, allowedTypes, props);
-	}
 	/**
 	 * This class is used with instanceof, and therefore should have nominal typing.
 	 * This field enforces that.
@@ -331,11 +330,15 @@ export class FieldSchema<
 	/**
 	 * {@inheritDoc FieldProps.metadata}
 	 */
-	public get metadata(): FieldSchemaMetadata<TCustomMetadata> | undefined {
-		return this.props?.metadata;
+	public get metadata(): FieldSchemaMetadata<TCustomMetadata> {
+		return this.props?.metadata ?? {};
 	}
 
-	private constructor(
+	/**
+	 * This class is `@sealed`: protected members like this constructor are for internal use only.
+	 * Use {@link SchemaFactory} to create the FieldSchema instances.
+	 */
+	protected constructor(
 		/**
 		 * The {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind } of this field.
 		 * Determines the multiplicity, viewing and editing APIs as well as the merge resolution policy.
@@ -350,6 +353,10 @@ export class FieldSchema<
 		 */
 		public readonly props?: FieldProps<TCustomMetadata>,
 	) {
+		if (!(this instanceof FieldSchemaAlpha)) {
+			throw new UsageError("FieldSchema is @sealed: sub-classing is not allowed.");
+		}
+
 		this.lazyTypes = new Lazy(() => normalizeAllowedTypes(this.allowedTypes));
 		// TODO: optional fields should (by default) get a default provider that returns undefined, removing the need to special case them here:
 		this.requiresValue =
@@ -357,12 +364,75 @@ export class FieldSchema<
 	}
 }
 
+/**
+ * {@link FieldSchema} including alpha APIs (currently {@link SimpleFieldSchema}).
+ * @remarks
+ * This class will go away once the alpha APIs are stable and implemented by {@link FieldSchema}.
+ * @sealed @alpha
+ */
+export class FieldSchemaAlpha<
+		Kind extends FieldKind = FieldKind,
+		Types extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+		TCustomMetadata = unknown,
+	>
+	extends FieldSchema<Kind, Types, TCustomMetadata>
+	implements SimpleFieldSchema
+{
+	private readonly lazyIdentifiers: Lazy<ReadonlySet<string>>;
+
+	static {
+		createFieldSchema = <
+			Kind2 extends FieldKind = FieldKind,
+			Types2 extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+			TCustomMetadata2 = unknown,
+		>(
+			kind: Kind2,
+			allowedTypes: Types2,
+			props?: FieldProps<TCustomMetadata2>,
+		) => new FieldSchemaAlpha(kind, allowedTypes, props);
+	}
+
+	protected constructor(kind: Kind, allowedTypes: Types, props?: FieldProps<TCustomMetadata>) {
+		super(kind, allowedTypes, props);
+		this.lazyIdentifiers = new Lazy(
+			() => new Set([...this.allowedTypeSet].map((t) => t.identifier)),
+		);
+	}
+
+	public get allowedTypesIdentifiers(): ReadonlySet<string> {
+		return this.lazyIdentifiers.value;
+	}
+}
+
+/**
+ * {@link FieldSchemaAlpha} including {@link SimpleObjectFieldSchema}.
+ */
+export class ObjectFieldSchema<
+		Kind extends FieldKind = FieldKind,
+		Types extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+		TCustomMetadata = unknown,
+	>
+	extends FieldSchemaAlpha<Kind, Types, TCustomMetadata>
+	implements SimpleObjectFieldSchema
+{
+	public readonly storedKey: string;
+
+	public constructor(
+		kind: Kind,
+		allowedTypes: Types,
+		props: FieldProps<TCustomMetadata> & { readonly key: string },
+	) {
+		super(kind, allowedTypes, props);
+		this.storedKey = props.key;
+	}
+}
+
 /**
  * Normalizes a {@link ImplicitFieldSchema} to a {@link FieldSchema}.
  */
-export function normalizeFieldSchema(schema: ImplicitFieldSchema): FieldSchema {
+export function normalizeFieldSchema(schema: ImplicitFieldSchema): FieldSchemaAlpha {
 	return schema instanceof FieldSchema
-		? schema
+		? (schema as FieldSchemaAlpha)
 		: createFieldSchema(FieldKind.Required, schema);
 }
 /**
@@ -379,6 +449,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 +541,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 +636,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;
@@ -822,7 +952,7 @@ export type NodeBuilderData<T extends TreeNodeSchemaCore<string, NodeKind, boole
 /**
  * Value that may be stored as a leaf node.
  * @remarks
- * Some limitations apply, see the documentation for {@link schemaStatics.number} and {@link schemaStatics.string} for those restrictions.
+ * Some limitations apply, see the documentation for {@link SchemaStatics.number} and {@link SchemaStatics.string} for those restrictions.
  * @public
  */
 // eslint-disable-next-line @rushstack/no-new-null

package/src/simple-tree/{api/simpleSchema.ts → simpleSchema.ts}

@@ -3,81 +3,115 @@
  * Licensed under the MIT License.
  */
 
-import type { ValueSchema } from "../../core/index.js";
-import type { NodeKind } from "../core/index.js";
-import type { FieldKind, FieldSchemaMetadata, NodeSchemaMetadata } from "../schemaTypes.js";
+import type { ValueSchema } from "../core/index.js";
+import type { NodeKind } from "./core/index.js";
+import type { FieldKind, FieldSchemaMetadata, NodeSchemaMetadata } from "./schemaTypes.js";
+
+/*
+ * TODO:
+ * - Customize their JSON serialization to use these formats or provide some other serialization scheme.
+ */
 
 /**
- * Base interface for all {@link SimpleNodeSchema} implementations.
- *
- * @internal
+ * Base interface for {@link TreeNodeSchema} and {@link SimpleNodeSchema} types.
+ * Once simple schema is stable this doesn't have a reason to be kept `@system`, but it could be.
+ * @system
+ * @public
  * @sealed
  */
-export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
+export interface SimpleNodeSchemaBase<
+	out TNodeKind extends NodeKind,
+	out TCustomMetadata = unknown,
+> {
 	/**
-	 * The kind of {@link SimpleNodeSchema}.
+	 * The {@link NodeKind}.
 	 *
 	 * @remarks can be used to type-switch between implementations.
 	 */
 	readonly kind: TNodeKind;
 
 	/**
-	 * {@inheritDoc NodeSchemaMetadata}
+	 * User-provided {@link NodeSchemaMetadata} for this schema.
 	 */
-	readonly metadata?: NodeSchemaMetadata | undefined;
+	readonly metadata: NodeSchemaMetadata<TCustomMetadata>;
 }
 
 /**
  * A {@link SimpleNodeSchema} for an object node.
  *
- * @internal
+ * @alpha
  * @sealed
  */
-export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Object> {
+export interface SimpleObjectNodeSchema<out TCustomMetadata = unknown>
+	extends SimpleNodeSchemaBase<NodeKind.Object, TCustomMetadata> {
 	/**
 	 * Schemas for each of the object's fields, keyed off of schema's keys.
 	 * @remarks
-	 * Depending on how this schema was exported, the string keys may be either the property keys or the stored keys.
+	 * The keys are the property keys if known, otherwise they are the stored keys.
+	 * Use {@link SimpleObjectFieldSchema.storedKey} to get the stored key.
+	 * @privateRemarks
+	 * TODO: Provide and link a way to translate from stored keys to the property keys.
+	 * TODO: Consider adding `storedKeysToFields` or something similar to reduce confusion,
+	 * especially if/when TreeNodeSchema for objects provide more maps.
 	 */
-	readonly fields: Record<string, SimpleFieldSchema>;
+	readonly fields: ReadonlyMap<string, SimpleObjectFieldSchema>;
+}
+
+/**
+ * A {@link SimpleFieldSchema} for an {@link SimpleObjectNodeSchema} field.
+ * @remarks
+ * The only other case fields are uses in the root schema.
+ *
+ * @alpha
+ * @sealed
+ */
+export interface SimpleObjectFieldSchema extends SimpleFieldSchema {
+	/**
+	 * The stored key of the field.
+	 * @remarks
+	 * See {@link FieldProps.key} for more information.
+	 */
+	readonly storedKey: string;
 }
 
 /**
  * A {@link SimpleNodeSchema} for an array node.
  *
- * @internal
+ * @alpha
  * @sealed
  */
-export interface SimpleArrayNodeSchema extends SimpleNodeSchemaBase<NodeKind.Array> {
+export interface SimpleArrayNodeSchema<out TCustomMetadata = unknown>
+	extends SimpleNodeSchemaBase<NodeKind.Array, TCustomMetadata> {
 	/**
 	 * The types allowed in the array.
 	 *
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypes: ReadonlySet<string>;
+	readonly allowedTypesIdentifiers: ReadonlySet<string>;
 }
 
 /**
  * A {@link SimpleNodeSchema} for a map node.
  *
- * @internal
+ * @alpha
  * @sealed
  */
-export interface SimpleMapNodeSchema extends SimpleNodeSchemaBase<NodeKind.Map> {
+export interface SimpleMapNodeSchema<out TCustomMetadata = unknown>
+	extends SimpleNodeSchemaBase<NodeKind.Map, TCustomMetadata> {
 	/**
 	 * The types allowed as values in the map.
 	 *
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypes: ReadonlySet<string>;
+	readonly allowedTypesIdentifiers: ReadonlySet<string>;
 }
 
 /**
  * A {@link SimpleNodeSchema} for a leaf node.
  *
- * @internal
+ * @alpha
  * @sealed
  */
 export interface SimpleLeafNodeSchema extends SimpleNodeSchemaBase<NodeKind.Leaf> {
@@ -94,7 +128,12 @@ export interface SimpleLeafNodeSchema extends SimpleNodeSchemaBase<NodeKind.Leaf
  * To be useful, this generally needs to be used as a part of a complete {@link SimpleTreeSchema}, which
  * contains backing {@link SimpleTreeSchema.definitions} for each referenced identifier.
  *
- * @internal
+ * Note that, as documented on {@link NodeKind}, more kinds of nodes may be added,
+ * and therefore code should not assume that switching over all these cases can be done exhaustively.
+ * @privateRemarks
+ * Because of the above mentioned extensibility of node kinds, does it make sense to stabilize this?
+ *
+ * @alpha
  */
 export type SimpleNodeSchema =
 	| SimpleLeafNodeSchema
@@ -109,7 +148,7 @@ export type SimpleNodeSchema =
  * To be useful, this generally needs to be used as a part of a complete {@link SimpleTreeSchema}, which
  * contains backing {@link SimpleTreeSchema.definitions} for each referenced identifier.
  *
- * @internal
+ * @alpha
  * @sealed
  */
 export interface SimpleFieldSchema {
@@ -124,12 +163,12 @@ export interface SimpleFieldSchema {
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypes: ReadonlySet<string>;
+	readonly allowedTypesIdentifiers: ReadonlySet<string>;
 
 	/**
 	 * {@inheritDoc FieldSchemaMetadata}
 	 */
-	readonly metadata?: FieldSchemaMetadata | undefined;
+	readonly metadata: FieldSchemaMetadata;
 }
 
 /**
@@ -138,7 +177,7 @@ export interface SimpleFieldSchema {
  * @remarks Contains the complete set of schema {@link SimpleTreeSchema.definitions} required to resolve references,
  * which are represented inline with identifiers.
  *
- * @internal
+ * @alpha
  * @sealed
  */
 export interface SimpleTreeSchema extends SimpleFieldSchema {
@@ -153,10 +192,10 @@ export interface SimpleTreeSchema extends SimpleFieldSchema {
 	 * @remarks Refers to the types by identifier.
 	 * Can be resolved via {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypes: ReadonlySet<string>;
+	readonly allowedTypesIdentifiers: ReadonlySet<string>;
 
 	/**
-	 * The complete set of node schema definitions recursively referenced by the tree's {@link SimpleTreeSchema.allowedTypes}.
+	 * The complete set of node schema definitions recursively referenced by the tree's {@link SimpleTreeSchema.allowedTypesIdentifiers}.
 	 *
 	 * @remarks the keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
 	 */

package/src/simple-tree/toMapTree.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
@@ -19,9 +19,9 @@ import {
 import {
 	isTreeValue,
 	valueSchemaAllows,
-	type NodeKeyManager,
+	type NodeIdentifierManager,
 } from "../feature-libraries/index.js";
-import { brand, fail, isReadonlyArray, find, hasSome, hasSingle } from "../util/index.js";
+import { brand, isReadonlyArray, find, hasSome, hasSingle } from "../util/index.js";
 
 import { nullSchema } from "./leafNodeSchema.js";
 import {
@@ -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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -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, 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)));
 }
 
 /**

package/src/simple-tree/treeNodeValid.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 
 import {
 	type TreeNodeSchema,
@@ -20,7 +20,6 @@ import {
 } from "./core/index.js";
 import { type FlexTreeNode, isFlexTreeNode } from "../feature-libraries/index.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { fail } from "../util/index.js";
 
 import { getSimpleNodeSchemaFromInnerNode } from "./core/index.js";
 import { markEager } from "./flexList.js";
@@ -64,6 +63,8 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 	/**
 	 * 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(0xae5 /* Missing oneTimeSetup */);
@@ -146,7 +147,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,
@@ -155,13 +156,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.

package/src/treeFactory.ts

@@ -22,25 +22,7 @@ import {
 } from "./shared-tree/index.js";
 import type { ITree } from "./simple-tree/index.js";
 
-import { pkgVersion } from "./packageVersion.js";
-
-/**
- * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
- * @alpha
- * @legacy
- */
-export const SharedTreeFactoryType = "https://graph.microsoft.com/types/tree";
-
-/**
- * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.attributes}
- * @alpha
- * @legacy
- */
-export const SharedTreeAttributes: IChannelAttributes = {
-	type: SharedTreeFactoryType,
-	snapshotFormatVersion: "0.0.0",
-	packageVersion: pkgVersion,
-};
+import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
 
 /**
  * A channel factory that creates an {@link ITree}.