@fluidframework/tree 2.1.0 → 2.3.0-288113

package/src/shared-tree/sharedTreeEditBuilder.ts

@@ -15,7 +15,6 @@ import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 /**
  * Editor for schema changes.
  * The only currently supported operation is to replace the stored schema.
- * @internal
  */
 export interface ISchemaEditor {
 	/**
@@ -28,7 +27,6 @@ export interface ISchemaEditor {
 
 /**
  * SharedTree editor for transactional tree data and schema changes.
- * @internal
  */
 export interface ISharedTreeEditor extends IDefaultEditBuilder {
 	/**

package/src/shared-tree/treeApi.ts

@@ -11,7 +11,7 @@ import {
 	type TreeNode,
 	type TreeNodeApi,
 	type TreeView,
-	getFlexNode,
+	getOrCreateInnerNode,
 	treeNodeApi,
 } from "../simple-tree/index.js";
 import { fail } from "../util/index.js";
@@ -435,7 +435,7 @@ export function runTransaction<
 	} else {
 		const node = treeOrNode as TNode;
 		const t = transaction as (node: TNode) => TResult | typeof rollback;
-		const context = getFlexNode(node).context;
+		const context = getOrCreateInnerNode(node).context;
 		assert(context instanceof Context, 0x901 /* Unsupported context */);
 		const treeView =
 			contextToTreeView.get(context) ?? fail("Expected view to be registered for context");
@@ -453,7 +453,7 @@ function runTransactionInCheckout<TResult>(
 	for (const constraint of preconditions) {
 		switch (constraint.type) {
 			case "nodeInDocument": {
-				const node = getFlexNode(constraint.node);
+				const node = getOrCreateInnerNode(constraint.node);
 				assert(
 					treeApi.status(constraint.node) === TreeStatus.InDocument,
 					0x90f /* Attempted to apply "nodeExists" constraint when building a transaction, but the node is not in the document. */,

package/src/shared-tree/treeCheckout.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import {
 	UsageError,
@@ -61,7 +61,6 @@ import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditB
 
 /**
  * Events for {@link ITreeCheckout}.
- * @internal
  */
 export interface CheckoutEvents {
 	/**
@@ -110,7 +109,6 @@ export type RevertibleFactory = (
  * @privateRemarks
  * API for interacting with a {@link SharedTreeBranch}.
  * Implementations of this interface must implement the {@link branchKey} property.
- * @internal
  */
 export interface ITreeCheckout extends AnchorLocator {
 	/**
@@ -278,7 +276,6 @@ export function createTreeCheckout(
  *
  * To avoid updating observers of the view state with intermediate results during a transaction,
  * use {@link ITreeCheckout#fork} and {@link ISharedTreeFork#merge}.
- * @internal
  */
 export interface ITransaction {
 	/**
@@ -342,7 +339,6 @@ class Transaction implements ITransaction {
  * Branch (like in a version control system) of SharedTree.
  *
  * {@link ITreeCheckout} that has forked off of the main trunk/branch.
- * @internal
  */
 export interface ITreeCheckoutFork extends ITreeCheckout, IDisposable {
 	/**
@@ -441,7 +437,9 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			if (event.change !== undefined) {
 				const revision =
 					event.type === "replace"
-						? event.newCommits[event.newCommits.length - 1].revision
+						? // Change events will always contain new commits
+							// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+							event.newCommits[event.newCommits.length - 1]!.revision
 						: event.change.revision;
 
 				// Conflicts due to schema will be empty and thus are not applied.
@@ -475,7 +473,8 @@ export class TreeCheckout implements ITreeCheckoutFork {
 				this.events.emit("afterBatch");
 			}
 			if (event.type === "replace" && getChangeReplaceType(event) === "transactionCommit") {
-				const transactionRevision = event.newCommits[0].revision;
+				const firstCommit = event.newCommits[0] ?? oob();
+				const transactionRevision = firstCommit.revision;
 				for (const transactionStep of event.removedCommits) {
 					this.removedRoots.updateMajor(transactionStep.revision, transactionRevision);
 				}
@@ -749,7 +748,6 @@ export class TreeCheckout implements ITreeCheckoutFork {
  * @param transaction - the transaction function. This will be executed immediately. It is passed `view` as an argument for convenience.
  * If this function returns an `Abort` result then the transaction will be aborted. Otherwise, it will be committed.
  * @returns whether or not the transaction was committed or aborted
- * @internal
  */
 export function runSynchronous(
 	view: ITreeCheckout,

package/src/shared-tree/treeView.ts

@@ -15,13 +15,12 @@ import {
 import { tryDisposeTreeNode } from "../simple-tree/index.js";
 import { type IDisposable, disposeSymbol } from "../util/index.js";
 
-import type { ITreeCheckout, ITreeCheckoutFork, TreeCheckout } from "./treeCheckout.js";
+import type { ITreeCheckout, ITreeCheckoutFork } from "./treeCheckout.js";
 
 /**
  * The portion of {@link FlexTreeView} that does not depend on the schema's type.
  * @privateRemarks
  * Since {@link FlexTreeView}'s schema is invariant, `FlexTreeView<FlexFieldSchema>` does not cover this use case.
- * @internal
  */
 export interface FlexTreeViewGeneric extends IDisposable {
 	/**
@@ -46,7 +45,6 @@ export interface FlexTreeViewGeneric extends IDisposable {
  * @privateRemarks
  * TODO:
  * If schema aware APIs are removed from flex tree, this can be combined with {@link FlexTreeViewGeneric}.
- * @internal
  */
 export interface FlexTreeView<in out TRoot extends FlexFieldSchema>
 	extends FlexTreeViewGeneric {
@@ -66,7 +64,6 @@ export interface FlexTreeView<in out TRoot extends FlexFieldSchema>
  * Branch (like in a version control system) of SharedTree.
  *
  * {@link FlexTreeView} that has forked off of the main trunk/branch.
- * @internal
  */
 export interface ITreeViewFork<in out TRoot extends FlexFieldSchema>
 	extends FlexTreeView<TRoot> {
@@ -78,7 +75,7 @@ export interface ITreeViewFork<in out TRoot extends FlexFieldSchema>
  */
 export class CheckoutFlexTreeView<
 	in out TRoot extends FlexFieldSchema,
-	out TCheckout extends TreeCheckout = TreeCheckout,
+	out TCheckout extends ITreeCheckout = ITreeCheckout,
 > implements FlexTreeView<TRoot>
 {
 	public readonly context: Context;
@@ -103,7 +100,7 @@ export class CheckoutFlexTreeView<
 		this.onDispose?.();
 	}
 
-	public fork(): CheckoutFlexTreeView<TRoot, TreeCheckout & ITreeCheckoutFork> {
+	public fork(): CheckoutFlexTreeView<TRoot, ITreeCheckout & ITreeCheckoutFork> {
 		const branch = this.checkout.fork();
 		return new CheckoutFlexTreeView(branch, this.schema, this.nodeKeyManager);
 	}

package/src/shared-tree-core/branch.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import { type TelemetryEventBatcher, measure } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -26,6 +26,7 @@ import {
 import { EventEmitter, type Listenable } from "../events/index.js";
 
 import { TransactionStack } from "./transactionStack.js";
+import { fail } from "../util/index.js";
 
 /**
  * Describes a change to a `SharedTreeBranch`. Various operations can mutate the head of the branch;
@@ -80,6 +81,14 @@ export function getChangeReplaceType(
 	// └─ B' (branch Y)                                └─ (branch Y)
 	//
 	// B' is removed and replaced by B because both have the same revision.
+	assert(
+		change.removedCommits[0] !== undefined,
+		0x9e4 /* This wont run due to the length check above */,
+	);
+	assert(
+		change.newCommits[0] !== undefined,
+		0x9e5 /* This wont run because a replace operation always has new commits */,
+	);
 	if (
 		change.removedCommits.length === 1 &&
 		change.removedCommits[0].revision === change.newCommits[0].revision
@@ -375,13 +384,15 @@ export class SharedTreeBranch<
 		const inverses: TaggedChange<TChange>[] = [];
 		for (let i = commits.length - 1; i >= 0; i--) {
 			const revision = this.mintRevisionTag();
+			const commit =
+				commits[i] ?? fail("This wont run because we are iterating through commits");
 			const inverse = this.changeFamily.rebaser.changeRevision(
-				this.changeFamily.rebaser.invert(commits[i], false),
+				this.changeFamily.rebaser.invert(commit, false),
 				revision,
-				commits[i].revision,
+				commit.revision,
 			);
 
-			inverses.push(tagRollbackInverse(inverse, revision, commits[i].revision));
+			inverses.push(tagRollbackInverse(inverse, revision, commit.revision));
 		}
 		const change =
 			inverses.length > 0 ? this.changeFamily.rebaser.compose(inverses) : undefined;
@@ -410,8 +421,7 @@ export class SharedTreeBranch<
 		const { startRevision: startRevisionOriginal } = this.transactions.pop();
 		let startRevision = startRevisionOriginal;
 		while (this.initialTransactionRevToRebasedRev.has(startRevision)) {
-			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-			startRevision = this.initialTransactionRevToRebasedRev.get(startRevision)!;
+			startRevision = this.initialTransactionRevToRebasedRev.get(startRevision) ?? oob();
 		}
 
 		if (!this.isTransacting()) {
@@ -474,8 +484,10 @@ export class SharedTreeBranch<
 
 		const newCommits = targetCommits.concat(sourceCommits);
 		if (this.isTransacting()) {
-			const src = targetCommits[0].parent?.revision;
-			const dst = targetCommits[targetCommits.length - 1].revision;
+			const firstCommit = targetCommits[0] ?? oob();
+			const lastCommit = targetCommits[targetCommits.length - 1] ?? oob();
+			const src = firstCommit.parent?.revision;
+			const dst = lastCommit.revision;
 			if (src !== undefined && dst !== undefined) {
 				this.initialTransactionRevToRebasedRev.set(src, dst);
 			}

package/src/shared-tree-core/defaultResubmitMachine.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import type { ChangeRebaser, GraphCommit } from "../core/index.js";
 import { disposeSymbol } from "../util/index.js";
 import type { ChangeEnricherReadonlyCheckout, ResubmitMachine } from "./index.js";
@@ -74,7 +74,7 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 			const checkout = this.tip.fork();
 			// Roll back the checkout to the state before the oldest commit
 			for (let iCommit = toResubmit.length - 1; iCommit >= 0; iCommit -= 1) {
-				const commit = toResubmit[iCommit];
+				const commit = toResubmit[iCommit] ?? oob();
 				const rollback = this.inverter(commit, true);
 				// WARNING: it's not currently possible to roll back past a schema change (see AB#7265).
 				// Either we have to make it possible to do so, or this logic will have to change to work
@@ -87,7 +87,7 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 				iCommit <= this.latestInFlightCommitWithStaleEnrichments;
 				iCommit += 1
 			) {
-				const commit = toResubmit[iCommit];
+				const commit = toResubmit[iCommit] ?? oob();
 				const enrichedChange = checkout.updateChangeEnrichments(
 					commit.change,
 					commit.revision,
@@ -114,7 +114,7 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 			this.isInResubmitPhase,
 			0x982 /* No available commit to resubmit outside of resubmit phase */,
 		);
-		return this.resubmitQueue[0];
+		return this.resubmitQueue[0] ?? oob();
 	}
 
 	public get isInResubmitPhase(): boolean {

package/src/shared-tree-core/editManagerCodecs.ts

@@ -72,6 +72,7 @@ export function makeEditManagerCodecs<TChangeset>(
 		[1, makeV1CodecWithVersion(changeCodecs.resolve(1), revisionTagCodec, options, 1)],
 		[2, makeV1CodecWithVersion(changeCodecs.resolve(2), revisionTagCodec, options, 2)],
 		[3, makeV1CodecWithVersion(changeCodecs.resolve(3), revisionTagCodec, options, 3)],
+		[4, makeV1CodecWithVersion(changeCodecs.resolve(4), revisionTagCodec, options, 4)],
 	]);
 }
 

package/src/shared-tree-core/editManagerFormat.ts

@@ -98,13 +98,18 @@ const SummarySessionBranch = <ChangeSchema extends TSchema>(tChange: ChangeSchem
 export interface EncodedEditManager<TChangeset> {
 	readonly trunk: readonly Readonly<SequencedCommit<TChangeset>>[];
 	readonly branches: readonly [SessionId, Readonly<EncodedSummarySessionBranch<TChangeset>>][];
-	readonly version: 1 | 2 | 3;
+	readonly version: 1 | 2 | 3 | 4;
 }
 
 export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 	Type.Object(
 		{
-			version: Type.Union([Type.Literal(1), Type.Literal(2), Type.Literal(3)]),
+			version: Type.Union([
+				Type.Literal(1),
+				Type.Literal(2),
+				Type.Literal(3),
+				Type.Literal(4),
+			]),
 			trunk: Type.Array(SequencedCommit(tChange)),
 			branches: Type.Array(Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange)])),
 		},

package/src/shared-tree-core/messageCodecs.ts

@@ -76,6 +76,7 @@ export function makeMessageCodecs<TChangeset>(
 		[1, v1Codec],
 		[2, makeV1CodecWithVersion(changeCodecs.resolve(2).json, revisionTagCodec, options, 2)],
 		[3, makeV1CodecWithVersion(changeCodecs.resolve(3).json, revisionTagCodec, options, 3)],
+		[4, makeV1CodecWithVersion(changeCodecs.resolve(4).json, revisionTagCodec, options, 4)],
 	]);
 }
 
@@ -88,7 +89,7 @@ function makeV1CodecWithVersion<TChangeset>(
 		ChangeEncodingContext
 	>,
 	options: ICodecOptions,
-	version: 1 | 2 | 3,
+	version: 1 | 2 | 3 | 4,
 ): IJsonCodec<
 	DecodedMessage<TChangeset>,
 	JsonCompatibleReadOnly,

package/src/shared-tree-core/sharedTreeCore.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import type {
 	IChannelAttributes,
 	IFluidDataStoreRuntime,
@@ -214,7 +214,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 					change.newCommits.length === 1,
 					0x983 /* Unexpected number of commits when committing transaction */,
 				);
-				this.commitEnricher.prepareCommit(change.newCommits[0], true);
+				this.commitEnricher.prepareCommit(change.newCommits[0] ?? oob(), true);
 			}
 		});
 		this.editManager.localBranch.on("afterChange", (change) => {
@@ -455,7 +455,9 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			for (const [id, routes] of Object.entries(s.getGCData(fullGC).gcNodes)) {
 				gcNodes[id] ??= [];
 				for (const route of routes) {
-					gcNodes[id].push(route);
+					// Non null asserting here because we are creating an array at gcNodes[id] if it is undefined
+					// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+					gcNodes[id]!.push(route);
 				}
 			}
 		}

package/src/simple-tree/ProxyBinding.md

@@ -24,6 +24,8 @@ This feature is supported by doing some bookkeeping to ensure that the proxy obj
 flex tree nodes and anchor nodes in the tree get associated and disassociated at the right times.
 There are three states that a node proxy can be in: "raw", "marinated" and "cooked".
 
+Note from the public API perspective, `Unhydrated` nodes are "raw", and hydrated nodes are either "marinated" or "cooked".
+
 ### Raw Proxies
 
 A newly created proxy, a.k.a. a **raw** proxy. A raw proxy is produced by invoking the schema-provided constructor for a node:

package/src/simple-tree/api/README.md

@@ -0,0 +1,7 @@
+# simple-tree api
+
+simple-tree content which exists only to implement the public API.
+
+Content in this folder should not be imported from other simple-tree content.
+
+Not all public API types belong here: only ones that the rest of simple tree does not need to depend on for its implementation.

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

@@ -0,0 +1,179 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils/internal";
+
+import type { ITreeCursorSynchronous, SchemaAndPolicy } from "../../core/index.js";
+import { fail } from "../../util/index.js";
+import type {
+	TreeLeafValue,
+	ImplicitFieldSchema,
+	InsertableTreeFieldFromImplicitField,
+	TreeFieldFromImplicitField,
+	FieldSchema,
+	FieldKind,
+} from "../schemaTypes.js";
+import type { Unhydrated } from "../core/index.js";
+import {
+	cursorForMapTreeNode,
+	defaultSchemaPolicy,
+	FieldKinds,
+	intoStoredSchema,
+	mapTreeFromCursor,
+	type NodeKeyManager,
+} from "../../feature-libraries/index.js";
+import { getOrCreateNodeFromFlexTreeNode, type InsertableContent } from "../proxies.js";
+import { getOrCreateMapTreeNode, isFieldInSchema } from "../../feature-libraries/index.js";
+import { toFlexSchema } from "../toFlexSchema.js";
+import { inSchemaOrThrow, mapTreeFromNodeData } from "../toMapTree.js";
+import {
+	applySchemaToParserOptions,
+	cursorFromVerbose,
+	type ParseOptions,
+	type VerboseTree,
+	type VerboseTreeNode,
+} from "./verboseTree.js";
+
+/**
+ * Construct tree content that is compatible with the field defined by the provided `schema`.
+ * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
+ * @param data - The data used to construct the field content.
+ * @remarks
+ * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.
+ * This function exists as a generalization that can be used in other cases as well,
+ * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.
+ *
+ * Like with {@link TreeNodeSchemaClass}'s constructor, its an error to provide an existing node to this API.
+ * TODO: For that case, use we should provide `Tree.clone`.
+ * @privateRemarks
+ * This could be exposed as a public `Tree.create` function.
+ */
+export function createFromInsertable<TSchema extends ImplicitFieldSchema>(
+	schema: TSchema,
+	data: InsertableTreeFieldFromImplicitField<TSchema>,
+	context?: NodeKeyManager | undefined,
+): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+	const cursor = cursorFromInsertable(schema, data, context);
+	const result = cursor === undefined ? undefined : createFromCursor(schema, cursor);
+	return result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+}
+
+/**
+ * Construct tree content that is compatible with the field defined by the provided `schema`.
+ * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
+ * @param data - The data used to construct the field content.
+ * @remarks
+ * When providing a {@link TreeNodeSchemaClass},
+ * this is the same as invoking its constructor except that an unhydrated node can also be provided and the returned value is a cursor.
+ * When `undefined` is provided (for an optional field), `undefined` is returned.
+ */
+export function cursorFromInsertable<TSchema extends ImplicitFieldSchema>(
+	schema: TSchema,
+	data: InsertableTreeFieldFromImplicitField<TSchema>,
+	context?: NodeKeyManager | undefined,
+):
+	| ITreeCursorSynchronous
+	| (TSchema extends FieldSchema<FieldKind.Optional> ? undefined : never) {
+	const flexSchema = toFlexSchema(schema);
+	const schemaValidationPolicy: SchemaAndPolicy = {
+		policy: defaultSchemaPolicy,
+		// TODO: optimize: This isn't the most efficient operation since its not cached, and has to convert all the schema.
+		schema: intoStoredSchema(flexSchema),
+	};
+
+	const mapTree = mapTreeFromNodeData(
+		data as InsertableContent | undefined,
+		schema,
+		context,
+		schemaValidationPolicy,
+	);
+	if (mapTree === undefined) {
+		assert(
+			flexSchema.rootFieldSchema.kind === FieldKinds.optional,
+			0xa10 /* missing non-optional field */,
+		);
+		return undefined as TSchema extends FieldSchema<FieldKind.Optional> ? undefined : never;
+	}
+	return cursorForMapTreeNode(mapTree);
+}
+
+/**
+ * Construct tree content compatible with a field defined by the provided `schema`.
+ * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
+ * @param data - The data used to construct the field content. See `Tree.cloneToJSONVerbose`.
+ * @privateRemarks
+ * This could be exposed as a public `Tree.createFromVerbose` function.
+ */
+export function createFromVerbose<TSchema extends ImplicitFieldSchema, THandle>(
+	schema: TSchema,
+	data: VerboseTreeNode<THandle> | undefined,
+	options: ParseOptions<THandle>,
+): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+
+/**
+ * Construct tree content compatible with a field defined by the provided `schema`.
+ * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
+ * @param data - The data used to construct the field content. See `Tree.cloneToJSONVerbose`.
+ */
+export function createFromVerbose<TSchema extends ImplicitFieldSchema>(
+	schema: TSchema,
+	data: VerboseTreeNode | undefined,
+	options?: Partial<ParseOptions<IFluidHandle>>,
+): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+
+export function createFromVerbose<TSchema extends ImplicitFieldSchema, THandle>(
+	schema: TSchema,
+	data: VerboseTreeNode<THandle> | undefined,
+	options?: Partial<ParseOptions<THandle>>,
+): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+	const config: ParseOptions<THandle> = {
+		valueConverter: (input: VerboseTree<THandle>) => {
+			return input as TreeLeafValue | VerboseTreeNode<THandle>;
+		},
+		...options,
+	};
+	const schemalessConfig = applySchemaToParserOptions(schema, config);
+	const cursor = cursorFromVerbose(data, schemalessConfig);
+	return createFromCursor(schema, cursor);
+}
+
+/**
+ * Creates an unhydrated simple-tree field from a cursor in nodes mode.
+ */
+export function createFromCursor<TSchema extends ImplicitFieldSchema>(
+	schema: TSchema,
+	cursor: ITreeCursorSynchronous | undefined,
+): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+	const mapTrees = cursor === undefined ? [] : [mapTreeFromCursor(cursor)];
+	const flexSchema = toFlexSchema(schema);
+
+	const schemaValidationPolicy: SchemaAndPolicy = {
+		policy: defaultSchemaPolicy,
+		// TODO: optimize: This isn't the most efficient operation since its not cached, and has to convert all the schema.
+		schema: intoStoredSchema(flexSchema),
+	};
+
+	const maybeError = isFieldInSchema(
+		mapTrees,
+		flexSchema.rootFieldSchema.stored,
+		schemaValidationPolicy,
+	);
+	inSchemaOrThrow(maybeError);
+
+	if (mapTrees.length === 0) {
+		return undefined as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+	}
+	assert(mapTrees.length === 1, 0xa11 /* unexpected field length */);
+	// Length asserted above, so this is safe. This assert is done instead of checking for undefined after indexing to ensure a length greater than 1 also errors.
+	// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+	const mapTree = mapTrees[0]!;
+	const rootSchema = flexSchema.nodeSchema.get(mapTree.type) ?? fail("missing schema");
+	const mapTreeNode = getOrCreateMapTreeNode(rootSchema, mapTree);
+
+	// TODO: ensure this works for InnerNodes to create unhydrated nodes
+	const result = getOrCreateNodeFromFlexTreeNode(mapTreeNode);
+	return result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+}

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

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	type ITree,
+	type TreeView,
+	type TreeViewEvents,
+	TreeViewConfiguration,
+	type ITreeViewConfiguration,
+	type SchemaCompatibilityStatus,
+	type ITreeConfigurationOptions,
+} from "./tree.js";
+export { SchemaFactory, type ScopedSchemaName } from "./schemaFactory.js";
+export type {
+	ValidateRecursiveSchema,
+	FixRecursiveArraySchema,
+} from "./schemaFactoryRecursive.js";
+export {
+	adaptEnum,
+	enumFromStrings,
+	singletonSchema,
+	typedObjectValues,
+	type EmptyObject,
+} from "./schemaCreationUtilities.js";
+export { treeNodeApi, type TreeNodeApi } from "./treeNodeApi.js";
+export { createFromInsertable, cursorFromInsertable } from "./create.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 {
+	RecursiveObject as test_RecursiveObject,
+	base as test_RecursiveObject_base,
+	RecursiveObjectPojoMode as test_RecursiveObjectPojoMode,
+} from "./testRecursiveDomain.js";

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

@@ -5,16 +5,24 @@
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { EmptyObject } from "../feature-libraries/index.js";
-import { fail } from "../util/index.js";
+import { fail } from "../../util/index.js";
 
 import type { SchemaFactory, ScopedSchemaName } from "./schemaFactory.js";
-import type { NodeFromSchema, NodeKind, TreeNodeSchemaClass } from "./schemaTypes.js";
-import type { TreeNode } from "./types.js";
+import type { NodeFromSchema } from "../schemaTypes.js";
+import type { NodeKind, TreeNodeSchemaClass, TreeNode } from "../core/index.js";
 import type {
 	InsertableObjectFromSchemaRecord,
 	ObjectFromSchemaRecord,
-} from "./objectNode.js";
+} from "../objectNode.js";
+
+/**
+ * Empty Object for use in type computations that should contribute no fields when `&`ed with another type.
+ * @internal
+ */
+// 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.