@fluidframework/tree 2.23.0 → 2.31.0

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

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import type { NodeSchemaMetadata, TreeLeafValue } from "../schemaTypes.js";
+import type { TreeLeafValue } from "../schemaTypes.js";
+import type { SimpleNodeSchemaBase } from "../simpleSchema.js";
 import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
 
 /**
@@ -18,6 +19,13 @@ import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
  * Captures the schema both as runtime data and compile time type information.
  * Use {@link SchemaFactory} to define schema.
  * Use `Tree.schema(value)` to lookup the schema for a {@link TreeNode} or {@link TreeLeafValue}.
+ * @privateRemarks
+ * TODO:
+ * The long lists of type parameters here are awkward to deal with.
+ * Switching to (or adding an option to use)
+ * an interface based pattern with unordered named parameters for types like this would be a good idea.
+ * The related `@system` types should be simple to port to the new pattern, but stable public one like this will need to support both:
+ * the new one could either be added as a system type, or be recommended to replace this one (deprecating it).
  * @sealed @public
  */
 export type TreeNodeSchema<
@@ -81,6 +89,8 @@ export type TreeNodeSchemaNonClass<
 		? {
 				/**
 				 * Constructs an {@link Unhydrated} node with this schema.
+				 * @privateRemarks
+				 * Also allows InternalTreeNode.
 				 * @sealed
 				 */
 				create(data?: TInsertable | TConstructorExtra): TNode;
@@ -88,6 +98,8 @@ export type TreeNodeSchemaNonClass<
 		: {
 				/**
 				 * Constructs an {@link Unhydrated} node with this schema.
+				 * @privateRemarks
+				 * Also allows InternalTreeNode.
 				 * @sealed
 				 */
 				create(data: TInsertable | TConstructorExtra): TNode;
@@ -227,7 +239,7 @@ export interface TreeNodeSchemaCore<
 	out Info = unknown,
 	out TInsertable = never,
 	out TCustomMetadata = unknown,
-> {
+> extends SimpleNodeSchemaBase<Kind, TCustomMetadata> {
 	/**
 	 * Unique (within a document's schema) identifier used to associate nodes with their schema.
 	 * @remarks
@@ -239,7 +251,6 @@ export interface TreeNodeSchemaCore<
 	 * it is best practice to pick a new identifier.
 	 */
 	readonly identifier: Name;
-	readonly kind: Kind;
 
 	/**
 	 * Data used to define this schema.
@@ -283,11 +294,6 @@ export interface TreeNodeSchemaCore<
 	 */
 	readonly childTypes: ReadonlySet<TreeNodeSchema>;
 
-	/**
-	 * User-provided {@link NodeSchemaMetadata} for this schema.
-	 */
-	readonly metadata?: NodeSchemaMetadata<TCustomMetadata> | undefined;
-
 	/**
 	 * Constructs an instance of this node type.
 	 * @remarks

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail } from "@fluidframework/core-utils/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { Listenable } from "@fluidframework/core-interfaces";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
@@ -15,17 +15,17 @@ import {
 	type ExclusiveMapTree,
 	type FieldKey,
 	type FieldKindIdentifier,
-	type FieldUpPath,
 	forbiddenFieldKindIdentifier,
 	type ITreeCursorSynchronous,
 	type MapTree,
+	type NormalizedFieldUpPath,
 	type SchemaPolicy,
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
 	type TreeStoredSchema,
 	type Value,
 } from "../../core/index.js";
-import { brand, fail, getOrCreate, mapIterable } from "../../util/index.js";
+import { brand, getOrCreate, mapIterable } from "../../util/index.js";
 import {
 	type FlexTreeContext,
 	FlexTreeEntityKind,
@@ -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

@@ -57,14 +57,6 @@ export {
 	type IdentifierIndex,
 	createSimpleTreeIndex,
 	createIdentifierIndex,
-	type SimpleNodeSchemaBase,
-	type SimpleTreeSchema,
-	type SimpleNodeSchema,
-	type SimpleFieldSchema,
-	type SimpleLeafNodeSchema,
-	type SimpleMapNodeSchema,
-	type SimpleArrayNodeSchema,
-	type SimpleObjectNodeSchema,
 	type JsonSchemaId,
 	type JsonSchemaType,
 	type JsonObjectNodeSchema,
@@ -108,8 +100,12 @@ export {
 	type TreeNodeSchemaClassUnsafe,
 	type TreeNodeSchemaUnsafe,
 	type AllowedTypesUnsafe,
+	type ImplicitAllowedTypesUnsafe,
+	type ImplicitFieldSchemaUnsafe,
 	type TreeNodeSchemaNonClassUnsafe,
 	type InsertableTreeNodeFromAllowedTypesUnsafe,
+	type ArrayNodeCustomizableSchemaUnsafe,
+	type MapNodeCustomizableSchemaUnsafe,
 	type TreeViewAlpha,
 	type TreeBranch,
 	type TreeBranchEvents,
@@ -124,7 +120,7 @@ export {
 	type CustomTreeNode,
 	type CustomTreeValue,
 	tryStoredSchemaAsArray,
-	type schemaStatics,
+	type SchemaStatics,
 	type ITreeAlpha,
 	type TransactionConstraint,
 	type NodeInDocumentConstraint,
@@ -136,7 +132,24 @@ export {
 	type TransactionResultSuccess,
 	type TransactionResultFailed,
 	rollback,
+	generateSchemaFromSimpleSchema,
+	replaceConciseTreeHandles,
+	replaceHandles,
+	replaceVerboseTreeHandles,
+	type HandleConverter,
+	type FieldSchemaAlphaUnsafe,
 } from "./api/index.js";
+export type {
+	SimpleTreeSchema,
+	SimpleNodeSchema,
+	SimpleFieldSchema,
+	SimpleLeafNodeSchema,
+	SimpleMapNodeSchema,
+	SimpleArrayNodeSchema,
+	SimpleObjectNodeSchema,
+	SimpleNodeSchemaBase,
+	SimpleObjectFieldSchema,
+} from "./simpleSchema.js";
 export {
 	type NodeFromSchema,
 	isTreeNodeSchemaClass,
@@ -149,6 +162,7 @@ export {
 	type AllowedTypes,
 	FieldKind,
 	FieldSchema,
+	type FieldSchemaAlpha,
 	type InsertableTreeFieldFromImplicitField,
 	type InsertableTypedNode,
 	type NodeBuilderData,
@@ -170,6 +184,7 @@ export {
 	type ReadSchema,
 	type NodeSchemaOptions,
 	type NodeSchemaMetadata,
+	evaluateLazySchema,
 } from "./schemaTypes.js";
 export {
 	getTreeNodeForField,
@@ -180,6 +195,16 @@ export {
 	IterableTreeArrayContent,
 	type ReadonlyArrayNode,
 } from "./arrayNode.js";
+export type {
+	ArrayNodeCustomizableSchema,
+	ArrayNodePojoEmulationSchema,
+} from "./arrayNodeTypes.js";
+export { ArrayNodeSchema, isArrayNodeSchema } from "./arrayNodeTypes.js";
+export type {
+	MapNodeCustomizableSchema,
+	MapNodePojoEmulationSchema,
+} from "./mapNodeTypes.js";
+export { MapNodeSchema, isMapNodeSchema } from "./mapNodeTypes.js";
 export {
 	type FieldHasDefault,
 	type InsertableObjectFromSchemaRecord,
@@ -188,6 +213,7 @@ export {
 	setField,
 	createUnknownOptionalFieldPolicy,
 } from "./objectNode.js";
+export { ObjectNodeSchema } from "./objectNodeTypes.js";
 export type { TreeMapNode, MapNodeInsertableData } from "./mapNode.js";
 export {
 	mapTreeFromNodeData,
@@ -203,4 +229,5 @@ export {
 	handleSchema,
 	nullSchema,
 } from "./leafNodeSchema.js";
+export type { LeafSchema } from "./leafNodeSchema.js";
 export type { LazyItem, FlexList, FlexListToUnion, ExtractItemType } from "./flexList.js";

package/src/simple-tree/leafNodeSchema.ts

@@ -12,6 +12,8 @@ import {
 	valueSchemaAllows,
 } from "../feature-libraries/index.js";
 import { NodeKind, type TreeNodeSchema, type TreeNodeSchemaNonClass } from "./core/index.js";
+import type { NodeSchemaMetadata, TreeLeafValue } from "./schemaTypes.js";
+import type { SimpleLeafNodeSchema } from "./simpleSchema.js";
 
 /**
  * Instances of this class are schema for leaf nodes.
@@ -44,9 +46,14 @@ export class LeafNodeSchema<Name extends string, const T extends ValueSchema>
 		return data;
 	}
 
+	public readonly leafKind: ValueSchema;
+
+	public readonly metadata: NodeSchemaMetadata = {};
+
 	public constructor(name: Name, t: T) {
 		this.identifier = name;
 		this.info = t;
+		this.leafKind = t;
 	}
 }
 
@@ -56,17 +63,31 @@ export class LeafNodeSchema<Name extends string, const T extends ValueSchema>
 function makeLeaf<Name extends string, const T extends ValueSchema>(
 	name: Name,
 	t: T,
-): TreeNodeSchema<
-	`com.fluidframework.leaf.${Name}`,
-	NodeKind.Leaf,
-	TreeValue<T>,
-	TreeValue<T>,
-	true
-> {
+): LeafSchema<Name, TreeValue<T>> & SimpleLeafNodeSchema {
 	// Names in this domain follow https://en.wikipedia.org/wiki/Reverse_domain_name_notation
 	return new LeafNodeSchema(`com.fluidframework.leaf.${name}`, t);
 }
 
+/**
+ * A {@link TreeNodeSchema} for a {@link TreeLeafValue}.
+ * @remarks
+ * This is just a more specific alias for a particular {@link TreeNodeSchemaNonClass}.
+ * It only exists to make the API (particularly errors, IntelliSense, and generated .d.ts files) more readable.
+ *
+ * See {@link SchemaFactory} and its various properties for actual leaf schema objects.
+ * @privateRemarks
+ * This is an interface so its name will show up in things like type errors instead of the fully expanded TreeNodeSchemaNonClass.
+ * @system @sealed @public
+ */
+export interface LeafSchema<Name extends string, T extends TreeLeafValue>
+	extends TreeNodeSchemaNonClass<
+		`com.fluidframework.leaf.${Name}`,
+		NodeKind.Leaf,
+		/* TNode */ T,
+		/* TInsertable */ T,
+		/* ImplicitlyConstructable */ true
+	> {}
+
 // Leaf schema shared between all SchemaFactory instances.
 export const stringSchema = makeLeaf("string", ValueSchema.String);
 export const numberSchema = makeLeaf("number", ValueSchema.Number);

package/src/simple-tree/mapNode.ts

@@ -24,9 +24,7 @@ import {
 	getKernel,
 	type InnerNode,
 	NodeKind,
-	type TreeNodeSchemaBoth,
 	type TreeNodeSchema,
-	type WithType,
 	// eslint-disable-next-line import/no-deprecated
 	typeNameSymbol,
 	type TreeNode,
@@ -45,6 +43,7 @@ import { brand, count, type RestrictiveStringRecord } from "../util/index.js";
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import type { ExclusiveMapTree } from "../core/index.js";
 import { getUnhydratedContext } from "./createContext.js";
+import type { MapNodeCustomizableSchema, MapNodePojoEmulationSchema } from "./mapNodeTypes.js";
 
 /**
  * A map of string keys to tree objects.
@@ -245,6 +244,9 @@ export function mapSchema<
 	metadata?: NodeSchemaMetadata<TCustomMetadata>,
 ) {
 	const lazyChildTypes = new Lazy(() => normalizeAllowedTypes(info));
+	const lazyAllowedTypesIdentifiers = new Lazy(
+		() => new Set([...lazyChildTypes.value].map((type) => type.identifier)),
+	);
 
 	let unhydratedContext: Context;
 
@@ -271,6 +273,10 @@ export function mapSchema<
 			);
 		}
 
+		public static get allowedTypesIdentifiers(): ReadonlySet<string> {
+			return lazyAllowedTypesIdentifiers.value;
+		}
+
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup<T2>(this: typeof TreeNodeValid<T2>): Context {
@@ -286,8 +292,7 @@ export function mapSchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;
 		}
-		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> | undefined =
-			metadata;
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> = metadata ?? {};
 
 		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {
@@ -297,16 +302,13 @@ export function mapSchema<
 			return Schema.constructorCached?.constructor as unknown as typeof schemaErased;
 		}
 	}
-	const schemaErased: TreeNodeSchemaBoth<
+	const schemaErased: MapNodeCustomizableSchema<
 		TName,
-		NodeKind.Map,
-		TreeMapNode<T> & WithType<TName, NodeKind.Map>,
-		MapNodeInsertableData<T>,
-		ImplicitlyConstructable,
 		T,
-		undefined,
+		ImplicitlyConstructable,
 		TCustomMetadata
-	> = Schema;
+	> &
+		MapNodePojoEmulationSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> = Schema;
 	return schemaErased;
 }
 

package/src/simple-tree/mapNodeTypes.ts

@@ -0,0 +1,90 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { MapNodeInsertableData, TreeMapNode } from "./mapNode.js";
+import type { ImplicitAllowedTypes } from "./schemaTypes.js";
+import {
+	NodeKind,
+	type TreeNodeSchemaClass,
+	type TreeNodeSchema,
+	type TreeNodeSchemaNonClass,
+	type WithType,
+} from "./core/index.js";
+
+import type { SimpleMapNodeSchema } from "./simpleSchema.js";
+
+/**
+ * A schema for customizable {@link (TreeMapNode:interface)}s.
+ * @system @sealed @alpha
+ */
+export interface MapNodeCustomizableSchema<
+	out TName extends string = string,
+	in out T extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	out ImplicitlyConstructable extends boolean = true,
+	out TCustomMetadata = unknown,
+> extends TreeNodeSchemaClass<
+			TName,
+			NodeKind.Map,
+			TreeMapNode<T> & WithType<TName, NodeKind.Map, T>,
+			MapNodeInsertableData<T>,
+			ImplicitlyConstructable,
+			T,
+			undefined,
+			TCustomMetadata
+		>,
+		SimpleMapNodeSchema<TCustomMetadata> {}
+
+/**
+ * A schema for POJO emulation mode {@link (TreeMapNode:interface)}s.
+ * @system @sealed @alpha
+ */
+export interface MapNodePojoEmulationSchema<
+	out TName extends string = string,
+	in out T extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	out ImplicitlyConstructable extends boolean = true,
+	out TCustomMetadata = unknown,
+> extends TreeNodeSchemaNonClass<
+			TName,
+			NodeKind.Map,
+			TreeMapNode<T> & WithType<TName, NodeKind.Map, T>,
+			MapNodeInsertableData<T>,
+			ImplicitlyConstructable,
+			T,
+			undefined,
+			TCustomMetadata
+		>,
+		SimpleMapNodeSchema<TCustomMetadata> {}
+
+/**
+ * A schema for {@link (TreeMapNode:interface)}s.
+ * @privateRemarks
+ * This could have generic arguments added and forwarded.
+ * The expected use-cases for this don't need them however, and if they did want an argument it would probably be the allowed types;
+ * perhaps if moving to an order independent way to pass generic arguments, adding support for them here would make sense.
+ * @alpha
+ */
+export type MapNodeSchema = MapNodeCustomizableSchema | MapNodePojoEmulationSchema;
+
+/**
+ * @alpha
+ */
+export const MapNodeSchema = {
+	/**
+	 * instanceof-based narrowing support for MapNodeSchema in Javascript and TypeScript 5.3 or newer.
+	 */
+	[Symbol.hasInstance](value: TreeNodeSchema): value is MapNodeSchema {
+		return isMapNodeSchema(value);
+	},
+} as const;
+
+/**
+ * Narrows a {@link (TreeNodeSchema:interface)} to an {@link (MapNodeSchema:interface)}.
+ * @privateRemarks
+ * If at some point we want to have internal only APIs for MapNodeSchema (like done for objects),
+ * this can include those since its not the public facing API.
+ */
+export function isMapNodeSchema(schema: TreeNodeSchema): schema is MapNodeSchema {
+	return schema.kind === NodeKind.Map;
+}

package/src/simple-tree/objectNode.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, Lazy } from "@fluidframework/core-utils/internal";
+import { assert, Lazy, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { FieldKey, SchemaPolicy } from "../core/index.js";
@@ -27,6 +27,8 @@ import {
 	type ImplicitAllowedTypes,
 	FieldKind,
 	type NodeSchemaMetadata,
+	type FieldSchemaAlpha,
+	ObjectFieldSchema,
 } from "./schemaTypes.js";
 import {
 	type TreeNodeSchema,
@@ -42,7 +44,7 @@ import {
 	getOrCreateInnerNode,
 } from "./core/index.js";
 import { mapTreeFromNodeData, type InsertableContent } from "./toMapTree.js";
-import { type RestrictiveStringRecord, fail, type FlattenKeys } from "../util/index.js";
+import type { RestrictiveStringRecord, FlattenKeys } from "../util/index.js";
 import {
 	isObjectNodeSchema,
 	type ObjectNodeSchema,
@@ -50,16 +52,21 @@ import {
 } from "./objectNodeTypes.js";
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import { getUnhydratedContext } from "./createContext.js";
+import type { SimpleObjectFieldSchema } from "./simpleSchema.js";
 
 /**
  * Generates the properties for an ObjectNode from its field schema object.
  * @system @public
  */
-export type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFieldSchema>> = {
-	-readonly [Property in keyof T]: Property extends string
-		? TreeFieldFromImplicitField<T[Property]>
-		: unknown;
-};
+export type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFieldSchema>> =
+	RestrictiveStringRecord<ImplicitFieldSchema> extends T
+		? // eslint-disable-next-line @typescript-eslint/ban-types
+			{}
+		: {
+				-readonly [Property in keyof T]: Property extends string
+					? TreeFieldFromImplicitField<T[Property]>
+					: unknown;
+			};
 
 /**
  * A {@link TreeNode} which modules a JavaScript object.
@@ -112,12 +119,21 @@ export type FieldHasDefault<T extends ImplicitFieldSchema> = T extends FieldSche
  * To prevent extraneous properties in literals for the fields of an empty object from compiling, the empty case is special cased to produce `Record<string, never>`.
  * More details at {@link https://mercury.com/blog/creating-an-emptyobject-type-in-typescript}.
  *
+ * Additionally when T is exactly `RestrictiveStringRecord<ImplicitFieldSchema>` produce just `never` so that it is assignable to the insertable for any given object type.
+ *
+ * Separating `{}` from `RestrictiveStringRecord<ImplicitFieldSchema>` is a bit messy since both extend each-other despite them being very different types.
+ * A third dummy type `{ arbitraryKey: "arbitraryValue" }` is used to resolve this.
+ *
  * @system @public
  */
 export type InsertableObjectFromSchemaRecord<
 	T extends RestrictiveStringRecord<ImplicitFieldSchema>,
-> = Record<string, never> extends T
-	? Record<string, never>
+> = RestrictiveStringRecord<ImplicitFieldSchema> extends T
+	? { arbitraryKey: "arbitraryValue" } extends T
+		? // {} case
+			Record<string, never>
+		: // RestrictiveStringRecord<ImplicitFieldSchema> case
+			never
 	: FlattenKeys<
 			{
 				readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
@@ -340,6 +356,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);
@@ -363,8 +382,17 @@ export function objectSchema<
 	let unhydratedContext: Context;
 
 	class CustomObjectNode extends CustomObjectNodeBase<T> {
-		public static readonly fields: ReadonlyMap<string, FieldSchema> = new Map(
-			Array.from(flexKeyMap, ([key, value]) => [key as string, value.schema]),
+		public static readonly fields: ReadonlyMap<
+			string,
+			FieldSchemaAlpha & SimpleObjectFieldSchema
+		> = new Map(
+			Array.from(flexKeyMap, ([key, value]) => [
+				key as string,
+				new ObjectFieldSchema(value.schema.kind, value.schema.allowedTypes, {
+					...value.schema.props,
+					key: getStoredKey(key as string, value.schema),
+				}),
+			]),
 		);
 		public static readonly flexKeyMap: SimpleKeyMap = flexKeyMap;
 		public static readonly storedKeyToPropertyKey: ReadonlyMap<FieldKey, string> = new Map<
@@ -464,8 +492,7 @@ export function objectSchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;
 		}
-		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> | undefined =
-			metadata;
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> = metadata ?? {};
 
 		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {

package/src/simple-tree/objectNodeTypes.ts

@@ -9,35 +9,37 @@ import type {
 	InsertableObjectFromSchemaRecord,
 	SimpleKeyMap,
 } from "./objectNode.js";
-import type { ImplicitFieldSchema, FieldSchema } from "./schemaTypes.js";
+import type { ImplicitFieldSchema, FieldSchemaAlpha } from "./schemaTypes.js";
 import { NodeKind, type TreeNodeSchemaClass, type TreeNodeSchema } from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
+import type { SimpleObjectFieldSchema, SimpleObjectNodeSchema } from "./simpleSchema.js";
 
 /**
  * A schema for {@link TreeObjectNode}s.
- * @privateRemarks
- * This is a candidate for being promoted to the public package API.
+ * @sealed
+ * @alpha
  */
 export interface ObjectNodeSchema<
-	TName extends string = string,
-	T extends
+	out TName extends string = string,
+	in out T extends
 		RestrictiveStringRecord<ImplicitFieldSchema> = RestrictiveStringRecord<ImplicitFieldSchema>,
 	ImplicitlyConstructable extends boolean = boolean,
-	TCustomMetadata = unknown,
+	out TCustomMetadata = unknown,
 > extends TreeNodeSchemaClass<
-		TName,
-		NodeKind.Object,
-		TreeObjectNode<T, TName>,
-		object & InsertableObjectFromSchemaRecord<T>,
-		ImplicitlyConstructable,
-		T,
-		never,
-		TCustomMetadata
-	> {
+			TName,
+			NodeKind.Object,
+			TreeObjectNode<T, TName>,
+			InsertableObjectFromSchemaRecord<T>,
+			ImplicitlyConstructable,
+			T,
+			never,
+			TCustomMetadata
+		>,
+		SimpleObjectNodeSchema<TCustomMetadata> {
 	/**
 	 * From property keys to the associated schema.
 	 */
-	readonly fields: ReadonlyMap<string, FieldSchema>;
+	readonly fields: ReadonlyMap<string, FieldSchemaAlpha & SimpleObjectFieldSchema>;
 }
 
 /**
@@ -65,6 +67,9 @@ export interface ObjectNodeSchemaInternalData {
 	readonly allowUnknownOptionalFields: boolean;
 }
 
+/**
+ * @alpha
+ */
 export const ObjectNodeSchema = {
 	/**
 	 * instanceof-based narrowing support for ObjectNodeSchema in Javascript and TypeScript 5.3 or newer.

package/src/simple-tree/proxies.ts

@@ -4,7 +4,7 @@
  */
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-
+import { fail } from "@fluidframework/core-utils/internal";
 import {
 	EmptyKey,
 	type IForestSubscription,
@@ -20,7 +20,7 @@ import {
 	type FlexTreeRequiredField,
 	type FlexTreeOptionalField,
 } from "../feature-libraries/index.js";
-import { type Mutable, fail, isReadonlyArray } from "../util/index.js";
+import { type Mutable, isReadonlyArray } from "../util/index.js";
 import {
 	getKernel,
 	type TreeNode,