@fluidframework/tree 2.113.0-411909 → 2.114.0

package/src/core/change-family/changeFamily.ts

@@ -10,14 +10,31 @@ import type { SchemaAndPolicy } from "../../core/index.js";
 import type { IdentifierHealingConfig, JsonCompatibleReadOnly } from "../../util/index.js";
 import type { ChangeRebaser, RevisionTag, TaggedChange } from "../rebase/index.js";
 
-export interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {
+export type ProcessChangeFn<TChange, TChangeProcessingContext> =
+	TChangeProcessingContext extends never
+		? (change: TChange) => TChange
+		: (change: TChange, context: TChangeProcessingContext) => TChange;
+
+export interface ChangeFamily<
+	TEditor extends ChangeFamilyEditor,
+	TChange,
+	// For simplicity, may be a concrete ChangeFamily implementation such as
+	// ChangeFamilyFoo implements ChangeFamily<EditorFoo, ChangeFoo, ChangeFamilyFoo>
+	// to provide all details and helpers that processFn for ChangeFoo
+	// may require, but there is no requirement to follow that pattern.
+	TChangeProcessingContext = never,
+> {
 	buildEditor(
 		mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<TChange>) => void,
 	): TEditor;
 
 	readonly rebaser: ChangeRebaser<TChange>;
-	readonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;
+	readonly codecs: ICodecFamily<TChange, ChangeEncodingContext, ChangeDecodingContext>;
+
+	buildProcessor(
+		processFn: ProcessChangeFn<TChange, TChangeProcessingContext>,
+	): (change: TChange) => TChange;
 }
 
 export interface ChangeEncodingContext {
@@ -36,18 +53,29 @@ export interface ChangeEncodingContext {
 	 * (possibly broken) attach-summary blob, never when applying ops.
 	 */
 	readonly isSummary: boolean;
+}
+
+/**
+ * Context provided to change codecs when decoding.
+ * @remarks
+ * The same as {@link ChangeEncodingContext} except that it omits `schema` (only consulted when
+ * *encoding*, for schema-aware compression) and adds `healing` (only consulted when *decoding*, to
+ * recover unresolvable identifiers from a summary blob).
+ */
+export type ChangeDecodingContext = Omit<ChangeEncodingContext, "schema"> & {
 	/**
 	 * Heal-on-decode workaround configuration. See {@link IdentifierHealingConfig}.
 	 * Only takes effect when `isSummary` is also `true`.
 	 */
 	readonly healing?: IdentifierHealingConfig;
-}
+};
 
 export type ChangeFamilyCodec<TChange> = IJsonCodec<
 	TChange,
 	JsonCompatibleReadOnly,
 	JsonCompatibleReadOnly,
