@fluidframework/tree 2.23.0 → 2.31.0

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:
@@ -51,13 +53,17 @@ export type Unenforced<_DesiredExtendsConstraint> = unknown;
 /**
  * {@link Unenforced} version of `ObjectFromSchemaRecord`.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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
@@ -121,24 +135,24 @@ export interface TreeNodeSchemaNonClassUnsafe<
 /**
  * {@link Unenforced} version of {@link TreeObjectNode}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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 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}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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,14 +164,43 @@ 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
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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 TreeNodeFromImplicitAllowedTypesUnsafe<
-	TSchema extends Unenforced<ImplicitAllowedTypes>,
+	TSchema extends ImplicitAllowedTypesUnsafe,
 > = TSchema extends TreeNodeSchemaUnsafe
 	? NodeFromSchemaUnsafe<TSchema>
 	: TSchema extends AllowedTypesUnsafe
@@ -168,11 +211,11 @@ export type TreeNodeFromImplicitAllowedTypesUnsafe<
  * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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 InsertableTreeNodeFromImplicitAllowedTypesUnsafe<
-	TSchema extends Unenforced<ImplicitAllowedTypes>,
+	TSchema extends ImplicitAllowedTypesUnsafe,
 > = [TSchema] extends [TreeNodeSchemaUnsafe]
 	? InsertableTypedNodeUnsafe<TSchema>
 	: [TSchema] extends [AllowedTypesUnsafe]
@@ -184,20 +227,19 @@ 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}.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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
  * TODO:
  * This is less strict than InsertableTypedNode when given non-exact schema to avoid compilation issues.
@@ -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>
@@ -216,7 +258,7 @@ export type InsertableTypedNodeUnsafe<
 /**
  * {@link Unenforced} version of {@link NodeFromSchema}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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 NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> =
@@ -225,7 +267,7 @@ export type NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> =
 /**
  * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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 NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =
@@ -234,10 +276,10 @@ export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =
 /**
  * {@link Unenforced} version of {@link (TreeArrayNode:interface)}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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>,
@@ -247,10 +289,10 @@ export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAl
 /**
  * {@link Unenforced} version of {@link TreeMapNode}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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 {
 	/**
@@ -271,14 +313,14 @@ export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
  * Copy of TypeScript's ReadonlyMap, but with `TreeNodeFromImplicitAllowedTypesUnsafe<T>` inlined into it.
  * Using this instead of ReadonlyMap in TreeMapNodeUnsafe is necessary to make recursive map schema not generate compile errors in the d.ts files when exported.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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 is the same as `ReadonlyMap<K, TreeNodeFromImplicitAllowedTypesUnsafe<T>>` (Checked in test),
  * except that it avoids the above mentioned compile error.
  * 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>]>;
 
@@ -313,13 +355,13 @@ export interface ReadonlyMapInlined<K, T extends Unenforced<ImplicitAllowedTypes
 /**
  * {@link Unenforced} version of `FieldHasDefault`.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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;
@@ -328,33 +370,33 @@ export type FieldHasDefaultUnsafe<T extends Unenforced<ImplicitFieldSchema>> =
  * {@link Unenforced} version of `InsertableObjectFromSchemaRecord`.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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 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]>;
 };
 
 /**
  * {@link Unenforced} version of {@link InsertableTreeFieldFromImplicitField}.
  * @see {@link Input}
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * 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 InsertableTreeFieldFromImplicitFieldUnsafe<
-	TSchemaInput extends Unenforced<ImplicitFieldSchema>,
+	TSchemaInput extends ImplicitFieldSchemaUnsafe,
 	TSchema = UnionToIntersection<TSchemaInput>,
 > = [TSchema] extends [FieldSchemaUnsafe<infer Kind, infer Types>]
 	? ApplyKindInput<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<Types>, Kind, true>
@@ -365,13 +407,14 @@ export type InsertableTreeFieldFromImplicitFieldUnsafe<
 /**
  * {@link Unenforced} version of {@link FieldSchema}.
  * @remarks
- * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
- * @public
+ * 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 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,
@@ -39,9 +39,10 @@ import {
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
 import {
 	customFromCursor,
+	replaceHandles,
 	type CustomTreeNode,
-	type CustomTreeValue,
 	type EncodeOptions,
+	type HandleConverter,
 } from "./customTree.js";
 import { getUnhydratedContext } from "../createContext.js";
 
@@ -110,20 +111,10 @@ export interface VerboseTreeNode<THandle = IFluidHandle> {
 }
 
 /**
- * Options for how to interpret a `VerboseTree<TCustom>` when schema information is available.
+ * Options for how to interpret a `VerboseTree` when schema information is available.
  * @alpha
  */
