@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/core/tree/sparseTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparseTree.js","sourceRoot":"","sources":["../../../src/core/tree/sparseTree.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 { assert } from \"@fluidframework/core-utils\";\nimport { FieldKey } from \"../schema-stored\";\nimport { topDownPath, UpPath } from \"./pathTree\";\n\n/**\n * Sparse Tree of nodes.\n *\n * Contains both child and parent pointers, which are kept in sync.\n *\n * Each node is equivalent to a path through the tree.\n * This tree structure stores a collection of these paths, but deduplicating the common prefixes of the tree\n * prefix-tree style.\n */\nexport class SparseNode<TData> implements UpPath {\n\t/**\n\t * SparseNode arrays are kept sorted the SparseNode's parentIndex for efficient search.\n\t * Users of this field must take care to maintain invariants (correct parent pointers, not empty child arrays etc.)\n\t *\n\t * Performance Note:\n\t * Large child lists could be updated more efficiently here using a data-structure optimized\n\t * for efficient prefix sum updates, such as a Fenwick tree or Finger tree.\n\t * This would be complicated by the need for parent pointers (including indexes),\n\t * but is possible to do.\n\t */\n\tpublic readonly children: Map<FieldKey, SparseNode<TData>[]> = new Map();\n\n\tpublic constructor(\n\t\tpublic parentField: FieldKey,\n\t\tpublic parentIndex: number,\n\t\t/**\n\t\t * The parent of this `SparseNode` (an up pointer in the `SparseNode` tree).\n\t\t * If the status of this node is `Alive`, then there must be a corresponding down pointer from the\n\t\t * `parentPath` node to this node.\n\t\t * When undefined, this node is the root and thus has no parent.\n\t\t *\n\t\t * When updating the tree, it is valid to transiently leave the up and down pointers inconsistent\n\t\t * (updating down pointers first), but they must be consistent when the update is completed.\n\t\t */\n\t\tpublic parentPath: SparseNode<TData> | undefined,\n\t\tpublic data: TData,\n\t) {}\n\n\t/**\n\t * @returns true iff this SparseNode is the special root node that sits above all the detached fields.\n\t * In this case, the fields are detached sequences.\n\t * Note that the special root node should never appear in an UpPath\n\t * since UpPaths represent this root as `undefined`.\n\t */\n\tprivate isRoot(): boolean {\n\t\treturn this.parentPath === undefined;\n\t}\n\n\tpublic get parent(): SparseNode<TData> | undefined {\n\t\tassert(\n\t\t\tthis.parentPath !== undefined,\n\t\t\t0x4a4 /* SparseNode.parent is an UpPath API and thus should never be called on the root SparseNode. */,\n\t\t);\n\t\t// Root SparseNode corresponds to the undefined root for UpPath API.\n\t\tif (this.parentPath.isRoot()) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn this.parentPath;\n\t}\n\n\t/**\n\t * Gets a child, adding a ref to it.\n\t * Creates child (with 1 ref) if needed.\n\t */\n\tpublic getOrCreateChild(key: FieldKey, index: number, data: () => TData): SparseNode<TData> {\n\t\tlet field = this.children.get(key);\n\t\tif (field === undefined) {\n\t\t\tfield = [];\n\t\t\tthis.children.set(key, field);\n\t\t}\n\t\t// TODO: should do more optimized search (ex: binary search).\n\t\tlet child = field.find((c) => c.parentIndex === index);\n\t\tif (child === undefined) {\n\t\t\tchild = new SparseNode(key, index, this, data());\n\t\t\tfield.push(child);\n\t\t\t// Keep list sorted by index.\n\t\t\tfield.sort((a, b) => a.parentIndex - b.parentIndex);\n\t\t}\n\t\treturn child;\n\t}\n\n\t/**\n\t * Gets a child if it exists.\n\t * Does NOT add a ref.\n\t */\n\tpublic tryGetChild(key: FieldKey, index: number): SparseNode<TData> | undefined {\n\t\tconst field = this.children.get(key);\n\t\tif (field === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\t\t// TODO: should do more optimized search (ex: binary search or better) using index.\n\t\treturn field.find((c) => c.parentIndex === index);\n\t}\n\n\t/**\n\t * Removes reference from this to `child`.\n\t * Since PathNodes are doubly linked,\n\t * the caller must ensure that the reference from child to parent is also removed (or the child is no longer used).\n\t */\n\tpublic removeChild(child: SparseNode<TData>): void {\n\t\tconst key = child.parentField;\n\t\tconst field = this.children.get(key);\n\t\t// TODO: should do more optimized search (ex: binary search or better) using child.parentIndex()\n\t\t// Note that this is the index in the list of child paths, not the index within the field\n\t\tconst childIndex = field?.indexOf(child) ?? -1;\n\t\tassert(childIndex !== -1, 0x4a5 /* child must be parented to be removed */);\n\t\tfield?.splice(childIndex, 1);\n\t\tif (field?.length === 0) {\n\t\t\tthis.afterEmptyField(key);\n\t\t}\n\t}\n\n\t/**\n\t * Call this after directly editing the child array for a field to be empty.\n\t * Handles cleaning up unneeded data\n\t * (like the field in the map, and possibly this entire SparseNode and its parents if they are no longer needed.)\n\t */\n\tpublic afterEmptyField(key: FieldKey): void {\n\t\tthis.children.delete(key);\n\t\tif (this.children.size === 0) {\n\t\t\tthis.disposeThis();\n\t\t}\n\t}\n\n\t/**\n\t * Removes this from parent if alive, and sets this to disposed.\n\t * Must only be called when this node is no longer needed (has no references and no children).\n\t *\n\t * Allowed when dangling (but not when disposed).\n\t */\n\tprivate disposeThis(): void {\n\t\tthis.parentPath?.removeChild(this);\n\t}\n}\n\nexport function getDescendant<TData>(\n\tancestor: SparseNode<TData>,\n\tpath: UpPath | undefined,\n): SparseNode<TData> {\n\tconst topDown = topDownPath(path);\n\tlet curr = ancestor;\n\tfor (const hop of topDown) {\n\t\tconst field = curr.children.get(hop.parentField);\n\t\tassert(field !== undefined, 0x4a6 /* Field not present in sparse node */);\n\t\t// TODO: should do more optimized search (ex: binary search).\n\t\tconst child = field.find((c) => c.parentIndex === hop.parentIndex);\n\t\tassert(child !== undefined, 0x4a7 /* Child not present in sparse node field */);\n\t\tcurr = child;\n\t}\n\treturn curr;\n}\n"]}

