@fluidframework/tree 2.90.0-378676 → 2.90.0

package/src/core/tree/detachedFieldIndex.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, fail } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
@@ -52,12 +52,6 @@ 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.
@@ -69,12 +63,6 @@ export interface ReadOnlyDetachedFieldIndex {
 	 * Fails if no such id is known to the index.
 	 */
 	getEntry(id: Delta.DetachedNodeId): ForestRootId;
-
-	/**
-	 * Returns the source associated with the given id if any.
-	 * @param id - The detached node ID.
-	 */
-	isAttachable(id: Delta.DetachedNodeId): boolean | undefined;
 }
 
 /**
@@ -209,16 +197,6 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		return brand(`${this.name}-${id}`);
 	}
 
-	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;
-			}
-		}
-		fail("No known detached roots in the given field");
-	}
-
 	public tryGetEntry(id: Delta.DetachedNodeId): ForestRootId | undefined {
 		return tryGetFromNestedMap(this.detachedNodeToField, id.major, id.minor)?.root;
 	}
@@ -229,10 +207,6 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		return key;
 	}
 
-	public isAttachable(id: Delta.DetachedNodeId): boolean | undefined {
-		return tryGetFromNestedMap(this.detachedNodeToField, id.major, id.minor)?.isAttachable;
-	}
-
 	/**
 	 * Returns the detached root IDs for all the trees that were detached or last modified by the given revision.
 	 */
