@fluidframework/tree 2.30.0 → 2.31.1

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

@@ -21,26 +21,24 @@ import type {
 	WithType,
 	TreeNode,
 } from "../core/index.js";
-import type { FieldSchemaUnsafe, Unenforced } from "./typesUnsafe.js";
+import type { FieldSchemaAlphaUnsafe, ImplicitAllowedTypesUnsafe } from "./typesUnsafe.js";
 
 export function createFieldSchemaUnsafe<
 	Kind extends FieldKind,
-	Types extends Unenforced<ImplicitAllowedTypes>,
+	Types extends ImplicitAllowedTypesUnsafe,
+	TCustomMetadata = unknown,
 >(
 	kind: Kind,
 	allowedTypes: Types,
-	props: FieldProps | undefined,
-): FieldSchemaUnsafe<Kind, Types> {
+	props?: FieldProps<TCustomMetadata>,
+): FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata> {
 	// At runtime, we still want this to be a FieldSchema instance, but we can't satisfy its extends clause, so just return it as an FieldSchemaUnsafe
-	return createFieldSchema(
-		kind,
-		allowedTypes as ImplicitAllowedTypes,
-		props,
-	) as FieldSchemaUnsafe<Kind, Types>;
+	return createFieldSchema(kind, allowedTypes as ImplicitAllowedTypes & Types, props);
 }
 
 /**
  * Compile time check for validity of a recursive schema.
+ * This type also serves as a central location for documenting the requirements and issues related to recursive schema.
  *
  * @example
  * ```typescript
@@ -50,13 +48,37 @@ export function createFieldSchemaUnsafe<
  * }
  * ```
  * @remarks
- * The type of a recursive schema can be passed to this, and a compile error will be produced for some of the cases of malformed schema.
+ * In this context recursive schema are defined as all {@link FieldSchema} and {@link TreeNodeSchema} schema which are part of a cycle such that walking down through each {@link TreeNodeSchemaCore.childTypes} the given starting schema can be reached again.
+ * Schema referencing the recursive schema and schema they reference that are not part of a cycle are not considered recursive.
+ *
+ * TypeScript puts a lot of limitations on the typing of recursive schema.
+ * To help avoid running into these limitations and thus getting schema that do not type check (or only type checks sometimes!),
+ * {@link SchemaFactory} provides APIs (postfixed with `Recursive`) for writing recursive schema.
+ * These APIs when combined with the patterns documented below should ensure that the schema provide robust type checking.
+ * These special patterns (other than {@link LazyItem} forward references which are not recursion specific)
+ * are not required for correct runtime behavior: they exist entirely to mitigate TypeScript type checking limitations and bugs.
+ * Ideally TypeScript's type checker would be able to handle all of these cases and more, removing the need for recursive type specific guidance, rules and APIs.
+ * Currently however there are open issues preventing this:
+ * {@link https://github.com/microsoft/TypeScript/issues/59550 | 1},
+ * {@link https://github.com/microsoft/TypeScript/issues/55832 | 2},
+ * {@link https://github.com/microsoft/TypeScript/issues/55758 | 3}.
+ * Note that the proposed resolution to some of these issues is for the compiler to error rather than allow the case,
+ * so even if these are all resolved the recursive type workarounds may still be needed.
+ *
+ * # Patterns
+ *
+ * Below are patterns for how to use recursive schema.
+ *
+ * ## General Patterns
+ *
+ * When defining a recursive {@link TreeNodeSchema}, use the `*Recursive` {@link SchemaFactory} methods.
+ * The returned class should be used as the base class for the recursive schema, which should then be passed to {@link ValidateRecursiveSchema}.
+ *
+ * Using {@link ValidateRecursiveSchema} will provide compile error for some of the cases of malformed schema.
  * This can be used to help mitigate the issue that recursive schema definitions are {@link Unenforced}.
  * If an issue is encountered where a mistake in a recursive schema is made which produces an invalid schema but is not rejected by this checker,
  * it should be considered a bug and this should be updated to handle that case (or have a disclaimer added to these docs that it misses that case).
  *
- * # Recursive Schema
- *
  * The non-recursive versions of the schema building methods will run into several issues when used recursively.
  * Consider the following example:
  *
@@ -110,12 +132,22 @@ export function createFieldSchemaUnsafe<
  * }
  * ```
  *
+ * ## Object Schema
+ *
+ * When defining fields, if the fields is part of the recursive cycle, use the `*Recursive` {@link SchemaFactory} methods for defining the {@link FieldSchema}.
+ *
+ * ## Array Schema
+ *
+ * See {@link FixRecursiveArraySchema} for array specific details.
+ *
  * @privateRemarks
  * There are probably mistakes this misses: it's hard to guess all the wrong things people will accidentally do and defend against them.
  * Hopefully over time this can grow toward being robust, at least for common mistakes.
  *
  * This check duplicates logic that ideally would be entirely decided by the actual schema building methods.
  * Therefore changes to those methods may require updating `ValidateRecursiveSchema`.
+ *
+ * TODO: this currently does not reject `any`, but ideally should.
  * @public
  */
 export type ValidateRecursiveSchema<

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

