@fluidframework/tree 2.5.0-302463 → 2.5.0

package/src/core/rebase/utils.ts

@@ -441,8 +441,9 @@ function rollbackFromCommit<TChange>(
 	mintRevisionTag: () => RevisionTag,
 	cache?: boolean,
 ): TaggedChange<TChange, RevisionTag> {
-	if (commit.rollback !== undefined) {
-		return commit.rollback;
+	const rollback = Rollback.get(commit);
+	if (rollback !== undefined) {
+		return rollback;
 	}
 	const tag = mintRevisionTag();
 	const untagged = changeRebaser.invert(commit, true, tag);
@@ -450,7 +451,7 @@ function rollbackFromCommit<TChange>(
 	const fullyTaggedRollback = tagRollbackInverse(deeplyTaggedRollback, tag, commit.revision);
 
 	if (cache === true) {
-		commit.rollback = fullyTaggedRollback;
+		Rollback.set(commit, fullyTaggedRollback);
 	}
 	return fullyTaggedRollback;
 }
@@ -620,3 +621,34 @@ export function findCommonAncestor<T extends { parent?: T }>(
 	}
 	return undefined;
 }
+
+export function replaceChange<TChange>(
+	commit: GraphCommit<TChange>,
+	change: TChange,
+): GraphCommit<TChange> {
+	const output = { ...commit, change };
+	Rollback.set(output, undefined);
+	return output;
+}
+
+/** Associates rollback data with commits */
+namespace Rollback {
+	const map = new WeakMap<GraphCommit<unknown>, TaggedChange<unknown, RevisionTag>>();
+
+	export function get<TChange>(
+		commit: GraphCommit<TChange>,
+	): TaggedChange<TChange, RevisionTag> | undefined {
+		return map.get(commit) as TaggedChange<TChange, RevisionTag> | undefined;
+	}
+
+	export function set<TChange>(
+		commit: GraphCommit<TChange>,
+		rollback: TaggedChange<TChange, RevisionTag> | undefined,
+	): void {
+		if (rollback === undefined) {
+			map.delete(commit);
+		} else {
+			map.set(commit, rollback);
+		}
+	}
+}

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -9,6 +9,7 @@ import {
 	type FieldKey,
 	type FieldKindIdentifier,
 	type FieldUpPath,
+	type ITreeCursorSynchronous,
 	type TreeNodeSchemaIdentifier,
 	type TreeValue,
 	anchorSlot,
@@ -184,6 +185,14 @@ export interface FlexTreeNode extends FlexTreeEntity {
 	 * If well-formed, it must follow this schema.
 	 */
 	readonly schema: TreeNodeSchemaIdentifier;
+
+	/**
+	 * Get a cursor for the underlying data.
+	 * @remarks
+	 * This cursor might be one the node uses in its implementation, and thus must be returned to its original location before using any other APIs to interact with the tree.
+	 * Must not be held onto across edits or any other tree API use.
+	 */
+	borrowCursor(): ITreeCursorSynchronous;
 }
 
 /**

package/src/feature-libraries/flex-tree/lazyNode.ts

@@ -10,6 +10,7 @@ import {
 	type AnchorNode,
 	CursorLocationType,
 	type FieldKey,
+	type ITreeCursorSynchronous,
 	type FieldKindIdentifier,
 	type ITreeSubscriptionCursor,
 	type TreeNavigationResult,
@@ -91,6 +92,10 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements FlexTreeNode {
 		this.#removeDeleteCallback = anchorNode.on("afterDestroy", cleanupTree);
 	}
 
+	public borrowCursor(): ITreeCursorSynchronous {
+		return this[cursorSymbol] as ITreeCursorSynchronous;
+	}
+
 	protected override [tryMoveCursorToAnchorSymbol](
 		cursor: ITreeSubscriptionCursor,
 	): TreeNavigationResult {

package/src/index.ts

@@ -58,8 +58,12 @@ export {
 	rollback,
 	type ForestOptions,
 	getBranch,
-	type TreeBranch,
+	type BranchableTree,
 	type TreeBranchFork,
+	independentInitializedView,
+	type ViewContent,
+	TreeAlpha,
+	independentView,
 } from "./shared-tree/index.js";
 
 export {
@@ -133,6 +137,8 @@ export {
 	type InsertableContent,
 	type FactoryContent,
 	type FactoryContentObject,
+	type ReadableField,
+	type ReadSchema,
 	// test recursive schema for checking that d.ts files handles schema correctly
 	test_RecursiveObject,
 	test_RecursiveObject_base,
@@ -140,8 +146,13 @@ export {
 	// Beta APIs
 	TreeBeta,
 	type TreeChangeEventsBeta,
+	type VerboseTreeNode,
+	type EncodeOptions,
+	type ParseOptions,
+	type VerboseTree,
 	extractPersistedSchema,
 	comparePersistedSchema,
+	type ConciseTree,
 	// Back to normal types
 	type JsonTreeSchema,
 	type JsonSchemaId,
@@ -162,16 +173,20 @@ export {
 	type ReadonlyArrayNode,
 	type InsertableTreeNodeFromAllowedTypes,
 	type Input,
+	type TreeBranch,
+	type TreeBranchEvents,
+	asTreeViewAlpha,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,
 	configuredSharedTree,
 } from "./treeFactory.js";
 
-export type {
-	ICodecOptions,
-	JsonValidator,
-	SchemaValidationFunction,
+export {
+	type ICodecOptions,
+	type JsonValidator,
+	type SchemaValidationFunction,
+	FluidClientVersion,
 } from "./codec/index.js";
 export { noopValidator } from "./codec/index.js";
 export { typeboxValidator } from "./external-utilities/index.js";

package/src/packageVersion.ts

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

package/src/shared-tree/independentView.ts

@@ -0,0 +1,176 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils/internal";
+import {
+	type IIdCompressor,
+	createIdCompressor,
+} from "@fluidframework/id-compressor/internal";
+import type { ICodecOptions } from "../codec/index.js";
+import {
+	type RevisionTag,
+	RevisionTagCodec,
+	TreeStoredSchemaRepository,
+	initializeForest,
+	type ITreeCursorSynchronous,
+	mapCursorField,
+} from "../core/index.js";
+import {
+	createNodeKeyManager,
+	makeFieldBatchCodec,
+	makeSchemaCodec,
+	type FieldBatchEncodingContext,
+	defaultSchemaPolicy,
+	chunkTree,
+	defaultChunkPolicy,
+	TreeCompressionStrategy,
+} from "../feature-libraries/index.js";
+// eslint-disable-next-line import/no-internal-modules
+import type { Format } from "../feature-libraries/schema-index/format.js";
+import type {
+	TreeViewConfiguration,
+	ImplicitFieldSchema,
+	TreeViewAlpha,
+} from "../simple-tree/index.js";
+import type { JsonCompatibleReadOnly, JsonCompatible } from "../util/index.js";
+import {
+	buildConfiguredForest,
+	defaultSharedTreeOptions,
+	type ForestOptions,
+} from "./sharedTree.js";
+import { createTreeCheckout } from "./treeCheckout.js";
+import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+
+/**
+ * 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.
+ *
+ * This can be useful for testing, as well as use-cases like working on local files instead of documents stored in some Fluid service.
+ * @alpha
+ */
+export function independentView<const TSchema extends ImplicitFieldSchema>(
+	config: TreeViewConfiguration<TSchema>,
+	options: ForestOptions & { idCompressor?: IIdCompressor | undefined },
+): TreeViewAlpha<TSchema> {
+	const idCompressor: IIdCompressor = options.idCompressor ?? createIdCompressor();
+	const mintRevisionTag = (): RevisionTag => idCompressor.generateCompressedId();
+	const revisionTagCodec = new RevisionTagCodec(idCompressor);
+	const schema = new TreeStoredSchemaRepository();
+	const forest = buildConfiguredForest(
+		options.forest ?? defaultSharedTreeOptions.forest,
+		schema,
+		idCompressor,
+	);
+	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {
+		forest,
+		schema,
+	});
+	const out: TreeViewAlpha<TSchema> = new SchematizingSimpleTreeView<TSchema>(
+		checkout,
+		config,
+		createNodeKeyManager(idCompressor),
+	);
+	return out;
+}
+/**
+ * Create an initialized {@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.
+ *
+ * This can be useful for testing, as well as use-cases like working on local files instead of documents stored in some Fluid service.
+ * @alpha
+ */
+export function independentInitializedView<const TSchema extends ImplicitFieldSchema>(
+	config: TreeViewConfiguration<TSchema>,
+	options: ForestOptions & ICodecOptions,
+	content: ViewContent,
+): TreeViewAlpha<TSchema> {
+	const idCompressor: IIdCompressor = content.idCompressor;
+	const mintRevisionTag = (): RevisionTag => idCompressor.generateCompressedId();
+	const revisionTagCodec = new RevisionTagCodec(idCompressor);
+
+	const fieldBatchCodec = makeFieldBatchCodec(options, 1);
+	const schemaCodec = makeSchemaCodec(options);
+
+	const schema = new TreeStoredSchemaRepository(schemaCodec.decode(content.schema as Format));
+	const forest = buildConfiguredForest(
+		options.forest ?? defaultSharedTreeOptions.forest,
+		schema,
+		idCompressor,
+	);
+
+	const context: FieldBatchEncodingContext = {
+		encodeType: TreeCompressionStrategy.Compressed,
+		idCompressor,
+		originatorId: idCompressor.localSessionId, // Is this right? If so, why is is needed?
+		schema: { schema, policy: defaultSchemaPolicy },
+	};
+
+	const fieldCursors = fieldBatchCodec.decode(content.tree as JsonCompatibleReadOnly, context);
+	assert(fieldCursors.length === 1, 0xa5b /* must have exactly 1 field in batch */);
+	// Checked above.
+	// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+	const cursors = fieldCursorToNodesCursors(fieldCursors[0]!);
+
+	initializeForest(forest, cursors, revisionTagCodec, idCompressor, false);
+
+	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {
+		forest,
+		schema,
+	});
+	const out: TreeViewAlpha<TSchema> = new SchematizingSimpleTreeView<TSchema>(
+		checkout,
+		config,
+		createNodeKeyManager(idCompressor),
+	);
+	return out;
+}
+
+function fieldCursorToNodesCursors(
+	fieldCursor: ITreeCursorSynchronous,
+): ITreeCursorSynchronous[] {
+	return mapCursorField(fieldCursor, copyNodeCursor);
+}
+
+/**
+ * TODO: avoid needing this, or optimize it.
+ */
+function copyNodeCursor(cursor: ITreeCursorSynchronous): ITreeCursorSynchronous {
+	const copy = chunkTree(cursor, {
+		policy: defaultChunkPolicy,
+		idCompressor: undefined,
+	}).cursor();
+	copy.enterNode(0);
+	return copy;
+}
+
+/**
+ * The portion of SharedTree data typically persisted by the container.
+ * Usable with {@link independentInitializedView} to create a {@link TreeView}
+ * without loading a container.
+ * @alpha
+ */
+export interface ViewContent {
+	/**
+	 * Compressed tree from {@link TreeAlpha.exportCompressed}.
+	 * @remarks
+	 * This is an owning reference:
+	 * consumers of this content might modify this data in place (for example when applying edits) to avoid copying.
+	 */
+	readonly tree: JsonCompatible<IFluidHandle>;
+	/**
+	 * Persisted schema from {@link extractPersistedSchema}.
+	 */
+	readonly schema: JsonCompatible;
+	/**
+	 * IIdCompressor which will be used to decompress any compressed identifiers in `tree`
+	 * as well as for any other identifiers added to the view.
+	 */
+	readonly idCompressor: IIdCompressor;
+}

