@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/shared-tree-core/branch.d.ts

@@ -0,0 +1,199 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ChangeFamily, ChangeFamilyEditor, GraphCommit, TaggedChange, RevisionTag, Revertible, BranchRebaseResult } from "../core";
+import { EventEmitter, ISubscribable } from "../events";
+/**
+ * Describes a change to a `SharedTreeBranch`. Various operations can mutate the head of the branch;
+ * this change format describes each in terms of the "removed commits" (all commits which were present
+ * on the branch before the operation but are no longer present after) and the "new commits" (all
+ * commits which are present on the branch after the operation that were not present before). Each of
+ * the following event types also provides a `change` which contains the net change to the branch
+ * (or is undefined if there was no net change):
+ * * Append - when one or more commits are appended to the head of the branch, for example via
+ * a change applied by the branch's editor, or as a result of merging another branch into this one
+ * * Remove - when one or more commits are removed from the head of the branch. This occurs
+ * when a transaction is aborted and all commits pending in that transaction are removed.
+ * * Replace - when an operation simultaneously removes and appends commits. For example, when this
+ * branch is rebased and some commits are removed and replaced with rebased versions, or when a
+ * transaction completes and all pending commits are replaced with a single squash commit.
+ */
+export type SharedTreeBranchChange<TChange> = {
+    type: "append";
+    change: TaggedChange<TChange>;
+    newCommits: readonly GraphCommit<TChange>[];
+} | {
+    type: "remove";
+    change: TaggedChange<TChange> | undefined;
+    removedCommits: readonly GraphCommit<TChange>[];
+} | {
+    type: "replace";
+    change: TaggedChange<TChange> | undefined;
+    removedCommits: readonly GraphCommit<TChange>[];
+    newCommits: readonly GraphCommit<TChange>[];
+};
+/**
+ * Returns the operation that caused the given {@link SharedTreeBranchChange}.
+ */
+export declare function getChangeReplaceType(change: SharedTreeBranchChange<unknown> & {
+    type: "replace";
+}): "transactionCommit" | "rebase";
+/**
+ * The events emitted by a `SharedTreeBranch`
+ */
+export interface SharedTreeBranchEvents<TEditor extends ChangeFamilyEditor, TChange> {
+    /**
+     * Fired just before the head of this branch changes.
+     * @param change - the change to this branch's state and commits
+     */
+    beforeChange(change: SharedTreeBranchChange<TChange>): void;
+    /**
+     * Fired just after the head of this branch changes.
+     * @param change - the change to this branch's state and commits
+     */
+    afterChange(change: SharedTreeBranchChange<TChange>): void;
+    /**
+     * Fired when a revertible change is made to this branch.
+     */
+    revertible(type: Revertible): void;
+    /**
+     * Fired when a revertible made on this branch is disposed.
+     */
+    revertibleDispose(revision: RevisionTag): void;
+    /**
+     * Fired when this branch forks
+     * @param fork - the new branch that forked off of this branch
+     */
+    fork(fork: SharedTreeBranch<TEditor, TChange>): void;
+    /**
+     * Fired after this branch is disposed
+     */
+    dispose(): void;
+}
+/**
+ * A branch of changes that can be applied to a SharedTree.
+ */
+export declare class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> extends EventEmitter<SharedTreeBranchEvents<TEditor, TChange>> {
+    private head;
+    readonly changeFamily: ChangeFamily<TEditor, TChange>;
+    readonly editor: TEditor;
+    private readonly revertibles;
+    private readonly _revertibleCommits;
+    private readonly transactions;
+    private disposed;
+    /**
+     * Construct a new branch.
+     * @param head - the head of the branch
+     * @param changeFamily - determines the set of changes that this branch can commit
+     */
+    constructor(head: GraphCommit<TChange>, changeFamily: ChangeFamily<TEditor, TChange>);
+    /**
+     * Sets the head of this branch. Emits no change events.
+     */
+    setHead(head: GraphCommit<TChange>): void;
+    /**
+     * Apply a change to this branch.
+     * @param change - the change to apply
+     * @param revision - the revision of the new head commit of the branch that contains `change`
+     * @returns the change that was applied and the new head commit of the branch
+     */
+    apply(change: TChange, revision: RevisionTag): [change: TChange, newCommit: GraphCommit<TChange>];
+    private applyChange;
+    /**
+     * @returns the commit at the head of this branch.
+     */
+    getHead(): GraphCommit<TChange>;
+    /**
+     * Begin a transaction on this branch. If the transaction is committed via {@link commitTransaction},
+     * all commits made since this call will be squashed into a single head commit.
+     * @param repairStore - the repair store associated with this transaction
+     */
+    startTransaction(): void;
+    /**
+     * Commit the current transaction. There must be a transaction in progress that was begun via {@link startTransaction}.
+     * If there are commits in the current transaction, they will be squashed into a new single head commit.
+     * @returns the commits that were squashed and the new squash commit if a squash occurred, otherwise `undefined`.
+     * @remarks If the transaction had no changes applied during its lifetime, then no squash occurs (i.e. this method is a no-op).
+     * Even if the transaction contained only one change, it will still be replaced with an (equivalent) squash change.
+     */
+    commitTransaction(): [squashedCommits: GraphCommit<TChange>[], newCommit: GraphCommit<TChange>] | undefined;
+    /**
+     * Cancel the current transaction. There must be a transaction in progress that was begun via
+     * {@link startTransaction}. All commits made during the transaction will be removed.
+     * @returns the change to this branch resulting in the removal of the commits, and a list of the
+     * commits that were removed.
+     */
+    abortTransaction(): [
+        change: TChange | undefined,
+        abortedCommits: GraphCommit<TChange>[]
+    ];
+    /**
+     * True iff this branch is in the middle of a transaction that was begin via {@link startTransaction}
+     */
+    isTransacting(): boolean;
+    private popTransaction;
+    revertibleCommits(): IterableIterator<RevisionTag>;
+    /**
+     * Associate a revertible with a new commit of the same revision.
+     * This is applicable when a commit is replaced by a rebase or a local commit is sequenced.
+     */
+    updateRevertibleCommit(commit: GraphCommit<TChange>): void;
+    private makeSharedTreeRevertible;
+    private revert;
+    /**
+     * Spawn a new branch that is based off of the current state of this branch.
+     * Changes made to the new branch will not be applied to this branch until the new branch is merged back in.
+     *
+     * @remarks Forks created during a transaction will be disposed when the transaction ends.
+     */
+    fork(): SharedTreeBranch<TEditor, TChange>;
+    /**
+     * Rebase the changes that have been applied to this branch over divergent changes in the given branch.
+     * After this operation completes, this branch will be based off of `branch`.
+     *
+     * @remarks
+     * This operation can change the relative ordering between revertible commits therefore, the revertible event
+     * is not emitted during this operation.
+     *
+     * @param branch - the branch to rebase onto
+     * @param upTo - the furthest commit on `branch` over which to rebase (inclusive). Defaults to the head commit of `branch`.
+     * @returns the result of the rebase or undefined if nothing changed
+     */
+    rebaseOnto(branch: SharedTreeBranch<TEditor, TChange>, upTo?: GraphCommit<TChange>): BranchRebaseResult<TChange> | undefined;
+    /**
+     * Apply all the divergent changes on the given branch to this branch.
+     *
+     * @remarks
+     * Revertible events are emitted for new local commits merged into this branch.
+     *
+     * @param branch - the branch to merge into this branch
+     * @returns the net change to this branch and the commits that were added to this branch by the merge,
+     * or undefined if nothing changed
+     */
+    merge(branch: SharedTreeBranch<TEditor, TChange>): [change: TChange, newCommits: GraphCommit<TChange>[]] | undefined;
+    /** Rebase `branchHead` onto `onto`, but return undefined if nothing changed */
+    private rebaseBranch;
+    /**
+     * Dispose this branch, freezing its state.
+     *
+     * @remarks
+     * Attempts to further mutate the branch will error.
+     * Any transactions in progress will be aborted.
+     * Calling dispose more than once has no effect.
+     */
+    dispose(): void;
+    private assertNotDisposed;
+}
+/**
+ * Registers an event listener that fires when the given forkable object forks.
+ * The listener will also fire when any of those forks fork, and when those forks of forks fork, and so on.
+ * @param forkable - an object that emits an event when it is forked
+ * @param onFork - the fork event listener
+ * @returns a function which when called will deregister all registrations (including transitive) created by this function.
+ * The deregister function has undefined behavior if called more than once.
+ */
+export declare function onForkTransitive<T extends ISubscribable<{
+    fork: (t: T) => void;
+}>>(forkable: T, onFork: (fork: T) => void): () => void;
+//# sourceMappingURL=branch.d.ts.map

