@fluid-experimental/tree 0.59.1000 → 0.59.2000-63294

package/src/SharedTree.ts

@@ -66,6 +66,7 @@ import {
 	ghostSessionId,
 	WriteFormat,
 	TreeNodeSequence,
+	InternalizedChange,
 } from './persisted-types';
 import { serialize, SummaryContents } from './Summary';
 import {
@@ -558,16 +559,8 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 	 * @returns the edit history of the tree.
 	 * @public
 	 */
-	public get edits(): OrderedEditSet {
-		return this.editLog;
-	}
-
-	/**
-	 * @returns the edit history of the tree. The format of the contents of edits are subject to change and should not be relied upon.
-	 * @internal
-	 */
-	public get editsInternal(): OrderedEditSet<ChangeInternal> {
-		return this.editLog;
+	public get edits(): OrderedEditSet<InternalizedChange> {
+		return this.editLog as unknown as OrderedEditSet<InternalizedChange>;
 	}
 
 	private deserializeHandle(serializedHandle: string): IFluidHandle<ArrayBufferLike> {
@@ -1133,7 +1126,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 
 		const unifyHistoricalIds = (context: NodeIdContext): void => {
 			for (let i = 0; i < this.editLog.numberOfSequencedEdits; i++) {
-				const edit = this.editsInternal.getEditInSessionAtIndex(i);
+				const edit = this.editLog.getEditInSessionAtIndex(i);
 				convertEditIds(edit, (id) => context.generateNodeId(this.convertToStableNodeId(id)));
 			}
 		};
@@ -1146,7 +1139,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 			unifyHistoricalIds(ghostContext);
 			// The same logic applies to string interning, so intern all the strings in the history (superset of those in the current view)
 			for (let i = 0; i < this.editLog.numberOfSequencedEdits; i++) {
-				this.internStringsFromEdit(this.editsInternal.getEditInSessionAtIndex(i));
+				this.internStringsFromEdit(this.editLog.getEditInSessionAtIndex(i));
 			}
 		} else {
 			// Clients do not have the full history, but all share the same current view (sequenced). They can all finalize the same final
@@ -1174,9 +1167,9 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 	 * should be used instead.
 	 * @public
 	 */
-	public applyEdit(...changes: Change[]): Edit<unknown>;
-	public applyEdit(changes: Change[]): Edit<unknown>;
-	public applyEdit(headOrChanges: Change | Change[], ...tail: Change[]): Edit<unknown> {
+	public applyEdit(...changes: Change[]): Edit<InternalizedChange>;
+	public applyEdit(changes: Change[]): Edit<InternalizedChange>;
+	public applyEdit(headOrChanges: Change | Change[], ...tail: Change[]): Edit<InternalizedChange> {
 		const changes = Array.isArray(headOrChanges) ? headOrChanges : [headOrChanges, ...tail];
 		const id = newEditId();
 		const internalEdit: Edit<ChangeInternal> = {
@@ -1185,7 +1178,34 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		};
 		this.submitEditOp(internalEdit);
 		this.applyEditLocally(internalEdit, undefined);
-		return internalEdit;
+		return internalEdit as unknown as Edit<InternalizedChange>;
+	}
+
+	/**
+	 * Merges `edits` from `other` into this SharedTree.
+	 * @param other - Tree containing the edits that should be applied to this one.
+	 * @param edits - Iterable of edits from `other` to apply.
+	 * @param stableIdRemapper - Optional remapper to translate stable identities from `other` into stable identities on this tree.
+	 * Any references that `other` contains to a stable id `foo` will be replaced with references to the id `stableIdRemapper(foo)`.
+	 *
+	 * Payloads on the edits are left intact.
+	 * @returns a list containing `EditId`s for all applied edits.
+	 */
+	public mergeEditsFrom(
+		other: SharedTree,
+		edits: Iterable<Edit<InternalizedChange>>,
+		stableIdRemapper?: (id: StableNodeId) => StableNodeId
+	): EditId[] {
+		const idConverter = (id: NodeId) => {
+			const stableId = other.convertToStableNodeId(id);
+			const convertedStableId = stableIdRemapper?.(stableId) ?? stableId;
+			return this.generateNodeId(convertedStableId);
+		};
+
+		return Array.from(
+			edits as unknown as Iterable<Edit<ChangeInternal>>,
+			(edit) => this.applyEditInternal(convertEditIds(edit, (id) => idConverter(id))).id
+		);
 	}
 
 	/**
@@ -1305,7 +1325,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 	 */
 	public revert(editId: EditId): EditId | undefined {
 		const index = this.edits.getIndexOfId(editId);
-		const edit = this.editLog.getEditInSessionAtIndex(index);
+		const edit = this.edits.getEditInSessionAtIndex(index);
 		const before = this.logViewer.getRevisionViewInSession(index);
 		const changes = this.revertChanges(edit.changes, before);
 		if (changes === undefined) {
@@ -1322,8 +1342,8 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 	 * @returns the inverse of `changes` or undefined if the changes could not be inverted for the given tree state.
 	 * @internal
 	 */
-	public revertChanges(changes: readonly ChangeInternal[], before: RevisionView): ChangeInternal[] | undefined {
-		return revert(changes, before);
+	public revertChanges(changes: readonly InternalizedChange[], before: RevisionView): ChangeInternal[] | undefined {
+		return revert(changes as unknown as readonly ChangeInternal[], before);
 	}
 
 	/**

package/src/SummaryTestUtilities.ts

@@ -29,7 +29,7 @@ export interface UploadedEditChunkContents {
  */
 export async function getUploadedEditChunkContents(sharedTree: SharedTree): Promise<UploadedEditChunkContents[]> {
 	const editChunks: UploadedEditChunkContents[] = [];
-	const { editChunks: editsOrHandles } = (sharedTree.edits as EditLog<ChangeInternal>).getEditLogSummary();
+	const { editChunks: editsOrHandles } = (sharedTree.edits as unknown as EditLog<ChangeInternal>).getEditLogSummary();
 	for (const { chunk } of editsOrHandles) {
 		if (!Array.isArray(chunk)) {
 			const handle = chunk as FluidEditHandle;

package/src/Transaction.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import { IErrorEvent } from '@fluidframework/common-definitions';
+import { TypedEventEmitter } from '@fluidframework/common-utils';
 import { ChangeInternal, Edit, EditStatus } from './persisted-types';
 import { newEditId } from './EditUtilities';
 import { TreeView } from './TreeView';
@@ -11,11 +13,30 @@ import { SharedTree } from './SharedTree';
 import { GenericTransaction, TransactionInternal } from './TransactionInternal';
 import { CachingLogViewer } from './LogViewer';
 
+/**
+ * An event emitted by a `Transaction` to indicate a state change. See {@link TransactionEvents} for event argument information.
+ * @public
+ */
+export enum TransactionEvent {
+	/**
+	 * `currentView` has changed from `before` to `after`
+	 */
+	ViewChange = 'viewChange',
+}
+
+/**
+ * Events which may be emitted by `Transaction`
+ * @public
+ */
+export interface TransactionEvents extends IErrorEvent {
+	(event: TransactionEvent.ViewChange, listener: (before: TreeView, after: TreeView) => void);
+}
+
 /**
  * Buffers changes to be applied to an isolated view of a `SharedTree` over time before applying them directly to the tree itself as a
  * single edit
  */
-export class Transaction {
+export class Transaction extends TypedEventEmitter<TransactionEvents> {
 	/** The view of the tree when this transaction was created */
 	public readonly startingView: TreeView;
 	private readonly transaction: GenericTransaction;
@@ -26,6 +47,7 @@ export class Transaction {
 	 * @param tree - the `SharedTree` that this transaction applies changes to
 	 */
 	public constructor(public readonly tree: SharedTree) {
+		super();
 		const { currentView } = tree;
 		this.transaction = new GenericTransaction(currentView, new TransactionInternal.Policy());
 		this.startingView = currentView;
@@ -57,7 +79,8 @@ export class Transaction {
 	/**
 	 * Attempt to apply a sequence of changes in this transaction. The `currentView` will be updated to reflect the new tree state after all
 	 * applied changes. If any change fails to apply, the remaining changes will be ignored and this transaction will be automatically
-	 * closed (see `isOpen`). If this transaction is already closed, this method has no effect.
+	 * closed (see `isOpen`). If this transaction is already closed, this method has no effect. This method will emit a
+	 * `TransactionEvent.ViewChange` event at most once per call.
 	 * @param changes - the changes to apply
 	 * @returns either the `EditStatus` of the given changes or the `EditStatus` of the last change before the transaction was closed
 	 */
@@ -66,7 +89,16 @@ export class Transaction {
 	public apply(headOrChanges: Change | Change[], ...tail: Change[]): EditStatus {
 		if (this.isOpen) {
 			const changes = Array.isArray(headOrChanges) ? headOrChanges : [headOrChanges, ...tail];
-			this.transaction.applyChanges(changes.map((c) => this.tree.internalizeChange(c)));
+			if (changes.length > 0) {
+				const previousView = this.currentView;
+				this.transaction.applyChanges(changes.map((c) => this.tree.internalizeChange(c)));
+				if (
+					this.listenerCount(TransactionEvent.ViewChange) > 0 &&
+					!previousView.hasEqualForest(this.currentView)
+				) {
+					this.emit(TransactionEvent.ViewChange, previousView, this.currentView);
+				}
+			}
 		}
 		return this.status;
 	}
@@ -77,10 +109,10 @@ export class Transaction {
 	public closeAndCommit(): void {
 		if (this.isOpen) {
 			if (this.transaction.changes.length > 0) {
-				const edit: Edit<ChangeInternal> = { id: newEditId(), changes: this.transaction.changes };
 				const result = this.transaction.close();
-				if (this.tree.editsInternal instanceof CachingLogViewer) {
-					this.tree.editsInternal.setKnownEditingResult(edit, result);
+				const edit: Edit<ChangeInternal> = { id: newEditId(), changes: result.changes };
+				if (this.tree.edits instanceof CachingLogViewer) {
+					this.tree.edits.setKnownEditingResult(edit, result);
 				}
 				this.tree.applyEditInternal(edit);
 			}

package/src/index.ts

@@ -56,6 +56,7 @@ export {
 	ConstraintEffect,
 	Edit,
 	ChangeInternal,
+	InternalizedChange,
 	ChangeNode,
 	ChangeNode_0_0_2,
 	EditLogSummary,
@@ -135,7 +136,7 @@ export {
 } from './TreeView';
 export { RevisionView, TransactionView } from './RevisionView';
 export { NodeIdContext, NodeIdGenerator, NodeIdConverter } from './NodeIdUtilities';
-export { Transaction } from './Transaction';
+export { Transaction, TransactionEvent, TransactionEvents } from './Transaction';
 
 /**
  * TODO:#61413: Publish test utilities from a separate test package

package/src/persisted-types/0.1.1.ts

@@ -204,6 +204,17 @@ export interface CompressedBuildInternal<TId extends OpSpaceNodeId> {
  */
 export type CompressedBuildNode<TId extends OpSpaceNodeId> = CompressedPlaceholderTree<TId, DetachedSequenceId>;
 
+// TODO: `ChangeInternal`s should be assignable to this type without casting; this will require some test refactoring.
+/**
+ * This type should be used as an opaque handle in the public API for `ChangeInternal` objects.
+ * This is useful for supporting public APIs which involve working with a tree's edit history,
+ * which will involve changes that have already been internalized.
+ * @public
+ */
+export interface InternalizedChange {
+	InternalChangeBrand: '2cae1045-61cf-4ef7-a6a3-8ad920cb7ab3';
+}
+
 /**
  * {@inheritdoc (Change:type)}
  * @public