package/dist/core/tree/treeTextFormat.d.ts

@@ -0,0 +1,94 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { FieldKey } from "../schema-stored";
+import { NodeData } from "./types";
+/**
+ * This modules provides a simple human readable (and editable) tree format.
+ *
+ * This implementation can handle all trees (so it does not need a fallback for any special cases),
+ * and is not optimized.
+ *
+ * It's suitable for testing and debugging,
+ * though it could also reasonably be used as a fallback for edge cases or for small trees.
+ *
+ * The serialized format is valid utf-8, and also includes a json compatible intermediate in memory format.
+ *
+ * This format is currently not stable: its internal contents are not considered public APIs and may change.
+ * There is currently no guarantee that data serialized with this library will
+ * be loadable with a different version of this library.
+ *
+ * TODO: stabilize this format (probably after schema are more stable).
+ *
+ * This format does not include schema: typically schema would be stored alongside data in this format.
+ *
+ * @privateRemarks A forked version of these types is available at `persistedTreeTextFormat.ts`.
+ * Changes to them might necessitate changes to the analogous forked types, or codecs which transcode between
+ * them.
+ * See persistedTreeTextFormat's module documentation for more details.
+ */
+/**
+ * Json compatible map as object.
+ * Keys are FieldKey strings.
+ * Values are the content of the field specified by the key.
+ *
+ * WARNING:
+ * Be very careful when using objects as maps:
+ * Use `Object.prototype.hasOwnProperty.call(fieldMap, key)` to safely check for keys.
+ * Do NOT simply read the field and check for undefined as this will return values for `__proto__`
+ * and various methods on Object.prototype, like `hasOwnProperty` and `toString`.
+ * This exposes numerous bug possibilities, including prototype pollution.
+ *
+ * Due to the above issue, try to avoid this type (and the whole object as map pattern).
+ * Only use this type when needed for json compatible maps,
+ * but even in those cases consider lists of key value pairs for serialization and using `Map`
+ * for runtime.
+ *
+ * @internal
+ */
+export interface FieldMapObject<TChild> {
+    [key: string]: TChild[];
+}
+/**
+ * Json comparable tree node, generic over child type.
+ * Json compatibility assumes `TChild` is also json compatible.
+ * @internal
+ */
+export interface GenericTreeNode<TChild> extends GenericFieldsNode<TChild>, NodeData {
+}
+/**
+ * Json comparable field collection, generic over child type.
+ * Json compatibility assumes `TChild` is also json compatible.
+ * @internal
+ */
+export interface GenericFieldsNode<TChild> {
+    fields?: FieldMapObject<TChild>;
+}
+/**
+ * A tree represented using plain JavaScript objects.
+ * Can be passed to `JSON.stringify()` to produce a human-readable/editable JSON tree.
+ *
+ * JsonableTrees should not store empty fields.
+ * @internal
+ */
+export interface JsonableTree extends GenericTreeNode<JsonableTree> {
+}
+/**
+ * Get a field from `node`, optionally modifying the tree to create it if missing.
+ */
+export declare function getGenericTreeField<T>(node: GenericFieldsNode<T>, key: FieldKey, createIfMissing: boolean): T[];
+/**
+ * Sets a field on `node`.
+ */
+export declare function setGenericTreeField<T>(node: GenericFieldsNode<T>, key: FieldKey, content: T[]): void;
+/**
+ * @returns keys for fields of `tree`.
+ */
+export declare function genericTreeKeys<T>(tree: GenericFieldsNode<T>): readonly FieldKey[];
+/**
+ * Delete a field if empty.
+ * Optionally delete FieldMapObject if empty as well.
+ */
+export declare function genericTreeDeleteIfEmpty<T>(node: GenericFieldsNode<T>, key: FieldKey, removeMapObject: boolean): void;
+//# sourceMappingURL=treeTextFormat.d.ts.map

package/dist/core/tree/treeTextFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeTextFormat.d.ts","sourceRoot":"","sources":["../../../src/core/tree/treeTextFormat.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,MAAM,CAAE,SAAQ,iBAAiB,CAAC,MAAM,CAAC,EAAE,QAAQ;CAAG;AAEvF;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM;IACxC,MAAM,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAa,SAAQ,eAAe,CAAC,YAAY,CAAC;CAAG;AAEtE;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACpC,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC1B,GAAG,EAAE,QAAQ,EACb,eAAe,EAAE,OAAO,GACtB,CAAC,EAAE,CAcL;AAqBD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACpC,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC1B,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,CAAC,EAAE,GACV,IAAI,CASN;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,QAAQ,EAAE,CAWlF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACzC,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC1B,GAAG,EAAE,QAAQ,EACb,eAAe,EAAE,OAAO,GACtB,IAAI,CAaN"}

