@fluidframework/tree 2.52.0 → 2.53.0-350190

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,
@@ -134,7 +139,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() {}
 }
 
 /**
@@ -191,7 +223,7 @@ 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
@@ -205,17 +237,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 +249,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 +287,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,

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>;
+}

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

@@ -0,0 +1,58 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { brand } from "../../util/index.js";
+import {
+	normalizeAnnotatedAllowedTypes,
+	type AnnotatedAllowedType,
+	type ImplicitAnnotatedAllowedTypes,
+	type SchemaUpgrade,
+} from "./allowedTypes.js";
+import type { TreeNodeSchemaIdentifier, TreeTypeSet } from "../../core/index.js";
+
+/**
+ * Options for generating a {@link TreeStoredSchema} from view schema.
+ */
+export interface StoredSchemaGenerationOptions {
+	/**
+	 * Determines whether to include staged schema in the resulting stored schema.
+	 * @remarks
+	 * Due to caching, the behavior of this function must be pure.
+	 */
+	includeStaged(upgrade: SchemaUpgrade): boolean;
+}
+
+/**
+ * Filters an allowed type based on the provided options.
+ * @param allowedType - The allowed type to filter.
+ * @param options - The options to use for filtering.
+ * @returns Whether the allowed type passes the filter.
+ */
+export function allowedTypeFilter(
+	allowedType: AnnotatedAllowedType,
+	options: StoredSchemaGenerationOptions,
+): boolean {
+	// If the allowed type is staged, only include it if the options allow it.
+	if (allowedType.metadata.stagedSchemaUpgrade !== undefined) {
+		return options.includeStaged(allowedType.metadata.stagedSchemaUpgrade);
+	}
+	return true;
+}
+
+/**
+ * Converts an ImplicitAnnotatedAllowedTypes to a stored schema.
+ * @param schema - The schema to convert.
+ * @param options - The options to use for filtering.
+ * @returns The converted stored schema.
+ */
+export function convertAllowedTypes(
+	schema: ImplicitAnnotatedAllowedTypes,
+	options: StoredSchemaGenerationOptions,
+): TreeTypeSet {
+	const filtered: TreeNodeSchemaIdentifier[] = normalizeAnnotatedAllowedTypes(schema)
+		.types.filter((allowedType) => allowedTypeFilter(allowedType, options))
+		.map((a) => brand(a.type.identifier));
+	return new Set(filtered);
+}

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

@@ -6,7 +6,7 @@
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 
-import type { SimpleNodeSchemaBase } from "../simpleSchema.js";
+import type { SimpleNodeSchemaBase } from "./simpleNodeSchemaBase.js";
 import type { TreeNode } from "./treeNode.js";
 import type { InternalTreeNode, Unhydrated } from "./types.js";
 import type { UnionToIntersection } from "../../util/index.js";
@@ -15,9 +15,10 @@ import type {
 	NormalizedAnnotatedAllowedTypes,
 } from "./allowedTypes.js";
 import type { Context } from "./context.js";
-import type { FieldKey, NodeData } from "../../core/index.js";
+import type { FieldKey, NodeData, TreeNodeStoredSchema } from "../../core/index.js";
 import type { UnhydratedFlexTreeField } from "./unhydratedFlexTree.js";
 import type { FactoryContent } from "../unhydratedFlexTreeFromInsertable.js";
+import type { StoredSchemaGenerationOptions } from "./toStored.js";
 
 /**
  * Schema for a {@link TreeNode} or {@link TreeLeafValue}.
@@ -396,6 +397,11 @@ export interface TreeNodeSchemaPrivateData {
 	 * Idempotent initialization function that pre-caches data and can dereference lazy schema references.
 	 */
 	idempotentInitialize(): TreeNodeSchemaInitializedData;
+
+	/**
+	 * Converts a the schema into a {@link TreeNodeStoredSchema}.
+	 */
+	toStored(options: StoredSchemaGenerationOptions): TreeNodeStoredSchema;
 }
 
 /**

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

@@ -27,6 +27,7 @@ import {
 import type { InternalTreeNode } from "./types.js";
 import { typeSchemaSymbol } from "./withType.js";
 import type { ImplicitAnnotatedAllowedTypes } from "./allowedTypes.js";
+import type { SimpleNodeSchemaBase } from "./simpleNodeSchemaBase.js";
 
 /**
  * Class which all {@link TreeNode}s must extend.
@@ -233,7 +234,7 @@ export interface MostDerivedData {
 export function schemaAsTreeNodeValid(
 	schema: TreeNodeSchemaCore<string, NodeKind, boolean>,
 ): typeof TreeNodeValid & TreeNodeSchema {
-	if (!inPrototypeChain(schema, TreeNodeValid)) {
+	if (!isClassBasedSchema(schema)) {
 		// Use JSON.stringify to quote and escape identifier string.
 		throw new UsageError(
 			`Schema for ${JSON.stringify(
@@ -242,7 +243,16 @@ export function schemaAsTreeNodeValid(
 		);
 	}
 
-	return schema as typeof TreeNodeValid & TreeNodeSchema;
+	return schema;
+}
+
+/**
+ * Check if a schema is a {@link TreeNodeValid}.
+ */
+export function isClassBasedSchema(
+	schema: SimpleNodeSchemaBase<NodeKind>,
+): schema is typeof TreeNodeValid & TreeNodeSchema {
+	return inPrototypeChain(schema, TreeNodeValid);
 }
 
 /**
@@ -253,6 +263,7 @@ export function schemaAsTreeNodeValid(
 export function createTreeNodeSchemaPrivateData(
 	schema: TreeNodeSchemaCore<string, NodeKind, boolean>,
 	childAnnotatedAllowedTypes: readonly ImplicitAnnotatedAllowedTypes[],
+	toStored: TreeNodeSchemaPrivateData["toStored"],
 ): TreeNodeSchemaPrivateData {
 	const schemaValid = schemaAsTreeNodeValid(schema);
 	// Since this closes over the schema, ensure this schema is marked as most derived
@@ -262,6 +273,7 @@ export function createTreeNodeSchemaPrivateData(
 	return {
 		idempotentInitialize: () => schemaValid.oneTimeInitialize().oneTimeInitialized,
 		childAnnotatedAllowedTypes,
+		toStored,
 	};
 }