@fluidframework/tree 2.83.0 → 2.90.0

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

@@ -3,17 +3,17 @@
  * Licensed under the MIT License.
  */
 
-export { EncodedFieldBatch, FieldBatchFormatVersion } from "./format.js";
+export type { EncodedFieldBatch } from "./format.js";
+export { FieldBatchFormatVersion } from "./format.js";
 export type { FieldBatch } from "./fieldBatch.js";
 export {
 	type FieldBatchCodec,
-	makeFieldBatchCodec,
+	fieldBatchCodecBuilder,
 	type FieldBatchEncodingContext,
 	type IncrementalEncoderDecoder,
 	type IncrementalEncoder,
 	type IncrementalDecoder,
 	type ChunkReferenceId,
-	getCodecTreeForFieldBatchFormat,
 } from "./codecs.js";
 export {
 	type IncrementalEncodingPolicy,

package/src/feature-libraries/chunked-forest/index.ts

@@ -16,12 +16,11 @@ export {
 } from "./chunkTree.js";
 export { buildChunkedForest } from "./chunkedForest.js";
 export {
-	EncodedFieldBatch,
+	type EncodedFieldBatch,
 	FieldBatchFormatVersion,
-	getCodecTreeForFieldBatchFormat,
 	type FieldBatch,
 	type FieldBatchCodec,
-	makeFieldBatchCodec,
+	fieldBatchCodecBuilder,
 	type FieldBatchEncodingContext,
 	type IncrementalEncoderDecoder,
 	type ChunkReferenceId,

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

@@ -22,8 +22,25 @@ import type { FlexTreeNode } from "./flexTreeTypes.js";
  * See {@link withObservation} and {@link currentObserver}.
  */
 export interface Observer {
+	/**
+	 * Arbitrary content in `node` subtree might be observed.
+	 */
+	observeNodeDeep(node: FlexTreeNode): void;
+	/**
+	 * Which fields exist (as non-empty) on `node` is being observed.
+	 * @remarks
+	 * The set of fields should be considered order independent.
+	 */
 	observeNodeFields(node: FlexTreeNode): void;
+	/**
+	 * The contents of the `key` field of `node` are being observed.
+	 * @remarks
+	 * Any (shallow) change to which children exist in this field, or in what order should invalidate this observation.
+	 */
 	observeNodeField(node: FlexTreeNode, key: FieldKey): void;
+	/**
+	 * The parent of `node` is being observed.
+	 */
 	observeParentOf(node: FlexTreeNode): void;
 }
 

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

@@ -4,89 +4,79 @@
  */
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
-import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
-import {
-	getConfigForMinVersionForCollab,
-	lowestMinVersionForCollab,
-} from "@fluidframework/runtime-utils/internal";
-import { Type } from "@sinclair/typebox";
+import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal";
 
 import {
-	type CodecTree,
+	ClientVersionDispatchingCodecBuilder,
+	type CodecAndSchema,
 	type CodecWriteOptions,
 	FluidClientVersion,
-	type IJsonCodec,
-	makeVersionedValidatedCodec,
 } from "../../codec/index.js";
 import type { FieldKey, ITreeCursorSynchronous } from "../../core/index.js";
-import { brand, type JsonCompatibleReadOnly } from "../../util/index.js";
-import type { FieldBatchCodec, FieldBatchEncodingContext } from "../chunked-forest/index.js";
+import {
+	fieldBatchCodecBuilder,
+	type FieldBatchEncodingContext,
+} from "../chunked-forest/index.js";
 
-import { ForestFormatVersion, validVersions, type Format } from "./formatCommon.js";
-import { FormatV1 } from "./formatV1.js";
-import { FormatV2 } from "./formatV2.js";
+import { ForestFormatVersion, FormatCommon } from "./formatCommon.js";
 
 /**
  * Uses field cursors
  */
 export type FieldSet = ReadonlyMap<FieldKey, ITreeCursorSynchronous>;
-export type ForestCodec = IJsonCodec<
-	FieldSet,
-	Format,
-	JsonCompatibleReadOnly,
-	FieldBatchEncodingContext
->;
+export type ForestCodec = ReturnType<typeof forestCodecBuilder.build>;
 
-/**
- * Convert a MinimumVersionForCollab to a ForestFormatVersion.
- * @param clientVersion - The MinimumVersionForCollab to convert.
- * @returns The ForestFormatVersion that corresponds to the provided MinimumVersionForCollab.
- */
-export function clientVersionToForestFormatVersion(
-	clientVersion: MinimumVersionForCollab,
-): ForestFormatVersion {
-	return brand(
-		getConfigForMinVersionForCollab(clientVersion, {
-			[lowestMinVersionForCollab]: ForestFormatVersion.v1,
-			[FluidClientVersion.v2_74]: ForestFormatVersion.v2,
-		}),
-	);
-}
-
-export function makeForestSummarizerCodec(
+function makeForestSummarizerCodec(
 	options: CodecWriteOptions,
-	fieldBatchCodec: FieldBatchCodec,
-): ForestCodec {
-	const inner = fieldBatchCodec;
-	const writeVersion = clientVersionToForestFormatVersion(options.minVersionForCollab);
-	const formatSchema = Type.Union([FormatV1, FormatV2]);
-	// Both the encode and decode logic here support both v1 and v2, as does `validVersions` and `formatSchema`.
-	// This makes this use of makeVersionedValidatedCodec atypical as it is a single call being used to make a codec that supports all versions,
-	// instead of one call per version, then using another utility to select between them based on version.
-	return makeVersionedValidatedCodec(options, validVersions, formatSchema, {
-		encode: (data: FieldSet, context: FieldBatchEncodingContext): Format => {
+	version: ForestFormatVersion,
+): CodecAndSchema<FieldSet, FieldBatchEncodingContext> {
+	// Performance: Since multiple places (including multiple versions of this codec) use the field batch codec,
+	// we may end up with multiple copies of it, including compiling its format validation multiple times.
+	// This is not ideal, but is not too bad as it is a small fixed number of copies and thus should not be too expensive.
+	// If this becomes problematic a cache could be added for options to codec instances somewhere.
+	const fieldBatchCodec = fieldBatchCodecBuilder.build(options);
+	const formatSchema = FormatCommon;
+	return {
+		encode: (data: FieldSet, context: FieldBatchEncodingContext): FormatCommon => {
 			const keys: FieldKey[] = [];
 			const fields: ITreeCursorSynchronous[] = [];
 			for (const [key, value] of data) {
 				keys.push(key);
 				fields.push(value);
 			}
-			return { keys, fields: inner.encode(fields, context), version: writeVersion };
+			return {
+				keys,
+				fields: fieldBatchCodec.encode(fields, context),
+				version,
+			};
 		},
-		decode: (data: Format, context: FieldBatchEncodingContext): FieldSet => {
+		decode: (data: FormatCommon, context: FieldBatchEncodingContext): FieldSet => {
 			const out: Map<FieldKey, ITreeCursorSynchronous> = new Map();
-			const fields = inner.decode(data.fields, context);
+			const fields = fieldBatchCodec.decode(data.fields, context);
 			assert(data.keys.length === fields.length, 0x891 /* mismatched lengths */);
 			for (const [index, field] of fields.entries()) {
 				out.set(data.keys[index] ?? oob(), field);
 			}
 			return out;
 		},
-	});
+		schema: formatSchema,
+	};
 }
 
-export function getCodecTreeForForestFormat(
-	clientVersion: MinimumVersionForCollab,
-): CodecTree {
-	return { name: "Forest", version: clientVersionToForestFormatVersion(clientVersion) };
-}
+/**
+ * {@link ClientVersionDispatchingCodecBuilder} for forest summarizer codecs.
+ */
+export const forestCodecBuilder = ClientVersionDispatchingCodecBuilder.build("Forest", [
+	{
+		minVersionForCollab: lowestMinVersionForCollab,
+		formatVersion: ForestFormatVersion.v1,
+		codec: (options: CodecWriteOptions) =>
+			makeForestSummarizerCodec(options, ForestFormatVersion.v1),
+	},
+	{
+		minVersionForCollab: FluidClientVersion.v2_74,
+		formatVersion: ForestFormatVersion.v2,
+		codec: (options: CodecWriteOptions) =>
+			makeForestSummarizerCodec(options, ForestFormatVersion.v2),
+	},
+]);

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

@@ -41,18 +41,12 @@ import {
 import { chunkFieldSingle, defaultChunkPolicy } from "../chunked-forest/chunkTree.js";
 import {
 	defaultIncrementalEncodingPolicy,
-	type FieldBatchCodec,
 	type FieldBatchEncodingContext,
 	type IncrementalEncodingPolicy,
 } from "../chunked-forest/index.js";
 import { TreeCompressionStrategy } from "../treeCompressionUtils.js";
 
-import {
-	clientVersionToForestFormatVersion,
-	type ForestCodec,
-	makeForestSummarizerCodec,
-} from "./codec.js";
-import { ForestFormatVersion } from "./formatCommon.js";
+import { forestCodecBuilder, type ForestCodec } from "./codec.js";
 import {
 	ForestIncrementalSummaryBehavior,
 	ForestIncrementalSummaryBuilder,
@@ -85,7 +79,6 @@ export class ForestSummarizer
 	public constructor(
 		private readonly forest: IEditableForest,
 		private readonly revisionTagCodec: RevisionTagCodec,
-		fieldBatchCodec: FieldBatchCodec,
 		private readonly encoderContext: FieldBatchEncodingContext,
 		options: CodecWriteOptions,
 		private readonly idCompressor: IIdCompressor,
@@ -99,11 +92,8 @@ export class ForestSummarizer
 			true /* supportPreVersioningFormat */,
 		);
 
-		this.codec = makeForestSummarizerCodec(options, fieldBatchCodec);
+		this.codec = forestCodecBuilder.build(options);
 
-		const forestFormatWriteVersion = clientVersionToForestFormatVersion(
-			options.minVersionForCollab,
-		);
 		const summaryFormatWriteVersion = minVersionToForestSummaryFormatVersion(
 			options.minVersionForCollab,
 		);
@@ -111,9 +101,10 @@ export class ForestSummarizer
 			summaryFormatWriteVersion,
 		);
 
-		// Incremental summary is supported from ForestFormatVersion.v2 and ForestSummaryFormatVersion.v3 onwards.
+		// Incremental summary is supported in ForestSummaryFormatVersion.v3 onwards.
+		// Note that even in versions that support it, it is possible that the
+		// FieldBatchCodec will not use incremental encoding (for example if using its v1 formats which does not support it).
 		const enableIncrementalSummary =
-			forestFormatWriteVersion >= ForestFormatVersion.v2 &&
 			summaryFormatWriteVersion >= ForestSummaryFormatVersion.v3 &&
 			encoderContext.encodeType === TreeCompressionStrategy.CompressedIncremental;
 		this.incrementalSummaryBuilder = new ForestIncrementalSummaryBuilder(

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

@@ -5,6 +5,7 @@
 
 import { type Static, Type } from "@sinclair/typebox";
 
+import { versionField } from "../../codec/index.js";
 import { schemaFormatV1 } from "../../core/index.js";
 import { strictEnum, type Values, JsonCompatibleReadOnlySchema } from "../../util/index.js";
 
@@ -13,26 +14,20 @@ import { strictEnum, type Values, JsonCompatibleReadOnlySchema } from "../../uti
  */
 export const ForestFormatVersion = strictEnum("ForestFormatVersion", {
 	v1: 1,
-	/** This format supports incremental encoding */
+	/** This format is the same as v1, and was added at the same time as incremental encoding for reasons that no longer apply */
 	v2: 2,
 });
 export type ForestFormatVersion = Values<typeof ForestFormatVersion>;
 
-export const validVersions = new Set([...Object.values(ForestFormatVersion)]);
-
-export const FormatCommon = <const TVersion extends ForestFormatVersion>(
-	version: TVersion,
-	// Return type is intentionally derived.
-	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-) =>
-	Type.Object(
-		{
-			version: Type.Literal(version),
-			keys: Type.Array(schemaFormatV1.FieldKeySchema),
-			fields: JsonCompatibleReadOnlySchema, // Uses field batch codec
-		},
-		{ additionalProperties: false },
-	);
-export type Format<TVersion extends ForestFormatVersion = ForestFormatVersion> = Static<
-	ReturnType<typeof FormatCommon<TVersion>>
->;
+/**
+ * Format used by {@link ForestFormatVersion.v1} and {@link ForestFormatVersion.v2}.
+ */
+export const FormatCommon = Type.Object(
+	{
+		...versionField,
+		keys: Type.Array(schemaFormatV1.FieldKeySchema),
+		fields: JsonCompatibleReadOnlySchema, // Uses field batch codec
+	},
+	{ additionalProperties: false },
+);
+export type FormatCommon = Static<typeof FormatCommon>;

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

@@ -31,18 +31,6 @@ import type {
 
 import { summaryContentBlobKey } from "./summaryFormatV3.js";
 
-/**
- * State that tells whether a summary is currently being tracked.
- */
-export const ForestSummaryTrackingState = {
-	/** A summary is currently being tracked. */
-	Tracking: "Tracking",
-	/** A summary is ready to be tracked. */
-	ReadyToTrack: "ReadyToTrack",
-} as const;
-export type ForestSummaryTrackingState =
-	(typeof ForestSummaryTrackingState)[keyof typeof ForestSummaryTrackingState];
-
 /**
  * The properties of a chunk tracked during the loading process.
  * These are used to identify a chunk when it is decoded and recreate the tracking state
@@ -144,44 +132,6 @@ export enum ForestIncrementalSummaryBehavior {
 	SingleBlob,
 }
 
-/**
- * Validates that a summary is currently being tracked and that the tracked summary properties are defined.
- * @param forestSummaryState - The current state of the forest summary tracking.
- * @param trackedSummaryProperties - The properties of the tracked summary, which must be available.
- */
-function validateTrackingSummary(
-	forestSummaryState: ForestSummaryTrackingState,
-	trackedSummaryProperties: TrackedSummaryProperties | undefined,
-): asserts trackedSummaryProperties is TrackedSummaryProperties {
-	assert(
-		forestSummaryState === ForestSummaryTrackingState.Tracking,
-		0xc22 /* Not tracking a summary */,
-	);
-	assert(
-		trackedSummaryProperties !== undefined,
-		0xc23 /* Tracked summary properties must be available when tracking a summary */,
-	);
-}
-
-/**
- * Validates that a summary is ready to be tracked and that the tracked summary properties are undefined.
- * @param forestSummaryState - The current state of the forest summary tracking.
- * @param trackedSummaryProperties - The properties of the tracked summary, which must be undefined.
- */
-function validateReadyToTrackSummary(
-	forestSummaryState: ForestSummaryTrackingState,
-	trackedSummaryProperties: TrackedSummaryProperties | undefined,
-): asserts trackedSummaryProperties is undefined {
-	assert(
-		forestSummaryState === ForestSummaryTrackingState.ReadyToTrack,
-		0xc24 /* Already tracking a summary */,
-	);
-	assert(
-		trackedSummaryProperties === undefined,
-		0xc25 /* Tracked summary properties must not be available when ready to track */,
-	);
-}
-
 /* eslint-disable jsdoc/check-indentation */
 /**
  * Tracks and builds the incremental summary tree for a forest where chunks that support incremental encoding are
@@ -235,19 +185,29 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	> = new Map();
 
 	/**
-	 * The state indicating whether a summary is currently being tracked or not.
+	 * True when encoding a summary, false otherwise.
+	 * @remarks
+	 * Exposed for testing purposes.
 	 */
-	public forestSummaryState: ForestSummaryTrackingState =
-		ForestSummaryTrackingState.ReadyToTrack;
-
+	public get isSummarizing(): boolean {
+		return this.trackedSummaryProperties !== undefined;
+	}
 	/**
 	 * The sequence number of the latest summary that was successful.
 	 */
 	private latestSummarySequenceNumber: number = -1;
 
 	/**
-	 * The current state of the summary being tracked.
-	 * This is undefined if no summary is currently being tracked.
+	 * The current state of the summary being "tracked".
+	 * @remarks
+	 * A summary being "tracked" means that a summary is being encoded.
+	 * This is undefined if no summary is currently being encoded.
+	 *
+	 * @privateRemarks
+	 * This has nothing to do which how content from a summary being loaded is tracked (thats written all in chunkTrackingPropertiesMap).
+	 * "Tracked" should probably be renamed to "encoded" or "summarizing" or something like that to avoid confusion.
+	 * Perhaps a better way to clarify this would be to not store this property on this object at all, and have it
+	 * only exist within the scope of the summary encoding (use an encoding specific object to accumulate any stat necessary during encode).
 	 */
 	private trackedSummaryProperties: TrackedSummaryProperties | undefined;
 
@@ -321,6 +281,15 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		await downloadChunkContentsInTree(forestTree, "");
 	}
 
+	/**
+	 * Asserts that a summary is currently being tracked and that the tracked summary properties are defined.
+	 * @returns The properties of the tracked summary.
+	 */
+	private requireTrackingSummary(): TrackedSummaryProperties {
+		assert(this.trackedSummaryProperties !== undefined, 0xc22 /* Not tracking a summary */);
+		return this.trackedSummaryProperties;
+	}
+
 	/**
 	 * Must be called when starting a new forest summary to track it.
 	 * @param fullTree - Whether the summary is a full tree summary. If true, the summary will not contain
@@ -336,6 +305,11 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		stringify: SummaryElementStringifier;
 		builder: SummaryTreeBuilder;
 	}): ForestIncrementalSummaryBehavior {
+		assert(
+			this.trackedSummaryProperties === undefined,
+			0xc24 /* Already tracking a summary */,
+		);
+
 		const { fullTree, incrementalSummaryContext, stringify, builder } = args;
 		// If there is no incremental summary context, do not summarize incrementally. This happens in two scenarios:
 		// 1. When summarizing a detached container, i.e., the first ever summary.
@@ -344,9 +318,6 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			return ForestIncrementalSummaryBehavior.SingleBlob;
 		}
 
-		validateReadyToTrackSummary(this.forestSummaryState, this.trackedSummaryProperties);
-
-		this.forestSummaryState = ForestSummaryTrackingState.Tracking;
 		this.latestSummarySequenceNumber = incrementalSummaryContext.latestSummarySequenceNumber;
 		this.trackedSummaryProperties = {
 			summarySequenceNumber: incrementalSummaryContext.summarySequenceNumber,
@@ -368,7 +339,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		chunkEncoder: (chunk: TreeChunk) => EncodedFieldBatch,
 	): ChunkReferenceId[] {
 		// Validate that a summary is currently being tracked and that the tracked summary properties are defined.
-		validateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);
+		const trackedSummaryProperties = this.requireTrackingSummary();
 
 		const chunkReferenceIds: ChunkReferenceId[] = [];
 		const chunks = this.getChunkAtCursor(cursor);
@@ -383,12 +354,12 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				this.latestSummarySequenceNumber,
 				chunk,
 			);
-			if (previousChunkProperties !== undefined && !this.trackedSummaryProperties.fullTree) {
+			if (previousChunkProperties !== undefined && !trackedSummaryProperties.fullTree) {
 				chunkProperties = previousChunkProperties;
-				this.trackedSummaryProperties.parentSummaryBuilder.addHandle(
+				trackedSummaryProperties.parentSummaryBuilder.addHandle(
 					`${chunkProperties.referenceId}`,
 					SummaryType.Tree,
-					`${this.trackedSummaryProperties.latestSummaryBasePath}/${chunkProperties.summaryPath}`,
+					`${trackedSummaryProperties.latestSummaryBasePath}/${chunkProperties.summaryPath}`,
 				);
 			} else {
 				// Generate a new reference ID for the chunk.
@@ -398,23 +369,23 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				// for the chunk in its summary properties.
 				// This is done before encoding the chunk so that the summary path is updated correctly when encoding
 				// any incremental chunks that are under this chunk.
-				this.trackedSummaryProperties.chunkSummaryPath.push(newReferenceId);
+				trackedSummaryProperties.chunkSummaryPath.push(newReferenceId);
 
 				chunkProperties = {
 					referenceId: newReferenceId,
-					summaryPath: this.trackedSummaryProperties.chunkSummaryPath.join("/"),
+					summaryPath: trackedSummaryProperties.chunkSummaryPath.join("/"),
 				};
 
-				const parentSummaryBuilder = this.trackedSummaryProperties.parentSummaryBuilder;
+				const parentSummaryBuilder = trackedSummaryProperties.parentSummaryBuilder;
 				// Create a new summary builder for this chunk to build its summary tree which will be stored in the
 				// parent's summary tree under its reference ID.
 				// Before encoding the chunk, set the parent summary builder to this chunk's summary builder so that
 				// any incremental chunks in the subtree of this chunk will use that as their parent summary builder.
 				const chunkSummaryBuilder = new SummaryTreeBuilder();
-				this.trackedSummaryProperties.parentSummaryBuilder = chunkSummaryBuilder;
+				trackedSummaryProperties.parentSummaryBuilder = chunkSummaryBuilder;
 				chunkSummaryBuilder.addBlob(
 					summaryContentBlobKey,
-					this.trackedSummaryProperties.stringify(chunkEncoder(chunk)),
+					trackedSummaryProperties.stringify(chunkEncoder(chunk)),
 				);
 
 				// Add this chunk's summary tree to the parent's summary tree. The summary tree contains its encoded
@@ -425,13 +396,13 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				);
 
 				// Restore the parent summary builder and chunk summary path.
-				this.trackedSummaryProperties.parentSummaryBuilder = parentSummaryBuilder;
-				this.trackedSummaryProperties.chunkSummaryPath.pop();
+				trackedSummaryProperties.parentSummaryBuilder = parentSummaryBuilder;
+				trackedSummaryProperties.chunkSummaryPath.pop();
 			}
 
 			setInNestedMap(
 				this.chunkTrackingPropertiesMap,
-				this.trackedSummaryProperties.summarySequenceNumber,
+				trackedSummaryProperties.summarySequenceNumber,
 				chunk,
 				chunkProperties,
 			);
@@ -469,7 +440,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			return;
 		}
 
-		validateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);
+		const trackedSummaryProperties = this.requireTrackingSummary();
 
 		builder.addBlob(forestSummaryRootContentKey, forestSummaryRootContent);
 
@@ -481,7 +452,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			this.latestSummarySequenceNumber,
 		);
 		const currentSummaryTrackingMap = this.chunkTrackingPropertiesMap.get(
-			this.trackedSummaryProperties.summarySequenceNumber,
+			trackedSummaryProperties.summarySequenceNumber,
 		);
 		if (latestSummaryTrackingMap !== undefined && currentSummaryTrackingMap !== undefined) {
 			for (const [chunk, chunkProperties] of latestSummaryTrackingMap.entries()) {
@@ -499,7 +470,6 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			}
 		}
 
-		this.forestSummaryState = ForestSummaryTrackingState.ReadyToTrack;
 		this.trackedSummaryProperties = undefined;
 	}
 

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

@@ -4,5 +4,5 @@
  */
 
 export { ForestSummarizer } from "./forestSummarizer.js";
-export { getCodecTreeForForestFormat } from "./codec.js";
+export { forestCodecBuilder } from "./codec.js";
 export { ForestFormatVersion } from "./formatCommon.js";

package/src/feature-libraries/index.ts

@@ -11,7 +11,7 @@ export { allowsValue, assertAllowedValue, isTreeValue } from "./valueUtilities.j
 
 export {
 	ForestSummarizer,
-	getCodecTreeForForestFormat,
+	forestCodecBuilder,
 	ForestFormatVersion,
 } from "./forest-summary/index.js";
 export {
@@ -104,9 +104,8 @@ export {
 	type FieldBatch,
 	type FieldBatchCodec,
 	FieldBatchFormatVersion,
-	getCodecTreeForFieldBatchFormat,
 	makeTreeChunker,
-	makeFieldBatchCodec,
+	fieldBatchCodecBuilder,
 	type FieldBatchEncodingContext,
 	emptyChunk,
 	combineChunks,
@@ -204,7 +203,6 @@ export {
 	AnchorTreeIndex,
 	hasElement,
 	type TreeIndex,
-	type TreeIndexKey,
 	type TreeIndexNodes,
 } from "./indexing/index.js";
 

package/src/feature-libraries/indexing/anchorTreeIndex.ts

@@ -27,7 +27,7 @@ import {
 import { disposeSymbol, getOrCreate } from "../../util/index.js";
 import { TreeStatus } from "../flex-tree/index.js";
 
-import type { TreeIndex, TreeIndexKey, TreeIndexNodes } from "./types.js";
+import type { TreeIndex, TreeIndexNodes } from "./types.js";
 
 /**
  * A function that gets the value to index a node on, must be pure and functional.
@@ -40,7 +40,7 @@ import type { TreeIndex, TreeIndexKey, TreeIndexNodes } from "./types.js";
  * but returns the cursor to the state it was in before being passed to the function. It should also not be disposed by this function
  * and must be disposed elsewhere.
  */
-export type KeyFinder<TKey extends TreeIndexKey> = (tree: ITreeSubscriptionCursor) => TKey;
+export type KeyFinder<TKey> = (tree: ITreeSubscriptionCursor) => TKey;
 
 /**
  * An index from some arbitrary keys to anchor nodes. Keys can be anything that is a {@link TreeValue}.
@@ -50,9 +50,7 @@ export type KeyFinder<TKey extends TreeIndexKey> = (tree: ITreeSubscriptionCurso
  * Detached nodes are stored in the index but filtered out when any public facing apis are called. This means that
  * calling {@link keys} will not include any keys that are stored in the index but only map to detached nodes.
  */
-export class AnchorTreeIndex<TKey extends TreeIndexKey, TValue>
-	implements TreeIndex<TKey, TValue>
-{
+export class AnchorTreeIndex<TKey, TValue> implements TreeIndex<TKey, TValue> {
 	public disposed = false;
 	/**
 	 * Caches {@link KeyFinder}s for each schema definition. If a schema maps to null, it does not

package/src/feature-libraries/indexing/index.ts

@@ -8,4 +8,4 @@ export {
 	type KeyFinder,
 	hasElement,
 } from "./anchorTreeIndex.js";
-export type { TreeIndex, TreeIndexKey, TreeIndexNodes } from "./types.js";
+export type { TreeIndex, TreeIndexNodes } from "./types.js";

package/src/feature-libraries/indexing/types.ts

@@ -3,8 +3,6 @@
  * Licensed under the MIT License.
  */
 
-import type { IFluidHandle } from "@fluidframework/core-interfaces";
-
 /**
  * an array of nodes that is guaranteed to have at least one element
  *
@@ -13,25 +11,25 @@ import type { IFluidHandle } from "@fluidframework/core-interfaces";
 export type TreeIndexNodes<TNode> = readonly [first: TNode, ...rest: TNode[]];
 
 /**
- * Value that may be used as keys in a {@link TreeIndex}.
- *
+ * An index allows lookup content from a tree using keys.
+ * @remarks
+ * The index will be kept up to date with the {@link TreeBranchAlpha} it is associated with.
+ * Keeping an index up to date incurs overhead.
+ * Therefore, indexes should only be created when needed and disposed when no longer needed.
  * @privateRemarks
- * no-new-null is disabled for this type so that it supports the TreeValue type.
- *
- * @alpha
- */
-// eslint-disable-next-line @rushstack/no-new-null
-export type TreeIndexKey = number | string | boolean | IFluidHandle | null;
-
-/**
- * A index where values are keyed on {@link TreeIndexKey}s.
- *
+ * We have various disposable interfaces. Perhaps this should extend one.
+ * Currently all of these indexes are generated on load and exist only in memory (do not persist anything to the document).
+ * In the future, we may want to support indexes which persist some content, allowing them to be kept up to date when when only loading part of a tree.
+ * Since currently partially loading a tree is not supported, there is no need for this.
+ * At some point the low level shared tree index type for persisted indexes could be leveraged to provide user facing extensible sets of persisted indexes.
+ * @sealed
  * @alpha
  */
-export interface TreeIndex<TKey extends TreeIndexKey, TValue>
-	extends ReadonlyMap<TKey, TValue> {
+export interface TreeIndex<TKey, TValue> extends ReadonlyMap<TKey, TValue> {
 	/**
-	 * Disposes the index such that it can no longer be used and receives no updates from the forest
+	 * Disposes the index such that it can no longer be used and receives no updates for changes in the tree.
+	 * @remarks
+	 * An index may not be used after it is disposed.
 	 */
 	dispose(): void;
 }