@fluidframework/tree 2.90.0-378676 → 2.91.0

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

@@ -4,20 +4,27 @@
  */
 
 import type { RestrictiveStringRecord } from "../../util/index.js";
-import type {
-	NodeKind,
-	TreeNodeSchemaClass,
-	ImplicitAllowedTypes,
-	WithType,
+import {
+	type NodeKind,
+	type TreeNodeSchemaClass,
+	type ImplicitAllowedTypes,
+	type WithType,
+	normalizeAllowedTypes,
+	isTreeNode,
 } from "../core/index.js";
-import type { ImplicitFieldSchema } from "../fieldSchema.js";
 // These imports prevent a large number of type references in the API reports from showing up as *_2.
 /* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */
-import type {
-	FieldProps,
-	FieldSchemaAlpha,
-	FieldPropsAlpha,
-	FieldKind,
+import {
+	type FieldProps,
+	type FieldSchemaAlpha,
+	type FieldPropsAlpha,
+	type FieldKind,
+	type ImplicitFieldSchema,
+	type InsertableTreeFieldFromImplicitField,
+	type FieldSchema,
+	getDefaultProvider,
+	createFieldSchema,
+	type DefaultProvider,
 } from "../fieldSchema.js";
 import type { LeafSchema } from "../leafNodeSchema.js";
 import {
@@ -26,12 +33,14 @@ import {
 	type MapNodeCustomizableSchema,
 	mapSchema,
 	type ObjectNodeSchema,
+	type ObjectNodeSchemaWorkaround,
 	objectSchema,
 	type RecordNodeCustomizableSchema,
 	recordSchema,
 } from "../node-kinds/index.js";
 import type { SchemaType, SimpleObjectNodeSchema } from "../simpleSchema.js";
 import type { SimpleLeafNodeSchema } from "../simpleSchema.js";
+import { unhydratedFlexTreeFromInsertableNode } from "../unhydratedFlexTreeFromInsertable.js";
 
 import {
 	defaultSchemaFactoryObjectOptions,
@@ -42,15 +51,185 @@ import {
 } from "./schemaFactory.js";
 import { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
 import { schemaStatics } from "./schemaStatics.js";
+import { TreeBeta } from "./treeBeta.js";
 import type {
 	ArrayNodeCustomizableSchemaUnsafe,
+	FieldSchemaAlphaUnsafe,
+	InsertableObjectFromSchemaRecordAlphaUnsafe,
 	MapNodeCustomizableSchemaUnsafe,
 	System_Unsafe,
 	TreeRecordNodeUnsafe,
+	Unenforced,
 } from "./typesUnsafe.js";
-import type { FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
 /* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */
 
+/**
+ * A provider for values in tree nodes.
+ *
+ * @remarks
+ * This type represents two ways to provide node values:
+ *
+ * 1. **A value**: Provide any value directly (number, string, object, array, etc.). When a value is provided,
+ * the data is copied for each use to ensure independence between instances. The value must be of an allowed type for the field.
+ *
+ * 2. **A generator function**: A function that returns a value. The function is called each time a default is needed,
+ * allowing for dynamic defaults or explicit control over value creation. The return value must be of an allowed type for the field.
+ *
+ * Values should be preferred over generator functions when possible, as they are simpler and more efficient.
+ * Generator functions should be used when the default value needs to be dynamic or when it is not possible to provide a value directly.
+ *
+ * @example
+ * ```typescript
+ * // Provide a value directly
+ * factory.withDefault(factory.required(factory.string), "default")
+ * factory.withDefault(factory.optional(Person), new Person({ name: "Guest" }))
+ *
+ * // Use a generator function
+ * factory.withDefault(factory.required(factory.string), () => crypto.randomUUID())
+ * factory.withDefault(factory.optional(Person), () => new Person({ name: "Guest" }))
+ * ```
+ *
+ * @alpha @sealed
+ */
+export type NodeProvider<T> = T | (() => T);
+
+/**
+ * Stateless APIs exposed via {@link SchemaFactoryBeta} as both instance properties and as statics.
+ * @see {@link SchemaStatics} for why this is useful.
+ * @system @sealed @alpha
+ */
+export interface SchemaStaticsAlpha {
+	/**
+	 * Creates a field schema with a default value. Fields with defaults (whether required or optional) are recognized by the type system as optional in constructors,
+	 * allowing them to be omitted when creating new nodes.
+	 *
+	 * @param fieldSchema - The field schema to add a default to (e.g., `factory.required(factory.string)` or `factory.optional(factory.number)`)
+	 * @param defaultValue - A {@link NodeProvider} specifying the default value.
+	 *
+	 * @example
+	 * ```typescript
+	 * const MySchema = factory.objectAlpha("MyObject", {
+	 *     // Provide values directly
+	 *     name: factory.withDefault(factory.required(factory.string), "untitled"),
+	 *     count: factory.withDefault(factory.required(factory.number), 0),
+	 *     metadata: factory.withDefault(factory.optional(Metadata), new Metadata({ version: 1 })),
+	 *
+	 *     // Use generator functions for dynamic values
+	 *     timestamp: factory.withDefault(factory.required(factory.number), () => Date.now()),
+	 *     id: factory.withDefault(factory.required(factory.string), () => crypto.randomUUID()),
+	 * });
+	 *
+	 * const obj1 = new MySchema({}); // All defaults applied
+	 * const obj2 = new MySchema({ name: "custom" }); // name="custom", other defaults applied
+	 * ```
+	 *
+	 * @privateRemarks
+	 * This function wraps an existing field schema and adds a default value provider to it.
+	 * The default value will be used when constructing nodes if the field is not explicitly provided or set to `undefined`.
+	 *
+	 * Defaults are evaluated eagerly during node construction, unlike identifier defaults which require context.
+	 */
+	readonly withDefault: <
+		Kind extends FieldKind,
+		Types extends ImplicitAllowedTypes,
+		TCustomMetadata = unknown,
+	>(
+		fieldSchema: FieldSchema<Kind, Types, TCustomMetadata>,
+		defaultValue: NodeProvider<InsertableTreeFieldFromImplicitField<FieldSchema<Kind, Types>>>,
+	) => FieldSchemaAlpha<
+		Kind,
+		Types,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }
+	>;
+	/**
+	 * {@link SchemaStaticsAlpha.withDefault} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStaticsAlpha.withDefault} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 */
+	withDefaultRecursive: <
+		Kind extends FieldKind,
+		Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+		TCustomMetadata = unknown,
+	>(
+		fieldSchema: System_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata>,
+		defaultValue: Unenforced<
+			NodeProvider<
+				System_Unsafe.InsertableTreeFieldFromImplicitFieldUnsafe<
+					System_Unsafe.FieldSchemaUnsafe<Kind, Types>
+				>
+			>
+		>,
+	) => FieldSchemaAlphaUnsafe<
+		Kind,
+		Types,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }
+	>;
+}
+
+const withDefault = <
+	Kind extends FieldKind,
+	Types extends ImplicitAllowedTypes,
+	TCustomMetadata = unknown,
+>(
+	fieldSchema: FieldSchema<Kind, Types, TCustomMetadata>,
+	defaultValue: NodeProvider<InsertableTreeFieldFromImplicitField<FieldSchema<Kind, Types>>>,
+): FieldSchemaAlpha<
+	Kind,
+	Types,
+	TCustomMetadata,
+	FieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }
+> => {
+	const typedFieldSchema = fieldSchema as FieldSchemaAlpha<Kind, Types, TCustomMetadata>;
+
+	// create the default provider function, it is called eagerly during node construction
+	const defaultProvider = getDefaultProvider(() => {
+		// Resolve the value: if it's a function, call it; otherwise use it directly
+		let insertableValue =
+			typeof defaultValue === "function" ? (defaultValue as () => unknown)() : defaultValue;
+
+		// If the value is an already-constructed TreeNode (e.g., from a generator function that
+		// returns the same instance repeatedly), clone it to ensure each use gets a fresh instance.
+		// This prevents multi-parenting errors.
+		if (isTreeNode(insertableValue)) {
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			insertableValue = TreeBeta.clone(insertableValue as any);
+		}
+
+		// For optional fields with an undefined default, return an empty array (no value).
+		if (insertableValue === undefined) {
+			return [];
+		}
+
+		// Convert the insertable value to an unhydrated flex tree.
+		// For insertable data, this creates a fresh tree structure.
+		const allowedTypeSet = normalizeAllowedTypes(typedFieldSchema.allowedTypes).evaluateSet();
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		return [unhydratedFlexTreeFromInsertableNode(insertableValue as any, allowedTypeSet)];
+	});
+
+	// create a new field schema with the default provider
+	const propsWithDefault = {
+		...typedFieldSchema.props,
+		defaultProvider,
+	};
+
+	return createFieldSchema(
+		typedFieldSchema.kind,
+		typedFieldSchema.allowedTypes,
+		propsWithDefault,
+	);
+};
+
+const schemaStaticsAlpha: SchemaStaticsAlpha = {
+	withDefault,
+
+	withDefaultRecursive: withDefault as SchemaStaticsAlpha["withDefaultRecursive"],
+};
+
 /**
  * {@link SchemaFactory} with additional alpha APIs.
  *
@@ -79,19 +258,7 @@ export class SchemaFactoryAlpha<
 		name: Name,
 		fields: T,
 		options?: ObjectSchemaOptionsAlpha<TCustomMetadata>,
-	): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> & {
-		/**
-		 * Typing checking workaround: not for for actual use.
-		 * @remarks
-		 * This API collides with {@link TreeNodeSchemaCore.createFromInsertable} to disable a type checking optimization which produces different and undesired results.
-		 * See {@link https://github.com/microsoft/TypeScript/issues/59049#issuecomment-2773459693} for more details.
-		 * @privateRemarks
-		 * The specific issue here is non-empty POJO mode object schema not being assignable to `ObjectNodeSchema`,
-		 * See the above link and the tests in objectNode.spec.ts which reference it.
-		 * @system
-		 */
-		readonly createFromInsertable: unknown;
-	} {
+	): ObjectNodeSchemaWorkaround<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
 		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {
 			...defaultSchemaFactoryObjectOptions,
 			...options,
@@ -154,6 +321,56 @@ export class SchemaFactoryAlpha<
 			>;
 	}
 
+	/**
+	 * Alpha version of {@link SchemaFactory.objectRecursive} that supports field defaults via {@link SchemaStaticsAlpha.withDefaultRecursive}.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * Use this instead of {@link SchemaFactory.objectRecursive} when fields use {@link SchemaStaticsAlpha.withDefaultRecursive}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 */
+	public objectRecursiveAlpha<
+		const Name extends TName,
+		const T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,
+		const TCustomMetadata = unknown,
+	>(
+		name: Name,
+		t: T,
+		options?: ObjectSchemaOptionsAlpha<TCustomMetadata>,
+	): TreeNodeSchemaClass<
+		ScopedSchemaName<TScope, Name>,
+		NodeKind.Object,
+		System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,
+		object & InsertableObjectFromSchemaRecordAlphaUnsafe<T>,
+		false,
+		T,
+		never,
+		TCustomMetadata
+	> &
+		SimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> &
+		Pick<ObjectNodeSchema, "fields"> {
+		type TScopedName = ScopedSchemaName<TScope, Name>;
+		return this.objectAlpha(
+			name,
+			t as T & RestrictiveStringRecord<ImplicitFieldSchema>,
+			options,
+		) as unknown as TreeNodeSchemaClass<
+			TScopedName,
+			NodeKind.Object,
+			System_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,
+			object & InsertableObjectFromSchemaRecordAlphaUnsafe<T>,
+			false,
+			T,
+			never,
+			TCustomMetadata
+		> &
+			ObjectNodeSchema<
+				ScopedSchemaName<TScope, Name>,
+				RestrictiveStringRecord<ImplicitFieldSchema>,
+				false,
+				TCustomMetadata
+			>;
+	}
+
 	/**
 	 * {@inheritDoc SchemaStatics.leaves}
 	 */
@@ -209,6 +426,26 @@ export class SchemaFactoryAlpha<
 	 */
 	public override readonly requiredRecursive = schemaStatics.requiredRecursive;
 
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.withDefault}
+	 */
+	public readonly withDefault = schemaStaticsAlpha.withDefault;
+
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.withDefault}
+	 */
+	public static readonly withDefault = schemaStaticsAlpha.withDefault;
+
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.withDefault}
+	 */
+	public readonly withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;
+
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.withDefault}
+	 */
+	public static readonly withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;
+
 	/**
 	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
 	 *

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

@@ -263,7 +263,16 @@ export class SchemaFactoryBeta<
 		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {
 			...defaultSchemaFactoryObjectOptions,
 			...options,
-		});
+		}) as TreeNodeSchemaClass<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Object,
+			TreeObjectNode<T, ScopedSchemaName<TScope, Name>>,
+			object & InsertableObjectFromSchemaRecord<T>,
+			true,
+			T,
+			never,
+			TCustomMetadata
+		>;
 	}
 
 	public override objectRecursive<

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

@@ -6,13 +6,15 @@
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 
 import type { ImplicitAllowedTypes } from "../core/index.js";
-import { FieldKind, getDefaultProvider, createFieldSchema } from "../fieldSchema.js";
-import type {
-	FieldProps,
-	FieldSchema,
-	DefaultProvider,
-	FieldPropsAlpha,
-	FieldSchemaAlpha,
+import {
+	FieldKind,
+	getDefaultProvider,
+	createFieldSchema,
+	type FieldProps,
+	type DefaultProvider,
+	type FieldPropsAlpha,
+	type FieldSchema,
+	type FieldSchemaAlpha,
 } from "../fieldSchema.js";
 import type { LeafSchema } from "../leafNodeSchema.js";
 import {
@@ -180,7 +182,12 @@ export const schemaStaticsStable = {
 	optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 		t: T,
 		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-	): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata> => {
+	): FieldSchemaAlpha<
+		FieldKind.Optional,
+		T,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata>
+	> => {
 		return createFieldSchema(FieldKind.Optional, t, {
 			defaultProvider: defaultOptionalProvider,
 			...props,
@@ -190,8 +197,13 @@ export const schemaStaticsStable = {
 	required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 		t: T,
 		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-	): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata> => {
-		return createFieldSchema(FieldKind.Required, t, props);
+	): FieldSchemaAlpha<
+		FieldKind.Required,
+		T,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata>
+	> => {
+		return createFieldSchema(FieldKind.Required, t, { defaultProvider: undefined, ...props });
 	},
 
 	optionalRecursive: <
@@ -200,7 +212,12 @@ export const schemaStaticsStable = {
 	>(
 		t: T,
 		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-	): FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata> => {
+	): FieldSchemaAlphaUnsafe<
+		FieldKind.Optional,
+		T,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata>
+	> => {
 		return createFieldSchemaUnsafe(FieldKind.Optional, t, {
 			defaultProvider: defaultOptionalProvider,
 			...props,
@@ -213,8 +230,16 @@ export const schemaStaticsStable = {
 	>(
 		t: T,
 		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-	): FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata> => {
-		return createFieldSchemaUnsafe(FieldKind.Required, t, props);
+	): FieldSchemaAlphaUnsafe<
+		FieldKind.Required,
+		T,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata>
+	> => {
+		return createFieldSchemaUnsafe(FieldKind.Required, t, {
+			defaultProvider: undefined,
+			...props,
+		});
 	},
 } as const satisfies SchemaStatics;
 
@@ -225,14 +250,37 @@ 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);
+	): FieldSchemaAlpha<
+		FieldKind.Identifier,
+		typeof stringSchema,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata>
+	> => {
+		return createFieldSchema(FieldKind.Identifier, stringSchema, {
+			defaultProvider: undefined,
+			...props,
+		});
 	},
 } as const;
 
 /**
  * {@link Unenforced} version of {@link createFieldSchema}.
  */
