@fluidframework/tree 2.4.0-297027 → 2.4.0-299374

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

@@ -0,0 +1,58 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+
+import type { ITreeCursor } from "../../core/index.js";
+import type { TreeLeafValue, ImplicitAllowedTypes } from "../schemaTypes.js";
+import type { TreeNodeSchema } from "../core/index.js";
+import { customFromCursorInner, type EncodeOptions } from "./customTree.js";
+import { getUnhydratedContext } from "../createContext.js";
+
+/**
+ * Concise encoding of a {@link TreeNode} or {@link TreeLeafValue}.
+ * @remarks
+ * This is "concise" meaning that explicit type information is omitted.
+ * If the schema is compatible with {@link ITreeConfigurationOptions.preventAmbiguity},
+ * types will be lossless and compatible with {@link TreeBeta.create} (unless the options are used to customize it).
+ *
+ * Every {@link TreeNode} is an array or object.
+ * 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.
+ */
+export type ConciseTree<THandle = IFluidHandle> =
+	| Exclude<TreeLeafValue, IFluidHandle>
+	| THandle
+	| ConciseTree<THandle>[]
+	| {
+			[key: string]: ConciseTree<THandle>;
+	  };
+
+/**
+ * Used to read a node cursor as a ConciseTree.
+ */
+export function conciseFromCursor<TCustom>(
+	reader: ITreeCursor,
+	rootSchema: ImplicitAllowedTypes,
+	options: EncodeOptions<TCustom>,
+): ConciseTree<TCustom> {
+	const config: Required<EncodeOptions<TCustom>> = {
+		useStoredKeys: false,
+		...options,
+	};
+
+	const schemaMap = getUnhydratedContext(rootSchema).schema;
+	return conciseFromCursorInner(reader, config, schemaMap);
+}
+
+function conciseFromCursorInner<TCustom>(
+	reader: ITreeCursor,
+	options: Required<EncodeOptions<TCustom>>,
+	schema: ReadonlyMap<string, TreeNodeSchema>,
+): ConciseTree<TCustom> {
+	return customFromCursorInner(reader, options, schema, conciseFromCursorInner);
+}

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

