@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/shared-tree/treeCheckout.d.ts

@@ -0,0 +1,228 @@
+import { AnchorLocator, IForestSubscription, AnchorSetRootEvents, Anchor, AnchorNode, IEditableForest, TreeStoredSchemaRepository, DetachedFieldIndex, Revertible, ChangeFamily, TreeStoredSchema, TreeStoredSchemaSubscription, JsonableTree } from "../core";
+import { HasListeners, IEmitter, ISubscribable } from "../events";
+import { SharedTreeBranch } from "../shared-tree-core";
+import { TransactionResult } from "../util";
+import { SharedTreeChange } from "./sharedTreeChangeTypes";
+import { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder";
+/**
+ * Events for {@link ITreeCheckout}.
+ * @beta
+ */
+export interface CheckoutEvents {
+    /**
+     * A batch of changes has finished processing and the view is in a consistent state.
+     * It is once again safe to access the EditableTree, Forest and AnchorSet.
+     *
+     * @remarks
+     * This is mainly useful for knowing when to do followup work scheduled during events from Anchors.
+     */
+    afterBatch(): void;
+    /**
+     * A revertible change has been made to this view.
+     * Applications which subscribe to this event are expected to revert or discard revertibles they acquire, if they so choose (failure to do so will leak memory).
+     * The provided revertible is inherently bound to the view that raised the event, calling `revert` won't apply to forked views.
+     *
+     * @remarks
+     * This event provides a {@link Revertible} object that can be used to revert the change.
+     */
+    revertible(revertible: Revertible): void;
+}
+/**
+ * Provides a means for interacting with a SharedTree.
+ * This includes reading data from the tree and running transactions to mutate the tree.
+ * @remarks This interface should not have any implementations other than those provided by the SharedTree package libraries.
+ * @privateRemarks
+ * API for interacting with a {@link SharedTreeBranch}.
+ * Implementations of this interface must implement the {@link branchKey} property.
+ * @internal
+ */
+export interface ITreeCheckout extends AnchorLocator {
+    /**
+     * Read and Write access for schema stored in the document.
+     *
+     * These APIs are temporary and will be replaced with different abstractions (View Schema based) in a different place later.
+     *
+     * TODO:
+     * Editing of this should be moved into transactions with the rest of tree editing to they can be intermixed.
+     * This will be done after the relations between views, branches and Indexes are figured out.
+     *
+     * TODO:
+     * Public APIs for dealing with schema should be in terms of View Schema, and schema update policies.
+     * The actual stored schema should be hidden (or ar least not be the most prominent way to interact with schema).
+     *
+     * TODO:
+     * Something should ensure the document contents are always in schema.
+     */
+    readonly storedSchema: TreeStoredSchemaSubscription;
+    /**
+     * Current contents.
+     * Updated by edits (local and remote).
+     * Use `editor` to create a local edit.
+     */
+    readonly forest: IForestSubscription;
+    /**
+     * Used to edit the state of the tree. Edits will be immediately applied locally to the tree.
+     * If there is no transaction currently ongoing, then the edits will be submitted to Fluid immediately as well.
+     */
+    readonly editor: ISharedTreeEditor;
+    /**
+     * A collection of functions for managing transactions.
+     */
+    readonly transaction: ITransaction;
+    /**
+     * Spawn a new view which is based off of the current state of this view.
+     * Any mutations of the new view will not apply to this view until the new view is merged back into this view via `merge()`.
+     */
+    fork(): ITreeCheckoutFork;
+    /**
+     * Apply all the new changes on the given view to this view.
+     * @param view - a view which was created by a call to `fork()`.
+     * It is automatically disposed after the merge completes.
+     * @remarks All ongoing transactions (if any) in `view` will be committed before the merge.
+     */
+    merge(view: ITreeCheckoutFork): void;
+    /**
+     * Apply all the new changes on the given view to this view.
+     * @param view - a view which was created by a call to `fork()`.
+     * @param disposeView - whether or not to dispose `view` after the merge completes.
+     * @remarks All ongoing transactions (if any) in `view` will be committed before the merge.
+     */
+    merge(view: ITreeCheckoutFork, disposeView: boolean): void;
+    /**
+     * Rebase the given view onto this view.
+     * @param view - a view which was created by a call to `fork()`. It is modified by this operation.
+     */
+    rebase(view: ITreeCheckoutFork): void;
+    /**
+     * Replaces all schema with the provided schema.
+     * Can over-write preexisting schema, and removes unmentioned schema.
+     */
+    updateSchema(newSchema: TreeStoredSchema): void;
+    /**
+     * Events about this view.
+     */
+    readonly events: ISubscribable<CheckoutEvents>;
+    /**
+     * Events about the root of the tree in this view.
+     */
+    readonly rootEvents: ISubscribable<AnchorSetRootEvents>;
+    /**
+     * Returns a JsonableTree for each tree that was removed from (and not restored to) the document.
+     * This list is guaranteed to contain all nodes that are recoverable through undo/redo on this checkout.
+     * The list may also contain additional nodes.
+     *
+     * This is only intended for use in testing and exceptional code paths: it is not performant.
+     */
+    getRemovedRoots(): [string | number | undefined, number, JsonableTree][];
+}
+/**
+ * Creates a {@link TreeCheckout}.
+ * @param args - an object containing optional components that will be used to build the view.
+ * Any components not provided will be created by default.
+ * @remarks This does not create a {@link SharedTree}, but rather a view with the minimal state
+ * and functionality required to implement {@link ITreeCheckout}.
+ */
+export declare function createTreeCheckout(args?: {
+    branch?: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>;
+    changeFamily?: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>;
+    schema?: TreeStoredSchemaRepository;
+    forest?: IEditableForest;
+    events?: ISubscribable<CheckoutEvents> & IEmitter<CheckoutEvents> & HasListeners<CheckoutEvents>;
+    removedRoots?: DetachedFieldIndex;
+}): TreeCheckout;
+/**
+ * A collection of functions for managing transactions.
+ * 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#fork} and {@link ISharedTreeFork#merge}.
+ * @internal
+ */
+export interface ITransaction {
+    /**
+     * Start a new transaction.
+     * If a transaction is already in progress when this new transaction starts, then this transaction will be "nested" inside of it,
+     * i.e. the outer transaction will still be in progress after this new transaction is committed or aborted.
+     *
+     * @remarks - Asynchronous transactions are not supported on the root checkout,
+     * since it is always kept up-to-date with the latest remote edits and the results of this rebasing (which might invalidate
+     * the transaction) is not visible to the application author.
+     * Instead,
+     *
+     * 1. fork the root checkout
+     * 2. run the transaction on the fork
+     * 3. merge the fork back into the root checkout
+     *
+     * @privateRemarks - There is currently no enforcement that asynchronous transactions don't happen on the root checkout.
+     * AB#6488 tracks adding some enforcement to make it more clear to application authors that this is not supported.
+     */
+    start(): void;
+    /**
+     * Close this transaction by squashing its edits and committing them as a single edit.
+     * If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.
+     */
+    commit(): TransactionResult.Commit;
+    /**
+     * Close this transaction and revert the state of the tree to what it was before this transaction began.
+     */
+    abort(): TransactionResult.Abort;
+    /**
+     * True if there is at least one transaction currently in progress on this view, otherwise false.
+     */
+    inProgress(): boolean;
+}
+/**
+ * Branch (like in a version control system) of SharedTree.
+ *
+ * {@link ITreeCheckout} that has forked off of the main trunk/branch.
+ * @internal
+ */
+export interface ITreeCheckoutFork extends ITreeCheckout {
+    /**
+     * Rebase the changes that have been applied to this view over all the new changes in the given view.
+     * @param view - Either the root view or a view that was created by a call to `fork()`. It is not modified by this operation.
+     */
+    rebaseOnto(view: ITreeCheckout): void;
+}
+/**
+ * An implementation of {@link ITreeCheckoutFork}.
+ */
+export declare class TreeCheckout implements ITreeCheckoutFork {
+    readonly transaction: ITransaction;
+    private readonly branch;
+    private readonly changeFamily;
+    readonly storedSchema: TreeStoredSchemaRepository;
+    readonly forest: IEditableForest;
+    readonly events: ISubscribable<CheckoutEvents> & IEmitter<CheckoutEvents> & HasListeners<CheckoutEvents>;
+    private readonly removedRoots;
+    constructor(transaction: ITransaction, branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>, changeFamily: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>, storedSchema: TreeStoredSchemaRepository, forest: IEditableForest, events: ISubscribable<CheckoutEvents> & IEmitter<CheckoutEvents> & HasListeners<CheckoutEvents>, removedRoots?: DetachedFieldIndex);
+    get rootEvents(): ISubscribable<AnchorSetRootEvents>;
+    get editor(): ISharedTreeEditor;
+    locate(anchor: Anchor): AnchorNode | undefined;
+    fork(): TreeCheckout;
+    rebase(view: TreeCheckout): void;
+    rebaseOnto(view: ITreeCheckout): void;
+    merge(view: TreeCheckout): void;
+    merge(view: TreeCheckout, disposeView: boolean): void;
+    updateSchema(newSchema: TreeStoredSchema): void;
+    /**
+     * Dispose this view, freezing its state and allowing the SharedTree to release resources required by it.
+     * Attempts to further mutate or dispose this view will error.
+     */
+    dispose(): void;
+    getRemovedRoots(): [string | number | undefined, number, JsonableTree][];
+}
+/**
+ * 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
+ * @internal
+ */
+export declare function runSynchronous(view: ITreeCheckout, transaction: (view: ITreeCheckout) => TransactionResult | void): TransactionResult;
+//# sourceMappingURL=treeCheckout.d.ts.map

package/dist/shared-tree/treeCheckout.d.ts.map

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

package/dist/shared-tree/treeCheckout.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSynchronous = exports.TreeCheckout = exports.createTreeCheckout = void 0;
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+const core_utils_1 = require("@fluidframework/core-utils");
+const core_1 = require("../core");
+const events_1 = require("../events");
+const feature_libraries_1 = require("../feature-libraries");
+const shared_tree_core_1 = require("../shared-tree-core");
+const util_1 = require("../util");
+const codec_1 = require("../codec");
+const sharedTreeChangeFamily_1 = require("./sharedTreeChangeFamily");
+/**
+ * Creates a {@link TreeCheckout}.
+ * @param args - an object containing optional components that will be used to build the view.
+ * Any components not provided will be created by default.
+ * @remarks This does not create a {@link SharedTree}, but rather a view with the minimal state
+ * and functionality required to implement {@link ITreeCheckout}.
+ */
+function createTreeCheckout(args) {
+    const forest = args?.forest ?? (0, feature_libraries_1.buildForest)();
+    const changeFamily = args?.changeFamily ?? new sharedTreeChangeFamily_1.SharedTreeChangeFamily({ jsonValidator: codec_1.noopValidator });
+    const branch = args?.branch ??
+        new shared_tree_core_1.SharedTreeBranch({
+            change: changeFamily.rebaser.compose([]),
+            revision: (0, core_1.assertIsRevisionTag)("00000000-0000-4000-8000-000000000000"),
+        }, changeFamily);
+    const schema = args?.schema ?? new core_1.TreeStoredSchemaRepository();
+    const events = args?.events ?? (0, events_1.createEmitter)();
+    const transaction = new Transaction(branch);
+    return new TreeCheckout(transaction, branch, changeFamily, schema, forest, events, args?.removedRoots);
+}
+exports.createTreeCheckout = createTreeCheckout;
+class Transaction {
+    constructor(branch) {
+        this.branch = branch;
+    }
+    start() {
+        this.branch.startTransaction();
+        this.branch.editor.enterTransaction();
+    }
+    commit() {
+        this.branch.commitTransaction();
+        this.branch.editor.exitTransaction();
+        return util_1.TransactionResult.Commit;
+    }
+    abort() {
+        this.branch.abortTransaction();
+        this.branch.editor.exitTransaction();
+        return util_1.TransactionResult.Abort;
+    }
+    inProgress() {
+        return this.branch.isTransacting();
+    }
+}
+/**
+ * An implementation of {@link ITreeCheckoutFork}.
+ */
+class TreeCheckout {
+    constructor(transaction, branch, changeFamily, storedSchema, forest, events, removedRoots = (0, core_1.makeDetachedFieldIndex)("repair")) {
+        this.transaction = transaction;
+        this.branch = branch;
+        this.changeFamily = changeFamily;
+        this.storedSchema = storedSchema;
+        this.forest = forest;
+        this.events = events;
+        this.removedRoots = removedRoots;
+        // 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.on("beforeChange", (event) => {
+            if (event.change !== undefined) {
+                // Conflicts due to schema will be empty and thus are not applied.
+                for (const change of event.change.change.changes) {
+                    if (change.type === "data") {
+                        const delta = (0, feature_libraries_1.intoDelta)((0, core_1.tagChange)(change.innerChange, event.change.revision));
+                        const anchorVisitor = this.forest.anchors.acquireVisitor();
+                        const combinedVisitor = (0, core_1.combineVisitors)([this.forest.acquireVisitor(), anchorVisitor], [anchorVisitor]);
+                        (0, core_1.visitDelta)(delta, combinedVisitor, this.removedRoots);
+                        combinedVisitor.free();
+                    }
+                    else if (change.type === "schema") {
+                        if (change.innerChange.schema !== undefined) {
+                            storedSchema.apply(change.innerChange.schema.new);
+                        }
+                    }
+                    else {
+                        (0, util_1.fail)("Unknown Shared Tree change type.");
+                    }
+                }
+                this.events.emit("afterBatch");
+            }
+            if (event.type === "replace" && (0, shared_tree_core_1.getChangeReplaceType)(event) === "transactionCommit") {
+                const transactionRevision = event.newCommits[0].revision;
+                for (const transactionStep of event.removedCommits) {
+                    this.removedRoots.updateMajor(transactionStep.revision, transactionRevision);
+                }
+            }
+        });
+        branch.on("revertible", (revertible) => {
+            // if there are no listeners, discard the revertible to avoid memory leaks
+            if (!this.events.hasListeners("revertible")) {
+                revertible.discard();
+            }
+            else {
+                this.events.emit("revertible", revertible);
+            }
+        });
+    }
+    get rootEvents() {
+        return this.forest.anchors;
+    }
+    get editor() {
+        return this.branch.editor;
+    }
+    locate(anchor) {
+        return this.forest.anchors.locate(anchor);
+    }
+    fork() {
+        const anchors = new core_1.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, this.changeFamily, storedSchema, forest, (0, events_1.createEmitter)(), this.removedRoots.clone());
+    }
+    rebase(view) {
+        view.branch.rebaseOnto(this.branch);
+    }
+    rebaseOnto(view) {
+        view.rebase(this);
+    }
+    merge(view, disposeView = true) {
+        (0, core_utils_1.assert)(!this.transaction.inProgress() || disposeView, 0x710 /* A view that is merged into an in-progress transaction must be disposed */);
+        while (view.transaction.inProgress()) {
+            view.transaction.commit();
+        }
+        this.branch.merge(view.branch);
+        if (disposeView) {
+            view.dispose();
+        }
+    }
+    updateSchema(newSchema) {
+        this.editor.schema.setStoredSchema(this.storedSchema.clone(), newSchema);
+    }
+    /**
+     * Dispose this view, freezing its state and allowing the SharedTree to release resources required by it.
+     * Attempts to further mutate or dispose this view will error.
+     */
+    dispose() {
+        this.branch.dispose();
+    }
+    getRemovedRoots() {
+        const trees = [];
+        const cursor = this.forest.allocateCursor();
+        for (const { id, root } of this.removedRoots.entries()) {
+            const parentField = this.removedRoots.toFieldKey(root);
+            this.forest.moveCursorToPath({ parent: undefined, parentField, parentIndex: 0 }, cursor);
+            const tree = (0, feature_libraries_1.jsonableTreeFromCursor)(cursor);
+            if (tree !== undefined) {
+                trees.push([id.major, id.minor, tree]);
+            }
+        }
+        cursor.free();
+        return trees;
+    }
+}
+exports.TreeCheckout = TreeCheckout;
+/**
+ * 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
+ * @internal
+ */
+function runSynchronous(view, transaction) {
+    view.transaction.start();
+    const result = transaction(view);
+    return result === util_1.TransactionResult.Abort
+        ? view.transaction.abort()
+        : view.transaction.commit();
+}
+exports.runSynchronous = runSynchronous;
+//# sourceMappingURL=treeCheckout.js.map

