@fluidframework/tree 2.4.0-297385 → 2.4.0-299707

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

@@ -0,0 +1,126 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ICodecOptions } from "../../codec/index.js";
+import { Compatibility, type TreeStoredSchema } from "../../core/index.js";
+import {
+	defaultSchemaPolicy,
+	encodeTreeSchema,
+	makeSchemaCodec,
+} from "../../feature-libraries/index.js";
+// eslint-disable-next-line import/no-internal-modules
+import type { Format } from "../../feature-libraries/schema-index/index.js";
+import type { JsonCompatible } from "../../util/index.js";
+import type { ImplicitFieldSchema } from "../schemaTypes.js";
+import { toStoredSchema } from "../toFlexSchema.js";
+import type { SchemaCompatibilityStatus } from "./tree.js";
+import { ViewSchema } from "./view.js";
+
+/**
+ * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable, but unspecified format.
+ *
+ * @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.
+ *
+ * This format may change across major versions of this package: such changes are considered breaking.
+ * Beyond that, no compatibility guarantee is provided for this format: it should never be relied upon to load data, it should only be used for comparing outputs from this function.
+ *
+ * This only includes the "persisted" subset of schema information, which means the portion which gets included in documents.
+ * It thus uses "persisted" keys, see {@link FieldProps.key}.
+ *
+ * If two schema have identical "persisted" schema, then they are considered {@link SchemaCompatibilityStatus.isEquivalent|equivalent}.
+ *
+ * See also {@link comparePersistedSchema}.
+ *
+ * @example
+ * An application could use this API to generate a `schema.json` file when it first releases,
+ * then test that the schema is sill compatible with documents from that version with a test like :
+ * ```typescript
+ * assert.deepEqual(extractPersistedSchema(MySchema), require("./schema.json"));
+ * ```
+ *
+ * @privateRemarks
+ * This currently uses the schema summary format, but that could be changed to something more human readable (particularly if the encoded format becomes less human readable).
+ * This intentionally does not leak the format types in the API.
+ *
+ * Public API surface uses "persisted" terminology while internally we use "stored".
+ * @alpha
+ */
+export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompatible {
+	const stored = toStoredSchema(schema);
+	return encodeTreeSchema(stored);
+}
+
+/**
+ * Compares two schema extracted using {@link extractPersistedSchema}.
+ * Reports the same compatibility that {@link TreeView.compatibility} would report if
+ * opening a document that used the `persisted` schema and provided `view` to {@link ViewableTree.viewWith}.
+ *
+ * @param persisted - Schema persisted for a document. Typically persisted alongside the data and assumed to describe that data.
+ * @param view - Schema which would be used to view persisted content. Use {@link extractPersistedSchema} to convert the view schema into this format.
+ * @param options - {@link ICodecOptions} used when parsing the provided schema.
+ * @param canInitialize - Passed through to the return value unchanged and otherwise unused.
+ * @returns The {@link SchemaCompatibilityStatus} a {@link TreeView} would report for this combination of schema.
+ *
+ * @remarks
+ * This uses the persisted formats for schema, meaning it only includes data which impacts compatibility.
+ * It also uses the persisted format so that this API can be used in tests to compare against saved schema from previous versions of the application.
+ *
+ * @example
+ * An application could use {@link extractPersistedSchema} to generate a `schema.json` file for various versions of the app,
+ * then test that documents using those schema can be upgraded to work with the current schema using a test like:
+ * ```typescript
+ * assert(
+ * 	comparePersistedSchema(
+ * 		require("./schema.json"),
+ * 		extractPersistedSchema(MySchema),
+ * 		{ jsonValidator: typeboxValidator },
+ * 		false,
+ * 	).canUpgrade,
+ * );
+ * ```
+ * @alpha
+ */
+export function comparePersistedSchema(
+	persisted: JsonCompatible,
+	view: JsonCompatible,
+	options: ICodecOptions,
+	canInitialize: boolean,
+): SchemaCompatibilityStatus {
+	const schemaCodec = makeSchemaCodec(options);
+	const stored = schemaCodec.decode(persisted as Format);
+	const viewParsed = schemaCodec.decode(view as Format);
+	const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, viewParsed);
+	return comparePersistedSchemaInternal(stored, viewSchema, canInitialize);
+}
+
+/**
+ * Compute compatibility for viewing a document with `stored` schema using `viewSchema`.
+ * `canInitialize` is passed through to the return value unchanged and otherwise unused.
+ */
+export function comparePersistedSchemaInternal(
+	stored: TreeStoredSchema,
+	viewSchema: ViewSchema,
+	canInitialize: boolean,
+): SchemaCompatibilityStatus {
+	const result = viewSchema.checkCompatibility(stored);
+
+	// TODO: AB#8121: Weaken this check to support viewing under additional circumstances.
+	// In the near term, this should support viewing documents with additional optional fields in their schema on object types.
+	// Longer-term (as demand arises), we could also add APIs to constructing view schema to allow for more flexibility
+	// (e.g. out-of-schema content handlers could allow support for viewing docs which have extra allowed types in a particular field)
+	const canView =
+		result.write === Compatibility.Compatible && result.read === Compatibility.Compatible;
+	const canUpgrade = result.read === Compatibility.Compatible;
+	const isEquivalent = canView && canUpgrade;
+	const compatibility: SchemaCompatibilityStatus = {
+		canView,
+		canUpgrade,
+		isEquivalent,
+		canInitialize,
+	};
+
+	return compatibility;
+}

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

