@fluidframework/tree 2.118.1 → 3.0.1

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

@@ -3,20 +3,27 @@
  * 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 {
+	EditFilterStatus,
+	type FilterAttachFunc,
+	type FilterDetachFunc,
+} 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 {
+	getDetachedNodeId,
+	getDetachOutputCellId,
+	getOutputCellId,
+	omitMarkEffect,
+} from "./utils.js";
 import { MarkQueueBase } from "./markQueue.js";
-import { unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 
 export function filterEdits(
 	change: Changeset,
 	options: {
-		filterDetach: EditFilterFunc;
-		filterAttach: EditFilterFunc;
+		filterDetach: FilterDetachFunc;
+		filterAttach: FilterAttachFunc;
 		preserveOtherEdits: boolean;
 	},
 ): Changeset {
@@ -38,16 +45,8 @@ export function filterEdits(
 
 function filterMark(
 	mark: Mark,
-	filterDetach: (
-		id: ChangeAtomId,
-		count: number,
-		endpoint?: ChangeAtomId,
-	) => RangeQueryResult<EditFilterStatus>,
-	filterAttach: (
-		id: ChangeAtomId,
-		count: number,
-		endpoint?: ChangeAtomId,
-	) => RangeQueryResult<EditFilterStatus>,
+	filterDetach: FilterDetachFunc,
+	filterAttach: FilterAttachFunc,
 	preserveOtherEdits: boolean,
 ): Mark {
 	const type = mark.type;
@@ -58,11 +57,14 @@ function filterMark(
 				return preserveOtherEdits ? mark : omitMarkEffect(mark);
 			}
 
+			const attachId =
+				mark.type === "MoveIn" ? { revision: mark.revision, localId: mark.id } : mark.cellId;
+
 			const endpoint = mark.type === "MoveIn" ? mark.finalEndpoint : undefined;
-			const result = filterAttach(mark.cellId, mark.count, endpoint);
+			const result = filterAttach(attachId, mark.count, undefined, endpoint);
 
 			let filtered: Mark;
-			switch (result.value) {
+			switch (result.value.action) {
 				case EditFilterStatus.Preserve: {
 					filtered = mark;
 					break;
@@ -73,7 +75,11 @@ function filterMark(
 					// 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 };
+					const newCellId = result.value.newAttachId ??
+						endpoint ?? {
+							revision: mark.revision,
+							localId: mark.id,
+						};
 					filtered = {
 						type: "Insert",
 						count: result.length,
@@ -81,6 +87,11 @@ function filterMark(
 						revision: mark.revision,
 						id: mark.id,
 					};
+
+					if (result.value.nodeId !== undefined) {
+						filtered.changes = result.value.nodeId;
+					}
+
 					break;
 				}
 				case EditFilterStatus.Remove: {
@@ -88,7 +99,7 @@ function filterMark(
 					break;
 				}
 				default: {
-					unreachableCase(result.value);
+					unreachableCase(result.value.action);
 				}
 			}
 
@@ -98,10 +109,10 @@ function filterMark(
 		case "MoveOut": {
 			const detachId = getDetachedNodeId(mark);
 			const endpoint = mark.type === "MoveOut" ? mark.finalEndpoint : undefined;
-			const result = filterDetach(detachId, mark.count, endpoint);
+			const result = filterDetach(detachId, mark.count, mark.cellId, endpoint);
 
 			let filtered: Mark;
-			switch (result.value) {
+			switch (result.value.action) {
 				case EditFilterStatus.Preserve: {
 					filtered = mark;
 					break;
@@ -123,17 +134,42 @@ function filterMark(
 				}
 				case EditFilterStatus.Remove: {
 					filtered = omitMarkEffect(mark);
+					if (result.value.shouldRemoveChild === true) {
+						delete filtered.changes;
+					}
+
 					break;
 				}
 				default: {
-					unreachableCase(result.value);
+					unreachableCase(result.value.action);
 				}
 			}
 			return { ...filtered, count: result.length };
 		}
-		case NoopMarkType:
-		case "Rename":
 		case "AttachAndDetach": {
+			assert(
+				mark.attach.type === "MoveIn",
+				0xd3c /* AttachAndDetach marks in changesets should always represent MoveIn + Remove */,
+			);
+
+			if (mark.cellId === undefined) {
+				return preserveOtherEdits ? mark : omitMarkEffect(mark);
+			}
+
+			const result = filterAttach(
+				{ revision: mark.attach.revision, localId: mark.attach.id },
+				mark.count,
+				getOutputCellId(mark),
+				mark.attach.finalEndpoint,
+			);
+
+			const filtered =
+				result.value.action === EditFilterStatus.Preserve ? mark : omitMarkEffect(mark);
+
+			return { ...filtered, count: result.length };
+		}
+		case NoopMarkType:
+		case "Rename": {
 			return preserveOtherEdits ? mark : omitMarkEffect(mark);
 		}
 		default: {

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

@@ -19,7 +19,7 @@ import {
 	CrossFieldTarget,
 	type NodeId,
 	type CrossFieldKeyRange,
-	type NestedChangesIndices,
+	type ChildChangeInfo,
 } from "../modular-schema/index.js";
 
 import type {
@@ -62,25 +62,13 @@ export function createEmpty(): Changeset {
 	return [];
 }
 
-export function getNestedChanges(change: Changeset): NestedChangesIndices {
-	const output: NestedChangesIndices = [];
-	let inputIndex = 0;
-	let outputIndex = 0;
-	for (const mark of change) {
-		const { changes, count } = mark;
-		if (changes !== undefined) {
-			output.push([
-				changes,
-				areInputCellsEmpty(mark) ? undefined : inputIndex /* inputIndex */,
-				areOutputCellsEmpty(mark) ? undefined : outputIndex /* outputIndex */,
-			]);
-		}
-		if (!areInputCellsEmpty(mark)) {
-			inputIndex += count;
-		}
+export function getNestedChanges(change: Changeset): ChildChangeInfo[] {
+	const output: ChildChangeInfo[] = [];
 
-		if (!areOutputCellsEmpty(mark)) {
-			outputIndex += count;
+	for (const mark of change) {
+		if (mark.changes !== undefined) {
+			const detachId = isDetach(mark) ? getDetachedNodeId(mark) : undefined;
+			output.push({ nodeId: mark.changes, inputRootId: mark.cellId, detachId });
 		}
 	}
 	return output;

package/src/index.ts

@@ -27,38 +27,6 @@ export {
 	type RevertToOptionsAlpha,
 } from "./core/index.js";
 
-import type {
-	Listeners as EventListeners,
-	IsListener as EventIsListener,
-	Listenable as EventListenable,
-	Off as EventOff,
-} from "@fluidframework/core-interfaces";
-
-/**
- * {@inheritdoc @fluidframework/core-interfaces#Listeners}
- * @public
- * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
- */
-export type Listeners<T extends object> = EventListeners<T>;
-/**
- * {@inheritdoc @fluidframework/core-interfaces#IsListener}
- * @public
- * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
- */
-export type IsListener<T> = EventIsListener<T>;
-/**
- * {@inheritdoc @fluidframework/core-interfaces#Listenable}
- * @public
- * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
- */
-export type Listenable<T extends object> = EventListenable<T>;
-/**
- * {@inheritdoc @fluidframework/core-interfaces#Off}
- * @public
- * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
- */
-export type Off = EventOff;
-
 export {
 	TreeStatus,
 	TreeCompressionStrategy,
@@ -74,6 +42,7 @@ export {
 	type ForestType,
 	type SharedTreeFormatOptions,
 	Tree,
+	TreeBeta,
 	type RunTransaction,
 	type ForestOptions,
 	independentInitializedView,
@@ -81,11 +50,13 @@ export {
 	TreeAlpha,
 	type ObservationResults,
 	type TreeIdentifierUtils,
+	createIndependentTreeViewAlpha,
 	independentView,
 	type IndependentViewOptions,
 	type IndependentViewTelemetryOptions,
-	createIndependentTreeBeta,
 	createIndependentTreeAlpha,
+	createIndependentTreeBeta,
+	createIndependentTreeView,
 	type CreateIndependentTreeAlphaOptions,
 	ForestTypeOptimized,
 	ForestTypeExpensiveDebug,
@@ -151,7 +122,6 @@ export {
 	type ArrayNodeTreeChangedDeltaOp,
 	type ArrayNodeTreeChangedRetainOp,
 	type NodeChangedData,
-	type NodeChangedDataAlpha,
 	type NodeChangedDataDelta,
 	type NodeChangedDataProperties,
 	type NodeChangedDataTreeDelta,
@@ -224,9 +194,7 @@ export {
 	type InsertableObjectFromSchemaRecordAlpha,
 	type FieldHasDefaultAlpha,
 	// Beta APIs
-	TreeBeta,
 	type TreeChangeEventsBeta,
-	type TreeChangeEventsAlpha,
 	// Other
 	type VerboseTreeNode,
 	type TreeEncodingOptions,
@@ -281,9 +249,9 @@ export {
 	type TreeBranchAlpha,
 	type UntypedTreeViewAlpha,
 	type TreeBranchEvents,
-	asTreeViewAlpha,
 	type TreeBranchCommitMetadata,
 	type TreeBranchHistory,
+	type TreeContextBeta,
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
 	type NodeSchemaMetadata,
@@ -403,7 +371,7 @@ export type {
 } from "./util/index.js";
 export { cloneWithReplacements } from "./util/index.js";
 
-import * as InternalTypes from "./internalTypes.js";
+import type * as InternalTypes from "./internalTypes.js";
 /**
  * Contains types used by the API, but which serve mechanical purposes and do not represent semantic concepts.
  * They are used internally to implement API aspects, but are not intended for use by external consumers.
@@ -415,7 +383,7 @@ import * as InternalTypes from "./internalTypes.js";
  * support level tag is recognized by flub entrypoint generation.
  */
 // eslint-disable-next-line unicorn/prefer-export-from -- fixing requires `export * as` (breaks API-Extractor)
-export { InternalTypes };
+export type { InternalTypes };
 
 // Internal/System types:
 // These would be put in `internalTypes` except doing so tends to cause errors like:

package/src/internalTypes.ts

@@ -15,7 +15,7 @@ export type {
 	FieldHasDefault,
 	ScopedSchemaName,
 	DefaultProvider,
-	typeNameSymbol,
+	schemaIdentifierBrand,
 	InsertableObjectFromSchemaRecord,
 } from "./simple-tree/index.js";
 export type { FlexList, FlexListToUnion, ExtractItemType } from "./simple-tree/index.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.118.1";
+export const pkgVersion = "3.0.1";

package/src/shared-tree/history.ts

@@ -4,12 +4,16 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type { IIdCompressor, SessionSpaceCompressedId } from "@fluidframework/id-compressor";
 
 import type { GraphCommit, CustomMetadataTree } from "../core/index.js";
 import { flattenCustomMetadata } from "../core/index.js";
 import { BranchCommitCounter, type SharedTreeBranch } from "../shared-tree-core/index.js";
-import type { TreeBranchCommitMetadata, TreeBranchHistory } from "../simple-tree/index.js";
+import type {
+	CommitRevision,
+	TreeBranchCommitMetadata,
+	TreeBranchHistory,
+} from "../simple-tree/index.js";
 import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
 
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
@@ -19,10 +23,17 @@ import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
  * A lazily constructed implementation of {@link TreeBranchCommitMetadata} that wraps a {@link GraphCommit}.
  */
 class LazyTreeBranchCommitMetadata implements TreeBranchCommitMetadata {
-	public readonly revision: string;
+	/**
+	 * Holds a copy of data that may become inaccessible when the commit is trimmed.
+	 */
+	private readonly snapshot: {
+		readonly revision: SessionSpaceCompressedId;
+		readonly parent: GraphCommit<SharedTreeChange> | undefined;
+		readonly customMetadata: CustomMetadataTree | undefined;
+	};
 	private parentCache?: {
-		readonly prior: GraphCommit<SharedTreeChange>;
-		readonly cached: TreeBranchCommitMetadata;
+		readonly prior: GraphCommit<SharedTreeChange> | undefined;
+		readonly cached: TreeBranchCommitMetadata | undefined;
 	};
 
 	public constructor(
@@ -31,30 +42,41 @@ class LazyTreeBranchCommitMetadata implements TreeBranchCommitMetadata {
 	) {
 		assert(
 			commit.revision !== "root",
-			0xd34 /* Cannot construct metadata for the root commit */,
+			0xd33 /* Cannot construct metadata for the root commit */,
 		);
-		this.revision = idCompressor.decompress(commit.revision);
+		this.snapshot = {
+			revision: commit.revision,
+			parent: commit.parent,
+			customMetadata: commit.customMetadata,
+		};
+	}
+
+	public get revision(): CommitRevision {
+		return this.idCompressor.decompress(this.snapshot.revision);
 	}
 
 	public get custom(): JsonCompatibleReadOnlyObject | undefined {
-		return flattenCustomMetadata(this.commit.customMetadata);
+		return flattenCustomMetadata(this.snapshot.customMetadata);
 	}
 
 	public get customTree(): CustomMetadataTree | undefined {
-		return this.commit.customMetadata;
+		return this.snapshot.customMetadata;
 	}
 
 	public getParent(): TreeBranchCommitMetadata | undefined {
-		// The parent of the commit may change over time due to trunk trimming.
-		if (this.commit.parent !== this.parentCache?.prior) {
-			const { parent } = this.commit;
-			this.parentCache =
-				parent === undefined || parent.revision === "root"
-					? undefined
-					: {
-							prior: parent,
-							cached: new LazyTreeBranchCommitMetadata(parent, this.idCompressor),
-						};
+		if (this.commit.wasTrimmed) {
+			delete this.parentCache;
+			return undefined;
+		}
+		const parent = this.snapshot.parent;
+		if (parent !== this.parentCache?.prior) {
+			this.parentCache = {
+				prior: parent,
+				cached:
+					parent === undefined || parent.wasTrimmed
+						? undefined
+						: new LazyTreeBranchCommitMetadata(parent, this.idCompressor),
+			};
 		}
 		return this.parentCache?.cached;
 	}

package/src/shared-tree/independentView.ts

@@ -29,6 +29,7 @@ import type {
 	TreeViewConfiguration,
 	ImplicitFieldSchema,
 	TreeViewAlpha,
+	TreeViewBeta,
 	ITreeAlpha,
 	ViewableTree,
 	TreeView,
@@ -68,7 +69,7 @@ export interface IndependentViewTelemetryOptions {
 }
 
 /**
- * {@link independentView} options.
+ * {@link createIndependentTreeViewAlpha} options.
  * @alpha @input
  */
 export interface IndependentViewOptions
@@ -114,18 +115,54 @@ export type CreateIndependentTreeAlphaOptions = ForestOptions &
  * Create an uninitialized {@link TreeView} that is not tied to any {@link ITree} instance.
  *
  * @remarks
- * Such a view can never experience collaboration or be persisted to to a Fluid Container.
+ * Such a view can never experience collaboration or be persisted to a Fluid Container.
  *
  * This can be useful for testing, as well as use-cases like working on local files instead of documents stored in some Fluid service.
+ *
+ * @param config - The configuration for the tree view.
+ * @param options - Options for the independent tree view.
+ * @returns An uninitialized, non-collaborative tree view.
  * @alpha
  */
-export function independentView<const TSchema extends ImplicitFieldSchema>(
+export function createIndependentTreeViewAlpha<const TSchema extends ImplicitFieldSchema>(
 	config: TreeViewConfiguration<TSchema>,
 	options?: IndependentViewOptions,
 ): TreeViewAlpha<TSchema> {
 	return createIndependentTreeAlpha(options).viewWith(config) as TreeViewAlpha<TSchema>;
 }
 
+/**
+ * {@inheritDoc createIndependentTreeViewAlpha}
+ * @deprecated Use {@link createIndependentTreeViewAlpha} instead.
+ * @alpha
+ */
+export function independentView<const TSchema extends ImplicitFieldSchema>(
+	config: TreeViewConfiguration<TSchema>,
+	options?: IndependentViewOptions,
+): TreeViewAlpha<TSchema> {
+	return createIndependentTreeViewAlpha(config, options);
+}
+
+/**
+ * Creates an uninitialized tree view that is not tied to any {@link ITree} instance.
+ *
+ * @remarks
+ * Such a view can never experience collaboration or be persisted to a Fluid Container.
+ *
+ * This can be useful for testing and for use cases such as working on local files instead of documents stored in a Fluid service.
+ *
+ * @param config - The configuration for the tree view.
+ * @param options - Options for the independent tree's forest.
+ * @returns An uninitialized, non-collaborative tree view.
+ * @beta
+ */
+export function createIndependentTreeView<const TSchema extends ImplicitFieldSchema>(
+	config: TreeViewConfiguration<TSchema>,
+	options?: ForestOptions,
+): TreeViewBeta<TSchema> {
+	return createIndependentTreeBeta(options).viewWith(config) as TreeViewBeta<TSchema>;
+}
+
 /**
  * Create an initialized {@link TreeView} that is not tied to any {@link ITree} instance.
  *

package/src/shared-tree/index.ts

@@ -48,6 +48,8 @@ export { minimize } from "./transactionMinimize.js";
 export { Tree } from "./tree.js";
 export type { RunTransaction } from "./tree.js";
 
+export { TreeBeta } from "./treeBeta.js";
+
 export {
 	TreeAlpha,
 	type TreeIdentifierUtils,
@@ -57,11 +59,13 @@ export {
 export {
 	independentInitializedView,
 	type ViewContent,
+	createIndependentTreeViewAlpha,
 	independentView,
 	type IndependentViewOptions,
 	type IndependentViewTelemetryOptions,
-	createIndependentTreeBeta,
 	createIndependentTreeAlpha,
+	createIndependentTreeBeta,
+	createIndependentTreeView,
 	type CreateIndependentTreeAlphaOptions,
 } from "./independentView.js";
 

package/src/shared-tree/schematizingTreeView.ts

@@ -28,7 +28,7 @@ import {
 import {
 	type ImplicitFieldSchema,
 	type SchemaCompatibilityStatusBeta,
-	type TreeView,
+	type TreeContextAlpha,
 	type TreeViewEvents,
 	tryGetTreeNodeForField,
 	setField,
@@ -79,7 +79,7 @@ import type { TreeCheckout } from "./treeCheckout.js";
  * Creating multiple tree views from the same checkout is not supported. This slot is used to detect if one already
  * exists and error if creating a second.
  */
-export const ViewSlot = anchorSlot<TreeView<ImplicitFieldSchema>>();
+export const ViewSlot = anchorSlot<TreeContextAlpha>();
 
 function throwIfSchemaIsIncompatible(compatibility: SchemaCompatibilityStatusBeta): void {
 	if (compatibility.canView) {

package/src/shared-tree/sharedTree.ts

@@ -14,6 +14,7 @@ import type {
 	SharedKernel,
 } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { lt } from "semver-ts";
 
 import {
 	type CodecTree,
@@ -213,7 +214,7 @@ export class SharedTreeKernel
 			...defaultSharedTreeOptions,
 			...optionsParam,
 		};
-		if (options.minVersionForCollab < FluidClientVersion.v2_0) {
+		if (lt(options.minVersionForCollab, FluidClientVersion.v2_0)) {
 			throw new UsageError("SharedTree requires minVersionForCollab of at least 2.0.0");
 		}
 		const schema = new TreeStoredSchemaRepository();

package/src/shared-tree/transactionMinimize.ts

@@ -5,14 +5,21 @@
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { minimizeModularChangeset } from "../feature-libraries/index.js";
+import {
+	buildForest,
+	fieldKinds,
+	minimizeModularChangeset,
+} from "../feature-libraries/index.js";
 import { ChangeProcessorApplicability } from "../shared-tree-core/index.js";
 import type { TransactionPostProcessor } from "../simple-tree/index.js";
 
-import { mapDataChanges } from "./sharedTreeChangeFamily.js";
+import {
+	mapDataChanges,
+	type SharedTreeChangeProcessingContext,
+} from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import { createTransactionPostProcessor } from "./transactionPostProcessor.js";
-import type { SharedTreeChangeProcessingContext } from "./sharedTreeChangeFamily.js";
+import { Breakable } from "../util/index.js";
 
 /**
  * "Minimizes" a {@link SharedTreeChange} so that it contains no extraneous
@@ -40,7 +47,9 @@ function minimizeSharedTreeChange(
 		);
 	}
 	return mapDataChanges(change, (dataChange) =>
-		minimizeModularChangeset(dataChange, context.modularChangeFamily),
+		minimizeModularChangeset(dataChange, fieldKinds, () =>
+			buildForest(new Breakable("minimizeSharedTreeChange")),
+		),
 	);
 }