package/dist/shared-tree/treeCheckout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeCheckout.js","sourceRoot":"","sources":["../../src/shared-tree/treeCheckout.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nimport { assert } from \"@fluidframework/core-utils\";\nimport {\n\tAnchorLocator,\n\tIForestSubscription,\n\tAnchorSetRootEvents,\n\tAnchor,\n\tAnchorNode,\n\tAnchorSet,\n\tIEditableForest,\n\tTreeStoredSchemaRepository,\n\tassertIsRevisionTag,\n\tcombineVisitors,\n\tvisitDelta,\n\tDetachedFieldIndex,\n\tmakeDetachedFieldIndex,\n\tRevertible,\n\tChangeFamily,\n\ttagChange,\n\tTreeStoredSchema,\n\tTreeStoredSchemaSubscription,\n\tJsonableTree,\n} from \"../core\";\nimport { HasListeners, IEmitter, ISubscribable, createEmitter } from \"../events\";\nimport { buildForest, intoDelta, jsonableTreeFromCursor } from \"../feature-libraries\";\nimport { SharedTreeBranch, getChangeReplaceType } from \"../shared-tree-core\";\nimport { TransactionResult, fail } from \"../util\";\nimport { noopValidator } from \"../codec\";\nimport { SharedTreeChange } from \"./sharedTreeChangeTypes\";\nimport { SharedTreeChangeFamily } from \"./sharedTreeChangeFamily\";\nimport { ISharedTreeEditor, SharedTreeEditBuilder } from \"./sharedTreeEditBuilder\";\n\n/**\n * Events for {@link ITreeCheckout}.\n * @beta\n */\nexport interface CheckoutEvents {\n\t/**\n\t * A batch of changes has finished processing and the view is in a consistent state.\n\t * It is once again safe to access the EditableTree, Forest and AnchorSet.\n\t *\n\t * @remarks\n\t * This is mainly useful for knowing when to do followup work scheduled during events from Anchors.\n\t */\n\tafterBatch(): void;\n\n\t/**\n\t * A revertible change has been made to this view.\n\t * Applications which subscribe to this event are expected to revert or discard revertibles they acquire, if they so choose (failure to do so will leak memory).\n\t * The provided revertible is inherently bound to the view that raised the event, calling `revert` won't apply to forked views.\n\t *\n\t * @remarks\n\t * This event provides a {@link Revertible} object that can be used to revert the change.\n\t */\n\trevertible(revertible: Revertible): void;\n}\n\n/**\n * Provides a means for interacting with a SharedTree.\n * This includes reading data from the tree and running transactions to mutate the tree.\n * @remarks This interface should not have any implementations other than those provided by the SharedTree package libraries.\n * @privateRemarks\n * API for interacting with a {@link SharedTreeBranch}.\n * Implementations of this interface must implement the {@link branchKey} property.\n * @internal\n */\nexport interface ITreeCheckout extends AnchorLocator {\n\t/**\n\t * Read and Write access for schema stored in the document.\n\t *\n\t * These APIs are temporary and will be replaced with different abstractions (View Schema based) in a different place later.\n\t *\n\t * TODO:\n\t * Editing of this should be moved into transactions with the rest of tree editing to they can be intermixed.\n\t * This will be done after the relations between views, branches and Indexes are figured out.\n\t *\n\t * TODO:\n\t * Public APIs for dealing with schema should be in terms of View Schema, and schema update policies.\n\t * The actual stored schema should be hidden (or ar least not be the most prominent way to interact with schema).\n\t *\n\t * TODO:\n\t * Something should ensure the document contents are always in schema.\n\t */\n\treadonly storedSchema: TreeStoredSchemaSubscription;\n\t/**\n\t * Current contents.\n\t * Updated by edits (local and remote).\n\t * Use `editor` to create a local edit.\n\t */\n\treadonly forest: IForestSubscription;\n\n\t/**\n\t * Used to edit the state of the tree. Edits will be immediately applied locally to the tree.\n\t * If there is no transaction currently ongoing, then the edits will be submitted to Fluid immediately as well.\n\t */\n\treadonly editor: ISharedTreeEditor;\n\n\t/**\n\t * A collection of functions for managing transactions.\n\t */\n\treadonly transaction: ITransaction;\n\n\t/**\n\t * Spawn a new view which is based off of the current state of this view.\n\t * Any mutations of the new view will not apply to this view until the new view is merged back into this view via `merge()`.\n\t */\n\tfork(): ITreeCheckoutFork;\n\n\t/**\n\t * Apply all the new changes on the given view to this view.\n\t * @param view - a view which was created by a call to `fork()`.\n\t * It is automatically disposed after the merge completes.\n\t * @remarks All ongoing transactions (if any) in `view` will be committed before the merge.\n\t */\n\tmerge(view: ITreeCheckoutFork): void;\n\n\t/**\n\t * Apply all the new changes on the given view to this view.\n\t * @param view - a view which was created by a call to `fork()`.\n\t * @param disposeView - whether or not to dispose `view` after the merge completes.\n\t * @remarks All ongoing transactions (if any) in `view` will be committed before the merge.\n\t */\n\tmerge(view: ITreeCheckoutFork, disposeView: boolean): void;\n\n\t/**\n\t * Rebase the given view onto this view.\n\t * @param view - a view which was created by a call to `fork()`. It is modified by this operation.\n\t */\n\trebase(view: ITreeCheckoutFork): void;\n\n\t/**\n\t * Replaces all schema with the provided schema.\n\t * Can over-write preexisting schema, and removes unmentioned schema.\n\t */\n\tupdateSchema(newSchema: TreeStoredSchema): void;\n\n\t/**\n\t * Events about this view.\n\t */\n\treadonly events: ISubscribable<CheckoutEvents>;\n\n\t/**\n\t * Events about the root of the tree in this view.\n\t */\n\treadonly rootEvents: ISubscribable<AnchorSetRootEvents>;\n\n\t/**\n\t * Returns a JsonableTree for each tree that was removed from (and not restored to) the document.\n\t * This list is guaranteed to contain all nodes that are recoverable through undo/redo on this checkout.\n\t * The list may also contain additional nodes.\n\t *\n\t * This is only intended for use in testing and exceptional code paths: it is not performant.\n\t */\n\tgetRemovedRoots(): [string | number | undefined, number, JsonableTree][];\n}\n\n/**\n * Creates a {@link TreeCheckout}.\n * @param args - an object containing optional components that will be used to build the view.\n * Any components not provided will be created by default.\n * @remarks This does not create a {@link SharedTree}, but rather a view with the minimal state\n * and functionality required to implement {@link ITreeCheckout}.\n */\nexport function createTreeCheckout(args?: {\n\tbranch?: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>;\n\tchangeFamily?: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>;\n\tschema?: TreeStoredSchemaRepository;\n\tforest?: IEditableForest;\n\tevents?: ISubscribable<CheckoutEvents> &\n\t\tIEmitter<CheckoutEvents> &\n\t\tHasListeners<CheckoutEvents>;\n\tremovedRoots?: DetachedFieldIndex;\n}): TreeCheckout {\n\tconst forest = args?.forest ?? buildForest();\n\tconst changeFamily =\n\t\targs?.changeFamily ?? new SharedTreeChangeFamily({ jsonValidator: noopValidator });\n\tconst branch =\n\t\targs?.branch ??\n\t\tnew SharedTreeBranch(\n\t\t\t{\n\t\t\t\tchange: changeFamily.rebaser.compose([]),\n\t\t\t\trevision: assertIsRevisionTag(\"00000000-0000-4000-8000-000000000000\"),\n\t\t\t},\n\t\t\tchangeFamily,\n\t\t);\n\tconst schema = args?.schema ?? new TreeStoredSchemaRepository();\n\tconst events = args?.events ?? createEmitter();\n\n\tconst transaction = new Transaction(branch);\n\n\treturn new TreeCheckout(\n\t\ttransaction,\n\t\tbranch,\n\t\tchangeFamily,\n\t\tschema,\n\t\tforest,\n\t\tevents,\n\t\targs?.removedRoots,\n\t);\n}\n\n/**\n * A collection of functions for managing transactions.\n * Transactions allow edits to be batched into atomic units.\n * 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.\n * If the transaction is aborted, the local state will be reset to what it was before the transaction began.\n * Transactions may nest, meaning that a transaction may be started while a transaction is already ongoing.\n *\n * To avoid updating observers of the view state with intermediate results during a transaction,\n * use {@link ITreeCheckout#fork} and {@link ISharedTreeFork#merge}.\n * @internal\n */\nexport interface ITransaction {\n\t/**\n\t * Start a new transaction.\n\t * If a transaction is already in progress when this new transaction starts, then this transaction will be \"nested\" inside of it,\n\t * i.e. the outer transaction will still be in progress after this new transaction is committed or aborted.\n\t *\n\t * @remarks - Asynchronous transactions are not supported on the root checkout,\n\t * since it is always kept up-to-date with the latest remote edits and the results of this rebasing (which might invalidate\n\t * the transaction) is not visible to the application author.\n\t * Instead,\n\t *\n\t * 1. fork the root checkout\n\t * 2. run the transaction on the fork\n\t * 3. merge the fork back into the root checkout\n\t *\n\t * @privateRemarks - There is currently no enforcement that asynchronous transactions don't happen on the root checkout.\n\t * AB#6488 tracks adding some enforcement to make it more clear to application authors that this is not supported.\n\t */\n\tstart(): void;\n\t/**\n\t * Close this transaction by squashing its edits and committing them as a single edit.\n\t * If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.\n\t */\n\tcommit(): TransactionResult.Commit;\n\t/**\n\t * Close this transaction and revert the state of the tree to what it was before this transaction began.\n\t */\n\tabort(): TransactionResult.Abort;\n\t/**\n\t * True if there is at least one transaction currently in progress on this view, otherwise false.\n\t */\n\tinProgress(): boolean;\n}\n\nclass Transaction implements ITransaction {\n\tpublic constructor(\n\t\tprivate readonly branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,\n\t) {}\n\n\tpublic start(): void {\n\t\tthis.branch.startTransaction();\n\t\tthis.branch.editor.enterTransaction();\n\t}\n\tpublic commit(): TransactionResult.Commit {\n\t\tthis.branch.commitTransaction();\n\t\tthis.branch.editor.exitTransaction();\n\t\treturn TransactionResult.Commit;\n\t}\n\tpublic abort(): TransactionResult.Abort {\n\t\tthis.branch.abortTransaction();\n\t\tthis.branch.editor.exitTransaction();\n\t\treturn TransactionResult.Abort;\n\t}\n\tpublic inProgress(): boolean {\n\t\treturn this.branch.isTransacting();\n\t}\n}\n\n/**\n * Branch (like in a version control system) of SharedTree.\n *\n * {@link ITreeCheckout} that has forked off of the main trunk/branch.\n * @internal\n */\nexport interface ITreeCheckoutFork extends ITreeCheckout {\n\t/**\n\t * Rebase the changes that have been applied to this view over all the new changes in the given view.\n\t * @param view - Either the root view or a view that was created by a call to `fork()`. It is not modified by this operation.\n\t */\n\trebaseOnto(view: ITreeCheckout): void;\n}\n\n/**\n * An implementation of {@link ITreeCheckoutFork}.\n */\nexport class TreeCheckout implements ITreeCheckoutFork {\n\tpublic constructor(\n\t\tpublic readonly transaction: ITransaction,\n\t\tprivate readonly branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,\n\t\tprivate readonly changeFamily: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>,\n\t\tpublic readonly storedSchema: TreeStoredSchemaRepository,\n\t\tpublic readonly forest: IEditableForest,\n\t\tpublic readonly events: ISubscribable<CheckoutEvents> &\n\t\t\tIEmitter<CheckoutEvents> &\n\t\t\tHasListeners<CheckoutEvents>,\n\t\tprivate readonly removedRoots: DetachedFieldIndex = makeDetachedFieldIndex(\"repair\"),\n\t) {\n\t\t// We subscribe to `beforeChange` rather than `afterChange` here because it's possible that the change is invalid WRT our forest.\n\t\t// 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.\n\t\t// In such a case we will crash here, preventing the change from being added to the commit graph, and preventing `afterChange` from firing.\n\t\t// 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`.\n\t\tbranch.on(\"beforeChange\", (event) => {\n\t\t\tif (event.change !== undefined) {\n\t\t\t\t// Conflicts due to schema will be empty and thus are not applied.\n\t\t\t\tfor (const change of event.change.change.changes) {\n\t\t\t\t\tif (change.type === \"data\") {\n\t\t\t\t\t\tconst delta = intoDelta(\n\t\t\t\t\t\t\ttagChange(change.innerChange, event.change.revision),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tconst anchorVisitor = this.forest.anchors.acquireVisitor();\n\t\t\t\t\t\tconst combinedVisitor = combineVisitors(\n\t\t\t\t\t\t\t[this.forest.acquireVisitor(), anchorVisitor],\n\t\t\t\t\t\t\t[anchorVisitor],\n\t\t\t\t\t\t);\n\t\t\t\t\t\tvisitDelta(delta, combinedVisitor, this.removedRoots);\n\t\t\t\t\t\tcombinedVisitor.free();\n\t\t\t\t\t} else if (change.type === \"schema\") {\n\t\t\t\t\t\tif (change.innerChange.schema !== undefined) {\n\t\t\t\t\t\t\tstoredSchema.apply(change.innerChange.schema.new);\n\t\t\t\t\t\t}\n\t\t\t\t\t} else {\n\t\t\t\t\t\tfail(\"Unknown Shared Tree change type.\");\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tthis.events.emit(\"afterBatch\");\n\t\t\t}\n\t\t\tif (event.type === \"replace\" && getChangeReplaceType(event) === \"transactionCommit\") {\n\t\t\t\tconst transactionRevision = event.newCommits[0].revision;\n\t\t\t\tfor (const transactionStep of event.removedCommits) {\n\t\t\t\t\tthis.removedRoots.updateMajor(transactionStep.revision, transactionRevision);\n\t\t\t\t}\n\t\t\t}\n\t\t});\n\t\tbranch.on(\"revertible\", (revertible) => {\n\t\t\t// if there are no listeners, discard the revertible to avoid memory leaks\n\t\t\tif (!this.events.hasListeners(\"revertible\")) {\n\t\t\t\trevertible.discard();\n\t\t\t} else {\n\t\t\t\tthis.events.emit(\"revertible\", revertible);\n\t\t\t}\n\t\t});\n\t}\n\n\tpublic get rootEvents(): ISubscribable<AnchorSetRootEvents> {\n\t\treturn this.forest.anchors;\n\t}\n\n\tpublic get editor(): ISharedTreeEditor {\n\t\treturn this.branch.editor;\n\t}\n\n\tpublic locate(anchor: Anchor): AnchorNode | undefined {\n\t\treturn this.forest.anchors.locate(anchor);\n\t}\n\n\tpublic fork(): TreeCheckout {\n\t\tconst anchors = new AnchorSet();\n\t\tconst branch = this.branch.fork();\n\t\tconst storedSchema = this.storedSchema.clone();\n\t\tconst forest = this.forest.clone(storedSchema, anchors);\n\t\tconst transaction = new Transaction(branch);\n\t\treturn new TreeCheckout(\n\t\t\ttransaction,\n\t\t\tbranch,\n\t\t\tthis.changeFamily,\n\t\t\tstoredSchema,\n\t\t\tforest,\n\t\t\tcreateEmitter(),\n\t\t\tthis.removedRoots.clone(),\n\t\t);\n\t}\n\n\tpublic rebase(view: TreeCheckout): void {\n\t\tview.branch.rebaseOnto(this.branch);\n\t}\n\n\tpublic rebaseOnto(view: ITreeCheckout): void {\n\t\tview.rebase(this);\n\t}\n\n\tpublic merge(view: TreeCheckout): void;\n\tpublic merge(view: TreeCheckout, disposeView: boolean): void;\n\tpublic merge(view: TreeCheckout, disposeView = true): void {\n\t\tassert(\n\t\t\t!this.transaction.inProgress() || disposeView,\n\t\t\t0x710 /* A view that is merged into an in-progress transaction must be disposed */,\n\t\t);\n\t\twhile (view.transaction.inProgress()) {\n\t\t\tview.transaction.commit();\n\t\t}\n\t\tthis.branch.merge(view.branch);\n\t\tif (disposeView) {\n\t\t\tview.dispose();\n\t\t}\n\t}\n\n\tpublic updateSchema(newSchema: TreeStoredSchema): void {\n\t\tthis.editor.schema.setStoredSchema(this.storedSchema.clone(), newSchema);\n\t}\n\n\t/**\n\t * Dispose this view, freezing its state and allowing the SharedTree to release resources required by it.\n\t * Attempts to further mutate or dispose this view will error.\n\t */\n\tpublic dispose(): void {\n\t\tthis.branch.dispose();\n\t}\n\n\tpublic getRemovedRoots(): [string | number | undefined, number, JsonableTree][] {\n\t\tconst trees: [string | number | undefined, number, JsonableTree][] = [];\n\t\tconst cursor = this.forest.allocateCursor();\n\t\tfor (const { id, root } of this.removedRoots.entries()) {\n\t\t\tconst parentField = this.removedRoots.toFieldKey(root);\n\t\t\tthis.forest.moveCursorToPath(\n\t\t\t\t{ parent: undefined, parentField, parentIndex: 0 },\n\t\t\t\tcursor,\n\t\t\t);\n\t\t\tconst tree = jsonableTreeFromCursor(cursor);\n\t\t\tif (tree !== undefined) {\n\t\t\t\ttrees.push([id.major, id.minor, tree]);\n\t\t\t}\n\t\t}\n\t\tcursor.free();\n\t\treturn trees;\n\t}\n}\n\n/**\n * Run a synchronous transaction on the given shared tree view.\n * This is a convenience helper around the {@link SharedTreeFork#transaction} APIs.\n * @param view - the view on which to run the transaction\n * @param transaction - the transaction function. This will be executed immediately. It is passed `view` as an argument for convenience.\n * If this function returns an `Abort` result then the transaction will be aborted. Otherwise, it will be committed.\n * @returns whether or not the transaction was committed or aborted\n * @internal\n */\nexport function runSynchronous(\n\tview: ITreeCheckout,\n\ttransaction: (view: ITreeCheckout) => TransactionResult | void,\n): TransactionResult {\n\tview.transaction.start();\n\tconst result = transaction(view);\n\treturn result === TransactionResult.Abort\n\t\t? view.transaction.abort()\n\t\t: view.transaction.commit();\n}\n"]}

