@fluidframework/tree 2.51.0 → 2.52.0

package/src/feature-libraries/chunked-forest/codec/README.md

@@ -19,7 +19,7 @@ A few implementations are included which make different choices here:
 
 -   [uncompressedEncode.ts](uncompressedEncode.ts): the simplest implementation, which captures nothing in the shape and does no Dictionary Coding of identifiers.
     This makes for more human readable data as well as a simple reference implementation.
--   [compressedEncode.ts](compressedEncode.ts): some utilities for actual compressed encoding, but does not contain any advanced strategies (instead they must be provided to it via the `EncoderCache`)
+-   [compressedEncode.ts](compressedEncode.ts): some utilities for actual compressed encoding, but does not contain any advanced strategies (instead they must be provided to it via the `EncoderContext`)
 -   [schemaBasedEncode.ts](schemaBasedEncode.ts): a strategy for compressedEncode using schema to infer commonly used shapes.
 
 ### Future Optimizations

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

@@ -41,9 +41,9 @@ import {
 	type EncodedAnyShape,
 	type EncodedChunkShape,
 	type EncodedFieldBatch,
-	type EncodedInlineArray,
-	type EncodedNestedArray,
-	type EncodedTreeShape,
+	type EncodedInlineArrayShape,
+	type EncodedNestedArrayShape,
+	type EncodedNodeShape,
 	type EncodedValueShape,
 	SpecialField,
 } from "./format.js";
