@fluidframework/tree 2.4.0 → 2.5.0

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

@@ -53,6 +53,14 @@ const minimumPossibleSequenceId: SequenceId = {
 	sequenceNumber: minimumPossibleSequenceNumber,
 };
 
+/**
+ * A special revision tag for the initial {@link EditManager.trunkBase} commit.
+ * @remarks This tag is used to supply the _initial_ trunk base with a known revision.
+ * The trunk base may advance over time, after which point the trunk base will have a different revision.
+ * When {@link EditManager.getSummaryData | serializing} and deserializing, peer branches that include the trunk base commit in their history will always use this tag.
+ */
+const rootRevision = "root" as const satisfies RevisionTag;
+
 /**
  * Max number of telemetry log call that may be aggregated before being sent.
  */
@@ -152,7 +160,7 @@ export class EditManager<
 		logger?: ITelemetryLoggerExt,
 	) {
 		this.trunkBase = {
-			revision: "root",
+			revision: rootRevision,
 			change: changeFamily.rebaser.compose([]),
 		};
 		this.sequenceMap.set(minimumPossibleSequenceId, this.trunkBase);
@@ -262,30 +270,62 @@ export class EditManager<
 	}
 
 	/**
-	 * Updates the `trunkBranches` map to reflect the fact that a new local commit was fast-forwarded to the trunk.
-	 * @param priorTrunkCommit - The trunk head prior to the fast-forward.
-	 * @param newId - The ID of the new trunk head.
+	 * Promote the oldest un-sequenced commit on the local branch to the head of the trunk.
+	 * @param sequenceId - The sequence id of the new trunk commit
+	 * @remarks This method is a performance optimization for the scenario where this client receives its own change back after sequencing.
+	 * The normal (not optimized) process in this case would be to apply the new sequenced commit to the trunk and then rebase the local branch over the trunk.
+	 * The first commit will be "the same" (as in, it will have the same revision) as the commit that was just sequenced, so the rebase will be a no-op.
+	 * Because the rebase is a no-op, we can skip it entirely and simply remove the commit from the local branch and append it to the trunk.
+	 * Avoiding the overhead of the rebase process, even when it's a no-op, has real measured performance benefits and is worth the added complexity here.
 	 */