package/dist/shared-tree/treeView.d.ts

@@ -0,0 +1,66 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { FieldKey } from "../core";
+import { TreeFieldSchema, FlexTreeSchema, FlexTreeTypedField, FlexTreeContext, NodeKeyManager, Context } from "../feature-libraries";
+import { IDisposable, disposeSymbol } from "../util";
+import { ITreeCheckoutFork, ITreeCheckout } from "./treeCheckout";
+/**
+ * An editable view of a (version control style) branch of a shared tree.
+ * @privateRemarks
+ * TODO:
+ * 1. Once ISharedTreeView is renamed this can become ISharedTreeView.
+ * 2. This object should be combined with or accessible from the TreeContext to allow easy access to thinks like branching.
+ * @internal
+ */
+export interface FlexTreeView<in out TRoot extends TreeFieldSchema> extends IDisposable {
+    /**
+     * Context for controlling the EditableTree nodes produced from {@link FlexTreeView.editableTree}.
+     *
+     * @remarks
+     * This is an owning reference: disposing of this view disposes its context.
+     */
+    readonly context: FlexTreeContext;
+    /**
+     * Access non-view schema specific aspects of of this branch.
+     *
+     * @remarks
+     * This is a non-owning reference: disposing of this view does not impact the branch.
+     */
+    readonly checkout: ITreeCheckout;
+    /**
+     * Get a typed view of the tree content using the editable-tree-2 API.
+     */
+    readonly editableTree: FlexTreeTypedField<TRoot>;
+    /**
+     * Spawn a new view which is based off of the current state of this view.
+     * Any mutations of the new view will not apply to this view until the new view is merged back into this view via `merge()`.
+     */
+    fork(): ITreeViewFork<TRoot>;
+}
+/**
+ * Branch (like in a version control system) of SharedTree.
+ *
+ * {@link FlexTreeView} that has forked off of the main trunk/branch.
+ * @internal
+ */
+export interface ITreeViewFork<in out TRoot extends TreeFieldSchema> extends FlexTreeView<TRoot> {
+    readonly checkout: ITreeCheckoutFork;
+}
+/**
+ * Implementation of FlexTreeView wrapping a ITreeCheckout.
+ */
+export declare class CheckoutFlexTreeView<in out TRoot extends TreeFieldSchema, out TCheckout extends ITreeCheckout = ITreeCheckout> implements FlexTreeView<TRoot> {
+    readonly checkout: TCheckout;
+    readonly schema: FlexTreeSchema<TRoot>;
+    readonly nodeKeyManager: NodeKeyManager;
+    readonly nodeKeyFieldKey: FieldKey;
+    private readonly onDispose?;
+    readonly context: Context;
+    readonly editableTree: FlexTreeTypedField<TRoot>;
+    constructor(checkout: TCheckout, schema: FlexTreeSchema<TRoot>, nodeKeyManager: NodeKeyManager, nodeKeyFieldKey: FieldKey, onDispose?: (() => void) | undefined);
+    [disposeSymbol](): void;
+    fork(): CheckoutFlexTreeView<TRoot, ITreeCheckoutFork>;
+}
+//# sourceMappingURL=treeView.d.ts.map