+function createFieldSchemaUnsafe<
+	Kind extends FieldKind,
+	Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+	TCustomMetadata = unknown,
+>(kind: Kind, allowedTypes: Types): FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata>;
+function createFieldSchemaUnsafe<
+	Kind extends FieldKind,
+	Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+	TCustomMetadata = unknown,
+	TProps extends FieldProps<TCustomMetadata> = FieldProps<TCustomMetadata>,
+>(
+	kind: Kind,
+	allowedTypes: Types,
+	props: TProps,
+): FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata, TProps>;
 function createFieldSchemaUnsafe<
 	Kind extends FieldKind,
 	Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,
@@ -241,11 +289,21 @@ function createFieldSchemaUnsafe<
 	kind: Kind,
 	allowedTypes: Types,
 	props?: FieldProps<TCustomMetadata>,
-): FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata> {
+): FieldSchemaAlphaUnsafe<
+	Kind,
+	Types,
+	TCustomMetadata,
+	FieldProps<TCustomMetadata> | undefined
+> {
 	// 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>;
+	const schema =
+		props === undefined
+			? createFieldSchema(kind, allowedTypes as ImplicitAllowedTypes & Types)
+			: createFieldSchema(kind, allowedTypes as ImplicitAllowedTypes & Types, props);
+	return schema as FieldSchemaAlphaUnsafe<
+		Kind,
+		Types,
+		TCustomMetadata,
+		FieldProps<TCustomMetadata> | undefined
+	>;
 }

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