@@ -3,14 +3,23 @@
  * Licensed under the MIT License.
  */
 
-import { unreachableCase } from "@fluidframework/core-utils/internal";
-import { fail } from "../../util/index.js";
+import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
-import { createFieldSchema, type FieldSchema, type AllowedTypes } from "../schemaTypes.js";
+import {
+	type FieldSchema,
+	type AllowedTypes,
+	type FieldSchemaAlpha,
+	FieldKind,
+} from "../schemaTypes.js";
 import { SchemaFactory } from "./schemaFactory.js";
-import type { SimpleFieldSchema, SimpleNodeSchema, SimpleTreeSchema } from "./simpleSchema.js";
+import type {
+	SimpleFieldSchema,
+	SimpleNodeSchema,
+	SimpleTreeSchema,
+} from "../simpleSchema.js";
+import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 
-const factory = new SchemaFactory(undefined);
+const factory = new SchemaFactoryAlpha(undefined);
 
 /**
  * Create {@link FieldSchema} from a SimpleTreeSchema.
@@ -21,9 +30,9 @@ const factory = new SchemaFactory(undefined);
  * will produce a poor TypeScript typing experience which is subject to change.
  *
  * Editing through a view produced using this schema can easily violate invariants other users of the document might expect and must be done with great care.
- * @internal
+ * @alpha
  */