-	ChangeEncodingContext
+	ChangeEncodingContext,
+	ChangeDecodingContext
 >;
 
 export interface ChangeFamilyEditor {

package/src/core/change-family/editBuilder.ts

@@ -5,11 +5,10 @@
 
 import type { TaggedChange } from "../rebase/index.js";
 
-import type { ChangeFamily, ChangeFamilyEditor } from "./changeFamily.js";
+import type { ChangeFamilyEditor } from "./changeFamily.js";
 
 export abstract class EditBuilder<TChange> implements ChangeFamilyEditor {
 	public constructor(
-		protected readonly changeFamily: ChangeFamily<ChangeFamilyEditor, TChange>,
 		private readonly changeReceiver: (change: TaggedChange<TChange>) => void,
 	) {}
 

package/src/core/change-family/index.ts

@@ -7,6 +7,8 @@ export type {
 	ChangeFamily,
 	ChangeFamilyEditor,
 	ChangeEncodingContext,
+	ChangeDecodingContext,
 	ChangeFamilyCodec,
+	ProcessChangeFn,
 } from "./changeFamily.js";
 export { EditBuilder } from "./editBuilder.js";

package/src/core/index.ts

@@ -83,6 +83,7 @@ export {
 	CursorMarker,
 	isCursor,
 	DetachedFieldIndex,
+	type DetachedFieldSummaryData,
 	type ReadOnlyDetachedFieldIndex,
 	type DetachedFieldIndexCheckpoint,
 	type ForestRootId,
@@ -160,13 +161,15 @@ export {
 	SchemaFormatVersion,
 } from "./schema-stored/index.js";
 
-export {
-	type ChangeFamily,
-	type ChangeFamilyCodec,
-	type ChangeEncodingContext,
-	type ChangeFamilyEditor,
-	EditBuilder,
+export type {
+	ChangeFamily,
+	ChangeFamilyCodec,
+	ChangeEncodingContext,
+	ChangeDecodingContext,
+	ChangeFamilyEditor,
+	ProcessChangeFn,
 } from "./change-family/index.js";
+export { EditBuilder } from "./change-family/index.js";
 
 export {
 	areEqualChangeAtomIds,

package/src/core/tree/delta.ts

@@ -67,7 +67,7 @@ import type { TreeChunk } from "./chunk.js";
  */
 
 /**
- * Represents the change made to a document.
+ * A change made to a document.
  * Immutable, therefore safe to retain for async processing.
  */
 export interface Root<TTrees = ProtoNodes> {
@@ -122,20 +122,50 @@ export interface Root<TTrees = ProtoNodes> {
 export type ProtoNodes = TreeChunk;
 
 /**
- * Represents a change being made to a part of the document tree.
+ * A change to a contiguous range of a field,
+ * including nested changes described by {@link Mark.fields}.
+ *
+ * @remarks
+ * See {@link FieldChanges} for how these marks are applied to a field.
+ *
+ * The presence of {@link Mark.attach} and {@link Mark.detach} determines the kind of change:
+ *
+ * - Retain (neither `attach` nor `detach` are set): retains `count` existing nodes.
+ * When `count` is `1`, `fields` may describe nested changes to the retained node.
+ * - Detach (`detach` only): removes `count` existing nodes.
+ * When `count` is `1`, `fields` may describe nested changes to the detached node.
+ * - Attach (`attach` only): inserts `count` new nodes.
+ * `fields` must be undefined.
+ * - Replace (both `attach` and `detach`): replaces `count` existing nodes with `count` attached
+ * nodes.
+ * When `count` is `1`, `fields` may describe nested changes to the detached node.
  */
 export interface Mark {
 	/**
-	 * The number of nodes affected.
-	 * When `isAttachMark(mark)` is true, this is the number of new nodes being attached.
-	 * When `isAttachMark(mark)` is false, this the number of existing nodes affected.
-	 * Must be 1 when `fields` is populated.
+	 * The number of existing nodes affected, attached nodes added, or both, according to the
+	 * combination of {@link Mark.attach} and {@link Mark.detach}.
+	 * Must be `1` when {@link Mark.fields} is populated.
+	 * @remarks
+	 * The size of the attached content is never inferred from what is attached: it must be exactly `count`.
+	 * This means that a single mark can represent replacing a run of `count` nodes with `count` new nodes,
+	 * but cannot replace a run of one length with a run of another length.
+	 * Such edits require multiple marks.
+	 *
+	 * Must be a positive integer.
+	 * Marks with a count of `0` are no-ops and should be omitted from {@link FieldChanges}.
 	 */
 	readonly count: number;
 
 	/**
-	 * Modifications to the pre-existing content.
-	 * Must be undefined when `attach` is set but `detach` is not.
+	 * Nested changes to pre-existing content.
+	 * @remarks
+	 * If {@link Mark.detach} is set, these changes apply to the node being detached.
+	 * Otherwise, they apply to the retained node.
+	 *
+	 * May only be set when this mark applies to exactly one pre-existing node.
+	 * Therefore, `fields` must be undefined if:
+	 * - {@link Mark.attach} is set and {@link Mark.detach} is not: in this case there are no pre-existing nodes.
+	 * - {@link Mark.count} is not 1: in this case there is not exactly one node to modify.
 	 */
 	readonly fields?: FieldMap;
 
@@ -154,54 +184,70 @@ export interface Mark {
  * A globally unique ID for a node in a detached field.
  */
 export interface DetachedNodeId {
+	/** Revision in which the ID was allocated, if applicable. */
 	readonly major?: RevisionTag;
+	/** Identifier within the scope of {@link DetachedNodeId.major}. */
 	readonly minor: number;
 }
 
 export type FieldMap = ReadonlyMap<FieldKey, FieldChanges>;
 
 /**
- * Represents changes made to a detached node
+ * Changes made to a detached node.
  */
 export interface DetachedNodeChanges {
+	/** ID of the detached node to modify. */
 	readonly id: DetachedNodeId;
+	/** Changes to the node's fields. */
 	readonly fields: FieldMap;
 }
 
 /**
- * Represents the creation of detached nodes.
+ * The creation of detached nodes.
  *
  * Tree creation is idempotent: if a tree with the same ID already exists,
  * then this build is ignored in favor of the existing tree.
  */
 export interface DetachedNodeBuild<TTrees = ProtoNodes> {
+	/** ID assigned to the first node in {@link DetachedNodeBuild.trees}. */
 	readonly id: DetachedNodeId;
+	/** Nodes to create, assigned consecutive IDs by incrementing {@link DetachedNodeId.minor}. */
 	readonly trees: TTrees;
 }
 
 /**
- * Represents the destruction of detached nodes
+ * The destruction of detached nodes.
  */
 export interface DetachedNodeDestruction {
+	/** ID of the first detached node to destroy. */
 	readonly id: DetachedNodeId;
+	/** Number of consecutively identified nodes to destroy. */
 	readonly count: number;
 }
 
 /**
- * Represents a detached node being assigned a new `DetachedNodeId`.
+ * A detached node being assigned a new `DetachedNodeId`.
  */
 export interface DetachedNodeRename {
+	/** Number of consecutively identified nodes to rename. */
 	readonly count: number;
+	/** Current ID of the first node. */
 	readonly oldId: DetachedNodeId;
+	/** New ID for the first node. */
 	readonly newId: DetachedNodeId;
 }
 
 export interface FieldChanges {
 	/**
-	 * Represents a list of changes to the nodes in the field.
-	 * The index of each mark within the range of nodes, before
-	 * applying any of the changes, is not represented explicitly.
-	 * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.
+	 * A list of changes to the nodes in the field.
+	 * @remarks
+	 * This includes changes to the field's nodes and nested changes to those nodes' fields.
+	 *
+	 * The index at which each mark applies is implicit. Marks are applied in order, advancing the
+	 * index according to the kind of {@link Mark} and its {@link Mark.count}.
+	 *
+	 * Because this describes changes rather than content, untouched nodes after the final mark are
+	 * implicitly retained. This is equivalent to a trailing retain mark with the relevant count.
 	 */
 	readonly marks: readonly Mark[];
 }

package/src/core/tree/detachedFieldIndex.ts

@@ -4,17 +4,8 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
-
-import {
-	type CodecWriteOptions,
-	FluidClientVersion,
-	FormatValidatorNoOp,
-	type IJsonCodec,
-} from "../../codec/index.js";
 import {
 	type IdAllocator,
-	type JsonCompatibleReadOnly,
 	type NestedMap,
 	brand,
 	deleteFromNestedMap,
@@ -24,11 +15,10 @@ import {
 	setInNestedMap,
 	tryGetFromNestedMap,
 } from "../../util/index.js";
-import type { RevisionTag, RevisionTagCodec } from "../rebase/index.js";
+import type { RevisionTag } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type * as Delta from "./delta.js";
-import { detachedFieldIndexCodecBuilder } from "./detachedFieldIndexCodecs.js";
 import type {
 	DetachedField,
 	DetachedFieldSummaryData,
@@ -92,9 +82,6 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		Delta.DetachedNodeId
 	> = new Map();
 
-	private readonly codec: IJsonCodec<DetachedFieldSummaryData>;
-	private readonly options: CodecWriteOptions;
-
 	/**
 	 * The process for loading `DetachedFieldIndex` data from a summary is split into two steps:
 	 * 1. Call {@link loadData}
@@ -112,28 +99,12 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 	public constructor(
 		private readonly name: string,
 		private rootIdAllocator: IdAllocator<ForestRootId>,
-		private readonly revisionTagCodec: RevisionTagCodec,
-		private readonly idCompressor: IIdCompressor,
-		options?: CodecWriteOptions,
-	) {
-		this.options = options ?? {
-			jsonValidator: FormatValidatorNoOp,
-			minVersionForCollab: FluidClientVersion.v2_0,
-		};
-		this.codec = detachedFieldIndexCodecBuilder.build({
-			...this.options,
-			revisionTagCodec,
-			idCompressor,
-		});
-	}
+	) {}
 
 	public clone(): DetachedFieldIndex {
 		const clone = new DetachedFieldIndex(
 			this.name,
 			idAllocatorFromMaxId(this.rootIdAllocator.getMaxId()) as IdAllocator<ForestRootId>,
-			this.revisionTagCodec,
-			this.idCompressor,
-			this.options,
 		);
 		populateNestedMap(this.detachedNodeToField, clone.detachedNodeToField, true);
 		populateNestedMap(
@@ -307,19 +278,17 @@ export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 		});
 	}
 
-	public encode(): JsonCompatibleReadOnly {
-		return this.codec.encode({
+	public getSummaryData(): DetachedFieldSummaryData {
+		return {
 			data: this.detachedNodeToField,
 			maxId: this.rootIdAllocator.getMaxId(),
-		});
+		};
 	}
 
 	/**
-	 * Loads the tree index from the given string, this overrides any existing data.
+	 * Loads the tree index from summary data, this overrides any existing data.
 	 */
-	public loadData(data: JsonCompatibleReadOnly): void {
-		const detachedFieldIndex: DetachedFieldSummaryData = this.codec.decode(data);
-
+	public loadData(detachedFieldIndex: DetachedFieldSummaryData): void {
 		this.rootIdAllocator = idAllocatorFromMaxId(
 			detachedFieldIndex.maxId,
 		) as IdAllocator<ForestRootId>;

package/src/core/tree/index.ts

@@ -127,6 +127,8 @@ export {
 	type ReadOnlyDetachedFieldIndex,
 } from "./detachedFieldIndex.js";
 
+export { type DetachedFieldSummaryData } from "./detachedFieldIndexTypes.js";
+
 export { detachedFieldIndexCodecBuilder } from "./detachedFieldIndexCodecs.js";
 export { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
 export { type FormatV1 } from "./detachedFieldIndexFormatV1.js";

package/src/core/tree/visitorUtils.ts

@@ -3,11 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import type { IIdCompressor } from "@fluidframework/id-compressor";
-
-import type { CodecWriteOptions } from "../../codec/index.js";
 import { type IdAllocator, idAllocatorFromMaxId } from "../../util/index.js";
-import type { RevisionTag, RevisionTagCodec } from "../rebase/index.js";
+import type { RevisionTag } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type { ITreeCursorSynchronous } from "./cursor.js";
@@ -17,19 +14,8 @@ import type { ForestRootId } from "./detachedFieldIndexTypes.js";
 import type { PlaceIndex, Range } from "./pathTree.js";
 import { type DeltaVisitor, visitDelta } from "./visitDelta.js";
 
-export function makeDetachedFieldIndex(
-	prefix: string = "Temp",
-	revisionTagCodec: RevisionTagCodec,
-	idCompressor: IIdCompressor,
-	options?: CodecWriteOptions,
-): DetachedFieldIndex {
-	return new DetachedFieldIndex(
-		prefix,
-		idAllocatorFromMaxId() as IdAllocator<ForestRootId>,
-		revisionTagCodec,
-		idCompressor,
-		options,
-	);
+export function makeDetachedFieldIndex(prefix: string = "Temp"): DetachedFieldIndex {
+	return new DetachedFieldIndex(prefix, idAllocatorFromMaxId() as IdAllocator<ForestRootId>);
 }
 
 export function applyDelta(

package/src/entrypoints/alpha.ts

@@ -256,8 +256,9 @@ export {
 	SchemaFactoryAlpha, 
 	SchemaStaticsAlpha, 
 	SchemaType, 
-	SharedTreeFormatOptions, 
-	SharedTreeOptions, 
+	SharedTreeAlpha,
+	SharedTreeFormatOptions,
+	SharedTreeOptions,
 	SimpleAllowedTypeAttributes, 
 	SimpleArrayNodeSchema, 
 	SimpleFieldSchema, 
@@ -283,6 +284,7 @@ export {
 	TreeChangeEventsAlpha, 
 	TreeCompressionStrategy, 
 	TreeContextAlpha, 
+	TreeDataStoreOptions, 
 	TreeIdentifierUtils, 
 	TreeMapNodeAlpha, 
 	TreeParsingOptions, 
@@ -321,12 +323,14 @@ export {
 	incrementalSummaryHint, 
 	independentInitializedView, 
 	independentView, 
+	instantiateTreeFirstTime, 
 	minimize, 
 	normalizeAllowedTypes, 
 	persistedToSimpleSchema, 
 	replaceConciseTreeHandles, 
 	replaceHandles, 
 	replaceVerboseTreeHandles, 
-	trackDirtyNodes
+	trackDirtyNodes, 
+	defineTreeDataStore
 	// #endregion
 } from "../index.js";

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

@@ -191,6 +191,17 @@ export class TreeShape {
 	}
 
 	public equals(other: TreeShape): boolean {
+		// Shapes are commonly shared (e.g. all chunks from one chunker reference the same instance), so
+		// short-circuit on reference identity to avoid the full structural walk in the common case.
+		if (this === other) {
+			return true;
+		}
+
+		// A given type usually only has one shape, so check it next to speed up the false case.
+		if (this.type !== other.type) {
+			return false;
+		}
+
 		// TODO: either dedupe instances and/or store a collision resistant hash for fast compare.
 
 		if (
@@ -203,7 +214,6 @@ export class TreeShape {
 			return false;
 		}
 		return (
-			this.type === other.type &&
 			this.hasValue === other.hasValue &&
 			this.mayContainCompressedIds === other.mayContainCompressedIds
 		);

package/src/feature-libraries/comparison-forest/comparisonForest.ts

@@ -0,0 +1,140 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { Listenable } from "@fluidframework/core-interfaces";
+
+import {
+	type Anchor,
+	type AnchorSet,
+	type AnnouncedVisitor,
+	type DeltaVisitor,
+	type FieldAnchor,
+	type ForestEvents,
+	type IEditableForest,
+	type ITreeCursorSynchronous,
+	type ITreeSubscriptionCursor,
+	type TreeChunk,
+	type TreeNavigationResult,
+	type TreeStoredSchemaSubscription,
+	type UpPath,
+	combineVisitors,
+	createAnnouncedVisitor,
+} from "../../core/index.js";
+import type { Breakable } from "../../util/index.js";
+
+import { assertForestsEqual } from "../treeTextCursor.js";
+
+/**
+ * An {@link IEditableForest} which wraps two other forests: a `main` forest and a `reference` forest.
+ *
+ * @remarks
+ * All read operations are delegated to `main`, so from the outside a `ComparisonForest` behaves exactly like its `main` forest.
+ *
+ * When a delta is applied (via {@link IEditableForest.acquireVisitor}), the delta is applied to both `main` and `reference`.
+ * Once the visitor is freed, the full contents of both forests (including all detached/removed fields) are compared,
+ * and an error is thrown if they differ.
+ *
+ * This is a testing/debugging aid: it allows validating that a forest implementation (for example the optimized `ChunkedForest`)
+ * produces the same results as a simpler reference implementation (for example the `ObjectForest`) for every delta that is applied.
+ *
+ * @privateRemarks
+ * This forest is intentionally expensive: it maintains two full copies of the data and re-reads and
+ * structurally compares all of their contents after every delta.
+ */
+export class ComparisonForest implements IEditableForest {
+	/**
+	 * @param main - The forest whose behavior is under test.
+	 * All reads are delegated to this forest, and it is the source of truth for anchors and events.
+	 * @param reference - The forest to compare against.
+	 * This forest receives all the same deltas as `main`, and its contents are asserted to match `main` after each delta.
+	 */
+	public constructor(
+		public readonly main: IEditableForest,
+		public readonly reference: IEditableForest,
+	) {
+		this.assertValid();
+	}
+
+	private assertValid(): void {
+		assertForestsEqual(this.main, this.reference);
+	}
+
+	public get events(): Listenable<ForestEvents> {
+		return this.main.events;
+	}
+
+	public get anchors(): AnchorSet {
+		return this.main.anchors;
+	}
+
+	public get isEmpty(): boolean {
+		return this.main.isEmpty;
+	}
+
+	public clone(schema: TreeStoredSchemaSubscription, breaker?: Breakable): ComparisonForest {
+		this.assertValid();
+		return new ComparisonForest(
+			this.main.clone(schema, breaker),
+			this.reference.clone(schema, breaker),
+		);
+	}
+
+	public chunkField(cursor: ITreeCursorSynchronous): TreeChunk[] {
+		return this.main.chunkField(cursor);
+	}
+
+	public allocateCursor(source?: string): ITreeSubscriptionCursor {
+		// Currently we just use the cursor from "main", but we could use "reference" or a custom cursor ensuring both match in behavior.
+		// TODO: Add a custom combined cursor type which validates two cursors match, and use it here.
+		return this.main.allocateCursor(source);
+	}
+
+	public forgetAnchor(anchor: Anchor): void {
+		this.main.forgetAnchor(anchor);
+	}
+
+	public tryMoveCursorToNode(
+		destination: Anchor,
+		cursorToMove: ITreeSubscriptionCursor,
+	): TreeNavigationResult {
+		return this.main.tryMoveCursorToNode(destination, cursorToMove);
+	}
+
+	public tryMoveCursorToField(
+		destination: FieldAnchor,
+		cursorToMove: ITreeSubscriptionCursor,
+	): TreeNavigationResult {
+		return this.main.tryMoveCursorToField(destination, cursorToMove);
+	}
+
+	public moveCursorToPath(destination: UpPath, cursorToMove: ITreeSubscriptionCursor): void {
+		this.main.moveCursorToPath(destination, cursorToMove);
+	}
+
+	public getCursorAboveDetachedFields(): ITreeCursorSynchronous {
+		return this.main.getCursorAboveDetachedFields();
+	}
+
+	public registerAnnouncedVisitor(visitor: () => AnnouncedVisitor): void {
+		this.main.registerAnnouncedVisitor(visitor);
+	}
+
+	public deregisterAnnouncedVisitor(visitor: () => AnnouncedVisitor): void {
+		this.main.deregisterAnnouncedVisitor(visitor);
+	}
+
+	public acquireVisitor(): DeltaVisitor {
+		this.assertValid();
+		const main = this.main;
+		const reference = this.reference;
+		const mainVisitor = main.acquireVisitor();
+		const referenceVisitor = reference.acquireVisitor();
+		// A visitor which does nothing except assert the two forests match once the delta has been fully applied to both.
+		const comparisonVisitor = createAnnouncedVisitor({
+			free: () => this.assertValid(),
+		});
+		return combineVisitors([mainVisitor, referenceVisitor, comparisonVisitor]);
+	}
+}

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

@@ -0,0 +1,6 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { ComparisonForest } from "./comparisonForest.js";