package/src/shared-tree/index.ts

@@ -26,7 +26,7 @@ export {
 	type CheckoutEvents,
 	type ITransaction,
 	type ITreeCheckoutFork,
-	type TreeBranch,
+	type BranchableTree,
 	type TreeBranchFork,
 } from "./treeCheckout.js";
 
@@ -46,3 +46,11 @@ export {
 	type RunTransaction,
 	rollback,
 } from "./treeApi.js";
+
+export { TreeAlpha } from "./treeApiAlpha.js";
+
+export {
+	independentInitializedView,
+	type ViewContent,
+	independentView,
+} from "./independentView.js";

package/src/shared-tree/schematizingTreeView.ts

@@ -29,8 +29,6 @@ import {
 	type FieldSchema,
 	type ImplicitFieldSchema,
 	type SchemaCompatibilityStatus,
-	type InsertableTreeFieldFromImplicitField,
-	type TreeFieldFromImplicitField,
 	type TreeView,
 	type TreeViewEvents,
 	getTreeNodeForField,
@@ -43,13 +41,23 @@ import {
 	prepareContentForHydration,
 	comparePersistedSchemaInternal,
 	toStoredSchema,
+	type TreeViewAlpha,
+	type InsertableField,
+	type ReadableField,
+	type ReadSchema,
+	type UnsafeUnknownSchema,
+	type TreeBranch,
 } from "../simple-tree/index.js";
 import { Breakable, breakingClass, disposeSymbol, type WithBreakable } from "../util/index.js";
 
 import { canInitialize, ensureSchema, initialize } from "./schematizeTree.js";
 import type { ITreeCheckout, TreeCheckout } from "./treeCheckout.js";
 import { CheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
-import { HydratedContext, SimpleContextSlot } from "../simple-tree/index.js";
+import {
+	HydratedContext,
+	SimpleContextSlot,
+	areImplicitFieldSchemaEqual,
+} from "../simple-tree/index.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.
@@ -60,8 +68,9 @@ export const ViewSlot = anchorSlot<TreeView<ImplicitFieldSchema>>();
  * Implementation of TreeView wrapping a FlexTreeView.
  */
 @breakingClass
-export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitFieldSchema>
-	implements TreeView<TRootSchema>, WithBreakable
+export class SchematizingSimpleTreeView<
+	in out TRootSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
+> implements TreeBranch, TreeViewAlpha<TRootSchema>, WithBreakable
 {
 	/**
 	 * The view is set to undefined when this object is disposed or the view schema does not support viewing the document's stored schema.
@@ -96,7 +105,7 @@ export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitField
 
 	public constructor(
 		public readonly checkout: TreeCheckout,
-		public readonly config: TreeViewConfiguration<TRootSchema>,
+		public readonly config: TreeViewConfiguration<ReadSchema<TRootSchema>>,
 		public readonly nodeKeyManager: NodeKeyManager,
 		public readonly breaker: Breakable = new Breakable("SchematizingSimpleTreeView"),
 		private readonly onDispose?: () => void,
@@ -130,11 +139,17 @@ export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitField
 		);
 	}
 
-	public get schema(): TRootSchema {
+	public hasRootSchema<TSchema extends ImplicitFieldSchema>(
+		schema: TSchema,
+	): this is TreeViewAlpha<TSchema> {
+		return areImplicitFieldSchemaEqual(this.rootFieldSchema, schema);
+	}
+
+	public get schema(): ReadSchema<TRootSchema> {
 		return this.config.schema;
 	}
 
-	public initialize(content: InsertableTreeFieldFromImplicitField<TRootSchema>): void {
+	public initialize(content: InsertableField<TRootSchema>): void {
 		this.ensureUndisposed();
 
 		const compatibility = this.compatibility;
@@ -338,9 +353,13 @@ export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitField
 		this.checkout.forest.anchors.slots.delete(ViewSlot);
 		this.currentCompatibility = undefined;
 		this.onDispose?.();
+		if (this.checkout.isBranch && !this.checkout.disposed) {
+			// All (non-main) branches are 1:1 with views, so if a user manually disposes a view, we should also dispose the checkout/branch.
+			this.checkout.dispose();
+		}
 	}
 
-	public get root(): TreeFieldFromImplicitField<TRootSchema> {
+	public get root(): ReadableField<TRootSchema> {
 		this.breaker.use();
 		if (!this.compatibility.canView) {
 			throw new UsageError(
@@ -348,10 +367,10 @@ export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitField
 			);
 		}
 		const view = this.getView();
-		return getTreeNodeForField(view.flexTree) as TreeFieldFromImplicitField<TRootSchema>;
+		return getTreeNodeForField(view.flexTree) as ReadableField<TRootSchema>;
 	}
 
-	public set root(newRoot: InsertableTreeFieldFromImplicitField<TRootSchema>) {
+	public set root(newRoot: InsertableField<TRootSchema>) {
 		this.breaker.use();
 		if (!this.compatibility.canView) {
 			throw new UsageError(
@@ -365,6 +384,34 @@ export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitField
 			newRoot as InsertableContent | undefined,
 		);
 	}
+
+	// #region Branching
+
+	public fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TRootSchema> {
+		return this.checkout.branch().viewWith(this.config);
+	}
+
+	public merge(context: TreeBranch, disposeMerged = true): void {
+		this.checkout.merge(getCheckout(context), disposeMerged);
+	}
+
+	public rebaseOnto(context: TreeBranch): void {
+		getCheckout(context).rebase(this.checkout);
+	}
+
+	// #endregion Branching
+}
+
+/**
+ * Get the {@link TreeCheckout} associated with a given {@link TreeBranch}.
+ * @remarks Currently, all contexts are also {@link SchematizingSimpleTreeView}s.
+ * Other checkout implementations (e.g. not associated with a view) may be supported in the future.
+ */
+function getCheckout(context: TreeBranch): TreeCheckout {
+	if (context instanceof SchematizingSimpleTreeView) {
+		return context.checkout;
+	}
+	throw new UsageError("Unsupported context implementation");
 }
 
 /**

package/src/shared-tree/sharedTree.ts

@@ -53,8 +53,11 @@ import {
 import type {
 	ITree,
 	ImplicitFieldSchema,
+	ReadSchema,
 	TreeView,
+	TreeViewAlpha,
 	TreeViewConfiguration,
+	UnsafeUnknownSchema,
 } from "../simple-tree/index.js";
 
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
@@ -65,7 +68,7 @@ import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import {
 	type CheckoutEvents,
 	type TreeCheckout,
-	type TreeBranch,
+	type BranchableTree,
 	createTreeCheckout,
 } from "./treeCheckout.js";
 import { breakingClass, throwIfBroken } from "../util/index.js";
@@ -324,10 +327,21 @@ export class SharedTree
 		}
 	}
 
+	// For the new TreeViewAlpha API
+	public viewWith<TRoot extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+		config: TreeViewConfiguration<ReadSchema<TRoot>>,
+	): SchematizingSimpleTreeView<TRoot> & TreeView<ReadSchema<TRoot>>;
+
+	// For the old TreeView API
 	public viewWith<TRoot extends ImplicitFieldSchema>(
 		config: TreeViewConfiguration<TRoot>,
-	): SchematizingSimpleTreeView<TRoot> {
-		return this.checkout.viewWith(config);
+	): SchematizingSimpleTreeView<TRoot> & TreeView<TRoot>;
+
+	public viewWith<TRoot extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+		config: TreeViewConfiguration<ReadSchema<TRoot>>,
+	): SchematizingSimpleTreeView<TRoot> & TreeView<ReadSchema<TRoot>> {
+		return this.checkout.viewWith(config) as SchematizingSimpleTreeView<TRoot> &
+			TreeView<ReadSchema<TRoot>>;
 	}
 
 	protected override async loadCore(services: IChannelStorageService): Promise<void> {
@@ -338,32 +352,36 @@ export class SharedTree
 }
 
 /**
- * Get a {@link TreeBranch} from a {@link ITree}.
+ * Get a {@link BranchableTree} from a {@link ITree}.
  * @remarks The branch can be used for "version control"-style coordination of edits on the tree.
  * @privateRemarks This function will be removed if/when the branching API becomes public,
  * but it (or something like it) is necessary in the meantime to prevent the alpha types from being exposed as public.
  * @alpha
+ * @deprecated This API is superseded by {@link TreeBranch}, which should be used instead.
  */
-export function getBranch(tree: ITree): TreeBranch;
+export function getBranch(tree: ITree): BranchableTree;
 /**
- * Get a {@link TreeBranch} from a {@link TreeView}.
+ * Get a {@link BranchableTree} from a {@link TreeView}.
  * @remarks The branch can be used for "version control"-style coordination of edits on the tree.
  * Branches are currently an unstable "alpha" API and are subject to change in the future.
  * @privateRemarks This function will be removed if/when the branching API becomes public,
  * but it (or something like it) is necessary in the meantime to prevent the alpha types from being exposed as public.
  * @alpha
+ * @deprecated This API is superseded by {@link TreeBranch}, which should be used instead.
  */
-export function getBranch<T extends ImplicitFieldSchema>(view: TreeView<T>): TreeBranch;
-export function getBranch<T extends ImplicitFieldSchema>(
-	treeOrView: ITree | TreeView<T>,
-): TreeBranch {
+export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+	view: TreeViewAlpha<T>,
+): BranchableTree;
+export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+	treeOrView: ITree | TreeViewAlpha<T>,
+): BranchableTree {
 	assert(
 		treeOrView instanceof SharedTree || treeOrView instanceof SchematizingSimpleTreeView,
 		0xa48 /* Unsupported implementation */,
 	);
 	const checkout: TreeCheckout = treeOrView.checkout;
 	// This cast is safe so long as TreeCheckout supports all the operations on the branch interface.
-	return checkout as unknown as TreeBranch;
+	return checkout as unknown as BranchableTree;
 }
 
 /**