@fluidframework/tree 2.116.0 → 2.117.0

package/dist/shared-tree/treeCheckout.js

@@ -16,10 +16,44 @@ const index_js_4 = require("../shared-tree-core/index.js");
 const index_js_5 = require("../simple-tree/index.js");
 const index_js_6 = require("../util/index.js");
 const schematizingTreeView_js_1 = require("./schematizingTreeView.js");
+const history_js_1 = require("./history.js");
 const sharedTreeChangeEnricher_js_1 = require("./sharedTreeChangeEnricher.js");
 const sharedTreeChangeFamily_js_1 = require("./sharedTreeChangeFamily.js");
 const transactionPostProcessor_js_1 = require("./transactionPostProcessor.js");
 const serializedChange_js_1 = require("./serializedChange.js");
+/**
+ * Returns a defensive copy of the given metadata, validating that it can be persisted.
+ * @remarks
+ * The round-trip through JSON ensures that the value read back locally is exactly the value that peers and
+ * future summaries will see, and that later mutation of the caller's object cannot affect an existing commit.
+ * @throws A `UsageError` if the value cannot be represented as a JSON object.
+ */
+function snapshotCustomMetadata(customMetadata) {
+    if (customMetadata === undefined) {
+        return undefined;
+    }
+    let serialized;
+    try {
+        serialized = JSON.stringify(customMetadata);
+    }
+    catch (error) {
+        throw new internal_2.UsageError(`"customMetadata" must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (serialized === undefined) {
+        throw new internal_2.UsageError(`"customMetadata" must be JSON-serializable.`);
+    }
+    const snapshot = JSON.parse(serialized);
+    if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot)) {
+        throw new internal_2.UsageError(`"customMetadata" must be a JSON object.`);
+    }
+    return snapshot;
+}
+/**
+ * Wraps metadata for an operation which produces a single commit.
+ */
+function toMetadataTree(customMetadata) {
+    return customMetadata === undefined ? undefined : { metadata: customMetadata, children: [] };
+}
 /**
  * Yields all defined (non-`undefined`) labels from a {@link LabelTree}, depth-first.
  */
@@ -84,12 +118,13 @@ function createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, arg
         new index_js_4.SharedTreeBranch({
             change: changeFamily.rebaser.compose([]),
             revision: "root",
+            customMetadata: undefined,
         }, changeFamily, () => idCompressor.generateCompressedId());
     return new TreeCheckout(branch, true, changeFamily, schema, forest, mintRevisionTag, revisionTagCodec, idCompressor, args?.removedRoots);
 }
 exports.createTreeCheckout = createTreeCheckout;
 /**
- * Get the {@link TreeCheckout} associated with a given {@link TreeBranch}.
+ * Get the {@link TreeCheckout} associated with a given {@link UntypedTreeView}.
  */
 function getCheckout(context) {
     if (context instanceof TreeCheckout) {
@@ -205,7 +240,8 @@ let TreeCheckout = (() => {
             constructor(branch, 
             /** True if and only if this checkout is for a branch which is persisted and shared with other clients. */
             isSharedBranch, changeFamily, storedSchema, forest, mintRevisionTag, revisionTagCodec, idCompressor, _removedRoots = (0, index_js_2.makeDetachedFieldIndex)("repair"), disposeForksAfterTransaction = true) {
-                this.isSharedBranch = (tslib_1.__runInitializers(this, _instanceExtraInitializers), isSharedBranch);
+                this.branch = (tslib_1.__runInitializers(this, _instanceExtraInitializers), branch);
+                this.isSharedBranch = isSharedBranch;
                 this.changeFamily = changeFamily;
                 this.storedSchema = storedSchema;
                 this.forest = forest;
@@ -287,7 +323,7 @@ let TreeCheckout = (() => {
                                         throw new internal_2.UsageError("Cannot generate the same revertible more than once. Note that this can happen when multiple changed event listeners are registered.");
                                     }
                                     const revertible = this.createRevertible(revision, kind, this, onRevertibleDisposed, commitLabelTree);
-                                    this.revertibleCommitBranches.set(revision, tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.fork(commit));
+                                    this.revertibleCommitBranches.set(revision, tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.fork(commit));
                                     this.revertibles.set(revision, revertible);
                                     return revertible;
                                 };
@@ -387,6 +423,10 @@ let TreeCheckout = (() => {
                 this.editLock = new EditLock(tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranchEditor);
                 this.registerForBranchEvents();
             }
+            get branchHistory() {
+                this._branchHistory ??= new history_js_1.DefaultTreeBranchHistory(this.branch, this.idCompressor);
+                return this._branchHistory;
+            }
             /**
              * Pushes a new label node for a transaction nesting level.
              *
@@ -585,13 +625,16 @@ let TreeCheckout = (() => {
             applySerializedChange(serializedChange) {
                 const change = serializedChange_js_1.SerializedChange.V1.decode(this.idCompressor, this.changeFamily, serializedChange);
                 // Apply the change to the branch, but _not_ the `activeBranch` - we do not support squashing serialized commits in a transaction.
-                tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.apply(change);
+                tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.apply(change, index_js_2.CommitKind.Default, undefined);
             }
-            // #region TreeBranchAlpha
+            // #region UntypedTreeViewAlpha
             applyChange(change) {
                 this.applySerializedChange(change);
             }
             isBranch() {
+                return this.isView();
+            }
+            isView() {
                 return true;
             }
             hasRootSchema(_schema) {
@@ -624,6 +667,9 @@ let TreeCheckout = (() => {
                 this.pushLabelFrame(params?.label);
                 this.transaction.start({
                     postProcessor: (0, transactionPostProcessor_js_1.extractTransactionChangeProcessor)(params?.postProcessor),
+                    // Like the validation described above, rejecting malformed metadata breaks the checkout rather
+                    // than being recoverable. Tracked by https://github.com/microsoft/FluidFramework/issues/28085.
+                    customMetadata: snapshotCustomMetadata(params?.customMetadata),
                 });
                 addConstraintsToTransaction(this, false, params?.preconditions);
             }
@@ -647,7 +693,7 @@ let TreeCheckout = (() => {
                     ? { success: true }
                     : { success: true, value: value };
             }
-            // #endregion TreeBranchAlpha
+            // #endregion UntypedTreeViewAlpha
             // Revision is the revision of the commit, if any, which caused this change.
             applyInternalChange(change, revision) {
                 // Conflicts due to schema will be empty and thus are not applied.
@@ -717,29 +763,32 @@ let TreeCheckout = (() => {
                             ? index_js_2.RevertibleStatus.Disposed
                             : index_js_2.RevertibleStatus.Valid;
                     },
-                    revert: (release = true) => {
+                    revert: (releaseOrOptions = true) => {
                         if (revertible.status === index_js_2.RevertibleStatus.Disposed) {
                             throw new internal_2.UsageError("Unable to revert a revertible that has been disposed.");
                         }
-                        const revertMetrics = checkout.revertRevertible(revision, kind, labelTree);
+                        const options = typeof releaseOrOptions === "boolean"
+                            ? { dispose: releaseOrOptions }
+                            : releaseOrOptions;
+                        const revertMetrics = checkout.revertRevertible(revision, kind, labelTree, snapshotCustomMetadata(options.customMetadata));
                         checkout.logger?.sendTelemetryEvent({
                             eventName: _a.revertTelemetryEventName,
                             ...revertMetrics,
                         });
-                        if (release) {
+                        if (options.dispose ?? true) {
                             revertible.dispose();
                         }
                     },
-                    clone: (targetBranch) => {
+                    clone: (targetView) => {
                         // TODO:#23442: When a revertible is cloned for a forked branch, optimize to create a fork of a revertible branch once per revision NOT once per revision per checkout.
-                        const targetCheckout = getCheckout(targetBranch);
+                        const targetCheckout = getCheckout(targetView);
                         const revertibleBranch = this.revertibleCommitBranches.get(revision);
                         if (revertibleBranch === undefined) {
                             throw new internal_2.UsageError("Unable to clone a revertible that has been disposed.");
                         }
                         const commitToRevert = revertibleBranch.getHead();
-                        const activeBranchHead = tslib_1.__classPrivateFieldGet(targetCheckout, _TreeCheckout_transaction, "f").activeBranch.getHead();
-                        if ((0, index_js_2.isAncestor)(commitToRevert, activeBranchHead, true) === false) {
+                        const branchHead = tslib_1.__classPrivateFieldGet(targetCheckout, _TreeCheckout_transaction, "f").branch.getHead();
+                        if ((0, index_js_2.isAncestor)(commitToRevert, branchHead, true) === false) {
                             throw new internal_2.UsageError("Cannot clone revertible for a commit that is not present on the given branch.");
                         }
                         targetCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
@@ -782,7 +831,7 @@ let TreeCheckout = (() => {
                 if (this.transaction.size > 0) {
                     throw new internal_2.UsageError("A view cannot be forked while it has a pending transaction.");
                 }
-                const branch = tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.fork();
+                const branch = tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.fork();
                 const storedSchema = this.storedSchema.clone();
                 const forkBreaker = new index_js_6.Breakable("TreeCheckout", this.logger);
                 const forest = this.forest.clone(storedSchema, forkBreaker);
@@ -791,19 +840,65 @@ let TreeCheckout = (() => {
                 return checkout;
             }
             switchBranch(branch) {
-                // TODO: Dispose old branch, if necessary
                 (0, internal_1.assert)(tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").size === 0, 0xc55 /* Cannot switch branches during a transaction */);
+                if (this.isSharedBranch) {
+                    throw new internal_2.UsageError("Cannot switch a view away from a shared branch. Consider forking first.");
+                }
                 const diff = (0, index_js_2.diffHistories)(this.changeFamily.rebaser, tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.getHead(), branch.getHead(), this.mintRevisionTag);
                 this.unregisterFromBranchEvents();
                 tslib_1.__classPrivateFieldSet(this, _TreeCheckout_transaction, this.createTransactionStack(branch), "f");
+                this.branch = branch;
+                this._branchHistory?.dispose();
+                this._branchHistory = undefined;
                 this.editLock = new EditLock(tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranchEditor);
                 this.registerForBranchEvents();
                 // TODO: Rework eventing
                 this.applyInternalChange(diff);
                 tslib_1.__classPrivateFieldGet(this, _TreeCheckout_events, "f").emit("afterBatch");
             }
-            rebase(branch) {
-                const checkout = getCheckout(branch);
+            rewindTo(revisionString) {
+                this.checkNotDisposed("The branch has already been disposed and cannot be rewound.");
+                if (tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").size > 0) {
+                    throw new internal_2.UsageError("Rewinding is not supported during transactions.");
+                }
+                const revision = this.idCompressor.tryRecompress(revisionString);
+                if (revision === undefined) {
+                    throw new internal_2.UsageError(`Unrecognized revision id: ${revisionString}`);
+                }
+                const targetCommit = (0, index_js_2.findAncestor)(tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.getHead(), (commit) => commit.revision === revision);
+                if (targetCommit === undefined) {
+                    throw new internal_2.UsageError(`No commit found with revision: ${revisionString}`);
+                }
+                this.switchBranch(tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.fork(targetCommit));
+            }
+            revertTo(revisionString, options) {
+                this.checkNotDisposed("The branch has already been disposed and prior revisions cannot be reverted to.");
+                this.editLock.checkUnlocked("Reverting to a revision");
+                if (tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").size > 0) {
+                    throw new internal_2.UsageError("Reverting to a revision is not supported during transactions.");
+                }
+                const customMetadata = snapshotCustomMetadata(options?.customMetadata);
+                const revision = this.idCompressor.tryRecompress(revisionString);
+                if (revision === undefined) {
+                    throw new internal_2.UsageError(`Unrecognized revision id: ${revisionString}`);
+                }
+                // Populated with the commits that came after the target commit, from oldest to newest.
+                const commitsToUndo = [];
+                const targetCommit = (0, index_js_2.findAncestor)([tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.getHead(), commitsToUndo], (commit) => commit.revision === revision);
+                if (targetCommit === undefined) {
+                    throw new internal_2.UsageError(`No commit found with revision: ${revisionString}`);
+                }
+                if (!(0, index_js_6.hasSome)(commitsToUndo)) {
+                    // The target commit is already the head of the branch, so there is nothing to revert.
+                    return;
+                }
+                const revisionForInvert = this.mintRevisionTag();
+                const toUndo = this.changeFamily.rebaser.compose(commitsToUndo);
+                const inverse = this.changeFamily.rebaser.invert((0, index_js_2.makeAnonChange)(toUndo), false, revisionForInvert);
+                tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.apply((0, index_js_2.tagChange)(inverse, revisionForInvert), index_js_2.CommitKind.Default, toMetadataTree(customMetadata));
+            }
+            rebase(view) {
+                const checkout = getCheckout(view);
                 this.checkNotDisposed("The target branch of the rebase has been disposed and cannot be rebased.");
                 checkout.checkNotDisposed("The source branch of the rebase has been disposed and cannot be rebased.");
                 this.editLock.checkUnlocked("Rebasing");
@@ -814,16 +909,16 @@ let TreeCheckout = (() => {
                     throw new internal_2.UsageError("A view cannot be rebased while it has a pending transaction.");
                 }
                 (0, internal_1.assert)(!checkout.isSharedBranch, 0xa5d /* Shared branches cannot be rebased onto another branch. */);
-                tslib_1.__classPrivateFieldGet(checkout, _TreeCheckout_transaction, "f").activeBranch.rebaseOnto(tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch);
+                tslib_1.__classPrivateFieldGet(checkout, _TreeCheckout_transaction, "f").branch.rebaseOnto(tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch);
             }
-            rebaseOnto(branch) {
-                getCheckout(branch).rebase(this);
+            rebaseOnto(view) {
+                getCheckout(view).rebase(this);
             }
-            isMissingEditsFrom(branch) {
-                const branchCheckout = getCheckout(branch);
+            isMissingEditsFrom(view) {
+                const viewCheckout = getCheckout(view);
                 const targetPath = [];
                 const ancestor = (0, index_js_2.findCommonAncestor)(this.mainBranch.getHead(), [
-                    branchCheckout.mainBranch.getHead(),
+                    viewCheckout.mainBranch.getHead(),
                     targetPath,
                 ]);
                 if (ancestor === undefined) {
@@ -831,17 +926,17 @@ let TreeCheckout = (() => {
                 }
                 return targetPath.length > 0;
             }
-            computeNetChangeIfRebasedOnto(branch) {
-                const branchCheckout = getCheckout(branch);
-                const rebased = (0, index_js_2.rebaseBranch)(this.mintRevisionTag, this.changeFamily.rebaser, tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.getHead(), tslib_1.__classPrivateFieldGet(branchCheckout, _TreeCheckout_transaction, "f").branch.getHead());
+            computeNetChangeIfRebasedOnto(view) {
+                const viewCheckout = getCheckout(view);
+                const rebased = (0, index_js_2.rebaseBranch)(this.mintRevisionTag, this.changeFamily.rebaser, tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.getHead(), tslib_1.__classPrivateFieldGet(viewCheckout, _TreeCheckout_transaction, "f").branch.getHead());
                 if (rebased.sourceChange === undefined) {
                     return undefined;
                 }
                 const revision = this.mintRevisionTag();
                 return serializedChange_js_1.SerializedChange.V1.encode(this.idCompressor, this.changeFamily, rebased.sourceChange, revision, undefined);
             }
-            merge(branch, disposeMerged = true) {
-                const checkout = getCheckout(branch);
+            merge(view, disposeMerged = true) {
+                const checkout = getCheckout(view);
                 this.checkNotDisposed("The target branch of the merge has been disposed and cannot be merged.");
                 checkout.checkNotDisposed("The source branch of the merge has been disposed and cannot be merged.");
                 this.editLock.checkUnlocked("Merging");
@@ -851,7 +946,7 @@ let TreeCheckout = (() => {
                 if (checkout.transaction.size > 0) {
                     throw new internal_2.UsageError("Views with an open transaction cannot be merged into another view.");
                 }
-                tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.merge(tslib_1.__classPrivateFieldGet(checkout, _TreeCheckout_transaction, "f").activeBranch);
+                tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.merge(tslib_1.__classPrivateFieldGet(checkout, _TreeCheckout_transaction, "f").branch);
                 if (disposeMerged && !checkout.isSharedBranch) {
                     // Dispose the merged checkout unless it is a shared branch.
                     checkout[index_js_6.disposeSymbol]();
@@ -878,6 +973,8 @@ let TreeCheckout = (() => {
                     view.dispose();
                 }
                 tslib_1.__classPrivateFieldGet(this, _TreeCheckout_events, "f").emit("dispose");
+                this._branchHistory?.dispose();
+                this._branchHistory = undefined;
             }
             getRemovedRoots() {
                 this.assertNoUntrackedRoots();
@@ -917,7 +1014,7 @@ let TreeCheckout = (() => {
                 this.revertibleCommitBranches.delete(revision);
                 this.revertibles.delete(revision);
             }
-            revertRevertible(revision, kind, labelTree) {
+            revertRevertible(revision, kind, labelTree, customMetadata) {
                 this.editLock.checkUnlocked("Reverting a commit");
                 if (this.transaction.size > 0) {
                     throw new internal_2.UsageError("Undo is not yet supported during transactions.");
@@ -927,7 +1024,7 @@ let TreeCheckout = (() => {
                 const commitToRevert = revertibleBranch.getHead();
                 const revisionForInvert = this.mintRevisionTag();
                 let change = (0, index_js_2.tagChange)(this.changeFamily.rebaser.invert(commitToRevert, false, revisionForInvert), revisionForInvert);
-                const headCommit = tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.getHead();
+                const headCommit = tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.getHead();
                 // Rebase the inverted change onto any commits that occurred after the undoable commits.
                 if (commitToRevert !== headCommit) {
                     // The inverse may be rebased over newer commits which (despite being present in the history)
@@ -943,9 +1040,9 @@ let TreeCheckout = (() => {
                 const previousLabelTreeNode = this.labelTreeNode;
                 this.labelTreeNode = labelTree;
                 try {
-                    tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.apply(change, kind === index_js_2.CommitKind.Default || kind === index_js_2.CommitKind.Redo
+                    tslib_1.__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.apply(change, kind === index_js_2.CommitKind.Default || kind === index_js_2.CommitKind.Redo
                         ? index_js_2.CommitKind.Undo
-                        : index_js_2.CommitKind.Redo);
+                        : index_js_2.CommitKind.Redo, toMetadataTree(customMetadata));
                 }
                 finally {
                     this.labelTreeNode = previousLabelTreeNode;