package/dist/shared-tree/treeView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeView.d.ts","sourceRoot":"","sources":["../../src/shared-tree/treeView.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EACN,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,cAAc,EAEd,OAAO,EACP,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,SAAS,eAAe,CAAE,SAAQ,WAAW;IACtF;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAEjD;;;OAGG;IACH,IAAI,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,SAAS,eAAe,CAAE,SAAQ,YAAY,CAAC,KAAK,CAAC;IAC/F,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACrC;AAED;;GAEG;AACH,qBAAa,oBAAoB,CAChC,EAAE,CAAC,GAAG,CAAC,KAAK,SAAS,eAAe,EACpC,GAAG,CAAC,SAAS,SAAS,aAAa,GAAG,aAAa,CAClD,YAAW,YAAY,CAAC,KAAK,CAAC;aAKd,QAAQ,EAAE,SAAS;aACnB,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC;aAC7B,cAAc,EAAE,cAAc;aAC9B,eAAe,EAAE,QAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAP5B,SAAgB,OAAO,EAAE,OAAO,CAAC;IACjC,SAAgB,YAAY,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;gBAEvC,QAAQ,EAAE,SAAS,EACnB,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,EAC7B,cAAc,EAAE,cAAc,EAC9B,eAAe,EAAE,QAAQ,EACxB,SAAS,CAAC,SAAQ,IAAI,aAAA;IAYjC,CAAC,aAAa,CAAC,IAAI,IAAI;IAKvB,IAAI,IAAI,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,CAAC;CAS7D"}