@@ -17,7 +17,6 @@ import {
 	type TreeIndexNodes,
 	hasElement,
 	type TreeIndex,
-	type TreeIndexKey,
 	type KeyFinder,
 } from "../../feature-libraries/index.js";
 import type { SchematizingSimpleTreeView } from "../../shared-tree/index.js";
@@ -27,6 +26,7 @@ import {
 	type TreeNode,
 	type TreeNodeSchema,
 	type NodeFromSchema,
+	type TreeLeafValue,
 } from "../core/index.js";
 import type { ImplicitFieldSchema } from "../fieldSchema.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
@@ -35,14 +35,16 @@ import type { TreeView } from "./tree.js";
 import { treeNodeApi } from "./treeNodeApi.js";
 
 /**
- * A {@link TreeIndex} that returns tree nodes given their associated keys.
- *
+ * Value that may be used as keys in a {@link TreeIndex}.
+ * @remarks
+ * This supports values which have value semantics and are compared by value, just like {@link TreeLeafValue}.
+ * This allows using any tree value as a key (for example in an index tracking where those values occur in the tree).
  * @alpha
  */
-export type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey, TValue>;
+export type TreeIndexKey = TreeLeafValue;
 
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema
@@ -52,7 +54,7 @@ export type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey,
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -61,9 +63,10 @@ export function createSimpleTreeIndex<
 	indexer: (schema: TreeNodeSchema) => string | undefined,
 	getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema
