@fluidframework/tree 2.82.0 → 2.90.0-378676

package/src/index.ts

@@ -296,13 +296,13 @@ export {
 	exportCompatibilitySchemaSnapshot,
 	importCompatibilitySchemaSnapshot,
 	checkCompatibility,
-	checkSchemaCompatibilitySnapshots,
+	snapshotSchemaCompatibility,
 	type SnapshotFileSystem,
 	incrementalSummaryHint,
 	incrementalEncodingPolicyForAllowedTypes,
 	eraseSchemaDetails,
 	eraseSchemaDetailsSubclassable,
-	type SchemaCompatibilitySnapshotsOptions,
+	type SnapshotSchemaCompatibilityOptions,
 	type ArrayPlaceAnchor,
 	createArrayInsertionAnchor,
 } from "./simple-tree/index.js";
@@ -371,4 +371,4 @@ export { TableSchema, type System_TableSchema } from "./tableSchema.js";
 export { asAlpha, asBeta } from "./api.js";
 
 export { TextAsTree, FormattedTextAsTree } from "./text/index.js";
-export { ExtensibleSchemaUnion } from "./extensibleSchemaUnion.js";
+export { ExtensibleUnionNode } from "./extensibleUnionNode.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.82.0";
+export const pkgVersion = "2.90.0-378676";

package/src/shared-tree/independentView.ts

@@ -228,12 +228,18 @@ export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSc
 		defaultIncrementalEncodingPolicy,
 	);
 
-	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {
-		forest,
-		schema: schemaRepository,
-		breaker,
-		codecOptions: options,
-	});
+	const checkout = createTreeCheckout(
+		idCompressor,
+		mintRevisionTag,
+		revisionTagCodec,
+		{ enableDetachedRootEditing: true },
+		{
+			forest,
+			schema: schemaRepository,
+			breaker,
+			codecOptions: options,
+		},
+	);
 
 	if (options?.content !== undefined) {
 		// Any version can be passed down to `makeSchemaCodec` and `makeFieldBatchCodec` here.

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,42 @@ 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(false);
+			initialize(this.checkout, schema, () => {
+				const preparedContent = prepareForInsertionContextless(
+					content as InsertableContent | undefined,
+					this.rootFieldSchema,
+					{
+						schema,
+						policy: defaultSchemaPolicy,
+					},
+					this,
+					schema.rootFieldSchema,
+				);
 
-			this.runTransaction(() => {
-				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]);
+
+			this.checkout.transaction.commit();
 		});
 	}
 
@@ -440,9 +419,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", () => {
@@ -466,10 +443,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");
 		}
@@ -482,9 +455,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");
 	}
@@ -600,7 +570,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

