@fluidframework/tree 2.74.0 → 2.81.0-374083

package/src/core/rebase/types.ts

@@ -20,6 +20,7 @@ import {
 	brandedNumberType,
 	brandedStringType,
 } from "../../util/index.js";
+import type { RevertibleAlpha } from "../revertible.js";
 
 /**
  * The identifier for a particular session/user/client that can generate `GraphCommit`s
@@ -121,32 +122,23 @@ export function taggedOptAtomId(
 	return taggedAtomId(id, revision);
 }
 
-export function offsetChangeAtomId(id: ChangeAtomId, offset: number): ChangeAtomId {
+export function offsetChangeAtomId<T extends ChangeAtomId = ChangeAtomId>(
+	id: T,
+	offset: number,
+): T {
 	return { ...id, localId: brand(id.localId + offset) };
 }
 
-export function replaceAtomRevisions(
-	id: ChangeAtomId,
-	oldRevisions: Set<RevisionTag | undefined>,
-	newRevision: RevisionTag | undefined,
-): ChangeAtomId {
-	return oldRevisions.has(id.revision) ? atomWithRevision(id, newRevision) : id;
-}
-
-function atomWithRevision(id: ChangeAtomId, revision: RevisionTag | undefined): ChangeAtomId {
-	const updated = { ...id, revision };
-	if (revision === undefined) {
-		delete updated.revision;
-	}
-
-	return updated;
-}
-
 /**
  * A node in a graph of commits. A commit's parent is the commit on which it was based.
  */
 export interface GraphCommit<TChange> {
-	/** The tag for this commit. If this commit is rebased, the corresponding rebased commit will retain this tag. */
+	/**
+	 * The tag for this commit.
+	 * @remarks
+	 * If this commit is rebased, the corresponding rebased commit will retain this tag.
+	 * With the exception of transaction commits (which all share the same tag), this tag is unique within a given branch history.
+	 */
 	readonly revision: RevisionTag;
 	/** The change that will result from applying this commit */
 	readonly change: TChange;
@@ -185,28 +177,64 @@ export interface CommitMetadata {
 }
 
 /**
- * Information about a commit that has been applied.
- *
+ * Information about a change that has been applied by the local client.
+ * @sealed @alpha
+ */
+export interface LocalChangeMetadata extends CommitMetadata {
+	/**
+	 * Whether the change was made on the local machine/client or received from a remote client.
+	 */
+	readonly isLocal: true;
+	/**
+	 * Returns a serializable object that encodes the change.
+	 * @remarks This is only available for local changes.
+	 * This change object can be {@link TreeBranchAlpha.applyChange | applied to another branch} in the same state as the one which generated it.
+	 * The change object must be applied to a SharedTree with the same IdCompressor session ID as it was created from.
+	 * @privateRemarks
+	 * This is a `SerializedChange` from treeCheckout.ts.
+	 */
+	getChange(): JsonCompatibleReadOnly;
+	/**
+	 * Returns an object (a {@link RevertibleAlpha | "revertible"}) that can be used to revert the change that produced this event.
+	 * @remarks This is only available for local changes.
+	 * If the change is not revertible (for example, it was a change to the application schema), then this will return `undefined`.
+	 * Revertibles should be disposed when they are no longer needed.
+	 * @param onDisposed - A callback that will be invoked when the `Revertible` is disposed.
+	 * This happens when the `Revertible` is disposed manually or when the `TreeView` that the `Revertible` belongs to is disposed - whichever happens first.
+	 * This is typically used to clean up any resources associated with the `Revertible` in the host application.
+	 * @throws Throws an error if called outside the scope of the `changed` event that provided it.
+	 */
+	getRevertible(
+		onDisposed?: (revertible: RevertibleAlpha) => void,
+	): RevertibleAlpha | undefined;
+}
+
+/**
+ * Information about a change that has been applied by a remote client.
+ * @sealed @alpha
+ */
+export interface RemoteChangeMetadata extends CommitMetadata {
+	/**
+	 * Whether the change was made on the local machine/client or received from a remote client.
+	 */
+	readonly isLocal: false;
+	/**
+	 * Returns a serializable object that encodes the change.
+	 * @remarks This is only available for {@link LocalChangeMetadata | local changes}.
+	 */
+	readonly getChange?: undefined;
+	/**
+	 * Returns an object (a {@link RevertibleAlpha | "revertible"}) that can be used to revert the change that produced this event.
+	 * @remarks This is only available for {@link LocalChangeMetadata | local changes}.
+	 */
+	readonly getRevertible?: undefined;
+}
+
+/**
+ * Information about a {@link LocalChangeMetadata | local} or {@link RemoteChangeMetadata | remote} change that has been applied.
  * @sealed @alpha
  */
-export type ChangeMetadata = CommitMetadata &
-	(
-		| {
-				readonly isLocal: true;
-				/**
-				 * A serializable object that encodes the change.
-				 * @remarks This change object can be {@link TreeBranchAlpha.applyChange | applied to another branch} in the same state as the one which generated it.
-				 * The change object must be applied to a SharedTree with the same IdCompressor session ID as it was created from.
-				 * @privateRemarks
-				 * This is a `SerializedChange` from treeCheckout.ts.
-				 */
-				getChange(): JsonCompatibleReadOnly;
-		  }
-		| {
-				readonly isLocal: false;
-				readonly getChange?: undefined;
-		  }
-	);
+export type ChangeMetadata = LocalChangeMetadata | RemoteChangeMetadata;
 
 /**
  * Creates a new graph commit object. This is useful for creating copies of commits with different parentage.
@@ -234,6 +262,10 @@ export function newChangeAtomIdRangeMap<V>(): ChangeAtomIdRangeMap<V> {
 	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds);
 }
 
+export function newChangeAtomIdTransform(): ChangeAtomIdRangeMap<ChangeAtomId> {
+	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetChangeAtomId);
+}
+
 export function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number {
 	const cmp = compareRevisions(a.revision, b.revision);
 	if (cmp !== 0) {

package/src/core/rebase/utils.ts

@@ -200,7 +200,7 @@ export function rebaseBranch<TChange>(
 	const sourceBranchLength = sourcePath.length;
 
 	// Find where `targetCommit` is in the target branch
-	const targetCommitIndex = targetPath.findIndex((r) => r === targetCommit);
+	const targetCommitIndex = targetPath.indexOf(targetCommit);
 	if (targetCommitIndex === -1) {
 		// If the targetCommit is not in the target path, then it is either disjoint from `target` or it is behind/at
 		// the commit where source and target diverge (ancestor), in which case there is nothing more to rebase
@@ -292,7 +292,7 @@ export function rebaseBranch<TChange>(
 	const revInfos = getRevInfoFromTaggedChanges([...targetRebasePath, ...sourcePath]);
 	// Note that the `revisionMetadata` gets updated as `revInfos` gets updated.
 	const revisionMetadata = revisionMetadataSourceFromInfo(revInfos);
-	let editsToCompose: TaggedChange<TChange>[] = targetRebasePath.slice();
+	let editsToCompose: TaggedChange<TChange>[] = [...targetRebasePath];
 	for (const c of sourcePath) {
 		const rollback = rollbackFromCommit(changeRebaser, c, mintRevisionTag, true /* cache */);
 		if (sourceSet.has(c.revision)) {
@@ -327,7 +327,9 @@ export function rebaseBranch<TChange>(
 			},
 		},
 		"sourceChange",
