@fluidframework/tree 2.74.0 → 2.81.0-374083

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

@@ -171,7 +171,9 @@ export class ForestSummarizer
 					: undefined,
 		};
 		const encoded = this.codec.encode(fieldMap, encoderContext);
-		fieldMap.forEach((value) => value.free());
+		for (const value of fieldMap.values()) {
+			value.free();
+		}
 
 		this.incrementalSummaryBuilder.completeSummary({
 			incrementalSummaryContext,

package/src/feature-libraries/index.ts

@@ -29,11 +29,8 @@ export {
 export { buildForest } from "./object-forest/index.js";
 export {
 	SchemaSummarizer,
-	encodeTreeSchema,
 	makeSchemaCodec,
-	makeSchemaCodecs,
-	getCodecTreeForSchemaFormat,
-	clientVersionToSchemaVersion,
+	schemaCodecBuilder,
 } from "./schema-index/index.js";
 export {
 	stackTreeNodeCursor,
@@ -72,7 +69,9 @@ export {
 	type NodeChangeInverter,
 	type NodeChangeRebaser,
 	type NodeChangePruner,
-	type CrossFieldManager,
+	type ComposeNodeManager,
+	type InvertNodeManager,
+	type RebaseNodeManager,
 	CrossFieldTarget,
 	FlexFieldKind,
 	type FullSchemaPolicy,
@@ -82,17 +81,22 @@ export {
 	type HasFieldChanges,
 	type NodeExistsConstraint,
 	ModularChangeFamily,
-	type RelevantRemovedRootsFromChild,
-	EncodedModularChangeset,
+	EncodedModularChangesetV1,
+	EncodedModularChangesetV2,
 	updateRefreshers,
 	type NodeId,
 	type FieldChangeEncodingContext,
 	type FieldKindConfiguration,
 	type FieldKindConfigurationEntry,
 	isNeverTree,
+	DefaultRevisionReplacer,
 } from "./modular-schema/index.js";
 
-export { mapRootChanges } from "./deltaUtils.js";
+export {
+	mapRootChanges,
+	nodeIdFromChangeAtom,
+	changeAtomFromDetachedNodeId,
+} from "./deltaUtils.js";
 
 export {
 	type TreeChunk,
@@ -133,17 +137,26 @@ export {
 	type Identifier,
 	type Forbidden,
 	type DefaultChangeset,
+	type DetachedRootIds,
 	DefaultChangeFamily,
-	DefaultEditBuilder,
-	type IDefaultEditBuilder,
-	type ValueFieldEditBuilder,
-	type OptionalFieldEditBuilder,
-	type SequenceFieldEditBuilder,
+	type IdBasedChangeFamilyDataEditor,
+	DefaultIdBasedDataEditor,
+	type DataEditor,
+	type RequiredFieldEditor,
+	type OptionalFieldEditor,
+	type SequenceFieldEditor,
 	defaultSchemaPolicy,
 	fieldKinds,
 	fieldKindConfigurations,
 	intoDelta,
 	relevantRemovedRoots,
+	getBuildsIds,
+	type DetachedRootLocation,
+	type DetachedRootsLocation,
+	type DetachedRootIdRange,
+	type Locator,
+	LocationBasedDataEditor,
+	type ILocationBasedDataEditor,
 	getCodecTreeForModularChangeFormat,
 	type ModularChangeFormatVersion,
 } from "./default-schema/index.js";
@@ -213,3 +226,9 @@ export {
 	type TreeIndexKey,
 	type TreeIndexNodes,
 } from "./indexing/index.js";
+
+export {
+	type ChangeAtomIdBTree,
+	getFromChangeAtomIdMap,
+	setInChangeAtomIdMap,
+} from "./changeAtomIdBTree.js";

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

@@ -394,12 +394,12 @@ export class AnchorTreeIndex<TKey extends TreeIndexKey, TValue>
 	 * Given a cursor in field mode, indexes all nodes under the field and then indexes all nodes up the spine.
 	 */
 	private indexSpine(cursor: ITreeSubscriptionCursor): void {
-		if (keyAsDetachedField(cursor.getFieldKey()) !== rootField) {
-			cursor.exitField();
-			cursor.exitNode();
-		} else {
+		if (keyAsDetachedField(cursor.getFieldKey()) === rootField) {
 			// return early if we're already at the root field
 			return;
+		} else {
+			cursor.exitField();
+			cursor.exitNode();
 		}
 
 		// walk up the spine and index nodes until we reach the root
@@ -470,5 +470,5 @@ function filterNodes(
  * Checks that an array is of the type {@link TreeIndexNodes} and has at least one element.
  */
 export function hasElement<T>(array: readonly T[]): array is TreeIndexNodes<T> {
-	return array.length >= 1;
+	return array.length > 0;
 }

package/src/feature-libraries/mapTreeCursor.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert } from "@fluidframework/core-utils/internal";
 
 import {
 	CursorLocationType,
@@ -161,6 +161,7 @@ export function mapTreeFromCursor(cursor: ITreeCursor): ExclusiveMapTree {
 	const fields: Map<FieldKey, ExclusiveMapTree[]> = new Map();
 	for (let inField = cursor.firstField(); inField; inField = cursor.nextField()) {
 		const field: ExclusiveMapTree[] = mapCursorField(cursor, mapTreeFromCursor);
+		debugAssert(() => field.length > 0 || "field must have at least one child");
 		fields.set(cursor.getFieldKey(), field);
 	}
 

package/src/feature-libraries/mitigatedChangeFamily.ts

@@ -7,7 +7,9 @@ import type {
 	ChangeFamily,
 	ChangeFamilyEditor,
 	ChangeRebaser,
+	EditorOptions,
 	RevisionMetadataSource,
+	RevisionReplacer,
 	RevisionTag,
 	TaggedChange,
 } from "../core/index.js";
@@ -35,8 +37,9 @@ export function makeMitigatedChangeFamily<TEditor extends ChangeFamilyEditor, TC
 		buildEditor: (
 			mintRevisionTag: () => RevisionTag,
 			changeReceiver: (change: TaggedChange<TChange>) => void,
+			options?: EditorOptions,
 		): TEditor => {
-			return unmitigatedChangeFamily.buildEditor(mintRevisionTag, changeReceiver);
+			return unmitigatedChangeFamily.buildEditor(mintRevisionTag, changeReceiver, options);
 		},
 		rebaser: makeMitigatedRebaser(unmitigatedChangeFamily.rebaser, fallbackChange, onError),
 		codecs: unmitigatedChangeFamily.codecs,
@@ -75,11 +78,15 @@ export function makeMitigatedRebaser<TChange>(
 		): TChange => {
 			return withFallback(() => unmitigatedRebaser.rebase(change, over, revisionMetadata));
 		},
-		changeRevision: (
-			change: TChange,
-			newRevision: RevisionTag | undefined,
-			rollbackOf?: RevisionTag,
-		): TChange =>
-			withFallback(() => unmitigatedRebaser.changeRevision(change, newRevision, rollbackOf)),
+		getRevisions: (change: TChange): Set<RevisionTag | undefined> => {
+			try {
+				return unmitigatedRebaser.getRevisions(change);
+			} catch (error: unknown) {
+				onError(error);
+				return new Set();
+			}
+		},
+		changeRevision: (change: TChange, replacer: RevisionReplacer): TChange =>
+			withFallback(() => unmitigatedRebaser.changeRevision(change, replacer)),
 	};
 }

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

@@ -144,10 +144,8 @@ export function allowsFieldSuperset(
 	superset: TreeFieldStoredSchema,
 	monotonicOnly: boolean = true,
 ): boolean {
-	if (!monotonicOnly) {
-		if (isNeverField(policy, originalData, original)) {
-			return true;
-		}
+	if (!monotonicOnly && isNeverField(policy, originalData, original)) {
+		return true;
 	}
 
 	if (!allowsTreeSchemaIdentifierSuperset(original.types, superset.types)) {
@@ -239,15 +237,20 @@ export function allowsMultiplicitySuperset(
 	}
 
 	switch (superset) {
-		case Multiplicity.Forbidden:
+		case Multiplicity.Forbidden: {
 			return false;
-		case Multiplicity.Optional:
+		}
+		case Multiplicity.Optional: {
 			return original === Multiplicity.Single || original === Multiplicity.Forbidden;
-		case Multiplicity.Single:
+		}
+		case Multiplicity.Single: {
 			return false;
-		case Multiplicity.Sequence:
+		}
+		case Multiplicity.Sequence: {
 			return true;
-		default:
+		}
+		default: {
 			return unreachableCase(superset);
+		}
 	}
 }

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

@@ -16,23 +16,13 @@ import type { NodeId } from "./modularChangeTypes.js";
 export type CrossFieldMap<T> = ChangeAtomIdRangeMap<T>;
 export type CrossFieldQuerySet = CrossFieldMap<boolean>;
 
-export function addCrossFieldQuery(
-	set: CrossFieldQuerySet,
-	revision: RevisionTag | undefined,
-	id: ChangesetLocalId,
-	count: number,
-): void {
-	setInCrossFieldMap(set, revision, id, count, true);
-}
-
 export function setInCrossFieldMap<T>(
 	map: CrossFieldMap<T>,
-	revision: RevisionTag | undefined,
-	id: ChangesetLocalId,
+	id: ChangeAtomId,
 	count: number,
 	value: T,
 ): void {
-	map.set({ revision, localId: id }, count, value);
+	map.set(id, count, value);
 }
 
 export function getFirstFromCrossFieldMap<T>(
@@ -40,60 +30,168 @@ export function getFirstFromCrossFieldMap<T>(
 	revision: RevisionTag | undefined,
 	id: ChangesetLocalId,
 	count: number,
-): RangeQueryResult<ChangeAtomId, T> {
+): RangeQueryResult<T | undefined> {
 	return map.getFirst({ revision, localId: id }, count);
 }
 
+// TODO: Rename to NodeMoveType(Attach | Detach)
 export enum CrossFieldTarget {
 	Source,
 	Destination,
 }
 
-/**
- * Used by {@link FieldChangeHandler} implementations for exchanging information across other fields
- * while rebasing, composing, or inverting a change.
- */
-export interface CrossFieldManager<T = unknown> {
+export interface InvertNodeManager {
+	/**
+	 * Transfers the given node changes from the input context of the field changeset being inverted to the input context of the detached space (from which it may be further moved).
+	 *
+	 * This must be called for each detach in the field kind when rolling-back or undoing an detach.
+	 * This implies that all detaches in the field must be inverted.
+	 * @param detachId - The ID of the detach to invert.
+	 * @param count - The number of nodes being detached.
+	 * @param nodeChanges - The node changes to transfer.
+	 * @param newAttachId - The ID that the nodes will be attached with in the inverted changeset of this field.
+	 */
+	invertDetach(
+		detachId: ChangeAtomId,
+		count: number,
+		nodeChanges: NodeId | undefined,
+		newAttachId: ChangeAtomId,
+	): void;
+
+	/**
+	 * Gets the node changes associated with the node being attached in input changeset.
+	 *
+	 * This must be called for each attach in the field kind when rolling-back or undoing an attach.
+	 * This implies that all attaches in the field must be inverted.
+	 * @param attachId - The ID of the attach to invert.
+	 * @param count - The number of nodes being attached.
+	 */
+	invertAttach(
+		attachId: ChangeAtomId,
+		count: number,
+	): RangeQueryResult<DetachedNodeEntry | undefined>;
+}
+
+export interface ComposeNodeManager {
+	/**
+	 * Allows a field kind to query nested changes associated with a node in the input context of the new changeset.
+	 * This should be called for every detach in the base changeset.
+	 * @param baseDetachId - The ID of the detach in the base changeset.
+	 * @param count - The number of nodes being detached.
+	 */
+	getNewChangesForBaseDetach(
+		baseDetachId: ChangeAtomId,
+		count: number,
+	): RangeQueryResult<DetachedNodeEntry | undefined>;
+
 	/**
-	 * Returns the first data range associated with the key of `target`, `revision`, between `id` and `id + count`.
-	 * Calling this records a dependency for the current field on this key if `addDependency` is true.
+	 * Must be called by a field kind when composing an attach in the base changeset with a detach in the new changeset.
+	 * This allows Modular Change Family to keep track of how a given node is being renamed.
+	 * @param baseAttachId - The ID of the attach in the base changeset.
+	 * @param newDetachId - The ID of the detach in the new changeset.
+	 * @param count - The number of nodes being attached then detached.
 	 */
-	get(
-		target: CrossFieldTarget,
-		revision: RevisionTag | undefined,
-		id: ChangesetLocalId,
+	composeAttachDetach(
+		baseAttachId: ChangeAtomId,
+		newDetachId: ChangeAtomId,
 		count: number,
-		addDependency: boolean,
-	): RangeQueryResult<ChangeAtomId, T>;
+	): void;
+
+	/**
+	 * Must be called by a field kind when composing an attach in the base changeset with nested changes the new changeset.
+	 *
+	 * This is needed because child changes are represented at the location of the node they impact in the input context of a changeset.
+	 * So if the later of the two changes being composed carries nested changes for a node,
+	 * then in the composed changeset, these nested changes must to be represented at the location of that node in the input context of the composed changeset.
+	 *
+	 * @param baseAttachId - The ID of the attach in the base changeset.
+	 * @param newChanges - The ID of the nested changes associated with this node in the new changeset.
+	 */
+	sendNewChangesToBaseSourceLocation(baseAttachId: ChangeAtomId, newChanges: NodeId): void;
 
+	// XXX: It doesn't seem like it should be mandatory to call this if you don't want the rename to be removed (e.g., optional field pin).
 	/**
-	 * Sets the range of keys to `newValue`.
-	 * If `invalidateDependents` is true, all fields which took a dependency on this key will be considered invalidated
-	 * and will be given a chance to address the new data in `amendCompose`, or a second pass of `rebase` or `invert` as appropriate.
+	 * Must be called by a field kind when composing a detach in the base changeset with an attach of the same nodes in the new changeset.
+	 * @param baseDetachId - The ID of the detach in the base changeset.
+	 * @param newAttachId - The ID of the attach in the new changeset.
+	 * @param count - The number of nodes being detached then attached.
+	 * @param convertToPin - Should be set to true if the composed change will include a detach and attach with `newAttachId`.
+	 * Otherwise the composed change should not include either `baseDetachId` or `newAttachId`.
 	 */
-	set(
-		target: CrossFieldTarget,
-		revision: RevisionTag | undefined,
-		id: ChangesetLocalId,
+	composeDetachAttach(
+		baseDetachId: ChangeAtomId,
+		newAttachId: ChangeAtomId,
 		count: number,
-		newValue: T,
-		invalidateDependents: boolean,
+		convertToPin: boolean,
 	): void;
+}
 
+export interface RebaseNodeManager {
+	// XXX: It's not clear whether the returned changes are already rebased or not.
 	/**
-	 * This must be called whenever a new node is moved into this field as part of the current rebase, compose, or invert.
-	 * Calling this for a node which was already in the field is tolerated.
+	 * Must be called by a field kind when rebasing over an attach.
+	 * The returned child changes and detach intentions must be represented in the output changeset.
+	 * @param baseAttachId - The ID of the attach that is being rebased over.
+	 * @param count - The number of nodes attached by the base attach.
+	 * @returns The new nested changes and detach intentions associated with the node in the changeset being rebased.
 	 */
-	onMoveIn(id: NodeId): void;
+	getNewChangesForBaseAttach(
+		baseAttachId: ChangeAtomId,
+		count: number,
+	): RangeQueryResult<RebaseDetachedNodeEntry | undefined>;
 
+	// XXX: It's not clear if this must be called even when newDetachId and nodeChange are undefined.
+	// XXX: It's not clear if it's okay to call this once with a newDetachId then once with a nodeChange.
+	// XXX: It's not clear if nodeChange should be rebased already, or should not be rebased, or if it doesn't matter.
 	/**
-	 * This must be called whenever a new cross field key is moved into this field as part of the current rebase or compose.
-	 * Calling this for a key which was already in the field is tolerated.
+	 * Must be called by a field kind when rebasing over a detach.
+	 * The field kind must provide the nested changes and detach intentions associated with the node in the changeset being rebased.
+	 * @param baseDetachId - The ID of the detach that is being rebased over.
+	 * @param count - The number of nodes detached by the base detach.
+	 * @param newDetachId - The ID associated the detach intention (if any) for these nodes in the rebased changeset.
+	 * @param nodeChange - The nested changes (if any) associated with this node in the rebased changeset.
+	 * @param newDetachCellId - An additional ID to associate with this node.
+	 * This ID will be included in the result of {@link getNewChangesForBaseAttach}.
+	 * This is only used by sequence field for compatibility with earlier client versions.
 	 */
-	moveKey(
-		target: CrossFieldTarget,
-		revision: RevisionTag | undefined,
-		id: ChangesetLocalId,
+	rebaseOverDetach(
+		baseDetachId: ChangeAtomId,
 		count: number,
+		newDetachId: ChangeAtomId | undefined,
+		nodeChange: NodeId | undefined,
+		newDetachCellId?: ChangeAtomId,
 	): void;
+
+	addDetach(id: ChangeAtomId, count: number): void;
+	removeDetach(id: ChangeAtomId, count: number): void;
+
+	/**
+	 * Returns whether nodes which were either previously detached by `id` or the base changeset is now detaching with `id`
+	 * are also reattached by the base changeset.
+	 */
+	doesBaseAttachNodes(id: ChangeAtomId, count: number): RangeQueryResult<boolean>;
+
+	/**
+	 * Returns the root ID the base change renames `id` to, if any.
+	 */
+	getBaseRename(id: ChangeAtomId, count: number): RangeQueryResult<ChangeAtomId | undefined>;
+
+	/**
+	 * Given a detached node ID in the base changeset's output context,
+	 * returns the ID the rebased changeset renames that ID to, if any.
+	 */
+	getNewRenameForBaseRename(
+		baseRenameTo: ChangeAtomId,
+		count: number,
+	): RangeQueryResult<ChangeAtomId | undefined>;
+}
+
+export interface DetachedNodeEntry {
+	nodeChange?: NodeId;
+	detachId?: ChangeAtomId;
+}
+
+export interface RebaseDetachedNodeEntry extends DetachedNodeEntry {
+	// This is only needed for sequence field to implement detach cell IDs.
+	cellRename?: ChangeAtomId;
 }

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

@@ -0,0 +1,70 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	ChangeAtomId,
+	ChangesetLocalId,
+	RevisionReplacer,
+	RevisionTag,
+} from "../../core/index.js";
+import { brand, brandConst, newTupleBTree, type Mutable } from "../../util/index.js";
+import {
+	getFromChangeAtomIdMap,
+	setInChangeAtomIdMap,
+	type ChangeAtomIdBTree,
+} from "../changeAtomIdBTree.js";
+
+export class DefaultRevisionReplacer implements RevisionReplacer {
+	/**
+	 * Mapping from (obsolete revision tag, original local id) to the updated local id.
+	 */
+	private readonly updatedLocalIds: ChangeAtomIdBTree<ChangesetLocalId> = newTupleBTree();
+	/**
+	 * The set of local IDs already used in the scope of the updated revision.
+	 */
+	private readonly localIds: Set<ChangesetLocalId> = new Set();
+	/**
+	 * The maximum local ID seen so far in the scope of the updated revision.
+	 */
+	private maxSeen: ChangesetLocalId = brandConst(-1)();
+
+	public constructor(
+		public readonly updatedRevision: RevisionTag,
+		private readonly obsoleteRevisions: Set<RevisionTag | undefined>,
+	) {}
+
+	public isObsolete(revision: RevisionTag | undefined): boolean {
+		return this.obsoleteRevisions.has(revision);
+	}
+
+	public getUpdatedAtomId<T extends ChangeAtomId>(id: T): T {
+		if (this.isObsolete(id.revision)) {
+			const updated: Mutable<T> = { ...id, revision: this.updatedRevision };
+			const prior: ChangesetLocalId | undefined = getFromChangeAtomIdMap(
+				this.updatedLocalIds,
+				id,
+			);
+			if (prior === undefined) {
+				let localId: ChangesetLocalId;
+				if (this.localIds.has(id.localId)) {
+					this.maxSeen = brand(this.maxSeen + 1);
+					localId = this.maxSeen;
+				} else {
+					// This change atom ID uses a local ID that has not yet been used in the scope of the updated revision.
+					// We reuse it as is to minimize the number of IDs that need to be updated.
+					localId = id.localId;
+					this.maxSeen = brand(Math.max(this.maxSeen, localId));
+					this.localIds.add(id.localId);
+				}
+				setInChangeAtomIdMap(this.updatedLocalIds, id, localId);
+				updated.localId = localId;
+			} else {
+				updated.localId = prior;
+			}
+			return updated;
+		}
+		return id;
+	}
+}