@fluidframework/tree 2.10.0-307399 → 2.11.0

package/lib/shared-tree/treeCheckout.js

@@ -2,16 +2,22 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert, oob } from "@fluidframework/core-utils/internal";
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _TreeCheckout_transaction;
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { createEmitter } from "@fluid-internal/client-utils";
 import { UsageError, } from "@fluidframework/telemetry-utils/internal";
 import { noopValidator } from "../codec/index.js";
 import { AnchorSet, CommitKind, RevertibleStatus, TreeStoredSchemaRepository, combineVisitors, makeDetachedFieldIndex, rebaseChange, rootFieldKey, tagChange, visitDelta, } from "../core/index.js";
-import { createEmitter, } from "../events/index.js";
 import { buildForest, createNodeKeyManager, intoDelta, jsonableTreeFromCursor, makeFieldBatchCodec, } from "../feature-libraries/index.js";
-import { SharedTreeBranch, getChangeReplaceType } from "../shared-tree-core/index.js";
-import { Breakable, TransactionResult, disposeSymbol, fail } from "../util/index.js";
+import { SharedTreeBranch, TransactionResult, TransactionStack, getChangeReplaceType, onForkTransitive, } from "../shared-tree-core/index.js";
+import { Breakable, disposeSymbol, fail, getLast, hasSome } from "../util/index.js";
 import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamily.js";