package/dist/shared-tree-core/branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch.d.ts","sourceRoot":"","sources":["../../src/shared-tree-core/branch.ts"],"names":[],"mappings":"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"}

package/dist/shared-tree-core/branch.js

@@ -0,0 +1,413 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onForkTransitive = exports.SharedTreeBranch = exports.getChangeReplaceType = void 0;
+const core_utils_1 = require("@fluidframework/core-utils");
+const core_1 = require("../core");
+const events_1 = require("../events");
+const util_1 = require("../util");
+const transactionStack_1 = require("./transactionStack");
+/**
+ * Returns the operation that caused the given {@link SharedTreeBranchChange}.
+ */
+function getChangeReplaceType(change) {
+    // The "replace" variant of the change event is emitted by two operations: committing a transaction and doing a rebase.
+    // Committing a transaction will always remove one or more commits (the commits that were squashed),
+    // and will add exactly one new commit (the squash commit).
+    if (change.removedCommits.length === 0 || change.newCommits.length !== 1) {
+        return "rebase";
+    }
+    // There is only one case in which a rebase both removes commits and adds exactly one new commit.
+    // This occurs when there is exactly one divergent, but equivalent, commit on each branch:
+    //
+    // A ─ B (branch X)	  -- rebase Y onto X -->   A ─ B (branch X)
+    // └─ B' (branch Y)                                └─ (branch Y)
+    //
+    // B' is removed and replaced by B because both have the same revision.
+    if (change.removedCommits.length === 1 &&
+        change.removedCommits[0].revision === change.newCommits[0].revision) {
+        return "rebase";
+    }
+    return "transactionCommit";
+}
+exports.getChangeReplaceType = getChangeReplaceType;
+/**
+ * A branch of changes that can be applied to a SharedTree.
+ */
+class SharedTreeBranch extends events_1.EventEmitter {
+    /**
+     * Construct a new branch.
+     * @param head - the head of the branch
+     * @param changeFamily - determines the set of changes that this branch can commit
+     */
+    constructor(head, changeFamily) {
+        super();
+        this.head = head;
+        this.changeFamily = changeFamily;
+        // set of revertibles maintained for automatic disposal
+        this.revertibles = new Set();
+        this._revertibleCommits = new Map();
+        this.transactions = new transactionStack_1.TransactionStack();
+        this.disposed = false;
+        this.editor = this.changeFamily.buildEditor((change) => this.apply(change, (0, core_1.mintRevisionTag)()));
+    }
+    /**
+     * Sets the head of this branch. Emits no change events.
+     */
+    setHead(head) {
+        this.assertNotDisposed();
+        (0, core_utils_1.assert)(!this.isTransacting(), 0x685 /* Cannot set head during a transaction */);
+        this.head = head;
+    }
+    /**
+     * Apply a change to this branch.
+     * @param change - the change to apply
+     * @param revision - the revision of the new head commit of the branch that contains `change`
+     * @returns the change that was applied and the new head commit of the branch
+     */
+    apply(change, revision) {
+        return this.applyChange(change, revision, core_1.RevertibleKind.Default);
+    }
+    applyChange(change, revision, revertibleKind) {
+        this.assertNotDisposed();
+        const newHead = (0, core_1.mintCommit)(this.head, {
+            revision,
+            change,
+        });
+        const changeEvent = {
+            type: "append",
+            change: (0, core_1.tagChange)(change, revision),
+            newCommits: [newHead],
+        };
+        this.emit("beforeChange", changeEvent);
+        this.head = newHead;
+        // If this is not part of a transaction, emit a revertible event
+        if (!this.isTransacting()) {
+            this.emit("revertible", this.makeSharedTreeRevertible(newHead, revertibleKind));
+        }
+        this.emit("afterChange", changeEvent);
+        return [change, newHead];
+    }
+    /**
+     * @returns the commit at the head of this branch.
+     */
+    getHead() {
+        return this.head;
+    }
+    /**
+     * Begin a transaction on this branch. If the transaction is committed via {@link commitTransaction},
+     * all commits made since this call will be squashed into a single head commit.
+     * @param repairStore - the repair store associated with this transaction
+     */
+    startTransaction() {
+        this.assertNotDisposed();
+        const forks = new Set();
+        const onDisposeUnSubscribes = [];
+        const onForkUnSubscribe = onForkTransitive(this, (fork) => {
+            forks.add(fork);
+            onDisposeUnSubscribes.push(fork.on("dispose", () => forks.delete(fork)));
+        });
+        this.transactions.push(this.head.revision, () => {
+            forks.forEach((fork) => fork.dispose());
+            onDisposeUnSubscribes.forEach((unsubscribe) => unsubscribe());
+            onForkUnSubscribe();
+        });
+        this.editor.enterTransaction();
+    }
+    /**
+     * Commit the current transaction. There must be a transaction in progress that was begun via {@link startTransaction}.
+     * If there are commits in the current transaction, they will be squashed into a new single head commit.
+     * @returns the commits that were squashed and the new squash commit if a squash occurred, otherwise `undefined`.
+     * @remarks If the transaction had no changes applied during its lifetime, then no squash occurs (i.e. this method is a no-op).
+     * Even if the transaction contained only one change, it will still be replaced with an (equivalent) squash change.
+     */
+    commitTransaction() {
+        this.assertNotDisposed();
+        const [startCommit, commits] = this.popTransaction();
+        this.editor.exitTransaction();
+        if (commits.length === 0) {
+            return undefined;
+        }
+        // Anonymize the commits from this transaction by stripping their revision tags.
+        // Otherwise, the change rebaser will record their tags and those tags no longer exist.
+        const anonymousCommits = commits.map(({ change }) => ({ change, revision: undefined }));
+        // Squash the changes and make the squash commit the new head of this branch
+        const squashedChange = this.changeFamily.rebaser.compose(anonymousCommits);
+        const revision = (0, core_1.mintRevisionTag)();
+        const newHead = (0, core_1.mintCommit)(startCommit, {
+            revision,
+            change: squashedChange,
+        });
+        const changeEvent = {
+            type: "replace",
+            change: undefined,
+            removedCommits: commits,
+            newCommits: [newHead],
+        };
+        this.emit("beforeChange", changeEvent);
+        this.head = newHead;
+        // If this transaction is not nested, emit a revertible event
+        if (!this.isTransacting()) {
+            this.emit("revertible", this.makeSharedTreeRevertible(newHead, core_1.RevertibleKind.Default));
+        }
+        this.emit("afterChange", changeEvent);
+        return [commits, newHead];
+    }
+    /**
+     * Cancel the current transaction. There must be a transaction in progress that was begun via
+     * {@link startTransaction}. All commits made during the transaction will be removed.
+     * @returns the change to this branch resulting in the removal of the commits, and a list of the
+     * commits that were removed.
+     */
+    abortTransaction() {
+        this.assertNotDisposed();
+        const [startCommit, commits] = this.popTransaction();
+        this.editor.exitTransaction();
+        if (commits.length === 0) {
+            return [undefined, []];
+        }
+        const inverses = [];
+        for (let i = commits.length - 1; i >= 0; i--) {
+            const inverse = this.changeFamily.rebaser.invert(commits[i], false);
+            inverses.push((0, core_1.tagRollbackInverse)(inverse, (0, core_1.mintRevisionTag)(), commits[i].revision));
+        }
+        const change = inverses.length > 0 ? this.changeFamily.rebaser.compose(inverses) : undefined;
+        const changeEvent = {
+            type: "remove",
+            change: change === undefined ? undefined : (0, core_1.makeAnonChange)(change),
+            removedCommits: commits,
+        };
+        this.emit("beforeChange", changeEvent);
+        this.head = startCommit;
+        this.emit("afterChange", changeEvent);
+        return [change, commits];
+    }
+    /**
+     * True iff this branch is in the middle of a transaction that was begin via {@link startTransaction}
+     */
+    isTransacting() {
+        return this.transactions.size !== 0;
+    }
+    popTransaction() {
+        const { startRevision } = this.transactions.pop();
+        const commits = [];
+        const startCommit = (0, core_1.findAncestor)([this.head, commits], (c) => c.revision === startRevision);
+        (0, core_utils_1.assert)(startCommit !== undefined, 0x593 /* Expected branch to be ahead of transaction start revision */);
+        return [startCommit, commits];
+    }
+    revertibleCommits() {
+        return this._revertibleCommits.keys();
+    }
+    /**
+     * Associate a revertible with a new commit of the same revision.
+     * This is applicable when a commit is replaced by a rebase or a local commit is sequenced.
+     */
+    updateRevertibleCommit(commit) {
+        if (this._revertibleCommits.get(commit.revision) !== undefined) {
+            this._revertibleCommits.set(commit.revision, commit);
+        }
+    }
+    makeSharedTreeRevertible(commit, kind) {
+        this._revertibleCommits.set(commit.revision, commit);
+        let discarded = false;
+        const revertible = {
+            kind,
+            origin: {
+                // This is currently always the case, but we may want to support reverting remote ops
+                isLocal: true,
+            },
+            revert: () => {
+                if (discarded) {
+                    (0, util_1.fail)("revertible has already been discarded");
+                }
+                const revertCommit = this.revert(commit.revision, kind);
+                if (revertCommit !== undefined) {
+                    revertible.discard();
+                    return core_1.RevertResult.Success;
+                }
+                return core_1.RevertResult.Failure;
+            },
+            discard: () => {
+                if (discarded) {
+                    (0, util_1.fail)("revertible has already been discarded");
+                }
+                // TODO: delete the repair data from the forest
+                this._revertibleCommits.delete(commit.revision);
+                this.revertibles.delete(revertible);
+                discarded = true;
+                this.emit("revertibleDispose", commit.revision);
+                return core_1.DiscardResult.Success;
+            },
+        };
+        this.revertibles.add(revertible);
+        return revertible;
+    }
+    revert(revision, revertibleKind) {
+        (0, core_utils_1.assert)(!this.isTransacting(), 0x7cb /* Undo is not yet supported during transactions */);
+        const commit = this._revertibleCommits.get(revision);
+        (0, core_utils_1.assert)(commit !== undefined, 0x7cc /* expected to find a revertible commit */);
+        let change = this.changeFamily.rebaser.invert((0, core_1.tagChange)(commit.change, revision), false);
+        const headCommit = this.getHead();
+        // Rebase the inverted change onto any commits that occurred after the undoable commits.
+        if (revision !== headCommit.revision) {
+            const pathAfterUndoable = [];
+            const ancestor = (0, core_1.findCommonAncestor)([commit], [headCommit, pathAfterUndoable]);
+            (0, core_utils_1.assert)(ancestor === commit, 0x677 /* The head commit should be based off the undoable commit. */);
+            change = (0, core_1.rebaseChangeOverChanges)(this.changeFamily.rebaser, change, pathAfterUndoable);
+        }
+        return this.applyChange(change, (0, core_1.mintRevisionTag)(), revertibleKind === core_1.RevertibleKind.Default || revertibleKind === core_1.RevertibleKind.Redo
+            ? core_1.RevertibleKind.Undo
+            : core_1.RevertibleKind.Redo);
+    }
+    /**
+     * Spawn a new branch that is based off of the current state of this branch.
+     * Changes made to the new branch will not be applied to this branch until the new branch is merged back in.
+     *
+     * @remarks Forks created during a transaction will be disposed when the transaction ends.
+     */
+    fork() {
+        this.assertNotDisposed();
+        const fork = new SharedTreeBranch(this.head, this.changeFamily);
+        this.emit("fork", fork);
+        return fork;
+    }
+    /**
+     * Rebase the changes that have been applied to this branch over divergent changes in the given branch.
+     * After this operation completes, this branch will be based off of `branch`.
+     *
+     * @remarks
+     * This operation can change the relative ordering between revertible commits therefore, the revertible event
+     * is not emitted during this operation.
+     *
+     * @param branch - the branch to rebase onto
+     * @param upTo - the furthest commit on `branch` over which to rebase (inclusive). Defaults to the head commit of `branch`.
+     * @returns the result of the rebase or undefined if nothing changed
+     */
+    rebaseOnto(branch, upTo = branch.getHead()) {
+        this.assertNotDisposed();
+        // Rebase this branch onto the given branch
+        const rebaseResult = this.rebaseBranch(this, branch, upTo);
+        if (rebaseResult === undefined) {
+            return undefined;
+        }
+        // The net change to this branch is provided by the `rebaseBranch` API
+        const { newSourceHead, commits } = rebaseResult;
+        const { deletedSourceCommits, targetCommits, sourceCommits } = commits;
+        // It's possible that the target branch already contained some of the commits that
+        // were on this branch. When that's the case, we adopt the commit objects from the target branch.
+        // Because of that, we need to make sure that any revertibles that were based on the old commit objects
+        // now point to the new object that were adopted from the target branch.
+        for (const targetCommit of targetCommits) {
+            this.updateRevertibleCommit(targetCommit);
+        }
+        const newCommits = targetCommits.concat(sourceCommits);
+        const changeEvent = {
+            type: "replace",
+            get change() {
+                const change = rebaseResult.sourceChange;
+                return change === undefined ? undefined : (0, core_1.makeAnonChange)(change);
+            },
+            removedCommits: deletedSourceCommits,
+            newCommits,
+        };
+        this.emit("beforeChange", changeEvent);
+        this.head = newSourceHead;
+        // update revertible commits that have been rebased
+        sourceCommits.forEach((commit) => {
+            this.updateRevertibleCommit(commit);
+        });
+        this.emit("afterChange", changeEvent);
+        return rebaseResult;
+    }
+    /**
+     * Apply all the divergent changes on the given branch to this branch.
+     *
+     * @remarks
+     * Revertible events are emitted for new local commits merged into this branch.
+     *
+     * @param branch - the branch to merge into this branch
+     * @returns the net change to this branch and the commits that were added to this branch by the merge,
+     * or undefined if nothing changed
+     */
+    merge(branch) {
+        this.assertNotDisposed();
+        branch.assertNotDisposed();
+        (0, core_utils_1.assert)(!branch.isTransacting(), 0x597 /* Branch may not be merged while transaction is in progress */);
+        // Rebase the given branch onto this branch
+        const rebaseResult = this.rebaseBranch(branch, this);
+        if (rebaseResult === undefined) {
+            return undefined;
+        }
+        // Compute the net change to this branch
+        const sourceCommits = rebaseResult.commits.sourceCommits;
+        const change = this.changeFamily.rebaser.compose(sourceCommits);
+        const taggedChange = (0, core_1.makeAnonChange)(change);
+        const changeEvent = {
+            type: "append",
+            get change() {
+                return taggedChange;
+            },
+            newCommits: sourceCommits,
+        };
+        this.emit("beforeChange", changeEvent);
+        this.head = rebaseResult.newSourceHead;
+        this.emit("afterChange", changeEvent);
+        return [change, sourceCommits];
+    }
+    /** Rebase `branchHead` onto `onto`, but return undefined if nothing changed */
+    rebaseBranch(branch, onto, upTo = onto.getHead()) {
+        const { head } = branch;
+        if (head === upTo) {
+            return undefined;
+        }
+        const rebaseResult = (0, core_1.rebaseBranch)(this.changeFamily.rebaser, head, upTo, onto.getHead());
+        if (this.head === rebaseResult.newSourceHead) {
+            return undefined;
+        }
+        return rebaseResult;
+    }
+    /**
+     * Dispose this branch, freezing its state.
+     *
+     * @remarks
+     * Attempts to further mutate the branch will error.
+     * Any transactions in progress will be aborted.
+     * Calling dispose more than once has no effect.
+     */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        while (this.isTransacting()) {
+            this.abortTransaction();
+        }
+        this.revertibles.forEach((revertible) => revertible.discard());
+        this.disposed = true;
+        this.emit("dispose");
+    }
+    assertNotDisposed() {
+        (0, core_utils_1.assert)(!this.disposed, 0x66e /* Branch is disposed */);
+    }
+}
+exports.SharedTreeBranch = SharedTreeBranch;
+/**
+ * Registers an event listener that fires when the given forkable object forks.
+ * The listener will also fire when any of those forks fork, and when those forks of forks fork, and so on.
+ * @param forkable - an object that emits an event when it is forked
+ * @param onFork - the fork event listener
+ * @returns a function which when called will deregister all registrations (including transitive) created by this function.
+ * The deregister function has undefined behavior if called more than once.
+ */
+function onForkTransitive(forkable, onFork) {
+    const offs = [];
+    offs.push(forkable.on("fork", (fork) => {
+        offs.push(onForkTransitive(fork, onFork));
+        onFork(fork);
+    }));
+    return () => offs.forEach((off) => off());
+}
+exports.onForkTransitive = onForkTransitive;
+//# sourceMappingURL=branch.js.map