package/dist/core/tree/treeTextFormat.js

@@ -0,0 +1,88 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genericTreeDeleteIfEmpty = exports.genericTreeKeys = exports.setGenericTreeField = exports.getGenericTreeField = void 0;
+/**
+ * Get a field from `node`, optionally modifying the tree to create it if missing.
+ */
+function getGenericTreeField(node, key, createIfMissing) {
+    const children = getGenericTreeFieldMap(node, createIfMissing);
+    // Do not just read field and check for undefined: see warning on FieldMapObject.
+    if (Object.prototype.hasOwnProperty.call(children, key)) {
+        return children[key];
+    }
+    // Handle missing field:
+    if (createIfMissing === false) {
+        return [];
+    }
+    const newField = [];
+    children[key] = newField;
+    return newField;
+}
+exports.getGenericTreeField = getGenericTreeField;
+/**
+ * Get a FieldMap from `node`, optionally modifying the tree to create it if missing.
+ */
+function getGenericTreeFieldMap(node, createIfMissing) {
+    let children = node.fields;
+    if (children === undefined) {
+        children = {};
+        // Handle missing fields:
+        if (createIfMissing) {
+            node.fields = children;
+        }
+    }
+    return children;
+}
+/**
+ * Sets a field on `node`.
+ */
+function setGenericTreeField(node, key, content) {
+    const children = getGenericTreeFieldMap(node, true);
+    // like `children[keyString] = content;` except safe when keyString == "__proto__".
+    Object.defineProperty(children, key, {
+        enumerable: true,
+        configurable: true,
+        writable: true,
+        value: content,
+    });
+}
+exports.setGenericTreeField = setGenericTreeField;
+/**
+ * @returns keys for fields of `tree`.
+ */
+function genericTreeKeys(tree) {
+    const fields = tree.fields;
+    // This function is used when iterating through a tree.
+    // This means that this is often called on nodes with no keys
+    // (most trees are a large portion leaf nodes).
+    // Therefore this function special cases empty fields objects as an optimization.
+    if (fields === undefined) {
+        return [];
+    }
+    return Object.keys(fields);
+}
+exports.genericTreeKeys = genericTreeKeys;
+/**
+ * Delete a field if empty.
+ * Optionally delete FieldMapObject if empty as well.
+ */
+function genericTreeDeleteIfEmpty(node, key, removeMapObject) {
+    const children = getGenericTreeFieldMap(node, false);
+    if (Object.prototype.hasOwnProperty.call(children, key)) {
+        if (children[key].length === 0) {
+            // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+            delete children[key];
+            if (removeMapObject) {
+                if (Object.keys(children).length === 0) {
+                    delete node.fields;
+                }
+            }
+        }
+    }
+}
+exports.genericTreeDeleteIfEmpty = genericTreeDeleteIfEmpty;
+//# sourceMappingURL=treeTextFormat.js.map