-export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): FieldSchema {
+export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): FieldSchemaAlpha {
 	const context: Context = new Map(
 		[...simple.definitions].map(([id, schema]): [string, () => TreeNodeSchema] => [
 			id,
@@ -36,8 +45,19 @@ export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): FieldS
 
 type Context = ReadonlyMap<string, () => TreeNodeSchema>;
 
-function generateFieldSchema(simple: SimpleFieldSchema, context: Context): FieldSchema {
-	return createFieldSchema(simple.kind, generateAllowedTypes(simple.allowedTypes, context));
+function generateFieldSchema(simple: SimpleFieldSchema, context: Context): FieldSchemaAlpha {
+	const allowed = generateAllowedTypes(simple.allowedTypesIdentifiers, context);
+	// Using createFieldSchema could work, but would require setting up the default providers.
+	switch (simple.kind) {
+		case FieldKind.Identifier:
+			return SchemaFactoryAlpha.identifier({ metadata: simple.metadata });
+		case FieldKind.Optional:
+			return SchemaFactoryAlpha.optional(allowed, { metadata: simple.metadata });
+		case FieldKind.Required:
+			return SchemaFactoryAlpha.required(allowed, { metadata: simple.metadata });
+		default:
+			return unreachableCase(simple.kind);
+	}
 }
 
 function generateAllowedTypes(allowed: ReadonlySet<string>, context: Context): AllowedTypes {
@@ -48,15 +68,23 @@ function generateNode(id: string, schema: SimpleNodeSchema, context: Context): T
 	switch (schema.kind) {
 		case NodeKind.Object: {
 			const fields: Record<string, FieldSchema> = {};
-			for (const [key, field] of Object.entries(schema.fields)) {
+			for (const [key, field] of schema.fields) {
 				fields[key] = generateFieldSchema(field, context);
 			}
-			return factory.object(id, fields);
+			return factory.object(id, fields, { metadata: schema.metadata });
 		}
 		case NodeKind.Array:
-			return factory.array(id, generateAllowedTypes(schema.allowedTypes, context));
+			return factory.arrayAlpha(
+				id,
+				generateAllowedTypes(schema.allowedTypesIdentifiers, context),
+				{ metadata: schema.metadata },
+			);
 		case NodeKind.Map:
-			return factory.map(id, generateAllowedTypes(schema.allowedTypes, context));
+			return factory.mapAlpha(
+				id,
+				generateAllowedTypes(schema.allowedTypesIdentifiers, context),
+				{ metadata: schema.metadata },
+			);
 		case NodeKind.Leaf:
 			return (
 				SchemaFactory.leaves.find((leaf) => leaf.identifier === id) ??

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

@@ -27,7 +27,7 @@ import type {
 	SimpleNodeSchema,
 	SimpleObjectNodeSchema,
 	SimpleTreeSchema,
-} from "./simpleSchema.js";
+} from "../simpleSchema.js";
 import { NodeKind } from "../core/index.js";
 
 /**
@@ -38,7 +38,7 @@ export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
 	const definitions = convertDefinitions(schema.definitions);
 
 	const allowedTypes: JsonSchemaRef[] = [];
-	for (const allowedType of schema.allowedTypes) {
+	for (const allowedType of schema.allowedTypesIdentifiers) {
 		allowedTypes.push(createSchemaRef(allowedType));
 	}
 
@@ -92,7 +92,7 @@ function convertNodeSchema(schema: SimpleNodeSchema): JsonNodeSchema {
 
 function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSchema {
 	const allowedTypes: JsonSchemaRef[] = [];
-	schema.allowedTypes.forEach((type) => {
+	schema.allowedTypesIdentifiers.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
 
@@ -138,12 +138,12 @@ function convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema
 	};
 }
 
-function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {
+export function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {
 	const properties: Record<string, JsonFieldSchema> = {};
 	const required: string[] = [];
-	for (const [key, fieldSchema] of Object.entries(schema.fields)) {
+	for (const [key, fieldSchema] of schema.fields) {
 		const allowedTypes: JsonSchemaRef[] = [];
-		for (const allowedType of fieldSchema.allowedTypes) {
+		for (const allowedType of fieldSchema.allowedTypesIdentifiers) {
 			allowedTypes.push(createSchemaRef(allowedType));
 		}
 
@@ -176,7 +176,7 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 
 function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 	const allowedTypes: JsonSchemaRef[] = [];
-	schema.allowedTypes.forEach((type) => {
+	schema.allowedTypesIdentifiers.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
 

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

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { fail } from "@fluidframework/core-utils/internal";
 import type {
 	AnchorNode,
 	FieldKey,
@@ -18,7 +19,7 @@ import {
 	type TreeIndexKey,
 	type KeyFinder,
 } from "../../feature-libraries/index.js";
-import { brand, fail } from "../../util/index.js";
+import { brand } from "../../util/index.js";
 import type { ImplicitFieldSchema, NodeFromSchema } from "../schemaTypes.js";
 import { treeNodeFromAnchor, type TreeNode, type TreeNodeSchema } from "../core/index.js";
 import { treeNodeApi } from "./treeNodeApi.js";

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

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IFluidLoadable, IDisposable, Listenable } from "@fluidframework/core-interfaces";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -32,13 +33,12 @@ import {
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import { toStoredSchema } from "../toStoredSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
-import { assert } from "@fluidframework/core-utils/internal";
 import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js";
-import { fail, getOrCreate } from "../../util/index.js";
+import { getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
 import type { VerboseTree } from "./verboseTree.js";
-import type { SimpleTreeSchema } from "./simpleSchema.js";
+import type { SimpleTreeSchema } from "../simpleSchema.js";
 import type {
 	RunTransactionParams,
 	TransactionCallbackStatus,

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

@@ -3,11 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail } from "@fluidframework/core-utils/internal";
 
 import { EmptyKey, rootFieldKey } from "../../core/index.js";
 import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
-import { fail, extractFromOpaque } from "../../util/index.js";
+import { extractFromOpaque } from "../../util/index.js";
 import {
 	type TreeLeafValue,
 	type ImplicitFieldSchema,

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

@@ -10,8 +10,8 @@ import type {
 	ApplyKindInput,
 	FieldKind,
 	FieldSchema,
+	FieldSchemaAlpha,
 	ImplicitAllowedTypes,
-	ImplicitFieldSchema,
 	TreeLeafValue,
 } from "../schemaTypes.js";
 import type {
@@ -22,9 +22,11 @@ import type {
 	InternalTreeNode,
 	TreeNodeSchema,
 	TreeNodeSchemaCore,
+	TreeNodeSchemaClass,
 } from "../core/index.js";
 import type { TreeArrayNode } from "../arrayNode.js";
 import type { FlexListToUnion, LazyItem } from "../flexList.js";
+import type { SimpleArrayNodeSchema, SimpleMapNodeSchema } from "../simpleSchema.js";
 
 /*
  * TODO:
@@ -52,12 +54,16 @@ export type Unenforced<_DesiredExtendsConstraint> = unknown;
  * {@link Unenforced} version of `ObjectFromSchemaRecord`.
  * @remarks
  * 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 does not bother special casing `{}` since no one should make empty objects using the *Recursive APIs.
  * @system @public
  */
 export type ObjectFromSchemaRecordUnsafe<
-	T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>,
+	T extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,
 > = {
-	-readonly [Property in keyof T]: TreeFieldFromImplicitFieldUnsafe<T[Property]>;
+	-readonly [Property in keyof T]: Property extends string
+		? TreeFieldFromImplicitFieldUnsafe<T[Property]>
+		: unknown;
 };
 
 /**
@@ -90,7 +96,15 @@ export interface TreeNodeSchemaClassUnsafe<
 	in TInsertable,
 	out ImplicitlyConstructable extends boolean,
 	out Info,
-> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
+	out TCustomMetadata = unknown,
+> extends TreeNodeSchemaCore<
+		Name,
+		Kind,
+		ImplicitlyConstructable,
+		Info,
+		never,
+		TCustomMetadata
+	> {
 	/**
 	 * Constructs an {@link Unhydrated} node with this schema.
 	 * @remarks
@@ -125,9 +139,9 @@ export interface TreeNodeSchemaNonClassUnsafe<
  * @system @public
  */
 export type TreeObjectNodeUnsafe<
-	T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>,
+	T extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,
 	TypeName extends string = string,
-> = TreeNode & ObjectFromSchemaRecordUnsafe<T> & WithType<TypeName, NodeKind.Object>;
+> = TreeNode & ObjectFromSchemaRecordUnsafe<T> & WithType<TypeName, NodeKind.Object, T>;
 
 /**
  * {@link Unenforced} version of {@link TreeFieldFromImplicitField}.
@@ -135,10 +149,10 @@ export type TreeObjectNodeUnsafe<
  * 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>> =
+export type TreeFieldFromImplicitFieldUnsafe<TSchema extends ImplicitFieldSchemaUnsafe> =
 	TSchema extends FieldSchemaUnsafe<infer Kind, infer Types>
 		? ApplyKind<TreeNodeFromImplicitAllowedTypesUnsafe<Types>, Kind>
-		: TSchema extends ImplicitAllowedTypes
+		: TSchema extends ImplicitAllowedTypesUnsafe
 			? TreeNodeFromImplicitAllowedTypesUnsafe<TSchema>
 			: unknown;
 
@@ -150,6 +164,35 @@ export type TreeFieldFromImplicitFieldUnsafe<TSchema extends Unenforced<Implicit
  */
 export type AllowedTypesUnsafe = readonly LazyItem<TreeNodeSchemaUnsafe>[];
 
+/**
+ * {@link Unenforced} version of {@link ImplicitAllowedTypes}.
+ * @remarks
+ * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @privateRemarks
+ * This is similar to `Unenforced<ImplicitAllowedTypes>` in that it avoids constraining the schema
+ * (which is necessary to avoid breaking recursive types),
+ * but is superior from a safety perspective because it constrains the structure containing the schema.
+ * @system @public
+ */
+export type ImplicitAllowedTypesUnsafe =
+	| TreeNodeSchemaUnsafe
+	// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+	| readonly LazyItem<Unenforced<TreeNodeSchema>>[];
+
+/**
+ * {@link Unenforced} version of {@link ImplicitFieldSchema}.
+ * @remarks
+ * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @privateRemarks
+ * This is similar to `Unenforced<ImplicitFieldSchema>` in that it avoids constraining the schema
+ * (which is necessary to avoid breaking recursive types),
+ * but is superior from a safety perspective because it constrains the structure containing the schema.
+ * @system @public
+ */
+export type ImplicitFieldSchemaUnsafe =
+	| FieldSchemaUnsafe<FieldKind, ImplicitAllowedTypesUnsafe>
+	| ImplicitAllowedTypesUnsafe;
+
 /**
  * {@link Unenforced} version of {@link TreeNodeFromImplicitAllowedTypes}.
  * @remarks
@@ -157,7 +200,7 @@ export type AllowedTypesUnsafe = readonly LazyItem<TreeNodeSchemaUnsafe>[];
  * @system @public
  */
 export type TreeNodeFromImplicitAllowedTypesUnsafe<
-	TSchema extends Unenforced<ImplicitAllowedTypes>,
+	TSchema extends ImplicitAllowedTypesUnsafe,
 > = TSchema extends TreeNodeSchemaUnsafe
 	? NodeFromSchemaUnsafe<TSchema>
 	: TSchema extends AllowedTypesUnsafe
@@ -172,7 +215,7 @@ export type TreeNodeFromImplicitAllowedTypesUnsafe<
  * @system @public
  */
 export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<
-	TSchema extends Unenforced<ImplicitAllowedTypes>,
+	TSchema extends ImplicitAllowedTypesUnsafe,
 > = [TSchema] extends [TreeNodeSchemaUnsafe]
 	? InsertableTypedNodeUnsafe<TSchema>
 	: [TSchema] extends [AllowedTypesUnsafe]
@@ -184,14 +227,13 @@ export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<
  * @see {@link Input}
  * @system @public
  */
-export type InsertableTreeNodeFromAllowedTypesUnsafe<
-	TList extends Unenforced<AllowedTypesUnsafe>,
-> = TList extends readonly [
-	LazyItem<infer TSchema extends TreeNodeSchemaUnsafe>,
-	...infer Rest extends AllowedTypesUnsafe,
-]
-	? InsertableTypedNodeUnsafe<TSchema> | InsertableTreeNodeFromAllowedTypesUnsafe<Rest>
-	: never;
+export type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> =
+	TList extends readonly [
+		LazyItem<infer TSchema extends TreeNodeSchemaUnsafe>,
+		...infer Rest extends AllowedTypesUnsafe,
+	]
+		? InsertableTypedNodeUnsafe<TSchema> | InsertableTreeNodeFromAllowedTypesUnsafe<Rest>
+		: never;
 
 /**
  * {@link Unenforced} version of {@link InsertableTypedNode}.
@@ -205,7 +247,7 @@ export type InsertableTreeNodeFromAllowedTypesUnsafe<
  * @system @public
  */
 export type InsertableTypedNodeUnsafe<
-	TSchema extends Unenforced<TreeNodeSchemaUnsafe>,
+	TSchema extends TreeNodeSchemaUnsafe,
 	T = UnionToIntersection<TSchema>,
 > =
 	| (T extends TreeNodeSchemaUnsafe<string, NodeKind, TreeNode | TreeLeafValue, never, true>
@@ -237,7 +279,7 @@ export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =
  * 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>>
+export interface TreeArrayNodeUnsafe<TAllowedTypes extends ImplicitAllowedTypesUnsafe>
 	extends TreeArrayNode<
 		TAllowedTypes,
 		TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>,
@@ -250,7 +292,7 @@ export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAl
  * 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>>
+export interface TreeMapNodeUnsafe<T extends ImplicitAllowedTypesUnsafe>
 	extends ReadonlyMapInlined<string, T>,
 		TreeNode {
 	/**
@@ -278,7 +320,7 @@ export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
  * Authored by manually inlining ReadonlyMap from from the TypeScript lib which can be found by navigating to the definition of `ReadonlyMap`.
  * @system @sealed @public
  */
-export interface ReadonlyMapInlined<K, T extends Unenforced<ImplicitAllowedTypes>> {
+export interface ReadonlyMapInlined<K, T extends ImplicitAllowedTypesUnsafe> {
 	/** Returns an iterable of entries in the map. */
 	[Symbol.iterator](): IterableIterator<[K, TreeNodeFromImplicitAllowedTypesUnsafe<T>]>;
 
@@ -316,10 +358,10 @@ export interface ReadonlyMapInlined<K, T extends Unenforced<ImplicitAllowedTypes
  * 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>> =
+export type FieldHasDefaultUnsafe<T extends ImplicitFieldSchemaUnsafe> =
 	T extends FieldSchemaUnsafe<
 		FieldKind.Optional | FieldKind.Identifier,
-		Unenforced<ImplicitAllowedTypes>
+		ImplicitAllowedTypesUnsafe
 	>
 		? true
 		: false;
@@ -332,18 +374,18 @@ export type FieldHasDefaultUnsafe<T extends Unenforced<ImplicitFieldSchema>> =
  * @system @public
  */
 export type InsertableObjectFromSchemaRecordUnsafe<
-	T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>,
+	T extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,
 > = {
 	// Field might not have a default, so make it required:
-	readonly [Property in keyof T as FieldHasDefaultUnsafe<T[Property]> extends false
+	readonly [Property in keyof T as FieldHasDefaultUnsafe<T[Property & string]> extends false
 		? Property
-		: never]: InsertableTreeFieldFromImplicitFieldUnsafe<T[Property]>;
+		: never]: InsertableTreeFieldFromImplicitFieldUnsafe<T[Property & string]>;
 } & {
 	// Field might have a default, so allow optional.
 	// Note that if the field could be either, this returns boolean, causing both fields to exist, resulting in required.
-	readonly [Property in keyof T as FieldHasDefaultUnsafe<T[Property]> extends true
+	readonly [Property in keyof T as FieldHasDefaultUnsafe<T[Property & string]> extends true
 		? Property
-		: never]?: InsertableTreeFieldFromImplicitFieldUnsafe<T[Property]>;
+		: never]?: InsertableTreeFieldFromImplicitFieldUnsafe<T[Property & string]>;
 };
 
 /**
@@ -354,7 +396,7 @@ export type InsertableObjectFromSchemaRecordUnsafe<
  * @system @public
  */
 export type InsertableTreeFieldFromImplicitFieldUnsafe<
-	TSchemaInput extends Unenforced<ImplicitFieldSchema>,
+	TSchemaInput extends ImplicitFieldSchemaUnsafe,
 	TSchema = UnionToIntersection<TSchemaInput>,
 > = [TSchema] extends [FieldSchemaUnsafe<infer Kind, infer Types>]
 	? ApplyKindInput<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<Types>, Kind, true>
@@ -366,12 +408,13 @@ export type InsertableTreeFieldFromImplicitFieldUnsafe<
  * {@link Unenforced} version of {@link FieldSchema}.
  * @remarks
  * 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
+ * @system @sealed @public
  */
 export interface FieldSchemaUnsafe<
 	out Kind extends FieldKind,
-	out Types extends Unenforced<ImplicitAllowedTypes>,
-> extends FieldSchema<Kind, any> {
+	out Types extends ImplicitAllowedTypesUnsafe,
+	out TCustomMetadata = unknown,
+> extends FieldSchema<Kind, any, TCustomMetadata> {
 	/**
 	 * {@inheritDoc FieldSchema.kind}
 	 */
@@ -386,4 +429,79 @@ export interface FieldSchemaUnsafe<
 	readonly allowedTypeSet: ReadonlySet<TreeNodeSchema>;
 }
 
+/**
+ * {@link Unenforced} version of {@link FieldSchemaAlpha}.
+ * @remarks
+ * 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 @alpha
+ */
+export interface FieldSchemaAlphaUnsafe<
+	out Kind extends FieldKind,
+	out Types extends ImplicitAllowedTypesUnsafe,
+	out TCustomMetadata = unknown,
+> extends FieldSchemaAlpha<Kind, any, TCustomMetadata>,
+		FieldSchemaUnsafe<Kind, Types, TCustomMetadata> {
+	/**
+	 * {@inheritDoc FieldSchema.allowedTypes}
+	 */
+	readonly allowedTypes: Types;
+}
+
 /* eslint-enable @typescript-eslint/no-explicit-any */
+
+/**
+ * {@link Unenforced} version of {@link ArrayNodeCustomizableSchema}s.
+ * @remarks
+ * 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.
+ * @sealed
+ * @alpha
+ * @system
+ */
+export interface ArrayNodeCustomizableSchemaUnsafe<
+	out TName extends string,
+	in out T extends ImplicitAllowedTypesUnsafe,
+	out TCustomMetadata,
+> extends TreeNodeSchemaClass<
+			TName,
+			NodeKind.Array,
+			TreeArrayNodeUnsafe<T> & WithType<TName, NodeKind.Array, T>,
+			{
+				[Symbol.iterator](): Iterator<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>;
+			},
+			false,
+			T,
+			undefined,
+			TCustomMetadata
+		>,
+		SimpleArrayNodeSchema<TCustomMetadata> {}
+
+/**
+ * {@link Unenforced} version of {@link MapNodeCustomizableSchema}s.
+ * @remarks
+ * 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.
+ * @sealed
+ * @alpha
+ * @system
+ */
+export interface MapNodeCustomizableSchemaUnsafe<
+	out TName extends string,
+	in out T extends ImplicitAllowedTypesUnsafe,
+	out TCustomMetadata,
+> extends TreeNodeSchemaClass<
+			TName,
+			NodeKind.Map,
+			TreeMapNodeUnsafe<T> & WithType<TName, NodeKind.Map, T>,
+			| {
+					[Symbol.iterator](): Iterator<
+						[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
+					>;
+			  }
+			| {
+					readonly [P in string]: InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
+			  },
+			false,
+			T,
+			undefined,
+			TCustomMetadata
+		>,
+		SimpleMapNodeSchema<TCustomMetadata> {}

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

@@ -5,7 +5,7 @@
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 
 import {
 	aboveRootPlaceholder,
@@ -16,7 +16,7 @@ import {
 	type ITreeCursorSynchronous,
 	type TreeNodeSchemaIdentifier,
 } from "../../core/index.js";
-import { brand, fail } from "../../util/index.js";
+import { brand } from "../../util/index.js";
 import type {
 	TreeLeafValue,
 	ImplicitFieldSchema,

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

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import {
 	AdaptedViewSchema,
 	type TreeNodeStoredSchema,
@@ -11,7 +12,6 @@ import {
 	type TreeNodeSchemaIdentifier,
 	type TreeStoredSchema,
 } from "../../core/index.js";
-import { fail } from "../../util/index.js";
 import {
 	FieldKinds,
 	type FullSchemaPolicy,
@@ -28,7 +28,6 @@ import {
 	type ImplicitFieldSchema,
 } from "../schemaTypes.js";
 import { toStoredSchema } from "../toStoredSchema.js";
-import { unreachableCase } from "@fluidframework/core-utils/internal";
 import type { SchemaCompatibilityStatus } from "./tree.js";
 
 /**