package/dist/shared-tree/treeView.js

@@ -0,0 +1,33 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckoutFlexTreeView = void 0;
+const feature_libraries_1 = require("../feature-libraries");
+const util_1 = require("../util");
+/**
+ * Implementation of FlexTreeView wrapping a ITreeCheckout.
+ */
+class CheckoutFlexTreeView {
+    constructor(checkout, schema, nodeKeyManager, nodeKeyFieldKey, onDispose) {
+        this.checkout = checkout;
+        this.schema = schema;
+        this.nodeKeyManager = nodeKeyManager;
+        this.nodeKeyFieldKey = nodeKeyFieldKey;
+        this.onDispose = onDispose;
+        this.context = (0, feature_libraries_1.getTreeContext)(schema, this.checkout.forest, this.checkout.editor, nodeKeyManager, nodeKeyFieldKey);
+        this.editableTree = this.context.root;
+    }
+    [util_1.disposeSymbol]() {
+        this.context[util_1.disposeSymbol]();
+        this.onDispose?.();
+    }
+    fork() {
+        const branch = this.checkout.fork();
+        return new CheckoutFlexTreeView(branch, this.schema, this.nodeKeyManager, this.nodeKeyFieldKey);
+    }
+}
+exports.CheckoutFlexTreeView = CheckoutFlexTreeView;
+//# sourceMappingURL=treeView.js.map