package/dist/core/tree/treeTextFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeTextFormat.js","sourceRoot":"","sources":["../../../src/core/tree/treeTextFormat.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AA8EH;;GAEG;AACH,SAAgB,mBAAmB,CAClC,IAA0B,EAC1B,GAAa,EACb,eAAwB;IAExB,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IAE/D,iFAAiF;IACjF,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE;QACxD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;KACrB;IACD,wBAAwB;IACxB,IAAI,eAAe,KAAK,KAAK,EAAE;QAC9B,OAAO,EAAE,CAAC;KACV;IACD,MAAM,QAAQ,GAAQ,EAAE,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;IACzB,OAAO,QAAQ,CAAC;AACjB,CAAC;AAlBD,kDAkBC;AAED;;GAEG;AACH,SAAS,sBAAsB,CAC9B,IAA0B,EAC1B,eAAwB;IAExB,IAAI,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,IAAI,QAAQ,KAAK,SAAS,EAAE;QAC3B,QAAQ,GAAG,EAAE,CAAC;QACd,yBAAyB;QACzB,IAAI,eAAe,EAAE;YACpB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;SACvB;KACD;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CAClC,IAA0B,EAC1B,GAAa,EACb,OAAY;IAEZ,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACpD,mFAAmF;IACnF,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE;QACpC,UAAU,EAAE,IAAI;QAChB,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,OAAO;KACd,CAAC,CAAC;AACJ,CAAC;AAbD,kDAaC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAI,IAA0B;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,uDAAuD;IACvD,6DAA6D;IAC7D,+CAA+C;IAC/C,iFAAiF;IACjF,IAAI,MAAM,KAAK,SAAS,EAAE;QACzB,OAAO,EAAE,CAAC;KACV;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAe,CAAC;AAC1C,CAAC;AAXD,0CAWC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CACvC,IAA0B,EAC1B,GAAa,EACb,eAAwB;IAExB,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE;QACxD,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE;YAC/B,gEAAgE;YAChE,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;YACrB,IAAI,eAAe,EAAE;gBACpB,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE;oBACvC,OAAO,IAAI,CAAC,MAAM,CAAC;iBACnB;aACD;SACD;KACD;AACF,CAAC;AAjBD,4DAiBC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { FieldKey } from \"../schema-stored\";\nimport { NodeData } from \"./types\";\n\n/**\n * This modules provides a simple human readable (and editable) tree format.\n *\n * This implementation can handle all trees (so it does not need a fallback for any special cases),\n * and is not optimized.\n *\n * It's suitable for testing and debugging,\n * though it could also reasonably be used as a fallback for edge cases or for small trees.\n *\n * The serialized format is valid utf-8, and also includes a json compatible intermediate in memory format.\n *\n * This format is currently not stable: its internal contents are not considered public APIs and may change.\n * There is currently no guarantee that data serialized with this library will\n * be loadable with a different version of this library.\n *\n * TODO: stabilize this format (probably after schema are more stable).\n *\n * This format does not include schema: typically schema would be stored alongside data in this format.\n *\n * @privateRemarks A forked version of these types is available at `persistedTreeTextFormat.ts`.\n * Changes to them might necessitate changes to the analogous forked types, or codecs which transcode between\n * them.\n * See persistedTreeTextFormat's module documentation for more details.\n */\n\n/**\n * Json compatible map as object.\n * Keys are FieldKey strings.\n * Values are the content of the field specified by the key.\n *\n * WARNING:\n * Be very careful when using objects as maps:\n * Use `Object.prototype.hasOwnProperty.call(fieldMap, key)` to safely check for keys.\n * Do NOT simply read the field and check for undefined as this will return values for `__proto__`\n * and various methods on Object.prototype, like `hasOwnProperty` and `toString`.\n * This exposes numerous bug possibilities, including prototype pollution.\n *\n * Due to the above issue, try to avoid this type (and the whole object as map pattern).\n * Only use this type when needed for json compatible maps,\n * but even in those cases consider lists of key value pairs for serialization and using `Map`\n * for runtime.\n *\n * @internal\n */\nexport interface FieldMapObject<TChild> {\n\t[key: string]: TChild[];\n}\n\n/**\n * Json comparable tree node, generic over child type.\n * Json compatibility assumes `TChild` is also json compatible.\n * @internal\n */\nexport interface GenericTreeNode<TChild> extends GenericFieldsNode<TChild>, NodeData {}\n\n/**\n * Json comparable field collection, generic over child type.\n * Json compatibility assumes `TChild` is also json compatible.\n * @internal\n */\nexport interface GenericFieldsNode<TChild> {\n\tfields?: FieldMapObject<TChild>;\n}\n\n/**\n * A tree represented using plain JavaScript objects.\n * Can be passed to `JSON.stringify()` to produce a human-readable/editable JSON tree.\n *\n * JsonableTrees should not store empty fields.\n * @internal\n */\nexport interface JsonableTree extends GenericTreeNode<JsonableTree> {}\n\n/**\n * Get a field from `node`, optionally modifying the tree to create it if missing.\n */\nexport function getGenericTreeField<T>(\n\tnode: GenericFieldsNode<T>,\n\tkey: FieldKey,\n\tcreateIfMissing: boolean,\n): T[] {\n\tconst children = getGenericTreeFieldMap(node, createIfMissing);\n\n\t// Do not just read field and check for undefined: see warning on FieldMapObject.\n\tif (Object.prototype.hasOwnProperty.call(children, key)) {\n\t\treturn children[key];\n\t}\n\t// Handle missing field:\n\tif (createIfMissing === false) {\n\t\treturn [];\n\t}\n\tconst newField: T[] = [];\n\tchildren[key] = newField;\n\treturn newField;\n}\n\n/**\n * Get a FieldMap from `node`, optionally modifying the tree to create it if missing.\n */\nfunction getGenericTreeFieldMap<T>(\n\tnode: GenericFieldsNode<T>,\n\tcreateIfMissing: boolean,\n): FieldMapObject<T> {\n\tlet children = node.fields;\n\tif (children === undefined) {\n\t\tchildren = {};\n\t\t// Handle missing fields:\n\t\tif (createIfMissing) {\n\t\t\tnode.fields = children;\n\t\t}\n\t}\n\n\treturn children;\n}\n\n/**\n * Sets a field on `node`.\n */\nexport function setGenericTreeField<T>(\n\tnode: GenericFieldsNode<T>,\n\tkey: FieldKey,\n\tcontent: T[],\n): void {\n\tconst children = getGenericTreeFieldMap(node, true);\n\t// like `children[keyString] = content;` except safe when keyString == \"__proto__\".\n\tObject.defineProperty(children, key, {\n\t\tenumerable: true,\n\t\tconfigurable: true,\n\t\twritable: true,\n\t\tvalue: content,\n\t});\n}\n\n/**\n * @returns keys for fields of `tree`.\n */\nexport function genericTreeKeys<T>(tree: GenericFieldsNode<T>): readonly FieldKey[] {\n\tconst fields = tree.fields;\n\t// This function is used when iterating through a tree.\n\t// This means that this is often called on nodes with no keys\n\t// (most trees are a large portion leaf nodes).\n\t// Therefore this function special cases empty fields objects as an optimization.\n\tif (fields === undefined) {\n\t\treturn [];\n\t}\n\n\treturn Object.keys(fields) as FieldKey[];\n}\n\n/**\n * Delete a field if empty.\n * Optionally delete FieldMapObject if empty as well.\n */\nexport function genericTreeDeleteIfEmpty<T>(\n\tnode: GenericFieldsNode<T>,\n\tkey: FieldKey,\n\tremoveMapObject: boolean,\n): void {\n\tconst children = getGenericTreeFieldMap(node, false);\n\tif (Object.prototype.hasOwnProperty.call(children, key)) {\n\t\tif (children[key].length === 0) {\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-dynamic-delete\n\t\t\tdelete children[key];\n\t\t\tif (removeMapObject) {\n\t\t\t\tif (Object.keys(children).length === 0) {\n\t\t\t\t\tdelete node.fields;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n"]}

