@fluidframework/tree 2.4.0-297385 → 2.4.0-299374

package/src/simple-tree/arrayNode.ts

@@ -14,11 +14,11 @@ import {
 	isFlexTreeNode,
 } from "../feature-libraries/index.js";
 import { prepareContentForHydration } from "./proxies.js";
-import { getOrCreateInnerNode } from "./proxyBinding.js";
 import {
 	normalizeAllowedTypes,
 	type ImplicitAllowedTypes,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
+	type TreeLeafValue,
 	type TreeNodeFromImplicitAllowedTypes,
 } from "./schemaTypes.js";
 import {
@@ -34,6 +34,8 @@ import {
 	getOrCreateNodeFromInnerNode,
 	type TreeNodeSchemaBoth,
 	getSimpleNodeSchemaFromInnerNode,
+	getOrCreateInnerNode,
+	type TreeNodeSchemaClass,
 } from "./core/index.js";
 import { type InsertableContent, mapTreeFromNodeData } from "./toMapTree.js";
 import { fail } from "../util/index.js";
@@ -45,6 +47,19 @@ import {
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import { getUnhydratedContext } from "./createContext.js";
 
+/**
+ * A covariant base type for {@link (TreeArrayNode:interface)}.
+ *
+ * This provides the readonly subset of TreeArrayNode functionality, and is used as the source interface for moves since that needs to be covariant.
+ * @privateRemarks
+ * Ideally this would just include `TreeNode, WithType<string, NodeKind.Array>` in the extends list but https://github.com/microsoft/TypeScript/issues/16936 prevents that from compiling.
+ * As a workaround around for this TypeScript limitation, the conflicting type intersection is wrapped in `Awaited` (which has no effect on the type in this case) which allows it to compile.
+ * @system @sealed @public
+ */
+export interface ReadonlyArrayNode<out T = TreeNode | TreeLeafValue>
+	extends ReadonlyArray<T>,
+		Awaited<TreeNode & WithType<string, NodeKind.Array>> {}
+
 /**
  * A generic array type, used to defined types like {@link (TreeArrayNode:interface)}.
  *
@@ -53,9 +68,8 @@ import { getUnhydratedContext } from "./createContext.js";
  *
  * @system @sealed @public
  */
-export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom>
-	extends ReadonlyArray<T>,
-		TreeNode {
+export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom = ReadonlyArrayNode>
+	extends ReadonlyArrayNode<T> {
 	/**
 	 * Inserts new item(s) at a specified location.
 	 * @param index - The index at which to insert `value`.
@@ -366,8 +380,7 @@ export interface TreeArrayNode<
 	TAllowedTypes extends ImplicitAllowedTypes = ImplicitAllowedTypes,
 > extends TreeArrayNodeBase<
 		TreeNodeFromImplicitAllowedTypes<TAllowedTypes>,
-		InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>,
-		TreeArrayNode
+		InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
 	> {}
 
 /**
@@ -417,9 +430,7 @@ export class IterableTreeArrayContent<T> implements Iterable<T> {
 /**
  * Given a array node proxy, returns its underlying LazySequence field.
  */
-function getSequenceField<TSimpleType extends ImplicitAllowedTypes>(
-	arrayNode: TreeArrayNode<TSimpleType>,
-): FlexTreeSequenceField {
+function getSequenceField(arrayNode: ReadonlyArrayNode): FlexTreeSequenceField {
 	return getOrCreateInnerNode(arrayNode).getBoxed(EmptyKey) as FlexTreeSequenceField;
 }
 
@@ -799,6 +810,11 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	protected abstract get simpleSchema(): T;
 	protected abstract get allowedTypes(): ReadonlySet<TreeNodeSchema>;
 
+	public abstract override get [typeSchemaSymbol](): TreeNodeSchemaClass<
+		string,
+		NodeKind.Array
+	>;
+
 	public constructor(
 		input: Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>> | InternalTreeNode,
 	) {
@@ -901,13 +917,13 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		}
 		field.editor.remove(removeStart, removeEnd - removeStart);
 	}
-	public moveToStart(sourceIndex: number, source?: TreeArrayNode): void {
+	public moveToStart(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);
 		validateIndex(sourceIndex, sourceField, "moveToStart");
 		this.moveRangeToIndex(0, sourceIndex, sourceIndex + 1, source);
 	}
-	public moveToEnd(sourceIndex: number, source?: TreeArrayNode): void {
+	public moveToEnd(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);
 		validateIndex(sourceIndex, sourceField, "moveToEnd");
@@ -916,7 +932,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	public moveToIndex(
 		destinationGap: number,
 		sourceIndex: number,
-		source?: TreeArrayNode,
+		source?: ReadonlyArrayNode,
 	): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);
@@ -928,7 +944,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	public moveRangeToStart(
 		sourceStart: number,
 		sourceEnd: number,
-		source?: TreeArrayNode,
+		source?: ReadonlyArrayNode,
 	): void {
 		validateIndexRange(
 			sourceStart,
@@ -938,7 +954,11 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		);
 		this.moveRangeToIndex(0, sourceStart, sourceEnd, source);
 	}
-	public moveRangeToEnd(sourceStart: number, sourceEnd: number, source?: TreeArrayNode): void {
+	public moveRangeToEnd(
+		sourceStart: number,
+		sourceEnd: number,
+		source?: ReadonlyArrayNode,
+	): void {
 		validateIndexRange(
 			sourceStart,
 			sourceEnd,
@@ -951,7 +971,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		destinationGap: number,
 		sourceStart: number,
 		sourceEnd: number,
-		source?: TreeArrayNode,
+		source?: ReadonlyArrayNode,
 	): void {
 		const destinationField = getSequenceField(this);
 		const destinationSchema = this.allowedTypes;

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

@@ -11,6 +11,7 @@ export {
 	type InnerNode,
 	tryDisposeTreeNode,
 	tryGetTreeNodeFromMapNode,
+	getOrCreateInnerNode,
 } from "./treeNodeKernel.js";
 export { type WithType, typeNameSymbol, typeSchemaSymbol } from "./withType.js";
 export {

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

@@ -430,3 +430,16 @@ export function getTreeNodeSchemaFromHydratedFlexNode(flexNode: FlexTreeNode): T
 
 	return context.schema.get(flexNode.schema) ?? fail("Missing schema");
 }
+
+/**
+ * Retrieves the flex node associated with the given target via {@link setInnerNode}.
+ * @remarks
+ * For {@link Unhydrated} nodes, this returns the MapTreeNode.
+ *
+ * For hydrated nodes it returns a FlexTreeNode backed by the forest.
+ * Note that for "marinated" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.
+ */
+export function getOrCreateInnerNode(treeNode: TreeNode, allowFreed = false): InnerNode {
+	const kernel = getKernel(treeNode);
+	return kernel.getOrCreateInnerNode(allowFreed);
+}

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

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import type { InternalTreeNode, Unhydrated } from "./types.js";
+import type { TreeLeafValue } from "../schemaTypes.js";
+import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
 
 /**
  * Schema for a tree node.
@@ -19,7 +20,7 @@ import type { InternalTreeNode, Unhydrated } from "./types.js";
 export type TreeNodeSchema<
 	Name extends string = string,
 	Kind extends NodeKind = NodeKind,
-	TNode = unknown,
+	TNode extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
 	TBuild = never,
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
@@ -38,7 +39,7 @@ export type TreeNodeSchema<
 export interface TreeNodeSchemaNonClass<
 	out Name extends string = string,
 	out Kind extends NodeKind = NodeKind,
-	out TNode = unknown,
+	out TNode extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
 	in TInsertable = never,
 	out ImplicitlyConstructable extends boolean = boolean,
 	out Info = unknown,
@@ -94,7 +95,8 @@ export interface TreeNodeSchemaNonClass<
 export interface TreeNodeSchemaClass<
 	out Name extends string = string,
 	out Kind extends NodeKind = NodeKind,
-	out TNode = unknown,
+	// TODO: maybe this can be more specific (exclude leaves)
+	out TNode extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
 	in TInsertable = never,
 	out ImplicitlyConstructable extends boolean = boolean,
 	out Info = unknown,
@@ -115,7 +117,7 @@ export interface TreeNodeSchemaClass<
 export type TreeNodeSchemaBoth<
 	Name extends string = string,
 	Kind extends NodeKind = NodeKind,
-	TNode = unknown,
+	TNode extends TreeNode = TreeNode,
 	TInsertable = never,
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,

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

@@ -442,7 +442,12 @@ class EagerMapTreeRequiredField
 	implements FlexTreeRequiredField
 {
 	public override get content(): FlexTreeUnknownUnboxed {
-		return super.content ?? fail("Expected EagerMapTree required field to have a value");
+		// This cannot use ?? since null is a legal value here.
+		assert(
+			super.content !== undefined,
+			"Expected EagerMapTree required field to have a value",
+		);
+		return super.content;
 	}
 }
 

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

@@ -3,7 +3,9 @@
  * Licensed under the MIT License.
  */
 
+import type { TreeLeafValue } from "../schemaTypes.js";
 import type { NodeKind, TreeNodeSchemaClass } from "./treeNodeSchema.js";
+import type { TreeNode } from "./types.js";
 
 /**
  * The type of a {@link TreeNode}.
@@ -87,5 +89,12 @@ export interface WithType<
 	/**
 	 * Type symbol, marking a type in a way to increase type safety via strong type checking.
 	 */
-	get [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind, unknown, never, boolean, TInfo>;
+	get [typeSchemaSymbol](): TreeNodeSchemaClass<
+		TName,
+		TKind,
+		TreeNode | TreeLeafValue,
+		never,
+		boolean,
+		TInfo
+	>;
 }

package/src/simple-tree/index.ts

@@ -22,6 +22,7 @@ export {
 	tryDisposeTreeNode,
 	HydratedContext,
 	SimpleContextSlot,
+	getOrCreateInnerNode,
 } from "./core/index.js";
 export {
 	type ITree,
@@ -40,7 +41,6 @@ export {
 	enumFromStrings,
 	singletonSchema,
 	typedObjectValues,
-	type EmptyObject,
 	test_RecursiveObject,
 	test_RecursiveObject_base,
 	test_RecursiveObjectPojoMode,
@@ -67,7 +67,36 @@ export {
 	type JsonLeafSchemaType,
 	getJsonSchema,
 	getSimpleSchema,
+	type VerboseTreeNode,
+	type EncodeOptions,
+	type ParseOptions,
+	type VerboseTree,
+	extractPersistedSchema,
+	comparePersistedSchema,
+	type ConciseTree,
+	comparePersistedSchemaInternal,
 	ViewSchema,
+	type Unenforced,
+	type FieldHasDefaultUnsafe,
+	type ObjectFromSchemaRecordUnsafe,
+	type TreeObjectNodeUnsafe,
+	type TreeFieldFromImplicitFieldUnsafe,
+	type TreeNodeFromImplicitAllowedTypesUnsafe,
+	type FieldSchemaUnsafe,
+	type InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
+	type TreeArrayNodeUnsafe,
+	type TreeMapNodeUnsafe,
+	type InsertableObjectFromSchemaRecordUnsafe,
+	type InsertableTreeFieldFromImplicitFieldUnsafe,
+	type InsertableTypedNodeUnsafe,
+	type NodeBuilderDataUnsafe,
+	type NodeFromSchemaUnsafe,
+	type ReadonlyMapInlined,
+	type TreeNodeSchemaClassUnsafe,
+	type TreeNodeSchemaUnsafe,
+	type AllowedTypesUnsafe,
+	type TreeNodeSchemaNonClassUnsafe,
+	type TreeViewAlpha,
 } from "./api/index.js";
 export {
 	type NodeFromSchema,
@@ -89,34 +118,19 @@ export {
 	normalizeFieldSchema,
 	type ApplyKind,
 	type FieldSchemaMetadata,
+	type InsertableField,
+	type Insertable,
+	type UnsafeUnknownSchema,
 } from "./schemaTypes.js";
-export { getOrCreateInnerNode } from "./proxyBinding.js";
-export type {
-	FieldHasDefaultUnsafe,
-	ObjectFromSchemaRecordUnsafe,
-	TreeObjectNodeUnsafe,
-	TreeFieldFromImplicitFieldUnsafe,
-	TreeNodeFromImplicitAllowedTypesUnsafe,
-	FieldSchemaUnsafe,
-	InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
-	TreeArrayNodeUnsafe,
-	TreeMapNodeUnsafe,
-	InsertableObjectFromSchemaRecordUnsafe,
-	InsertableTreeFieldFromImplicitFieldUnsafe,
-	InsertableTypedNodeUnsafe,
-	NodeBuilderDataUnsafe,
-	NodeFromSchemaUnsafe,
-	ReadonlyMapInlined,
-} from "./typesUnsafe.js";
 export {
 	getTreeNodeForField,
 	prepareContentForHydration,
 } from "./proxies.js";
-
 export {
 	TreeArrayNode,
 	IterableTreeArrayContent,
 	type TreeArrayNodeBase,
+	type ReadonlyArrayNode,
 } from "./arrayNode.js";
 export {
 	type FieldHasDefault,
@@ -126,7 +140,12 @@ export {
 	setField,
 } from "./objectNode.js";
 export type { TreeMapNode, MapNodeInsertableData } from "./mapNode.js";
-export { mapTreeFromNodeData, type InsertableContent } from "./toMapTree.js";
+export {
+	mapTreeFromNodeData,
+	type InsertableContent,
+	type FactoryContent,
+	type FactoryContentObject,
+} from "./toMapTree.js";
 export { toStoredSchema, getStoredSchema } from "./toFlexSchema.js";
 export {
 	numberSchema,
@@ -135,3 +154,4 @@ export {
 	handleSchema,
 	nullSchema,
 } from "./leafNodeSchema.js";
+export type { LazyItem, FlexList, FlexListToUnion, ExtractItemType } from "./flexList.js";

package/src/simple-tree/mapNode.ts

@@ -11,7 +11,6 @@ import {
 	getSchemaAndPolicy,
 } from "../feature-libraries/index.js";
 import { getTreeNodeForField, prepareContentForHydration } from "./proxies.js";
-import { getOrCreateInnerNode } from "./proxyBinding.js";
 import {
 	createFieldSchema,
 	FieldKind,
@@ -33,6 +32,7 @@ import {
 	typeSchemaSymbol,
 	type Context,
 	UnhydratedFlexTreeNode,
+	getOrCreateInnerNode,
 } from "./core/index.js";
 import {
 	mapTreeFromNodeData,

package/src/simple-tree/objectNode.ts

@@ -16,7 +16,6 @@ import {
 	getSchemaAndPolicy,
 } from "../feature-libraries/index.js";
 import { getTreeNodeForField, prepareContentForHydration } from "./proxies.js";
-import { getOrCreateInnerNode } from "./proxyBinding.js";
 import {
 	type ImplicitFieldSchema,
 	getStoredKey,
@@ -39,6 +38,7 @@ import {
 	type TreeNode,
 	type Context,
 	UnhydratedFlexTreeNode,
+	getOrCreateInnerNode,
 } from "./core/index.js";
 import { mapTreeFromNodeData, type InsertableContent } from "./toMapTree.js";
 import { type RestrictiveStringRecord, fail, type FlattenKeys } from "../util/index.js";

package/src/simple-tree/schemaTypes.ts

@@ -7,21 +7,18 @@ import type { ErasedType, IFluidHandle } from "@fluidframework/core-interfaces";
 import { Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import {
-	type LazyItem,
-	type NodeKeyManager,
-	isLazy,
-	type FlexListToUnion,
-} from "../feature-libraries/index.js";
+import type { NodeKeyManager } from "../feature-libraries/index.js";
 import { type MakeNominal, brand, isReadonlyArray } from "../util/index.js";
 import type {
 	Unhydrated,
 	NodeKind,
 	TreeNodeSchema,
 	TreeNodeSchemaClass,
+	TreeNode,
 } from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
 import type { InsertableContent } from "./toMapTree.js";
+import { isLazy, type FlexListToUnion, type LazyItem } from "./flexList.js";
 
 /**
  * Returns true if the given schema is a {@link TreeNodeSchemaClass}, or otherwise false if it is a {@link TreeNodeSchemaNonClass}.
@@ -29,7 +26,7 @@ import type { InsertableContent } from "./toMapTree.js";
 export function isTreeNodeSchemaClass<
 	Name extends string,
 	Kind extends NodeKind,
-	TNode,
+	TNode extends TreeNode | TreeLeafValue,
 	TBuild,
 	ImplicitlyConstructable extends boolean,
 	Info,
@@ -385,7 +382,17 @@ export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
 export type ImplicitFieldSchema = FieldSchema | ImplicitAllowedTypes;
 
 /**
- * Converts ImplicitFieldSchema to the corresponding tree node's field type.
+ * Converts an `ImplicitFieldSchema` to a property type suitable for reading a field with this that schema.
+ *
+ * @typeparam TSchema - When non-exact schema are provided this errors on the side of returning too general of a type (a conservative union of all possibilities).
+ * This is ideal for "output APIs" - i.e. it converts the schema type to the runtime type that a user will _read_ from the tree.
+ * Examples of such "non-exact" schema include `ImplicitFieldSchema`, `ImplicitAllowedTypes`, and  TypeScript unions of schema types.
+ * @privateRemarks
+ * TODO:
+ * There are two known problematic usages of this type (which produce invalid/unsound results when given non-specific schema):
+ * 1. setters for fields (on object nodes the Tree.view.root).
+ * 2. Indirectly in InsertableTreeFieldFromImplicitField via InsertableTypedNode including NodeFromSchema.
+ * These cases should be mitigated by introducing a way to detect inexact schema and special casing them in these two places.
  * @public
  */
 export type TreeFieldFromImplicitField<TSchema extends ImplicitFieldSchema = FieldSchema> =
@@ -393,7 +400,7 @@ export type TreeFieldFromImplicitField<TSchema extends ImplicitFieldSchema = Fie
 		? ApplyKind<TreeNodeFromImplicitAllowedTypes<Types>, Kind, false>
 		: TSchema extends ImplicitAllowedTypes
 			? TreeNodeFromImplicitAllowedTypes<TSchema>
-			: unknown;
+			: TreeNode | TreeLeafValue | undefined;
 
 /**
  * Type of content that can be inserted into the tree for a field of the given schema.
@@ -405,7 +412,55 @@ export type InsertableTreeFieldFromImplicitField<
 	? ApplyKind<InsertableTreeNodeFromImplicitAllowedTypes<Types>, Kind, true>
 	: TSchema extends ImplicitAllowedTypes
 		? InsertableTreeNodeFromImplicitAllowedTypes<TSchema>
-		: unknown;
+		: never;
+
+/**
+ * {@inheritdoc (UnsafeUnknownSchema:type)}
+ * @alpha
+ */
+export const UnsafeUnknownSchema: unique symbol = Symbol("UnsafeUnknownSchema");
+
+/**
+ * A special type which can be provided to some APIs as the schema type parameter when schema cannot easily be provided at compile time and an unsafe (instead of disabled) editing API is desired.
+ * @remarks
+ * When used this means the TypeScript typing should error on the side of completeness (allow all inputs that could be valid).
+ * This introduces the risk that out of schema data could be allowed at compile time, and only error at runtime.
+ *
+ * @privateRemarks
+ * This only applies to APIs which input data which is expected to be in schema, since APIs outputting have easy mechanisms to do so in a type safe way even when the schema is unknown.
+ * In most cases that amounts to returning `TreeNode | TreeLeafValue`.
+ *
+ * This can be contrasted with the default behavior of TypeScript, which is to require the intersection of the possible types for input APIs,
+ * which for unknown schema defining input trees results in the `never` type.
+ *
+ * Any APIs which use this must produce UsageErrors when out of schema data is encountered, and never produce unrecoverable errors,
+ * or silently accept invalid data.
+ * This is currently only type exported from the package: the symbol is just used as a way to get a named type.
+ * @alpha
+ */
+export type UnsafeUnknownSchema = typeof UnsafeUnknownSchema;
+
+/**
+ * Content which could be inserted into a tree.
+ * @remarks
+ * Extended version of {@link InsertableTreeNodeFromImplicitAllowedTypes} that also allows {@link (UnsafeUnknownSchema:type)}.
+ * @alpha
+ */
+export type Insertable<TSchema extends ImplicitAllowedTypes | UnsafeUnknownSchema> =
+	TSchema extends ImplicitAllowedTypes
+		? InsertableTreeNodeFromImplicitAllowedTypes<TSchema>
+		: InsertableContent;
+
+/**
+ * Content which could be inserted into a field within a tree.
+ * @remarks
+ * Extended version of {@link InsertableTreeFieldFromImplicitField} that also allows {@link (UnsafeUnknownSchema:type)}.
+ * @alpha
+ */
+export type InsertableField<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema> =
+	TSchema extends ImplicitFieldSchema
+		? InsertableTreeFieldFromImplicitField<TSchema>
+		: InsertableContent | undefined;
 
 /**
  * Suitable for output.
@@ -457,6 +512,10 @@ export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchema<
 /**
  * Data which can be used as a node to be inserted.
  * Either an unhydrated node, or content to build a new node.
+ * @privateRemarks
+ * TODO:
+ * This should behave contravariantly, but it uses NodeFromSchema which behaves covariantly.
+ * This results in unsoundness where when the schema is less specific, more types are allowed instead of less.
  * @public
  */
 export type InsertableTypedNode<T extends TreeNodeSchema> =
@@ -475,7 +534,7 @@ export type InsertableTypedNode<T extends TreeNodeSchema> =
 export type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema<
 	string,
 	NodeKind,
-	unknown,
+	TreeNode | TreeLeafValue,
 	infer TBuild
 >
 	? TBuild

package/src/simple-tree/toFlexSchema.ts

@@ -20,9 +20,6 @@ import {
 	type TreeTypeSet,
 } from "../core/index.js";
 import { FieldKinds, type FlexFieldKind } from "../feature-libraries/index.js";
-// TODO: once flex schema is gone, this code can move into simple-tree
-// eslint-disable-next-line import/no-internal-modules
-import { normalizeFlexListEager } from "../feature-libraries/typed-schema/index.js";
 import { brand, fail, isReadonlyArray } from "../util/index.js";
 import { NodeKind, type TreeNodeSchema } from "./core/index.js";
 import {
@@ -34,6 +31,7 @@ import {
 import { walkFieldSchema } from "./walkFieldSchema.js";
 import { LeafNodeSchema } from "./leafNodeSchema.js";
 import { isObjectNodeSchema } from "./objectNodeTypes.js";
+import { normalizeFlexListEager } from "./flexList.js";
 
 /**
  * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema}.

package/src/simple-tree/toMapTree.ts

@@ -262,14 +262,14 @@ function mapValueWithFallbacks(
 				// Our serialized data format does not support -0.
 				// Map such input to +0.
 				return 0;
-			} else if (Number.isNaN(value) || !Number.isFinite(value)) {
+			} else if (!Number.isFinite(value)) {
 				// Our serialized data format does not support NaN nor +/-∞.
 				// If the schema supports `null`, fall back to that. Otherwise, throw.
 				// This is intended to match JSON's behavior for such values.
 				if (allowedTypes.has(nullSchema)) {
 					return null;
 				} else {
-					throw new TypeError(`Received unsupported numeric value: ${value}.`);
+					throw new UsageError(`Received unsupported numeric value: ${value}.`);
 				}
 			} else {
 				return value;
@@ -287,7 +287,7 @@ function mapValueWithFallbacks(
 			}
 		}
 		default:
-			throw new TypeError(`Received unsupported leaf value: ${value}.`);
+			throw new UsageError(`Received unsupported leaf value: ${value}.`);
 	}
 }
 
@@ -726,6 +726,7 @@ function tryGetInnerNode(target: unknown): InnerNode | undefined {
  * Content which can be used to build a node.
  * @remarks
  * Can contain unhydrated nodes, but can not be an unhydrated node at the root.
+ * @system @alpha
  */
 export type FactoryContent =
 	| IFluidHandle
@@ -744,12 +745,14 @@ export type FactoryContent =
  * Can contain unhydrated nodes, but can not be an unhydrated node at the root.
  *
  * Supports object and map nodes.
+ * @system @alpha
  */
-type FactoryContentObject = {
+export type FactoryContentObject = {
 	readonly [P in string]?: InsertableContent;
 };
 
 /**
  * Content which can be inserted into a tree.
+ * @system @alpha
  */
 export type InsertableContent = Unhydrated<TreeNode> | FactoryContent;

package/src/simple-tree/treeNodeValid.ts

@@ -18,11 +18,12 @@ import {
 	type Context,
 	type UnhydratedFlexTreeNode,
 } from "./core/index.js";
-import { type FlexTreeNode, isFlexTreeNode, markEager } from "../feature-libraries/index.js";
+import { type FlexTreeNode, isFlexTreeNode } from "../feature-libraries/index.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { fail } from "../util/index.js";
 
 import { getSimpleNodeSchemaFromInnerNode } from "./core/index.js";
+import { markEager } from "./flexList.js";
 
 /**
  * Class which all {@link TreeNode}s must extend.

package/src/treeFactory.ts

@@ -81,6 +81,7 @@ export const SharedTree = configuredSharedTree({});
  * });
  * ```
  * @privateRemarks
+ * This should be legacy, but has to be internal due to limitations of API tagging preventing it from being both alpha and alpha+legacy.
  * TODO:
  * Expose Ajv validator for better error message quality somehow.
  * Maybe as part of a test utils or dev-tool package?

package/src/util/utils.ts

@@ -219,9 +219,10 @@ export function count(iterable: Iterable<unknown>): number {
 
 /**
  * Use for Json compatible data.
- *
- * Note that this does not robustly forbid non json comparable data via type checking,
+ * @remarks
+ * This does not robustly forbid non json comparable data via type checking,
  * but instead mostly restricts access to it.
+ * @alpha
  */
 export type JsonCompatible =
 	| string
@@ -234,16 +235,17 @@ export type JsonCompatible =
 
 /**
  * Use for Json object compatible data.
- *
- * Note that this does not robustly forbid non json comparable data via type checking,
+ * @remarks
+ * This does not robustly forbid non json comparable data via type checking,
  * but instead mostly restricts access to it.
+ * @alpha
  */
 export type JsonCompatibleObject = { [P in string]?: JsonCompatible };
 
 /**
  * Use for readonly view of Json compatible data.
- *
- * Note that this does not robustly forbid non json comparable data via type checking,
+ * @remarks
+ * This does not robustly forbid non json comparable data via type checking,
  * but instead mostly restricts access to it.
  */
 export type JsonCompatibleReadOnly =
@@ -257,8 +259,8 @@ export type JsonCompatibleReadOnly =
 
 /**
  * Use for readonly view of Json compatible data.
- *
- * Note that this does not robustly forbid non json comparable data via type checking,
+ * @remarks
+ * This does not robustly forbid non json comparable data via type checking,
  * but instead mostly restricts access to it.
  */
 export type JsonCompatibleReadOnlyObject = { readonly [P in string]?: JsonCompatibleReadOnly };