@fluidframework/tree 2.90.0-378676 → 2.91.0

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

@@ -5,6 +5,7 @@
 
 import { type Static, Type } from "@sinclair/typebox";
 
+import { versionField } from "../../codec/index.js";
 import { schemaFormatV1 } from "../../core/index.js";
 import { strictEnum, type Values, JsonCompatibleReadOnlySchema } from "../../util/index.js";
 
@@ -13,26 +14,20 @@ import { strictEnum, type Values, JsonCompatibleReadOnlySchema } from "../../uti
  */
 export const ForestFormatVersion = strictEnum("ForestFormatVersion", {
 	v1: 1,
-	/** This format supports incremental encoding */
+	/** This format is the same as v1, and was added at the same time as incremental encoding for reasons that no longer apply */
 	v2: 2,
 });
 export type ForestFormatVersion = Values<typeof ForestFormatVersion>;
 
-export const validVersions = new Set([...Object.values(ForestFormatVersion)]);
-
-export const FormatCommon = <const TVersion extends ForestFormatVersion>(
-	version: TVersion,
-	// Return type is intentionally derived.
-	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-) =>
-	Type.Object(
-		{
-			version: Type.Literal(version),
-			keys: Type.Array(schemaFormatV1.FieldKeySchema),
-			fields: JsonCompatibleReadOnlySchema, // Uses field batch codec
-		},
-		{ additionalProperties: false },
-	);
-export type Format<TVersion extends ForestFormatVersion = ForestFormatVersion> = Static<
-	ReturnType<typeof FormatCommon<TVersion>>
->;
+/**
+ * Format used by {@link ForestFormatVersion.v1} and {@link ForestFormatVersion.v2}.
+ */
+export const FormatCommon = Type.Object(
+	{
+		...versionField,
+		keys: Type.Array(schemaFormatV1.FieldKeySchema),
+		fields: JsonCompatibleReadOnlySchema, // Uses field batch codec
+	},
+	{ additionalProperties: false },
+);
+export type FormatCommon = Static<typeof FormatCommon>;

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

@@ -31,18 +31,6 @@ import type {
 
 import { summaryContentBlobKey } from "./summaryFormatV3.js";
 
-/**
- * State that tells whether a summary is currently being tracked.
- */
-export const ForestSummaryTrackingState = {
-	/** A summary is currently being tracked. */
-	Tracking: "Tracking",
-	/** A summary is ready to be tracked. */
-	ReadyToTrack: "ReadyToTrack",
-} as const;
-export type ForestSummaryTrackingState =
-	(typeof ForestSummaryTrackingState)[keyof typeof ForestSummaryTrackingState];
-
 /**
  * The properties of a chunk tracked during the loading process.
  * These are used to identify a chunk when it is decoded and recreate the tracking state
@@ -144,44 +132,6 @@ export enum ForestIncrementalSummaryBehavior {
 	SingleBlob,
 }
 
-/**
- * Validates that a summary is currently being tracked and that the tracked summary properties are defined.
- * @param forestSummaryState - The current state of the forest summary tracking.
- * @param trackedSummaryProperties - The properties of the tracked summary, which must be available.
- */
-function validateTrackingSummary(
-	forestSummaryState: ForestSummaryTrackingState,
-	trackedSummaryProperties: TrackedSummaryProperties | undefined,
-): asserts trackedSummaryProperties is TrackedSummaryProperties {
-	assert(
-		forestSummaryState === ForestSummaryTrackingState.Tracking,
-		0xc22 /* Not tracking a summary */,
-	);
-	assert(
-		trackedSummaryProperties !== undefined,
-		0xc23 /* Tracked summary properties must be available when tracking a summary */,
-	);
-}
-
-/**
- * Validates that a summary is ready to be tracked and that the tracked summary properties are undefined.
- * @param forestSummaryState - The current state of the forest summary tracking.
- * @param trackedSummaryProperties - The properties of the tracked summary, which must be undefined.
- */
-function validateReadyToTrackSummary(
-	forestSummaryState: ForestSummaryTrackingState,
-	trackedSummaryProperties: TrackedSummaryProperties | undefined,
-): asserts trackedSummaryProperties is undefined {
-	assert(
-		forestSummaryState === ForestSummaryTrackingState.ReadyToTrack,
-		0xc24 /* Already tracking a summary */,
-	);
-	assert(
-		trackedSummaryProperties === undefined,
-		0xc25 /* Tracked summary properties must not be available when ready to track */,
-	);
-}
-
 /* eslint-disable jsdoc/check-indentation */
 /**
  * Tracks and builds the incremental summary tree for a forest where chunks that support incremental encoding are
@@ -235,19 +185,29 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 	> = new Map();
 
 	/**
-	 * The state indicating whether a summary is currently being tracked or not.
+	 * True when encoding a summary, false otherwise.
+	 * @remarks
+	 * Exposed for testing purposes.
 	 */
-	public forestSummaryState: ForestSummaryTrackingState =
-		ForestSummaryTrackingState.ReadyToTrack;
-
+	public get isSummarizing(): boolean {
+		return this.trackedSummaryProperties !== undefined;
+	}
 	/**
 	 * The sequence number of the latest summary that was successful.
 	 */
 	private latestSummarySequenceNumber: number = -1;
 
 	/**
-	 * The current state of the summary being tracked.
-	 * This is undefined if no summary is currently being tracked.
+	 * The current state of the summary being "tracked".
+	 * @remarks
+	 * A summary being "tracked" means that a summary is being encoded.
+	 * This is undefined if no summary is currently being encoded.
+	 *
+	 * @privateRemarks
+	 * This has nothing to do which how content from a summary being loaded is tracked (thats written all in chunkTrackingPropertiesMap).
+	 * "Tracked" should probably be renamed to "encoded" or "summarizing" or something like that to avoid confusion.
+	 * Perhaps a better way to clarify this would be to not store this property on this object at all, and have it
+	 * only exist within the scope of the summary encoding (use an encoding specific object to accumulate any stat necessary during encode).
 	 */
 	private trackedSummaryProperties: TrackedSummaryProperties | undefined;
 
@@ -321,6 +281,15 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		await downloadChunkContentsInTree(forestTree, "");
 	}
 