package/dist/core/tree/types.d.ts

@@ -0,0 +1,145 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IFluidHandle } from "@fluidframework/core-interfaces";
+import { FieldKey, TreeNodeSchemaIdentifier, ValueSchema } from "../schema-stored";
+import { _InlineTrick, Brand, Opaque } from "../../util";
+/**
+ * @internal
+ */
+export type TreeType = TreeNodeSchemaIdentifier;
+/**
+ * The empty key ("") is used for unnamed relationships, such as the indexer
+ * of an explicit array node.
+ *
+ * This key is a hint that this field is the primary function of the node,
+ * and in some abstractions the APIs for this field should be inlined onto the node.
+ *
+ * TODO:
+ * This has to be a FieldKey since different nodes will have different TreeFieldStoredSchema for it.
+ * This makes it prone to collisions and suggests
+ * that this intention may be better conveyed by metadata on the ITreeSchema.
+ * @internal
+ */
+export declare const EmptyKey: FieldKey;
+/**
+ * FieldKey to use for the root of documents in places that need to refer to detached sequences or the root.
+ * TODO: if we do want to standardize on a single value for this,
+ * it likely should be namespaced or a UUID to avoid risk of collisions.
+ * @internal
+ */
+export declare const rootFieldKey: FieldKey;
+/**
+ * @internal
+ */
+export declare const rootField: DetachedField;
+/**
+ * Location of a tree relative to is parent container (which can be a tree or forest).
+ *
+ * @internal
+ */
+export interface ChildLocation {
+    readonly container: ChildCollection;
+    readonly index: number;
+}
+/**
+ * Wrapper around DetachedField that can be detected at runtime.
+ * @internal
+ */
+export interface RootField {
+    readonly key: DetachedField;
+}
+/**
+ * Identifier for a child collection, either on a node/tree or at the root of a forest.
+ * @internal
+ */
+export type ChildCollection = FieldKey | RootField;
+/**
+ * A root in the forest.
+ *
+ * The range is a "container" like a field:
+ * any additional content inserted before or after contents of this range will be included in the range.
+ * This also means that moving the content from this range elsewhere will leave this range valid, but empty.
+ *
+ * In some APIs DetachedFields are used as FieldKeys on a special implicit root node
+ * to simplify the APIs and implementation.
+ * @internal
+ */
+export interface DetachedField extends Opaque<Brand<string, "tree.DetachedField">> {
+}
+/**
+ * Some code abstracts the root as a node with detached fields as its fields.
+ * This maps detached field to field keys for thus use.
+ *
+ * @returns `field` as a {@link FieldKey} usable on a special root node serving as a parent of detached fields.
+ * @internal
+ */
+export declare function detachedFieldAsKey(field: DetachedField): FieldKey;
+/**
+ * The inverse of {@link detachedFieldAsKey}.
+ * Thus must only be used on {@link FieldKey}s which were produced via {@link detachedFieldAsKey},
+ * and with the same scope (ex: forest) as the detachedFieldAsKey was originally from.
+ * @internal
+ */
+export declare function keyAsDetachedField(key: FieldKey): DetachedField;
+/**
+ * TODO: integrate this into Schema. Decide how to persist them (need stable Id?). Maybe allow updating field kinds?.
+ * TODO: make families of changes per field kind. Build editing APIs from that.
+ * TODO: factor ChangeRebaser implementations to support adding new field kinds.
+ * @internal
+ */
+export interface FieldKind {
+    readonly name: string;
+    readonly description: string;
+    readonly minimumChildren: number;
+    readonly maximumChildren: number;
+}
+/**
+ * Value that may be stored on a leaf node.
+ * @internal
+ */
+export type TreeValue<TSchema extends ValueSchema = ValueSchema> = [
+    {
+        [ValueSchema.Number]: number;
+        [ValueSchema.String]: string;
+        [ValueSchema.Boolean]: boolean;
+        [ValueSchema.FluidHandle]: IFluidHandle;
+        [ValueSchema.Null]: null;
+    }[TSchema]
+][_InlineTrick];
+/**
+ * Value stored on a node.
+ * @internal
+ */
+export type Value = undefined | TreeValue;
+/**
+ * The fields required by a node in a tree.
+ *
+ * @privateRemarks A forked version of this type is used in `persistedTreeTextFormat.ts`.
+ * Changes to this type might necessitate changes to `EncodedNodeData` or codecs.
+ * See persistedTreeTextFormat's module documentation for more details.
+ *
+ * @internal
+ */
+export interface NodeData {
+    /**
+     * A payload of arbitrary serializable data.
+     *
+     * TODO: clarify rules for mutating this value.
+     * For now, avoid mutating the TreeValue itself.
+     * For example, if its an object, make a modified copy of the object instead of mutating it.
+     */
+    value?: TreeValue;
+    /**
+     * The meaning of this node.
+     * Provides contexts/semantics for this node and its content.
+     * Typically used to associate a node with metadata (including a schema) and source code (types, behaviors, etc).
+     */
+    readonly type: TreeNodeSchemaIdentifier;
+}
+/**
+ * Use this type to indicate that a node sits above the detached fields, and thus is not a real node and who's type should not matter.
+ */
+export declare const aboveRootPlaceholder: TreeNodeSchemaIdentifier;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/tree/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/tree/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,YAAY,EAAS,KAAK,EAAqB,MAAM,EAAE,MAAM,YAAY,CAAC;AAEnF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,wBAAwB,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAoB,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,QAAgC,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,SAAS,eAAmC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,CAAC;AAKnD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAAG;AAErF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,CAE/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW,IAAI;IAClE;QACC,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAC7B,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAC7B,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAC/B,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC;QAExC,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;KACzB,CAAC,OAAO,CAAC;CACV,CAAC,YAAY,CAAC,CAAC;AAEhB;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;CACxC;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,wBAElC,CAAC"}

