@fluidframework/tree 2.42.0 → 2.43.0

package/src/core/schema-stored/schema.ts

@@ -6,16 +6,27 @@
 import { fail } from "@fluidframework/core-utils/internal";
 
 import { DiscriminatedUnionDispatcher } from "../../codec/index.js";
-import { type MakeNominal, brand, invertMap } from "../../util/index.js";
+import {
+	type JsonCompatibleReadOnlyObject,
+	type MakeNominal,
+	brand,
+	invertMap,
+} from "../../util/index.js";
 
 import {
 	type FieldKey,
 	type FieldKindIdentifier,
-	type FieldSchemaFormat,
+	type FieldSchemaFormat as FieldSchemaFormatV1,
 	PersistedValueSchema,
-	type TreeNodeSchemaDataFormat,
+	type TreeNodeSchemaDataFormat as TreeNodeSchemaDataFormatV1,
 	type TreeNodeSchemaIdentifier,
 } from "./formatV1.js";
+import type {
+	FieldSchemaFormat as FieldSchemaFormatV2,
+	PersistedMetadataFormat,
+	TreeNodeSchemaUnionFormat,
+	TreeNodeSchemaDataFormat as TreeNodeSchemaDataFormatV2,
+} from "./formatV2.js";
 import type { Multiplicity } from "./multiplicity.js";
 
 /**
@@ -23,8 +34,14 @@ import type { Multiplicity } from "./multiplicity.js";
  */
 export enum SchemaVersion {
 	v1 = 1,
+	/**
+	 * Adds persisted metadata to the node schema and field schema.
+	 */
+	v2 = 2,
 }
 
+type FieldSchemaFormat = FieldSchemaFormatV1 | FieldSchemaFormatV2;
+
 /**
  * Schema for what {@link TreeLeafValue} is allowed on a Leaf node.
  * @privateRemarks
@@ -128,6 +145,15 @@ export interface TreeFieldStoredSchema {
 	 * If not specified, types are unconstrained.
 	 */
 	readonly types: TreeTypeSet;
+
+	/**
+	 * Portion of the metadata which can be persisted.
+	 * @remarks
+	 * Discarded when encoding to {@link SchemaFormatVersion.V1}.
+	 * @privateRemarks
+	 * This field corresponds to the `metadata` field in the persisted schema format.
+	 */
+	readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined;
 }
 
 /**
@@ -151,6 +177,7 @@ export const storedEmptyFieldSchema: TreeFieldStoredSchema = {
 	kind: brand(forbiddenFieldKindIdentifier),
 	// This type set also forces the field to be empty not not allowing any types as all.
 	types: new Set(),
+	persistedMetadata: undefined,
 };
 
 /**
@@ -164,12 +191,21 @@ export abstract class TreeNodeStoredSchema {
 	protected _typeCheck!: MakeNominal;
 
 	/**
-	 * @privateRemarks
-	 * Returns TreeNodeSchemaDataFormat.
-	 * This is uses an opaque type to avoid leaking these types out of the package,
-	 * and is runtime validated by the codec.
+	 * Constructor for a TreeNodeStoredSchema.
+	 * @param metadata - Persisted metadata for this node schema.
+	 */
+	public constructor(public readonly metadata: PersistedMetadataFormat | undefined) {}
+
+	/**
+	 * Encode in the v1 schema format.
 	 */
-	public abstract encode(): TreeNodeSchemaDataFormat;
+	public abstract encodeV1(): TreeNodeSchemaDataFormatV1;
+
+	/**
+	 * Encode in the v2 schema format.
+	 * @remarks Post-condition: if metadata was specified on the input schema, it will be present in the output.
+	 */
+	public abstract encodeV2(): TreeNodeSchemaDataFormatV2;
 
 	/**
 	 * Returns the schema for the provided field.
@@ -190,11 +226,35 @@ export class ObjectNodeStoredSchema extends TreeNodeStoredSchema {
 	 */
 	public constructor(
 		public readonly objectNodeFields: ReadonlyMap<FieldKey, TreeFieldStoredSchema>,
+		metadata?: PersistedMetadataFormat | undefined,
 	) {
-		super();
+		super(metadata);
+	}
+
+	public override encodeV1(): TreeNodeSchemaDataFormatV1 {
+		const fieldsObject: Record<string, FieldSchemaFormat> =
+			this.encodeFieldsObject(encodeFieldSchemaV1);
+
+		return {
+			object: fieldsObject,
+		};
+	}
+
+	public override encodeV2(): TreeNodeSchemaDataFormatV2 {
+		const fieldsObject: Record<string, FieldSchemaFormat> =
+			this.encodeFieldsObject(encodeFieldSchemaV2);
+		const kind = { object: fieldsObject };
+
+		return { kind, metadata: this.metadata };
 	}
 
