@fluidframework/tree 2.80.0 → 2.81.0-374083

package/src/index.ts

@@ -9,6 +9,8 @@ export {
 	CommitKind,
 	RevertibleStatus,
 	type CommitMetadata,
+	type LocalChangeMetadata,
+	type RemoteChangeMetadata,
 	type ChangeMetadata,
 	type RevertibleFactory,
 	type RevertibleAlphaFactory,
@@ -292,10 +294,13 @@ export {
 	exportCompatibilitySchemaSnapshot,
 	importCompatibilitySchemaSnapshot,
 	checkCompatibility,
+	checkSchemaCompatibilitySnapshots,
+	type SnapshotFileSystem,
 	incrementalSummaryHint,
 	incrementalEncodingPolicyForAllowedTypes,
 	eraseSchemaDetails,
 	eraseSchemaDetailsSubclassable,
+	type SchemaCompatibilitySnapshotsOptions,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,
@@ -360,3 +365,5 @@ export { JsonAsTree } from "./jsonDomainSchema.js";
 export { FluidSerializableAsTree } from "./serializableDomainSchema.js";
 export { TableSchema, type System_TableSchema } from "./tableSchema.js";
 export { asAlpha, asBeta } from "./api.js";
+
+export { TextAsTree } from "./text/index.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.80.0";
+export const pkgVersion = "2.81.0-374083";

package/src/shared-tree/index.ts

@@ -41,9 +41,10 @@ export { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 export { initialize, initializerFromChunk } from "./schematizeTree.js";
 
 export type {
-	ISharedTreeEditor,
+	IIdBasedSharedTreeEditor,
+	ILocationBasedSharedTreeEditor,
 	ISchemaEditor,
-	SharedTreeEditBuilder,
+	IdBasedSharedTreeEditBuilder,
 } from "./sharedTreeEditBuilder.js";
 
 export { Tree } from "./tree.js";

package/src/shared-tree/schematizeTree.ts

@@ -5,12 +5,19 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 
-import { type TreeStoredSchema, rootFieldKey, schemaDataIsEmpty } from "../core/index.js";
+import {
+	type ChangeAtomId,
+	type TreeStoredSchema,
+	rootFieldKey,
+	schemaDataIsEmpty,
+} from "../core/index.js";
 import {
 	FieldKinds,
 	allowsRepoSuperset,
 	defaultSchemaPolicy,
-	type IDefaultEditBuilder,
+	type DetachedRootIds,
+	type ILocationBasedDataEditor,
+	type DataEditor,
 	type TreeChunk,
 } from "../feature-libraries/index.js";
 
@@ -37,11 +44,11 @@ export function canInitialize(checkout: ITreeCheckout): boolean {
  * @privateRemarks
  * This takes in a checkout using a subset of the checkout interface to enable easier unit testing.
  */
-export function initialize(
+export function initialize<T>(
 	checkout: Pick<ITreeCheckout, "storedSchema" | "updateSchema">,
 	newSchema: TreeStoredSchema,
-	setInitialTree: () => void,
-): void {
+	setInitialTree: () => T,
+): T {
 	assert(
 		schemaDataIsEmpty(checkout.storedSchema),
 		0x743 /* cannot initialize after a schema is set */,
@@ -78,13 +85,15 @@ export function initialize(
 	);
 
 	checkout.updateSchema(intermediateSchema);
-	setInitialTree();
+	const result = setInitialTree();
 
 	// If intermediate schema is not final desired schema, update to the final schema:
 	if (intermediateSchema !== newSchema) {
 		// This makes the root more strict, so set allowNonSupersetSchema to true.
 		checkout.updateSchema(newSchema, true);
 	}
+
+	return result;
 }
 
 /**
@@ -99,7 +108,9 @@ export function initialize(
  */
 export function initializerFromChunk(
 	checkout: Pick<ITreeCheckout, "storedSchema"> & {
-		readonly editor: IDefaultEditBuilder;
+		readonly editor:
+			| ILocationBasedDataEditor
+			| DataEditor<TreeChunk, ChangeAtomId, DetachedRootIds>;
 	},
 	contentFactory: () => TreeChunk,
 ): () => void {
@@ -108,7 +119,9 @@ export function initializerFromChunk(
 
 function initializeFromChunk(
 	checkout: Pick<ITreeCheckout, "storedSchema"> & {
-		readonly editor: IDefaultEditBuilder;
+		readonly editor:
+			| ILocationBasedDataEditor
+			| DataEditor<TreeChunk, ChangeAtomId, DetachedRootIds>;
 	},
 	contentChunk: TreeChunk,
 ): void {

package/src/shared-tree/schematizingTreeView.ts

@@ -16,10 +16,8 @@ import { anchorSlot, rootFieldKey } from "../core/index.js";
 import {
 	type NodeIdentifierManager,
 	defaultSchemaPolicy,
-	cursorForMapTreeField,
 	TreeStatus,
 	Context,
-	combineChunks,
 	type FlexTreeOptionalField,
 	type FlexTreeUnknownUnboxed,
 	FieldKinds,
@@ -67,11 +65,12 @@ import {
 	type Breakable,
 	breakingClass,
 	disposeSymbol,
+	hasSingle,
 	type JsonCompatibleReadOnly,
 	type WithBreakable,
 } from "../util/index.js";
 
-import { canInitialize, initialize, initializerFromChunk } from "./schematizeTree.js";
+import { canInitialize, initialize } from "./schematizeTree.js";
 import type { ITreeCheckout, TreeCheckout } from "./treeCheckout.js";
 
 /**
@@ -124,11 +123,6 @@ export class SchematizingSimpleTreeView<
 	 */
 	private midUpgrade = false;
 
-	/**
-	 * Hydration work deferred until Context has been created.
-	 */
-	private pendingHydration?: () => void;
-
 	private readonly rootFieldSchema: FieldSchema;
 	public readonly breaker: Breakable;
 
@@ -190,57 +184,54 @@ export class SchematizingSimpleTreeView<
 
 		this.runSchemaEdit(() => {
 			const schema = toInitialSchema(this.config.schema);
-			// 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
-			// immediately dispose them instead of having them actually be useable after initialize.
-			// For this to work,
-			// the hydration must be deferred until after the content is inserted into the tree and the final schema change is done (for required roots),
-			// but before any user event could could run.
-			const mapTree = prepareForInsertionContextless(
-				content as InsertableContent | undefined,
-				this.rootFieldSchema,
-				{
-					schema,
-					policy: defaultSchemaPolicy,
-				},
-				this,
-				schema.rootFieldSchema,
-				(batches, doHydration) => {
-					assert(
-						this.pendingHydration === undefined,
-						0xc74 /* pendingHydration already set */,
-					);
-					this.pendingHydration = () => {
-						assert(
-							batches.length <= 1,
-							0xc75 /* initialize should at most one hydration batch */,
-						);
-						for (const batch of batches) {
-							doHydration(batch, {
-								parent: undefined,
-								parentField: rootFieldKey,
-								parentIndex: 0,
-							});
-						}
-					};
-				},
-			);
-
 			this.checkout.transaction.start();
+			initialize(this.checkout, schema, () => {
+				const preparedContent = prepareForInsertionContextless(
+					content as InsertableContent | undefined,
+					this.rootFieldSchema,
+					{
+						schema,
+						policy: defaultSchemaPolicy,
+					},
+					this,
+					schema.rootFieldSchema,
+				);
 
-			initialize(
-				this.checkout,
-				schema,
-				initializerFromChunk(this.checkout, () => {
-					// This must be done after initial schema is set!
-					return combineChunks(
-						this.checkout.forest.chunkField(
-							cursorForMapTreeField(mapTree === undefined ? [] : [mapTree]),
-						),
-					);
-				}),
-			);
+				if (preparedContent.rootsLocations.length === 0) {
+					// If there's no content to attach, no work is needed
+					return undefined;
+				}
+
+				const field = { field: rootFieldKey, parent: undefined };
+				assert(
+					this.checkout.storedSchema.rootFieldSchema.kind === FieldKinds.optional.identifier,
+					"initializerFromChunk only supports optional roots",
+				);
+
+				assert(
+					hasSingle(preparedContent.rootsLocations) &&
+						preparedContent.rootsLocations[0].count === 1,
+					"Expected one root",
+				);
+				const fieldEditor = this.checkout.editor.optionalField(field);
+				fieldEditor.attach(preparedContent.rootsLocations[0].field, true);
+
+				return preparedContent;
+			})?.finalize([...this.getFlexTreeContext().root]);
+
+			// TODO:CM
+			// initialize(
+			// 	this.checkout,
+			// 	schema,
+			// 	initializerFromChunk(this.checkout, () => {
+			// 		// This must be done after initial schema is set!
+			// 		return combineChunks(
+			// 			this.checkout.forest.chunkField(
+			// 				cursorForMapTreeField(mapTree === undefined ? [] : [mapTree]),
+			// 			),
+			// 		);
+			// 	}),
+			// );
 			this.checkout.transaction.commit();
 		});
 	}
@@ -395,9 +386,7 @@ export class SchematizingSimpleTreeView<
 
 				// Track what the root was before to be able to detect changes.
 				// This uses the flex tree root to avoid demanding the simple-tree TreeNode when it might not be hydrated yet.
-				let lastRoot: FlexTreeUnknownUnboxed | undefined = (
-					this.flexTreeContext.root as FlexTreeOptionalField
-				).content;
+				let lastRoot: FlexTreeUnknownUnboxed | undefined = this.flexRoot.content;
 
 				this.flexTreeViewUnregisterCallbacks.add(
 					this.checkout.events.on("afterBatch", () => {
@@ -421,10 +410,6 @@ export class SchematizingSimpleTreeView<
 		);
 
 		if (!this.midUpgrade) {
-			assert(
-				this.pendingHydration === undefined,
-				0xc76 /* no nodes should be pending hydration when triggering events that could access nodes */,
-			);
 			this.events.emit("schemaChanged");
 			this.events.emit("rootChanged");
 		}
@@ -437,9 +422,6 @@ export class SchematizingSimpleTreeView<
 		} finally {
 			this.midUpgrade = false;
 		}
-		// Ensure hydration is flushed before events run which could access nodes.
-		this.pendingHydration?.();
-		this.pendingHydration = undefined;
 		this.events.emit("schemaChanged");
 		this.events.emit("rootChanged");
 	}
@@ -455,7 +437,9 @@ export class SchematizingSimpleTreeView<
 			this.flexTreeContext[disposeSymbol]();
 			this.flexTreeContext = undefined;
 		}
-		this.flexTreeViewUnregisterCallbacks.forEach((unregister) => unregister());
+		for (const unregister of this.flexTreeViewUnregisterCallbacks) {
+			unregister();
+		}
 		this.flexTreeViewUnregisterCallbacks.clear();
 		anchors.slots.delete(SimpleContextSlot);
 	}
@@ -470,7 +454,9 @@ export class SchematizingSimpleTreeView<
 	public dispose(): void {
 		this.disposed = true;
 		this.disposeFlexView();
-		this.unregisterCallbacks.forEach((unregister) => unregister());
+		for (const unregister of this.unregisterCallbacks) {
+			unregister();
+		}
 		this.checkout.forest.anchors.slots.delete(ViewSlot);
 		this.currentCompatibility = undefined;
 		this.onDispose?.();
@@ -551,7 +537,7 @@ export function getCheckout(context: TreeBranch): TreeCheckout {
  * Adds constraints to a `checkout`'s pending transaction.
  *
  * @param checkout - The checkout's who's transaction will have the constraints added to it.
- * @param constraintsOnRevert - If true, use {@link ISharedTreeEditor.addNodeExistsConstraintOnRevert}.
+ * @param constraintsOnRevert - If true, use {@link IIdBasedSharedTreeEditor.addNodeExistsConstraintOnRevert}.
  * @param constraints - The constraints to add to the transaction.
  *
  * @see {@link RunTransactionParams.preconditions}.

package/src/shared-tree/sharedTree.ts

@@ -103,7 +103,7 @@ import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import { SharedTreeReadonlyChangeEnricher } from "./sharedTreeChangeEnricher.js";
 import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
-import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
+import type { IdBasedSharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { type TreeCheckout, type BranchableTree, createTreeCheckout } from "./treeCheckout.js";
 import {
 	brand,
@@ -181,7 +181,7 @@ export type SharedTreeKernelView = Omit<ITreePrivate, keyof (IChannelView & IFlu
  */
 @breakingClass
 export class SharedTreeKernel
-	extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>
+	extends SharedTreeCore<IdBasedSharedTreeEditBuilder, SharedTreeChange>
 	implements SharedKernel
 {
 	public readonly checkout: TreeCheckout;
@@ -471,7 +471,7 @@ export class SharedTreeKernel
 
 	public override applyStashedOp(
 		...args: Parameters<
-			SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>["applyStashedOp"]
+			SharedTreeCore<IdBasedSharedTreeEditBuilder, SharedTreeChange>["applyStashedOp"]
 		>
 	): void {
 		for (const checkout of this.checkouts.values()) {
@@ -587,6 +587,7 @@ export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(
  * Once an entry is defined and used in production, it cannot be changed.
  * This is because the format for SharedTree changes are not explicitly versioned.
  */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-enum-comparison -- intentional comparison
 export const changeFormatVersionForEditManager = DependentFormatVersion.fromPairs([
 	[
 		brand<EditManagerFormatVersion>(EditManagerFormatVersion.v3),
@@ -604,6 +605,10 @@ export const changeFormatVersionForEditManager = DependentFormatVersion.fromPair
 		brand<EditManagerFormatVersion>(EditManagerFormatVersion.v6),
 		brand<SharedTreeChangeFormatVersion>(5),
 	],
+	[
+		brand<EditManagerFormatVersion>(EditManagerFormatVersion.vDetachedRoots),
+		brand<SharedTreeChangeFormatVersion>(101),
+	],
 ]);
 
 /**
@@ -629,6 +634,10 @@ export const changeFormatVersionForMessage = DependentFormatVersion.fromPairs([
 		brand<MessageFormatVersion>(MessageFormatVersion.v6),
 		brand<SharedTreeChangeFormatVersion>(5),
 	],
+	[
+		brand<MessageFormatVersion>(MessageFormatVersion.vDetachedRoots),
+		brand<SharedTreeChangeFormatVersion>(101),
+	],
 ]);
 
 function getCodecTreeForEditManagerFormat(clientVersion: MinimumVersionForCollab): CodecTree {
@@ -684,6 +693,12 @@ export interface SharedTreeOptions
 	 * Defaults to false.
 	 */
 	readonly enableSharedBranches?: boolean;
+	/**
+	 * Experimental feature flag to enable the ability to edit detached roots.
+	 * This feature is not yet complete and should not be used in production.
+	 * Defaults to false.
+	 */
+	readonly enableDetachedRootEditing?: boolean;
 	/**
 	 * Returns whether a node / field should be incrementally encoded.
 	 * @remarks
@@ -826,6 +841,8 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	enableSharedBranches: false,
 	writeVersionOverrides: new Map(),
 	allowPossiblyIncompatibleWriteVersionOverrides: false,
+	enableDetachedRootEditing: false,
+	canMakeDetachedRootEdits: false,
 };
 
 /**

package/src/shared-tree/sharedTreeChangeCodecs.ts

@@ -74,7 +74,10 @@ interface ChangeFormatDependencies {
 	readonly schemaChange: SchemaFormatVersion;
 }
 
-export type SharedTreeChangeFormatVersion = Brand<3 | 4 | 5, "SharedTreeChangeFormatVersion">;
+export type SharedTreeChangeFormatVersion = Brand<
+	3 | 4 | 5 | 101,
+	"SharedTreeChangeFormatVersion"
+>;
 
 /**
  * Defines for each SharedTree change format the corresponding dependent formats to use.
@@ -89,6 +92,7 @@ export const dependenciesForChangeFormat: Map<
 	[brand(3), { modularChange: brand(3), schemaChange: SchemaFormatVersion.v1 }],
 	[brand(4), { modularChange: brand(4), schemaChange: SchemaFormatVersion.v1 }],
 	[brand(5), { modularChange: brand(5), schemaChange: SchemaFormatVersion.v1 }],
+	[brand(101), { modularChange: brand(101), schemaChange: brand(SchemaFormatVersion.v1) }],
 ]);
 
 export function getCodecTreeForChangeFormat(

package/src/shared-tree/sharedTreeChangeEnricher.ts

@@ -20,6 +20,7 @@ import {
 	type TreeChunk,
 	chunkTree,
 	defaultChunkPolicy,
+	getBuildsIds,
 	intoDelta,
 	relevantRemovedRoots,
 	updateRefreshers as updateDataChangeRefreshers,
@@ -62,6 +63,7 @@ export class SharedTreeReadonlyChangeEnricher
 	public updateChangeEnrichments(change: SharedTreeChange): SharedTreeChange {
 		return updateRefreshers(
 			change,
+			getBuildsIds,
 			this.getDetachedRoot,
 			relevantRemovedRoots,
 			updateDataChangeRefreshers,

package/src/shared-tree/sharedTreeChangeFamily.ts

@@ -12,6 +12,7 @@ import {
 	type ChangeFamily,
 	type ChangeRebaser,
 	type DeltaDetachedNodeId,
+	type EditorOptions,
 	type RevisionMetadataSource,
 	type RevisionReplacer,
 	type RevisionTag,
@@ -39,7 +40,7 @@ import {
 
 import { makeSharedTreeChangeCodecFamily } from "./sharedTreeChangeCodecs.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
-import { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
+import { IdBasedSharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 
 /**
  * Implementation of {@link ChangeFamily} that combines edits to fields and schema changes.
@@ -48,7 +49,7 @@ import { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
  */
 export class SharedTreeChangeFamily
 	implements
-		ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>,
+		ChangeFamily<IdBasedSharedTreeEditBuilder, SharedTreeChange>,
 		ChangeRebaser<SharedTreeChange>
 {
 	public static readonly emptyChange: SharedTreeChange = {
@@ -86,11 +87,13 @@ export class SharedTreeChangeFamily
 	public buildEditor(
 		mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<SharedTreeChange>) => void,
-	): SharedTreeEditBuilder {
-		return new SharedTreeEditBuilder(
+		options?: EditorOptions,
+	): IdBasedSharedTreeEditBuilder {
+		return new IdBasedSharedTreeEditBuilder(
 			this.modularChangeFamily,
 			mintRevisionTag,
 			changeReceiver,
+			options,
 		);
 	}
 
@@ -269,6 +272,7 @@ function mapDataChanges(
  */
 export function updateRefreshers(
 	change: SharedTreeChange,
+	buildsFromDataChange: (taggedChange: ModularChangeset) => Iterable<DeltaDetachedNodeId>,
 	getDetachedNode: (id: DeltaDetachedNodeId) => TreeChunk | undefined,
 	relevantRemovedRootsFromDataChange: (
 		taggedChange: ModularChangeset,
@@ -315,13 +319,19 @@ export function updateRefreshers(
 	}
 	let isFirstDataChange = true;
 	return mapDataChanges(change, (dataChange) => {
+		const builtRoots = buildsFromDataChange(dataChange);
+		for (const id of builtRoots) {
+			// Detached root IDs that are used for builds are only ever used by a single node,
+			// so there is no risk of excluding needed refreshers by adding them to the list of already included roots.
+			addToNestedSet(includedRoots, id.major, id.minor);
+		}
 		const removedRoots = relevantRemovedRootsFromDataChange(dataChange);
 		if (isFirstDataChange) {
 			isFirstDataChange = false;
 			return updateDataChangeRefreshers(
 				dataChange,
 				getAndRememberDetachedNode,
-				removedRoots,
+				filterIncludedRoots(removedRoots),
 				true,
 			);
 		} else {

package/src/shared-tree/sharedTreeEditBuilder.ts

@@ -4,14 +4,22 @@
  */
 
 import type {
+	ChangeAtomId,
 	ChangeFamilyEditor,
+	EditorOptions,
 	RevisionTag,
 	TaggedChange,
+	TreeChunk,
 	TreeStoredSchema,
 } from "../core/index.js";
 import {
-	DefaultEditBuilder,
-	type IDefaultEditBuilder,
+	DefaultIdBasedDataEditor,
+	LocationBasedDataEditor,
+	type DetachedRootIds,
+	type DetachedRootLocation,
+	type DetachedRootsLocation,
+	type Locator,
+	type DataEditor,
 	type ModularChangeFamily,
 } from "../feature-libraries/index.js";
 
@@ -33,7 +41,16 @@ export interface ISchemaEditor {
 /**
  * SharedTree editor for transactional tree data and schema changes.
  */
-export interface ISharedTreeEditor extends IDefaultEditBuilder {
+export interface IIdBasedSharedTreeEditor
+	extends DataEditor<TreeChunk, ChangeAtomId, DetachedRootIds> {
+	/**
+	 * Editor for schema changes.
+	 */
+	schema: ISchemaEditor;
+}
+
+export interface ILocationBasedSharedTreeEditor
+	extends DataEditor<TreeChunk, DetachedRootLocation, DetachedRootsLocation> {
 	/**
 	 * Editor for schema changes.
 	 */
@@ -41,12 +58,12 @@ export interface ISharedTreeEditor extends IDefaultEditBuilder {
 }
 
 /**
- * Implementation of {@link IDefaultEditBuilder} based on the default set of supported field kinds.
+ * Implementation of {@link DataEditor} based on the default set of supported field kinds.
  * @sealed
  */
-export class SharedTreeEditBuilder
-	extends DefaultEditBuilder
-	implements ChangeFamilyEditor, ISharedTreeEditor
+export class IdBasedSharedTreeEditBuilder
+	extends DefaultIdBasedDataEditor
+	implements ChangeFamilyEditor, IIdBasedSharedTreeEditor
 {
 	public readonly schema: ISchemaEditor;
 
@@ -54,6 +71,7 @@ export class SharedTreeEditBuilder
 		modularChangeFamily: ModularChangeFamily,
 		mintRevisionTag: () => RevisionTag,
 		private readonly changeReceiver: (change: TaggedChange<SharedTreeChange>) => void,
+		options?: EditorOptions,
 	) {
 		super(
 			modularChangeFamily,
@@ -63,12 +81,13 @@ export class SharedTreeEditBuilder
 					...taggedChange,
 					change: { changes: [{ type: "data", innerChange: taggedChange.change }] },
 				}),
+			options,
 			modularChangeFamily.codecOptions,
 		);
 
 		this.schema = {
 			setStoredSchema: (oldSchema, newSchema) => {
-				this.changeReceiver({
+				changeReceiver({
 					revision: mintRevisionTag(),
 					change: {
 						changes: [
@@ -86,3 +105,15 @@ export class SharedTreeEditBuilder
 		};
 	}
 }
+
+export class LocationBasedSharedTreeEditBuilder
+	extends LocationBasedDataEditor
+	implements ILocationBasedSharedTreeEditor
+{
+	public readonly schema: ISchemaEditor;
+
+	public constructor(idBasedEditor: IIdBasedSharedTreeEditor, locator: Locator) {
+		super(idBasedEditor, locator);
+		this.schema = idBasedEditor.schema;
+	}
+}