-	private fastForwardBranches(
-		priorTrunkCommit: GraphCommit<TChangeset>,
-		newId: SequenceId,
-	): void {
-		const currentId = this.getCommitSequenceId(priorTrunkCommit);
-		const currentBranches = this.trunkBranches.get(currentId);
+	private fastForwardNextLocalCommit(sequenceId: SequenceId): void {
+		// First, push the local commit to the trunk.
+		// We are mutating our `localCommits` cache here, but there is no need to actually change the `localBranch` itself because it will simply catch up later if/when it next rebases.
+		const firstLocalCommit = this.localCommits.shift();
+		assert(
+			firstLocalCommit !== undefined,
+			0x6b5 /* Received a sequenced change from the local session despite having no local changes */,
+		);
+
+		const previousSequenceId = this.getCommitSequenceId(this.trunk.getHead());
+		this.pushGraphCommitToTrunk(sequenceId, firstLocalCommit, this.localSessionId);
+
+		// Next, we need to update the sequence IDs that our local branches (user's branches, not peer branches) are associated with.
+		// In particular, if a local branch is based on the previous trunk head (the branch's first ancestor in the trunk is the commit that was the head before we pushed the new commit)
+		// and also branches off of the local branch (it has an ancestor that is part of the local branch), it needs to have its sequence number advanced to be that of the new trunk head.
+		// Intuitively, this makes sense because:
+		// 1. The trunk's head just advanced forward by some (sequence) amount.
+		// 2. The local branch is always rebased to be branching off of the head of the trunk (not literally in this case, because of the optimization, but in effect).
+		// 3. Therefore, the entire local branch just advanced forward by some (sequence) amount, and any commits downstream of it which track the sequence numbers of their base commits on the trunk should also advance.
+		// This update is not necessarily required for all local branches, since some may have fallen behind the local branch and are based on older trunk commits (such branches do not need updating).
+		const currentBranches = this.trunkBranches.get(previousSequenceId);
 		if (currentBranches !== undefined) {
-			const newBranches = getOrCreate(this.trunkBranches, newId, () => new Set());
+			const newBranches = getOrCreate(this.trunkBranches, sequenceId, () => new Set());
 			for (const branch of currentBranches) {
-				if (branch.getHead() !== priorTrunkCommit) {
+				// Check every branch associated with the old sequence ID and advance it if it is based on the local branch (specifically, on the local branch as it was before we pushed its first commit to the trunk).
+				// We validate this by checking if the branch's head is a descendant of the local commit that we just pushed.
+				if (findAncestor(branch.getHead(), (c) => c === firstLocalCommit) !== undefined) {
 					newBranches.add(branch);
 					currentBranches.delete(branch);
 				}
 			}
+			// Clean up our trunk branches map by removing any empty sets.
 			if (currentBranches.size === 0) {
-				this.trunkBranches.delete(currentId);
+				this.trunkBranches.delete(previousSequenceId);
+			}
+			if (newBranches.size === 0) {
+				this.trunkBranches.delete(sequenceId);
 			}
 		}
 	}
 
+	/**
+	 * Return the sequence number at which the given commit was sequenced on the trunk, or undefined if the commit is not part of the trunk.
+	 */
+	public getSequenceNumber(trunkCommit: GraphCommit<TChangeset>): SeqNumber | undefined {
+		return this.trunkMetadata.get(trunkCommit.revision)?.sequenceId.sequenceNumber;
+	}
+
 	/**
 	 * Advances the minimum sequence number, and removes all commits from the trunk which lie outside the collaboration window,
 	 * if they are not retained by revertibles or local branches.
@@ -293,7 +333,10 @@ export class EditManager<
 	 *
 	 * @remarks If there are more than one commit with the same sequence number we assume this refers to the last commit in the batch.
 	 */
-	public advanceMinimumSequenceNumber(minimumSequenceNumber: SeqNumber): void {
+	public advanceMinimumSequenceNumber(
+		minimumSequenceNumber: SeqNumber,
+		trimTrunk = true,
+	): void {
 		if (minimumSequenceNumber === this.minimumSequenceNumber) {
 			return;
 		}
@@ -304,16 +347,17 @@ export class EditManager<
 		);
 
 		this.minimumSequenceNumber = minimumSequenceNumber;
-		this.trimTrunk();
+		if (trimTrunk) {
+			this.trimTrunk();
+		}
 	}
 
 	/**
 	 * Examines the latest known minimum sequence number and the trunk bases of any registered branches to determine
 	 * if any commits on the trunk are unreferenced and unneeded for future computation; those found are evicted from the trunk.
-	 * @returns the number of commits that were removed from the trunk
 	 */
 	private trimTrunk(): void {
-		/** The sequence id of the oldest commit on the trunk that will be retained */
+		/** The sequence id of the most recent commit on the trunk that will be trimmed */
 		let trunkTailSequenceId: SequenceId = {
 			sequenceNumber: this.minimumSequenceNumber,
 			indexInBatch: Number.POSITIVE_INFINITY,
@@ -363,34 +407,45 @@ export class EditManager<
 				newTrunkBase,
 				this.trunkBase,
 			).map((c) => c.revision);
-			// Copying the revision of the old trunk base into the new trunk base means we don't need to write out the original
-			// revision to summaries. All clients agree that the trunk base always has the same hardcoded revision.
-			newTrunkBase.revision = this.trunkBase.revision;
-			// Overwriting the change is not strictly necessary, but done here for consistency (so all trunk bases are deeply equal).
-			newTrunkBase.change = this.trunkBase.change;
 			// Dropping the parent field removes (transitively) all references to the evicted commits so they can be garbage collected.
 			delete newTrunkBase.parent;
 			this.trunkBase = newTrunkBase;
 
 			// Update any state that is derived from trunk commits
-			this.sequenceMap.editRange(
-				minimumPossibleSequenceId,
-				sequenceId,
-				true,
-				(s, { revision }) => {
-					// Cleanup look-aside data for each evicted commit
-					this.trunkMetadata.delete(revision);
-					// Delete all evicted commits from `sequenceMap` except for the latest one, which is the new `trunkBase`
-					if (equalSequenceIds(s, sequenceId)) {
-						assert(
-							revision === newTrunkBase.revision,
-							0x729 /* Expected last evicted commit to be new trunk base */,
-						);
-					} else {
-						return { delete: true };
-					}
-				},
-			);
+			this.sequenceMap.editRange(minimumPossibleSequenceId, sequenceId, true, (s, commit) => {
+				// Cleanup look-aside data for each evicted commit
+				this.trunkMetadata.delete(commit.revision);
+				// Delete all evicted commits from `sequenceMap` except for the latest one, which is the new `trunkBase`
+				if (equalSequenceIds(s, sequenceId)) {
+					assert(
+						commit === newTrunkBase,
+						0x729 /* Expected last evicted commit to be new trunk base */,
+					);
+				} else {
+					Reflect.defineProperty(commit, "change", {
+						get: () =>
+							assert(
+								false,
+								0xa5e /* Should not access 'change' property of an evicted commit */,
+							),
+					});
+					Reflect.defineProperty(commit, "revision", {
+						get: () =>
+							assert(
+								false,
+								0xa5f /* Should not access 'revision' property of an evicted commit */,
+							),
+					});
+					Reflect.defineProperty(commit, "parent", {
+						get: () =>
+							assert(
+								false,
+								0xa60 /* Should not access 'parent' property of an evicted commit */,
+							),
+					});
+					return { delete: true };
+				}
+			});
 
 			const trunkSize = getPathFromBase(this.trunk.getHead(), this.trunkBase).length;
 			assert(
@@ -429,6 +484,9 @@ export class EditManager<
 			0x428 /* Clients with local changes cannot be used to generate summaries */,
 		);
 
+		// Trimming the trunk before serializing ensures that the trunk data in the summary is as minimal as possible.
+		this.trimTrunk();
+
 		let oldestCommitInCollabWindow = this.getClosestTrunkCommit(this.minimumSequenceNumber)[1];
 		assert(
 			oldestCommitInCollabWindow.parent !== undefined ||
@@ -442,6 +500,10 @@ export class EditManager<
 
 		const trunk = getPathFromBase(this.trunk.getHead(), oldestCommitInCollabWindow).map(
 			(c) => {
+				assert(
+					c !== this.trunkBase,
+					0xa61 /* Serialized trunk should not include the trunk base */,
+				);
 				const metadata =
 					this.trunkMetadata.get(c.revision) ?? fail("Expected metadata for trunk commit");
 				const commit: SequencedCommit<TChangeset> = {
@@ -464,11 +526,16 @@ export class EditManager<
 					findCommonAncestor([branch.getHead(), branchPath], this.trunk.getHead()) ??
 					fail("Expected branch to be based on trunk");
 
+				const base = ancestor === this.trunkBase ? rootRevision : ancestor.revision;
 				return [
 					sessionId,
 					{
-						base: ancestor.revision,
+						base,
 						commits: branchPath.map((c) => {
+							assert(
+								c !== this.trunkBase,
+								0xa62 /* Serialized branch should not include the trunk base */,
+							);
 							const commit: Commit<TChangeset> = {
 								change: c.change,
 								revision: c.revision,
@@ -533,8 +600,16 @@ export class EditManager<
 		}
 	}
 
-	private getCommitSequenceId(commit: GraphCommit<TChangeset>): SequenceId {
-		return this.trunkMetadata.get(commit.revision)?.sequenceId ?? minimumPossibleSequenceId;
+	private getCommitSequenceId(trunkCommitOrTrunkBase: GraphCommit<TChangeset>): SequenceId {
+		const id = this.trunkMetadata.get(trunkCommitOrTrunkBase.revision)?.sequenceId;
+		if (id === undefined) {
+			assert(
+				trunkCommitOrTrunkBase === this.trunkBase,
+				0xa63 /* Commit must be either be on the trunk or be the trunk base */,
+			);
+			return minimumPossibleSequenceId;
+		}
+		return id;
 	}
 
 	public getTrunkChanges(): readonly TChangeset[] {
@@ -586,6 +661,12 @@ export class EditManager<
 			0x713 /* Expected change sequence number to exceed the last known minimum sequence number */,
 		);
 
+		assert(
+			sequenceNumber >= // This is ">=", not ">" because changes in the same batch will have the same sequence number
+				(this.sequenceMap.maxKey()?.sequenceNumber ?? minimumPossibleSequenceNumber),
+			0xa64 /* Attempted to sequence change with an outdated sequence number */,
+		);
+
 		const commitsSequenceNumber = this.getBatch(sequenceNumber);
 		const sequenceId: SequenceId =
 			commitsSequenceNumber.length === 0
@@ -598,17 +679,7 @@ export class EditManager<
 					};
 
 		if (newCommit.sessionId === this.localSessionId) {
-			const headTrunkCommit = this.trunk.getHead();
-			const firstLocalCommit = this.localCommits.shift();
-			assert(
-				firstLocalCommit !== undefined,
-				0x6b5 /* Received a sequenced change from the local session despite having no local changes */,
-			);
-
-			// The first local branch commit is already rebased over the trunk, so we can push it directly to the trunk.
-			this.pushGraphCommitToTrunk(sequenceId, firstLocalCommit, this.localSessionId);
-			this.fastForwardBranches(headTrunkCommit, sequenceId);
-			return;
+			return this.fastForwardNextLocalCommit(sequenceId);
 		}
 
 		// Get the revision that the remote change is based on
@@ -665,11 +736,7 @@ export class EditManager<
 		return [commit, commits];
 	}
 
-	private pushCommitToTrunk(
-		sequenceId: SequenceId,
-		commit: Commit<TChangeset>,
-		local = false,
-	): void {
+	private pushCommitToTrunk(sequenceId: SequenceId, commit: Commit<TChangeset>): void {
 		const mintedCommit = mintCommit(this.trunk.getHead(), commit);
 		this.pushGraphCommitToTrunk(sequenceId, mintedCommit, commit.sessionId);
 	}

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

@@ -27,6 +27,7 @@ import type { ICodecOptions, IJsonCodec } from "../codec/index.js";
 import {
 	type ChangeFamily,
 	type ChangeFamilyEditor,
+	findAncestor,
 	type GraphCommit,
 	type RevisionTag,
 	RevisionTagCodec,
@@ -80,7 +81,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	public readonly breaker: Breakable = new Breakable("Shared Tree");
 
 	private readonly editManager: EditManager<TEditor, TChange, ChangeFamily<TEditor, TChange>>;
-	private readonly summarizables: readonly Summarizable[];
+	private readonly summarizables: readonly [EditManagerSummarizer<TChange>, ...Summarizable[]];
 	/**
 	 * The sequence number that this instance is at.
 	 * This number is artificial in that it is made up by this instance as opposed to being provided by the runtime.
@@ -308,14 +309,42 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	}
 
 	protected async loadCore(services: IChannelStorageService): Promise<void> {
-		const loadSummaries = this.summarizables.map(async (summaryElement) =>
-			summaryElement.load(
-				scopeStorageService(services, summarizablesTreeKey, summaryElement.key),
-				(contents) => this.serializer.parse(contents),
-			),
+		const [editManagerSummarizer, ...summarizables] = this.summarizables;
+		const loadEditManager = this.loadSummarizable(editManagerSummarizer, services);
+		const loadSummarizables = summarizables.map(async (s) =>
+			this.loadSummarizable(s, services),
 		);
 
-		await Promise.all(loadSummaries);
+		if (this.detachedRevision !== undefined) {
+			// If we are detached but loading from a summary, then we need to update our detached revision to ensure that it is ahead of all detached revisions in the summary.
+			// First, finish loading the edit manager so that we can inspect the sequence numbers of the commits on the trunk.
+			await loadEditManager;
+			// Find the most recent detached revision in the summary trunk...
+			let latestDetachedSequenceNumber: SeqNumber | undefined;
+			findAncestor(this.editManager.getTrunkHead(), (c) => {
+				const sequenceNumber = this.editManager.getSequenceNumber(c);
+				if (sequenceNumber !== undefined && sequenceNumber < 0) {
+					latestDetachedSequenceNumber = sequenceNumber;
+					return true;
+				}
+				return false;
+			});
+			// ...and set our detached revision to be as it would be if we had been already created that revision.
+			this.detachedRevision = latestDetachedSequenceNumber ?? this.detachedRevision;
+			await Promise.all(loadSummarizables);
+		} else {
+			await Promise.all([loadEditManager, ...loadSummarizables]);
+		}
+	}
+
+	private async loadSummarizable(
+		summarizable: Summarizable,
+		services: IChannelStorageService,
+	): Promise<void> {
+		return summarizable.load(
+			scopeStorageService(services, summarizablesTreeKey, summarizable.key),
+			(contents) => this.serializer.parse(contents),
+		);
 	}
 
 	/**
@@ -351,7 +380,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				newRevision,
 				this.detachedRevision,
 			);
-			this.editManager.advanceMinimumSequenceNumber(newRevision);
+			this.editManager.advanceMinimumSequenceNumber(newRevision, false);
 			return undefined;
 		}
 		const message = this.messageCodec.encode(

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

@@ -16,13 +16,14 @@ import { getUnhydratedContext } from "../createContext.js";
  * @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).
+ * types will be lossless and compatible with {@link TreeAlpha.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.
+ * @alpha
  */
 export type ConciseTree<THandle = IFluidHandle> =
 	| Exclude<TreeLeafValue, IFluidHandle>

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

@@ -3,21 +3,22 @@
  * 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 type {
-	TreeLeafValue,
 	ImplicitFieldSchema,
-	InsertableTreeFieldFromImplicitField,
 	TreeFieldFromImplicitField,
 	FieldSchema,
 	FieldKind,
+	UnsafeUnknownSchema,
+	InsertableField,
+	TreeLeafValue,
 } from "../schemaTypes.js";
 import {
 	getOrCreateNodeFromInnerNode,
 	UnhydratedFlexTreeNode,
+	type TreeNode,
 	type Unhydrated,
 } from "../core/index.js";
 import {
@@ -28,15 +29,8 @@ import {
 	type NodeKeyManager,
 } from "../../feature-libraries/index.js";
 import { isFieldInSchema } from "../../feature-libraries/index.js";
-import { toStoredSchema } from "../toFlexSchema.js";
-import { inSchemaOrThrow, mapTreeFromNodeData, type InsertableContent } from "../toMapTree.js";
-import {
-	applySchemaToParserOptions,
-	cursorFromVerbose,
-	type ParseOptions,
-	type VerboseTree,
-	type VerboseTreeNode,
-} from "./verboseTree.js";
+import { toStoredSchema } from "../toStoredSchema.js";
+import { inSchemaOrThrow, mapTreeFromNodeData } from "../toMapTree.js";
 import { getUnhydratedContext } from "../createContext.js";
 
 /**
@@ -49,18 +43,28 @@ import { getUnhydratedContext } from "../createContext.js";
  * 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.
+ * For that case, use {@link TreeBeta.clone}.
  */
-export function createFromInsertable<TSchema extends ImplicitFieldSchema>(
-	schema: TSchema,
-	data: InsertableTreeFieldFromImplicitField<TSchema>,
+export function createFromInsertable<
+	const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
+>(
+	schema: UnsafeUnknownSchema extends TSchema
+		? ImplicitFieldSchema
+		: TSchema & ImplicitFieldSchema,
+	data: InsertableField<TSchema>,
 	context?: NodeKeyManager | undefined,
-): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+): Unhydrated<
+	TSchema extends ImplicitFieldSchema
+		? TreeFieldFromImplicitField<TSchema>
+		: TreeNode | TreeLeafValue | undefined
+> {
 	const cursor = cursorFromInsertable(schema, data, context);
 	const result = cursor === undefined ? undefined : createFromCursor(schema, cursor);
-	return result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+	return result as Unhydrated<
+		TSchema extends ImplicitFieldSchema
+			? TreeFieldFromImplicitField<TSchema>
+			: TreeNode | TreeLeafValue | undefined
+	>;
 }
 
 /**
@@ -72,9 +76,13 @@ export function createFromInsertable<TSchema extends ImplicitFieldSchema>(
  * 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>,
+export function cursorFromInsertable<
+	TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
+>(
+	schema: UnsafeUnknownSchema extends TSchema
+		? ImplicitFieldSchema
+		: TSchema & ImplicitFieldSchema,
+	data: InsertableField<TSchema>,
 	context?: NodeKeyManager | undefined,
 ):
 	| ITreeCursorSynchronous
@@ -87,7 +95,7 @@ export function cursorFromInsertable<TSchema extends ImplicitFieldSchema>(
 	};
 
 	const mapTree = mapTreeFromNodeData(
-		data as InsertableContent | undefined,
+		data as InsertableField<UnsafeUnknownSchema>,
 		schema,
 		context,
 		schemaValidationPolicy,
@@ -102,50 +110,10 @@ export function cursorFromInsertable<TSchema extends ImplicitFieldSchema>(
 	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>(
+export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 	schema: TSchema,
 	cursor: ITreeCursorSynchronous | undefined,
 ): Unhydrated<TreeFieldFromImplicitField<TSchema>> {

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

@@ -28,6 +28,7 @@ import { isObjectNodeSchema } from "../objectNodeTypes.js";
 
 /**
  * Options for how to encode a tree.
+ * @alpha
  */
 export interface EncodeOptions<TCustom> {
 	/**
@@ -102,8 +103,8 @@ export function customFromCursorInner<TChild, THandle>(
 						const storedKey = reader.getFieldKey();
 						const key =
 							isObjectNodeSchema(nodeSchema) && !options.useStoredKeys
-								? nodeSchema.storedKeyToPropertyKey.get(storedKey) ??
-									fail("missing property key")
+								? (nodeSchema.storedKeyToPropertyKey.get(storedKey) ??
+									fail("missing property key"))
 								: storedKey;
 						// Length is checked above.
 						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion

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

@@ -12,6 +12,10 @@ export {
 	type ITreeViewConfiguration,
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
+	type TreeViewAlpha,
+	type TreeBranch,
+	type TreeBranchEvents,
+	asTreeViewAlpha,
 } from "./tree.js";
 export { SchemaFactory, type ScopedSchemaName } from "./schemaFactory.js";
 export type {
@@ -22,10 +26,9 @@ export {
 	adaptEnum,
 	enumFromStrings,
 	singletonSchema,
-	typedObjectValues,
 } from "./schemaCreationUtilities.js";
-export { treeNodeApi, type TreeNodeApi } from "./treeNodeApi.js";
-export { createFromInsertable, cursorFromInsertable } from "./create.js";
+export { treeNodeApi, type TreeNodeApi, tryGetSchema } from "./treeNodeApi.js";
+export { createFromInsertable, cursorFromInsertable, createFromCursor } from "./create.js";
 export type { SimpleTreeSchema } from "./simpleSchema.js";
 export {
 	type JsonSchemaId,
@@ -62,17 +65,25 @@ export type {
 	NodeBuilderDataUnsafe,
 	NodeFromSchemaUnsafe,
 	ReadonlyMapInlined,
+	TreeNodeSchemaClassUnsafe,
+	TreeNodeSchemaUnsafe,
+	AllowedTypesUnsafe,
+	TreeNodeSchemaNonClassUnsafe,
+	InsertableTreeNodeFromAllowedTypesUnsafe,
 } from "./typesUnsafe.js";
 
-export type {
-	VerboseTreeNode,
-	ParseOptions,
-	VerboseTree,
+export {
+	type VerboseTreeNode,
+	type ParseOptions,
+	type VerboseTree,
+	applySchemaToParserOptions,
+	cursorFromVerbose,
+	verboseFromCursor,
 } from "./verboseTree.js";
 
 export type { EncodeOptions } from "./customTree.js";
 
-export type { ConciseTree } from "./conciseTree.js";
+export { type ConciseTree, conciseFromCursor } from "./conciseTree.js";
 
 export { TreeBeta, type NodeChangedData, type TreeChangeEventsBeta } from "./treeApiBeta.js";