package/dist/core/tree/types.js

@@ -0,0 +1,60 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aboveRootPlaceholder = exports.keyAsDetachedField = exports.detachedFieldAsKey = exports.rootField = exports.rootFieldKey = exports.EmptyKey = void 0;
+const schema_stored_1 = require("../schema-stored");
+const util_1 = require("../../util");
+/**
+ * The empty key ("") is used for unnamed relationships, such as the indexer
+ * of an explicit array node.
+ *
+ * This key is a hint that this field is the primary function of the node,
+ * and in some abstractions the APIs for this field should be inlined onto the node.
+ *
+ * TODO:
+ * This has to be a FieldKey since different nodes will have different TreeFieldStoredSchema for it.
+ * This makes it prone to collisions and suggests
+ * that this intention may be better conveyed by metadata on the ITreeSchema.
+ * @internal
+ */
+exports.EmptyKey = (0, util_1.brand)("");
+/**
+ * FieldKey to use for the root of documents in places that need to refer to detached sequences or the root.
+ * TODO: if we do want to standardize on a single value for this,
+ * it likely should be namespaced or a UUID to avoid risk of collisions.
+ * @internal
+ */
+exports.rootFieldKey = (0, util_1.brand)("rootFieldKey");
+/**
+ * @internal
+ */
+exports.rootField = keyAsDetachedField(exports.rootFieldKey);
+/**
+ * Some code abstracts the root as a node with detached fields as its fields.
+ * This maps detached field to field keys for thus use.
+ *
+ * @returns `field` as a {@link FieldKey} usable on a special root node serving as a parent of detached fields.
+ * @internal
+ */
+function detachedFieldAsKey(field) {
+    return (0, util_1.brand)((0, util_1.extractFromOpaque)(field));
+}
+exports.detachedFieldAsKey = detachedFieldAsKey;
+/**
+ * The inverse of {@link detachedFieldAsKey}.
+ * Thus must only be used on {@link FieldKey}s which were produced via {@link detachedFieldAsKey},
+ * and with the same scope (ex: forest) as the detachedFieldAsKey was originally from.
+ * @internal
+ */
+function keyAsDetachedField(key) {
+    return (0, util_1.brand)(key);
+}
+exports.keyAsDetachedField = keyAsDetachedField;
+/**
+ * Use this type to indicate that a node sits above the detached fields, and thus is not a real node and who's type should not matter.
+ */
+exports.aboveRootPlaceholder = (0, util_1.brand)("com.fluidframework.placeholder.aboveRoot");
+//# sourceMappingURL=types.js.map