@@ -285,7 +259,6 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 	public createEntry(
 		nodeId?: Delta.DetachedNodeId,
 		revision?: RevisionTag,
-		isAttachable?: boolean,
 		count: number = 1,
 	): ForestRootId {
 		const root = this.rootIdAllocator.allocate(count);
@@ -299,7 +272,6 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 				setInNestedMap(this.detachedNodeToField, nodeId.major, nodeId.minor + i, {
 					root: brand<ForestRootId>(root + i),
 					latestRelevantRevision: revision,
-					isAttachable,
 				});
 				setInNestedMap(this.latestRelevantRevisionToFields, revision, root + i, {
 					major: nodeId.major,

package/src/core/tree/detachedFieldIndexTypes.ts

@@ -49,9 +49,4 @@ export interface DetachedField {
 	 * `DetachedField` and `Forest` are GC-ed.
 	 */
 	readonly latestRelevantRevision?: RevisionTag;
-
-	/**
-	 * Indicates whether the corresponding root can safely be re-attached.
-	 */
-	readonly isAttachable?: boolean;
 }

package/src/core/tree/index.ts

@@ -30,17 +30,17 @@ export {
 	CursorMarker,
 	isCursor,
 } from "./cursor.js";
-export {
-	type ProtoNodes,
-	type Root as DeltaRoot,
-	type Mark as DeltaMark,
-	type DetachedNodeId as DeltaDetachedNodeId,
-	type FieldMap as DeltaFieldMap,
-	type DetachedNodeChanges as DeltaDetachedNodeChanges,
-	type DetachedNodeBuild as DeltaDetachedNodeBuild,
-	type DetachedNodeDestruction as DeltaDetachedNodeDestruction,
-	type DetachedNodeRename as DeltaDetachedNodeRename,
-	type FieldChanges as DeltaFieldChanges,
+export type {
+	ProtoNodes,
+	Root as DeltaRoot,
+	Mark as DeltaMark,
+	DetachedNodeId as DeltaDetachedNodeId,
+	FieldMap as DeltaFieldMap,
+	DetachedNodeChanges as DeltaDetachedNodeChanges,
+	DetachedNodeBuild as DeltaDetachedNodeBuild,
+	DetachedNodeDestruction as DeltaDetachedNodeDestruction,
+	DetachedNodeRename as DeltaDetachedNodeRename,
+	FieldChanges as DeltaFieldChanges,
 } from "./delta.js";
 export { type MapTree, type ExclusiveMapTree, deepCopyMapTree } from "./mapTree.js";
 export {
@@ -59,9 +59,8 @@ export {
 	type NodeIndex,
 	compareUpPaths,
 	compareFieldUpPaths,
-	isDetachedUpPathRoot,
+	isDetachedUpPathRoot as isDetachedUpPath,
 	getDetachedFieldContainingPath,
-	getDetachedFieldContainingFieldPath,
 	type UpPathDefault,
 } from "./pathTree.js";
 export {

package/src/core/tree/pathTree.ts

@@ -126,7 +126,7 @@ export interface FieldUpPath<TUpPath = UpPath> {
  */
 export function isDetachedUpPathRoot<T>(
 	path: UpPath<T> | NormalizedUpPath,
-): path is NormalizedUpPathRoot & { readonly detachedNodeId: DetachedNodeId } {
+): path is NormalizedUpPathRoot {
 	return (path as NormalizedUpPathRoot).detachedNodeId !== undefined;
 }
 
@@ -219,8 +219,8 @@ export function clonePath(path: UpPath | undefined): UpPath | undefined {
  * Gets the elements of the given `path`, ordered from root-most to child-most.
  * @remarks These elements are unchanged and therefore still point "up".
  */
-export function topDownPath<T extends UpPath<T>>(path: T | undefined): T[] {
-	const out: T[] = [];
+export function topDownPath(path: UpPath | undefined): UpPath[] {
+	const out: UpPath[] = [];
 	let curr = path;
 	while (curr !== undefined) {
 		out.push(curr);
@@ -262,7 +262,7 @@ export function compareFieldUpPaths(a: FieldUpPath, b: FieldUpPath): boolean {
 }
 
 /**
- * Returns the field key for the root field.
+ * Checks whether or not a given path is parented under the root field.
  * @param path - the path you want to check.
  * @returns the {@link DetachedField} which contains the path.
  */
@@ -277,15 +277,3 @@ export function getDetachedFieldContainingPath(path: UpPath): DetachedField {
 	}
 	return keyAsDetachedField(path.parentField);
 }
-
-/**
- * Returns the field key for the root field.
- * @param path - the path you want to check.
- * @returns the {@link DetachedField} which contains the path.
- */
-export function getDetachedFieldContainingFieldPath(path: FieldUpPath): DetachedField {
-	if (path.parent === undefined) {
-		return keyAsDetachedField(path.field);
-	}
-	return getDetachedFieldContainingPath(path.parent);
-}

package/src/core/tree/visitDelta.ts

@@ -166,9 +166,7 @@ function transferRoots(
 	refreshers: NestedMap<Major, Minor, ITreeCursorSynchronous>,
 	revision?: RevisionTag,
 ): void {
-	type AtomizedNodeRename = Omit<Delta.DetachedNodeRename, "count"> & {
-		isAttachable?: boolean;
-	};
+	type AtomizedNodeRename = Omit<Delta.DetachedNodeRename, "count">;
 	let nextBatch = rootTransfers.flatMap(({ oldId, newId, count }) => {
 		const atomized: AtomizedNodeRename[] = [];
 		// It's possible for a detached node to be revived transiently such that it ends up back in the same detached field.
@@ -178,12 +176,7 @@ function transferRoots(
 		// This if statement prevents that from happening.
 		if (!areDetachedNodeIdsEqual(oldId, newId)) {
 			for (let i = 0; i < count; i += 1) {
-				const source = detachedFieldIndex.isAttachable(offsetDetachId(oldId, i));
-				atomized.push({
-					oldId: offsetDetachId(oldId, i),
-					newId: offsetDetachId(newId, i),
-					isAttachable: source,
-				});
+				atomized.push({ oldId: offsetDetachId(oldId, i), newId: offsetDetachId(newId, i) });
 			}
 		}
 		return atomized;
@@ -191,29 +184,30 @@ function transferRoots(
 	while (nextBatch.length > 0) {
 		const delayed: AtomizedNodeRename[] = [];
 		const priorSize = nextBatch.length;
-		for (const { oldId, newId, isAttachable } of nextBatch) {
+		for (const { oldId, newId } of nextBatch) {
 			let oldRootId = detachedFieldIndex.tryGetEntry(oldId);
 			if (oldRootId === undefined) {
 				const tree = tryGetFromNestedMap(refreshers, oldId.major, oldId.minor);
 				if (tree !== undefined) {
-					buildTrees(oldId, [tree], detachedFieldIndex, revision, false, visitor);
+					buildTrees(oldId, [tree], detachedFieldIndex, revision, visitor);
 					oldRootId = detachedFieldIndex.getEntry(oldId);
 				}
 			}
 			if (oldRootId === undefined) {
 				// The source field is not populated.
 				// This can happen when another rename needs to be performed first.
-				delayed.push({ oldId, newId, isAttachable });
+				delayed.push({ oldId, newId });
 				continue;
 			}
 			let newRootId = detachedFieldIndex.tryGetEntry(newId);
 			if (newRootId !== undefined) {
 				// The destination field is already occupied.
 				// This can happen when another rename needs to be performed first.
-				delayed.push({ oldId, newId, isAttachable });
+				delayed.push({ oldId, newId });
 				continue;
 			}
-			newRootId = detachedFieldIndex.createEntry(newId, revision, isAttachable);
+			// eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- intentional behavior
+			newRootId = detachedFieldIndex.createEntry(newId, revision);
 			const fields = mapToUpdate.get(oldRootId);
 			if (fields !== undefined) {
 				mapToUpdate.delete(oldRootId);
@@ -419,11 +413,7 @@ function detachPass(
 		if (mark.detach !== undefined) {
 			for (let i = 0; i < mark.count; i += 1) {
 				const id = offsetDetachId(mark.detach, i);
-				const root = config.detachedFieldIndex.createEntry(
-					id,
-					config.latestRevision,
-					fieldChanges.allowReattach,
-				);
+				const root = config.detachedFieldIndex.createEntry(id, config.latestRevision);
 				if (mark.fields !== undefined) {
 					config.attachPassRoots.set(root, mark.fields);
 				}
@@ -442,14 +432,13 @@ function buildTrees(
 	trees: readonly ITreeCursorSynchronous[],
 	detachedFieldIndex: DetachedFieldIndex,
 	latestRevision: RevisionTag | undefined,
-	isAttachable: boolean,
 	visitor: DeltaVisitor,
 ): void {
 	for (const [i, tree] of trees.entries()) {
 		const offsettedId = offsetDetachId(id, i);
 		let root = detachedFieldIndex.tryGetEntry(offsettedId);
 		assert(root === undefined, 0x929 /* Unable to build tree that already exists */);
-		root = detachedFieldIndex.createEntry(offsettedId, latestRevision, isAttachable);
+		root = detachedFieldIndex.createEntry(offsettedId, latestRevision);
 		const field = detachedFieldIndex.toFieldKey(root);
 		visitor.create([tree], field);
 	}
@@ -467,7 +456,6 @@ function processBuilds(
 				nodeCursorsFromChunk(trees),
 				config.detachedFieldIndex,
 				config.latestRevision,
-				true,
 				visitor,
 			);
 		}
@@ -485,14 +473,7 @@ function processGlobal(
 			if (root === undefined) {
 				const tree = tryGetFromNestedMap(config.refreshers, id.major, id.minor);
 				assert(tree !== undefined, 0x928 /* refresher data not found */);
-				buildTrees(
-					id,
-					[tree],
-					config.detachedFieldIndex,
-					config.latestRevision,
-					false,
-					visitor,
-				);
+				buildTrees(id, [tree], config.detachedFieldIndex, config.latestRevision, visitor);
 				root = config.detachedFieldIndex.getEntry(id);
 			}
 			// the revision is updated for any refresher data included in the delta that is used
@@ -548,7 +529,6 @@ function attachPass(
 						[tree],
 						config.detachedFieldIndex,
 						config.latestRevision,
-						false,
 						visitor,
 					);
 					sourceRoot = config.detachedFieldIndex.getEntry(offsetAttachId);

package/src/feature-libraries/changeAtomIdBTree.ts

@@ -4,19 +4,13 @@
  */
 
 import {
-	subtractChangeAtomIds,
 	compareChangesetLocalIds,
 	comparePartialRevisions,
 	type ChangeAtomId,
 	type ChangesetLocalId,
 	type RevisionTag,
 } from "../core/index.js";
-import {
-	createTupleComparator,
-	newTupleBTree,
-	type RangeQueryResult,
-	type TupleBTree,
-} from "../util/index.js";
+import { createTupleComparator, newTupleBTree, type TupleBTree } from "../util/index.js";
 
 /**
  * A BTree which uses ChangeAtomId flattened into a tuple as the key.
@@ -48,25 +42,6 @@ export function setInChangeAtomIdMap<T>(
 	map: ChangeAtomIdBTree<T>,
 	id: ChangeAtomId,
 	value: T,
-): boolean {
-	return map.set([id.revision, id.localId], value);
-}
-
-export function rangeQueryChangeAtomIdMap<T>(
-	map: ChangeAtomIdBTree<T>,
-	id: ChangeAtomId,
-	count: number,
-): RangeQueryResult<T | undefined> {
-	const pair = map.getPairOrNextHigher([id.revision, id.localId]);
-	if (pair === undefined) {
-		return { value: undefined, length: count };
-	}
-
-	const [[revision, localId], value] = pair;
-	const lengthBefore = subtractChangeAtomIds({ revision, localId }, id);
-	if (lengthBefore === 0) {
-		return { value, length: 1 };
-	}
-
-	return { value: undefined, length: Math.min(lengthBefore, count) };
+): void {
+	map.set([id.revision, id.localId], value);
 }

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

@@ -5,37 +5,33 @@
 
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor, SessionId } 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 { TSchema } from "@sinclair/typebox";
 
 import {
-	type CodecTree,
-	type CodecWriteOptions,
+	ClientVersionDispatchingCodecBuilder,
+	type CodecAndSchema,
 	FluidClientVersion,
-	type IJsonCodec,
-	makeVersionedValidatedCodec,
 } from "../../../codec/index.js";
 import {
 	CursorLocationType,
 	type ITreeCursorSynchronous,
 	type SchemaAndPolicy,
+	type SchemaPolicy,
+	type StoredSchemaCollection,
 	type TreeChunk,
 } from "../../../core/index.js";
-import {
-	brand,
-	brandedNumberType,
-	type Brand,
-	type JsonCompatibleReadOnly,
-	unbrand,
-} from "../../../util/index.js";
+import { brandedNumberType, type Brand } from "../../../util/index.js";
 import { TreeCompressionStrategy } from "../../treeCompressionUtils.js";
 
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
-import { EncodedFieldBatch, validVersions, FieldBatchFormatVersion } from "./format.js";
+import {
+	type EncodedFieldBatch,
+	FieldBatchFormatVersion,
+	EncodedFieldBatchV1,
+	EncodedFieldBatchV2,
+} from "./format.js";
 import type { IncrementalEncodingPolicy } from "./incrementalEncodingPolicy.js";
 import { schemaCompressedEncodeV1, schemaCompressedEncodeV2 } from "./schemaBasedEncode.js";
 import { uncompressedEncodeV1, uncompressedEncodeV2 } from "./uncompressedEncode.js";
@@ -114,63 +110,24 @@ export interface FieldBatchEncodingContext {
  * @remarks
  * Fields in this batch currently don't have field schema for the root, which limits optimizations.
  */
-export type FieldBatchCodec = IJsonCodec<
-	FieldBatch,
-	EncodedFieldBatch,
-	JsonCompatibleReadOnly,
-	FieldBatchEncodingContext
->;
+export type FieldBatchCodec = ReturnType<typeof fieldBatchCodecBuilder.build>;
 
 /**
- * Convert a MinimumVersionForCollab to write version for {@link FieldBatchCodec}.
- * @param clientVersion - The MinimumVersionForCollab to convert.
+ * Creates the encode/decode functions for a specific FieldBatch format version.
  */
-function clientVersionToFieldBatchVersion(
-	clientVersion: MinimumVersionForCollab,
-): FieldBatchFormatVersion {
-	return brand(
-		getConfigForMinVersionForCollab(clientVersion, {
-			[lowestMinVersionForCollab]: FieldBatchFormatVersion.v1,
-			[FluidClientVersion.v2_73]: FieldBatchFormatVersion.v2,
-		}),
-	);
-}
-
-export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec {
-	const writeVersion = clientVersionToFieldBatchVersion(options.minVersionForCollab);
-	// Note: it's important that the decode function is schema-agnostic for this strategy/layering to work, since
-	// the schema that an op was encoded in doesn't necessarily match the current schema for the document (e.g. if
-	// decode is being run on a client that just submitted a schema change, but the op is from another client who has
-	// yet to receive that change).
-	assert(
-		validVersions.has(writeVersion),
-		0x935 /* Invalid write version for FieldBatch codec */,
-	);
-
-	let uncompressedEncodeFn: typeof uncompressedEncodeV1 | typeof uncompressedEncodeV2;
-	let schemaCompressedEncodeFn:
-		| typeof schemaCompressedEncodeV1
-		| typeof schemaCompressedEncodeV2;
-	switch (writeVersion) {
-		case unbrand(FieldBatchFormatVersion.v1): {
-			uncompressedEncodeFn = uncompressedEncodeV1;
-			schemaCompressedEncodeFn = schemaCompressedEncodeV1;
-			break;
-		}
-		case unbrand(FieldBatchFormatVersion.v2): {
-			uncompressedEncodeFn = uncompressedEncodeV2;
-			schemaCompressedEncodeFn = schemaCompressedEncodeV2;
-			break;
-		}
-		default: {
-			unreachableCase(writeVersion);
-		}
-	}
-
-	// Both the encode and decode logic here support both v1 and v2, as does `validVersions` and `EncodedFieldBatch`.
-	// 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, EncodedFieldBatch, {
+function makeFieldBatchCodecForVersion(
+	version: FieldBatchFormatVersion,
+	uncompressedEncodeFn: (batch: FieldBatch) => EncodedFieldBatch,
+	schemaCompressedEncodeFn: (
+		schema: StoredSchemaCollection,
+		policy: SchemaPolicy,
+		fieldBatch: FieldBatch,
+		idCompressor: IIdCompressor,
+		incrementalEncoder: IncrementalEncoder | undefined,
+	) => EncodedFieldBatch,
+	encodedFieldBatchType: TSchema,
+): CodecAndSchema<FieldBatch, FieldBatchEncodingContext> {
+	return {
 		encode: (data: FieldBatch, context: FieldBatchEncodingContext): EncodedFieldBatch => {
 			for (const cursor of data) {
 				assert(
@@ -187,7 +144,7 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 				}
 				case TreeCompressionStrategy.CompressedIncremental: {
 					assert(
-						writeVersion >= FieldBatchFormatVersion.v2,
+						version >= FieldBatchFormatVersion.v2,
 						0xca0 /* Unsupported FieldBatchFormatVersion for incremental encoding; must be v2 or higher */,
 					);
 					// Incremental encoding is only supported for CompressedIncremental.
@@ -230,11 +187,35 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 				context.incrementalEncoderDecoder,
 			).map((chunk) => chunk.cursor());
 		},
-	});
+		schema: encodedFieldBatchType,
+	};
 }
 
-export function getCodecTreeForFieldBatchFormat(
-	clientVersion: MinimumVersionForCollab,
-): CodecTree {
-	return { name: "FieldBatch", version: clientVersionToFieldBatchVersion(clientVersion) };
-}
+/**
+ * {@link ClientVersionDispatchingCodecBuilder} for field batch codecs.
+ */
+export const fieldBatchCodecBuilder = ClientVersionDispatchingCodecBuilder.build(
+	"FieldBatch",
+	[
+		{
+			minVersionForCollab: lowestMinVersionForCollab,
+			formatVersion: FieldBatchFormatVersion.v1,
+			codec: makeFieldBatchCodecForVersion(
+				FieldBatchFormatVersion.v1,
+				uncompressedEncodeV1,
+				schemaCompressedEncodeV1,
+				EncodedFieldBatchV1,
+			),
+		},
+		{
+			minVersionForCollab: FluidClientVersion.v2_73,
+			formatVersion: FieldBatchFormatVersion.v2,
+			codec: makeFieldBatchCodecForVersion(
+				FieldBatchFormatVersion.v2,
+				uncompressedEncodeV2,
+				schemaCompressedEncodeV2,
+				EncodedFieldBatchV2,
+			),
+		},
+	],
+);

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

@@ -19,7 +19,18 @@ import {
  * The format version for the field batch.
  */
 export const FieldBatchFormatVersion = strictEnum("FieldBatchFormatVersion", {
+	/**
+	 * Initial version.
+	 * @remarks
+	 * For simplicity of implementation the format for this version allows the same chunk shapes as v2, but must not use {@link EncodedIncrementalChunkShape}
+	 * as older clients will not know how to handle that shape but think they can handle this format.
+	 */
 	v1: 1,
+	/**
+	 * Adds support for incremental encoding of chunks.
+	 * @remarks
+	 * {@link EncodedIncrementalChunkShape} was added in this version.
+	 */
 	v2: 2,
 });
 export type FieldBatchFormatVersion = Values<typeof FieldBatchFormatVersion>;

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,