@@ -113,7 +113,7 @@ import {
 } from "./sharedTreeChangeCodecs.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";
 
 /**
@@ -180,7 +180,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;
@@ -311,18 +311,24 @@ export class SharedTreeKernel
 			defaultSchemaPolicy,
 		);
 
-		this.checkout = createTreeCheckout(idCompressor, this.mintRevisionTag, revisionTagCodec, {
-			branch: this.getLocalBranch(),
-			changeFamily,
-			schema,
-			forest,
-			fieldBatchCodec,
-			removedRoots,
-			chunkCompressionStrategy: options.treeEncodeType,
-			logger,
-			breaker: this.breaker,
-			disposeForksAfterTransaction: options.disposeForksAfterTransaction,
-		});
+		this.checkout = createTreeCheckout(
+			idCompressor,
+			this.mintRevisionTag,
+			revisionTagCodec,
+			{ enableDetachedRootEditing: options.enableDetachedRootEditing },
+			{
+				branch: this.getLocalBranch(),
+				changeFamily,
+				schema,
+				forest,
+				fieldBatchCodec,
+				removedRoots,
+				chunkCompressionStrategy: options.treeEncodeType,
+				logger,
+				breaker: this.breaker,
+				disposeForksAfterTransaction: options.disposeForksAfterTransaction,
+			},
+		);
 
 		this.registerSharedBranchForEditing("main", this.checkout);
 		this.registerCheckout("main", this.checkout);
@@ -433,7 +439,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()) {
@@ -558,6 +564,7 @@ export const changeFormatVersionForEditManager = DependentFormatVersion.fromPair
 	[EditManagerFormatVersion.v4, SharedTreeChangeFormatVersion.v4],
 	[EditManagerFormatVersion.vSharedBranches, SharedTreeChangeFormatVersion.v4],
 	[EditManagerFormatVersion.v6, SharedTreeChangeFormatVersion.v5],
+	[EditManagerFormatVersion.vDetachedRoots, SharedTreeChangeFormatVersion.vDetachedRoots],
 ]);
 
 /**
@@ -574,6 +581,7 @@ export const changeFormatVersionForMessage = DependentFormatVersion.fromPairs<
 	[MessageFormatVersion.v4, SharedTreeChangeFormatVersion.v4],
 	[MessageFormatVersion.vSharedBranches, SharedTreeChangeFormatVersion.v4],
 	[MessageFormatVersion.v6, SharedTreeChangeFormatVersion.v5],
+	[MessageFormatVersion.vDetachedRoots, SharedTreeChangeFormatVersion.vDetachedRoots],
 ]);
 
 function getCodecTreeForEditManagerFormat(clientVersion: MinimumVersionForCollab): CodecTree {
@@ -629,6 +637,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
@@ -771,6 +785,7 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	enableSharedBranches: false,
 	writeVersionOverrides: new Map(),
 	allowPossiblyIncompatibleWriteVersionOverrides: false,
+	enableDetachedRootEditing: false,
 };
 
 /**

package/src/shared-tree/sharedTreeChangeCodecs.ts

@@ -61,8 +61,8 @@ export function makeSharedTreeChangeCodecFamily(
 		([format, { modularChange, schemaChange }]) => [
 			format,
 			makeSharedTreeChangeCodec(
-				modularChangeCodecFamily.resolve(modularChange).json,
-				schemaChangeCodecs.resolve(schemaChange).json,
+				modularChangeCodecFamily.resolve(modularChange),
+				schemaChangeCodecs.resolve(schemaChange),
 				options,
 			),
 		],
@@ -99,6 +99,7 @@ export const SharedTreeChangeFormatVersion = strictEnum("SharedTreeChangeFormatV
 	 * Adds support for "no change" constraints.
 	 */
 	v5: 5,
+	vDetachedRoots: "detached-roots|v0.1",
 });
 export type SharedTreeChangeFormatVersion = Values<typeof SharedTreeChangeFormatVersion>;
 
@@ -124,6 +125,13 @@ export const dependenciesForChangeFormat = new Map<
 		SharedTreeChangeFormatVersion.v5,
 		{ modularChange: ModularChangeFormatVersion.v5, schemaChange: SchemaFormatVersion.v1 },
 	],
+	[
+		SharedTreeChangeFormatVersion.vDetachedRoots,
+		{
+			modularChange: ModularChangeFormatVersion.vDetachedRoots,
+			schemaChange: SchemaFormatVersion.v1,
+		},
+	],
 ]);
 
 export function getCodecTreeForChangeFormat(

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,
 		);
 	}
 

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,19 @@ export class SharedTreeEditBuilder
 		};
 	}
 }
+
+export class LocationBasedSharedTreeEditBuilder
+	extends LocationBasedDataEditor
+	implements ILocationBasedSharedTreeEditor
+{
+	public readonly schema: ISchemaEditor;
+
+	public constructor(
+		idBasedEditor: IIdBasedSharedTreeEditor,
+		locator: Locator,
+		options: EditorOptions,
+	) {
+		super(idBasedEditor, locator, options);
+		this.schema = idBasedEditor.schema;
+	}
+}

package/src/shared-tree/tree.ts

@@ -28,7 +28,7 @@ import type { ITreeCheckout } from "./treeCheckout.js";
  * Provides various functions for interacting with {@link TreeNode}s.
  * @remarks
  * This type should only be used via the {@link (Tree:variable)} export.
- * @system @sealed @public
+ * @sealed @public
  */
 export interface Tree extends TreeNodeApi {
 	/**

package/src/shared-tree/treeAlpha.ts

@@ -226,7 +226,7 @@ export interface TreeIdentifierUtils {
  * There should be a way to provide a source for defaulted identifiers for unhydrated node creation, either via these APIs or some way to add them to its output later.
  * If an option were added to these APIs, it could also be used to enable unknown optional fields.
  *
- * @system @sealed @alpha
+ * @sealed @alpha
  */
 export interface TreeAlpha {
 	/**