@@ -0,0 +1,119 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
+
+import {
+	EmptyKey,
+	forEachField,
+	inCursorField,
+	mapCursorField,
+	type ITreeCursor,
+} from "../../core/index.js";
+import { fail } from "../../util/index.js";
+import type { TreeLeafValue } from "../schemaTypes.js";
+import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import {
+	booleanSchema,
+	handleSchema,
+	nullSchema,
+	numberSchema,
+	stringSchema,
+} from "../leafNodeSchema.js";
+import { isObjectNodeSchema } from "../objectNodeTypes.js";
+
+/**
+ * Options for how to encode a tree.
+ */
+export interface EncodeOptions<TCustom> {
+	/**
+	 * How to encode any {@link @fluidframework/core-interfaces#IFluidHandle|IFluidHandles} in the tree.
+	 * @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;
+}
+
+/**
+ * Tree representation with fields as properties and customized handle and child representations.
+ */
+export type CustomTree<TChild, THandle> = CustomTreeNode<TChild> | CustomTreeValue<THandle>;
+
+/**
+ * TreeLeafValue except the handle type is customized.
+ */
+export type CustomTreeValue<THandle> = Exclude<TreeLeafValue, IFluidHandle> | THandle;
+
+/**
+ * Tree node representation with fields as properties and customized child representation.
+ */
+export type CustomTreeNode<TChild> = TChild[] | { [key: string]: TChild };
+
+/**
+ * Builds an {@link CustomTree} from a cursor in Nodes mode.
+ */
+export function customFromCursorInner<TChild, THandle>(
+	reader: ITreeCursor,
+	options: Required<EncodeOptions<THandle>>,
+	schema: ReadonlyMap<string, TreeNodeSchema>,
+	childHandler: (
+		reader: ITreeCursor,
+		options: Required<EncodeOptions<THandle>>,
+		schema: ReadonlyMap<string, TreeNodeSchema>,
+	) => TChild,
+): CustomTree<TChild, THandle> {
+	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, "out of schema: missing value");
+			assert(!isFluidHandle(reader.value), "out of schema: unexpected FluidHandle");
+			return reader.value;
+		case handleSchema.identifier:
+			assert(reader.value !== undefined, "out of schema: missing value");
+			assert(isFluidHandle(reader.value), "out of schema: expected FluidHandle");
+			return options.valueConverter(reader.value);
+		default: {
+			assert(reader.value === undefined, "out of schema: unexpected value");
+			if (nodeSchema.kind === NodeKind.Array) {
+				const fields = inCursorField(reader, EmptyKey, () =>
+					mapCursorField(reader, () => childHandler(reader, options, schema)),
+				);
+				return fields;
+			} else {
+				const fields: Record<string, TChild> = {};
+				forEachField(reader, () => {
+					const children = mapCursorField(reader, () => childHandler(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 fields;
+			}
+		}
+	}
+}

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

@@ -12,6 +12,7 @@ export {
 	type ITreeViewConfiguration,
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
+	type TreeViewAlpha,
 } from "./tree.js";
 export { SchemaFactory, type ScopedSchemaName } from "./schemaFactory.js";
 export type {
@@ -23,7 +24,6 @@ export {
 	enumFromStrings,
 	singletonSchema,
 	typedObjectValues,
-	type EmptyObject,
 } from "./schemaCreationUtilities.js";
 export { treeNodeApi, type TreeNodeApi } from "./treeNodeApi.js";
 export { createFromInsertable, cursorFromInsertable } from "./create.js";
@@ -46,9 +46,47 @@ export {
 export { getJsonSchema } from "./getJsonSchema.js";
 export { getSimpleSchema } from "./getSimpleSchema.js";
 export { ViewSchema } from "./view.js";
+export type {
+	Unenforced,
+	FieldHasDefaultUnsafe,
+	ObjectFromSchemaRecordUnsafe,
+	TreeObjectNodeUnsafe,
+	TreeFieldFromImplicitFieldUnsafe,
+	TreeNodeFromImplicitAllowedTypesUnsafe,
+	FieldSchemaUnsafe,
+	InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
+	TreeArrayNodeUnsafe,
+	TreeMapNodeUnsafe,
+	InsertableObjectFromSchemaRecordUnsafe,
+	InsertableTreeFieldFromImplicitFieldUnsafe,
+	InsertableTypedNodeUnsafe,
+	NodeBuilderDataUnsafe,
+	NodeFromSchemaUnsafe,
+	ReadonlyMapInlined,
+	TreeNodeSchemaClassUnsafe,
+	TreeNodeSchemaUnsafe,
+	AllowedTypesUnsafe,
+	TreeNodeSchemaNonClassUnsafe,
+} from "./typesUnsafe.js";
+
+export type {
+	VerboseTreeNode,
+	ParseOptions,
+	VerboseTree,
+} from "./verboseTree.js";
+
+export type { EncodeOptions } from "./customTree.js";
+
+export type { ConciseTree } from "./conciseTree.js";
 
 export { TreeBeta, type NodeChangedData, type TreeChangeEventsBeta } from "./treeApiBeta.js";
 
+export {
+	extractPersistedSchema,
+	comparePersistedSchemaInternal,
+	comparePersistedSchema,
+} from "./storedSchema.js";
+
 // Exporting the schema (RecursiveObject) to test that recursive types are working correctly.
 // These are `@internal` so they can't be included in the `InternalClassTreeTypes` due to https://github.com/microsoft/rushstack/issues/3639
 export {

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

@@ -9,27 +9,29 @@ import { fail } from "../../util/index.js";
 
 import type { SchemaFactory, ScopedSchemaName } from "./schemaFactory.js";
 import type { NodeFromSchema } from "../schemaTypes.js";
-import type { NodeKind, TreeNodeSchemaClass, TreeNode } from "../core/index.js";
 import type {
-	InsertableObjectFromSchemaRecord,
-	ObjectFromSchemaRecord,
-} from "../objectNode.js";
-
-/**
- * Empty Object for use in type computations that should contribute no fields when `&`ed with another type.
- * @internal
+	InternalTreeNode,
+	NodeKind,
+	TreeNode,
+	TreeNodeSchemaClass,
+} from "../core/index.js";
+
+/*
+ * This file does two things:
+ *
+ * 1. Provides tools for making schema for cases like enums.
+ *
+ * 2. Demonstrates the kinds of schema utilities apps can write.
+ * Nothing in here needs access to package internal APIs.
  */
-// Using {} instead of interface {} or Record<string, never> for empty object here produces better IntelliSense in the generated types than `Record<string, never>` recommended by the linter.
-// Making this a type instead of an interface prevents it from showing up in IntelliSense, and also avoids breaking the typing somehow.
-// eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/consistent-type-definitions
-export type EmptyObject = {};
 
 /**
  * Create a schema for a node with no state.
  * @remarks
  * This is commonly used in unions when the only information needed is which kind of node the value is.
  * Enums are a common example of this pattern.
- * @internal
+ * @see {@link adaptEnum}
+ * @alpha
  */
 // Return type is intentionally derived.
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -38,7 +40,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 	name: TName,
 ) {
 	class SingletonSchema extends factory.object(name, {}) {
-		public constructor(data?: EmptyObject) {
+		public constructor(data?: InternalTreeNode) {
 			super(data ?? {});
 		}
 		public get value(): TName {
@@ -46,9 +48,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 		}
 	}
 
-	type NodeType = object &
-		TreeNode &
-		ObjectFromSchemaRecord<EmptyObject> & { readonly value: TName };
+	type NodeType = TreeNode & { readonly value: TName };
 
 	// Returning SingletonSchema without a type conversion results in TypeScript generating something like `readonly "__#124291@#brand": unknown;`
 	// for the private brand field of TreeNode.
@@ -59,7 +59,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 		ScopedSchemaName<TScope, TName>,
 		NodeKind.Object,
 		NodeType,
-		object & InsertableObjectFromSchemaRecord<EmptyObject>,
+		never,
 		true
 	> &
 		(new () => NodeType) = SingletonSchema;
@@ -71,33 +71,50 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * Converts an enum into a collection of schema which can be used in a union.
  * @remarks
  * Currently only supports `string` enums.
+ * The string value of the enum is used as the name of the schema: callers must ensure that it is stable and unique.
+ * Consider making a dedicated schema factory with a nested scope to avoid the enum members colliding with other schema.
  * @example
  * ```typescript
+ * const schemaFactory = new SchemaFactory("com.myApp");
+ * // An enum for use in the tree. Must have string keys.
  * enum Mode {
  * 	a = "A",
  * 	b = "B",
  * }
- * const ModeNodes = adaptEnum(schema, Mode);
+ * // Define the schema for each member of the enum using a nested scope to group them together.
+ * const ModeNodes = adaptEnum(new SchemaFactory(`${schemaFactory.scope}.Mode`), Mode);
+ * // Defined the types of the nodes which correspond to this the schema.
  * type ModeNodes = NodeFromSchema<(typeof ModeNodes)[keyof typeof ModeNodes]>;
- * const nodeFromString: ModeNodes = ModeNodes(Mode.a);
- * const nodeFromSchema: ModeNodes = new ModeNodes.a();
- * const nameFromNode: Mode = nodeFromSchema.value;
+ * // An example schema which has an enum as a child.
  * class Parent extends schemaFactory.object("Parent", {
+ * 	// typedObjectValues extracts a list of all the fields of ModeNodes, which are the schema for each enum member.
+ * 	// This means any member of the enum is allowed in this field.
  * 	mode: typedObjectValues(ModeNodes),
  * }) {}
+ *
+ * // Example usage of enum-based nodes, showing what type to use and that `.value` can be used to read out the enum value.
+ * function getValue(node: ModeNodes): Mode {
+ * 	return node.value;
+ * }
+ *
+ * // Example constructing a tree containing an enum node from an enum value.
+ * // The syntax `new ModeNodes.a()` is also supported.
+ * function setValue(node: Parent): void {
+ * 	node.mode = ModeNodes(Mode.a);
+ * }
  * ```
  * @privateRemarks
  * TODO:
- * Extends this to support numeric enums.
- * Maybe require an explicit nested scope to group them under, or at least a warning about collisions.
- * Maybe just provide `SchemaFactory.nested` to east creating nested scopes?
- * @internal
+ * Extend this to support numeric enums.
+ * Maybe provide `SchemaFactory.nested` to ease creating nested scopes?
+ * @see {@link enumFromStrings} for a similar function that works on arrays of strings instead of an enum.
+ * @alpha
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-export function adaptEnum<TScope extends string, const TEnum extends Record<string, string>>(
-	factory: SchemaFactory<TScope>,
-	members: TEnum,
-) {
+export function adaptEnum<
+	TScope extends string,
+	const TEnum extends Record<string, string | number>,
+>(factory: SchemaFactory<TScope>, members: TEnum) {
 	type Values = TEnum[keyof TEnum];
 	const values = Object.values(members) as Values[];
 	const inverse = new Map(Object.entries(members).map(([key, value]) => [value, key])) as Map<
@@ -116,7 +133,7 @@ export function adaptEnum<TScope extends string, const TEnum extends Record<stri
 	};
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	const factoryOut = <TValue extends Values>(value: TValue) => {
-		return new out[inverse.get(value) ?? fail("missing enum value")]({}) as NodeFromSchema<
+		return new out[inverse.get(value) ?? fail("missing enum value")]() as NodeFromSchema<
 			ReturnType<typeof singletonSchema<TScope, TValue>>
 		>;
 	};
@@ -135,7 +152,9 @@ export function adaptEnum<TScope extends string, const TEnum extends Record<stri
 
 /**
  * `Object.values`, but with more specific types.
- * @internal
+ * @remarks
+ * Useful with collections of schema, like those returned by {@link adaptEnum} or {@link enumFromStrings}.
+ * @alpha
  */
 export function typedObjectValues<TKey extends string, TValues>(
 	object: Record<TKey, TValues>,
@@ -160,7 +179,8 @@ export function typedObjectValues<TKey extends string, TValues>(
  *
  * class Parent extends schemaFactory.object("Parent", { mode: typedObjectValues(Mode) }) {}
  * ```
- * @internal
+ * @see {@link adaptEnum} for a similar function that works on enums instead of arrays of strings.
+ * @alpha
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function enumFromStrings<TScope extends string, const Members extends string>(
@@ -175,7 +195,7 @@ export function enumFromStrings<TScope extends string, const Members extends str
 	type TOut = Record<Members, ReturnType<typeof singletonSchema<TScope, Members>>>;
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	const factoryOut = <TValue extends Members>(value: TValue) => {
-		return new out[value]({}) as NodeFromSchema<
+		return new out[value]() as NodeFromSchema<
 			ReturnType<typeof singletonSchema<TScope, TValue>>
 		>;
 	};
@@ -192,8 +212,7 @@ export function enumFromStrings<TScope extends string, const Members extends str
 	return out;
 }
 
-// TODO: Why does this one generate an invalid d.ts file if exported?
-// Tracked by https://github.com/microsoft/TypeScript/issues/58688
+// TODO: This generates an invalid d.ts file if exported due to a bug https://github.com/microsoft/TypeScript/issues/58688.
 // TODO: replace enumFromStrings above with this simpler implementation when the TypeScript bug is resolved.
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 function _enumFromStrings2<TScope extends string, const Members extends readonly string[]>(

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

@@ -12,11 +12,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
 import type { TreeValue } from "../../core/index.js";
-import {
-	type NodeKeyManager,
-	type Unenforced,
-	isLazy,
-} from "../../feature-libraries/index.js";
+import type { NodeKeyManager } from "../../feature-libraries/index.js";
 import {
 	type RestrictiveStringRecord,
 	getOrCreate,
@@ -73,9 +69,11 @@ import type {
 	TreeArrayNodeUnsafe,
 	TreeMapNodeUnsafe,
 	TreeObjectNodeUnsafe,
-} from "../typesUnsafe.js";
+	Unenforced,
+} from "./typesUnsafe.js";
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
 import { TreeNodeValid } from "../treeNodeValid.js";
+import { isLazy } from "../flexList.js";
 /**
  * Gets the leaf domain schema compatible with a given {@link TreeValue}.
  */

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

@@ -3,7 +3,6 @@
  * Licensed under the MIT License.
  */
 
-import type { Unenforced } from "../../feature-libraries/index.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
 import type { InsertableObjectFromSchemaRecord } from "../objectNode.js";
 
@@ -22,7 +21,7 @@ import type {
 	WithType,
 	TreeNode,
 } from "../core/index.js";
-import type { FieldSchemaUnsafe } from "../typesUnsafe.js";
+import type { FieldSchemaUnsafe, Unenforced } from "./typesUnsafe.js";
 
 export function createFieldSchemaUnsafe<
 	Kind extends FieldKind,

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/tree.ts

@@ -11,11 +11,14 @@ import type { Listenable } from "../../events/index.js";
 
 import {
 	type ImplicitFieldSchema,
+	type InsertableField,
 	type InsertableTreeFieldFromImplicitField,
 	type TreeFieldFromImplicitField,
+	type TreeLeafValue,
+	type UnsafeUnknownSchema,
 	FieldKind,
 } from "../schemaTypes.js";
-import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import { NodeKind, type TreeNode, type TreeNodeSchema } from "../core/index.js";
 import { toStoredSchema } from "../toFlexSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
 import { assert } from "@fluidframework/core-utils/internal";
@@ -363,7 +366,7 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
  * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.
  * @sealed @public
  */
-export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposable {
+export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {
 	/**
 	 * The current root of the tree.
 	 *
@@ -424,6 +427,25 @@ export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposab
 	readonly schema: TSchema;
 }
 
+/**
+ * {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.
+ * @alpha
+ */
+export interface TreeViewAlpha<
+	in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
+> extends Omit<
+		TreeView<TSchema extends ImplicitFieldSchema ? TSchema : ImplicitFieldSchema>,
+		"root" | "initialize"
+	> {
+	get root(): TSchema extends ImplicitFieldSchema
+		? TreeFieldFromImplicitField<TSchema>
+		: TreeLeafValue | TreeNode;
+
+	set root(newRoot: InsertableField<TSchema>);
+
+	initialize(content: InsertableField<TSchema>): void;
+}
+
 /**
  * Information about a view schema's compatibility with the document's stored schema.
  *

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.