+	/**
+	 * Asserts that a summary is currently being tracked and that the tracked summary properties are defined.
+	 * @returns The properties of the tracked summary.
+	 */
+	private requireTrackingSummary(): TrackedSummaryProperties {
+		assert(this.trackedSummaryProperties !== undefined, 0xc22 /* Not tracking a summary */);
+		return this.trackedSummaryProperties;
+	}
+
 	/**
 	 * Must be called when starting a new forest summary to track it.
 	 * @param fullTree - Whether the summary is a full tree summary. If true, the summary will not contain
@@ -336,6 +305,11 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		stringify: SummaryElementStringifier;
 		builder: SummaryTreeBuilder;
 	}): ForestIncrementalSummaryBehavior {
+		assert(
+			this.trackedSummaryProperties === undefined,
+			0xc24 /* Already tracking a summary */,
+		);
+
 		const { fullTree, incrementalSummaryContext, stringify, builder } = args;
 		// If there is no incremental summary context, do not summarize incrementally. This happens in two scenarios:
 		// 1. When summarizing a detached container, i.e., the first ever summary.
@@ -344,9 +318,6 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			return ForestIncrementalSummaryBehavior.SingleBlob;
 		}
 
-		validateReadyToTrackSummary(this.forestSummaryState, this.trackedSummaryProperties);
-
-		this.forestSummaryState = ForestSummaryTrackingState.Tracking;
 		this.latestSummarySequenceNumber = incrementalSummaryContext.latestSummarySequenceNumber;
 		this.trackedSummaryProperties = {
 			summarySequenceNumber: incrementalSummaryContext.summarySequenceNumber,
@@ -368,7 +339,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		chunkEncoder: (chunk: TreeChunk) => EncodedFieldBatch,
 	): ChunkReferenceId[] {
 		// Validate that a summary is currently being tracked and that the tracked summary properties are defined.
-		validateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);
+		const trackedSummaryProperties = this.requireTrackingSummary();
 
 		const chunkReferenceIds: ChunkReferenceId[] = [];
 		const chunks = this.getChunkAtCursor(cursor);
@@ -383,12 +354,12 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				this.latestSummarySequenceNumber,
 				chunk,
 			);