-	public override encode(): TreeNodeSchemaDataFormat {
+	public override getFieldSchema(field: FieldKey): TreeFieldStoredSchema {
+		return this.objectNodeFields.get(field) ?? storedEmptyFieldSchema;
+	}
+
+	private encodeFieldsObject(
+		encodeFieldSchema: (storedFieldSchema: TreeFieldStoredSchema) => FieldSchemaFormat,
+	): Record<string, FieldSchemaFormat> {
 		const fieldsObject: Record<string, FieldSchemaFormat> = Object.create(null);
 		// Sort fields to ensure output is identical for for equivalent schema (since field order is not considered significant).
 		// This makes comparing schema easier, and ensures chunk reuse for schema summaries isn't needlessly broken.
@@ -208,13 +268,7 @@ export class ObjectNodeStoredSchema extends TreeNodeStoredSchema {
 				),
 			});
 		}
-		return {
-			object: fieldsObject,
-		};
-	}
-
-	public override getFieldSchema(field: FieldKey): TreeFieldStoredSchema {
-		return this.objectNodeFields.get(field) ?? storedEmptyFieldSchema;
+		return fieldsObject;
 	}
 }
 
@@ -229,16 +283,24 @@ export class MapNodeStoredSchema extends TreeNodeStoredSchema {
 	 * since no nodes can ever be in schema if you use `FieldKind.Value` here
 	 * (that would require infinite children).
 	 */
-	public constructor(public readonly mapFields: TreeFieldStoredSchema) {
-		super();
+	public constructor(
+		public readonly mapFields: TreeFieldStoredSchema,
+		metadata?: PersistedMetadataFormat | undefined,
+	) {
+		super(metadata);
 	}
 
-	public override encode(): TreeNodeSchemaDataFormat {
+	public override encodeV1(): TreeNodeSchemaDataFormatV1 {
 		return {
-			map: encodeFieldSchema(this.mapFields),
+			map: encodeFieldSchemaV1(this.mapFields),
 		};
 	}
 
+	public override encodeV2(): TreeNodeSchemaDataFormatV2 {
+		const kind = { map: encodeFieldSchemaV2(this.mapFields) };
+		return { kind, metadata: this.metadata };
+	}
+
 	public override getFieldSchema(field: FieldKey): TreeFieldStoredSchema {
 		return this.mapFields;
 	}
@@ -260,36 +322,54 @@ export class LeafNodeStoredSchema extends TreeNodeStoredSchema {
 	 * This is simply one approach that can work for modeling them in the internal schema representation.
 	 */
 	public constructor(public readonly leafValue: ValueSchema) {
-		super();
+		// No metadata for leaf nodes.
+		super(undefined);
 	}
 
-	public override encode(): TreeNodeSchemaDataFormat {
+	public override encodeV1(): TreeNodeSchemaDataFormatV1 {
 		return {
 			leaf: encodeValueSchema(this.leafValue),
 		};
 	}
 
+	public override encodeV2(): TreeNodeSchemaDataFormatV2 {
+		return {
+			// No metadata for leaf nodes, so don't emit a metadata field.
+			kind: {
+				leaf: encodeValueSchema(this.leafValue),
+			},
+		};
+	}
+
 	public override getFieldSchema(field: FieldKey): TreeFieldStoredSchema {
 		return storedEmptyFieldSchema;
 	}
 }
 
+/**
+ * Decoder wrapper function for {@link TreeNodeStoredSchema} implementations.
+ * Curries the constructor so that the caller can inject metadata.
+ */
+type StoredSchemaDecoder = (
+	metadata: PersistedMetadataFormat | undefined,
+) => TreeNodeStoredSchema;
+
 export const storedSchemaDecodeDispatcher: DiscriminatedUnionDispatcher<
-	TreeNodeSchemaDataFormat,
+	TreeNodeSchemaUnionFormat,
 	[],
-	TreeNodeStoredSchema
+	StoredSchemaDecoder
 > = new DiscriminatedUnionDispatcher({
-	leaf: (data: PersistedValueSchema) => new LeafNodeStoredSchema(decodeValueSchema(data)),
-	object: (
-		data: Record<TreeNodeSchemaIdentifier, FieldSchemaFormat>,
-	): TreeNodeStoredSchema => {
+	leaf: (data: PersistedValueSchema) => (metadata) =>
+		new LeafNodeStoredSchema(decodeValueSchema(data)),
+	object: (data: Record<TreeNodeSchemaIdentifier, FieldSchemaFormat>) => (metadata) => {
 		const map = new Map();
 		for (const [key, value] of Object.entries(data)) {
 			map.set(key, decodeFieldSchema(value));
 		}
-		return new ObjectNodeStoredSchema(map);
+		return new ObjectNodeStoredSchema(map, metadata);
 	},
-	map: (data: FieldSchemaFormat) => new MapNodeStoredSchema(decodeFieldSchema(data)),
+	map: (data: FieldSchemaFormat) => (metadata) =>
+		new MapNodeStoredSchema(decodeFieldSchema(data), metadata),
 });
 
 const valueSchemaEncode = new Map([
@@ -310,7 +390,7 @@ function decodeValueSchema(inMemory: PersistedValueSchema): ValueSchema {
 	return valueSchemaDecode.get(inMemory) ?? fail(0xae9 /* missing ValueSchema */);
 }
 
-export function encodeFieldSchema(schema: TreeFieldStoredSchema): FieldSchemaFormat {
+export function encodeFieldSchemaV1(schema: TreeFieldStoredSchema): FieldSchemaFormatV1 {
 	return {
 		kind: schema.kind,
 		// Types are sorted by identifier to improve stability of persisted data to increase chance of schema blob reuse.
@@ -318,11 +398,21 @@ export function encodeFieldSchema(schema: TreeFieldStoredSchema): FieldSchemaFor
 	};
 }
 
-export function decodeFieldSchema(schema: FieldSchemaFormat): TreeFieldStoredSchema {
+export function encodeFieldSchemaV2(schema: TreeFieldStoredSchema): FieldSchemaFormatV2 {
+	const fieldSchema: FieldSchemaFormatV1 = encodeFieldSchemaV1(schema);
+
+	// Omit metadata from the output if it is undefined
+	return schema.persistedMetadata !== undefined
+		? { ...fieldSchema, metadata: schema.persistedMetadata }
+		: { ...fieldSchema };
+}
+
+export function decodeFieldSchema(schema: FieldSchemaFormatV2): TreeFieldStoredSchema {
 	const out: TreeFieldStoredSchema = {
 		// TODO: maybe provide actual FieldKind objects here, error on unrecognized kinds.
 		kind: schema.kind,
 		types: new Set(schema.types),
+		persistedMetadata: schema.metadata,
 	};
 	return out;
 }

package/src/feature-libraries/chunked-forest/codec/chunkEncodingGeneric.ts

@@ -43,13 +43,14 @@ export type BufferFormat<TEncodedShape> = (
 )[];
 
 /**
- * Replace shapes and identifiers in buffer and any nested arrays.
+ * Takes already encoded content in `buffer` and deeply searches, replacing each `IdentifierToken` and `Shape`
+ * with references to their encodings in the returned `EncodedFieldBatchGeneric`.
  *
  * This looks inside nested arrays (including transitively) but not inside objects.
  *
  * Note that this modifies `buffer` to avoid having to copy it.
  */
-export function handleShapesAndIdentifiers<TEncodedShape>(
+export function updateShapesAndIdentifiersEncoding<TEncodedShape>(
 	version: number,
 	buffer: BufferFormat<TEncodedShape>[],
 	identifierFilter: CounterFilter<string> = jsonMinimizingFilter,
@@ -68,6 +69,9 @@ export function handleShapesAndIdentifiers<TEncodedShape>(
 		}
 	};
 
+	// A collection of all arrays transitively reachable (via arrays) from buffer.
+	// These are all the arrays whose contents are searched for shapes and identifiers which are then replaced
+	// with references. This uses a breadth first traversal, but the actual order is not important.
 	const arrays: BufferFormat<TEncodedShape>[] = [buffer];
 	for (const array of arrays) {
 		for (const item of array) {
@@ -93,9 +97,9 @@ export function handleShapesAndIdentifiers<TEncodedShape>(
 
 	// Traverse shape graph, discovering and counting all shape to shape and shape to identifier references.
 	{
-		let item: Shape<TEncodedShape> | undefined;
-		while ((item = shapeToCount.pop()) !== undefined) {
-			item.count(identifiers, shapeDiscovered);
+		let shape: Shape<TEncodedShape> | undefined;
+		while ((shape = shapeToCount.pop()) !== undefined) {
+			shape.countReferencedShapesAndIdentifiers(identifiers, shapeDiscovered);
 		}
 	}
 
@@ -143,8 +147,8 @@ export function handleShapesAndIdentifiers<TEncodedShape>(
  * Comparison by content would be difficult due to shape containing references to other shapes.
  *
  * @privateRemarks
- * Unlike with identifiers, conversion from the initial form (this class / IdentifierToken) is done by the `encodeShape` method, not by general purpose logic in `handleShapesAndIdentifiers`.
- * For `handleShapesAndIdentifiers` to do the conversion without help from `encodeShape`,
+ * Unlike with identifiers, conversion from the initial form (this class / IdentifierToken) is done by the `encodeShape` method, not by general purpose logic in `updateShapesAndIdentifiersEncoding`.
+ * For `updateShapesAndIdentifiersEncoding` to do the conversion without help from `encodeShape`,
  * instances of this Shape class would have to either be or output an object that is identical to the `TEncodedShape` format except with all shape references as object references instead of indexes.
  * Those objects would have to be deeply traversed looking for shape objects to replace with reference indexes.
  * This is possible, but making it type safe would involve generating derived types from the `TEncodedShape` deeply replacing any shape references, as well as requiring deep traversal of all objects in the encoded output.
@@ -152,18 +156,19 @@ export function handleShapesAndIdentifiers<TEncodedShape>(
  */
 export abstract class Shape<TEncodedShape> {
 	/**
-	 * Count this shape's contents.
+	 * Enumerate all contents of this shape that can get replaced with references (for better compression/deduplication) during encoding.
+	 * This currently includes shapes and identifiers.
 	 *
 	 * Used to discover referenced shapes (to ensure they are included in the `shapes` passed to `encodeShape`),
 	 * as well as count usages of shapes and identifiers for more efficient dictionary encoding. See {@link Counter}.
 	 *
-	 * @param shapes - must be invoked with each directly referenced shape (which must provided to `encodeShape`).
+	 * @param shapeDiscovered - must be invoked with each directly referenced shape (which must be provided to `encodeShape`).
 	 * Can be invoked multiple times if a shape is referenced more than once for more efficient dictionary encoding.
 	 * Should not be invoked with `this` unless this shape references itself.
 	 */
-	public abstract count(
+	public abstract countReferencedShapesAndIdentifiers(
 		identifiers: Counter<string>,
-		shapes: (shape: Shape<TEncodedShape>) => void,
+		shapeDiscovered: (shape: Shape<TEncodedShape>) => void,
 	): void;
 
 	/**

package/src/feature-libraries/chunked-forest/codec/compressedEncode.ts

@@ -23,7 +23,7 @@ import type { Counter, DeduplicationTable } from "./chunkCodecUtilities.js";
 import {
 	type BufferFormat as BufferFormatGeneric,
 	Shape as ShapeGeneric,
-	handleShapesAndIdentifiers,
+	updateShapesAndIdentifiersEncoding,
 } from "./chunkEncodingGeneric.js";
 import type { FieldBatch } from "./fieldBatch.js";
 import {
@@ -55,7 +55,7 @@ export function compressedEncode(
 		anyFieldEncoder.encodeField(cursor, cache, buffer);
 		batchBuffer.push(buffer);
 	}
-	return handleShapesAndIdentifiers(version, batchBuffer);
+	return updateShapesAndIdentifiersEncoding(version, batchBuffer);
 }
 
 export type BufferFormat = BufferFormatGeneric<EncodedChunkShape>;
@@ -175,7 +175,10 @@ export class AnyShape extends ShapeGeneric<EncodedChunkShape> {
 		return { d: encodedAnyShape };
 	}
 
-	public count(identifiers: Counter<string>, shapes: (shape: Shape) => void): void {}
+	public countReferencedShapesAndIdentifiers(
+		identifiers: Counter<string>,
+		shapeDiscovered: (shape: Shape) => void,
+	): void {}
 
 	public static encodeField(
 		cursor: ITreeCursorSynchronous,
@@ -329,8 +332,11 @@ export class InlineArrayShape
 		};
 	}
 
-	public count(identifiers: Counter<string>, shapes: (shape: Shape) => void): void {
-		shapes(this.inner.shape);
+	public countReferencedShapesAndIdentifiers(
+		identifiers: Counter<string>,
+		shapeDiscovered: (shape: Shape) => void,
+	): void {
+		shapeDiscovered(this.inner.shape);
 	}
 
 	public get shape(): this {
@@ -387,8 +393,11 @@ export class NestedArrayShape extends ShapeGeneric<EncodedChunkShape> implements
 		};
 	}
 
-	public count(identifiers: Counter<string>, shapes: (shape: Shape) => void): void {
-		shapes(this.inner.shape);
+	public countReferencedShapesAndIdentifiers(
+		identifiers: Counter<string>,
+		shapeDiscovered: (shape: Shape) => void,
+	): void {
+		shapeDiscovered(this.inner.shape);
 	}
 }
 

package/src/feature-libraries/chunked-forest/codec/nodeShape.ts

@@ -121,9 +121,9 @@ export class NodeShape extends Shape<EncodedChunkShape> implements NodeEncoder {
 		};
 	}
 
-	public count(
+	public countReferencedShapesAndIdentifiers(
 		identifiers: Counter<string>,
-		shapes: (shape: Shape<EncodedChunkShape>) => void,
+		shapeDiscovered: (shape: Shape<EncodedChunkShape>) => void,
 	): void {
 		if (this.type !== undefined) {
 			identifiers.add(this.type);
@@ -131,11 +131,11 @@ export class NodeShape extends Shape<EncodedChunkShape> implements NodeEncoder {
 
 		for (const fieldEncoder of this.specializedFieldEncoders) {
 			identifiers.add(fieldEncoder.key);
-			shapes(fieldEncoder.encoder.shape);
+			shapeDiscovered(fieldEncoder.encoder.shape);
 		}
 
 		if (this.otherFieldsEncoder !== undefined) {
-			shapes(this.otherFieldsEncoder.shape);
+			shapeDiscovered(this.otherFieldsEncoder.shape);
 		}
 	}
 

package/src/feature-libraries/detachedFieldIndexSummarizer.ts

@@ -6,6 +6,7 @@
 import { bufferToString } from "@fluid-internal/client-utils";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type {
+	IExperimentalIncrementalSummaryContext,
 	ISummaryTreeWithStats,
 	ITelemetryContext,
 } from "@fluidframework/runtime-definitions/internal";
@@ -32,23 +33,15 @@ export class DetachedFieldIndexSummarizer implements Summarizable {
 
 	public constructor(private readonly detachedFieldIndex: DetachedFieldIndex) {}
 
-	public getAttachSummary(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-	): ISummaryTreeWithStats {
+	public summarize(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+	}): ISummaryTreeWithStats {
 		const data = this.detachedFieldIndex.encode();
-		return createSingleBlobSummary(detachedFieldIndexBlobKey, stringify(data));
-	}
-
-	public async summarize(
-		stringify: SummaryElementStringifier,
-		fullTree?: boolean,
-		trackState?: boolean,
-		telemetryContext?: ITelemetryContext,
-	): Promise<ISummaryTreeWithStats> {
-		return this.getAttachSummary(stringify, fullTree, trackState, telemetryContext);
+		return createSingleBlobSummary(detachedFieldIndexBlobKey, props.stringify(data));
 	}
 
 	public async load(

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -9,7 +9,6 @@ import {
 	type FieldKindIdentifier,
 	type ITreeCursorSynchronous,
 	type NormalizedFieldUpPath,
-	type TreeNodeSchemaIdentifier,
 	type TreeValue,
 	anchorSlot,
 } from "../../core/index.js";
@@ -19,7 +18,12 @@ import type {
 	ValueFieldEditBuilder,
 	OptionalFieldEditBuilder,
 } from "../default-schema/index.js";
-import type { MinimalMapTreeNodeView } from "../mapTreeCursor.js";
+import type {
+	MapTreeFieldViewGeneric,
+	MapTreeNodeViewGeneric,
+	MinimalFieldMap,
+	MinimalMapTreeNodeView,
+} from "../mapTreeCursor.js";
 import type { FlexFieldKind } from "../modular-schema/index.js";
 
 import type { FlexTreeContext, FlexTreeHydratedContext } from "./context.js";
@@ -75,6 +79,14 @@ export interface FlexTreeEntity {
 	 * A common context of FlexTrees.
 	 */
 	readonly context: FlexTreeContext;
+
+	/**
+	 * Get a cursor for the underlying data.
+	 * @remarks
+	 * This cursor might be one the node uses in its implementation, and thus must be returned to its original location before using any other APIs to interact with the tree.
+	 * Must not be held onto across edits or any other tree API use.
+	 */
+	borrowCursor(): ITreeCursorSynchronous;
 }
 
 /**
@@ -142,14 +154,9 @@ export enum TreeStatus {
  * @remarks
  * All editing is actually done via {@link FlexTreeField}s: the nodes are immutable other than that they contain mutable fields.
  */
-export interface FlexTreeNode extends FlexTreeEntity {
+export interface FlexTreeNode extends FlexTreeEntity, MapTreeNodeViewGeneric<FlexTreeNode> {
 	readonly [flexTreeMarker]: FlexTreeEntityKind.Node;
 
-	/**
-	 * Value stored on this node.
-	 */
-	readonly value?: TreeValue;
-
 	/**
 	 * Gets a field of this node, if it is not empty.
 	 */
@@ -162,16 +169,30 @@ export interface FlexTreeNode extends FlexTreeEntity {
 	 * @remarks
 	 * All fields implicitly exist, so `getBoxed` can be called with any key and will always return a field.
 	 * Even if the field is empty, it will still be returned, and can be edited to insert content if allowed by the field kind.
-	 * See {@link FlexTreeNode.tryGetField} for a variant that does not allocate afield in the empty case.
+	 * See {@link FlexTreeNode.tryGetField} for a variant that does not allocate a field in the empty case.
 	 */
 	getBoxed(key: FieldKey): FlexTreeField;
 
 	/**
 	 * The field this tree is in, and the index within that field.
+	 * @remarks
+	 * The behavior of this at the root (especially removed and unhydrated roots) is currently not very consistent.
+	 * Since very little relies on this, limit what it exposes to reduce the potential impact of inconsistent root handling.
 	 */
-	readonly parentField: { readonly parent: FlexTreeField; readonly index: number };
+	readonly parentField: {
+		readonly parent: Pick<FlexTreeField, "parent" | "schema" | "key">;
+		readonly index: number;
+	};
 
-	boxedIterator(): IterableIterator<FlexTreeField>;
+	/**
+	 * The non-empty fields on this node.
+	 */
+	readonly fields: MinimalFieldMap<FlexTreeField>;
+
+	/**
+	 * The non-empty fields on this node.
+	 */
+	[Symbol.iterator](): IterableIterator<FlexTreeField>;
 
 	/**
 	 * Returns an iterable of keys for non-empty fields.
@@ -183,20 +204,6 @@ export interface FlexTreeNode extends FlexTreeEntity {
 	 */
 	keys(): IterableIterator<FieldKey>;
 
-	/**
-	 * Schema for this entity.
-	 * If well-formed, it must follow this schema.
-	 */
-	readonly schema: TreeNodeSchemaIdentifier;
-
-	/**
-	 * Get a cursor for the underlying data.
-	 * @remarks
-	 * This cursor might be one the node uses in its implementation, and thus must be returned to its original location before using any other APIs to interact with the tree.
-	 * Must not be held onto across edits or any other tree API use.
-	 */
-	borrowCursor(): ITreeCursorSynchronous;
-
 	/**
 	 * If true, this node is a {@link HydratedFlexTreeNode}.
 	 *
@@ -243,7 +250,7 @@ export interface HydratedFlexTreeNode extends FlexTreeNode {
  * All content in the tree is accessible without down-casting, but if the schema is known,
  * the schema aware API may be more ergonomic.
  */
-export interface FlexTreeField extends FlexTreeEntity {
+export interface FlexTreeField extends FlexTreeEntity, MapTreeFieldViewGeneric<FlexTreeNode> {
 	readonly [flexTreeMarker]: FlexTreeEntityKind.Field;
 
 	/**
@@ -268,8 +275,6 @@ export interface FlexTreeField extends FlexTreeEntity {
 	 */
 	is<TKind extends FlexFieldKind>(kind: TKind): this is FlexTreeTypedField<TKind>;
 
-	boxedIterator(): IterableIterator<FlexTreeNode>;
-
 	/**
 	 * Gets a node of this field by its index without unboxing.
 	 * @param index - Zero-based index of the item to retrieve. Negative values are interpreted from the end of the sequence.
@@ -350,8 +355,6 @@ export interface FlexTreeSequenceField extends FlexTreeField {
 	 * Get an editor for this sequence.
 	 */
 	readonly editor: SequenceFieldEditBuilder<FlexibleFieldContent>;
-
-	boxedIterator(): IterableIterator<FlexTreeNode>;
 }
 
 /**

package/src/feature-libraries/flex-tree/index.ts

@@ -22,14 +22,6 @@ export {
 	type HydratedFlexTreeNode,
 } from "./flexTreeTypes.js";
 
-export {
-	visitBipartiteIterableTree,
-	Skip,
-	visitBipartiteIterableTreeWithState,
-	visitIterableTree,
-	visitIterableTreeWithState,
-} from "./navigation.js";
-
 export {
 	type FlexTreeContext,
 	type FlexTreeHydratedContext,

package/src/feature-libraries/flex-tree/lazyEntity.ts

@@ -6,6 +6,7 @@
 import { assert } from "@fluidframework/core-utils/internal";
 
 import {
+	type ITreeCursorSynchronous,
 	type ITreeSubscriptionCursor,
 	ITreeSubscriptionCursorState,
 	TreeNavigationResult,
@@ -48,7 +49,10 @@ export abstract class LazyEntity<TAnchor = unknown> implements FlexTreeEntity, I
 		this.context.withAnchors.add(this);
 	}
 
-	public abstract boxedIterator(): IterableIterator<FlexTreeEntity>;
+	public borrowCursor(): ITreeCursorSynchronous {
+		return this.cursor as ITreeCursorSynchronous;
+	}
+
 	public abstract get [flexTreeMarker](): FlexTreeEntityKind;
 
 	public [disposeSymbol](): void {

package/src/feature-libraries/flex-tree/lazyField.ts

@@ -19,6 +19,7 @@ import {
 	type TreeNavigationResult,
 	inCursorNode,
 	iterateCursorField,
+	mapCursorField,
 	rootFieldKey,
 } from "../../core/index.js";
 import { disposeSymbol, getOrCreate } from "../../util/index.js";
@@ -206,19 +207,15 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 	}
 
 	public map<U>(callbackfn: (value: FlexTreeUnknownUnboxed, index: number) => U): U[] {
-		return Array.from(this, callbackfn);
+		return mapCursorField(this.cursor, (cursor) =>
+			callbackfn(unboxedFlexNode(this.context, cursor, this.anchor), cursor.fieldIndex),
+		);
 	}
 
-	public boxedIterator(): IterableIterator<HydratedFlexTreeNode> {
+	public [Symbol.iterator](): IterableIterator<HydratedFlexTreeNode> {
 		return iterateCursorField(this.cursor, (cursor) => makeTree(this.context, cursor));
 	}
 
-	public [Symbol.iterator](): IterableIterator<FlexTreeUnknownUnboxed> {
-		return iterateCursorField(this.cursor, (cursor) =>
-			unboxedFlexNode(this.context, cursor, this.anchor),
-		);
-	}
-
 	public getFieldPath(): NormalizedFieldUpPath {
 		return { parent: this.parent?.anchorNode, field: this.key };
 	}