-export interface ParseOptions<TCustom> {
-	/**
-	 * Fixup custom input formats.
-	 * @remarks
-	 * Main usage is to handle IFluidHandles.
-	 * When targeting JSON compatibility,
-	 * this may be by throwing an error or including a placeholder.
-	 * Since IFluidHandles are special references to FLuid data which is garbage collected when not referenced by the container for long enough,
-	 * any scheme for encoding handles for storage outside the container (or in formats the container does not understand) is unreliable.
-	 */
-	valueConverter(data: VerboseTree<TCustom>): TreeLeafValue | VerboseTreeNode<TCustom>;
+export interface ParseOptions {
 	/**
 	 * If true, interpret the input keys of object nodes as stored keys.
 	 * If false, interpret them as property keys.
@@ -133,15 +124,9 @@ export interface ParseOptions<TCustom> {
 }
 
 /**
- * Options for how to interpret a `VerboseTree<TCustom>` without relying on schema.
+ * Options for how to interpret a `VerboseTree` without relying on schema.
  */
-export interface SchemalessParseOptions<TCustom> {
-	/**
-	 * Fixup custom input formats.
-	 * @remarks
-	 * See note on {@link ParseOptions.valueConverter}.
-	 */
-	valueConverter(data: VerboseTree<TCustom>): TreeLeafValue | VerboseTreeNode<TCustom>;
+export interface SchemalessParseOptions {
 	/**
 	 * Converts stored keys into whatever key the tree is using in its encoding.
 	 */
@@ -154,11 +139,11 @@ export interface SchemalessParseOptions<TCustom> {
 /**
  * Use info from `schema` to convert `options` to {@link SchemalessParseOptions}.
  */
-export function applySchemaToParserOptions<TCustom>(
+export function applySchemaToParserOptions(
 	schema: ImplicitFieldSchema,
-	options: ParseOptions<TCustom>,
-): SchemalessParseOptions<TCustom> {
-	const config: Required<ParseOptions<TCustom>> = {
+	options: ParseOptions,
+): SchemalessParseOptions {
+	const config: Required<ParseOptions> = {
 		useStoredKeys: false,
 		...options,
 	};
@@ -166,7 +151,6 @@ export function applySchemaToParserOptions<TCustom>(
 	const context = getUnhydratedContext(schema);
 
 	return {
-		valueConverter: config.valueConverter,
 		keyConverter: config.useStoredKeys
 			? undefined
 			: {
@@ -213,9 +197,9 @@ export function applySchemaToParserOptions<TCustom>(
  *
  * @returns an {@link ITreeCursorSynchronous} for a single node in nodes mode.
  */
-export function cursorFromVerbose<TCustom>(
-	data: VerboseTree<TCustom>,
-	options: SchemalessParseOptions<TCustom>,
+export function cursorFromVerbose(
+	data: VerboseTree,
+	options: SchemalessParseOptions,
 ): ITreeCursorSynchronous {
 	return stackTreeNodeCursor(verboseTreeAdapter(options), data);
 }
@@ -225,9 +209,9 @@ export function cursorFromVerbose<TCustom>(
  *
  * @returns an {@link ITreeCursorSynchronous} for a single field in fields mode.
  */
-export function fieldCursorFromVerbose<TCustom>(
-	data: VerboseTree<TCustom>[],
-	options: SchemalessParseOptions<TCustom>,
+export function fieldCursorFromVerbose(
+	data: VerboseTree[],
+	options: SchemalessParseOptions,
 ): ITreeCursorSynchronous {
 	return stackTreeFieldCursor(
 		verboseTreeAdapter(options),
@@ -236,16 +220,12 @@ export function fieldCursorFromVerbose<TCustom>(
 	);
 }
 
-function verboseTreeAdapter<TCustom>(
-	options: SchemalessParseOptions<TCustom>,
-): CursorAdapter<VerboseTree<TCustom>> {
+function verboseTreeAdapter(options: SchemalessParseOptions): CursorAdapter<VerboseTree> {
 	return {
-		value: (input: VerboseTree<TCustom>) => {
-			const node = options.valueConverter(input);
+		value: (node: VerboseTree) => {
 			return isTreeValue(node) ? node : undefined;
 		},
-		type: (input: VerboseTree<TCustom>) => {
-			const node = options.valueConverter(input);
+		type: (node: VerboseTree) => {
 			switch (typeof node) {
 				case "number":
 					return numberSchema.identifier as TreeNodeSchemaIdentifier;
@@ -263,8 +243,7 @@ function verboseTreeAdapter<TCustom>(
 					return node.type as TreeNodeSchemaIdentifier;
 			}
 		},
-		keysFromNode: (input: VerboseTree<TCustom>): readonly FieldKey[] => {
-			const node = options.valueConverter(input);
+		keysFromNode: (node: VerboseTree): readonly FieldKey[] => {
 			switch (typeof node) {
 				case "object": {
 					if (node === null) {
@@ -288,11 +267,7 @@ function verboseTreeAdapter<TCustom>(
 					return [];
 			}
 		},
-		getFieldFromNode: (
-			input: VerboseTree<TCustom>,
-			key: FieldKey,
-		): readonly VerboseTree<TCustom>[] => {
-			const node = options.valueConverter(input);
+		getFieldFromNode: (node: VerboseTree, key: FieldKey): readonly VerboseTree[] => {
 			// Object.prototype.hasOwnProperty can return true for strings (ex: with key "0"), so we have to filter them out.
 			// Rather than just special casing strings, we can handle them with an early return for all primitives.
 			if (typeof node !== "object") {
@@ -327,12 +302,12 @@ function verboseTreeAdapter<TCustom>(
 /**
  * Used to read a node cursor as a VerboseTree.
  */
-export function verboseFromCursor<TCustom>(
+export function verboseFromCursor(
 	reader: ITreeCursor,
 	rootSchema: ImplicitAllowedTypes,
-	options: EncodeOptions<TCustom>,
-): VerboseTree<TCustom> {
-	const config: Required<EncodeOptions<TCustom>> = {
+	options: EncodeOptions,
+): VerboseTree {
+	const config: Required<EncodeOptions> = {
 		useStoredKeys: false,
 		...options,
 	};
@@ -342,20 +317,33 @@ export function verboseFromCursor<TCustom>(
 	return verboseFromCursorInner(reader, config, schemaMap);
 }
 
-function verboseFromCursorInner<TCustom>(
+function verboseFromCursorInner(
 	reader: ITreeCursor,
-	options: Required<EncodeOptions<TCustom>>,
+	options: Required<EncodeOptions>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
-): VerboseTree<TCustom> {
+): VerboseTree {
 	const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);
 	const nodeSchema =
 		schema.get(reader.type) ?? fail(0xb3c /* missing schema for type in cursor */);
 	if (nodeSchema.kind === NodeKind.Leaf) {
-		return fields as CustomTreeValue<TCustom>;
+		return fields as TreeLeafValue;
 	}
 
 	return {
 		type: reader.type,
-		fields: fields as CustomTreeNode<TCustom>,
+		fields: fields as CustomTreeNode<VerboseTree>,
 	};
 }
+
+/**
+ * Clones tree, replacing any handles.
+ * @remarks
+ * A strongly types version of {@link replaceHandles}.
+ * @alpha
+ */
+export function replaceVerboseTreeHandles<T>(
+	tree: VerboseTree,
+	replacer: HandleConverter<T>,
+): VerboseTree<T> {
+	return replaceHandles(tree, replacer) as VerboseTree<T>;
+}

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";
 
 /**