@fluidframework/tree 2.116.0 → 2.117.0

package/lib/shared-tree/treeCheckout.js

@@ -7,16 +7,50 @@ import { createEmitter } from "@fluid-internal/client-utils";
 import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { FluidClientVersion, FormatValidatorNoOp, } from "../codec/index.js";
-import { CommitKind, CommitOutcome, RevertibleStatus, TreeStoredSchemaRepository, combineVisitors, makeDetachedFieldIndex, rebaseChange, rootFieldKey, tagChange, visitDelta, isAncestor, moveToDetachedField, LeafNodeStoredSchema, diffHistories, makeAnonChange, deltaFieldMapHasVisibleChanges, findCommonAncestor, rebaseBranch, } from "../core/index.js";
+import { CommitKind, CommitOutcome, RevertibleStatus, TreeStoredSchemaRepository, combineVisitors, makeDetachedFieldIndex, rebaseChange, rootFieldKey, tagChange, visitDelta, isAncestor, moveToDetachedField, LeafNodeStoredSchema, diffHistories, makeAnonChange, deltaFieldMapHasVisibleChanges, findCommonAncestor, rebaseBranch, findAncestor, } from "../core/index.js";
 import { allowsRepoSuperset, buildForest, createNodeIdentifierManager, defaultSchemaPolicy, fieldBatchCodecBuilder, TreeStatus, intoDelta, jsonableTreeFromCursor, } from "../feature-libraries/index.js";
 import { SquashingTransactionStack, SharedTreeBranch, TransactionResult as InternalTransactionResult, } from "../shared-tree-core/index.js";
 import { getInnerNode, getKernel, customFromCursorStored, } from "../simple-tree/index.js";
 import { Breakable, breakingMethod, disposeSymbol, getOrCreate, hasSome, throwIfBroken, } from "../util/index.js";
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+import { DefaultTreeBranchHistory } from "./history.js";
 import { SharedTreeChangeEnricher } from "./sharedTreeChangeEnricher.js";
 import { ConstraintStatus, SharedTreeChangeFamily, getConstraintStatus, hasSchemaChange, } from "./sharedTreeChangeFamily.js";
 import { extractTransactionChangeProcessor } from "./transactionPostProcessor.js";
 import { SerializedChange } from "./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 UsageError(`"customMetadata" must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (serialized === undefined) {
