@fluid-experimental/tree 0.58.2002 → 0.59.1000

package/lib/TransactionInternal.js

@@ -0,0 +1,622 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assert, copyPropertyIfDefined, fail, Result } from './Common';
+import { isDetachedSequenceId } from './Identifiers';
+import { rangeFromStableRange } from './TreeViewUtilities';
+import { ChangeTypeInternal, ConstraintEffect, EditStatus, } from './persisted-types';
+import { detachRange, insertIntoTrait, validateStablePlace, validateStableRange, PlaceValidationResult, RangeValidationResultKind, } from './EditUtilities';
+/**
+ * A mutable transaction for applying sequences of changes to a TreeView.
+ * Allows viewing the intermediate states.
+ *
+ * Contains necessary state to apply changes within an edit to a TreeView.
+ *
+ * May have any number of changes applied to make up the edit.
+ * Use `close` to complete the transaction, returning the array of changes and an EditingResult showing the
+ * results of applying the changes as an Edit to the initial TreeView (passed to the constructor).
+ *
+ * No data outside the Transaction is modified by Transaction:
+ * the results from `close` must be used to actually submit an `Edit`.
+ */
+export class GenericTransaction {
+    /**
+     * Create and open an edit of the provided `TreeView`. After applying 0 or more changes, this editor should be closed via `close()`.
+     * @param view - the `TreeView` at which this edit begins. The first change will be applied against this view.
+     */
+    constructor(view, policy) {
+        this.open = true;
+        this.before = view;
+        this.policy = policy;
+        this.state = {
+            view: view.openForTransaction(),
+            status: EditStatus.Applied,
+            changes: [],
+            steps: [],
+        };
+    }
+    /** Whether or not this transaction has been closed via `close()` */
+    get isOpen() {
+        return this.open;
+    }
+    /**
+     * The most up-to-date `TreeView` for this edit. This is the state of the tree after all changes applied so far.
+     */
+    get view() {
+        return this.state.view;
+    }
+    /**
+     * The status code of the most recent attempted change.
+     */
+    get status() {
+        return this.state.status;
+    }
+    /**
+     * The status code of the most recent attempted change.
+     */
+    get changes() {
+        return this.state.changes;
+    }
+    /**
+     * The status code of the most recent attempted change.
+     */
+    get steps() {
+        return this.state.steps;
+    }
+    /** @returns the final `EditStatus` and `TreeView` after all changes are applied. */
+    close() {
+        assert(this.open, 'transaction has already been closed');
+        this.open = false;
+        if (this.state.status === EditStatus.Applied) {
+            const validation = this.policy.validateOnClose(this.state);
+            if (Result.isOk(validation)) {
+                if (validation.result !== this.view) {
+                    this.state = Object.assign(Object.assign({}, this.state), { view: validation.result });
+                }
+                return {
+                    status: EditStatus.Applied,
+                    steps: this.steps,
+                    changes: this.changes,
+                    before: this.before,
+                    after: this.view.close(),
+                };
+            }
+            this.state = Object.assign(Object.assign({}, this.state), validation.error);
+            return Object.assign(Object.assign({}, validation.error), { steps: this.steps, changes: this.changes, before: this.before });
+        }
+        return {
+            status: this.state.status,
+            failure: this.state.failure,
+            steps: this.steps,
+            changes: this.changes,
+            before: this.before,
+        };
+    }
+    /**
+     * A helper to apply a sequence of changes. Changes will be applied one after the other. If a change fails to apply,
+     * the remaining changes in `changes` will be ignored.
+     * @param changes - the sequence of changes to apply.
+     * @param path - the reconciliation path for the first change.
+     * @returns this
+     */
+    applyChanges(changes, path = []) {
+        const iter = changes[Symbol.iterator]();
+        const firsChangeInternal = iter.next().value;
+        let iterResult = iter.next();
+        if (iterResult.done === true) {
+            for (const change of changes) {
+                if (this.applyChange(change, path).status !== EditStatus.Applied) {
+                    return this;
+                }
+            }
+            return this;
+        }
+        if (this.applyChange(firsChangeInternal, path).status !== EditStatus.Applied) {
+            return this;
+        }
+        const ongoingEdit = {
+            0: this.steps[this.steps.length - 1],
+            before: this.view,
+            after: this.view,
+            length: 1,
+        };
+        /**
+         * We use a Proxy instead of `{ ...path, ...objectWithOngoingEdit }` to avoid eagerly demanding all parts of the path, which may
+         * require extensive computation.
+         */
+        const pathWithOngoingEdit = new Proxy(path, {
+            get: (target, prop) => {
+                if (prop === 'length') {
+                    return target.length + 1;
+                }
+                return prop === String(target.length) ? ongoingEdit : target[prop];
+            },
+        });
+        while (iterResult.done !== true) {
+            if (this.applyChange(iterResult.value, pathWithOngoingEdit).status !== EditStatus.Applied) {
+                return this;
+            }
+            ongoingEdit[ongoingEdit.length] = this.steps[this.steps.length - 1];
+            ongoingEdit.length += 1;
+            ongoingEdit.after = this.view;
+            iterResult = iter.next();
+        }
+        return this;
+    }
+    /**
+     * Attempt to apply the given change as part of this edit. This method should not be called if a previous change in this edit failed to
+     * apply.
+     * @param change - the change to apply
+     * @param path - the reconciliation path for the change.
+     * @returns this
+     */
+    applyChange(change, path = []) {
+        assert(this.open, 'Editor must be open to apply changes.');
+        if (this.state.status !== EditStatus.Applied) {
+            fail('Cannot apply change to an edit unless all previous changes have applied');
+        }
+        const resolutionResult = this.policy.tryResolveChange(this.state, change, path);
+        if (Result.isError(resolutionResult)) {
+            this.state = Object.assign(Object.assign({}, this.state), resolutionResult.error);
+            return this;
+        }
+        const resolvedChange = resolutionResult.result;
+        const changeResult = this.policy.dispatchChange(this.state, resolvedChange);
+        if (Result.isOk(changeResult)) {
+            this.state = {
+                status: EditStatus.Applied,
+                view: changeResult.result,
+                changes: this.changes.concat(change),
+                steps: this.steps.concat({ resolvedChange, after: changeResult.result }),
+            };
+        }
+        else {
+            this.state = Object.assign(Object.assign({}, this.state), changeResult.error);
+        }
+        return this;
+    }
+}
+/**
+ * A mutable transaction for applying sequences of changes to a TreeView.
+ * Allows viewing the intermediate states.
+ *
+ * Contains necessary state to apply changes within an edit to a TreeView.
+ *
+ * May have any number of changes applied to make up the edit.
+ * Use `close` to complete the transaction, returning the array of changes and an EditingResult showing the
+ * results of applying the changes as an Edit to the initial TreeView (passed to the constructor).
+ *
+ * No data outside the Transaction is modified by Transaction:
+ * the results from `close` must be used to actually submit an `Edit`.
+ * @public
+ */
+export var TransactionInternal;
+(function (TransactionInternal) {
+    /**
+     * Makes a new {@link GenericTransaction} that follows the {@link TransactionInternal.Policy} policy.
+     */
+    function factory(view) {
+        return new GenericTransaction(view, new Policy());
+    }
+    TransactionInternal.factory = factory;
+    /**
+     * The policy followed by a {@link TransactionInternal}.
+     */
+    class Policy {
+        constructor() {
+            /**
+             * Maps detached sequences of nodes to their NodeIds
+             */
+            this.detached = new Map();
+        }
+        /**
+         * Resolves change with Result.Ok
+         *
+         * @param state - Unused
+         * @param change - Change to resolve
+         * @returns Result.Ok which contains change
+         */
+        tryResolveChange(state, change) {
+            return Result.ok(change);
+        }
+        /**
+         * Validates the transaction when it is closed
+         *
+         * @param state - Current state
+         * @returns a {@link ChangeResult} containing either the change result or a Failure
+         */
+        validateOnClose(state) {
+            // Making the policy choice that storing a detached sequences in an edit but not using it is an error.
+            return this.detached.size !== 0
+                ? Result.error({
+                    status: EditStatus.Malformed,
+                    failure: {
+                        kind: FailureKind.UnusedDetachedSequence,
+                        sequenceId: this.detached.keys().next().value,
+                    },
+                })
+                : Result.ok(state.view);
+        }
+        /**
+         * Applies a given change
+         *
+         * @param state - Current state
+         * @param change - Change to apply
+         * @returns a {@link ChangeResult} containing either the change result or a Failure
+         */
+        dispatchChange(state, change) {
+            switch (change.type) {
+                case ChangeTypeInternal.Build:
+                    return this.applyBuild(state, change);
+                case ChangeTypeInternal.Insert:
+                    return this.applyInsert(state, change);
+                case ChangeTypeInternal.Detach:
+                    return this.applyDetach(state, change);
+                case ChangeTypeInternal.Constraint:
+                    return this.applyConstraint(state, change);
+                case ChangeTypeInternal.SetValue:
+                    return this.applySetValue(state, change);
+                default:
+                    return fail('Attempted to apply unsupported change');
+            }
+        }
+        applyBuild(state, change) {
+            if (this.detached.has(change.destination)) {
+                return Result.error({
+                    status: EditStatus.Malformed,
+                    failure: {
+                        kind: FailureKind.DetachedSequenceIdAlreadyInUse,
+                        change,
+                        sequenceId: change.destination,
+                    },
+                });
+            }
+            let idAlreadyPresent;
+            let duplicateIdInBuild;
+            let invalidId;
+            let detachedSequenceNotFound;
+            const map = new Map();
+            const newIds = this.createViewNodesForTree(change.source, (id, viewNode) => {
+                if (map.has(id)) {
+                    duplicateIdInBuild = id;
+                    return true;
+                }
+                if (state.view.hasNode(viewNode.identifier)) {
+                    idAlreadyPresent = id;
+                    return true;
+                }
+                map.set(id, viewNode);
+                return false;
+            }, (detachedId) => {
+                detachedSequenceNotFound = detachedId;
+            });
+            if (idAlreadyPresent !== undefined) {
+                return Result.error({
+                    status: EditStatus.Invalid,
+                    failure: { kind: FailureKind.IdAlreadyInUse, change, id: idAlreadyPresent },
+                });
+            }
+            if (duplicateIdInBuild !== undefined) {
+                return Result.error({
+                    status: EditStatus.Malformed,
+                    failure: { kind: FailureKind.DuplicateIdInBuild, change, id: duplicateIdInBuild },
+                });
+            }
+            if (invalidId !== undefined) {
+                return Result.error({
+                    status: EditStatus.Invalid,
+                    failure: { kind: FailureKind.UnknownId, change, id: invalidId },
+                });
+            }
+            if (detachedSequenceNotFound !== undefined) {
+                return Result.error({
+                    status: EditStatus.Malformed,
+                    failure: {
+                        kind: FailureKind.DetachedSequenceNotFound,
+                        change,
+                        sequenceId: detachedSequenceNotFound,
+                    },
+                });
+            }
+            const view = state.view.addNodes(map.values());
+            this.detached.set(change.destination, newIds !== null && newIds !== void 0 ? newIds : fail('Unhandled failure case in Transaction.createViewNodesForTree'));
+            return Result.ok(view);
+        }
+        applyInsert(state, change) {
+            const source = this.detached.get(change.source);
+            if (source === undefined) {
+                return Result.error({
+                    status: EditStatus.Malformed,
+                    failure: {
+                        kind: FailureKind.DetachedSequenceNotFound,
+                        change,
+                        sequenceId: change.source,
+                    },
+                });
+            }
+            const validatedDestination = validateStablePlace(state.view, change.destination);
+            if (validatedDestination.result !== PlaceValidationResult.Valid) {
+                return Result.error({
+                    status: validatedDestination.result === PlaceValidationResult.Malformed
+                        ? EditStatus.Malformed
+                        : EditStatus.Invalid,
+                    failure: {
+                        kind: FailureKind.BadPlace,
+                        change,
+                        place: change.destination,
+                        placeFailure: validatedDestination.result,
+                    },
+                });
+            }
+            this.detached.delete(change.source);
+            const view = insertIntoTrait(state.view, source, validatedDestination);
+            return Result.ok(view);
+        }
+        applyDetach(state, change) {
+            const validatedSource = validateStableRange(state.view, change.source);
+            if (validatedSource.result !== RangeValidationResultKind.Valid) {
+                return Result.error({
+                    status: validatedSource.result === RangeValidationResultKind.PlacesInDifferentTraits ||
+                        validatedSource.result === RangeValidationResultKind.Inverted ||
+                        validatedSource.result.placeFailure !== PlaceValidationResult.Malformed
+                        ? EditStatus.Invalid
+                        : EditStatus.Malformed,
+                    failure: {
+                        kind: FailureKind.BadRange,
+                        change,
+                        range: change.source,
+                        rangeFailure: validatedSource.result,
+                    },
+                });
+            }
+            const result = detachRange(state.view, validatedSource);
+            let modifiedView = result.view;
+            const { detached } = result;
+            // Store or dispose detached
+            if (change.destination !== undefined) {
+                if (this.detached.has(change.destination)) {
+                    return Result.error({
+                        status: EditStatus.Malformed,
+                        failure: {
+                            kind: FailureKind.DetachedSequenceIdAlreadyInUse,
+                            change,
+                            sequenceId: change.destination,
+                        },
+                    });
+                }
+                this.detached.set(change.destination, detached);
+            }
+            else {
+                modifiedView = modifiedView.deleteNodes(detached);
+            }
+            return Result.ok(modifiedView);
+        }
+        applyConstraint(state, change) {
+            // TODO: Implement identityHash and contentHash
+            assert(change.identityHash === undefined, 'identityHash constraint is not implemented');
+            assert(change.contentHash === undefined, 'contentHash constraint is not implemented');
+            const validatedChange = validateStableRange(state.view, change.toConstrain);
+            if (validatedChange.result !== RangeValidationResultKind.Valid) {
+                return validatedChange.result !== RangeValidationResultKind.PlacesInDifferentTraits &&
+                    validatedChange.result !== RangeValidationResultKind.Inverted &&
+                    validatedChange.result.placeFailure !== PlaceValidationResult.Malformed
+                    ? change.effect === ConstraintEffect.ValidRetry
+                        ? Result.ok(state.view)
+                        : Result.error({
+                            status: EditStatus.Invalid,
+                            failure: {
+                                kind: FailureKind.ConstraintViolation,
+                                constraint: change,
+                                violation: {
+                                    kind: ConstraintViolationKind.BadRange,
+                                    rangeFailure: validatedChange.result,
+                                },
+                            },
+                        })
+                    : Result.error({
+                        status: EditStatus.Malformed,
+                        failure: {
+                            kind: FailureKind.ConstraintViolation,
+                            constraint: change,
+                            violation: {
+                                kind: ConstraintViolationKind.BadRange,
+                                rangeFailure: validatedChange.result,
+                            },
+                        },
+                    });
+            }
+            const { start, end } = rangeFromStableRange(state.view, validatedChange);
+            const startIndex = state.view.findIndexWithinTrait(start);
+            const endIndex = state.view.findIndexWithinTrait(end);
+            if (change.length !== undefined && change.length !== endIndex - startIndex) {
+                return Result.error({
+                    status: EditStatus.Invalid,
+                    failure: {
+                        kind: FailureKind.ConstraintViolation,
+                        constraint: change,
+                        violation: {
+                            kind: ConstraintViolationKind.BadLength,
+                            actual: endIndex - startIndex,
+                        },
+                    },
+                });
+            }
+            if (change.parentNode !== undefined && change.parentNode !== end.trait.parent) {
+                return Result.error({
+                    status: EditStatus.Invalid,
+                    failure: {
+                        kind: FailureKind.ConstraintViolation,
+                        constraint: change,
+                        violation: {
+                            kind: ConstraintViolationKind.BadParent,
+                            actual: change.parentNode,
+                        },
+                    },
+                });
+            }
+            if (change.label !== undefined && change.label !== end.trait.label) {
+                return Result.error({
+                    status: EditStatus.Invalid,
+                    failure: {
+                        kind: FailureKind.ConstraintViolation,
+                        constraint: change,
+                        violation: {
+                            kind: ConstraintViolationKind.BadLabel,
+                            actual: end.trait.label,
+                        },
+                    },
+                });
+            }
+            return Result.ok(state.view);
+        }
+        applySetValue(state, change) {
+            if (!state.view.hasNode(change.nodeToModify)) {
+                return Result.error({
+                    status: EditStatus.Invalid,
+                    failure: { kind: FailureKind.UnknownId, change, id: change.nodeToModify },
+                });
+            }
+            const newView = state.view.setNodeValue(change.nodeToModify, change.payload);
+            return Result.ok(newView);
+        }
+        /**
+         * Generates tree view nodes from the supplied edit nodes.
+         * Invokes onCreateNode for each new node, and halts creation early if it returns true.
+         * Invokes onInvalidDetachedId and halts early for any invalid detached IDs referenced in the edit node sequence.
+         * @returns all the top-level node IDs in `sequence` (both from nodes and from detached sequences).
+         */
+        createViewNodesForTree(sequence, onCreateNode, onInvalidDetachedId) {
+            const topLevelIds = [];
+            const unprocessed = [];
+            for (const buildNode of sequence) {
+                if (isDetachedSequenceId(buildNode)) {
+                    const detachedIds = this.getDetachedNodeIds(buildNode, onInvalidDetachedId);
+                    if (detachedIds === undefined) {
+                        return undefined;
+                    }
+                    topLevelIds.push(...detachedIds);
+                }
+                else {
+                    unprocessed.push(buildNode);
+                    topLevelIds.push(buildNode.identifier);
+                }
+            }
+            while (unprocessed.length > 0) {
+                const node = unprocessed.pop();
+                assert(node !== undefined && !isDetachedSequenceId(node));
+                const traits = new Map();
+                // eslint-disable-next-line no-restricted-syntax
+                for (const key in node.traits) {
+                    if (Object.prototype.hasOwnProperty.call(node.traits, key)) {
+                        const children = node.traits[key];
+                        if (children.length > 0) {
+                            const childIds = [];
+                            for (const child of children) {
+                                if (isDetachedSequenceId(child)) {
+                                    const detachedIds = this.getDetachedNodeIds(child, onInvalidDetachedId);
+                                    if (detachedIds === undefined) {
+                                        return undefined;
+                                    }
+                                    childIds.push(...detachedIds);
+                                }
+                                else {
+                                    childIds.push(child.identifier);
+                                    unprocessed.push(child);
+                                }
+                            }
+                            traits.set(key, childIds);
+                        }
+                    }
+                }
+                const newNode = {
+                    identifier: node.identifier,
+                    definition: node.definition,
+                    traits,
+                };
+                copyPropertyIfDefined(node, newNode, 'payload');
+                if (onCreateNode(node.identifier, newNode)) {
+                    return undefined;
+                }
+            }
+            return topLevelIds;
+        }
+        getDetachedNodeIds(detachedId, onInvalidDetachedId) {
+            // Retrieve the detached sequence from the void.
+            const detachedNodeIds = this.detached.get(detachedId);
+            if (detachedNodeIds === undefined) {
+                onInvalidDetachedId(detachedId);
+                return undefined;
+            }
+            // Since we have retrieved the sequence, remove it from the void to prevent a second tree from multi-parenting it later
+            this.detached.delete(detachedId);
+            return detachedNodeIds;
+        }
+    }
+    TransactionInternal.Policy = Policy;
+    /**
+     * The kinds of failures that a transaction might encounter.
+     */
+    let FailureKind;
+    (function (FailureKind) {
+        /**
+         * Transaction has an unused DetachedSequenceId
+         */
+        FailureKind["UnusedDetachedSequence"] = "UnusedDetachedSequence";
+        /**
+         * Transaction has a build operation using an already in use DetachedSequenceID.
+         */
+        FailureKind["DetachedSequenceIdAlreadyInUse"] = "DetachedSequenceIdAlreadyInUse";
+        /**
+         * Transaction tries to operate on an unknown DetachedSequenceID
+         */
+        FailureKind["DetachedSequenceNotFound"] = "DetachedSequenceNotFound";
+        /**
+         * Transaction has a build which uses a duplicated NodeId
+         */
+        FailureKind["DuplicateIdInBuild"] = "DuplicateIdInBuild";
+        /**
+         * Transaction tries to build a node using an ID which is already used in the current state
+         */
+        FailureKind["IdAlreadyInUse"] = "IdAlreadyInUse";
+        /**
+         * Transaction tries to set value of an unknown node
+         */
+        FailureKind["UnknownId"] = "UnknownId";
+        /**
+         * Transaction tries to insert in an invalid Place
+         */
+        FailureKind["BadPlace"] = "BadPlace";
+        /**
+         * Transaction tries to detach an invalid Range
+         */
+        FailureKind["BadRange"] = "BadRange";
+        /**
+         * Transaction has an invalid constraint
+         */
+        FailureKind["ConstraintViolation"] = "ConstraintViolation";
+    })(FailureKind = TransactionInternal.FailureKind || (TransactionInternal.FailureKind = {}));
+    /**
+     * Enum of possible kinds of constraint violations that can be encountered
+     */
+    let ConstraintViolationKind;
+    (function (ConstraintViolationKind) {
+        /**
+         * The constraint failed because it applies to an invalid range
+         */
+        ConstraintViolationKind["BadRange"] = "BadRange";
+        /**
+         * The constraint failed because the length prescribed by the constraint does not match the length of range being constrained
+         */
+        ConstraintViolationKind["BadLength"] = "BadLength";
+        /**
+         * The constraint failed because the parent prescribed by the constraint does not match the actual parent of the range being constrained
+         */
+        ConstraintViolationKind["BadParent"] = "BadParent";
+        /**
+         * The constraint failed because the trait label prescribed by the constraint does not match the actual trait label of the range being constrained
+         */
+        ConstraintViolationKind["BadLabel"] = "BadLabel";
+    })(ConstraintViolationKind = TransactionInternal.ConstraintViolationKind || (TransactionInternal.ConstraintViolationKind = {}));
+})(TransactionInternal || (TransactionInternal = {}));
+//# sourceMappingURL=TransactionInternal.js.map