-			if (previousChunkProperties !== undefined && !this.trackedSummaryProperties.fullTree) {
+			if (previousChunkProperties !== undefined && !trackedSummaryProperties.fullTree) {
 				chunkProperties = previousChunkProperties;
-				this.trackedSummaryProperties.parentSummaryBuilder.addHandle(
+				trackedSummaryProperties.parentSummaryBuilder.addHandle(
 					`${chunkProperties.referenceId}`,
 					SummaryType.Tree,
-					`${this.trackedSummaryProperties.latestSummaryBasePath}/${chunkProperties.summaryPath}`,
+					`${trackedSummaryProperties.latestSummaryBasePath}/${chunkProperties.summaryPath}`,
 				);
 			} else {
 				// Generate a new reference ID for the chunk.
@@ -398,23 +369,23 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				// for the chunk in its summary properties.
 				// This is done before encoding the chunk so that the summary path is updated correctly when encoding
 				// any incremental chunks that are under this chunk.
-				this.trackedSummaryProperties.chunkSummaryPath.push(newReferenceId);
+				trackedSummaryProperties.chunkSummaryPath.push(newReferenceId);
 
 				chunkProperties = {
 					referenceId: newReferenceId,
-					summaryPath: this.trackedSummaryProperties.chunkSummaryPath.join("/"),
+					summaryPath: trackedSummaryProperties.chunkSummaryPath.join("/"),
 				};
 
-				const parentSummaryBuilder = this.trackedSummaryProperties.parentSummaryBuilder;
+				const parentSummaryBuilder = trackedSummaryProperties.parentSummaryBuilder;
 				// Create a new summary builder for this chunk to build its summary tree which will be stored in the
 				// parent's summary tree under its reference ID.
 				// Before encoding the chunk, set the parent summary builder to this chunk's summary builder so that
 				// any incremental chunks in the subtree of this chunk will use that as their parent summary builder.
 				const chunkSummaryBuilder = new SummaryTreeBuilder();
-				this.trackedSummaryProperties.parentSummaryBuilder = chunkSummaryBuilder;
+				trackedSummaryProperties.parentSummaryBuilder = chunkSummaryBuilder;
 				chunkSummaryBuilder.addBlob(
 					summaryContentBlobKey,
-					this.trackedSummaryProperties.stringify(chunkEncoder(chunk)),
+					trackedSummaryProperties.stringify(chunkEncoder(chunk)),
 				);
 
 				// Add this chunk's summary tree to the parent's summary tree. The summary tree contains its encoded
@@ -425,13 +396,13 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 				);
 
 				// Restore the parent summary builder and chunk summary path.
-				this.trackedSummaryProperties.parentSummaryBuilder = parentSummaryBuilder;
-				this.trackedSummaryProperties.chunkSummaryPath.pop();
+				trackedSummaryProperties.parentSummaryBuilder = parentSummaryBuilder;
+				trackedSummaryProperties.chunkSummaryPath.pop();
 			}
 
 			setInNestedMap(
 				this.chunkTrackingPropertiesMap,
-				this.trackedSummaryProperties.summarySequenceNumber,
+				trackedSummaryProperties.summarySequenceNumber,
 				chunk,
 				chunkProperties,
 			);
@@ -469,7 +440,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			return;
 		}
 
-		validateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);
+		const trackedSummaryProperties = this.requireTrackingSummary();
 
 		builder.addBlob(forestSummaryRootContentKey, forestSummaryRootContent);
 
@@ -481,7 +452,7 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			this.latestSummarySequenceNumber,
 		);
 		const currentSummaryTrackingMap = this.chunkTrackingPropertiesMap.get(
-			this.trackedSummaryProperties.summarySequenceNumber,
+			trackedSummaryProperties.summarySequenceNumber,
 		);
 		if (latestSummaryTrackingMap !== undefined && currentSummaryTrackingMap !== undefined) {
 			for (const [chunk, chunkProperties] of latestSummaryTrackingMap.entries()) {
@@ -499,7 +470,6 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 			}
 		}
 
-		this.forestSummaryState = ForestSummaryTrackingState.ReadyToTrack;
 		this.trackedSummaryProperties = undefined;
 	}
 

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

@@ -4,5 +4,5 @@
  */
 
 export { ForestSummarizer } from "./forestSummarizer.js";
-export { getCodecTreeForForestFormat } from "./codec.js";
+export { forestCodecBuilder } from "./codec.js";
 export { ForestFormatVersion } from "./formatCommon.js";