package/dist/shared-tree/treeView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeView.js","sourceRoot":"","sources":["../../src/shared-tree/treeView.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,4DAQ8B;AAC9B,kCAAqD;AAkDrD;;GAEG;AACH,MAAa,oBAAoB;IAOhC,YACiB,QAAmB,EACnB,MAA6B,EAC7B,cAA8B,EAC9B,eAAyB,EACxB,SAAsB;QAJvB,aAAQ,GAAR,QAAQ,CAAW;QACnB,WAAM,GAAN,MAAM,CAAuB;QAC7B,mBAAc,GAAd,cAAc,CAAgB;QAC9B,oBAAe,GAAf,eAAe,CAAU;QACxB,cAAS,GAAT,SAAS,CAAa;QAEvC,IAAI,CAAC,OAAO,GAAG,IAAA,kCAAc,EAC5B,MAAM,EACN,IAAI,CAAC,QAAQ,CAAC,MAAM,EACpB,IAAI,CAAC,QAAQ,CAAC,MAAM,EACpB,cAAc,EACd,eAAe,CACf,CAAC;QACF,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAiC,CAAC;IACpE,CAAC;IAEM,CAAC,oBAAa,CAAC;QACrB,IAAI,CAAC,OAAO,CAAC,oBAAa,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;IACpB,CAAC;IAEM,IAAI;QACV,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACpC,OAAO,IAAI,oBAAoB,CAC9B,MAAM,EACN,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,cAAc,EACnB,IAAI,CAAC,eAAe,CACpB,CAAC;IACH,CAAC;CACD;AAtCD,oDAsCC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { FieldKey } from \"../core\";\nimport {\n\tTreeFieldSchema,\n\tFlexTreeSchema,\n\tFlexTreeTypedField,\n\tFlexTreeContext,\n\tNodeKeyManager,\n\tgetTreeContext,\n\tContext,\n} from \"../feature-libraries\";\nimport { IDisposable, disposeSymbol } from \"../util\";\nimport { ITreeCheckoutFork, ITreeCheckout } from \"./treeCheckout\";\n\n/**\n * An editable view of a (version control style) branch of a shared tree.\n * @privateRemarks\n * TODO:\n * 1. Once ISharedTreeView is renamed this can become ISharedTreeView.\n * 2. This object should be combined with or accessible from the TreeContext to allow easy access to thinks like branching.\n * @internal\n */\nexport interface FlexTreeView<in out TRoot extends TreeFieldSchema> extends IDisposable {\n\t/**\n\t * Context for controlling the EditableTree nodes produced from {@link FlexTreeView.editableTree}.\n\t *\n\t * @remarks\n\t * This is an owning reference: disposing of this view disposes its context.\n\t */\n\treadonly context: FlexTreeContext;\n\n\t/**\n\t * Access non-view schema specific aspects of of this branch.\n\t *\n\t * @remarks\n\t * This is a non-owning reference: disposing of this view does not impact the branch.\n\t */\n\treadonly checkout: ITreeCheckout;\n\n\t/**\n\t * Get a typed view of the tree content using the editable-tree-2 API.\n\t */\n\treadonly editableTree: FlexTreeTypedField<TRoot>;\n\n\t/**\n\t * Spawn a new view which is based off of the current state of this view.\n\t * Any mutations of the new view will not apply to this view until the new view is merged back into this view via `merge()`.\n\t */\n\tfork(): ITreeViewFork<TRoot>;\n}\n\n/**\n * Branch (like in a version control system) of SharedTree.\n *\n * {@link FlexTreeView} that has forked off of the main trunk/branch.\n * @internal\n */\nexport interface ITreeViewFork<in out TRoot extends TreeFieldSchema> extends FlexTreeView<TRoot> {\n\treadonly checkout: ITreeCheckoutFork;\n}\n\n/**\n * Implementation of FlexTreeView wrapping a ITreeCheckout.\n */\nexport class CheckoutFlexTreeView<\n\tin out TRoot extends TreeFieldSchema,\n\tout TCheckout extends ITreeCheckout = ITreeCheckout,\n> implements FlexTreeView<TRoot>\n{\n\tpublic readonly context: Context;\n\tpublic readonly editableTree: FlexTreeTypedField<TRoot>;\n\tpublic constructor(\n\t\tpublic readonly checkout: TCheckout,\n\t\tpublic readonly schema: FlexTreeSchema<TRoot>,\n\t\tpublic readonly nodeKeyManager: NodeKeyManager,\n\t\tpublic readonly nodeKeyFieldKey: FieldKey,\n\t\tprivate readonly onDispose?: () => void,\n\t) {\n\t\tthis.context = getTreeContext(\n\t\t\tschema,\n\t\t\tthis.checkout.forest,\n\t\t\tthis.checkout.editor,\n\t\t\tnodeKeyManager,\n\t\t\tnodeKeyFieldKey,\n\t\t);\n\t\tthis.editableTree = this.context.root as FlexTreeTypedField<TRoot>;\n\t}\n\n\tpublic [disposeSymbol](): void {\n\t\tthis.context[disposeSymbol]();\n\t\tthis.onDispose?.();\n\t}\n\n\tpublic fork(): CheckoutFlexTreeView<TRoot, ITreeCheckoutFork> {\n\t\tconst branch = this.checkout.fork();\n\t\treturn new CheckoutFlexTreeView(\n\t\t\tbranch,\n\t\t\tthis.schema,\n\t\t\tthis.nodeKeyManager,\n\t\t\tthis.nodeKeyFieldKey,\n\t\t);\n\t}\n}\n"]}