@fluidframework/tree 2.52.0 → 2.53.0

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

@@ -0,0 +1,291 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import type {
+	ImplicitAllowedTypes,
+	ImplicitAnnotatedAllowedTypes,
+	UnannotateImplicitAllowedTypes,
+} from "../core/index.js";
+import { FieldKind, getDefaultProvider, createFieldSchema } from "../fieldSchema.js";
+import type {
+	FieldProps,
+	FieldSchema,
+	DefaultProvider,
+	FieldPropsAlpha,
+	FieldSchemaAlpha,
+} from "../fieldSchema.js";
+import type { LeafSchema } from "../leafNodeSchema.js";
+import {
+	stringSchema,
+	numberSchema,
+	booleanSchema,
+	nullSchema,
+	handleSchema,
+} from "../leafNodeSchema.js";
+import type { System_Unsafe, FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
+
+/**
+ * Stateless APIs exposed via {@link SchemaFactory} as both instance properties and as statics.
+ * @privateRemarks
+ * We have no way to make linkable members which exist both as statics and instance properties since API-Extractor does not support this.
+ * As a workaround, we have this type as a third place which can be linked.
+ * @system @sealed @public
+ */
+export interface SchemaStatics {
+	/**
+	 * {@link TreeNodeSchema} for holding a JavaScript `string`.
+	 *
+	 * @remarks
+	 * Strings containing unpaired UTF-16 surrogate pair code units may not be handled correctly.
+	 *
+	 * These limitations come from the use of UTF-8 encoding of the strings, which requires them to be valid unicode.
+	 * JavaScript does not make this requirement for its strings so not all possible JavaScript strings are supported.
+	 * @privateRemarks
+	 * TODO:
+	 * We should be much more clear about what happens if you use problematic values.
+	 * We should validate and/or normalize them when inserting content.
+	 */
+	readonly string: LeafSchema<"string", string>;
+
+	/**
+	 * {@link TreeNodeSchema} for holding a JavaScript `number`.
+	 *
+	 * @remarks
+	 * The number is a {@link https://en.wikipedia.org/wiki/Double-precision_floating-point_format | double-precision 64-bit binary format IEEE 754} value, however there are some exceptions:
+	 *
+	 * - `NaN`, and the infinities are converted to `null` (and may therefore only be used where `null` is allowed by the schema).
+	 *
+	 * - `-0` may be converted to `0` in some cases.
+	 *
+	 * These limitations match the limitations of JSON.
+	 * @privateRemarks
+	 * TODO:
+	 * We should be much more clear about what happens if you use problematic values.
+	 * We should validate and/or normalize them when inserting content.
+	 */
+	readonly number: LeafSchema<"number", number>;
+
+	/**
+	 * {@link TreeNodeSchema} for holding a boolean.
+	 */
+	readonly boolean: LeafSchema<"boolean", boolean>;
+
+	/**
+	 * {@link TreeNodeSchema} for JavaScript `null`.
+	 *
+	 * @remarks
+	 * There are good {@link https://www.npmjs.com/package/%40rushstack/eslint-plugin#rushstackno-new-null | reasons to avoid using null} in JavaScript, however sometimes it is desired.
+	 * This {@link TreeNodeSchema} node provides the option to include nulls in trees when desired.
+	 * Unless directly inter-operating with existing data using null, consider other approaches, like wrapping the value in an optional field, or using a more specifically named empty object node.
+	 */
+	// eslint-disable-next-line @rushstack/no-new-null
+	readonly null: LeafSchema<"null", null>;
+
+	/**
+	 * {@link TreeNodeSchema} for holding an {@link @fluidframework/core-interfaces#(IFluidHandle:interface)}.
+	 */
+	readonly handle: LeafSchema<"handle", IFluidHandle>;
+
+	/**
+	 * {@link AllowedTypes} for holding any of the leaf types.
+	 */
+	readonly leaves: readonly [
+		SchemaStatics["string"],
+		SchemaStatics["number"],
+		SchemaStatics["boolean"],
+		SchemaStatics["null"],
+		SchemaStatics["handle"],
+	];
+
+	/**
+	 * Make a field optional instead of the default, which is required.
+	 *
+	 * @param t - The types allowed under the field.
+	 * @param props - Optional properties to associate with the field.
+	 *
+	 * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+	 * See {@link FieldSchemaMetadata.custom}.
+	 */
+	readonly optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+		t: T,
+		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	) => FieldSchema<FieldKind.Optional, T, TCustomMetadata>;
+
+	/**
+	 * Make a field explicitly required.
+	 *
+	 * @param t - The types allowed under the field.
+	 * @param props - Optional properties to associate with the field.
+	 *
+	 * @remarks
+	 * Fields are required by default, but this API can be used to make the required nature explicit in the schema,
+	 * and allows associating custom {@link FieldProps | properties} with the field.
+	 *
+	 * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+	 * See {@link FieldSchemaMetadata.custom}.
+	 */
+	readonly required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+		t: T,
+		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	) => FieldSchema<FieldKind.Required, T, TCustomMetadata>;
+
+	/**
+	 * {@link SchemaStatics.optional} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStatics.optional} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 */
+	readonly optionalRecursive: <
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+		const TCustomMetadata = unknown,
+	>(
+		t: T,
+		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Optional, T, TCustomMetadata>;
+
+	/**
+	 * {@link SchemaStatics.required} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStatics.required} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 */
+	readonly requiredRecursive: <
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+		const TCustomMetadata = unknown,
+	>(
+		t: T,
+		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Required, T, TCustomMetadata>;
+}
+
+const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => []);
+
+// The following overloads for optional and required are used to get around the fact that
+// the compiler can't infer that UnannotateImplicitAllowedTypes<T> is equal to T when T is known to extend ImplicitAllowedTypes
+
+// #region Overloads for optional and required
+function optional<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+	t: T,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
+
+function optional<
+	const T extends ImplicitAnnotatedAllowedTypes,
+	const TCustomMetadata = unknown,
+>(
+	t: T,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
+
+function optional<
+	const T extends ImplicitAnnotatedAllowedTypes,
+	const TCustomMetadata = unknown,
+>(
+	t: T,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
+	return createFieldSchema(FieldKind.Optional, t, {
+		defaultProvider: defaultOptionalProvider,
+		...props,
+	});
+}
+
+function required<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+	t: T,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
+
+function required<
+	const T extends ImplicitAnnotatedAllowedTypes,
+	const TCustomMetadata = unknown,
+>(
+	t: T,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
+
+function required<
+	const T extends ImplicitAnnotatedAllowedTypes,
+	const TCustomMetadata = unknown,
+>(
+	t: T,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
+	return createFieldSchema(FieldKind.Required, t, props);
+}
+// #endregion
+
+/**
+ * Implementation of {@link SchemaStatics}.
+ * @remarks
+ * Entries can use more specific types than {@link SchemaStatics} requires to be more useful for non-public consumers.
+ * Additional non-public members are in {@link schemaStatics}.
+ */
+export const schemaStaticsStable = {
+	string: stringSchema,
+	number: numberSchema,
+	boolean: booleanSchema,
+	null: nullSchema,
+	handle: handleSchema,
+	leaves: [stringSchema, numberSchema, booleanSchema, nullSchema, handleSchema],
+
+	optional,
+
+	required,
+
+	optionalRecursive: <
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+		const TCustomMetadata = unknown,
+	>(
+		t: T,
+		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+	): FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata> => {
+		return createFieldSchemaUnsafe(FieldKind.Optional, t, {
+			defaultProvider: defaultOptionalProvider,
+			...props,
+		});
+	},
+
+	requiredRecursive: <
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+		const TCustomMetadata = unknown,
+	>(
+		t: T,
+		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+	): FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata> => {
+		return createFieldSchemaUnsafe(FieldKind.Required, t, props);
+	},
+} as const satisfies SchemaStatics;
+
+/**
+ * Unstable extensions to {@link schemaStaticsStable}.
+ */
+export const schemaStatics = {
+	...schemaStaticsStable,
+	identifier: <const TCustomMetadata = unknown>(
+		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	): FieldSchemaAlpha<FieldKind.Identifier, typeof stringSchema, TCustomMetadata> => {
+		return createFieldSchema(FieldKind.Identifier, stringSchema, props);
+	},
+} as const;
+
+function createFieldSchemaUnsafe<
+	Kind extends FieldKind,
+	Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+	TCustomMetadata = unknown,
+>(
+	kind: Kind,
+	allowedTypes: 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 & Types,
+		props,
+	) as FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata>;
+}

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

@@ -12,9 +12,13 @@ import {
 	// eslint-disable-next-line import/no-internal-modules
 } from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
-import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
-import type { SimpleTreeSchema } from "../simpleSchema.js";
-import { simpleToStoredSchema } from "../toStoredSchema.js";
+import type { SchemaUpgrade } from "../core/index.js";
+import {
+	normalizeFieldSchema,
+	type ImplicitAnnotatedFieldSchema,
+	type ImplicitFieldSchema,
+} from "../fieldSchema.js";
+import { toStoredSchema } from "../toStoredSchema.js";
 import { TreeViewConfigurationAlpha } from "./configuration.js";
 
 import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
@@ -24,6 +28,8 @@ import type { SchemaCompatibilityStatus } from "./tree.js";
  * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.
  *
  * @param schema - The schema to dump.
+ * @param oldestCompatibleClient - The oldest client version which can read the schema: impacts the format used.
+ * @param includeStaged - filter for selecting which staged allowed types to include in the output.
  *
  * @remarks
  * This can be used to help inspect schema for debugging, and to save a snapshot of schema to help detect and review changes to an applications schema.
@@ -51,10 +57,11 @@ import type { SchemaCompatibilityStatus } from "./tree.js";
  * @alpha
  */
 export function extractPersistedSchema(
-	schema: SimpleTreeSchema,
+	schema: ImplicitAnnotatedFieldSchema,
 	oldestCompatibleClient: FluidClientVersion,
+	includeStaged: (upgrade: SchemaUpgrade) => boolean,
 ): JsonCompatible {
-	const stored = simpleToStoredSchema(schema);
+	const stored = toStoredSchema(schema, { includeStaged });
 	const schemaWriteVersion = clientVersionToSchemaVersion(oldestCompatibleClient);
 	return encodeTreeSchema(stored, schemaWriteVersion);
 }

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

@@ -3,7 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import { defaultSchemaPolicy } from "../../feature-libraries/index.js";
+import type { TreeFieldStoredSchema } from "../../core/index.js";
+import { defaultSchemaPolicy, FieldKinds } from "../../feature-libraries/index.js";
+import { brand } from "../../util/index.js";
 import {
 	Context,
 	getKernel,
@@ -191,7 +193,12 @@ export const TreeBeta: TreeBeta = {
 		);
 		const context = new Context(flexContext, getUnhydratedContext(kernel.schema).schema);
 
-		return createFromCursor(kernel.schema, cursor, context) as Unhydrated<
+		const fieldSchema: TreeFieldStoredSchema = {
+			kind: FieldKinds.required.identifier,
+			types: new Set([brand(kernel.schema.identifier)]),
+			persistedMetadata: undefined,
+		};
+		return createFromCursor(kernel.schema, cursor, fieldSchema, context) as Unhydrated<
 			TreeFieldFromImplicitField<TSchema>
 		>;
 	},

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

@@ -5,7 +5,12 @@
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { getOrCreate, isReadonlyArray, type IsUnion } from "../../util/index.js";
+import {
+	getOrCreate,
+	isReadonlyArray,
+	type IsUnion,
+	type MakeNominal,
+} from "../../util/index.js";
 import { isLazy, type FlexListToUnion, type LazyItem } from "./flexList.js";
 import {
 	NodeKind,
@@ -42,7 +47,10 @@ export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
 
 /**
  * Stores annotations for an individual allowed type.
+ * @remarks
+ * Create using APIs on {@link SchemaFactoryAlpha}, like {@link SchemaStaticsAlpha.staged}.
  * @alpha
+ * @sealed
  */
 export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
 	/**
@@ -56,19 +64,12 @@ export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
 }
 
 /**
- * Stores annotations for a set of evaluated annotated allowed types.
+ * {@link AnnotatedAllowedTypes} but with the lazy schema references eagerly evaluated.
+ * @sealed
  * @alpha
  */
-export interface NormalizedAnnotatedAllowedTypes {
-	/**
-	 * Annotations that apply to a set of allowed types.
-	 */
-	readonly metadata: AllowedTypesMetadata;
-	/**
-	 * All the evaluated allowed types that the annotations apply to. The types themselves are also individually annotated.
-	 */
-	readonly types: readonly AnnotatedAllowedType<TreeNodeSchema>[];
-}
+export interface NormalizedAnnotatedAllowedTypes
+	extends AnnotatedAllowedTypes<TreeNodeSchema> {}
 
 /**
  * Checks if the input is an {@link AnnotatedAllowedTypes}.
@@ -86,8 +87,9 @@ export function isAnnotatedAllowedTypes(
 /**
  * Stores annotations for a set of allowed types.
  * @alpha
+ * @sealed
  */
-export interface AnnotatedAllowedTypes {
+export interface AnnotatedAllowedTypes<T = LazyItem<TreeNodeSchema>> {
 	/**
 	 * Annotations that apply to a set of allowed types.
 	 */
@@ -95,7 +97,7 @@ export interface AnnotatedAllowedTypes {
 	/**
 	 * All the allowed types that the annotations apply to. The types themselves may also have individual annotations.
 	 */
-	readonly types: readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[];
+	readonly types: readonly AnnotatedAllowedType<T>[];
 }
 
 /**
@@ -103,6 +105,7 @@ export interface AnnotatedAllowedTypes {
  * @remarks
  * Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
  * @alpha
+ * @input
  */
 export interface AllowedTypesMetadata {
 	/**
@@ -127,6 +130,7 @@ export function isAnnotatedAllowedType(
  * @remarks
  * Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
  * @alpha
+ * @input
  */
 export interface AllowedTypeMetadata {
 	/**
@@ -134,7 +138,34 @@ export interface AllowedTypeMetadata {
 	 */
 	readonly custom?: unknown;
 
-	// TODO metadata for enablable types will be added here
+	/**
+	 * If defined, indicates that an allowed type is {@link SchemaStaticsAlpha.staged | staged}.
+	 */
+	readonly stagedSchemaUpgrade?: SchemaUpgrade;
+}
+
+/**
+ * Package internal {@link SchemaUpgrade} construction API.
+ */
+export let createSchemaUpgrade: () => SchemaUpgrade;
+
+/**
+ * Unique token used to upgrade schemas and determine if a particular upgrade has been completed.
+ * @remarks
+ * Create using {@link SchemaStaticsAlpha.staged}.
+ * @privateRemarks
+ * TODO:#38722 implement runtime schema upgrades.
+ * Until then, the class purely behaves mostly as a placeholder.
+ * TODO: Consider allowing users to store a name for the upgrade to use in error messages.
+ * @sealed @alpha
+ */
+export class SchemaUpgrade {
+	protected _typeCheck!: MakeNominal;
+	static {
+		createSchemaUpgrade = () => new SchemaUpgrade();
+	}
+
+	private constructor() {}
 }
 
 /**
@@ -176,6 +207,7 @@ export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
  * Types of {@link TreeNode|TreeNodes} or {@link TreeLeafValue|TreeLeafValues} allowed at a location in a tree with
  * additional metadata associated with the location they're allowed at.
  * @alpha
+ * @input
  */
 export type ImplicitAnnotatedAllowedTypes =
 	| TreeNodeSchema
@@ -191,12 +223,21 @@ export type UnannotateImplicitAllowedTypes<T extends ImplicitAnnotatedAllowedTyp
 	T extends AnnotatedAllowedTypes
 		? UnannotateAllowedTypes<T>
 		: T extends AnnotatedAllowedType
-			? UnannotateAllowedType<T>
+			? UnannotateAllowedTypesList<[T]>
 			: T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]
 				? UnannotateAllowedTypesList<T>
-				: T extends TreeNodeSchema
+				: // This should able to just return `T` here, however doing so breaks generic code in ArrayNode.
+					T extends TreeNodeSchema
 					? T
-					: never;
+					: // Ideally this case would not be hit as it should be impossible.
+						// Due to limitations of TypeScript some generic code does depend on this case,
+						// so return a valid nonspecific schema in this otherwise unreachable case.
+						// This ensures that when this case is hit, the type system can still reason about it.
+						// It also ensures that if bugs cause this to matter in other cases, they will err on the side of restricting the API
+						// (due to non-specific schema) rather than being unsafe.
+						// This helps any such bugs be noticed more easily, be less likely to lead to runtime errors,
+						// and be more likely to be fixable as non-breaking changes.
+						ImplicitAllowedTypes;
 
 /**
  * Removes annotations from a list of allowed types that may contain annotations.
@@ -205,17 +246,9 @@ export type UnannotateImplicitAllowedTypes<T extends ImplicitAnnotatedAllowedTyp
 export type UnannotateAllowedTypesList<
 	T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
 > = {
-	[I in keyof T]: UnannotateAllowedTypeOrLazyItem<T[I]>;
+	[I in keyof T]: UnannotateAllowedType<T[I]>;
 };
 
-/**
- * Removes annotations from an allowed type that may contain annotations.
- * @system @alpha
- */
-export type UnannotateAllowedTypeOrLazyItem<
-	T extends AnnotatedAllowedType | LazyItem<TreeNodeSchema>,
-> = T extends AnnotatedAllowedType<infer X> ? X : T;
-
 /**
  * Removes all annotations from a set of allowed types.
  * @system @alpha
@@ -225,10 +258,15 @@ export type UnannotateAllowedTypes<T extends AnnotatedAllowedTypes> =
 
 /**
  * Removes annotations from an allowed type.
+ * @remarks
+ * If the input could be lazy
+ * (is a LazyItem or AnnotatedAllowedType<LazyItem> instead of just a TreeNodeSchema | AnnotatedAllowedType<TreeNodeSchema>)
+ * then the output of this will be a LazyItem and thus is not valid as an ImplicitAllowedTypes without wrapping it in an array.
+ * This can however be used on items within an AllowedTypes array.
  * @system @alpha
  */
 export type UnannotateAllowedType<T extends AnnotatedAllowedType | LazyItem<TreeNodeSchema>> =
-	T extends AnnotatedAllowedType<infer X> ? [X] : T;
+	T extends AnnotatedAllowedType<infer X> ? X : T;
 
 /**
  * Normalizes a {@link ImplicitAllowedTypes} to a set of {@link TreeNodeSchema}s, by eagerly evaluating any
@@ -258,22 +296,13 @@ export function normalizeAllowedTypes(
 }
 
 /**
- * Normalizes an allowed type to an {@link AnnotatedAllowedType}, by adding empty annotations if they don't already exist
- * and eagerly evaluating any lazy schema declarations.
- *
- * @remarks
- * Note: this must only be called after all required schemas have been declared, otherwise evaluation of
- * recursive schemas may fail.
- * type is frozen and should not be modified after being passed in.
+ * Normalizes an allowed type to an {@link AnnotatedAllowedType}, by adding empty annotations if they don't already exist.
  */
-export function normalizeToAnnotatedAllowedType<T extends TreeNodeSchema>(
-	type: T | AnnotatedAllowedType<T> | AnnotatedAllowedType<LazyItem<T>>,
+export function normalizeToAnnotatedAllowedType<T extends LazyItem<TreeNodeSchema>>(
+	type: T | AnnotatedAllowedType<T>,
 ): AnnotatedAllowedType<T> {
 	return isAnnotatedAllowedType(type)
-		? {
-				metadata: type.metadata,
-				type: evaluateLazySchema(type.type),
-			}
+		? type
 		: {
 				metadata: {},
 				type,
@@ -375,7 +404,7 @@ export function evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>)
  * Throws a UsageError if the provided schema is undefined, most likely due to being used before it was initialized.
  */
 export function checkForUninitializedSchema(
-	schema: ImplicitAnnotatedAllowedTypes | LazyItem<TreeNodeSchema>,
+	schema: ImplicitAnnotatedAllowedTypes | LazyItem<TreeNodeSchema> | AnnotatedAllowedType,
 ): void {
 	if (schema === undefined) {
 		throw new UsageError(

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

@@ -57,6 +57,8 @@ export {
 	unannotateImplicitAllowedTypes,
 	markSchemaMostDerived,
 	evaluateLazySchema,
+	createSchemaUpgrade,
+	type SchemaUpgrade,
 } from "./allowedTypes.js";
 export type {
 	AnnotatedAllowedType,
@@ -73,7 +75,6 @@ export type {
 	UnannotateAllowedTypes,
 	UnannotateAllowedType,
 	UnannotateAllowedTypesList,
-	UnannotateAllowedTypeOrLazyItem,
 	AllowedTypeMetadata,
 	AnnotatedAllowedTypes,
 } from "./allowedTypes.js";
@@ -101,4 +102,11 @@ export {
 	TreeNodeValid,
 	type MostDerivedData,
 	createTreeNodeSchemaPrivateData,
+	isClassBasedSchema,
 } from "./treeNodeValid.js";
+export type { SimpleNodeSchemaBase } from "./simpleNodeSchemaBase.js";
+export {
+	type StoredSchemaGenerationOptions,
+	convertAllowedTypes,
+	allowedTypeFilter,
+} from "./toStored.js";

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

@@ -0,0 +1,30 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { NodeKind, NodeSchemaMetadata } from "./treeNodeSchema.js";
+
+/**
+ * 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<
+	out TNodeKind extends NodeKind,
+	out TCustomMetadata = unknown,
+> {
+	/**
+	 * The {@link NodeKind}.
+	 *
+	 * @remarks can be used to type-switch between implementations.
+	 */
+	readonly kind: TNodeKind;
+
+	/**
+	 * User-provided {@link NodeSchemaMetadata} for this schema.
+	 */
+	readonly metadata: NodeSchemaMetadata<TCustomMetadata>;
+}