+        throw new UsageError(`"customMetadata" must be JSON-serializable.`);
+    }
+    const snapshot = JSON.parse(serialized);
+    if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot)) {
+        throw new 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.
  */
@@ -81,11 +115,12 @@ export function createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCod
         new 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);
 }
 /**
- * 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) {
@@ -199,7 +234,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 = makeDetachedFieldIndex("repair"), disposeForksAfterTransaction = true) {
-                this.isSharedBranch = (__runInitializers(this, _instanceExtraInitializers), isSharedBranch);
+                this.branch = (__runInitializers(this, _instanceExtraInitializers), branch);
+                this.isSharedBranch = isSharedBranch;
                 this.changeFamily = changeFamily;
                 this.storedSchema = storedSchema;
                 this.forest = forest;
@@ -281,7 +317,7 @@ let TreeCheckout = (() => {
                                         throw new 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, __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.fork(commit));
+                                    this.revertibleCommitBranches.set(revision, __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.fork(commit));
                                     this.revertibles.set(revision, revertible);
                                     return revertible;
                                 };
@@ -381,6 +417,10 @@ let TreeCheckout = (() => {
                 this.editLock = new EditLock(__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranchEditor);
                 this.registerForBranchEvents();
             }
+            get branchHistory() {
+                this._branchHistory ??= new DefaultTreeBranchHistory(this.branch, this.idCompressor);
+                return this._branchHistory;
+            }
             /**
              * Pushes a new label node for a transaction nesting level.
              *
@@ -579,13 +619,16 @@ let TreeCheckout = (() => {
             applySerializedChange(serializedChange) {
                 const change = 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.
-                __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.apply(change);
+                __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.apply(change, CommitKind.Default, undefined);
             }
-            // #region TreeBranchAlpha
+            // #region UntypedTreeViewAlpha
             applyChange(change) {
                 this.applySerializedChange(change);
             }
             isBranch() {
+                return this.isView();
+            }
+            isView() {
                 return true;
             }
             hasRootSchema(_schema) {
@@ -618,6 +661,9 @@ let TreeCheckout = (() => {
                 this.pushLabelFrame(params?.label);
                 this.transaction.start({
                     postProcessor: 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);
             }
@@ -641,7 +687,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.
@@ -711,29 +757,32 @@ let TreeCheckout = (() => {
                             ? RevertibleStatus.Disposed
                             : RevertibleStatus.Valid;
                     },
-                    revert: (release = true) => {
+                    revert: (releaseOrOptions = true) => {
                         if (revertible.status === RevertibleStatus.Disposed) {
                             throw new 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 UsageError("Unable to clone a revertible that has been disposed.");
                         }
                         const commitToRevert = revertibleBranch.getHead();
-                        const activeBranchHead = __classPrivateFieldGet(targetCheckout, _TreeCheckout_transaction, "f").activeBranch.getHead();
-                        if (isAncestor(commitToRevert, activeBranchHead, true) === false) {
+                        const branchHead = __classPrivateFieldGet(targetCheckout, _TreeCheckout_transaction, "f").branch.getHead();
+                        if (isAncestor(commitToRevert, branchHead, true) === false) {
                             throw new UsageError("Cannot clone revertible for a commit that is not present on the given branch.");
                         }
                         targetCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
@@ -776,7 +825,7 @@ let TreeCheckout = (() => {
                 if (this.transaction.size > 0) {
                     throw new UsageError("A view cannot be forked while it has a pending transaction.");
                 }
-                const branch = __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.fork();
+                const branch = __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.fork();
                 const storedSchema = this.storedSchema.clone();
                 const forkBreaker = new Breakable("TreeCheckout", this.logger);
                 const forest = this.forest.clone(storedSchema, forkBreaker);
@@ -785,19 +834,65 @@ let TreeCheckout = (() => {
                 return checkout;
             }
             switchBranch(branch) {
-                // TODO: Dispose old branch, if necessary
                 assert(__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").size === 0, 0xc55 /* Cannot switch branches during a transaction */);
+                if (this.isSharedBranch) {
+                    throw new UsageError("Cannot switch a view away from a shared branch. Consider forking first.");
+                }
                 const diff = diffHistories(this.changeFamily.rebaser, __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.getHead(), branch.getHead(), this.mintRevisionTag);
                 this.unregisterFromBranchEvents();
                 __classPrivateFieldSet(this, _TreeCheckout_transaction, this.createTransactionStack(branch), "f");