@@ -72,17 +72,17 @@ export function decode(
 
 const decoderLibrary = new DiscriminatedUnionDispatcher<
 	EncodedChunkShape,
-	[cache: DecoderContext<EncodedChunkShape>],
+	[context: DecoderContext<EncodedChunkShape>],
 	ChunkDecoder
 >({
-	a(shape: EncodedNestedArray, cache): ChunkDecoder {
+	a(shape: EncodedNestedArrayShape, context): ChunkDecoder {
 		return new NestedArrayDecoder(shape);
 	},
-	b(shape: EncodedInlineArray, cache): ChunkDecoder {
+	b(shape: EncodedInlineArrayShape, context): ChunkDecoder {
 		return new InlineArrayDecoder(shape);
 	},
-	c(shape: EncodedTreeShape, cache): ChunkDecoder {
-		return new TreeDecoder(shape, cache);
+	c(shape: EncodedNodeShape, context): ChunkDecoder {
+		return new NodeDecoder(shape, context);
 	},
 	d(shape: EncodedAnyShape): ChunkDecoder {
 		return anyDecoder;
@@ -180,10 +180,10 @@ export function aggregateChunks(input: TreeChunk[]): TreeChunk {
 }
 
 /**
- * Decoder for {@link EncodedNestedArray}s.
+ * Decoder for {@link EncodedNestedArrayShape}s.
  */
 export class NestedArrayDecoder implements ChunkDecoder {
-	public constructor(private readonly shape: EncodedNestedArray) {}
+	public constructor(private readonly shape: EncodedNestedArrayShape) {}
 	public decode(decoders: readonly ChunkDecoder[], stream: StreamCursor): TreeChunk {
 		const decoder = decoders[this.shape] ?? oob();
 
@@ -213,10 +213,10 @@ export class NestedArrayDecoder implements ChunkDecoder {
 }
 
 /**
- * Decoder for {@link EncodedInlineArray}s.
+ * Decoder for {@link EncodedInlineArrayShape}s.
  */
 export class InlineArrayDecoder implements ChunkDecoder {
-	public constructor(private readonly shape: EncodedInlineArray) {}
+	public constructor(private readonly shape: EncodedInlineArrayShape) {}
 	public decode(decoders: readonly ChunkDecoder[], stream: StreamCursor): TreeChunk {
 		const length = this.shape.length;
 		const decoder = decoders[this.shape.shape] ?? oob();
@@ -248,14 +248,14 @@ type BasicFieldDecoder = (
 ) => [FieldKey, TreeChunk];
 
 /**
- * Get a decoder for fields of a provided (via `shape` and `cache`) {@link EncodedChunkShape}.
+ * Get a decoder for fields of a provided (via `shape` and `context`) {@link EncodedChunkShape}.
  */
 function fieldDecoder(
-	cache: DecoderContext<EncodedChunkShape>,
+	context: DecoderContext<EncodedChunkShape>,
 	key: FieldKey,
 	shape: number,
 ): BasicFieldDecoder {
-	assertValidIndex(shape, cache.shapes);
+	assertValidIndex(shape, context.shapes);
 	return (decoders, stream) => {
 		const decoder = decoders[shape] ?? oob();
 		return [key, decoder.decode(decoders, stream)];
@@ -263,30 +263,30 @@ function fieldDecoder(
 }
 
 /**
- * Decoder for {@link EncodedTreeShape}s.
+ * Decoder for {@link EncodedNodeShape}s.
  */
-export class TreeDecoder implements ChunkDecoder {
+export class NodeDecoder implements ChunkDecoder {
 	private readonly type?: TreeNodeSchemaIdentifier;
 	private readonly fieldDecoders: readonly BasicFieldDecoder[];
 	public constructor(
-		private readonly shape: EncodedTreeShape,
-		private readonly cache: DecoderContext<EncodedChunkShape>,
+		private readonly shape: EncodedNodeShape,
+		private readonly context: DecoderContext<EncodedChunkShape>,
 	) {
-		this.type = shape.type === undefined ? undefined : cache.identifier(shape.type);
+		this.type = shape.type === undefined ? undefined : context.identifier(shape.type);
 
 		const fieldDecoders: BasicFieldDecoder[] = [];
 		for (const [fieldKey, fieldShape] of shape.fields ?? []) {
-			const key: FieldKey = cache.identifier(fieldKey);
-			fieldDecoders.push(fieldDecoder(cache, key, fieldShape));
+			const key: FieldKey = context.identifier(fieldKey);
+			fieldDecoders.push(fieldDecoder(context, key, fieldShape));
 		}
 		this.fieldDecoders = fieldDecoders;
 	}
 	public decode(decoders: readonly ChunkDecoder[], stream: StreamCursor): TreeChunk {
 		const type: TreeNodeSchemaIdentifier =
-			this.type ?? readStreamIdentifier(stream, this.cache);
+			this.type ?? readStreamIdentifier(stream, this.context);
 		// TODO: Consider typechecking against stored schema in here somewhere.
 
-		const value = readValue(stream, this.shape.value, this.cache.idDecodingContext);
+		const value = readValue(stream, this.shape.value, this.context.idDecodingContext);
 		const fields: Map<FieldKey, TreeChunk[]> = new Map();
 
 		// Helper to add fields, but with unneeded array chunks removed.
@@ -309,7 +309,7 @@ export class TreeDecoder implements ChunkDecoder {
 			const decoder = decoders[this.shape.extraFields] ?? oob();
 			const inner = readStreamStream(stream);
 			while (inner.offset !== inner.data.length) {
-				const key: FieldKey = readStreamIdentifier(inner, this.cache);
+				const key: FieldKey = readStreamIdentifier(inner, this.context);
 				addField(key, decoder.decode(decoders, inner));
 			}
 		}

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

@@ -21,13 +21,17 @@ import type { EncodedFieldBatchGeneric, IdentifierOrIndex } from "./formatGeneri
 /**
  * General purpose shape based tree decoder which gets its support for specific shapes from the caller.
  */
-export function decode<TEncodedShape extends object, TCache>(
-	decoderLibrary: DiscriminatedUnionDispatcher<TEncodedShape, [cache: TCache], ChunkDecoder>,
-	cache: TCache,
+export function decode<TEncodedShape extends object, TContext>(
+	decoderLibrary: DiscriminatedUnionDispatcher<
+		TEncodedShape,
+		[context: TContext],
+		ChunkDecoder
+	>,
+	context: TContext,
 	batch: EncodedFieldBatchGeneric<TEncodedShape>,
 	rootDecoder: ChunkDecoder,
 ): TreeChunk[] {
-	const decoders = batch.shapes.map((shape) => decoderLibrary.dispatch(shape, cache));
+	const decoders = batch.shapes.map((shape) => decoderLibrary.dispatch(shape, context));
 	const chunks: TreeChunk[] = [];
 	for (const field of batch.data) {
 		const stream = { data: field, offset: 0 };
@@ -70,12 +74,12 @@ export class DecoderContext<TEncodedShape = unknown> {
  */
 export function readStreamIdentifier<T extends string & BrandedType<string, string>>(
 	stream: StreamCursor,
-	cache: DecoderContext,
+	context: DecoderContext,
 ): T {
 	const content = readStream(stream);
 	assert(
 		typeof content === "number" || typeof content === "string",
 		0x73b /* content to be a number or string */,
 	);
-	return cache.identifier(content);
+	return context.identifier(content);
 }

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

@@ -30,7 +30,7 @@ import {
 	type EncodedAnyShape,
 	type EncodedChunkShape,
 	type EncodedFieldBatch,
-	type EncodedNestedArray,
+	type EncodedNestedArrayShape,
 	type EncodedValueShape,
 	SpecialField,
 	version,
@@ -41,18 +41,18 @@ import {
  *
  * Optimized for encoded size and encoding performance.
  *
- * Most of the compression strategy comes from the policy provided via `cache`.
+ * Most of the compression strategy comes from the policy provided via `context`.
  */
 export function compressedEncode(
 	fieldBatch: FieldBatch,
-	cache: EncoderCache,
+	context: EncoderContext,
 ): EncodedFieldBatch {
 	const batchBuffer: BufferFormat[] = [];
 
 	// Populate buffer, including shape and identifier references
 	for (const cursor of fieldBatch) {
 		const buffer: BufferFormat = [];
-		anyFieldEncoder.encodeField(cursor, cache, buffer);
+		anyFieldEncoder.encodeField(cursor, context, buffer);
 		batchBuffer.push(buffer);
 	}
 	return updateShapesAndIdentifiersEncoding(version, batchBuffer);
@@ -91,7 +91,7 @@ export interface NodeEncoder extends Encoder {
 	 */
 	encodeNode(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
 	): void;
 }
@@ -105,7 +105,7 @@ export interface NodesEncoder extends Encoder {
 	 */
 	encodeNodes(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
 	): void;
 }
@@ -119,7 +119,7 @@ export interface FieldEncoder extends Encoder {
 	 */
 	encodeField(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
 	): void;
 }
@@ -132,10 +132,10 @@ export function asFieldEncoder(encoder: NodeEncoder): FieldEncoder {
 	return {
 		encodeField(
 			cursor: ITreeCursorSynchronous,
-			shapes: EncoderCache,
+			context: EncoderContext,
 			outputBuffer: BufferFormat,
 		): void {
-			forEachNode(cursor, () => encoder.encodeNode(cursor, shapes, outputBuffer));
+			forEachNode(cursor, () => encoder.encodeNode(cursor, context, outputBuffer));
 		},
 		shape: encoder.shape,
 	};
@@ -148,10 +148,10 @@ export function asNodesEncoder(encoder: NodeEncoder): NodesEncoder {
 	return {
 		encodeNodes(
 			cursor: ITreeCursorSynchronous,
-			shapes: EncoderCache,
+			context: EncoderContext,
 			outputBuffer: BufferFormat,
 		): void {
-			encoder.encodeNode(cursor, shapes, outputBuffer);
+			encoder.encodeNode(cursor, context, outputBuffer);
 			cursor.nextNode();
 		},
 		shape: encoder.shape,
@@ -182,32 +182,32 @@ export class AnyShape extends ShapeGeneric<EncodedChunkShape> {
 
 	public static encodeField(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
-		shape: FieldEncoder,
+		encoder: FieldEncoder,
 	): void {
-		outputBuffer.push(shape.shape);
-		shape.encodeField(cursor, cache, outputBuffer);
+		outputBuffer.push(encoder.shape);
+		encoder.encodeField(cursor, context, outputBuffer);
 	}
 
 	public static encodeNode(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
-		shape: NodeEncoder,
+		encoder: NodeEncoder,
 	): void {
-		outputBuffer.push(shape.shape);
-		shape.encodeNode(cursor, cache, outputBuffer);
+		outputBuffer.push(encoder.shape);
+		encoder.encodeNode(cursor, context, outputBuffer);
 	}
 
 	public static encodeNodes(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
-		shape: NodesEncoder,
+		encoder: NodesEncoder,
 	): void {
-		outputBuffer.push(shape.shape);
-		shape.encodeNodes(cursor, cache, outputBuffer);
+		outputBuffer.push(encoder.shape);
+		encoder.encodeNodes(cursor, context, outputBuffer);
 	}
 }
 
@@ -217,12 +217,12 @@ export class AnyShape extends ShapeGeneric<EncodedChunkShape> {
 export const anyNodeEncoder: NodeEncoder = {
 	encodeNode(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
 	): void {
 		// TODO: Fast path uniform chunk content.
-		const shape = cache.shapeFromTree(cursor.type);
-		AnyShape.encodeNode(cursor, cache, outputBuffer, shape);
+		const shape = context.nodeEncoderFromSchema(cursor.type);
+		AnyShape.encodeNode(cursor, context, outputBuffer, shape);
 	},
 
 	shape: AnyShape.instance,
@@ -234,25 +234,25 @@ export const anyNodeEncoder: NodeEncoder = {
 export const anyFieldEncoder: FieldEncoder = {
 	encodeField(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
 	): void {
 		// TODO: Fast path uniform chunks.
 
 		if (cursor.getFieldLength() === 0) {
-			const shape = InlineArrayShape.empty;
-			AnyShape.encodeField(cursor, cache, outputBuffer, shape);
+			const shape = InlineArrayEncoder.empty;
+			AnyShape.encodeField(cursor, context, outputBuffer, shape);
 		} else if (cursor.getFieldLength() === 1) {
 			// Fast path chunk of size one size one at least: skip nested array.
 			cursor.enterNode(0);
-			anyNodeEncoder.encodeNode(cursor, cache, outputBuffer);
+			anyNodeEncoder.encodeNode(cursor, context, outputBuffer);
 			cursor.exitNode();
 		} else {
 			// TODO: more efficient encoding for common cases.
 			// Could try to find more specific shape compatible with all children than `anyNodeEncoder`.
 
-			const shape = cache.nestedArray(anyNodeEncoder);
-			AnyShape.encodeField(cursor, cache, outputBuffer, shape);
+			const shape = context.nestedArrayEncoder(anyNodeEncoder);
+			AnyShape.encodeField(cursor, context, outputBuffer, shape);
 		}
 	},
 
@@ -260,20 +260,23 @@ export const anyFieldEncoder: FieldEncoder = {
 };
 
 /**
- * Encodes a chunk using {@link EncodedInlineArray}.
+ * Encodes a chunk using {@link EncodedInlineArrayShape}.
+ * @remarks
+ * The fact this is also a Shape is an implementation detail of the encoder: that allows the shape it uses to be itself,
+ * which is an easy way to keep all the related code together without extra objects.
  */
-export class InlineArrayShape
+export class InlineArrayEncoder
 	extends ShapeGeneric<EncodedChunkShape>
 	implements NodesEncoder, FieldEncoder
 {
-	public static readonly empty: InlineArrayShape = new InlineArrayShape(0, {
+	public static readonly empty: InlineArrayEncoder = new InlineArrayEncoder(0, {
 		get shape() {
 			// Not actually used, makes count work without adding an additional shape.
-			return InlineArrayShape.empty;
+			return InlineArrayEncoder.empty;
 		},
 		encodeNodes(
 			cursor: ITreeCursorSynchronous,
-			shapes: EncoderCache,
+			context: EncoderContext,
 			outputBuffer: BufferFormat,
 		): void {
 			fail(0xb4d /* Empty array should not encode any nodes */);
@@ -292,19 +295,19 @@ export class InlineArrayShape
 
 	public encodeNodes(
 		cursor: ITreeCursorSynchronous,
-		shapes: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
 	): void {
 		// Linter is wrong about this loop being for-of compatible.
 		// eslint-disable-next-line @typescript-eslint/prefer-for-of
 		for (let index = 0; index < this.length; index++) {
-			this.inner.encodeNodes(cursor, shapes, outputBuffer);
+			this.inner.encodeNodes(cursor, context, outputBuffer);
 		}
 	}
 
 	public encodeField(
 		cursor: ITreeCursorSynchronous,
-		shapes: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
 	): void {
 		// Its possible individual items from this array encode multiple nodes, so don't assume === here.
@@ -313,7 +316,7 @@ export class InlineArrayShape
 			0x73c /* unexpected length for fixed length array */,
 		);
 		cursor.firstNode();
-		this.encodeNodes(cursor, shapes, outputBuffer);
+		this.encodeNodes(cursor, context, outputBuffer);
 		assert(
 			cursor.mode === CursorLocationType.Fields,
 			0x73d /* should return to fields mode when finished encoding */,
@@ -345,9 +348,15 @@ export class InlineArrayShape
 }
 
 /**
- * Encodes a field as a nested array with the {@link EncodedNestedArray} shape.
+ * Encodes a field as a nested array with the {@link EncodedNestedArrayShape} shape.
+ * @remarks
+ * The fact this is also a Shape is an implementation detail of the encoder: that allows the shape it uses to be itself,
+ * which is an easy way to keep all the related code together without extra objects.
  */
-export class NestedArrayShape extends ShapeGeneric<EncodedChunkShape> implements FieldEncoder {
+export class NestedArrayEncoder
+	extends ShapeGeneric<EncodedChunkShape>
+	implements FieldEncoder
+{
 	public readonly shape: Shape;
 
 	public constructor(public readonly inner: NodeEncoder) {
@@ -357,7 +366,7 @@ export class NestedArrayShape extends ShapeGeneric<EncodedChunkShape> implements
 
 	public encodeField(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
 	): void {
 		const buffer: BufferFormat = [];
@@ -365,7 +374,7 @@ export class NestedArrayShape extends ShapeGeneric<EncodedChunkShape> implements
 		const length = cursor.getFieldLength();
 		forEachNode(cursor, () => {
 			const before = buffer.length;
-			this.inner.encodeNode(cursor, cache, buffer);
+			this.inner.encodeNode(cursor, context, buffer);
 			allNonZeroSize &&= buffer.length - before !== 0;
 		});
 		if (buffer.length === 0) {
@@ -385,7 +394,7 @@ export class NestedArrayShape extends ShapeGeneric<EncodedChunkShape> implements
 		identifiers: DeduplicationTable<string>,
 		shapes: DeduplicationTable<Shape>,
 	): EncodedChunkShape {
-		const shape: EncodedNestedArray =
+		const shape: EncodedNestedArrayShape =
 			shapes.valueToIndex.get(this.inner.shape) ??
 			fail(0xb4f /* index for shape not found in table */);
 		return {
@@ -436,46 +445,60 @@ export function encodeValue(
 	}
 }
 
-export class EncoderCache implements TreeShaper, FieldShaper {
-	private readonly shapesFromSchema: Map<TreeNodeSchemaIdentifier, NodeEncoder> = new Map();
-	private readonly nestedArrays: Map<NodeEncoder, NestedArrayShape> = new Map();
+/**
+ * Provides common contextual information during encoding, like schema and policy settings.
+ * Also, provides a cache to avoid duplicating equivalent shapes during a batch of encode operations.
+ * To avoid Shape duplication, any Shapes used in the encoding should either be:
+ * - Singletons defined in a static scope.
+ * - Cached in this object for future reuse such that all equivalent Shapes are deduplicated.
+ */
+export class EncoderContext implements NodeEncodeBuilder, FieldEncodeBuilder {
+	private readonly nodeEncodersFromSchema: Map<TreeNodeSchemaIdentifier, NodeEncoder> =
+		new Map();
+	private readonly nestedArrayEncoders: Map<NodeEncoder, NestedArrayEncoder> = new Map();
 	public constructor(
-		private readonly treeEncoder: TreeShapePolicy,
-		private readonly fieldEncoder: FieldShapePolicy,
+		private readonly nodeEncoderFromPolicy: NodeEncoderPolicy,
+		private readonly fieldEncoderFromPolicy: FieldEncoderPolicy,
 		public readonly fieldShapes: ReadonlyMap<FieldKindIdentifier, FlexFieldKind>,
 		public readonly idCompressor: IIdCompressor,
 	) {}
 
-	public shapeFromTree(schemaName: TreeNodeSchemaIdentifier): NodeEncoder {
-		return getOrCreate(this.shapesFromSchema, schemaName, () =>
-			this.treeEncoder(this, schemaName),
+	public nodeEncoderFromSchema(schemaName: TreeNodeSchemaIdentifier): NodeEncoder {
+		return getOrCreate(this.nodeEncodersFromSchema, schemaName, () =>
+			this.nodeEncoderFromPolicy(this, schemaName),
 		);
 	}
 
-	public nestedArray(inner: NodeEncoder): NestedArrayShape {
-		return getOrCreate(this.nestedArrays, inner, () => new NestedArrayShape(inner));
+	public fieldEncoderFromSchema(fieldSchema: TreeFieldStoredSchema): FieldEncoder {
+		return new LazyFieldEncoder(this, fieldSchema, this.fieldEncoderFromPolicy);
 	}
 
-	public shapeFromField(field: TreeFieldStoredSchema): FieldEncoder {
-		return new LazyFieldEncoder(this, field, this.fieldEncoder);
+	public nestedArrayEncoder(inner: NodeEncoder): NestedArrayEncoder {
+		return getOrCreate(this.nestedArrayEncoders, inner, () => new NestedArrayEncoder(inner));
 	}
 }
 
-export interface TreeShaper {
-	shapeFromTree(schemaName: TreeNodeSchemaIdentifier): NodeEncoder;
+export interface NodeEncodeBuilder {
+	nodeEncoderFromSchema(schemaName: TreeNodeSchemaIdentifier): NodeEncoder;
 }
 
-export interface FieldShaper {
-	shapeFromField(field: TreeFieldStoredSchema): FieldEncoder;
+export interface FieldEncodeBuilder {
+	fieldEncoderFromSchema(schema: TreeFieldStoredSchema): FieldEncoder;
 }
 
-export type FieldShapePolicy = (
-	treeShaper: TreeShaper,
-	field: TreeFieldStoredSchema,
+/**
+ * The policy for building a {@link FieldEncoder} for a field.
+ */
+export type FieldEncoderPolicy = (
+	nodeBuilder: NodeEncodeBuilder,
+	schema: TreeFieldStoredSchema,
 ) => FieldEncoder;
 
-export type TreeShapePolicy = (
-	fieldShaper: FieldShaper,
+/**
+ * The policy for building a {@link NodeEncoder} for a node.
+ */
+export type NodeEncoderPolicy = (
+	fieldBuilder: FieldEncodeBuilder,
 	schemaName: TreeNodeSchemaIdentifier,
 ) => NodeEncoder;
 
@@ -483,21 +506,21 @@ class LazyFieldEncoder implements FieldEncoder {
 	private encoderLazy: FieldEncoder | undefined;
 
 	public constructor(
-		public readonly cache: TreeShaper,
-		public readonly field: TreeFieldStoredSchema,
-		private readonly fieldEncoder: FieldShapePolicy,
+		public readonly nodeBuilder: NodeEncodeBuilder,
+		public readonly fieldSchema: TreeFieldStoredSchema,
+		private readonly fieldEncoderFromPolicy: FieldEncoderPolicy,
 	) {}
 	public encodeField(
 		cursor: ITreeCursorSynchronous,
-		cache: EncoderCache,
+		context: EncoderContext,
 		outputBuffer: BufferFormat,
 	): void {
-		this.encoder.encodeField(cursor, cache, outputBuffer);
+		this.encoder.encodeField(cursor, context, outputBuffer);
 	}
 
 	private get encoder(): FieldEncoder {
 		if (this.encoderLazy === undefined) {
-			this.encoderLazy = this.fieldEncoder(this.cache, this.field);
+			this.encoderLazy = this.fieldEncoderFromPolicy(this.nodeBuilder, this.fieldSchema);
 		}
 		return this.encoderLazy;
 	}

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

@@ -24,12 +24,12 @@ export const validVersions = new Set([version]);
  * Top level length is implied from length of data array.
  * All content are of this shape.
  */
-export const EncodedNestedArray = ShapeIndex;
+export const EncodedNestedArrayShape = ShapeIndex;
 
 /**
  * Inline array.
  */
-export const EncodedInlineArray = Type.Object(
+export const EncodedInlineArrayShape = Type.Object(
 	{
 		length: Count,
 		/**
@@ -123,7 +123,7 @@ export enum SpecialField {
  * In the future other value shape formats may be added, likely as objects.
  *
  * @remarks
- * See {@link EncodedTreeShape} for usage.
+ * See {@link EncodedNodeShape} for usage.
  */
 export const EncodedValueShape = Type.Union([
 	Type.Boolean(),
@@ -134,7 +134,7 @@ export const EncodedValueShape = Type.Union([
 ]);
 export type EncodedValueShape = undefined | Static<typeof EncodedValueShape>;
 
-export const EncodedTreeShape = Type.Object(
+export const EncodedNodeShape = Type.Object(
 	{
 		/**
 		 * If not provided, inlined in data.
@@ -157,24 +157,30 @@ export const EncodedTreeShape = Type.Object(
 );
 
 /**
- * Discriminated union of chunk shapes.
+ * Discriminated union that represents the shapes of chunks in the encoded data.
+ * "Chunk" here refers to a chunk of tree data, rooted at a range of nodes, that is encoded as a
+ * single unit in a specific format represented by one of the shapes in this union.
+ *
+ * The concept of "chunk" is same for the tree data in memory and in the encoded wire format.
+ * The physical representation of the chunk may differ, but the logical structure remains the same.
+ * This is similar to other such concepts in the system.
  *
  * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
  */
 export const EncodedChunkShape = Type.Object(
 	{
 		/**
-		 * {@link EncodedNestedArray} union member.
+		 * {@link EncodedNestedArrayShape} union member.
 		 */
-		a: Type.Optional(EncodedNestedArray),
+		a: Type.Optional(EncodedNestedArrayShape),
 		/**
-		 * {@link EncodedInlineArray} union member.
+		 * {@link EncodedInlineArrayShape} union member.
 		 */
-		b: Type.Optional(EncodedInlineArray),
+		b: Type.Optional(EncodedInlineArrayShape),
 		/**
-		 * {@link EncodedTreeShape} union member.
+		 * {@link EncodedNodeShape} union member.
 		 */
-		c: Type.Optional(EncodedTreeShape),
+		c: Type.Optional(EncodedNodeShape),
 		/**
 		 * {@link EncodedAnyShape} union member.
 		 */
@@ -185,9 +191,9 @@ export const EncodedChunkShape = Type.Object(
 
 export type EncodedChunkShape = Static<typeof EncodedChunkShape>;
 
-export type EncodedNestedArray = Static<typeof EncodedNestedArray>;
-export type EncodedInlineArray = Static<typeof EncodedInlineArray>;
-export type EncodedTreeShape = Static<typeof EncodedTreeShape>;
+export type EncodedNestedArrayShape = Static<typeof EncodedNestedArrayShape>;
+export type EncodedInlineArrayShape = Static<typeof EncodedInlineArrayShape>;
+export type EncodedNodeShape = Static<typeof EncodedNodeShape>;
 export type EncodedAnyShape = Static<typeof EncodedAnyShape>;
 
 export const EncodedFieldBatch = EncodedFieldBatchGeneric(version, EncodedChunkShape);