-		() => changeRebaser.compose(editsToCompose),
+		() => {
+			return changeRebaser.compose(editsToCompose);
+		},
 	);
 }
 
@@ -375,23 +377,45 @@ export function rebaseChange<TChange>(
 export function revisionMetadataSourceFromInfo(
 	revInfos: readonly RevisionInfo[],
 ): RevisionMetadataSource {
-	const getIndex = (revision: RevisionTag): number | undefined => {
-		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
-		return index >= 0 ? index : undefined;
+	const compareRevisions = (revision1: RevisionTag, revision2: RevisionTag): number => {
+		const index1 = getIndex(revision1);
+		const index2 = getIndex(revision2);
+
+		if (index1 !== undefined) {
+			return index2 === undefined ? -1 : index2 - index1;
+		}
+
+		return index2 === undefined ? 0 : 1;
 	};
+
 	const tryGetInfo = (revision: RevisionTag | undefined): RevisionInfo | undefined => {
 		if (revision === undefined) {
 			return undefined;
 		}
-		const index = getIndex(revision);
-		return index === undefined ? undefined : revInfos[index];
+		return revInfos.find((info) => info.revision === revision);
 	};
 
 	const hasRollback = (revision: RevisionTag): boolean => {
-		return revInfos.find((info) => info.rollbackOf === revision) !== undefined;
+		return revInfos.some((info) => info.rollbackOf === revision);
+	};
+
+	const getIndex = (revision: RevisionTag): number | undefined => {
+		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
+		if (index >= 0) {
+			return index;
+		}
+
+		const rollbackIndex = revInfos.findIndex((revInfo) => revInfo.rollbackOf === revision);
+		if (rollbackIndex >= 0) {
+			// This change is the forward revision of a rollback included in revInfos, so it comes after
+			// all revisions in revInfos. Earlier rollbacks have later forward revisions.
+			return 2 * revInfos.length - rollbackIndex;
+		}
+
+		return undefined;
 	};
 
-	return { getIndex, tryGetInfo, hasRollback };
+	return { compareRevisions, tryGetInfo, hasRollback };
 }
 
 export function rebaseChangeOverChanges<TChange>(
@@ -403,10 +427,14 @@ export function rebaseChangeOverChanges<TChange>(
 		getRevInfoFromTaggedChanges([...changesToRebaseOver, changeToRebase]),
 	);
 
-	return changesToRebaseOver.reduce(
-		(a, b) => mapTaggedChange(changeToRebase, changeRebaser.rebase(a, b, revisionMetadata)),
-		changeToRebase,
-	).change;
+	let result = changeToRebase;
+	for (const b of changesToRebaseOver) {
+		result = mapTaggedChange(
+			changeToRebase,
+			changeRebaser.rebase(result, b, revisionMetadata),
+		);
+	}
+	return result.change;
 }
 
 // TODO: Deduplicate

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

@@ -394,9 +394,9 @@ export function encodeFieldSchemaV2(schema: TreeFieldStoredSchema): FieldSchemaF
 	const fieldSchema: FieldSchemaFormatV1 = encodeFieldSchemaV1(schema);
 
 	// Omit metadata from the output if it is undefined
-	return schema.persistedMetadata !== undefined
-		? { ...fieldSchema, metadata: schema.persistedMetadata }
-		: { ...fieldSchema };
+	return schema.persistedMetadata === undefined
+		? { ...fieldSchema }
+		: { ...fieldSchema, metadata: schema.persistedMetadata };
 }
 
 export function decodeFieldSchema(schema: FieldSchemaFormatV2): TreeFieldStoredSchema {

package/src/core/tree/anchorSet.ts

@@ -424,10 +424,8 @@ export class AnchorSet implements AnchorLocator {
 	 * Does not add a ref!
 	 */
 	public find(path: UpPath): PathNode | undefined {
-		if (path instanceof PathNode) {
-			if (path.anchorSet === this) {
-				return path;
-			}
+		if (path instanceof PathNode && path.anchorSet === this) {
+			return path;
 		}
 		const parent = path.parent ?? this.root;
 		const parentPath = this.find(parent);
@@ -1185,6 +1183,7 @@ class PathNode extends ReferenceCountedBase implements AnchorNode {
 		assert(this.status !== Status.Disposed, 0x41d /* PathNode must not be disposed */);
 		if (this.isUnreferenced() && this.children.size === 0 && !this.events.hasListeners()) {
 			if (this.status === Status.Alive) {
+				// eslint-disable-next-line unicorn/prefer-dom-node-remove -- Custom tree structure, not DOM
 				this.parentPath?.removeChild(this);
 			}
 			this.status = Status.Disposed;
@@ -1211,6 +1210,7 @@ class PathNode extends ReferenceCountedBase implements AnchorNode {
 function binaryFind(sorted: readonly PathNode[], index: number): PathNode | undefined {
 	// Try guessing the list is not sparse as a starter:
 	const guess = sorted[index];
+	// eslint-disable-next-line @typescript-eslint/prefer-optional-chain -- using ?. could change behavior
 	if (guess !== undefined && guess.parentIndex === index) {
 		return guess;
 	}

package/src/core/tree/detachedFieldIndex.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
@@ -35,7 +35,7 @@ import type {
 	Major,
 	Minor,
 } from "./detachedFieldIndexTypes.js";
-import { makeDetachedFieldIndexCodec } from "./detachedFieldIndexCodecs.js";
+import { detachedFieldIndexCodecBuilder } from "./detachedFieldIndexCodecs.js";
 
 /**
  * Readonly interface for {@link DetachedFieldIndex}.
@@ -52,6 +52,12 @@ export interface ReadOnlyDetachedFieldIndex {
 	 */
 	toFieldKey(id: ForestRootId): FieldKey;
 
+	/**
+	 * Returns a node ID for the node in the given field.
+	 * @param field - The field key where the detached node resides.
+	 */
+	fromFieldKey(field: FieldKey): Delta.DetachedNodeId;
+
 	/**
 	 * Returns the `ForestRootId` associated with the given id.
 	 * Returns undefined if no such id is known to the index.
@@ -120,7 +126,11 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 			jsonValidator: FormatValidatorNoOp,
 			minVersionForCollab: FluidClientVersion.v2_0,
 		};
-		this.codec = makeDetachedFieldIndexCodec(revisionTagCodec, this.options, idCompressor);
+		this.codec = detachedFieldIndexCodecBuilder.build({
+			...this.options,
+			revisionTagCodec,
+			idCompressor,
+		});
 	}
 
 	public clone(): DetachedFieldIndex {
@@ -165,17 +175,17 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		id: Delta.DetachedNodeId;
 	}> {
 		for (const [major, innerMap] of this.detachedNodeToField) {
-			if (major !== undefined) {
+			if (major === undefined) {
 				for (const [minor, { root, latestRelevantRevision }] of innerMap) {
-					yield latestRelevantRevision !== undefined
-						? { id: { major, minor }, root, latestRelevantRevision }
-						: { id: { major, minor }, root };
+					yield latestRelevantRevision === undefined
+						? { id: { minor }, root }
+						: { id: { minor }, root, latestRelevantRevision };
 				}
 			} else {
 				for (const [minor, { root, latestRelevantRevision }] of innerMap) {
-					yield latestRelevantRevision !== undefined
-						? { id: { minor }, root, latestRelevantRevision }
-						: { id: { minor }, root };
+					yield latestRelevantRevision === undefined
+						? { id: { major, minor }, root }
+						: { id: { major, minor }, root, latestRelevantRevision };
 				}
 			}
 		}
@@ -189,73 +199,18 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		this.latestRelevantRevisionToFields.clear();
 	}
 
-	public updateMajor(current: Major, updated: Major): void {
-		// Update latestRelevantRevision information corresponding to `current`
-		{
-			const inner = this.latestRelevantRevisionToFields.get(current);
-			if (inner !== undefined) {
-				for (const nodeId of inner.values()) {
-					const entry = tryGetFromNestedMap(
-						this.detachedNodeToField,
-						nodeId.major,
-						nodeId.minor,
-					);
-					assert(
-						entry !== undefined,
-						0x9b8 /* Inconsistent data: missing detached node entry */,
-					);
-					setInNestedMap(this.detachedNodeToField, nodeId.major, nodeId.minor, {
-						...entry,
-						latestRelevantRevision: updated,
-					});
-				}
-				this.latestRelevantRevisionToFields.delete(current);
-
-				const updatedInner = this.latestRelevantRevisionToFields.get(updated);
-				if (updatedInner !== undefined) {
-					for (const [root, nodeId] of inner) {
-						updatedInner.set(root, nodeId);
-					}
-				} else {
-					this.latestRelevantRevisionToFields.set(updated, inner);
-				}
-			}
-		}
-
-		// Update the major keys corresponding to `current`
-		{
-			const innerCurrent = this.detachedNodeToField.get(current);
-			if (innerCurrent !== undefined) {
-				this.detachedNodeToField.delete(current);
-				const innerUpdated = this.detachedNodeToField.get(updated);
-				if (innerUpdated === undefined) {
-					this.detachedNodeToField.set(updated, innerCurrent);
-				} else {
-					for (const [minor, entry] of innerCurrent) {
-						assert(
-							innerUpdated.get(minor) === undefined,
-							0x7a9 /* Collision during index update */,
-						);
-						innerUpdated.set(minor, entry);
-					}
-				}
+	public toFieldKey(id: ForestRootId): FieldKey {
+		return brand(`${this.name}-${id}`);
+	}
 
-				for (const [minor, entry] of innerCurrent) {
-					const entryInLatest = this.latestRelevantRevisionToFields.get(
-						entry.latestRelevantRevision,
-					);
-					assert(
-						entryInLatest !== undefined,
-						0x9b9 /* Inconsistent data: missing node entry in latestRelevantRevision */,
-					);
-					entryInLatest.set(entry.root, { major: updated, minor });
-				}
+	public fromFieldKey(field: FieldKey): Delta.DetachedNodeId {
+		// TODO: maintain a lookup table or use field keys that encode the detached node ID
+		for (const { id, root } of this.entries()) {
+			if (this.toFieldKey(root) === field) {
+				return id;
 			}
 		}
-	}
-
-	public toFieldKey(id: ForestRootId): FieldKey {
-		return brand(`${this.name}-${id}`);
+		fail("No known detached roots in the given field");
 	}
 
 	public tryGetEntry(id: Delta.DetachedNodeId): ForestRootId | undefined {

package/src/core/tree/detachedFieldIndexCodecCommon.ts

@@ -3,11 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import {
-	type ICodecOptions,
-	type IJsonCodec,
-	makeVersionedValidatedCodec,
-} from "../../codec/index.js";
+import type { IJsonCodec } from "../../codec/index.js";
 import { hasSingle } from "../../util/index.js";
 
 import {
@@ -30,13 +26,13 @@ export function makeDetachedFieldIndexCodecFromMajorCodec<
 	TEncodedRevisionTagSchema extends TSchema,
 	TVersion extends DetachedFieldIndexFormatVersion,
 >(
-	options: ICodecOptions,
 	majorCodec: IJsonCodec<Major, TEncodedRevisionTag>,
 	version: TVersion,
 	encodedRevisionTagSchema: TEncodedRevisionTagSchema,
 ) {
 	const formatSchema = Format(version, encodedRevisionTagSchema);
-	return makeVersionedValidatedCodec(options, new Set([version]), formatSchema, {
+	return {
+		schema: formatSchema,
 		encode: (data: DetachedFieldSummaryData): Static<typeof formatSchema> => {
 			const rootsForRevisions: EncodedRootsForRevision[] = [];
 			for (const [major, innerMap] of data.data) {
@@ -84,5 +80,5 @@ export function makeDetachedFieldIndexCodecFromMajorCodec<
 				maxId: parsed.maxId,
 			};
 		},
-	});
+	};
 }

package/src/core/tree/detachedFieldIndexCodecV1.ts

@@ -6,7 +6,7 @@
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
-import type { ICodecOptions, IJsonCodec } from "../../codec/index.js";
+import type { CodecAndSchema, IJsonCodec } from "../../codec/index.js";
 import {
 	type EncodedRevisionTag,
 	type RevisionTagCodec,
@@ -14,7 +14,6 @@ import {
 	RevisionTagSchema,
 } from "../rebase/index.js";
 
-import type { FormatV1 } from "./detachedFieldIndexFormatV1.js";
 import type { DetachedFieldSummaryData, Major } from "./detachedFieldIndexTypes.js";
 import { makeDetachedFieldIndexCodecFromMajorCodec } from "./detachedFieldIndexCodecCommon.js";
 import { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
@@ -23,7 +22,6 @@ import { brand } from "../../util/index.js";
 class MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {
 	public constructor(
 		private readonly revisionTagCodec: RevisionTagCodec,
-		private readonly options: ICodecOptions,
 		private readonly idCompressor: IIdCompressor,
 	) {}
 
@@ -69,12 +67,10 @@ class MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {
 
 export function makeDetachedNodeToFieldCodecV1(
 	revisionTagCodec: RevisionTagCodec,
-	options: ICodecOptions,
 	idCompressor: IIdCompressor,
-): IJsonCodec<DetachedFieldSummaryData, FormatV1> {
-	const majorCodec = new MajorCodec(revisionTagCodec, options, idCompressor);
+): CodecAndSchema<DetachedFieldSummaryData> {
+	const majorCodec = new MajorCodec(revisionTagCodec, idCompressor);
 	return makeDetachedFieldIndexCodecFromMajorCodec(
-		options,
 		majorCodec,
 		brand(DetachedFieldIndexFormatVersion.v1),
 		RevisionTagSchema,

package/src/core/tree/detachedFieldIndexCodecV2.ts

@@ -6,20 +6,18 @@
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor, StableId } from "@fluidframework/id-compressor";
 
-import type { ICodecOptions, IJsonCodec } from "../../codec/index.js";
+import type { CodecAndSchema, IJsonCodec } from "../../codec/index.js";
 import type { EncodedRevisionTag, RevisionTagCodec, RevisionTag } from "../rebase/index.js";
 
-import { type FormatV2, StableOrFinalRevisionTag } from "./detachedFieldIndexFormatV2.js";
+import { StableOrFinalRevisionTag } from "./detachedFieldIndexFormatV2.js";
 import type { DetachedFieldSummaryData, Major } from "./detachedFieldIndexTypes.js";
 import { makeDetachedFieldIndexCodecFromMajorCodec } from "./detachedFieldIndexCodecCommon.js";
 import { isStableId } from "@fluidframework/id-compressor/internal";
 import { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
-import { brand } from "../../util/index.js";
 
 class MajorCodec implements IJsonCodec<Major> {
 	public constructor(
 		private readonly revisionTagCodec: RevisionTagCodec,
-		private readonly options: ICodecOptions,
 		private readonly idCompressor: IIdCompressor,
 	) {}
 
@@ -57,14 +55,12 @@ class MajorCodec implements IJsonCodec<Major> {
 
 export function makeDetachedNodeToFieldCodecV2(
 	revisionTagCodec: RevisionTagCodec,
-	options: ICodecOptions,
 	idCompressor: IIdCompressor,
-): IJsonCodec<DetachedFieldSummaryData, FormatV2> {
-	const majorCodec = new MajorCodec(revisionTagCodec, options, idCompressor);
+): CodecAndSchema<DetachedFieldSummaryData> {
+	const majorCodec = new MajorCodec(revisionTagCodec, idCompressor);
 	return makeDetachedFieldIndexCodecFromMajorCodec(
-		options,
 		majorCodec,
-		brand(DetachedFieldIndexFormatVersion.v2),
+		DetachedFieldIndexFormatVersion.v2,
 		StableOrFinalRevisionTag,
 	);
 }

package/src/core/tree/detachedFieldIndexCodecs.ts

@@ -4,79 +4,36 @@
  */
 
 import type { IIdCompressor } from "@fluidframework/id-compressor";
-import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
-import {
-	getConfigForMinVersionForCollab,
-	lowestMinVersionForCollab,
-} from "@fluidframework/runtime-utils/internal";
+import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal";
 
 import {
-	type CodecTree,
+	ClientVersionDispatchingCodecBuilder,
 	type CodecWriteOptions,
 	FluidClientVersion,
-	type ICodecFamily,
-	type IJsonCodec,
-	makeCodecFamily,
-	makeVersionDispatchingCodec,
 } from "../../codec/index.js";
 import type { RevisionTagCodec } from "../rebase/index.js";
 
 import { makeDetachedNodeToFieldCodecV1 } from "./detachedFieldIndexCodecV1.js";
 import { makeDetachedNodeToFieldCodecV2 } from "./detachedFieldIndexCodecV2.js";
-import type { DetachedFieldSummaryData } from "./detachedFieldIndexTypes.js";
 import { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
-import { brand } from "../../util/index.js";
-
-/**
- * Convert a MinimumVersionForCollab to a version for detached field codecs.
- * @param clientVersion - The MinimumVersionForCollab to convert.
- * @returns The detached field codec version that corresponds to the provided MinimumVersionForCollab.
- */
-function clientVersionToDetachedFieldVersion(
-	clientVersion: MinimumVersionForCollab,
-): DetachedFieldIndexFormatVersion {
-	return brand(
-		getConfigForMinVersionForCollab(clientVersion, {
-			[lowestMinVersionForCollab]: DetachedFieldIndexFormatVersion.v1,
-			[FluidClientVersion.v2_52]: DetachedFieldIndexFormatVersion.v2,
-		}),
-	);
-}
-
-export function makeDetachedFieldIndexCodec(
-	revisionTagCodec: RevisionTagCodec,
-	options: CodecWriteOptions,
-	idCompressor: IIdCompressor,
-): IJsonCodec<DetachedFieldSummaryData> {
-	const family = makeDetachedFieldIndexCodecFamily(revisionTagCodec, options, idCompressor);
-	return makeVersionDispatchingCodec(family, {
-		...options,
-		writeVersion: clientVersionToDetachedFieldVersion(options.minVersionForCollab),
-	});
-}
 
-export function makeDetachedFieldIndexCodecFamily(
-	revisionTagCodec: RevisionTagCodec,
-	options: CodecWriteOptions,
-	idCompressor: IIdCompressor,
-): ICodecFamily<DetachedFieldSummaryData> {
-	return makeCodecFamily([
-		[
-			DetachedFieldIndexFormatVersion.v1,
-			makeDetachedNodeToFieldCodecV1(revisionTagCodec, options, idCompressor),
-		],
-		[
-			DetachedFieldIndexFormatVersion.v2,
-			makeDetachedNodeToFieldCodecV2(revisionTagCodec, options, idCompressor),
-		],
-	]);
-}
+type BuildData = CodecWriteOptions & {
+	revisionTagCodec: RevisionTagCodec;
+	idCompressor: IIdCompressor;
+};
 
-export function getCodecTreeForDetachedFieldIndexFormat(
-	clientVersion: MinimumVersionForCollab,
-): CodecTree {
-	return {
-		name: "DetachedFieldIndex",
-		version: clientVersionToDetachedFieldVersion(clientVersion),
-	};
-}
+export const detachedFieldIndexCodecBuilder = ClientVersionDispatchingCodecBuilder.build(
+	"DetachedFieldIndex",
+	{
+		[lowestMinVersionForCollab]: {
+			formatVersion: DetachedFieldIndexFormatVersion.v1,
+			codec: (buildData: BuildData) =>
+				makeDetachedNodeToFieldCodecV1(buildData.revisionTagCodec, buildData.idCompressor),
+		},
+		[FluidClientVersion.v2_52]: {
+			formatVersion: DetachedFieldIndexFormatVersion.v2,
+			codec: (buildData: BuildData) =>
+				makeDetachedNodeToFieldCodecV2(buildData.revisionTagCodec, buildData.idCompressor),
+		},
+	},
+);

package/src/core/tree/index.ts

@@ -59,8 +59,9 @@ export {
 	type NodeIndex,
 	compareUpPaths,
 	compareFieldUpPaths,
-	isDetachedUpPathRoot as isDetachedUpPath,
+	isDetachedUpPathRoot,
 	getDetachedFieldContainingPath,
+	getDetachedFieldContainingFieldPath,
 	type UpPathDefault,
 } from "./pathTree.js";
 export {
@@ -123,7 +124,7 @@ export {
 	type ReadOnlyDetachedFieldIndex,
 } from "./detachedFieldIndex.js";
 
-export { getCodecTreeForDetachedFieldIndexFormat } from "./detachedFieldIndexCodecs.js";
+export { detachedFieldIndexCodecBuilder } from "./detachedFieldIndexCodecs.js";
 export { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
 export { type FormatV1 } from "./detachedFieldIndexFormatV1.js";