@fluid-experimental/tree 0.58.2002 → 0.59.1000

package/lib/EditUtilities.js

@@ -0,0 +1,353 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { v4 as uuidv4 } from 'uuid';
+import { compareArrays, copyPropertyIfDefined, fail } from './Common';
+import { ChangeInternal, StableRangeInternal, } from './persisted-types';
+import { Change, StableRange } from './ChangeTypes';
+import { placeFromStablePlace, rangeFromStableRange } from './TreeViewUtilities';
+import { iterateChildren } from './RevisionView';
+import { getChangeNode_0_0_2FromView } from './SerializationUtilities';
+import { comparePayloads } from './PayloadUtilities';
+/**
+ * Functions for constructing and comparing Edits.
+ */
+/**
+ * Returns true if the provided Edits have equivalent properties.
+ */
+export function compareEdits(editIdA, editIdB) {
+    // TODO #45414: We should also be deep comparing the list of changes in the edit. This is not straightforward.
+    // We can use our edit validation code when we write it since it will need to do deep walks of the changes.
+    return editIdA === editIdB;
+}
+/**
+ * Generates a new edit object from the supplied changes.
+ */
+export function newEdit(changes) {
+    return { id: newEditId(), changes };
+}
+/**
+ * Generates a new edit object from the supplied changes.
+ */
+export function newEditId() {
+    return uuidv4();
+}
+/**
+ * Transform an input tree into an isomorphic output tree
+ * @param tree - the input tree
+ * @param convert - a conversion function that will run on each (non-placeholder) node in the input tree to produce the output tree.
+ * Returning undefined means that conversion for the given node was impossible, at which time the entire tree conversion will be aborted
+ * and return undefined.
+ * @param isPlaceholder - a predicate which determines if the given node is of type TPlaceholder
+ */
+export function convertTreeNodes(root, convert, isPlaceholder) {
+    var _a;
+    if (isKnownType(root, isPlaceholder)) {
+        return root;
+    }
+    const convertedRoot = convert(root);
+    // `convertedRoot` might be the same as `root`, in which case stash the children of `root` before wiping them from `convertedRoot`
+    const rootTraits = root === convertedRoot ? { traits: root.traits } : root;
+    convertedRoot.traits = {};
+    const pendingNodes = [{ childIterator: iterateChildren(rootTraits)[Symbol.iterator](), newNode: convertedRoot }];
+    while (pendingNodes.length > 0) {
+        const { childIterator, newNode } = (_a = pendingNodes[pendingNodes.length - 1]) !== null && _a !== void 0 ? _a : fail('Undefined node');
+        const { value, done } = childIterator.next();
+        if (done === true) {
+            pendingNodes.pop();
+        }
+        else {
+            const [traitLabel, child] = value;
+            let convertedChild;
+            if (!isKnownType(child, isPlaceholder)) {
+                convertedChild = convert(child);
+                if (child.traits !== undefined) {
+                    const childTraits = child === convertedChild ? { traits: child.traits } : child;
+                    pendingNodes.push({
+                        childIterator: iterateChildren(childTraits)[Symbol.iterator](),
+                        newNode: convertedChild,
+                    });
+                }
+                convertedChild.traits = {};
+            }
+            else {
+                convertedChild = child;
+            }
+            const newTraits = newNode.traits;
+            let newTrait = newTraits[traitLabel];
+            if (newTrait === undefined) {
+                newTrait = [];
+                newTraits[traitLabel] = newTrait;
+            }
+            newTrait.push(convertedChild);
+        }
+    }
+    return convertedRoot;
+}
+export function walkTree(tree, visitors, isPlaceholder) {
+    var _a;
+    const nodeVisitor = typeof visitors === 'function' ? visitors : visitors.nodeVisitor;
+    const placeholderVisitor = typeof visitors === 'object' ? visitors.placeholderVisitor : undefined;
+    if (isKnownType(tree, isPlaceholder)) {
+        placeholderVisitor === null || placeholderVisitor === void 0 ? void 0 : placeholderVisitor(tree);
+        return;
+    }
+    nodeVisitor === null || nodeVisitor === void 0 ? void 0 : nodeVisitor(tree);
+    const childIterators = [iterateChildren(tree)[Symbol.iterator]()];
+    while (childIterators.length > 0) {
+        const childIterator = (_a = childIterators[childIterators.length - 1]) !== null && _a !== void 0 ? _a : fail('Undefined node');
+        const { value, done } = childIterator.next();
+        if (done === true) {
+            childIterators.pop();
+        }
+        else {
+            const [_, child] = value;
+            if (isKnownType(child, isPlaceholder)) {
+                placeholderVisitor === null || placeholderVisitor === void 0 ? void 0 : placeholderVisitor(child);
+            }
+            else {
+                nodeVisitor === null || nodeVisitor === void 0 ? void 0 : nodeVisitor(child);
+                childIterators.push(iterateChildren(child)[Symbol.iterator]());
+            }
+        }
+    }
+}
+// Useful for collapsing type checks in `convertTreeNodes` into a single line
+function isKnownType(value, isType) {
+    var _a;
+    return (_a = isType === null || isType === void 0 ? void 0 : isType(value)) !== null && _a !== void 0 ? _a : false;
+}
+/**
+ * Check if two trees are equivalent, meaning they have the same descendants with the same properties.
+ *
+ * See {@link comparePayloads} for payload comparison semantics.
+ */
+export function deepCompareNodes(a, b, comparator = compareNodes) {
+    if (a === b) {
+        return true;
+    }
+    if (!comparator(a, b)) {
+        return false;
+    }
+    const traitsA = Object.entries(a.traits);
+    const traitsB = Object.entries(b.traits);
+    if (traitsA.length !== traitsB.length) {
+        return false;
+    }
+    for (const [traitLabel, childrenA] of traitsA) {
+        const childrenB = b.traits[traitLabel];
+        if (childrenA.length !== childrenB.length) {
+            return false;
+        }
+        const traitsEqual = compareArrays(childrenA, childrenB, (childA, childB) => {
+            if (typeof childA === 'number' || typeof childB === 'number') {
+                // Check if children are DetachedSequenceIds
+                return childA === childB;
+            }
+            return deepCompareNodes(childA, childB);
+        });
+        if (!traitsEqual) {
+            return false;
+        }
+    }
+    return true;
+}
+/*
+ * Returns true if two nodes have equivalent data and payloads, otherwise false.
+ * Does not compare children
+ * @param nodes - two or more nodes to compare
+ */
+export function compareNodes(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (a.identifier !== b.identifier) {
+        return false;
+    }
+    if (a.definition !== b.definition) {
+        return false;
+    }
+    if (!comparePayloads(a.payload, b.payload)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Compare two views such that semantically equivalent node IDs are considered equal.
+ */
+export function areRevisionViewsSemanticallyEqual(treeViewA, idConverterA, treeViewB, idConverterB) {
+    const treeA = getChangeNode_0_0_2FromView(treeViewA, idConverterA);
+    const treeB = getChangeNode_0_0_2FromView(treeViewB, idConverterB);
+    if (!deepCompareNodes(treeA, treeB)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Create a sequence of changes that resets the contents of `trait`.
+ * @public
+ */
+export function setTrait(trait, nodes) {
+    const id = 0;
+    const traitContents = StableRange.all(trait);
+    return [Change.detach(traitContents), Change.build(nodes, id), Change.insert(id, traitContents.start)];
+}
+/**
+ * Create a sequence of changes that resets the contents of `trait`.
+ * @internal
+ */
+export function setTraitInternal(trait, nodes) {
+    const id = 0;
+    const traitContents = StableRangeInternal.all(trait);
+    return [
+        ChangeInternal.detach(traitContents),
+        ChangeInternal.build(nodes, id),
+        ChangeInternal.insert(id, traitContents.start),
+    ];
+}
+/**
+ * Check the validity of the given `StablePlace`
+ * @param view - the `TreeView` within which to validate the given place
+ * @param place - the `StablePlace` to check
+ */
+export function validateStablePlace(view, place) {
+    /* A StablePlace is valid if the following conditions are met:
+     *     1. A sibling or trait is defined.
+     *     2. If a sibling is defined, both it and its parent exist in the `TreeView`.
+     *     3. If a trait is defined, its parent node exists in the `TreeView`.
+     *     4. If a sibling and a trait location are both specified, the sibling needs to actually be in that trait.
+     */
+    const { referenceSibling, referenceTrait } = place;
+    // A well-formed `StablePlace` specifies exactly one of `referenceSibling` and `referenceTrait`.
+    if ((referenceSibling === undefined && referenceTrait === undefined) ||
+        (referenceSibling !== undefined && referenceTrait !== undefined)) {
+        return { result: PlaceValidationResult.Malformed };
+    }
+    if (referenceSibling !== undefined) {
+        if (!view.hasNode(referenceSibling)) {
+            return { result: PlaceValidationResult.MissingSibling };
+        }
+        // Detached nodes and the root are invalid anchors.
+        if (view.tryGetTraitLabel(referenceSibling) === undefined) {
+            return { result: PlaceValidationResult.SiblingIsRootOrDetached };
+        }
+        return { result: PlaceValidationResult.Valid, side: place.side, referenceSibling };
+    }
+    if (referenceTrait === undefined) {
+        return { result: PlaceValidationResult.MissingParent };
+    }
+    if (!view.hasNode(referenceTrait.parent)) {
+        return { result: PlaceValidationResult.MissingParent };
+    }
+    return { result: PlaceValidationResult.Valid, side: place.side, referenceTrait };
+}
+/**
+ * The result of validating a place.
+ */
+export var PlaceValidationResult;
+(function (PlaceValidationResult) {
+    PlaceValidationResult["Valid"] = "Valid";
+    PlaceValidationResult["Malformed"] = "Malformed";
+    PlaceValidationResult["SiblingIsRootOrDetached"] = "SiblingIsRootOrDetached";
+    PlaceValidationResult["MissingSibling"] = "MissingSibling";
+    PlaceValidationResult["MissingParent"] = "MissingParent";
+})(PlaceValidationResult || (PlaceValidationResult = {}));
+/**
+ * Check the validity of the given `StableRange`
+ * @param view - the `TreeView` within which to validate the given range
+ * @param range - the `StableRange` to check
+ */
+export function validateStableRange(view, range) {
+    /* A StableRange is valid if the following conditions are met:
+     *     1. Its start and end places are valid.
+     *     2. Its start and end places are within the same trait.
+     *     3. Its start place is before its end place.
+     */
+    const { start, end } = range;
+    const validatedStart = validateStablePlace(view, start);
+    if (validatedStart.result !== PlaceValidationResult.Valid) {
+        return {
+            result: { kind: RangeValidationResultKind.BadPlace, place: start, placeFailure: validatedStart.result },
+        };
+    }
+    const validatedEnd = validateStablePlace(view, end);
+    if (validatedEnd.result !== PlaceValidationResult.Valid) {
+        return { result: { kind: RangeValidationResultKind.BadPlace, place: end, placeFailure: validatedEnd.result } };
+    }
+    const startTraitLocation = validatedStart.referenceTrait || view.getTraitLocation(validatedStart.referenceSibling);
+    const endTraitLocation = validatedEnd.referenceTrait || view.getTraitLocation(validatedEnd.referenceSibling);
+    if (!compareTraits(startTraitLocation, endTraitLocation)) {
+        return { result: RangeValidationResultKind.PlacesInDifferentTraits };
+    }
+    const { start: startPlace, end: endPlace } = rangeFromStableRange(view, {
+        start: validatedStart,
+        end: validatedEnd,
+    });
+    const startIndex = view.findIndexWithinTrait(startPlace);
+    const endIndex = view.findIndexWithinTrait(endPlace);
+    if (startIndex > endIndex) {
+        return { result: RangeValidationResultKind.Inverted };
+    }
+    return { result: RangeValidationResultKind.Valid, start: validatedStart, end: validatedEnd };
+}
+/**
+ * The kinds of result of validating a range.
+ */
+export var RangeValidationResultKind;
+(function (RangeValidationResultKind) {
+    RangeValidationResultKind["Valid"] = "Valid";
+    RangeValidationResultKind["BadPlace"] = "BadPlace";
+    RangeValidationResultKind["PlacesInDifferentTraits"] = "PlacesInDifferentTraits";
+    RangeValidationResultKind["Inverted"] = "Inverted";
+})(RangeValidationResultKind || (RangeValidationResultKind = {}));
+/**
+ * Check if two TraitLocations are equal.
+ */
+function compareTraits(traitA, traitB) {
+    if (traitA.label !== traitB.label || traitA.parent !== traitB.parent) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Parents a set of nodes in a specified location within a trait.
+ * @param nodesToInsert - the nodes to parent in the specified place. The nodes must already be present in the TreeView.
+ * @param placeToInsert - the location to insert the nodes.
+ */
+export function insertIntoTrait(view, nodesToInsert, placeToInsert) {
+    return view.attachRange(nodesToInsert, placeFromStablePlace(view, placeToInsert));
+}
+/**
+ * Detaches a range of nodes from their parent. The detached nodes remain in the TreeView.
+ * @param rangeToDetach - the range of nodes to detach
+ */
+export function detachRange(view, rangeToDetach) {
+    return view.detachRange(rangeFromStableRange(view, rangeToDetach));
+}
+/**
+ * Deeply clone the given StablePlace
+ */
+export function deepCloneStablePlace(place) {
+    const clone = { side: place.side };
+    copyPropertyIfDefined(place, clone, 'referenceSibling');
+    copyPropertyIfDefined(place, clone, 'referenceTrait');
+    return clone;
+}
+/**
+ * Deeply clone the given StableRange
+ */
+export function deepCloneStableRange(range) {
+    return { start: deepCloneStablePlace(range.start), end: deepCloneStablePlace(range.end) };
+}
+/** Convert a node used in a Build change into its internal representation */
+export function internalizeBuildNode(nodeData, nodeIdContext) {
+    var _a;
+    const output = {
+        definition: nodeData.definition,
+        identifier: (_a = nodeData.identifier) !== null && _a !== void 0 ? _a : nodeIdContext.generateNodeId(),
+    };
+    copyPropertyIfDefined(nodeData, output, 'payload');
+    return output;
+}
+//# sourceMappingURL=EditUtilities.js.map

package/lib/EditUtilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EditUtilities.js","sourceRoot":"","sources":["../src/EditUtilities.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 */\n\nimport { v4 as uuidv4 } from 'uuid';\nimport { compareArrays, copyPropertyIfDefined, fail, Mutable } from './Common';\nimport { Definition, DetachedSequenceId, EditId, NodeId, StableNodeId, TraitLabel } from './Identifiers';\nimport { NodeIdContext, NodeIdConverter } from './NodeIdUtilities';\nimport {\n\tBuildNodeInternal,\n\tChangeInternal,\n\tChangeNode,\n\tChangeNode_0_0_2,\n\tEdit,\n\tHasTraits,\n\tNodeData,\n\tSide,\n\tStablePlaceInternal,\n\tStableRangeInternal,\n\tTraitLocationInternal,\n\tTraitMap,\n\tTreeNode,\n\tTreeNodeSequence,\n} from './persisted-types';\nimport { TraitLocation, TreeView } from './TreeView';\nimport { BuildNode, BuildTreeNode, Change, HasVariadicTraits, StablePlace, StableRange } from './ChangeTypes';\nimport { placeFromStablePlace, rangeFromStableRange } from './TreeViewUtilities';\nimport { iterateChildren, TransactionView } from './RevisionView';\nimport { getChangeNode_0_0_2FromView } from './SerializationUtilities';\nimport { comparePayloads } from './PayloadUtilities';\n\n/**\n * Functions for constructing and comparing Edits.\n */\n\n/**\n * Returns true if the provided Edits have equivalent properties.\n */\nexport function compareEdits(editIdA: EditId, editIdB: EditId): boolean {\n\t// TODO #45414: We should also be deep comparing the list of changes in the edit. This is not straightforward.\n\t// We can use our edit validation code when we write it since it will need to do deep walks of the changes.\n\treturn editIdA === editIdB;\n}\n\n/**\n * Generates a new edit object from the supplied changes.\n */\nexport function newEdit<TEdit>(changes: readonly TEdit[]): Edit<TEdit> {\n\treturn { id: newEditId(), changes };\n}\n\n/**\n * Generates a new edit object from the supplied changes.\n */\nexport function newEditId(): EditId {\n\treturn uuidv4() as EditId;\n}\n\n/**\n * A node type that does not require its children to be specified\n */\nexport type NoTraits<TChild extends HasVariadicTraits<unknown>> = Omit<TChild, keyof HasVariadicTraits<TChild>>;\n\n/**\n * Transform an input tree into an isomorphic output tree\n * @param tree - the input tree\n * @param convert - a conversion function that will run on each node in the input tree to produce the output tree.\n */\nexport function convertTreeNodes<TIn extends HasVariadicTraits<TIn>, TOut extends HasTraits<TOut>>(\n\troot: TIn,\n\tconvert: (node: TIn) => NoTraits<TOut>\n): TOut;\n\n/**\n * Transform an input tree into an isomorphic output tree\n * @param tree - the input tree\n * @param convert - a conversion function that will run on each (non-placeholder) node in the input tree to produce the output tree.\n * @param isPlaceholder - a predicate which determines if a node is a placeholder\n */\nexport function convertTreeNodes<\n\tTIn extends HasVariadicTraits<TIn | TPlaceholder>,\n\tTOut extends HasTraits<TOut | TPlaceholder>,\n\tTPlaceholder\n>(\n\troot: TIn | TPlaceholder,\n\tconvert: (node: TIn) => NoTraits<TOut>,\n\tisPlaceholder: (node: TIn | TPlaceholder) => node is TPlaceholder\n): TOut | TPlaceholder;\n\n/**\n * Transform an input tree into an isomorphic output tree\n * @param tree - the input tree\n * @param convert - a conversion function that will run on each (non-placeholder) node in the input tree to produce the output tree.\n * Returning undefined means that conversion for the given node was impossible, at which time the entire tree conversion will be aborted\n * and return undefined.\n * @param isPlaceholder - a predicate which determines if the given node is of type TPlaceholder\n */\nexport function convertTreeNodes<\n\tTIn extends HasVariadicTraits<TIn | TPlaceholder>,\n\tTOut extends HasTraits<TOut | TPlaceholder>,\n\tTPlaceholder\n>(\n\troot: TIn | TPlaceholder,\n\tconvert: (node: TIn) => NoTraits<TOut>,\n\tisPlaceholder?: (node: TIn | TPlaceholder) => node is TPlaceholder\n): TOut | TPlaceholder {\n\tif (isKnownType(root, isPlaceholder)) {\n\t\treturn root;\n\t}\n\n\tconst convertedRoot = convert(root) as TOut;\n\t// `convertedRoot` might be the same as `root`, in which case stash the children of `root` before wiping them from `convertedRoot`\n\tconst rootTraits = (root as unknown as TOut) === convertedRoot ? { traits: root.traits } : root;\n\t(convertedRoot as Mutable<TOut>).traits = {};\n\tconst pendingNodes: {\n\t\tchildIterator: Iterator<[TraitLabel, TIn | TPlaceholder]>;\n\t\tnewNode: Mutable<TOut>;\n\t}[] = [{ childIterator: iterateChildren(rootTraits)[Symbol.iterator](), newNode: convertedRoot }];\n\n\twhile (pendingNodes.length > 0) {\n\t\tconst { childIterator, newNode } = pendingNodes[pendingNodes.length - 1] ?? fail('Undefined node');\n\t\tconst { value, done } = childIterator.next();\n\t\tif (done === true) {\n\t\t\tpendingNodes.pop();\n\t\t} else {\n\t\t\tconst [traitLabel, child] = value as [TraitLabel, TIn | TPlaceholder];\n\t\t\tlet convertedChild: TOut | TPlaceholder;\n\t\t\tif (!isKnownType(child, isPlaceholder)) {\n\t\t\t\tconvertedChild = convert(child) as TOut;\n\t\t\t\tif (child.traits !== undefined) {\n\t\t\t\t\tconst childTraits =\n\t\t\t\t\t\t(child as unknown as TOut) === convertedChild ? { traits: child.traits } : child;\n\t\t\t\t\tpendingNodes.push({\n\t\t\t\t\t\tchildIterator: iterateChildren(childTraits)[Symbol.iterator](),\n\t\t\t\t\t\tnewNode: convertedChild,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\t(convertedChild as Mutable<TOut>).traits = {};\n\t\t\t} else {\n\t\t\t\tconvertedChild = child;\n\t\t\t}\n\t\t\tconst newTraits = newNode.traits as Mutable<TraitMap<TOut | TPlaceholder>>;\n\t\t\tlet newTrait = newTraits[traitLabel];\n\t\t\tif (newTrait === undefined) {\n\t\t\t\tnewTrait = [];\n\t\t\t\tnewTraits[traitLabel] = newTrait;\n\t\t\t}\n\t\t\t(newTrait as (TOut | TPlaceholder)[]).push(convertedChild);\n\t\t}\n\t}\n\n\treturn convertedRoot;\n}\n\n/**\n * Visits an input tree in a depth-first pre-order traversal.\n * @param tree - the input tree\n * @param visitor - callback invoked for each node in the tree.\n */\nexport function walkTree<TIn extends HasVariadicTraits<TIn>>(tree: TIn, visitor: (node: TIn) => void): void;\n\n/**\n * Visits an input tree containing placeholders in a depth-first pre-order traversal.\n * @param tree - the input tree\n * @param visitor - callback invoked for each node in the tree. Must return true if the given node is a TPlaceholder.\n */\nexport function walkTree<TIn extends HasVariadicTraits<TIn | TPlaceholder>, TPlaceholder = never>(\n\ttree: TIn | TPlaceholder,\n\tvisitors:\n\t\t| ((node: TIn) => void)\n\t\t| { nodeVisitor?: (node: TIn) => void; placeholderVisitor?: (placeholder: TPlaceholder) => void },\n\tisPlaceholder: (node: TIn | TPlaceholder) => node is TPlaceholder\n): void;\n\nexport function walkTree<TIn extends HasVariadicTraits<TIn | TPlaceholder>, TPlaceholder = never>(\n\ttree: TIn | TPlaceholder,\n\tvisitors:\n\t\t| ((node: TIn) => void)\n\t\t| { nodeVisitor?: (node: TIn) => void; placeholderVisitor?: (placeholder: TPlaceholder) => void },\n\tisPlaceholder?: (node: TIn | TPlaceholder) => node is TPlaceholder\n): void {\n\tconst nodeVisitor = typeof visitors === 'function' ? visitors : visitors.nodeVisitor;\n\tconst placeholderVisitor = typeof visitors === 'object' ? visitors.placeholderVisitor : undefined;\n\tif (isKnownType(tree, isPlaceholder)) {\n\t\tplaceholderVisitor?.(tree);\n\t\treturn;\n\t}\n\tnodeVisitor?.(tree);\n\n\tconst childIterators: Iterator<[TraitLabel, TIn | TPlaceholder]>[] = [iterateChildren(tree)[Symbol.iterator]()];\n\n\twhile (childIterators.length > 0) {\n\t\tconst childIterator = childIterators[childIterators.length - 1] ?? fail('Undefined node');\n\t\tconst { value, done } = childIterator.next();\n\t\tif (done === true) {\n\t\t\tchildIterators.pop();\n\t\t} else {\n\t\t\tconst [_, child] = value as [TraitLabel, TIn | TPlaceholder];\n\t\t\tif (isKnownType(child, isPlaceholder)) {\n\t\t\t\tplaceholderVisitor?.(child);\n\t\t\t} else {\n\t\t\t\tnodeVisitor?.(child);\n\t\t\t\tchildIterators.push(iterateChildren(child)[Symbol.iterator]());\n\t\t\t}\n\t\t}\n\t}\n}\n\n// Useful for collapsing type checks in `convertTreeNodes` into a single line\nfunction isKnownType<T, Type extends T>(value: T, isType?: (value: T) => value is Type): value is Type {\n\treturn isType?.(value) ?? false;\n}\n\n/**\n * Check if two trees are equivalent, meaning they have the same descendants with the same properties.\n *\n * See {@link comparePayloads} for payload comparison semantics.\n */\nexport function deepCompareNodes(\n\ta: ChangeNode | ChangeNode_0_0_2,\n\tb: ChangeNode | ChangeNode_0_0_2,\n\tcomparator: (\n\t\ta: NodeData<NodeId> | NodeData<StableNodeId>,\n\t\tb: NodeData<NodeId> | NodeData<StableNodeId>\n\t) => boolean = compareNodes\n): boolean {\n\tif (a === b) {\n\t\treturn true;\n\t}\n\n\tif (!comparator(a, b)) {\n\t\treturn false;\n\t}\n\n\tconst traitsA = Object.entries(a.traits);\n\tconst traitsB = Object.entries(b.traits);\n\n\tif (traitsA.length !== traitsB.length) {\n\t\treturn false;\n\t}\n\n\tfor (const [traitLabel, childrenA] of traitsA) {\n\t\tconst childrenB = b.traits[traitLabel];\n\n\t\tif (childrenA.length !== childrenB.length) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst traitsEqual = compareArrays<ChangeNode | ChangeNode_0_0_2>(childrenA, childrenB, (childA, childB) => {\n\t\t\tif (typeof childA === 'number' || typeof childB === 'number') {\n\t\t\t\t// Check if children are DetachedSequenceIds\n\t\t\t\treturn childA === childB;\n\t\t\t}\n\n\t\t\treturn deepCompareNodes(childA, childB);\n\t\t});\n\n\t\tif (!traitsEqual) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\treturn true;\n}\n\n/*\n * Returns true if two nodes have equivalent data and payloads, otherwise false.\n * Does not compare children\n * @param nodes - two or more nodes to compare\n */\nexport function compareNodes(\n\ta: NodeData<NodeId> | NodeData<StableNodeId>,\n\tb: NodeData<NodeId> | NodeData<StableNodeId>\n): boolean {\n\tif (a === b) {\n\t\treturn true;\n\t}\n\n\tif (a.identifier !== b.identifier) {\n\t\treturn false;\n\t}\n\n\tif (a.definition !== b.definition) {\n\t\treturn false;\n\t}\n\n\tif (!comparePayloads(a.payload, b.payload)) {\n\t\treturn false;\n\t}\n\n\treturn true;\n}\n\n/**\n * Compare two views such that semantically equivalent node IDs are considered equal.\n */\nexport function areRevisionViewsSemanticallyEqual(\n\ttreeViewA: TreeView,\n\tidConverterA: NodeIdConverter,\n\ttreeViewB: TreeView,\n\tidConverterB: NodeIdConverter\n): boolean {\n\tconst treeA = getChangeNode_0_0_2FromView(treeViewA, idConverterA);\n\tconst treeB = getChangeNode_0_0_2FromView(treeViewB, idConverterB);\n\tif (!deepCompareNodes(treeA, treeB)) {\n\t\treturn false;\n\t}\n\n\treturn true;\n}\n\n/**\n * Create a sequence of changes that resets the contents of `trait`.\n * @public\n */\nexport function setTrait(trait: TraitLocation, nodes: BuildNode | TreeNodeSequence<BuildNode>): Change[] {\n\tconst id = 0 as DetachedSequenceId;\n\tconst traitContents = StableRange.all(trait);\n\treturn [Change.detach(traitContents), Change.build(nodes, id), Change.insert(id, traitContents.start)];\n}\n\n/**\n * Create a sequence of changes that resets the contents of `trait`.\n * @internal\n */\nexport function setTraitInternal(\n\ttrait: TraitLocationInternal,\n\tnodes: TreeNodeSequence<BuildNodeInternal>\n): ChangeInternal[] {\n\tconst id = 0 as DetachedSequenceId;\n\tconst traitContents = StableRangeInternal.all(trait);\n\treturn [\n\t\tChangeInternal.detach(traitContents),\n\t\tChangeInternal.build(nodes, id),\n\t\tChangeInternal.insert(id, traitContents.start),\n\t];\n}\n\n/**\n * Check the validity of the given `StablePlace`\n * @param view - the `TreeView` within which to validate the given place\n * @param place - the `StablePlace` to check\n */\nexport function validateStablePlace(\n\tview: TreeView,\n\tplace: StablePlaceInternal\n):\n\t| {\n\t\t\tresult: PlaceValidationResult.Valid;\n\t\t\tside: Side;\n\t\t\treferenceSibling: NodeId;\n\t\t\treferenceTrait?: never;\n\t  }\n\t| {\n\t\t\tresult: PlaceValidationResult.Valid;\n\t\t\tside: Side;\n\t\t\treferenceSibling?: never;\n\t\t\treferenceTrait: TraitLocation;\n\t  }\n\t| { result: Exclude<PlaceValidationResult, PlaceValidationResult.Valid> } {\n\t/* A StablePlace is valid if the following conditions are met:\n\t *     1. A sibling or trait is defined.\n\t *     2. If a sibling is defined, both it and its parent exist in the `TreeView`.\n\t *     3. If a trait is defined, its parent node exists in the `TreeView`.\n\t *     4. If a sibling and a trait location are both specified, the sibling needs to actually be in that trait.\n\t */\n\tconst { referenceSibling, referenceTrait } = place;\n\n\t// A well-formed `StablePlace` specifies exactly one of `referenceSibling` and `referenceTrait`.\n\tif (\n\t\t(referenceSibling === undefined && referenceTrait === undefined) ||\n\t\t(referenceSibling !== undefined && referenceTrait !== undefined)\n\t) {\n\t\treturn { result: PlaceValidationResult.Malformed };\n\t}\n\n\tif (referenceSibling !== undefined) {\n\t\tif (!view.hasNode(referenceSibling)) {\n\t\t\treturn { result: PlaceValidationResult.MissingSibling };\n\t\t}\n\n\t\t// Detached nodes and the root are invalid anchors.\n\t\tif (view.tryGetTraitLabel(referenceSibling) === undefined) {\n\t\t\treturn { result: PlaceValidationResult.SiblingIsRootOrDetached };\n\t\t}\n\n\t\treturn { result: PlaceValidationResult.Valid, side: place.side, referenceSibling };\n\t}\n\n\tif (referenceTrait === undefined) {\n\t\treturn { result: PlaceValidationResult.MissingParent };\n\t}\n\n\tif (!view.hasNode(referenceTrait.parent)) {\n\t\treturn { result: PlaceValidationResult.MissingParent };\n\t}\n\n\treturn { result: PlaceValidationResult.Valid, side: place.side, referenceTrait };\n}\n\n/**\n * The result of validating a place.\n */\nexport enum PlaceValidationResult {\n\tValid = 'Valid',\n\tMalformed = 'Malformed',\n\tSiblingIsRootOrDetached = 'SiblingIsRootOrDetached',\n\tMissingSibling = 'MissingSibling',\n\tMissingParent = 'MissingParent',\n}\n\n/**\n * The result of validating a bad place.\n */\nexport type BadPlaceValidationResult = Exclude<PlaceValidationResult, PlaceValidationResult.Valid>;\n\n/**\n * Check the validity of the given `StableRange`\n * @param view - the `TreeView` within which to validate the given range\n * @param range - the `StableRange` to check\n */\nexport function validateStableRange(\n\tview: TreeView,\n\trange: StableRangeInternal\n):\n\t| { result: RangeValidationResultKind.Valid; start: StablePlaceInternal; end: StablePlaceInternal }\n\t| { result: Exclude<RangeValidationResult, RangeValidationResultKind.Valid> } {\n\t/* A StableRange is valid if the following conditions are met:\n\t *     1. Its start and end places are valid.\n\t *     2. Its start and end places are within the same trait.\n\t *     3. Its start place is before its end place.\n\t */\n\tconst { start, end } = range;\n\n\tconst validatedStart = validateStablePlace(view, start);\n\tif (validatedStart.result !== PlaceValidationResult.Valid) {\n\t\treturn {\n\t\t\tresult: { kind: RangeValidationResultKind.BadPlace, place: start, placeFailure: validatedStart.result },\n\t\t};\n\t}\n\n\tconst validatedEnd = validateStablePlace(view, end);\n\tif (validatedEnd.result !== PlaceValidationResult.Valid) {\n\t\treturn { result: { kind: RangeValidationResultKind.BadPlace, place: end, placeFailure: validatedEnd.result } };\n\t}\n\n\tconst startTraitLocation = validatedStart.referenceTrait || view.getTraitLocation(validatedStart.referenceSibling);\n\tconst endTraitLocation = validatedEnd.referenceTrait || view.getTraitLocation(validatedEnd.referenceSibling);\n\tif (!compareTraits(startTraitLocation, endTraitLocation)) {\n\t\treturn { result: RangeValidationResultKind.PlacesInDifferentTraits };\n\t}\n\n\tconst { start: startPlace, end: endPlace } = rangeFromStableRange(view, {\n\t\tstart: validatedStart,\n\t\tend: validatedEnd,\n\t});\n\tconst startIndex = view.findIndexWithinTrait(startPlace);\n\tconst endIndex = view.findIndexWithinTrait(endPlace);\n\n\tif (startIndex > endIndex) {\n\t\treturn { result: RangeValidationResultKind.Inverted };\n\t}\n\n\treturn { result: RangeValidationResultKind.Valid, start: validatedStart, end: validatedEnd };\n}\n\n/**\n * The kinds of result of validating a range.\n */\nexport enum RangeValidationResultKind {\n\tValid = 'Valid',\n\tBadPlace = 'BadPlace',\n\tPlacesInDifferentTraits = 'PlacesInDifferentTraits',\n\tInverted = 'Inverted',\n}\n\n/**\n * The result of validating a range.\n */\nexport type RangeValidationResult =\n\t| RangeValidationResultKind.Valid\n\t| RangeValidationResultKind.PlacesInDifferentTraits\n\t| RangeValidationResultKind.Inverted\n\t| {\n\t\t\tkind: RangeValidationResultKind.BadPlace;\n\t\t\tplace: StablePlaceInternal;\n\t\t\tplaceFailure: BadPlaceValidationResult;\n\t  };\n\n/**\n * The result of validating a bad range.\n */\nexport type BadRangeValidationResult = Exclude<RangeValidationResult, RangeValidationResultKind.Valid>;\n\n/**\n * Check if two TraitLocations are equal.\n */\nfunction compareTraits(traitA: TraitLocation, traitB: TraitLocation): boolean {\n\tif (traitA.label !== traitB.label || traitA.parent !== traitB.parent) {\n\t\treturn false;\n\t}\n\n\treturn true;\n}\n\n/**\n * Parents a set of nodes in a specified location within a trait.\n * @param nodesToInsert - the nodes to parent in the specified place. The nodes must already be present in the TreeView.\n * @param placeToInsert - the location to insert the nodes.\n */\nexport function insertIntoTrait(\n\tview: TransactionView,\n\tnodesToInsert: readonly NodeId[],\n\tplaceToInsert: StablePlace\n): TransactionView {\n\treturn view.attachRange(nodesToInsert, placeFromStablePlace(view, placeToInsert));\n}\n\n/**\n * Detaches a range of nodes from their parent. The detached nodes remain in the TreeView.\n * @param rangeToDetach - the range of nodes to detach\n */\nexport function detachRange(\n\tview: TransactionView,\n\trangeToDetach: StableRange\n): { view: TransactionView; detached: readonly NodeId[] } {\n\treturn view.detachRange(rangeFromStableRange(view, rangeToDetach));\n}\n\n/**\n * Deeply clone the given StablePlace\n */\nexport function deepCloneStablePlace(place: StablePlace): StablePlace {\n\tconst clone: StablePlace = { side: place.side };\n\tcopyPropertyIfDefined(place, clone, 'referenceSibling');\n\tcopyPropertyIfDefined(place, clone, 'referenceTrait');\n\treturn clone;\n}\n\n/**\n * Deeply clone the given StableRange\n */\nexport function deepCloneStableRange(range: StableRange): StableRange {\n\treturn { start: deepCloneStablePlace(range.start), end: deepCloneStablePlace(range.end) };\n}\n\n/** Convert a node used in a Build change into its internal representation */\nexport function internalizeBuildNode(\n\tnodeData: BuildTreeNode,\n\tnodeIdContext: NodeIdContext\n): Omit<TreeNode<BuildNodeInternal, NodeId>, 'traits'> {\n\tconst output = {\n\t\tdefinition: nodeData.definition as Definition,\n\t\tidentifier: nodeData.identifier ?? nodeIdContext.generateNodeId(),\n\t};\n\tcopyPropertyIfDefined(nodeData, output, 'payload');\n\treturn output;\n}\n"]}

package/lib/EventTypes.d.ts

@@ -0,0 +1,73 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * An event emitted by a `SharedTree` to indicate a state change. See {@link ISharedTreeEvents} for event argument information.
+ * @public
+ */
+export declare enum SharedTreeEvent {
+    /**
+     * An edit has been committed to the log.
+     * This happens when either:
+     * 	1. A locally generated edit is added to the log.
+     * 	2. A remotely generated edit is added to the log.
+     * Note that, for locally generated edits, this event will not be emitted again when that edit is sequenced.
+     * Passed the EditId of the committed edit, i.e. supports callbacks of type {@link EditCommittedHandler}.
+     */
+    EditCommitted = "committedEdit",
+    /**
+     * A sequenced edit has been applied.
+     * This includes local edits though the callback is only invoked once the sequenced version is received.
+     * For edits that were local (see {@link SequencedEditAppliedEventArguments.wasLocal}, this callback will only be called once.
+     * For non-local edits, it may be called multiple times: the number of calls and when they occur depends on caching and is an
+     * implementation detail.
+     * Supports callbacks of type {@link SequencedEditAppliedHandler}.
+     */
+    SequencedEditApplied = "sequencedEditApplied"
+}
+/**
+ * An event emitted by a `SharedTree` for diagnostic purposes.
+ * See {@link ISharedTreeEvents} for event argument information.
+ */
+export declare enum SharedTreeDiagnosticEvent {
+    /**
+     * A single catch up blob has been uploaded.
+     */
+    CatchUpBlobUploaded = "uploadedCatchUpBlob",
+    /**
+     * An edit chunk blob has been uploaded. This includes catchup blobs.
+     */
+    EditChunkUploaded = "uploadedEditChunk",
+    /**
+     * A valid edit (local or remote) has been applied.
+     * Passed the EditId of the applied edit.
+     * Note that this may be called multiple times, due to concurrent edits causing reordering,
+     * and/or due to not caching the output of every edit.
+     */
+    AppliedEdit = "appliedEdit",
+    /**
+     * An invalid edit (local or remote) has been dropped.
+     * Passed the EditId of the dropped edit.
+     * Note that this may be called multiple times, due to concurrent edits causing reordering,
+     * and/or due to not caching the output of every edit.
+     */
+    DroppedInvalidEdit = "droppedInvalidEdit",
+    /**
+     * A malformed edit (local or remote) has been dropped.
+     * Passed the EditId of the dropped edit.
+     * Note that this may be called multiple times, due to concurrent edits causing reordering,
+     * and/or due to not caching the output of every edit.
+     */
+    DroppedMalformedEdit = "droppedMalformedEdit",
+    /**
+     * A history chunk has been received that does not have a corresponding edit chunk on the edit log.
+     */
+    UnexpectedHistoryChunk = "unexpectedHistoryChunk",
+    /**
+     * The current write format changed, either because an old summary was loaded or an update op was successfully processed.
+     * This event is emitted with the new version as an argument.
+     */
+    WriteVersionChanged = "writeVersionChanged"
+}
+//# sourceMappingURL=EventTypes.d.ts.map

package/lib/EventTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventTypes.d.ts","sourceRoot":"","sources":["../src/EventTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,oBAAY,eAAe;IAC1B;;;;;;;OAOG;IACH,aAAa,kBAAkB;IAC/B;;;;;;;OAOG;IACH,oBAAoB,yBAAyB;CAC7C;AAED;;;GAGG;AACH,oBAAY,yBAAyB;IACpC;;OAEG;IACH,mBAAmB,wBAAwB;IAC3C;;OAEG;IACH,iBAAiB,sBAAsB;IACvC;;;;;OAKG;IACH,WAAW,gBAAgB;IAC3B;;;;;OAKG;IACH,kBAAkB,uBAAuB;IACzC;;;;;OAKG;IACH,oBAAoB,yBAAyB;IAC7C;;OAEG;IACH,sBAAsB,2BAA2B;IACjD;;;OAGG;IACH,mBAAmB,wBAAwB;CAC3C"}

package/lib/EventTypes.js

@@ -0,0 +1,75 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * An event emitted by a `SharedTree` to indicate a state change. See {@link ISharedTreeEvents} for event argument information.
+ * @public
+ */
+export var SharedTreeEvent;
+(function (SharedTreeEvent) {
+    /**
+     * An edit has been committed to the log.
+     * This happens when either:
+     * 	1. A locally generated edit is added to the log.
+     * 	2. A remotely generated edit is added to the log.
+     * Note that, for locally generated edits, this event will not be emitted again when that edit is sequenced.
+     * Passed the EditId of the committed edit, i.e. supports callbacks of type {@link EditCommittedHandler}.
+     */
+    SharedTreeEvent["EditCommitted"] = "committedEdit";
+    /**
+     * A sequenced edit has been applied.
+     * This includes local edits though the callback is only invoked once the sequenced version is received.
+     * For edits that were local (see {@link SequencedEditAppliedEventArguments.wasLocal}, this callback will only be called once.
+     * For non-local edits, it may be called multiple times: the number of calls and when they occur depends on caching and is an
+     * implementation detail.
+     * Supports callbacks of type {@link SequencedEditAppliedHandler}.
+     */
+    SharedTreeEvent["SequencedEditApplied"] = "sequencedEditApplied";
+})(SharedTreeEvent || (SharedTreeEvent = {}));
+/**
+ * An event emitted by a `SharedTree` for diagnostic purposes.
+ * See {@link ISharedTreeEvents} for event argument information.
+ */
+export var SharedTreeDiagnosticEvent;
+(function (SharedTreeDiagnosticEvent) {
+    /**
+     * A single catch up blob has been uploaded.
+     */
+    SharedTreeDiagnosticEvent["CatchUpBlobUploaded"] = "uploadedCatchUpBlob";
+    /**
+     * An edit chunk blob has been uploaded. This includes catchup blobs.
+     */
+    SharedTreeDiagnosticEvent["EditChunkUploaded"] = "uploadedEditChunk";
+    /**
+     * A valid edit (local or remote) has been applied.
+     * Passed the EditId of the applied edit.
+     * Note that this may be called multiple times, due to concurrent edits causing reordering,
+     * and/or due to not caching the output of every edit.
+     */
+    SharedTreeDiagnosticEvent["AppliedEdit"] = "appliedEdit";
+    /**
+     * An invalid edit (local or remote) has been dropped.
+     * Passed the EditId of the dropped edit.
+     * Note that this may be called multiple times, due to concurrent edits causing reordering,
+     * and/or due to not caching the output of every edit.
+     */
+    SharedTreeDiagnosticEvent["DroppedInvalidEdit"] = "droppedInvalidEdit";
+    /**
+     * A malformed edit (local or remote) has been dropped.
+     * Passed the EditId of the dropped edit.
+     * Note that this may be called multiple times, due to concurrent edits causing reordering,
+     * and/or due to not caching the output of every edit.
+     */
+    SharedTreeDiagnosticEvent["DroppedMalformedEdit"] = "droppedMalformedEdit";
+    /**
+     * A history chunk has been received that does not have a corresponding edit chunk on the edit log.
+     */
+    SharedTreeDiagnosticEvent["UnexpectedHistoryChunk"] = "unexpectedHistoryChunk";
+    /**
+     * The current write format changed, either because an old summary was loaded or an update op was successfully processed.
+     * This event is emitted with the new version as an argument.
+     */
+    SharedTreeDiagnosticEvent["WriteVersionChanged"] = "writeVersionChanged";
+})(SharedTreeDiagnosticEvent || (SharedTreeDiagnosticEvent = {}));
+//# sourceMappingURL=EventTypes.js.map

package/lib/EventTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventTypes.js","sourceRoot":"","sources":["../src/EventTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAN,IAAY,eAmBX;AAnBD,WAAY,eAAe;IAC1B;;;;;;;OAOG;IACH,kDAA+B,CAAA;IAC/B;;;;;;;OAOG;IACH,gEAA6C,CAAA;AAC9C,CAAC,EAnBW,eAAe,KAAf,eAAe,QAmB1B;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,yBAuCX;AAvCD,WAAY,yBAAyB;IACpC;;OAEG;IACH,wEAA2C,CAAA;IAC3C;;OAEG;IACH,oEAAuC,CAAA;IACvC;;;;;OAKG;IACH,wDAA2B,CAAA;IAC3B;;;;;OAKG;IACH,sEAAyC,CAAA;IACzC;;;;;OAKG;IACH,0EAA6C,CAAA;IAC7C;;OAEG;IACH,8EAAiD,CAAA;IACjD;;;OAGG;IACH,wEAA2C,CAAA;AAC5C,CAAC,EAvCW,yBAAyB,KAAzB,yBAAyB,QAuCpC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * An event emitted by a `SharedTree` to indicate a state change. See {@link ISharedTreeEvents} for event argument information.\n * @public\n */\nexport enum SharedTreeEvent {\n\t/**\n\t * An edit has been committed to the log.\n\t * This happens when either:\n\t * \t1. A locally generated edit is added to the log.\n\t * \t2. A remotely generated edit is added to the log.\n\t * Note that, for locally generated edits, this event will not be emitted again when that edit is sequenced.\n\t * Passed the EditId of the committed edit, i.e. supports callbacks of type {@link EditCommittedHandler}.\n\t */\n\tEditCommitted = 'committedEdit',\n\t/**\n\t * A sequenced edit has been applied.\n\t * This includes local edits though the callback is only invoked once the sequenced version is received.\n\t * For edits that were local (see {@link SequencedEditAppliedEventArguments.wasLocal}, this callback will only be called once.\n\t * For non-local edits, it may be called multiple times: the number of calls and when they occur depends on caching and is an\n\t * implementation detail.\n\t * Supports callbacks of type {@link SequencedEditAppliedHandler}.\n\t */\n\tSequencedEditApplied = 'sequencedEditApplied',\n}\n\n/**\n * An event emitted by a `SharedTree` for diagnostic purposes.\n * See {@link ISharedTreeEvents} for event argument information.\n */\nexport enum SharedTreeDiagnosticEvent {\n\t/**\n\t * A single catch up blob has been uploaded.\n\t */\n\tCatchUpBlobUploaded = 'uploadedCatchUpBlob',\n\t/**\n\t * An edit chunk blob has been uploaded. This includes catchup blobs.\n\t */\n\tEditChunkUploaded = 'uploadedEditChunk',\n\t/**\n\t * A valid edit (local or remote) has been applied.\n\t * Passed the EditId of the applied edit.\n\t * Note that this may be called multiple times, due to concurrent edits causing reordering,\n\t * and/or due to not caching the output of every edit.\n\t */\n\tAppliedEdit = 'appliedEdit',\n\t/**\n\t * An invalid edit (local or remote) has been dropped.\n\t * Passed the EditId of the dropped edit.\n\t * Note that this may be called multiple times, due to concurrent edits causing reordering,\n\t * and/or due to not caching the output of every edit.\n\t */\n\tDroppedInvalidEdit = 'droppedInvalidEdit',\n\t/**\n\t * A malformed edit (local or remote) has been dropped.\n\t * Passed the EditId of the dropped edit.\n\t * Note that this may be called multiple times, due to concurrent edits causing reordering,\n\t * and/or due to not caching the output of every edit.\n\t */\n\tDroppedMalformedEdit = 'droppedMalformedEdit',\n\t/**\n\t * A history chunk has been received that does not have a corresponding edit chunk on the edit log.\n\t */\n\tUnexpectedHistoryChunk = 'unexpectedHistoryChunk',\n\t/**\n\t * The current write format changed, either because an old summary was loaded or an update op was successfully processed.\n\t * This event is emitted with the new version as an argument.\n\t */\n\tWriteVersionChanged = 'writeVersionChanged',\n}\n"]}

package/lib/Forest.d.ts

@@ -2,16 +2,33 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { NodeData, Payload } from './generic';
 import { NodeId, TraitLabel } from './Identifiers';
+import { NodeData, Payload } from './persisted-types';
 /**
- * A node that can be contained within a Forest.
+ * A node that can be contained within a Forest
+ *
+ * @public
  */
-export interface ForestNode extends NodeData {
+export interface ForestNode extends NodeData<NodeId> {
     readonly traits: ReadonlyMap<TraitLabel, readonly NodeId[]>;
 }
+/**
+ * A node within a Forest that has a parent (and is therefore not the root node)
+ *
+ * @public
+ */
+export interface ParentedForestNode extends ForestNode, ParentData {
+}
+/**
+ * Check whether or not the given node in a forest is parented
+ *
+ * @public
+ */
+export declare function isParentedForestNode(node: ForestNode): node is ParentedForestNode;
 /**
  * Information about a ForestNode's parent
+ *
+ * @public
  */
 export interface ParentData {
     readonly parentId: NodeId;
@@ -37,6 +54,8 @@ export interface Delta<NodeId> {
 /**
  * An immutable forest of ForestNode.
  * Enforces single parenting, and allows querying the parent.
+ *
+ * @public
  */
 export declare class Forest {
     /**
@@ -66,9 +85,9 @@ export declare class Forest {
      */
     get size(): number;
     /**
-     * Adds the supplied nodes to the forest. The IDs must be unique in the forest.
+     * Adds the supplied nodes to the forest. The nodes' IDs must be unique in the forest.
      * @param nodes - the sequence of nodes to add to the forest. If any of them have children which exist in the forest already, those
-     * children will be parented. Any trait arrays present in a node must be non-empty.
+     * children will be parented. Any trait arrays present in a node must be non-empty. The nodes may be provided in any order.
      */
     add(nodes: Iterable<ForestNode>): Forest;
     /**
@@ -97,6 +116,10 @@ export declare class Forest {
      * @param value - the new value
      */
     setValue(nodeId: NodeId, value: Payload | null): Forest;
+    /**
+     * @returns true if the node associated with `id` exists in this forest, otherwise false
+     */
+    has(id: NodeId): boolean;
     /**
      * @returns the node associated with `id`. Should not be used if there is no node with the provided id.
      */
@@ -125,7 +148,6 @@ export declare class Forest {
      * @returns undefined iff root, otherwise the parent of `id`.
      */
     tryGetParent(id: NodeId): ParentData | undefined;
-    private static breakOnDifference;
     /**
      * Compares two forests for equality.
      * @param forest - the other forest to compare to this one
@@ -142,7 +164,7 @@ export declare class Forest {
     delta(forest: Forest): Delta<NodeId>;
 }
 /**
- * @returns true iff two `SnapshotNodes` are equivalent.
+ * @returns true iff two `ForestNodes` are equivalent.
  * May return false for nodes they contain equivalent payloads encoded differently.
  */
 export declare function compareForestNodes(nodeA: ForestNode, nodeB: ForestNode): boolean;