-import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+import { getCheckout, SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 /**
  * Creates a {@link TreeCheckout}.
  * @param args - an object containing optional components that will be used to build the view.
@@ -33,41 +39,17 @@ export function createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCod
             revision: "root",
         }, changeFamily, () => idCompressor.generateCompressedId());
     const events = args?.events ?? createEmitter();
-    const transaction = new Transaction(branch);
-    return new TreeCheckout(transaction, branch, false, changeFamily, schema, forest, events, mintRevisionTag, revisionTagCodec, idCompressor, args?.removedRoots, args?.logger, args?.breaker);
-}
-class Transaction {
-    constructor(branch) {
-        this.branch = branch;
-    }
-    start() {
-        this.branch.startTransaction();
-        this.branch.editor.enterTransaction();
-    }
-    commit() {
-        this.branch.commitTransaction();
-        this.branch.editor.exitTransaction();
-        return TransactionResult.Commit;
-    }
-    abort() {
-        this.branch.abortTransaction();
-        this.branch.editor.exitTransaction();
-        return TransactionResult.Abort;
-    }
-    inProgress() {
-        return this.branch.isTransacting();
-    }
+    return new TreeCheckout(branch, false, changeFamily, schema, forest, events, mintRevisionTag, revisionTagCodec, idCompressor, args?.removedRoots, args?.logger, args?.breaker);
 }
 /**
  * An implementation of {@link ITreeCheckoutFork}.
  */
 export class TreeCheckout {
-    constructor(transaction, _branch, 
+    constructor(_branch, 
     /** True if and only if this checkout is for a forked branch and not the "main branch" of the tree. */
     isBranch, changeFamily, storedSchema, forest, events, mintRevisionTag, revisionTagCodec, idCompressor, removedRoots = makeDetachedFieldIndex("repair", revisionTagCodec, idCompressor), 
     /** Optional logger for telemetry. */
     logger, breaker = new Breakable("TreeCheckout")) {
-        this.transaction = transaction;
         this._branch = _branch;
         this.isBranch = isBranch;
         this.changeFamily = changeFamily;
@@ -93,34 +75,68 @@ export class TreeCheckout {
          */
         this.revertibleCommitBranches = new Map();
         /**
-         * copies of the removed roots used as snapshots for reverting to previous state when transactions are aborted
+         * The {@link Transactor} for this checkout.
+         * @remarks In the context of a checkout, transactions allow edits to be batched into atomic units.
+         * Edits made during a transaction will update the local state of the tree immediately, but will be squashed into a single edit when the transaction is committed.
+         * If the transaction is aborted, the local state will be reset to what it was before the transaction began.
+         * Transactions may nest, meaning that a transaction may be started while a transaction is already ongoing.
+         *
+         * To avoid updating observers of the view state with intermediate results during a transaction,
+         * use {@link ITreeCheckout#branch} and {@link ISharedTreeFork#merge}.
          */
-        this.removedRootsSnapshots = [];
-        // when a transaction is started, take a snapshot of the current state of removed roots
-        _branch.events.on("transactionStarted", () => {
-            this.removedRootsSnapshots.push(this.removedRoots.clone());
-        });
-        // when a transaction is committed, the latest snapshot of removed roots can be discarded
-        _branch.events.on("transactionCommitted", () => {
-            this.removedRootsSnapshots.pop();
-        });
-        // after a transaction is rolled back, revert removed roots back to the latest snapshot
-        _branch.events.on("transactionRolledBack", () => {
-            const snapshot = this.removedRootsSnapshots.pop();
-            assert(snapshot !== undefined, 0x9ae /* a snapshot for removed roots does not exist */);
-            this.removedRoots = snapshot;
-        });
+        _TreeCheckout_transaction.set(this, new TransactionStack(() => {
+            // Keep track of the commit that each transaction was on when it started
+            // TODO:#8603: This may need to be computed differently if we allow rebasing during a transaction.
+            const startCommit = this._branch.getHead();
+            // Keep track of all the forks created during the transaction so that we can dispose them when the transaction ends.
+            // This is a policy decision that we think is useful for the user, but it is not necessary for correctness.
+            const forks = new Set();
+            const onDisposeUnSubscribes = [];
+            const onForkUnSubscribe = onForkTransitive(this, (fork) => {
+                forks.add(fork);
+                onDisposeUnSubscribes.push(fork.events.on("dispose", () => forks.delete(fork)));
+            });
+            // When each transaction is started, take a snapshot of the current state of removed roots
+            const removedRoots = this.removedRoots.clone();
+            this._branch.editor.enterTransaction();
+            return (result) => {
+                this._branch.editor.exitTransaction();
+                switch (result) {
+                    case TransactionResult.Abort:
+                        this._branch.removeAfter(startCommit);
+                        // If a transaction is rolled back, revert removed roots back to the latest snapshot
+                        this.removedRoots = removedRoots;
+                        break;
+                    case TransactionResult.Commit: {
+                        const removedCommits = this._branch.squashAfter(startCommit);
+                        const transactionRevision = this._branch.getHead().revision;
+                        for (const transactionStep of removedCommits) {
+                            this.removedRoots.updateMajor(transactionStep.revision, transactionRevision);
+                        }
+                        break;
+                    }
+                    default:
+                        unreachableCase(result);
+                }
+                forks.forEach((fork) => fork.dispose());
+                onDisposeUnSubscribes.forEach((unsubscribe) => unsubscribe());
+                onForkUnSubscribe();
+            };
+        }));
         // We subscribe to `beforeChange` rather than `afterChange` here because it's possible that the change is invalid WRT our forest.
         // For example, a bug in the editor might produce a malformed change object and thus applying the change to the forest will throw an error.
         // In such a case we will crash here, preventing the change from being added to the commit graph, and preventing `afterChange` from firing.
         // One important consequence of this is that we will not submit the op containing the invalid change, since op submissions happens in response to `afterChange`.
         _branch.events.on("beforeChange", (event) => {
             if (event.change !== undefined) {
-                const revision = event.type === "replace"
-                    ? // Change events will always contain new commits
-                        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                        event.newCommits[event.newCommits.length - 1].revision
-                    : event.change.revision;
+                let revision;
+                if (event.type === "replace") {
+                    assert(hasSome(event.newCommits), 0xa81 /* Expected new commit for non no-op change event */);
+                    revision = getLast(event.newCommits).revision;
+                }
+                else {
+                    revision = event.change.revision;
+                }
                 // Conflicts due to schema will be empty and thus are not applied.
                 for (const change of event.change.change.changes) {
                     if (change.type === "data") {
@@ -153,18 +169,11 @@ export class TreeCheckout {
                 }
                 this.events.emit("afterBatch");
             }
-            if (event.type === "replace" && getChangeReplaceType(event) === "transactionCommit") {
-                const firstCommit = event.newCommits[0] ?? oob();
-                const transactionRevision = firstCommit.revision;
-                for (const transactionStep of event.removedCommits) {
-                    this.removedRoots.updateMajor(transactionStep.revision, transactionRevision);
-                }
-            }
         });
         _branch.events.on("afterChange", (event) => {
             // The following logic allows revertibles to be generated for the change.
             // Currently only appends (including merges) and transaction commits are supported.
-            if (!_branch.isTransacting()) {
+            if (!this.transaction.isInProgress()) {
                 if (event.type === "append" ||
                     (event.type === "replace" && getChangeReplaceType(event) === "transactionCommit")) {
                     // TODO:#20949: When the SharedTree is detached, these commits will already have been garbage collected.
@@ -181,35 +190,7 @@ export class TreeCheckout {
                                 if (this.revertibleCommitBranches.get(revision) !== undefined) {
                                     throw new UsageError("Cannot generate the same revertible more than once. Note that this can happen when multiple changed event listeners are registered.");
                                 }
-                                const revertibleCommits = this.revertibleCommitBranches;
-                                const revertible = {
-                                    get status() {
-                                        const revertibleCommit = revertibleCommits.get(revision);
-                                        return revertibleCommit === undefined
-                                            ? RevertibleStatus.Disposed
-                                            : RevertibleStatus.Valid;
-                                    },
-                                    revert: (release = true) => {
-                                        if (revertible.status === RevertibleStatus.Disposed) {
-                                            throw new UsageError("Unable to revert a revertible that has been disposed.");
-                                        }
-                                        const revertMetrics = this.revertRevertible(revision, kind);
-                                        this.logger?.sendTelemetryEvent({
-                                            eventName: TreeCheckout.revertTelemetryEventName,
-                                            ...revertMetrics,
-                                        });
-                                        if (release) {
-                                            revertible.dispose();
-                                        }
-                                    },
-                                    dispose: () => {
-                                        if (revertible.status === RevertibleStatus.Disposed) {
-                                            throw new UsageError("Unable to dispose a revertible that has already been disposed.");
-                                        }
-                                        this.disposeRevertible(revertible, revision);
-                                        onRevertibleDisposed?.(revertible);
-                                    },
-                                };
+                                const revertible = this.createRevertible(revision, kind, this, onRevertibleDisposed);
                                 this.revertibleCommitBranches.set(revision, _branch.fork(commit));
                                 this.revertibles.add(revertible);
                                 return revertible;
@@ -219,7 +200,7 @@ export class TreeCheckout {
                         withinEventContext = false;
                     }
                 }
-                else if (event.type === "replace") {
+                else if (this.isRemoteChangeEvent(event)) {
                     // TODO: figure out how to plumb through commit kind info for remote changes
                     this.events.emit("changed", { isLocal: false, kind: CommitKind.Default });
                 }
@@ -255,6 +236,59 @@ export class TreeCheckout {
             assert(false, 0x911 /* Invalid operation on a disposed TreeCheckout */);
         }
     }
+    /**
+     * Creates a {@link RevertibleAlpha} object that can undo a specific change in the tree's history.
+     * Revision must exist in the given {@link TreeCheckout}'s branch.
+     *
+     * @param revision - The revision tag identifying the change to be made revertible.
+     * @param kind - The {@link CommitKind} that produced this revertible (e.g., Default, Undo, Redo).
+     * @param checkout - The {@link TreeCheckout} instance this revertible belongs to.
+     * @param onRevertibleDisposed - Callback function that will be called when the revertible is disposed.
+     * @returns - {@link RevertibleAlpha}
+     */
+    createRevertible(revision, kind, checkout, onRevertibleDisposed) {
+        const commitBranches = checkout.revertibleCommitBranches;
+        const revertible = {
+            get status() {
+                const revertibleCommit = commitBranches.get(revision);
+                return revertibleCommit === undefined
+                    ? RevertibleStatus.Disposed
+                    : RevertibleStatus.Valid;
+            },
+            revert: (release = true) => {
+                if (revertible.status === RevertibleStatus.Disposed) {
+                    throw new UsageError("Unable to revert a revertible that has been disposed.");
+                }
+                const revertMetrics = checkout.revertRevertible(revision, kind);
+                checkout.logger?.sendTelemetryEvent({
+                    eventName: TreeCheckout.revertTelemetryEventName,
+                    ...revertMetrics,
+                });
+                if (release) {
+                    revertible.dispose();
+                }
+            },
+            clone: (forkedBranch) => {
+                if (forkedBranch === undefined) {
+                    return this.createRevertible(revision, kind, checkout, onRevertibleDisposed);
+                }
+                // 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 forkedCheckout = getCheckout(forkedBranch);
+                const revertibleBranch = this.revertibleCommitBranches.get(revision);
+                assert(revertibleBranch !== undefined, 0xa82 /* change to revert does not exist on the given forked branch */);
+                forkedCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
+                return this.createRevertible(revision, kind, forkedCheckout, onRevertibleDisposed);
+            },
+            dispose: () => {
+                if (revertible.status === RevertibleStatus.Disposed) {
+                    throw new UsageError("Unable to dispose a revertible that has already been disposed.");
+                }
+                checkout.disposeRevertible(revertible, revision);
+                onRevertibleDisposed?.(revertible);
+            },
+        };
+        return revertible;
+    }
     viewWith(config) {
         const view = new SchematizingSimpleTreeView(this, config, createNodeKeyManager(this.idCompressor), this.breaker, () => {
             this.views.delete(view);
@@ -273,19 +307,23 @@ export class TreeCheckout {
         this.checkNotDisposed();
         return this.forest.anchors.locate(anchor);
     }
+    get transaction() {
+        return __classPrivateFieldGet(this, _TreeCheckout_transaction, "f");
+    }
     branch() {
         this.checkNotDisposed("The parent branch has already been disposed and can no longer create new branches.");
         const anchors = new AnchorSet();
         const branch = this._branch.fork();
         const storedSchema = this.storedSchema.clone();
         const forest = this.forest.clone(storedSchema, anchors);
-        const transaction = new Transaction(branch);
-        return new TreeCheckout(transaction, branch, true, this.changeFamily, storedSchema, forest, createEmitter(), this.mintRevisionTag, this.revisionTagCodec, this.idCompressor, this.removedRoots.clone(), this.logger, this.breaker);
+        const checkout = new TreeCheckout(branch, true, this.changeFamily, storedSchema, forest, createEmitter(), this.mintRevisionTag, this.revisionTagCodec, this.idCompressor, this.removedRoots.clone(), this.logger, this.breaker);
+        this.events.emit("fork", checkout);
+        return checkout;
     }
     rebase(checkout) {
         this.checkNotDisposed("The target of the branch rebase has been disposed and cannot be rebased.");
         checkout.checkNotDisposed("The source of the branch rebase has been disposed and cannot be rebased.");
-        assert(!checkout.transaction.inProgress(), 0x9af /* A view cannot be rebased while it has a pending transaction */);
+        assert(!checkout.transaction.isInProgress(), 0x9af /* A view cannot be rebased while it has a pending transaction */);
         assert(checkout.isBranch, 0xa5d /* The main branch cannot be rebased onto another branch. */);
         checkout._branch.rebaseOnto(this._branch);
     }
@@ -296,8 +334,8 @@ export class TreeCheckout {
     merge(checkout, disposeMerged = true) {
         this.checkNotDisposed("The target of the branch merge has been disposed and cannot be merged.");
         checkout.checkNotDisposed("The source of the branch merge has been disposed and cannot be merged.");
-        assert(!this.transaction.inProgress(), 0x9b0 /* Views cannot be merged into a view while it has a pending transaction */);
-        while (checkout.transaction.inProgress()) {
+        assert(!this.transaction.isInProgress(), 0x9b0 /* Views cannot be merged into a view while it has a pending transaction */);
+        while (checkout.transaction.isInProgress()) {
             checkout.transaction.commit();
         }
         this._branch.merge(checkout._branch);
@@ -313,14 +351,16 @@ export class TreeCheckout {
     dispose() {
         this[disposeSymbol]();
     }
-    [disposeSymbol]() {
+    [(_TreeCheckout_transaction = new WeakMap(), disposeSymbol)]() {
         this.checkNotDisposed("The branch has already been disposed and cannot be disposed again.");
         this.disposed = true;
+        __classPrivateFieldGet(this, _TreeCheckout_transaction, "f").dispose();
         this.purgeRevertibles();
         this._branch.dispose();
         for (const view of this.views) {
             view.dispose();
         }
+        this.events.emit("dispose");
     }
     getRemovedRoots() {
         this.assertNoUntrackedRoots();
@@ -356,7 +396,7 @@ export class TreeCheckout {
         this.revertibles.delete(revertible);
     }
     revertRevertible(revision, kind) {
-        if (this._branch.isTransacting()) {
+        if (this.transaction.isInProgress()) {
             throw new UsageError("Undo is not yet supported during transactions.");
         }
         const revertibleBranch = this.revertibleCommitBranches.get(revision);
@@ -398,25 +438,22 @@ export class TreeCheckout {
             rootFields.delete(field);
         } while (cursor.nextField());
     }
+    /**
+     * `true` iff the given branch change event is due to a remote change
+     */
+    isRemoteChangeEvent(event) {
+        return (
+        // Remote changes are only ever applied to the main branch
+        !this.isBranch &&
+            // Remote changes are applied to the main branch by rebasing it onto the trunk.
+            // No other rebases are allowed on the main branch, so we can use this to detect remote changes.
+            event.type === "replace" &&
+            getChangeReplaceType(event) === "rebase");
+    }
 }
 /**
  * The name of the telemetry event logged for calls to {@link TreeCheckout.revertRevertible}.
  * @privateRemarks Exposed for testing purposes.
  */
 TreeCheckout.revertTelemetryEventName = "RevertRevertible";
-/**
- * Run a synchronous transaction on the given shared tree view.
- * This is a convenience helper around the {@link SharedTreeFork#transaction} APIs.
- * @param view - the view on which to run the transaction
- * @param transaction - the transaction function. This will be executed immediately. It is passed `view` as an argument for convenience.
- * If this function returns an `Abort` result then the transaction will be aborted. Otherwise, it will be committed.
- * @returns whether or not the transaction was committed or aborted
- */
-export function runSynchronous(view, transaction) {
-    view.transaction.start();
-    const result = transaction(view);
-    return result === TransactionResult.Abort
-        ? view.transaction.abort()
-        : view.transaction.commit();
-}
 //# sourceMappingURL=treeCheckout.js.map