@@ -74,7 +77,7 @@ export function createSimpleTreeIndex<
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -85,9 +88,10 @@ export function createSimpleTreeIndex<
 	getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
 	indexableSchema: readonly TSchema[],
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema
@@ -97,7 +101,7 @@ export function createSimpleTreeIndex<
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -106,9 +110,10 @@ export function createSimpleTreeIndex<
 	indexer: Map<TreeNodeSchema, string>,
 	getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema
@@ -119,7 +124,7 @@ export function createSimpleTreeIndex<
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -130,13 +135,14 @@ export function createSimpleTreeIndex<
 	getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
 	indexableSchema: readonly TSchema[],
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -148,7 +154,7 @@ export function createSimpleTreeIndex<
 		| ((nodes: TreeIndexNodes<NodeFromSchema<TreeNodeSchema>>) => TValue),
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
 	indexableSchema?: readonly TreeNodeSchema[],
-): SimpleTreeIndex<TKey, TValue> {
+): TreeIndex<TKey, TValue> {
 	const indexableSchemaMap = new Map<string, TreeNodeSchema>();
 	if (indexableSchema === undefined) {
 		walkFieldSchema(view.schema, {
@@ -214,7 +220,7 @@ export function createSimpleTreeIndex<
 
 	// all the type checking guarantees that we put nodes of the correct type in the index
 	// but it's not captured in the type system
-	return index as SimpleTreeIndex<TKey, TValue>;
+	return index as TreeIndex<TKey, TValue>;
 }
 
 function makeGenericKeyFinder<TKey extends TreeIndexKey>(

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

@@ -167,7 +167,7 @@ export function importCompatibilitySchemaSnapshot(
  * allowing for greater portability and easier testing.
  *
  * @input
- * @alpha
+ * @beta
  */
 export interface SnapshotFileSystem {
 	/**
@@ -245,7 +245,7 @@ export interface CombinedSchemaCompatibilityStatus {
 /**
  * The options for {@link snapshotSchemaCompatibility}.
  * @input
- * @alpha
+ * @beta
  */
 export interface SnapshotSchemaCompatibilityOptions {
 	/**
@@ -447,7 +447,7 @@ export interface SnapshotSchemaCompatibilityOptions {
  * import fs from "node:fs";
  * import path from "node:path";
  *
- * import { snapshotSchemaCompatibility } from "@fluidframework/tree/alpha";
+ * import { snapshotSchemaCompatibility } from "@fluidframework/tree/beta";
  *
  * // The TreeViewConfiguration the application uses, which contains the application's schema.
  * import { treeViewConfiguration } from "./schema.js";
@@ -485,7 +485,7 @@ export interface SnapshotSchemaCompatibilityOptions {
  * but it would be nice to better unify how we do that versioning and format validation with our codecs.
  *
  * See snapshotCompatibilityChecker.example.mts for the large example included above.
- * @alpha
+ * @beta
  */
 export function snapshotSchemaCompatibility(
 	options: SnapshotSchemaCompatibilityOptions,