@@ -6,15 +6,8 @@
 import { assert, oob } from "@fluidframework/core-utils/internal";
 
 import { EmptyKey, rootFieldKey } from "../../core/index.js";
-import {
-	type LazyItem,
-	type TreeStatus,
-	isLazy,
-	isTreeValue,
-	FieldKinds,
-} from "../../feature-libraries/index.js";
+import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
 import { fail, extractFromOpaque, isReadonlyArray } from "../../util/index.js";
-import { getOrCreateInnerNode } from "../proxyBinding.js";
 import {
 	type TreeLeafValue,
 	type ImplicitFieldSchema,
@@ -43,8 +36,10 @@ import {
 	getOrCreateNodeFromInnerNode,
 	UnhydratedFlexTreeNode,
 	typeSchemaSymbol,
+	getOrCreateInnerNode,
 } from "../core/index.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
+import { isLazy, type LazyItem } from "../flexList.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.

package/src/simple-tree/{typesUnsafe.ts → api/typesUnsafe.ts}

@@ -3,8 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { FlexListToUnion, Unenforced } from "../feature-libraries/index.js";
-import type { RestrictiveStringRecord, _InlineTrick } from "../util/index.js";
+import type { RestrictiveStringRecord, _InlineTrick } from "../../util/index.js";
 
 import type {
 	AllowedTypes,
@@ -15,15 +14,16 @@ import type {
 	ImplicitFieldSchema,
 	NodeFromSchema,
 	TreeNodeFromImplicitAllowedTypes,
-} from "./schemaTypes.js";
+} from "../schemaTypes.js";
 import type {
 	NodeKind,
 	TreeNodeSchema,
 	WithType,
 	TreeNode,
 	Unhydrated,
-} from "./core/index.js";
-import type { TreeArrayNodeBase, TreeArrayNode } from "./arrayNode.js";
+} from "../core/index.js";
+import type { TreeArrayNodeBase, TreeArrayNode } from "../arrayNode.js";
+import type { FlexListToUnion } from "../flexList.js";
 
 /*
  * TODO:
@@ -37,6 +37,16 @@ import type { TreeArrayNodeBase, TreeArrayNode } from "./arrayNode.js";
  */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+/**
+ * A placeholder to use in {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-constraints | extends constraints} when using the real type breaks compilation of some recursive types due to {@link https://github.com/microsoft/TypeScript/issues/55758 | a design limitation of TypeScript}.
+ *
+ * These extends constraints only serve as documentation:
+ * to avoid breaking compilation, this type has to not actually enforce anything, and thus is just `unknown`.
+ * Therefore the type safety is the responsibility of the user of the API.
+ * @public
+ */
+export type Unenforced<_DesiredExtendsConstraint> = unknown;
+
 /**
  * {@link Unenforced} version of `ObjectFromSchemaRecord`.
  * @remarks

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

@@ -10,10 +10,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import {
 	aboveRootPlaceholder,
 	EmptyKey,
-	forEachField,
-	inCursorField,
 	keyAsDetachedField,
-	mapCursorField,
 	type FieldKey,
 	type ITreeCursor,
 	type ITreeCursorSynchronous,
@@ -40,16 +37,22 @@ import {
 	stringSchema,
 } from "../leafNodeSchema.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
-import { walkFieldSchema } from "../walkFieldSchema.js";
+import {
+	customFromCursorInner,
+	type CustomTreeNode,
+	type CustomTreeValue,
+	type EncodeOptions,
+} from "./customTree.js";
 import { getUnhydratedContext } from "../createContext.js";
 
 /**
- * Verbose encoding of a {@link TreeNode} or {@link TreeValue}.
+ * Verbose encoding of a {@link TreeNode} or {@link TreeLeafValue}.
  * @remarks
  * This is verbose meaning that every {@link TreeNode} is a {@link VerboseTreeNode}.
  * Any IFluidHandle values have been replaced by `THandle`.
  * @privateRemarks
- * This can store all possible simple trees, but it can not store all possible trees representable by our internal representations like FlexTree and JsonableTree.
+ * This can store all possible simple trees,
+ * but it can not store all possible trees representable by our internal representations like FlexTree and JsonableTree.
  */
 export type VerboseTree<THandle = IFluidHandle> =
 	| VerboseTreeNode<THandle>