package/src/feature-libraries/index.ts

@@ -11,7 +11,7 @@ export { allowsValue, assertAllowedValue, isTreeValue } from "./valueUtilities.j
 
 export {
 	ForestSummarizer,
-	getCodecTreeForForestFormat,
+	forestCodecBuilder,
 	ForestFormatVersion,
 } from "./forest-summary/index.js";
 export {
@@ -69,10 +69,8 @@ export {
 	type NodeChangeInverter,
 	type NodeChangeRebaser,
 	type NodeChangePruner,
-	type ComposeNodeManager,
-	type InvertNodeManager,
-	type RebaseNodeManager,
-	NodeMoveType,
+	type CrossFieldManager,
+	CrossFieldTarget,
 	FlexFieldKind,
 	type FullSchemaPolicy,
 	allowsRepoSuperset,
@@ -81,6 +79,7 @@ export {
 	type HasFieldChanges,
 	type NodeExistsConstraint,
 	ModularChangeFamily,
+	type RelevantRemovedRootsFromChild,
 	EncodedModularChangesetV1,
 	EncodedModularChangesetV2,
 	updateRefreshers,
@@ -93,11 +92,7 @@ export {
 	ModularChangeFormatVersion,
 } from "./modular-schema/index.js";
 
-export {
-	mapRootChanges,
-	nodeIdFromChangeAtom,
-	changeAtomFromDetachedNodeId,
-} from "./deltaUtils.js";
+export { mapRootChanges } from "./deltaUtils.js";
 
 export {
 	type TreeChunk,
@@ -109,9 +104,8 @@ export {
 	type FieldBatch,
 	type FieldBatchCodec,
 	FieldBatchFormatVersion,
-	getCodecTreeForFieldBatchFormat,
 	makeTreeChunker,
-	makeFieldBatchCodec,
+	fieldBatchCodecBuilder,
 	type FieldBatchEncodingContext,
 	emptyChunk,
 	combineChunks,
@@ -133,25 +127,17 @@ export {
 export {
 	FieldKinds,
 	type DefaultChangeset,
-	type DetachedRootIds,
 	DefaultChangeFamily,
-	type IdBasedChangeFamilyDataEditor,
-	DefaultIdBasedDataEditor,
-	type DataEditor,
-	type RequiredFieldEditor,
-	type OptionalFieldEditor,
-	type SequenceFieldEditor,
+	DefaultEditBuilder,
+	type IDefaultEditBuilder,
+	type ValueFieldEditBuilder,
+	type OptionalFieldEditBuilder,
+	type SequenceFieldEditBuilder,
 	defaultSchemaPolicy,
 	fieldKinds,
 	fieldKindConfigurations,
 	intoDelta,
 	relevantRemovedRoots,
-	type DetachedRootLocation,
-	type DetachedRootsLocation,
-	type DetachedRootIdRange,
-	type Locator,
-	LocationBasedDataEditor,
-	type ILocationBasedDataEditor,
 	getCodecTreeForModularChangeFormat,
 } from "./default-schema/index.js";
 
@@ -217,7 +203,6 @@ export {
 	AnchorTreeIndex,
 	hasElement,
 	type TreeIndex,
-	type TreeIndexKey,
 	type TreeIndexNodes,
 } from "./indexing/index.js";
 

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

@@ -27,7 +27,7 @@ import {
 import { disposeSymbol, getOrCreate } from "../../util/index.js";
 import { TreeStatus } from "../flex-tree/index.js";
 
-import type { TreeIndex, TreeIndexKey, TreeIndexNodes } from "./types.js";
+import type { TreeIndex, TreeIndexNodes } from "./types.js";
 
 /**
  * A function that gets the value to index a node on, must be pure and functional.
@@ -40,7 +40,7 @@ import type { TreeIndex, TreeIndexKey, TreeIndexNodes } from "./types.js";
  * but returns the cursor to the state it was in before being passed to the function. It should also not be disposed by this function
  * and must be disposed elsewhere.
  */
-export type KeyFinder<TKey extends TreeIndexKey> = (tree: ITreeSubscriptionCursor) => TKey;
+export type KeyFinder<TKey> = (tree: ITreeSubscriptionCursor) => TKey;
 
 /**
  * An index from some arbitrary keys to anchor nodes. Keys can be anything that is a {@link TreeValue}.
@@ -50,9 +50,7 @@ export type KeyFinder<TKey extends TreeIndexKey> = (tree: ITreeSubscriptionCurso
  * Detached nodes are stored in the index but filtered out when any public facing apis are called. This means that
  * calling {@link keys} will not include any keys that are stored in the index but only map to detached nodes.
  */
-export class AnchorTreeIndex<TKey extends TreeIndexKey, TValue>
-	implements TreeIndex<TKey, TValue>
-{
+export class AnchorTreeIndex<TKey, TValue> implements TreeIndex<TKey, TValue> {
 	public disposed = false;
 	/**
 	 * Caches {@link KeyFinder}s for each schema definition. If a schema maps to null, it does not

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

@@ -8,4 +8,4 @@ export {
 	type KeyFinder,
 	hasElement,
 } from "./anchorTreeIndex.js";
-export type { TreeIndex, TreeIndexKey, TreeIndexNodes } from "./types.js";
+export type { TreeIndex, TreeIndexNodes } from "./types.js";

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

@@ -3,8 +3,6 @@
  * Licensed under the MIT License.
  */
 
-import type { IFluidHandle } from "@fluidframework/core-interfaces";
-
 /**
  * an array of nodes that is guaranteed to have at least one element
  *
@@ -13,25 +11,25 @@ import type { IFluidHandle } from "@fluidframework/core-interfaces";
 export type TreeIndexNodes<TNode> = readonly [first: TNode, ...rest: TNode[]];
 
 /**
- * Value that may be used as keys in a {@link TreeIndex}.
- *
+ * An index allows lookup content from a tree using keys.
+ * @remarks
+ * The index will be kept up to date with the {@link TreeBranchAlpha} it is associated with.
+ * Keeping an index up to date incurs overhead.
+ * Therefore, indexes should only be created when needed and disposed when no longer needed.
  * @privateRemarks
- * no-new-null is disabled for this type so that it supports the TreeValue type.
- *
- * @alpha
- */
-// eslint-disable-next-line @rushstack/no-new-null
-export type TreeIndexKey = number | string | boolean | IFluidHandle | null;
-
-/**
- * A index where values are keyed on {@link TreeIndexKey}s.
- *
+ * We have various disposable interfaces. Perhaps this should extend one.
+ * Currently all of these indexes are generated on load and exist only in memory (do not persist anything to the document).
+ * In the future, we may want to support indexes which persist some content, allowing them to be kept up to date when when only loading part of a tree.
+ * Since currently partially loading a tree is not supported, there is no need for this.
+ * At some point the low level shared tree index type for persisted indexes could be leveraged to provide user facing extensible sets of persisted indexes.
+ * @sealed
  * @alpha
  */
-export interface TreeIndex<TKey extends TreeIndexKey, TValue>
-	extends ReadonlyMap<TKey, TValue> {
+export interface TreeIndex<TKey, TValue> extends ReadonlyMap<TKey, TValue> {
 	/**
-	 * Disposes the index such that it can no longer be used and receives no updates from the forest
+	 * Disposes the index such that it can no longer be used and receives no updates for changes in the tree.
+	 * @remarks
+	 * An index may not be used after it is disposed.
 	 */
 	dispose(): void;
 }

package/src/feature-libraries/mitigatedChangeFamily.ts

@@ -7,7 +7,6 @@ import type {
 	ChangeFamily,
 	ChangeFamilyEditor,
 	ChangeRebaser,
-	EditorOptions,
 	RevisionMetadataSource,
 	RevisionReplacer,
 	RevisionTag,
@@ -37,9 +36,8 @@ export function makeMitigatedChangeFamily<TEditor extends ChangeFamilyEditor, TC
 		buildEditor: (
 			mintRevisionTag: () => RevisionTag,
 			changeReceiver: (change: TaggedChange<TChange>) => void,
-			options?: EditorOptions,
 		): TEditor => {
-			return unmitigatedChangeFamily.buildEditor(mintRevisionTag, changeReceiver, options);
+			return unmitigatedChangeFamily.buildEditor(mintRevisionTag, changeReceiver);
 		},
 		rebaser: makeMitigatedRebaser(unmitigatedChangeFamily.rebaser, fallbackChange, onError),
 		codecs: unmitigatedChangeFamily.codecs,