package/dist/core/tree/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/tree/types.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,oDAAmF;AACnF,qCAAmF;AAOnF;;;;;;;;;;;;GAYG;AACU,QAAA,QAAQ,GAAa,IAAA,YAAK,EAAC,EAAE,CAAC,CAAC;AAE5C;;;;;GAKG;AACU,QAAA,YAAY,GAAa,IAAA,YAAK,EAAC,cAAc,CAAC,CAAC;AAE5D;;GAEG;AACU,QAAA,SAAS,GAAG,kBAAkB,CAAC,oBAAY,CAAC,CAAC;AA0C1D;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,KAAoB;IACtD,OAAO,IAAA,YAAK,EAAC,IAAA,wBAAiB,EAAC,KAAK,CAAC,CAAC,CAAC;AACxC,CAAC;AAFD,gDAEC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,GAAa;IAC/C,OAAO,IAAA,YAAK,EAAC,GAAG,CAAC,CAAC;AACnB,CAAC;AAFD,gDAEC;AA+DD;;GAEG;AACU,QAAA,oBAAoB,GAA6B,IAAA,YAAK,EAClE,0CAA0C,CAC1C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IFluidHandle } from \"@fluidframework/core-interfaces\";\nimport { FieldKey, TreeNodeSchemaIdentifier, ValueSchema } from \"../schema-stored\";\nimport { _InlineTrick, brand, Brand, extractFromOpaque, Opaque } from \"../../util\";\n\n/**\n * @internal\n */\nexport type TreeType = TreeNodeSchemaIdentifier;\n\n/**\n * The empty key (\"\") is used for unnamed relationships, such as the indexer\n * of an explicit array node.\n *\n * This key is a hint that this field is the primary function of the node,\n * and in some abstractions the APIs for this field should be inlined onto the node.\n *\n * TODO:\n * This has to be a FieldKey since different nodes will have different TreeFieldStoredSchema for it.\n * This makes it prone to collisions and suggests\n * that this intention may be better conveyed by metadata on the ITreeSchema.\n * @internal\n */\nexport const EmptyKey: FieldKey = brand(\"\");\n\n/**\n * FieldKey to use for the root of documents in places that need to refer to detached sequences or the root.\n * TODO: if we do want to standardize on a single value for this,\n * it likely should be namespaced or a UUID to avoid risk of collisions.\n * @internal\n */\nexport const rootFieldKey: FieldKey = brand(\"rootFieldKey\");\n\n/**\n * @internal\n */\nexport const rootField = keyAsDetachedField(rootFieldKey);\n\n/**\n * Location of a tree relative to is parent container (which can be a tree or forest).\n *\n * @internal\n */\nexport interface ChildLocation {\n\treadonly container: ChildCollection;\n\treadonly index: number;\n}\n\n/**\n * Wrapper around DetachedField that can be detected at runtime.\n * @internal\n */\nexport interface RootField {\n\treadonly key: DetachedField;\n}\n\n/**\n * Identifier for a child collection, either on a node/tree or at the root of a forest.\n * @internal\n */\nexport type ChildCollection = FieldKey | RootField;\n\n// TODO: its not clear how much DetachedField belongs here in tree,\n// but for now as its needed in Rebase and Forest,\n// it makes sense to have it here for reasoning about the roots of trees.\n/**\n * A root in the forest.\n *\n * The range is a \"container\" like a field:\n * any additional content inserted before or after contents of this range will be included in the range.\n * This also means that moving the content from this range elsewhere will leave this range valid, but empty.\n *\n * In some APIs DetachedFields are used as FieldKeys on a special implicit root node\n * to simplify the APIs and implementation.\n * @internal\n */\nexport interface DetachedField extends Opaque<Brand<string, \"tree.DetachedField\">> {}\n\n/**\n * Some code abstracts the root as a node with detached fields as its fields.\n * This maps detached field to field keys for thus use.\n *\n * @returns `field` as a {@link FieldKey} usable on a special root node serving as a parent of detached fields.\n * @internal\n */\nexport function detachedFieldAsKey(field: DetachedField): FieldKey {\n\treturn brand(extractFromOpaque(field));\n}\n\n/**\n * The inverse of {@link detachedFieldAsKey}.\n * Thus must only be used on {@link FieldKey}s which were produced via {@link detachedFieldAsKey},\n * and with the same scope (ex: forest) as the detachedFieldAsKey was originally from.\n * @internal\n */\nexport function keyAsDetachedField(key: FieldKey): DetachedField {\n\treturn brand(key);\n}\n\n/**\n * TODO: integrate this into Schema. Decide how to persist them (need stable Id?). Maybe allow updating field kinds?.\n * TODO: make families of changes per field kind. Build editing APIs from that.\n * TODO: factor ChangeRebaser implementations to support adding new field kinds.\n * @internal\n */\nexport interface FieldKind {\n\treadonly name: string;\n\treadonly description: string;\n\treadonly minimumChildren: number;\n\treadonly maximumChildren: number;\n}\n\n/**\n * Value that may be stored on a leaf node.\n * @internal\n */\nexport type TreeValue<TSchema extends ValueSchema = ValueSchema> = [\n\t{\n\t\t[ValueSchema.Number]: number;\n\t\t[ValueSchema.String]: string;\n\t\t[ValueSchema.Boolean]: boolean;\n\t\t[ValueSchema.FluidHandle]: IFluidHandle;\n\t\t// eslint-disable-next-line @rushstack/no-new-null\n\t\t[ValueSchema.Null]: null;\n\t}[TSchema],\n][_InlineTrick];\n\n/**\n * Value stored on a node.\n * @internal\n */\nexport type Value = undefined | TreeValue;\n\n/**\n * The fields required by a node in a tree.\n *\n * @privateRemarks A forked version of this type is used in `persistedTreeTextFormat.ts`.\n * Changes to this type might necessitate changes to `EncodedNodeData` or codecs.\n * See persistedTreeTextFormat's module documentation for more details.\n *\n * @internal\n */\nexport interface NodeData {\n\t/**\n\t * A payload of arbitrary serializable data.\n\t *\n\t * TODO: clarify rules for mutating this value.\n\t * For now, avoid mutating the TreeValue itself.\n\t * For example, if its an object, make a modified copy of the object instead of mutating it.\n\t */\n\tvalue?: TreeValue;\n\n\t/**\n\t * The meaning of this node.\n\t * Provides contexts/semantics for this node and its content.\n\t * Typically used to associate a node with metadata (including a schema) and source code (types, behaviors, etc).\n\t */\n\treadonly type: TreeNodeSchemaIdentifier;\n}\n\n/**\n * Use this type to indicate that a node sits above the detached fields, and thus is not a real node and who's type should not matter.\n */\nexport const aboveRootPlaceholder: TreeNodeSchemaIdentifier = brand(\n\t\"com.fluidframework.placeholder.aboveRoot\",\n);\n"]}

package/dist/core/tree/visitDelta.d.ts