@@ -77,7 +80,8 @@ export type VerboseTree<THandle = IFluidHandle> =
  * This format allows for all simple-tree compatible trees to be represented.
  *
  * Unlike `JsonableTree`, leaf nodes are not boxed into node objects, and instead have their schema inferred from the value.
- * Additionally, sequence fields can only occur on a node that has a single sequence field (with the empty key) replicating the behavior of simple-tree ArrayNodes.
+ * Additionally, sequence fields can only occur on a node that has a single sequence field (with the empty key)
+ * replicating the behavior of simple-tree ArrayNodes.
  */
 export interface VerboseTreeNode<THandle = IFluidHandle> {
 	/**
@@ -144,24 +148,6 @@ export interface SchemalessParseOptions<TCustom> {
 	};
 }
 
-/**
- * Options for how to interpret a `VerboseTree<TCustom>` without relying on schema.
- */
-export interface EncodeOptions<TCustom> {
-	/**
-	 * Fixup custom input formats.
-	 * @remarks
-	 * See note on {@link ParseOptions.valueConverter}.
-	 */
-	valueConverter(data: IFluidHandle): TCustom;
-	/**
-	 * If true, interpret the input keys of object nodes as stored keys.
-	 * If false, interpret them as property keys.
-	 * @defaultValue false.
-	 */
-	readonly useStoredKeys?: boolean;
-}
-
 /**
  * Use info from `schema` to convert `options` to {@link SchemalessParseOptions}.
  */
@@ -345,12 +331,7 @@ export function verboseFromCursor<TCustom>(
 		...options,
 	};
 
-	const schemaMap = new Map<string, TreeNodeSchema>();
-	walkFieldSchema(rootSchema, {
-		node(schema) {
-			schemaMap.set(schema.identifier, schema);
-		},
-	});
+	const schemaMap = getUnhydratedContext(rootSchema).schema;
 
 	return verboseFromCursorInner(reader, config, schemaMap);
 }