+                this.branch = branch;
+                this._branchHistory?.dispose();
+                this._branchHistory = undefined;
                 this.editLock = new EditLock(__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranchEditor);
                 this.registerForBranchEvents();
                 // TODO: Rework eventing
                 this.applyInternalChange(diff);
                 __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 (__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").size > 0) {
+                    throw new UsageError("Rewinding is not supported during transactions.");
+                }
+                const revision = this.idCompressor.tryRecompress(revisionString);
+                if (revision === undefined) {
+                    throw new UsageError(`Unrecognized revision id: ${revisionString}`);
+                }
+                const targetCommit = findAncestor(__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.getHead(), (commit) => commit.revision === revision);
+                if (targetCommit === undefined) {
+                    throw new UsageError(`No commit found with revision: ${revisionString}`);
+                }
+                this.switchBranch(__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 (__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").size > 0) {
+                    throw new 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 UsageError(`Unrecognized revision id: ${revisionString}`);
+                }
+                // Populated with the commits that came after the target commit, from oldest to newest.
+                const commitsToUndo = [];
+                const targetCommit = findAncestor([__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.getHead(), commitsToUndo], (commit) => commit.revision === revision);
+                if (targetCommit === undefined) {
+                    throw new UsageError(`No commit found with revision: ${revisionString}`);
+                }
+                if (!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(makeAnonChange(toUndo), false, revisionForInvert);
+                __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.apply(tagChange(inverse, revisionForInvert), 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");
@@ -808,16 +903,16 @@ let TreeCheckout = (() => {
                     throw new UsageError("A view cannot be rebased while it has a pending transaction.");
                 }
                 assert(!checkout.isSharedBranch, 0xa5d /* Shared branches cannot be rebased onto another branch. */);
-                __classPrivateFieldGet(checkout, _TreeCheckout_transaction, "f").activeBranch.rebaseOnto(__classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch);
+                __classPrivateFieldGet(checkout, _TreeCheckout_transaction, "f").branch.rebaseOnto(__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 = findCommonAncestor(this.mainBranch.getHead(), [
-                    branchCheckout.mainBranch.getHead(),
+                    viewCheckout.mainBranch.getHead(),
                     targetPath,
                 ]);
                 if (ancestor === undefined) {
@@ -825,17 +920,17 @@ let TreeCheckout = (() => {
                 }
                 return targetPath.length > 0;
             }
-            computeNetChangeIfRebasedOnto(branch) {
-                const branchCheckout = getCheckout(branch);
-                const rebased = rebaseBranch(this.mintRevisionTag, this.changeFamily.rebaser, __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.getHead(), __classPrivateFieldGet(branchCheckout, _TreeCheckout_transaction, "f").branch.getHead());
+            computeNetChangeIfRebasedOnto(view) {
+                const viewCheckout = getCheckout(view);
+                const rebased = rebaseBranch(this.mintRevisionTag, this.changeFamily.rebaser, __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.getHead(), __classPrivateFieldGet(viewCheckout, _TreeCheckout_transaction, "f").branch.getHead());
                 if (rebased.sourceChange === undefined) {
                     return undefined;
                 }
                 const revision = this.mintRevisionTag();
                 return 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");
@@ -845,7 +940,7 @@ let TreeCheckout = (() => {
                 if (checkout.transaction.size > 0) {
                     throw new UsageError("Views with an open transaction cannot be merged into another view.");
                 }
-                __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.merge(__classPrivateFieldGet(checkout, _TreeCheckout_transaction, "f").activeBranch);
+                __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.merge(__classPrivateFieldGet(checkout, _TreeCheckout_transaction, "f").branch);
                 if (disposeMerged && !checkout.isSharedBranch) {
                     // Dispose the merged checkout unless it is a shared branch.
                     checkout[disposeSymbol]();
@@ -872,6 +967,8 @@ let TreeCheckout = (() => {
                     view.dispose();
                 }
                 __classPrivateFieldGet(this, _TreeCheckout_events, "f").emit("dispose");
+                this._branchHistory?.dispose();
+                this._branchHistory = undefined;
             }
             getRemovedRoots() {
                 this.assertNoUntrackedRoots();
@@ -911,7 +1008,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 UsageError("Undo is not yet supported during transactions.");
@@ -921,7 +1018,7 @@ let TreeCheckout = (() => {
                 const commitToRevert = revertibleBranch.getHead();
                 const revisionForInvert = this.mintRevisionTag();
                 let change = tagChange(this.changeFamily.rebaser.invert(commitToRevert, false, revisionForInvert), revisionForInvert);
-                const headCommit = __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.getHead();
+                const headCommit = __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)
@@ -937,9 +1034,9 @@ let TreeCheckout = (() => {
                 const previousLabelTreeNode = this.labelTreeNode;
                 this.labelTreeNode = labelTree;
                 try {
-                    __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").activeBranch.apply(change, kind === CommitKind.Default || kind === CommitKind.Redo
+                    __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").branch.apply(change, kind === CommitKind.Default || kind === CommitKind.Redo
                         ? CommitKind.Undo
-                        : CommitKind.Redo);
+                        : CommitKind.Redo, toMetadataTree(customMetadata));
                 }
                 finally {
                     this.labelTreeNode = previousLabelTreeNode;