@fluidframework/tree 2.112.0 → 2.113.0-411909

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

@@ -5,6 +5,7 @@
 
 import type { ICodecFamily, JsonCodecPart } from "../../codec/index.js";
 import type {
+	ChangeAtomId,
 	ChangeEncodingContext,
 	DeltaDetachedNodeChanges,
 	DeltaDetachedNodeId,
@@ -16,7 +17,7 @@ import type {
 	RevisionTag,
 	RevisionTagSchema,
 } from "../../core/index.js";
-import type { IdAllocator, Invariant } from "../../util/index.js";
+import type { IdAllocator, Invariant, RangeQueryResult } from "../../util/index.js";
 
 import type { CrossFieldManager } from "./crossFieldQueries.js";
 import type { EncodedNodeChangeset } from "./modularChangeFormatV1.js";
@@ -167,10 +168,53 @@ export interface FieldChangeRebaser<TChangeset> {
 	replaceRevisions(change: TChangeset, replacer: RevisionReplacer): TChangeset;
 
 	/**
-	 * Returns a copy of the given changeset with the same declarations (e.g., new cells) but no actual changes.
-	 * This is a kludge. TODO: remove once AB#46104 is completed.
+	 * Returns a copy of the given changeset with edits removed as specified.
+	 * @param change - The change to filter edits from
+	 * @param filterDetach - This should be called for each range of detaches in the changeset,
+	 * and the detach should be preserved, removed, or converted to a non-move detach as specified.
+	 * If the returned result does not cover the entire detach range, the remainder should be queried again.
+	 * @param filterDetach - This should be called for each range of attaches in the changeset,
+	 * and the attach should be preserved, removed, or converted to a non-move attach as specified.
+	 * If the returned result does not cover the entire detach range, the remainder should be queried again.
+	 * @param preserveOtherEdits - Whether edits other than attaches and detaches (e.g. root renames),
+	 * should be preserved or removed.
 	 */
-	mute(change: TChangeset): TChangeset;
+	filterEdits(
+		change: TChangeset,
+		options: {
+			filterDetach: EditFilterFunc;
+			filterAttach: EditFilterFunc;
+			preserveOtherEdits: boolean;
+		},
+	): TChangeset;
+}
+
+export type EditFilterFunc = (
+	id: ChangeAtomId,
+	count: number,
+	endpoint?: ChangeAtomId,
+) => RangeQueryResult<EditFilterStatus>;
+
+/**
+ * Used to describe what should be done with a particular attach or detach during `filterEdits`.
+ */
+export enum EditFilterStatus {
+	/**
+	 * The edit should be removed from the filtered changeset.
+	 */
+	Remove,
+
+	/**
+	 * The edit should be preserved in the filtered changeset.
+	 */
+	Preserve,
+
+	/**
+	 * This should only be used for an attach or detach which is part of a move.
+	 * The edit should be preserved, but should be adjusted, if necessary,
+	 * to reflect that the other endpoint of the move has been filtered out.
+	 */
+	PreserveWithoutMove,
 }
 
 /**
@@ -181,13 +225,13 @@ export function referenceFreeFieldChangeRebaser<TChangeset>(data: {
 	compose: (change1: TChangeset, change2: TChangeset) => TChangeset;
 	invert: (change: TChangeset) => TChangeset;
 	rebase: (change: TChangeset, over: TChangeset) => TChangeset;
-	mute: (change: TChangeset) => TChangeset;
+	filterEdits: FieldChangeRebaser<TChangeset>["filterEdits"];
 }): FieldChangeRebaser<TChangeset> {
 	return isolatedFieldChangeRebaser({
 		compose: (change1, change2, _composeChild, _genId) => data.compose(change1, change2),
 		invert: (change, _invertChild, _genId) => data.invert(change),
 		rebase: (change, over, _rebaseChild, _genId) => data.rebase(change, over),
-		mute: (change) => data.mute(change),
+		filterEdits: (change, options) => data.filterEdits(change, options),
 	});
 }
 
@@ -195,7 +239,7 @@ export function isolatedFieldChangeRebaser<TChangeset>(data: {
 	compose: FieldChangeRebaser<TChangeset>["compose"];
 	invert: FieldChangeRebaser<TChangeset>["invert"];
 	rebase: FieldChangeRebaser<TChangeset>["rebase"];
-	mute: FieldChangeRebaser<TChangeset>["mute"];
+	filterEdits: FieldChangeRebaser<TChangeset>["filterEdits"];
 }): FieldChangeRebaser<TChangeset> {
 	return {
 		...data,

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

@@ -40,7 +40,7 @@ export const genericChangeHandler: FieldChangeHandler<GenericChangeset> = {
 		rebase: rebaseGenericChange,
 		prune: pruneGenericChange,
 		replaceRevisions,
-		mute: (change: GenericChangeset): GenericChangeset => change,
+		filterEdits: (change: GenericChangeset): GenericChangeset => change,
 	},
 	codecsFactory: makeGenericChangeCodec,
 	editor: {

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

@@ -29,10 +29,14 @@ export {
 export { EncodedModularChangesetV2 } from "./modularChangeFormatV2.js";
 export { FlexFieldKind, type FullSchemaPolicy } from "./fieldKind.js";
 export {
+	type EditFilterFunc,
+	EditFilterStatus,
 	type FieldChangeHandler,
 	type FieldChangeDelta,
+	type FieldChangeEncodingContext,
 	type FieldChangeRebaser,
 	type FieldEditor,
+	type NestedChangesIndices,
 	type NodeChangeComposer,
 	type NodeChangeInverter,
 	type NodeChangeRebaser,
@@ -42,8 +46,6 @@ export {
 	type RelevantRemovedRootsFromChild,
 	type ToDelta,
 	NodeAttachState,
-	type FieldChangeEncodingContext,
-	type NestedChangesIndices,
 } from "./fieldChangeHandler.js";
 export type {
 	CrossFieldKey,

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

@@ -82,6 +82,7 @@ import {
 	setInCrossFieldMap,
 } from "./crossFieldQueries.js";
 import {
+	EditFilterStatus,
 	type FieldChangeHandler,
 	NodeAttachState,
 	type RebaseRevisionMetadata,
@@ -1739,11 +1740,25 @@ export class ModularChangeFamily
 		const handler = getChangeHandler(this.fieldKinds, change.fieldKind);
 		return {
 			fieldKind: change.fieldKind,
-			change: brand(handler.rebaser.mute(change.change)),
+			change: brand(
+				handler.rebaser.filterEdits(change.change, {
+					filterDetach: removeAllEditsFilter,
+					filterAttach: removeAllEditsFilter,
+					preserveOtherEdits: false,
+				}),
+			),
 		};
 	}
 }
 
+function removeAllEditsFilter(
+	_id: ChangeAtomId,
+	count: number,
+	_endpointId?: ChangeAtomId,
+): RangeQueryResult<EditFilterStatus> {
+	return { value: EditFilterStatus.Remove, length: count };
+}
+
 function replaceCrossFieldKeyTableRevisions(
 	table: CrossFieldKeyTable,
 	replacer: RevisionReplacer,

package/src/feature-libraries/optional-field/optionalField.ts

@@ -35,6 +35,7 @@ import {
 	requiredIdentifier,
 } from "../fieldKindIdentifiers.js";
 import {
+	EditFilterStatus,
 	type FieldChangeHandler,
 	type FieldChangeRebaser,
 	type FieldEditor,
@@ -48,6 +49,7 @@ import {
 	type NestedChangesIndices,
 	type FieldChangeDelta,
 	FlexFieldKind,
+	type EditFilterFunc,
 } from "../modular-schema/index.js";
 
 import type {
@@ -466,9 +468,7 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 		return updated;
 	},
 
-	mute: (change: OptionalChangeset): OptionalChangeset => {
-		return { childChanges: change.childChanges, moves: [] };
-	},
+	filterEdits,
 };
 
 function replaceReplaceRevisions(
@@ -814,3 +814,43 @@ export const optional: Optional = new FlexFieldKind(
 		]),
 	},
 );
+
+function filterEdits(
+	change: OptionalChangeset,
+	options: {
+		filterDetach: EditFilterFunc;
+		filterAttach: EditFilterFunc;
+		preserveOtherEdits: boolean;
+	},
+): OptionalChangeset {
+	const filtered: Mutable<OptionalChangeset> = { ...change };
+	if (filtered.valueReplace !== undefined) {
+		if (isReplaceEffectful(filtered.valueReplace)) {
+			const detachId = getEffectfulDst(filtered.valueReplace);
+			const detachResult =
+				detachId === undefined ? undefined : options.filterDetach(detachId, 1).value;
+
+			const attachId = filtered.valueReplace.src;
+			const attachResult =
+				attachId === undefined ? undefined : options.filterAttach(attachId, 1).value;
+
+			if (detachResult === EditFilterStatus.Remove) {
+				assert(
+					attachId === undefined || attachResult === EditFilterStatus.Remove,
+					"Cannot remove detach without also removing attach",
+				);
+
+				delete filtered.valueReplace;
+			} else if (attachResult === EditFilterStatus.Remove) {
+				delete filtered.valueReplace.src;
+			}
+		} else if (!options.preserveOtherEdits) {
+			delete filtered.valueReplace;
+		}
+	}
+
+	if (!options.preserveOtherEdits) {
+		filtered.moves = [];
+	}
+	return filtered;
+}

package/src/feature-libraries/sequence-field/filterEdits.ts

@@ -0,0 +1,143 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ChangeAtomId } from "../../core/index.js";
+import type { RangeQueryResult } from "../../util/index.js";
+import { EditFilterStatus, type EditFilterFunc } from "../modular-schema/index.js";
+import { MarkListFactory } from "./markListFactory.js";
+import { NoopMarkType, type Changeset, type Mark } from "./types.js";
+import { getDetachedNodeId, getDetachOutputCellId, omitMarkEffect } from "./utils.js";
+import { MarkQueueBase } from "./markQueue.js";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
+
+export function filterEdits(
+	change: Changeset,
+	options: {
+		filterDetach: EditFilterFunc;
+		filterAttach: EditFilterFunc;
+		preserveOtherEdits: boolean;
+	},
+): Changeset {
+	const factory = new MarkListFactory();
+	const queue = new MarkQueueBase(change);
+	for (let mark = queue.peek(); mark !== undefined; mark = queue.peek()) {
+		const filtered = filterMark(
+			mark,
+			options.filterDetach,
+			options.filterAttach,
+			options.preserveOtherEdits,
+		);
+		factory.push(filtered);
+		queue.dequeueUpTo(filtered.count);
+	}
+
+	return factory.list;
+}
+
+function filterMark(
+	mark: Mark,
+	filterDetach: (
+		id: ChangeAtomId,
+		count: number,
+		endpoint?: ChangeAtomId,
+	) => RangeQueryResult<EditFilterStatus>,
+	filterAttach: (
+		id: ChangeAtomId,
+		count: number,
+		endpoint?: ChangeAtomId,
+	) => RangeQueryResult<EditFilterStatus>,
+	preserveOtherEdits: boolean,
+): Mark {
+	const type = mark.type;
+	switch (type) {
+		case "Insert":
+		case "MoveIn": {
+			if (mark.cellId === undefined) {
+				return preserveOtherEdits ? mark : omitMarkEffect(mark);
+			}
+
+			const endpoint = mark.type === "MoveIn" ? mark.finalEndpoint : undefined;
+			const result = filterAttach(mark.cellId, mark.count, endpoint);
+
+			let filtered: Mark;
+			switch (result.value) {
+				case EditFilterStatus.Preserve: {
+					filtered = mark;
+					break;
+				}
+				case EditFilterStatus.PreserveWithoutMove: {
+					// KLUDGE: PreserveWithoutMove requires us to return a mark which attaches the node
+					// using the detach ID of the move (the endpoint ID).
+					// Insert marks use the cell ID as the attach ID, so we must change the cell ID here.
+					// This could be a problem if there were references to the old cell ID outside this changeset,
+					// but PreserveWithoutMove is only used for transaction minimization, where that is not a problem.
+					const newCellId = endpoint ?? { revision: mark.revision, localId: mark.id };
+					filtered = {
+						type: "Insert",
+						count: result.length,
+						cellId: newCellId,
+						revision: mark.revision,
+						id: mark.id,
+					};
+					break;
+				}
+				case EditFilterStatus.Remove: {
+					filtered = omitMarkEffect(mark);
+					break;
+				}
+				default: {
+					unreachableCase(result.value);
+				}
+			}
+
+			return { ...filtered, count: result.length };
+		}
+		case "Remove":
+		case "MoveOut": {
+			const detachId = getDetachedNodeId(mark);
+			const endpoint = mark.type === "MoveOut" ? mark.finalEndpoint : undefined;
+			const result = filterDetach(detachId, mark.count, endpoint);
+
+			let filtered: Mark;
+			switch (result.value) {
+				case EditFilterStatus.Preserve: {
+					filtered = mark;
+					break;
+				}
+				case EditFilterStatus.PreserveWithoutMove: {
+					const outputCellId = getDetachOutputCellId(mark);
+					filtered = {
+						type: "Remove",
+						count: mark.count,
+						revision: outputCellId.revision,
+						id: outputCellId.localId,
+					};
+
+					if (mark.changes !== undefined) {
+						filtered.changes = mark.changes;
+					}
+
+					break;
+				}
+				case EditFilterStatus.Remove: {
+					filtered = omitMarkEffect(mark);
+					break;
+				}
+				default: {
+					unreachableCase(result.value);
+				}
+			}
+			return { ...filtered, count: result.length };
+		}
+		case NoopMarkType:
+		case "Rename":
+		case "AttachAndDetach": {
+			return preserveOtherEdits ? mark : omitMarkEffect(mark);
+		}
+		default: {
+			unreachableCase(type);
+		}
+	}
+}

package/src/feature-libraries/sequence-field/markQueue.ts

@@ -3,20 +3,17 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 
-import { type MoveEffectTable, splitMarkForMoveEffects } from "./moveEffectTable.js";
+import { getFirstMoveEffectLength, type MoveEffectTable } from "./moveEffectTable.js";
 import type { Mark } from "./types.js";
 import { splitMark } from "./utils.js";
 
-export class MarkQueue {
+export class MarkQueueBase {
 	private readonly stack: Mark[] = [];
 	private index = 0;
 
-	public constructor(
-		private readonly list: readonly Mark[],
-		private readonly moveEffects: MoveEffectTable,
-	) {
+	public constructor(private readonly list: readonly Mark[]) {
 		this.list = list;
 	}
 
@@ -36,11 +33,14 @@ export class MarkQueue {
 			return undefined;
 		}
 
-		const splitMarks = splitMarkForMoveEffects(mark, this.moveEffects);
-		for (let i = splitMarks.length - 1; i > 0; i--) {
-			this.stack.push(splitMarks[i] ?? oob());
+		const splitLength = this.getLengthForSplit(mark);
+		if (splitLength < mark.count) {
+			const [part1, part2] = splitMark(mark, splitLength);
+			this.stack.push(part2);
+			return part1;
 		}
-		return splitMarks[0];
+
+		return mark;
 	}
 
 	/**
@@ -66,4 +66,21 @@ export class MarkQueue {
 		}
 		return mark;
 	}
+
+	protected getLengthForSplit(mark: Mark): number {
+		return mark.count;
+	}
+}
+
+export class MarkQueue extends MarkQueueBase {
+	public constructor(
+		list: readonly Mark[],
+		private readonly moveEffects: MoveEffectTable,
+	) {
+		super(list);
+	}
+
+	protected override getLengthForSplit(mark: Mark): number {
+		return getFirstMoveEffectLength(mark, mark.count, this.moveEffects);
+	}
 }

package/src/feature-libraries/sequence-field/moveEffectTable.ts

@@ -15,7 +15,7 @@ import {
 
 import type { MoveMarkEffect } from "./helperTypes.js";
 import type { CellMark, Detach, Mark, MarkEffect, MoveId, MoveIn, MoveOut } from "./types.js";
-import { isAttachAndDetachEffect, splitMark, splitMarkEffect } from "./utils.js";
+import { isAttachAndDetachEffect, splitMarkEffect } from "./utils.js";
 
 export type MoveEffectTable = CrossFieldManager<MoveEffect>;
 
@@ -168,12 +168,7 @@ function adjustMoveEffectBasis(effect: MoveEffectWithBasis, newBasis: MoveId): M
 	return adjusted;
 }
 
-export function splitMarkForMoveEffects(mark: Mark, effects: MoveEffectTable): Mark[] {
-	const length = getFirstMoveEffectLength(mark, mark.count, effects);
-	return length < mark.count ? splitMark(mark, length) : [mark];
-}
-
-function getFirstMoveEffectLength(
+export function getFirstMoveEffectLength(
 	markEffect: MarkEffect,
 	count: number,
 	effects: MoveEffectTable,

package/src/feature-libraries/sequence-field/sequenceFieldChangeRebaser.ts

@@ -6,12 +6,12 @@
 import type { FieldChangeRebaser } from "../modular-schema/index.js";
 
 import { compose } from "./compose.js";
+import { filterEdits } from "./filterEdits.js";
 import { invert } from "./invert.js";
 import { prune } from "./prune.js";
 import { rebase } from "./rebase.js";
 import { replaceRevisions } from "./replaceRevisions.js";
 import type { Changeset } from "./types.js";
-import { omitMarkEffect } from "./utils.js";
 
 export type SequenceChangeRebaser = FieldChangeRebaser<Changeset>;
 
@@ -21,7 +21,5 @@ export const sequenceFieldChangeRebaser = {
 	rebase,
 	prune,
 	replaceRevisions,
-	mute: (change: Changeset): Changeset => {
-		return change.map((mark) => omitMarkEffect(mark));
-	},
-};
+	filterEdits,
+} as const;

package/src/index.ts

@@ -99,6 +99,7 @@ export {
 	type TreeNodeSchema,
 	TreeViewConfiguration,
 	type ITreeViewConfiguration,
+	type ITreeViewConfigurationAlpha,
 	type ITreeConfigurationOptions,
 	type TreeView,
 	type TreeViewEvents,
@@ -334,6 +335,8 @@ export {
 	type ErasedNode,
 	type ErasedSchemaSubclassable,
 	type SnapshotSchemaCompatibilityOptions,
+	StagedSchemaUpgradePolicy,
+	type StagedSchemaUpgradePolicyFactory,
 	type ArrayPlaceAnchor,
 	createArrayInsertionAnchor,
 	type WithValue,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.112.0";
+export const pkgVersion = "2.113.0-411909";

package/src/shared-tree/schematizingTreeView.ts

@@ -23,6 +23,7 @@ import {
 	type FlexTreeUnknownUnboxed,
 	FieldKinds,
 	type FlexTreeRequiredField,
+	allowsRepoSuperset,
 } from "../feature-libraries/index.js";
 import {
 	type ImplicitFieldSchema,
@@ -34,6 +35,7 @@ import {
 	normalizeFieldSchema,
 	checkSchemaCompatibility,
 	type InsertableContent,
+	type StagedSchemaUpgradePolicy,
 	type TreeViewConfiguration,
 	type TreeViewAlpha,
 	type InsertableField,
@@ -99,7 +101,14 @@ export class SchematizingSimpleTreeView<
 		IEmitter<TreeViewEvents & TreeBranchEvents> &
 		HasListeners<TreeViewEvents & TreeBranchEvents> = createEmitter();
 
+	/**
+	 * The schema for this view, captured at construction time for compatibility checking.
+	 */
 	private readonly viewSchema: TreeSchema;
+	/**
+	 * Stored-schema generation policy from the view configuration, frozen at construction time.
+	 */
+	private readonly stagedUpgradePolicy: StagedSchemaUpgradePolicy;
 
 	/**
 	 * Events to unregister upon flex-tree view disposal.
@@ -142,8 +151,17 @@ export class SchematizingSimpleTreeView<
 
 		this.rootFieldSchema = normalizeFieldSchema(config.schema);
 
-		const configAlpha = new TreeViewConfigurationAlpha({ schema: config.schema });
+		const stagedUpgradePolicy =
+			config instanceof TreeViewConfigurationAlpha ? config.stagedUpgradePolicy : undefined;
+		const configAlpha = new TreeViewConfigurationAlpha({
+			schema: config.schema,
+			enableSchemaValidation: config.enableSchemaValidation,
+			preventAmbiguity: config.preventAmbiguity,
+			stagedUpgradePolicy,
+		});
+		this.stagedUpgradePolicy = configAlpha.stagedUpgradePolicy;
 
+		// Store viewSchema directly from the configuration (TreeViewConfigurationAlpha implements TreeSchema)
 		this.viewSchema = configAlpha;
 		// This must be initialized before `update` can be called.
 		this.currentCompatibility = {
@@ -189,7 +207,7 @@ export class SchematizingSimpleTreeView<
 		}
 
 		this.runSchemaEdit(() => {
-			const schema = toInitialSchema(this.config.schema);
+			const schema = toInitialSchema(this.config.schema, this.stagedUpgradePolicy);
 			// This has to be the contextless version, since when "initialize" is called (right after this),
 			// it will do a schema change which would dispose of the current context (see inside `update`).
 			// Thus using the current context (if any) would hydrate nodes then
@@ -247,19 +265,18 @@ export class SchematizingSimpleTreeView<
 	public upgradeSchema(): void {
 		this.ensureUndisposed();
 
-		const compatibility = this.compatibility;
-		if (compatibility.isEquivalent) {
-			// No-op
-			return;
-		}
-
-		if (!compatibility.canUpgrade) {
+		const newSchema = toUpgradeSchema(this.viewSchema.root, this.stagedUpgradePolicy);
+		const storedSchema = this.checkout.storedSchema.clone();
+		if (!allowsRepoSuperset(defaultSchemaPolicy, storedSchema, newSchema)) {
 			throw new UsageError(
-				"Existing stored schema cannot be upgraded (see TreeView.compatibility.canUpgrade).",
+				"Existing stored schema cannot be upgraded to the requested schema (see TreeView.compatibility.canUpgrade).",
 			);
 		}
+		if (allowsRepoSuperset(defaultSchemaPolicy, newSchema, storedSchema)) {
+			// No-op
+			return;
+		}
 
-		const newSchema = toUpgradeSchema(this.viewSchema.root);
 		this.runSchemaEdit(() => this.checkout.updateSchema(newSchema));
 	}
 
@@ -348,15 +365,8 @@ export class SchematizingSimpleTreeView<
 	private update(): void {
 		this.disposeFlexView();
 
-		const compatibility = checkSchemaCompatibility(
-			this.viewSchema,
-			this.checkout.storedSchema,
-		);
-
-		this.currentCompatibility = {
-			...compatibility,
-			canInitialize: canInitialize(this.checkout),
-		};
+		const compatibility = this.computeCompatibility();
+		this.currentCompatibility = compatibility;
 
 		const anchors = this.checkout.forest.anchors;
 		const slots = anchors.slots;
@@ -427,6 +437,18 @@ export class SchematizingSimpleTreeView<
 		}
 	}
 
+	private computeCompatibility(): SchemaCompatibilityStatus {
+		const compatibility = checkSchemaCompatibility(
+			this.viewSchema,
+			this.checkout.storedSchema,
+			this.stagedUpgradePolicy,
+		);
+		return {
+			...compatibility,
+			canInitialize: canInitialize(this.checkout),
+		};
+	}
+
 	private runSchemaEdit(edit: () => void): void {
 		this.midUpgrade = true;
 		try {