@@ -0,0 +1,135 @@
+import { FieldKey } from "../schema-stored";
+import * as Delta from "./delta";
+import { NodeIndex, PlaceIndex, Range } from "./pathTree";
+import { DetachedFieldIndex } from "./detachedFieldIndex";
+import { ProtoNodes } from "./delta";
+/**
+ * Implementation notes:
+ *
+ * The visit is organized into four phases:
+ * 1. a detach pass
+ * 2. root transfers
+ * 3. an attach pass
+ * 4. root destructions
+ *
+ * The core idea is that before content can be attached, it must first exist and be in a detached field.
+ * The detach pass is therefore responsible for making sure that all roots that needs to be attached during the
+ * attach pass are detached.
+ * In practice, this means the detach pass must:
+ * - Create all subtrees that need to be created
+ * - Detach all moved nodes
+ *
+ * In addition to that, the detach pass also detaches nodes that need removing, with the exception of nodes that get
+ * replaced. The reason for this exception is that we need to be able to communicate replaces as atomic operations.
+ * In order to do that, we need to wait until we are sure that the content to attach is available as a detached root.
+ * Replaces are therefore handled during the attach pass.
+ * Note that this could theoretically lead to a situation where, in the attach pass, one replace wants to attach
+ * a node that has yet to be detached by another replace. This does not occur in practice because we do not support
+ * editing operations that would lead to this situation.
+ *
+ * While the detach pass ensures that nodes to be attached are in a detached state, it does not guarantee that they
+ * reside in the correct detach field. That is the responsibility of the root transfers phase.
+ *
+ * The attach phase carries out attaches and replaces.
+ *
+ * After the attach phase, roots destruction is carried out.
+ * This needs to happen last to allow modifications to detached roots to be applied before they are destroyed.
+ */
+/**
+ * Crawls the given `delta`, calling `visitor`'s callback for each change encountered.
+ * Each successive call to the visitor callbacks assumes that the change described by earlier calls have been applied
+ * to the document tree. For example, for a change that removes the first and third node of a field, the visitor calls
+ * will first call detach with a range from indices 0 to 1 then call detach with a range from indices 1 to 2.
+ *
+ * @param delta - The delta to be crawled.
+ * @param visitor - The object to notify of the changes encountered.
+ * @param detachedFieldIndex - Index responsible for keeping track of the existing detached fields.
+ */
+export declare function visitDelta(delta: Delta.Root, visitor: DeltaVisitor, detachedFieldIndex: DetachedFieldIndex): void;
+/**
+ * Visitor for changes in a delta.
+ * Must be freed after use.
+ * @internal
+ */
+export interface DeltaVisitor {
+    /**
+     * Frees/releases the visitor. Must be called once the visitor is no longer needed, since trying to acquire
+     * a new one before freeing an existing one is invalid.
+     */
+    free(): void;
+    /**
+     * Creates nodes for the given content in a new detached field.
+     * @param content - The content to create.
+     * @param destination - The key for a new detached field.
+     * A field with this key must not already exist.
+     */
+    create(content: ProtoNodes, destination: FieldKey): void;
+    /**
+     * Recursively destroys the given detached field and all of the nodes within it.
+     * @param detachedField - The key for the detached field to destroy.
+     * @param count - The number of nodes being destroyed.
+     * Expected to match the number of nodes in the detached field being destroyed.
+     */
+    destroy(detachedField: FieldKey, count: number): void;
+    /**
+     * Transfers all the nodes from a detached field to the current field.
+     * @param source - The detached field to transfer the nodes from.
+     * @param count - The number of nodes being attached.
+     * Expected to match the number of nodes in the source detached field.
+     * @param destination - The index at which to attach the nodes.
+     */
+    attach(source: FieldKey, count: number, destination: PlaceIndex): void;
+    /**
+     * Transfers a range of nodes from the current field to a new detached field.
+     * @param source - The bounds of the range of nodes to detach.
+     * @param destination - The key for a new detached field.
+     * A field with this key must not already exist.
+     */
+    detach(source: Range, destination: FieldKey): void;
+    /**
+     * Replaces a range of nodes in the current field by transferring them out to a new detached field
+     * and transferring in all the nodes from an existing detached field in their place.
+     * The number of nodes being detached must match the number of nodes being attached.
+     * @param newContentSource - The detached field to transfer the new nodes from.
+     * @param range - The bounds of the range of nodes to replace.
+     * @param oldContentDestination - The key for a new detached field to transfer the old nodes to.
+     */
+    replace(newContentSource: FieldKey, range: Range, oldContentDestination: FieldKey): void;
+    /**
+     * Tells the visitor that it should update its "current location" to be the Node at the specified index
+     * within the Field that is the current "current location".
+     * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.
+     * @param index - The index (within the Field) of the node that should become the new "current location".
+     *
+     * @remarks This should only be called when the "current location" is a Field.
+     */
+    enterNode(index: NodeIndex): void;
+    /**
+     * Tells the visitor that it should update its "current location" to be the Field which contains the Node
+     * that is the current "current location".
+     * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.
+     * @param index - The index (within its Field) of the node that is being exited.
+     *
+     * @remarks This should only be called when the "current location" is a Node.
+     */
+    exitNode(index: NodeIndex): void;
+    /**
+     * Tells the visitor that it should update its "current location" to be the Field with the specified key,
+     * within the Node that is the current "current location".
+     * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.
+     * @param key - The key of the field that should become the new "current location".
+     *
+     * @remarks This should only be called when the "current location" is a Node.
+     */
+    enterField(key: FieldKey): void;
+    /**
+     * Tells the visitor that it should update its "current location" to be the Node which contains the Field
+     * that is the current "current location".
+     * Future calls to methods of {@link DeltaVisitor} will assume that's the location where their effects are happening.
+     * @param key - The key of the field that is being exited.
+     *
+     * @remarks This should only be called when the "current location" is a Field.
+     */
+    exitField(key: FieldKey): void;
+}
+//# sourceMappingURL=visitDelta.d.ts.map

package/dist/core/tree/visitDelta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitDelta.d.ts","sourceRoot":"","sources":["../../../src/core/tree/visitDelta.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAgB,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAQxE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACzB,KAAK,EAAE,KAAK,CAAC,IAAI,EACjB,OAAO,EAAE,YAAY,EACrB,kBAAkB,EAAE,kBAAkB,GACpC,IAAI,CAqCN;AA6FD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAC;IACb;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAC;IACzD;;;;;OAKG;IACH,OAAO,CAAC,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,IAAI,CAAC;IACvE;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnD;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,qBAAqB,EAAE,QAAQ,GAAG,IAAI,CAAC;IAEzF;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAElC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAEjC;;;;;;;OAOG;IACH,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAEhC;;;;;;;OAOG;IACH,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC/B"}