@@ -360,50 +341,14 @@ function verboseFromCursorInner<TCustom>(
 	options: Required<EncodeOptions<TCustom>>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): VerboseTree<TCustom> {
-	const type = reader.type;
-	const nodeSchema = schema.get(type) ?? fail("missing schema for type in cursor");
-
-	switch (type) {
-		case numberSchema.identifier:
-		case booleanSchema.identifier:
-		case nullSchema.identifier:
-		case stringSchema.identifier:
-			assert(reader.value !== undefined, 0xa14 /* out of schema: missing value */);
-			assert(!isFluidHandle(reader.value), 0xa15 /* out of schema: unexpected FluidHandle */);
-			return reader.value;
-		case handleSchema.identifier:
-			assert(reader.value !== undefined, 0xa16 /* out of schema: missing value */);
-			assert(isFluidHandle(reader.value), 0xa17 /* out of schema: unexpected FluidHandle */);
-			return options.valueConverter(reader.value);
-		default: {
-			assert(reader.value === undefined, 0xa18 /* out of schema: unexpected value */);
-			if (nodeSchema.kind === NodeKind.Array) {
-				const fields = inCursorField(reader, EmptyKey, () =>
-					mapCursorField(reader, () => verboseFromCursorInner(reader, options, schema)),
-				);
-				return { type, fields };
-			} else {
-				const fields: Record<string, VerboseTree<TCustom>> = {};
-				forEachField(reader, () => {
-					const children = mapCursorField(reader, () =>
-						verboseFromCursorInner(reader, options, schema),
-					);
-					if (children.length === 1) {
-						const storedKey = reader.getFieldKey();
-						const key =
-							isObjectNodeSchema(nodeSchema) && !options.useStoredKeys
-								? nodeSchema.storedKeyToPropertyKey.get(storedKey) ??
-									fail("missing property key")
-								: storedKey;
-						// Length is checked above.
-						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-						fields[key] = children[0]!;
-					} else {
-						assert(children.length === 0, 0xa19 /* invalid children number */);
-					}
-				});
-				return { type, fields };
-			}
-		}
+	const fields = customFromCursorInner(reader, options, schema, verboseFromCursorInner);
+	const nodeSchema = schema.get(reader.type) ?? fail("missing schema for type in cursor");
+	if (nodeSchema.kind === NodeKind.Leaf) {
+		return fields as CustomTreeValue<TCustom>;
 	}
+
+	return {
+		type: reader.type,
+		fields: fields as CustomTreeNode<TCustom>,
+	};
 }

package/src/simple-tree/arrayNode.ts

@@ -14,7 +14,6 @@ import {
 	isFlexTreeNode,
 } from "../feature-libraries/index.js";
 import { prepareContentForHydration } from "./proxies.js";
-import { getOrCreateInnerNode } from "./proxyBinding.js";
 import {
 	normalizeAllowedTypes,
 	type ImplicitAllowedTypes,
@@ -34,6 +33,7 @@ import {
 	getOrCreateNodeFromInnerNode,
 	type TreeNodeSchemaBoth,
 	getSimpleNodeSchemaFromInnerNode,
+	getOrCreateInnerNode,
 } from "./core/index.js";
 import { type InsertableContent, mapTreeFromNodeData } from "./toMapTree.js";
 import { fail } from "../util/index.js";

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/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/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,31 @@ 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,
 } from "./api/index.js";
 export {
 	type NodeFromSchema,
@@ -90,29 +114,10 @@ export {
 	type ApplyKind,
 	type FieldSchemaMetadata,
 } 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,
@@ -135,3 +140,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,12 +7,7 @@ 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,
@@ -22,6 +17,7 @@ import type {
 } 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}.

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}.`);
 	}
 }
 

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

package/dist/feature-libraries/flex-tree/unboxed.d.ts

@@ -1,12 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import type { ITreeSubscriptionCursor } from "../../core/index.js";
-import type { Context } from "./context.js";
-import type { FlexTreeUnknownUnboxed } from "./flexTreeTypes.js";
-/**
- * Returns the flex tree node, of the value if it has one.
- */
-export declare function unboxedFlexNode(context: Context, cursor: ITreeSubscriptionCursor): FlexTreeUnknownUnboxed;
-//# sourceMappingURL=unboxed.d.ts.map

package/dist/feature-libraries/flex-tree/unboxed.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"unboxed.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/flex-tree/unboxed.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGjE;;GAEG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,uBAAuB,GAC7B,sBAAsB,CAMxB"}