@fluidframework/tree 2.41.0 → 2.42.0

package/src/feature-libraries/default-schema/schemaChecker.ts

@@ -7,7 +7,6 @@ import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
-	type MapTree,
 	type TreeFieldStoredSchema,
 	LeafNodeStoredSchema,
 	ObjectNodeStoredSchema,
@@ -16,6 +15,8 @@ import {
 	type SchemaAndPolicy,
 } from "../../core/index.js";
 import { allowsValue } from "../valueUtilities.js";
+import type { MapTreeFieldViewGeneric, MinimalMapTreeNodeView } from "../mapTreeCursor.js";
+import { iterableHasSome, mapIterable } from "../../util/index.js";
 
 export enum SchemaValidationError {
 	Field_KindNotInSchemaPolicy,
@@ -45,7 +46,7 @@ export function inSchemaOrThrow(maybeError: SchemaValidationError | undefined):
  * Deeply checks that the provided node complies with the schema based on its identifier.
  */
 export function isNodeInSchema(
-	node: MapTree,
+	node: MinimalMapTreeNodeView,
 	schemaAndPolicy: SchemaAndPolicy,
 ): SchemaValidationError | undefined {
 	// Validate the schema declared by the node exists
@@ -57,7 +58,7 @@ export function isNodeInSchema(
 	// Validate the node is well formed according to its schema
 
 	if (schema instanceof LeafNodeStoredSchema) {
-		if (node.fields.size !== 0) {
+		if (iterableHasSome(node.fields)) {
 			return SchemaValidationError.LeafNode_FieldsNotAllowed;
 		}
 		if (!allowsValue(schema.leafValue, node.value)) {
@@ -69,7 +70,7 @@ export function isNodeInSchema(
 		}
 
 		if (schema instanceof ObjectNodeStoredSchema) {
-			const uncheckedFieldsFromNode = new Set(node.fields.keys());
+			const uncheckedFieldsFromNode = new Set(mapIterable(node.fields, ([key, field]) => key));
 			for (const [fieldKey, fieldSchema] of schema.objectNodeFields) {
 				const nodeField = node.fields.get(fieldKey) ?? [];
 				const fieldInSchemaResult = isFieldInSchema(nodeField, fieldSchema, schemaAndPolicy);
@@ -86,7 +87,7 @@ export function isNodeInSchema(
 				return SchemaValidationError.ObjectNode_FieldNotInSchema;
 			}
 		} else if (schema instanceof MapNodeStoredSchema) {
-			for (const field of node.fields.values()) {
+			for (const [_key, field] of node.fields) {
 				const fieldInSchemaResult = isFieldInSchema(field, schema.mapFields, schemaAndPolicy);
 				if (fieldInSchemaResult !== undefined) {
 					return fieldInSchemaResult;
@@ -104,7 +105,7 @@ export function isNodeInSchema(
  * Deeply checks that the nodes comply with the field schema and included schema.
  */
 export function isFieldInSchema(
-	childNodes: readonly MapTree[],
+	childNodes: MapTreeFieldViewGeneric<MinimalMapTreeNodeView>,
 	schema: TreeFieldStoredSchema,
 	schemaAndPolicy: SchemaAndPolicy,
 ): SchemaValidationError | undefined {

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

@@ -54,16 +54,12 @@ export interface FlexTreeContext {
 }
 
 /**
- * A common context of a "forest" of FlexTrees.
- * It handles group operations like transforming cursors into anchors for edits.
+ * Subset of a hydrated context which can be used in more cases (like before the root and events are set up).
  */
-export interface FlexTreeHydratedContext extends FlexTreeContext {
-	readonly events: Listenable<ForestEvents>;
+export interface FlexTreeHydratedContextMinimal {
 	/**
-	 * Gets the root field of the tree.
+	 * The {@link NodeIdentifierManager} responsible for allocating and compressing identifiers for nodes in this context.
 	 */
-	get root(): FlexTreeField;
-
 	readonly nodeKeyManager: NodeIdentifierManager;
 
 	/**
@@ -72,6 +68,20 @@ export interface FlexTreeHydratedContext extends FlexTreeContext {
 	readonly checkout: ITreeCheckout;
 }
 
+/**
+ * A common context of a "forest" of FlexTrees.
+ * It handles group operations like transforming cursors into anchors for edits.
+ */
+export interface FlexTreeHydratedContext
+	extends FlexTreeContext,
+		FlexTreeHydratedContextMinimal {
+	readonly events: Listenable<ForestEvents>;
+	/**
+	 * Gets the root field of the tree.
+	 */
+	get root(): FlexTreeField;
+}
+
 /**
  * Creating multiple flex tree contexts for the same branch, and thus with the same underlying AnchorSet does not work due to how TreeNode caching works.
  * This slot is used to detect if one already exists and error if creating a second.

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

@@ -5,7 +5,6 @@
 
 import {
 	type AnchorNode,
-	type ExclusiveMapTree,
 	type FieldKey,
 	type FieldKindIdentifier,
 	type ITreeCursorSynchronous,
@@ -20,15 +19,16 @@ import type {
 	ValueFieldEditBuilder,
 	OptionalFieldEditBuilder,
 } from "../default-schema/index.js";
+import type { MinimalMapTreeNodeView } from "../mapTreeCursor.js";
 import type { FlexFieldKind } from "../modular-schema/index.js";
 
-import type { FlexTreeContext } from "./context.js";
+import type { FlexTreeContext, FlexTreeHydratedContext } from "./context.js";
 
 /**
  * An anchor slot which records the {@link FlexTreeNode} associated with that anchor, if there is one.
  * @remarks This always points to a "real" {@link FlexTreeNode} (i.e. a `LazyTreeNode`), never to a "raw" node.
  */
-export const flexTreeSlot = anchorSlot<FlexTreeNode>();
+export const flexTreeSlot = anchorSlot<HydratedFlexTreeNode>();
 
 /**
  * Indicates that an object is a flex tree.
@@ -98,6 +98,10 @@ export enum TreeStatus {
 	 * Nodes can enter this state for multiple reasons:
 	 * - The node was removed and nothing (e.g. undo/redo history) kept it from being cleaned up.
 	 * - The {@link TreeView} was disposed or had a schema change which made the tree incompatible.
+	 *
+	 * Deleted nodes' contents should not be observed or edited. This includes functionality exposed via {@link (Tree:variable)},
+	 * with the exception of {@link TreeNodeApi.status}.
+	 *
 	 * @privateRemarks
 	 * There was planned work (AB#17948) to make the first reason a node could become "Deleted" impossible,
 	 * at least as an opt in feature,
@@ -169,16 +173,6 @@ export interface FlexTreeNode extends FlexTreeEntity {
 
 	boxedIterator(): IterableIterator<FlexTreeField>;
 
-	/**
-	 * The anchor node associated with this node
-	 *
-	 * @remarks
-	 * The ref count keeping this alive is owned by the FlexTreeNode:
-	 * if holding onto this anchor for longer than the FlexTreeNode might be alive,
-	 * a separate Anchor (and thus ref count) must be allocated to keep it alive.
-	 */
-	readonly anchorNode: AnchorNode;
-
 	/**
 	 * Returns an iterable of keys for non-empty fields.
 	 *
@@ -202,6 +196,33 @@ export interface FlexTreeNode extends FlexTreeEntity {
 	 * Must not be held onto across edits or any other tree API use.
 	 */
 	borrowCursor(): ITreeCursorSynchronous;
+
+	/**
+	 * If true, this node is a {@link HydratedFlexTreeNode}.
+	 *
+	 * If false, this node is unhydrated.
+	 */
+	isHydrated(): this is HydratedFlexTreeNode;
+}
+
+/**
+ * A FlexTreeNode that is hydrated, meaning it is associated with a {@link FlexTreeHydratedContext}.
+ */
+export interface HydratedFlexTreeNode extends FlexTreeNode {
+	/**
+	 * {@inheritDoc FlexTreeNode.context}
+	 */
+	readonly context: FlexTreeHydratedContext;
+
+	/**
+	 * The anchor node associated with this node
+	 *
+	 * @remarks
+	 * The ref count keeping this alive is owned by the FlexTreeNode:
+	 * if holding onto this anchor for longer than the FlexTreeNode might be alive,
+	 * a separate Anchor (and thus ref count) must be allocated to keep it alive.
+	 */
+	readonly anchorNode: AnchorNode;
 }
 
 /**
@@ -278,12 +299,12 @@ export interface FlexTreeField extends FlexTreeEntity {
 /**
  * Typed tree for inserting as the content of a field.
  */
-export type FlexibleFieldContent = ExclusiveMapTree[];
+export type FlexibleFieldContent = readonly FlexibleNodeContent[];
 
 /**
  * Tree for inserting as a node.
  */
-export type FlexibleNodeContent = ExclusiveMapTree;
+export type FlexibleNodeContent = MinimalMapTreeNodeView;
 
 /**
  * {@link FlexTreeField} that stores a sequence of children.

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

@@ -17,6 +17,9 @@ export {
 	FlexTreeEntityKind,
 	isFlexTreeNode,
 	flexTreeSlot,
+	type FlexibleNodeContent,
+	type FlexibleFieldContent,
+	type HydratedFlexTreeNode,
 } from "./flexTreeTypes.js";
 
 export {
@@ -32,6 +35,7 @@ export {
 	type FlexTreeHydratedContext,
 	Context,
 	ContextSlot,
+	type FlexTreeHydratedContextMinimal,
 } from "./context.js";
 
 export { type FlexTreeNodeEvents } from "./treeEvents.js";

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

@@ -37,12 +37,14 @@ import type { Context } from "./context.js";
 import {
 	FlexTreeEntityKind,
 	type FlexTreeField,
-	type FlexTreeNode,
 	type FlexTreeOptionalField,
 	type FlexTreeRequiredField,
 	type FlexTreeSequenceField,
 	type FlexTreeTypedField,
 	type FlexTreeUnknownUnboxed,
+	type FlexibleFieldContent,
+	type FlexibleNodeContent,
+	type HydratedFlexTreeNode,
 	TreeStatus,
 	flexTreeMarker,
 	flexTreeSlot,
@@ -159,7 +161,7 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 		return this.schema === kind.identifier;
 	}
 
-	public get parent(): FlexTreeNode | undefined {
+	public get parent(): HydratedFlexTreeNode | undefined {
 		if (this.anchor.parent === undefined) {
 			return undefined;
 		}
@@ -193,7 +195,7 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 		);
 	}
 
-	public boxedAt(index: number): FlexTreeNode | undefined {
+	public boxedAt(index: number): HydratedFlexTreeNode | undefined {
 		const finalIndex = indexForAt(index, this.length);
 
 		if (finalIndex === undefined) {
@@ -207,7 +209,7 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 		return Array.from(this, callbackfn);
 	}
 
-	public boxedIterator(): IterableIterator<FlexTreeNode> {
+	public boxedIterator(): IterableIterator<HydratedFlexTreeNode> {
 		return iterateCursorField(this.cursor, (cursor) => makeTree(this.context, cursor));
 	}
 
@@ -263,7 +265,7 @@ export class LazySequence extends LazyField implements FlexTreeSequenceField {
 		return this.map((x) => x);
 	}
 
-	public editor: SequenceFieldEditBuilder<ExclusiveMapTree[]> = {
+	public editor: SequenceFieldEditBuilder<FlexibleFieldContent> = {
 		insert: (index, newContent) => {
 			this.sequenceEditor().insert(index, cursorForMapTreeField(newContent));
 		},
@@ -279,7 +281,7 @@ export class LazySequence extends LazyField implements FlexTreeSequenceField {
 }
 
 export class LazyValueField extends LazyField implements FlexTreeRequiredField {
-	public editor: ValueFieldEditBuilder<ExclusiveMapTree> = {
+	public editor: ValueFieldEditBuilder<FlexibleNodeContent> = {
 		set: (newContent) => {
 			this.valueFieldEditor().set(cursorForMapTreeField([newContent]));
 		},

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

@@ -28,7 +28,7 @@ import type { Context } from "./context.js";
 import {
 	FlexTreeEntityKind,
 	type FlexTreeField,
-	type FlexTreeNode,
+	type HydratedFlexTreeNode,
 	flexTreeMarker,
 	flexTreeSlot,
 } from "./flexTreeTypes.js";
@@ -63,7 +63,7 @@ function cleanupTree(anchor: AnchorNode): void {
 /**
  * Lazy implementation of {@link FlexTreeNode}.
  */
-export class LazyTreeNode extends LazyEntity<Anchor> implements FlexTreeNode {
+export class LazyTreeNode extends LazyEntity<Anchor> implements HydratedFlexTreeNode {
 	public get [flexTreeMarker](): FlexTreeEntityKind.Node {
 		return FlexTreeEntityKind.Node;
 	}
@@ -88,6 +88,10 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements FlexTreeNode {
 		this.#removeDeleteCallback = anchorNode.events.on("afterDestroy", cleanupTree);
 	}
 
+	public isHydrated(): this is HydratedFlexTreeNode {
+		return true;
+	}
+
 	public borrowCursor(): ITreeCursorSynchronous {
 		return this.cursor as ITreeCursorSynchronous;
 	}

package/src/feature-libraries/forest-summary/forestSummarizer.ts

@@ -13,7 +13,7 @@ import type {
 } from "@fluidframework/runtime-definitions/internal";
 import { createSingleBlobSummary } from "@fluidframework/shared-object-base/internal";
 
-import { type ICodecOptions, noopValidator } from "../../codec/index.js";
+import type { CodecWriteOptions } from "../../codec/index.js";
 import {
 	type DeltaDetachedNodeBuild,
 	type DeltaFieldChanges,
@@ -60,9 +60,10 @@ export class ForestSummarizer implements Summarizable {
 		private readonly revisionTagCodec: RevisionTagCodec,
 		fieldBatchCodec: FieldBatchCodec,
 		private readonly encoderContext: FieldBatchEncodingContext,
-		options: ICodecOptions = { jsonValidator: noopValidator },
+		options: CodecWriteOptions,
 		private readonly idCompressor: IIdCompressor,
 	) {
+		// TODO: this should take in CodecWriteOptions, and use it to pick the write version.
 		this.codec = makeForestSummarizerCodec(options, fieldBatchCodec);
 	}
 

package/src/feature-libraries/index.ts

@@ -15,6 +15,11 @@ export {
 	cursorForMapTreeNode,
 	mapTreeFromCursor,
 	mapTreeFieldFromCursor,
+	type MinimalMapTreeNodeView,
+	mapTreeFieldsWithField,
+	mapTreeWithField,
+	type MapTreeFieldViewGeneric,
+	type MapTreeNodeViewGeneric,
 } from "./mapTreeCursor.js";
 export { buildForest } from "./object-forest/index.js";
 export {
@@ -174,6 +179,10 @@ export {
 	treeStatusFromAnchorCache,
 	indexForAt,
 	FlexTreeEntityKind,
+	type FlexibleNodeContent,
+	type FlexibleFieldContent,
+	type FlexTreeHydratedContextMinimal,
+	type HydratedFlexTreeNode,
 } from "./flex-tree/index.js";
 
 export { TreeCompressionStrategy } from "./treeCompressionUtils.js";

package/src/feature-libraries/mapTreeCursor.ts

@@ -12,49 +12,136 @@ import {
 	type FieldKey,
 	type ITreeCursor,
 	type MapTree,
+	type NodeData,
 	aboveRootPlaceholder,
 	detachedFieldAsKey,
 	mapCursorField,
 	rootField,
+	rootFieldKey,
 } from "../core/index.js";
 
 import {
 	type CursorAdapter,
 	type CursorWithNode,
+	type Field,
 	stackTreeFieldCursor,
 	stackTreeNodeCursor,
 } from "./treeCursorUtils.js";
+import type { requireAssignableTo } from "../util/index.js";
+
+/**
+ * A generic variant of {@link MapTree} that can be used to strongly type trees implementing a MapTree-like API.
+ * @remarks
+ * Due to how TypeScript handles recursive generic types, explicitly named extension interfaces work best for parameterizing this, and a default type parameter can't be provided.
+ * @see {@link MinimalMapTreeNodeView} for a minimal configuration of this interface.
+ */
+export interface MapTreeNodeViewGeneric<TNode> extends NodeData {
+	/**
+	 * The non-empty fields on this node.
+	 * @remarks
+	 * This is the subset of map needed to view the tree.
+	 * Theoretically `Symbol.iterator` and "keys" are redundant.
+	 */
+	readonly fields: Pick<
+		Map<FieldKey, MapTreeFieldViewGeneric<TNode>>,
+		typeof Symbol.iterator | "get"
+	>;
+}
+
+/**
+ * A field in {@link MapTreeNodeViewGeneric}.
+ */
+export type MapTreeFieldViewGeneric<TNode> = Pick<
+	readonly TNode[],
+	typeof Symbol.iterator | "length"
+>;
+
+/**
+ * Like {@link MapTree} but with the minimal properties needed for reading.
+ */
+export interface MinimalMapTreeNodeView
+	extends MapTreeNodeViewGeneric<MinimalMapTreeNodeView> {}
+
+{
+	// Check that these interfaces are subsets of MapTree as intended:
+	type _check1 = requireAssignableTo<MapTree, MinimalMapTreeNodeView>;
+	type _check2 = requireAssignableTo<MapTree, MapTreeNodeViewGeneric<MapTree>>;
+}
 
 /**
  * Returns an {@link ITreeCursorSynchronous} in nodes mode for a single {@link MapTree}.
  */
-export function cursorForMapTreeNode(root: MapTree): CursorWithNode<MapTree> {
-	return stackTreeNodeCursor(adapter, root);
+export function cursorForMapTreeNode<T extends MapTreeNodeViewGeneric<T>>(
+	root: T,
+): CursorWithNode<T> {
+	// There doesn't seem to be a clean way to get TypeScript to type check this without casting
+	// without declaring the adapter inside this generic function and needlessly recreating it on every call.
+	const adapterTyped = adapter as CursorAdapter<MapTreeNodeViewGeneric<T>> as CursorAdapter<T>;
+	return stackTreeNodeCursor(adapterTyped, root);
+}
+
+/**
+ * Creates an {@link ExclusiveMapTree} with a single field and no value.
+ * @remarks
+ * This handles ensuring the field is omitted if empty, and defaults to making the node above the root.
+ */
+export function mapTreeWithField(
+	children: ExclusiveMapTree[],
+	key = rootFieldKey,
+	type = aboveRootPlaceholder,
+): ExclusiveMapTree {
+	return {
+		type,
+		fields: mapTreeFieldsWithField(children, key),
+	};
+}
+
+/**
+ * Creates a Map suitable for use as {@link MapTree.fields} with a single field.
+ * @remarks
+ * This handles ensuring the field is omitted if empty.
+ */
+export function mapTreeFieldsWithField<T extends readonly unknown[]>(
+	children: T,
+	key: FieldKey,
+): Map<FieldKey, T> {
+	return new Map(children.length === 0 ? [] : [[key, children]]);
 }
 
 /**
  * Returns an {@link ITreeCursorSynchronous} in fields mode for a MapTree field.
  */
-export function cursorForMapTreeField(
-	root: readonly MapTree[],
+export function cursorForMapTreeField<T extends MapTreeNodeViewGeneric<T>>(
+	root: readonly T[],
 	detachedField: DetachedField = rootField,
-): CursorWithNode<MapTree> {
+): CursorWithNode<T> {
 	const key = detachedFieldAsKey(detachedField);
-	return stackTreeFieldCursor(
-		adapter,
-		{
-			type: aboveRootPlaceholder,
-			fields: new Map([[key, root]]),
-		},
-		detachedField,
-	);
+	const adapterTyped = adapter as unknown as CursorAdapter<T>;
+	const dummyRoot: MapTreeNodeViewGeneric<T> = {
+		type: aboveRootPlaceholder,
+		fields: mapTreeFieldsWithField(root, key),
+	};
+	return stackTreeFieldCursor(adapterTyped, dummyRoot as T, detachedField);
 }
 
-const adapter: CursorAdapter<MapTree> = {
+const adapter: CursorAdapter<MinimalMapTreeNodeView> = {
 	value: (node) => node.value,
 	type: (node) => node.type,
-	keysFromNode: (node) => [...node.fields.keys()], // TODO: don't convert this to array here.
-	getFieldFromNode: (node, key) => node.fields.get(key) ?? [],
+	keysFromNode: (node) => Array.from(node.fields, ([key, field]) => key),
+	getFieldFromNode: (node, key): Field<MinimalMapTreeNodeView> => {
+		const field = node.fields.get(key) as
+			| MinimalMapTreeNodeView[]
+			| Iterable<MinimalMapTreeNodeView>
+			| undefined;
+		if (field === undefined) {
+			return [];
+		}
+		if (Array.isArray(field)) {
+			return field as readonly MinimalMapTreeNodeView[];
+		}
+		// TODO: this copy could be avoided by using Array.at instead of indexing in `Field`, but that requires ES2022.
+		return [...field] as readonly MinimalMapTreeNodeView[];
+	},
 };
 
 /**

package/src/feature-libraries/modular-schema/modularChangeCodecs.ts

@@ -76,7 +76,7 @@ export function makeModularChangeCodecFamily(
 		ChangeEncodingContext
 	>,
 	fieldsCodec: FieldBatchCodec,
-	{ jsonValidator: validator }: ICodecOptions,
+	codecOptions: ICodecOptions,
 	chunkCompressionStrategy: TreeCompressionStrategy = TreeCompressionStrategy.Compressed,
 ): ICodecFamily<ModularChangeset, ChangeEncodingContext> {
 	return makeCodecFamily(
@@ -86,7 +86,7 @@ export function makeModularChangeCodecFamily(
 				fieldKinds,
 				revisionTagCodec,
 				fieldsCodec,
-				{ jsonValidator: validator },
+				codecOptions,
 				chunkCompressionStrategy,
 			),
 		]),
@@ -116,7 +116,7 @@ function makeModularChangeCodec(
 		ChangeEncodingContext
 	>,
 	fieldsCodec: FieldBatchCodec,
-	{ jsonValidator: validator }: ICodecOptions,
+	codecOptions: ICodecOptions,
 	chunkCompressionStrategy: TreeCompressionStrategy = TreeCompressionStrategy.Compressed,
 ): ModularChangeCodec {
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -125,7 +125,7 @@ function makeModularChangeCodec(
 		return {
 			codec,
 			compiledSchema: codec.json.encodedSchema
-				? validator.compile(codec.json.encodedSchema)
+				? codecOptions.jsonValidator.compile(codec.json.encodedSchema)
 				: undefined,
 		};
 	};
@@ -519,7 +519,11 @@ function makeModularChangeCodec(
 		},
 	};
 
-	return withSchemaValidation(EncodedModularChangeset, modularChangeCodec, validator);
+	return withSchemaValidation(
+		EncodedModularChangeset,
+		modularChangeCodec,
+		codecOptions.jsonValidator,
+	);
 }
 
 function getChangeHandler(

package/src/feature-libraries/treeCursorUtils.ts

@@ -72,6 +72,11 @@ export function stackTreeFieldCursor<TNode>(
 	return cursor;
 }
 
+/**
+ * The representation of a field used by {@link CursorAdapter}.
+ */
+export type Field<TNode> = Pick<readonly TNode[], typeof Symbol.iterator | "length" | number>;
+
 /**
  * Provides functionality to allow a {@link stackTreeNodeCursor} and {@link stackTreeFieldCursor} to implement cursors.
  */
@@ -91,10 +96,10 @@ export interface CursorAdapter<TNode> {
 	/**
 	 * @returns the child nodes for the given node and key.
 	 */
-	getFieldFromNode(node: TNode, key: FieldKey): readonly TNode[];
+	getFieldFromNode(node: TNode, key: FieldKey): Field<TNode>;
 }
 
-type SiblingsOrKey<TNode> = readonly TNode[] | readonly FieldKey[];
+type SiblingsOrKey<TNode> = Field<TNode> | readonly FieldKey[];
 
 /**
  * A class that satisfies part of the ITreeCursorSynchronous implementation.
@@ -122,7 +127,7 @@ export abstract class SynchronousCursor {
  * 2. Support for cursors which are field cursors at the root.
  */
 class StackCursor<TNode> extends SynchronousCursor implements CursorWithNode<TNode> {
-	public readonly [CursorMarker] = true;
+	public override readonly [CursorMarker] = true;
 	/**
 	 * Might start at special root where fields are detached sequences.
 	 *
@@ -149,14 +154,18 @@ class StackCursor<TNode> extends SynchronousCursor implements CursorWithNode<TNo
 		debugAssert(() =>
 			this.mode === CursorLocationType.Fields ? true : "must be in fields mode",
 		);
-		return this.siblings[this.index] as FieldKey;
+		// index is kept inbounds as an invariant of the class.
+		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+		return (this.siblings as readonly FieldKey[])[this.index]!;
 	}
 
 	private getStackedFieldKey(height: number): FieldKey {
 		assert(height % 2 === 1, 0x3b8 /* must field height */);
 		const siblingStack = this.siblingStack[height] ?? oob();
 		const indexStack = this.indexStack[height] ?? oob();
-		return siblingStack[indexStack] as FieldKey;
+		// index is kept inbounds as an invariant of the class.
+		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+		return (siblingStack as readonly FieldKey[])[indexStack]!;
 	}
 
 	private getStackedNodeIndex(height: number): number {
@@ -166,9 +175,10 @@ class StackCursor<TNode> extends SynchronousCursor implements CursorWithNode<TNo
 
 	private getStackedNode(height: number): TNode {
 		const index = this.getStackedNodeIndex(height);
-		// Test is failing when using `?? oob()` here.
+		// Can not use `?? oob()` since null and undefined are valid values.
+		// index is kept inbounds as an invariant of the class.
 		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-		return (this.siblingStack[height] as readonly TNode[])[index]!;
+		return (this.siblingStack[height] as Field<TNode>)[index]!;
 	}
 
 	public getFieldLength(): number {
@@ -358,12 +368,13 @@ class StackCursor<TNode> extends SynchronousCursor implements CursorWithNode<TNo
 
 	public getNode(): TNode {
 		// assert(this.mode === CursorLocationType.Nodes, "can only get node when in node");
-		// Test is failing when using `?? oob()` here.
+		// Can not use `?? oob()` since null and undefined are valid values.
+		// index is kept inbounds as an invariant of the class.
 		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-		return (this.siblings as TNode[])[this.index]!;
+		return (this.siblings as Field<TNode>)[this.index]!;
 	}
 
-	private getField(): readonly TNode[] {
+	private getField(): Field<TNode> {
 		// assert(this.mode === CursorLocationType.Fields, "can only get field when in fields");
 		const parent = this.getStackedNode(this.indexStack.length - 1);
 		const key: FieldKey = this.getFieldKey();

package/src/index.ts

@@ -255,6 +255,7 @@ export { persistedToSimpleSchema } from "./shared-tree/index.js";
 
 export {
 	type ICodecOptions,
+	type CodecWriteOptions,
 	type JsonValidator,
 	type SchemaValidationFunction,
 	FluidClientVersion,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.41.0";
+export const pkgVersion = "2.42.0";