@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

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

@@ -0,0 +1,156 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Brand } from "../../util";
+import { FieldKey } from "../schema-stored";
+import { DetachedField } from "./types";
+/**
+ * Identical to {@link UpPath}, but a duplicate declaration is needed to make
+ * the default type parameter compile.
+ *
+ * @internal
+ */
+export type UpPathDefault = UpPath;
+/**
+ * Path from a location in the tree upward.
+ * UpPaths can be used with deduplicated upper parts to allow
+ * working with paths localized to part of the tree without incurring
+ * costs related to the depth of the local subtree.
+ *
+ * UpPaths can be thought of as terminating at a special root node (that is `undefined`)
+ * whose FieldKeys correspond to detached sequences.
+ *
+ * UpPaths can be mutated over time and should be considered to be invalidated when any edits occurs:
+ * Use of an UpPath that was acquired before the most recent edit is undefined behavior.
+ * @internal
+ */
+export interface UpPath<TParent = UpPathDefault> {
+    /**
+     * The parent, or undefined in the case where this path is a member of a detached sequence.
+     */
+    readonly parent: TParent | undefined;
+    /**
+     * The Field under which this path points.
+     * Note that if `parent` returns `undefined`, this key corresponds to a detached sequence.
+     */
+    readonly parentField: FieldKey;
+    /**
+     * The index within `parentField` this path is pointing to.
+     */
+    readonly parentIndex: NodeIndex;
+}
+/**
+ * Path from a field in the tree upward.
+ *
+ * See {@link UpPath}.
+ * @internal
+ */
+export interface FieldUpPath<TUpPath extends UpPath = UpPath> {
+    /**
+     * The parent, or undefined in the case where this path is to a detached sequence.
+     */
+    readonly parent: TUpPath | undefined;
+    /**
+     * The Field to which this path points.
+     * Note that if `parent` returns `undefined`, this key  corresponds to a detached sequence.
+     */
+    readonly field: FieldKey;
+}
+/**
+ * A range of nodes in a detached field.
+ * Unlike RangeUpPath, such ranges are generated by create and detach operations,
+ * as well as consumed by destroy and attach operations.
+ * @internal
+ */
+export type DetachedRangeUpPath = Brand<Omit<RangeUpPath, "parent">, "DetachedRangeUpPath">;
+/**
+ * Delimits the extend of a range.
+ * @internal
+ */
+export interface Range {
+    /**
+     * The location before the first node.
+     * Must be less than or equal to `end`.
+     */
+    readonly start: PlaceIndex;
+    /**
+     * The location after the last node.
+     * Must be greater than or equal to `start`.
+     */
+    readonly end: PlaceIndex;
+}
+/**
+ * A possibly empty range of nodes in a field.
+ * This object only characterizes the location of the range, it does not own/contain the nodes in the range.
+ * @internal
+ */
+export interface RangeUpPath<TUpPath extends UpPath = UpPath> extends FieldUpPath<TUpPath>, Range {
+}
+/**
+ * A place in a field.
+ * @internal
+ */
+export interface PlaceUpPath<TUpPath extends UpPath = UpPath> extends FieldUpPath<TUpPath> {
+    /**
+     * The location in the field.
+     */
+    readonly index: PlaceIndex;
+}
+/**
+ * A place in a detached field.
+ * @internal
+ */
+export type DetachedPlaceUpPath = Brand<Omit<PlaceUpPath, "parent">, "DetachedRangeUpPath">;
+/**
+ * Indicates the index of a node in a field.
+ * Zero indicates the first node in a field.
+ * @internal
+ */
+export type NodeIndex = number;
+/**
+ * Indicates a place between nodes in a field or at the extremity of a field.
+ * Zero indicates the place at the start of the field (before the first node if any).
+ * @internal
+ */
+export type PlaceIndex = number;
+/**
+ * @returns the number of nodes above this one.
+ * Zero when the path's parent is undefined, meaning the path represents a node in a detached field.
+ * Runs in O(depth) time.
+ */
+export declare function getDepth(path: UpPath): number;
+/**
+ * @returns a deep copy of the provided path as simple javascript objects.
+ * This is safe to hold onto and use deep object comparisons on.
+ */
+export declare function clonePath(path: UpPath): UpPath;
+/**
+ * @returns a deep copy of the provided path as simple javascript objects.
+ * This is safe to hold onto and use deep object comparisons on.
+ */
+export declare function clonePath(path: UpPath | undefined): UpPath | undefined;
+/**
+ * @returns The elements of the given `path`, ordered from root-most to child-most.
+ * These elements are unchanged and therefore still point "up".
+ */
+export declare function topDownPath(path: UpPath | undefined): UpPath[];
+/**
+ * @returns true iff `a` and `b` describe the same path.
+ *
+ * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.
+ */
+export declare function compareUpPaths(a: UpPath | undefined, b: UpPath | undefined): boolean;
+/**
+ * @returns true iff `a` and `b` describe the same field path.
+ *
+ * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.
+ */
+export declare function compareFieldUpPaths(a: FieldUpPath, b: FieldUpPath): boolean;
+/**
+ * Checks whether or not a given path is parented under the root field.
+ * @param path - the path you want to check.
+ * @returns the {@link DetachedField} which contains the path.
+ */
+export declare function getDetachedFieldContainingPath(path: UpPath): DetachedField;
+//# sourceMappingURL=pathTree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pathTree.d.ts","sourceRoot":"","sources":["../../../src/core/tree/pathTree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAsB,MAAM,SAAS,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,MAAM,CAAC,OAAO,GAAG,aAAa;IAC9C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC;IAC/B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IAC3D;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAErC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAE,qBAAqB,CAAC,CAAC;AAE5F;;;GAGG;AACH,MAAM,WAAW,KAAK;IACrB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,WAAW,CAAC,OAAO,CAAC,EAAE,KAAK;CAAG;AAEpG;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,WAAW,CAAC,OAAO,CAAC;IACzF;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAE,qBAAqB,CAAC,CAAC;AAE5F;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAaxE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAS9D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAYpF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAK3E;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAU1E"}

package/dist/core/tree/pathTree.js

@@ -0,0 +1,99 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDetachedFieldContainingPath = exports.compareFieldUpPaths = exports.compareUpPaths = exports.topDownPath = exports.clonePath = exports.getDepth = void 0;
+const types_1 = require("./types");
+/**
+ * @returns the number of nodes above this one.
+ * Zero when the path's parent is undefined, meaning the path represents a node in a detached field.
+ * Runs in O(depth) time.
+ */
+function getDepth(path) {
+    let depth = 0;
+    let next = path.parent;
+    while (next !== undefined) {
+        depth += 1;
+        next = next.parent;
+    }
+    return depth;
+}
+exports.getDepth = getDepth;
+function clonePath(path) {
+    if (path === undefined) {
+        return undefined;
+    }
+    return {
+        parent: clonePath(path.parent),
+        parentField: path.parentField,
+        parentIndex: path.parentIndex,
+    };
+}
+exports.clonePath = clonePath;
+/**
+ * @returns The elements of the given `path`, ordered from root-most to child-most.
+ * These elements are unchanged and therefore still point "up".
+ */
+function topDownPath(path) {
+    const out = [];
+    let curr = path;
+    while (curr !== undefined) {
+        out.push(curr);
+        curr = curr.parent;
+    }
+    out.reverse();
+    return out;
+}
+exports.topDownPath = topDownPath;
+/**
+ * @returns true iff `a` and `b` describe the same path.
+ *
+ * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.
+ */
+function compareUpPaths(a, b) {
+    if (a === b) {
+        // This handles the both `undefined` case, as well as provides an early out if a shared node is encountered.
+        return true;
+    }
+    if (a === undefined || b === undefined) {
+        return false;
+    }
+    if (a.parentField !== b.parentField || a.parentIndex !== b.parentIndex) {
+        return false;
+    }
+    return compareUpPaths(a.parent, b.parent);
+}
+exports.compareUpPaths = compareUpPaths;
+/**
+ * @returns true iff `a` and `b` describe the same field path.
+ *
+ * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.
+ */
+function compareFieldUpPaths(a, b) {
+    if (a.field !== b.field) {
+        return false;
+    }
+    return compareUpPaths(a.parent, b.parent);
+}
+exports.compareFieldUpPaths = compareFieldUpPaths;
+/**
+ * Checks whether or not a given path is parented under the root field.
+ * @param path - the path you want to check.
+ * @returns the {@link DetachedField} which contains the path.
+ */
+function getDetachedFieldContainingPath(path) {
+    let currentPath = path;
+    while (currentPath !== undefined) {
+        if (currentPath.parent === undefined) {
+            return (0, types_1.keyAsDetachedField)(currentPath.parentField);
+        }
+        else {
+            currentPath = currentPath.parent;
+        }
+    }
+    return (0, types_1.keyAsDetachedField)(path.parentField);
+}
+exports.getDetachedFieldContainingPath = getDetachedFieldContainingPath;
+//# sourceMappingURL=pathTree.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pathTree.js","sourceRoot":"","sources":["../../../src/core/tree/pathTree.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAIH,mCAA4D;AAyH5D;;;;GAIG;AACH,SAAgB,QAAQ,CAAC,IAAY;IACpC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;IACvB,OAAO,IAAI,KAAK,SAAS,EAAE;QAC1B,KAAK,IAAI,CAAC,CAAC;QACX,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;KACnB;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AARD,4BAQC;AAcD,SAAgB,SAAS,CAAC,IAAwB;IACjD,IAAI,IAAI,KAAK,SAAS,EAAE;QACvB,OAAO,SAAS,CAAC;KACjB;IACD,OAAO;QACN,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;QAC9B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;KAC7B,CAAC;AACH,CAAC;AATD,8BASC;AAED;;;GAGG;AACH,SAAgB,WAAW,CAAC,IAAwB;IACnD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,OAAO,IAAI,KAAK,SAAS,EAAE;QAC1B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;KACnB;IACD,GAAG,CAAC,OAAO,EAAE,CAAC;IACd,OAAO,GAAG,CAAC;AACZ,CAAC;AATD,kCASC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,CAAqB,EAAE,CAAqB;IAC1E,IAAI,CAAC,KAAK,CAAC,EAAE;QACZ,4GAA4G;QAC5G,OAAO,IAAI,CAAC;KACZ;IACD,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS,EAAE;QACvC,OAAO,KAAK,CAAC;KACb;IACD,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,EAAE;QACvE,OAAO,KAAK,CAAC;KACb;IACD,OAAO,cAAc,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC;AAZD,wCAYC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,CAAc,EAAE,CAAc;IACjE,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,EAAE;QACxB,OAAO,KAAK,CAAC;KACb;IACD,OAAO,cAAc,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC;AALD,kDAKC;AAED;;;;GAIG;AACH,SAAgB,8BAA8B,CAAC,IAAY;IAC1D,IAAI,WAAW,GAAG,IAAI,CAAC;IACvB,OAAO,WAAW,KAAK,SAAS,EAAE;QACjC,IAAI,WAAW,CAAC,MAAM,KAAK,SAAS,EAAE;YACrC,OAAO,IAAA,0BAAkB,EAAC,WAAW,CAAC,WAAW,CAAC,CAAC;SACnD;aAAM;YACN,WAAW,GAAG,WAAW,CAAC,MAAM,CAAC;SACjC;KACD;IACD,OAAO,IAAA,0BAAkB,EAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAC7C,CAAC;AAVD,wEAUC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { Brand } from \"../../util\";\nimport { FieldKey } from \"../schema-stored\";\nimport { DetachedField, keyAsDetachedField } from \"./types\";\n\n/**\n * Identical to {@link UpPath}, but a duplicate declaration is needed to make\n * the default type parameter compile.\n *\n * @internal\n */\nexport type UpPathDefault = UpPath;\n\n/**\n * Path from a location in the tree upward.\n * UpPaths can be used with deduplicated upper parts to allow\n * working with paths localized to part of the tree without incurring\n * costs related to the depth of the local subtree.\n *\n * UpPaths can be thought of as terminating at a special root node (that is `undefined`)\n * whose FieldKeys correspond to detached sequences.\n *\n * UpPaths can be mutated over time and should be considered to be invalidated when any edits occurs:\n * Use of an UpPath that was acquired before the most recent edit is undefined behavior.\n * @internal\n */\nexport interface UpPath<TParent = UpPathDefault> {\n\t/**\n\t * The parent, or undefined in the case where this path is a member of a detached sequence.\n\t */\n\treadonly parent: TParent | undefined;\n\t/**\n\t * The Field under which this path points.\n\t * Note that if `parent` returns `undefined`, this key corresponds to a detached sequence.\n\t */\n\treadonly parentField: FieldKey; // TODO: Type information, including when in DetachedField.\n\t/**\n\t * The index within `parentField` this path is pointing to.\n\t */\n\treadonly parentIndex: NodeIndex;\n}\n\n/**\n * Path from a field in the tree upward.\n *\n * See {@link UpPath}.\n * @internal\n */\nexport interface FieldUpPath<TUpPath extends UpPath = UpPath> {\n\t/**\n\t * The parent, or undefined in the case where this path is to a detached sequence.\n\t */\n\treadonly parent: TUpPath | undefined;\n\n\t/**\n\t * The Field to which this path points.\n\t * Note that if `parent` returns `undefined`, this key  corresponds to a detached sequence.\n\t */\n\treadonly field: FieldKey; // TODO: Type information, including when in DetachedField.\n}\n\n/**\n * A range of nodes in a detached field.\n * Unlike RangeUpPath, such ranges are generated by create and detach operations,\n * as well as consumed by destroy and attach operations.\n * @internal\n */\nexport type DetachedRangeUpPath = Brand<Omit<RangeUpPath, \"parent\">, \"DetachedRangeUpPath\">;\n\n/**\n * Delimits the extend of a range.\n * @internal\n */\nexport interface Range {\n\t/**\n\t * The location before the first node.\n\t * Must be less than or equal to `end`.\n\t */\n\treadonly start: PlaceIndex;\n\t/**\n\t * The location after the last node.\n\t * Must be greater than or equal to `start`.\n\t */\n\treadonly end: PlaceIndex;\n}\n\n/**\n * A possibly empty range of nodes in a field.\n * This object only characterizes the location of the range, it does not own/contain the nodes in the range.\n * @internal\n */\nexport interface RangeUpPath<TUpPath extends UpPath = UpPath> extends FieldUpPath<TUpPath>, Range {}\n\n/**\n * A place in a field.\n * @internal\n */\nexport interface PlaceUpPath<TUpPath extends UpPath = UpPath> extends FieldUpPath<TUpPath> {\n\t/**\n\t * The location in the field.\n\t */\n\treadonly index: PlaceIndex;\n}\n\n/**\n * A place in a detached field.\n * @internal\n */\nexport type DetachedPlaceUpPath = Brand<Omit<PlaceUpPath, \"parent\">, \"DetachedRangeUpPath\">;\n\n/**\n * Indicates the index of a node in a field.\n * Zero indicates the first node in a field.\n * @internal\n */\nexport type NodeIndex = number;\n\n/**\n * Indicates a place between nodes in a field or at the extremity of a field.\n * Zero indicates the place at the start of the field (before the first node if any).\n * @internal\n */\nexport type PlaceIndex = number;\n\n/**\n * @returns the number of nodes above this one.\n * Zero when the path's parent is undefined, meaning the path represents a node in a detached field.\n * Runs in O(depth) time.\n */\nexport function getDepth(path: UpPath): number {\n\tlet depth = 0;\n\tlet next = path.parent;\n\twhile (next !== undefined) {\n\t\tdepth += 1;\n\t\tnext = next.parent;\n\t}\n\treturn depth;\n}\n\n/**\n * @returns a deep copy of the provided path as simple javascript objects.\n * This is safe to hold onto and use deep object comparisons on.\n */\nexport function clonePath(path: UpPath): UpPath;\n\n/**\n * @returns a deep copy of the provided path as simple javascript objects.\n * This is safe to hold onto and use deep object comparisons on.\n */\nexport function clonePath(path: UpPath | undefined): UpPath | undefined;\n\nexport function clonePath(path: UpPath | undefined): UpPath | undefined {\n\tif (path === undefined) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tparent: clonePath(path.parent),\n\t\tparentField: path.parentField,\n\t\tparentIndex: path.parentIndex,\n\t};\n}\n\n/**\n * @returns The elements of the given `path`, ordered from root-most to child-most.\n * These elements are unchanged and therefore still point \"up\".\n */\nexport function topDownPath(path: UpPath | undefined): UpPath[] {\n\tconst out: UpPath[] = [];\n\tlet curr = path;\n\twhile (curr !== undefined) {\n\t\tout.push(curr);\n\t\tcurr = curr.parent;\n\t}\n\tout.reverse();\n\treturn out;\n}\n\n/**\n * @returns true iff `a` and `b` describe the same path.\n *\n * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.\n */\nexport function compareUpPaths(a: UpPath | undefined, b: UpPath | undefined): boolean {\n\tif (a === b) {\n\t\t// This handles the both `undefined` case, as well as provides an early out if a shared node is encountered.\n\t\treturn true;\n\t}\n\tif (a === undefined || b === undefined) {\n\t\treturn false;\n\t}\n\tif (a.parentField !== b.parentField || a.parentIndex !== b.parentIndex) {\n\t\treturn false;\n\t}\n\treturn compareUpPaths(a.parent, b.parent);\n}\n\n/**\n * @returns true iff `a` and `b` describe the same field path.\n *\n * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.\n */\nexport function compareFieldUpPaths(a: FieldUpPath, b: FieldUpPath): boolean {\n\tif (a.field !== b.field) {\n\t\treturn false;\n\t}\n\treturn compareUpPaths(a.parent, b.parent);\n}\n\n/**\n * Checks whether or not a given path is parented under the root field.\n * @param path - the path you want to check.\n * @returns the {@link DetachedField} which contains the path.\n */\nexport function getDetachedFieldContainingPath(path: UpPath): DetachedField {\n\tlet currentPath = path;\n\twhile (currentPath !== undefined) {\n\t\tif (currentPath.parent === undefined) {\n\t\t\treturn keyAsDetachedField(currentPath.parentField);\n\t\t} else {\n\t\t\tcurrentPath = currentPath.parent;\n\t\t}\n\t}\n\treturn keyAsDetachedField(path.parentField);\n}\n"]}

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

@@ -0,0 +1,93 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Static, TSchema } from "@sinclair/typebox";
+import { schemaFormat } from "../schema-stored";
+/**
+ * This module contains persisted types for a simple, human-readable tree format.
+ *
+ * It was forked from `treeTextFormat.ts` to more cleanly separate compatibility concerns: in the long-term,
+ * treeTextFormat.ts is intended to be useful for debugging/test purposes but not for persisted document storage
+ * due to its unoptimized nature.
+ *
+ * However, at the time of forking it was also used as a persisted format for several of SharedTree's indexes.
+ * Using the same types for both scenarios is problematic since `treeTextFormat.ts` types are exposed to the
+ * public API.
+ * These types should be used instead for all persisted format concerns.
+ *
+ * Before SharedTree has committed to persisted format backwards-compatibility, changes to `treeTextFormat.ts`
+ * should be accompanied by the same changes to this module.
+ *
+ * After that point, changes to `treeTextFormat.ts` will necessitate changes to codecs that deal with these types
+ * (and types in this module should not be changed except in compliance with persisted type compatibility guidelines).
+ *
+ * Longer-term, usages of these types should likely be replaced with a more optimized format.
+ * If that switch happens before SharedTree commits to back-compat, this persisted format file can be deleted.
+ */
+/**
+ * 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.
+ */
+interface EncodedFieldMapObject<TChild> {
+    [key: string]: TChild[];
+}
+declare const EncodedFieldMapObject: <Schema extends TSchema>(tChild: Schema) => import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<Schema>>;
+type EncodedNodeData = Static<typeof EncodedNodeData>;
+declare const EncodedNodeData: import("@sinclair/typebox").TObject<{
+    value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+    type: import("@sinclair/typebox").TReadonly<import("@sinclair/typebox").TUnsafe<schemaFormat.TreeNodeSchemaIdentifier<string>>>;
+}>;
+/**
+ * Json comparable field collection, generic over child type.
+ * Json compatibility assumes `TChild` is also json compatible.
+ */
+interface EncodedGenericFieldsNode<TChild> {
+    fields?: EncodedFieldMapObject<TChild>;
+    globalFields?: EncodedFieldMapObject<TChild>;
+}
+declare const EncodedGenericFieldsNode: <Schema extends TSchema>(tChild: Schema) => import("@sinclair/typebox").TObject<{
+    fields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<Schema>>>;
+    globalFields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<Schema>>>;
+}>;
+/**
+ * Json comparable tree node, generic over child type.
+ * Json compatibility assumes `TChild` is also json compatible.
+ */
+interface EncodedGenericTreeNode<TChild> extends EncodedGenericFieldsNode<TChild>, EncodedNodeData {
+}
+declare const EncodedGenericTreeNode: <Schema extends TSchema>(tChild: Schema) => import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TReadonly<import("@sinclair/typebox").TUnsafe<schemaFormat.TreeNodeSchemaIdentifier<string>>>;
+    value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+    fields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<Schema>>>;
+    globalFields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<Schema>>>;
+}>;
+/**
+ * A tree represented using plain JavaScript objects.
+ * Can be passed to `JSON.stringify()` to produce a human-readable/editable JSON tree.
+ *
+ * JsonableTrees must not store empty fields.
+ */
+export interface EncodedJsonableTree extends EncodedGenericTreeNode<EncodedJsonableTree> {
+}
+export declare const EncodedJsonableTree: import("@sinclair/typebox").TRecursive<import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TReadonly<import("@sinclair/typebox").TUnsafe<schemaFormat.TreeNodeSchemaIdentifier<string>>>;
+    value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+    fields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TThis>>>;
+    globalFields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TThis>>>;
+}>>;
+export {};
+//# sourceMappingURL=persistedTreeTextFormat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"persistedTreeTextFormat.d.ts","sourceRoot":"","sources":["../../../src/core/tree/persistedTreeTextFormat.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAQ,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,UAAU,qBAAqB,CAAC,MAAM;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACxB;AACD,QAAA,MAAM,qBAAqB,kKACqC,CAAC;AAEjE,KAAK,eAAe,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AACtD,QAAA,MAAM,eAAe;;;EAGnB,CAAC;AAEH;;;GAGG;AACH,UAAU,wBAAwB,CAAC,MAAM;IACxC,MAAM,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACvC,YAAY,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;CAC7C;AACD,QAAA,MAAM,wBAAwB;;;EAI3B,CAAC;AAEJ;;;GAGG;AACH,UAAU,sBAAsB,CAAC,MAAM,CACtC,SAAQ,wBAAwB,CAAC,MAAM,CAAC,EACvC,eAAe;CAAG;AACpB,QAAA,MAAM,sBAAsB;;;;;EAGzB,CAAC;AAEJ;;;;;GAKG;AACH,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB,CAAC,mBAAmB,CAAC;CAAG;AAC3F,eAAO,MAAM,mBAAmB;;;;;GAAyD,CAAC"}

package/dist/core/tree/persistedTreeTextFormat.js

@@ -0,0 +1,23 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncodedJsonableTree = void 0;
+const typebox_1 = require("@sinclair/typebox");
+const schema_stored_1 = require("../schema-stored");
+const EncodedFieldMapObject = (tChild) => typebox_1.Type.Record(typebox_1.Type.String(), typebox_1.Type.Array(tChild, { minItems: 1 }));
+const EncodedNodeData = typebox_1.Type.Object({
+    value: typebox_1.Type.Optional(typebox_1.Type.Any()),
+    type: typebox_1.Type.Readonly(schema_stored_1.schemaFormat.TreeNodeSchemaIdentifierSchema),
+});
+const EncodedGenericFieldsNode = (tChild) => typebox_1.Type.Object({
+    fields: typebox_1.Type.Optional(EncodedFieldMapObject(tChild)),
+    globalFields: typebox_1.Type.Optional(EncodedFieldMapObject(tChild)),
+});
+const EncodedGenericTreeNode = (tChild) => typebox_1.Type.Composite([EncodedGenericFieldsNode(tChild), EncodedNodeData], {
+    additionalProperties: false,
+});
+exports.EncodedJsonableTree = typebox_1.Type.Recursive((Self) => EncodedGenericTreeNode(Self));
+//# sourceMappingURL=persistedTreeTextFormat.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"persistedTreeTextFormat.js","sourceRoot":"","sources":["../../../src/core/tree/persistedTreeTextFormat.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,+CAA0D;AAC1D,oDAAgD;AA4ChD,MAAM,qBAAqB,GAAG,CAAyB,MAAc,EAAE,EAAE,CACxE,cAAI,CAAC,MAAM,CAAC,cAAI,CAAC,MAAM,EAAE,EAAE,cAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAGjE,MAAM,eAAe,GAAG,cAAI,CAAC,MAAM,CAAC;IACnC,KAAK,EAAE,cAAI,CAAC,QAAQ,CAAC,cAAI,CAAC,GAAG,EAAE,CAAC;IAChC,IAAI,EAAE,cAAI,CAAC,QAAQ,CAAC,4BAAY,CAAC,8BAA8B,CAAC;CAChE,CAAC,CAAC;AAUH,MAAM,wBAAwB,GAAG,CAAyB,MAAc,EAAE,EAAE,CAC3E,cAAI,CAAC,MAAM,CAAC;IACX,MAAM,EAAE,cAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACpD,YAAY,EAAE,cAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;CAC1D,CAAC,CAAC;AASJ,MAAM,sBAAsB,GAAG,CAAyB,MAAc,EAAE,EAAE,CACzE,cAAI,CAAC,SAAS,CAAC,CAAC,wBAAwB,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC,EAAE;IACnE,oBAAoB,EAAE,KAAK;CAC3B,CAAC,CAAC;AASS,QAAA,mBAAmB,GAAG,cAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { Static, TSchema, Type } from \"@sinclair/typebox\";\nimport { schemaFormat } from \"../schema-stored\";\n\n/**\n * This module contains persisted types for a simple, human-readable tree format.\n *\n * It was forked from `treeTextFormat.ts` to more cleanly separate compatibility concerns: in the long-term,\n * treeTextFormat.ts is intended to be useful for debugging/test purposes but not for persisted document storage\n * due to its unoptimized nature.\n *\n * However, at the time of forking it was also used as a persisted format for several of SharedTree's indexes.\n * Using the same types for both scenarios is problematic since `treeTextFormat.ts` types are exposed to the\n * public API.\n * These types should be used instead for all persisted format concerns.\n *\n * Before SharedTree has committed to persisted format backwards-compatibility, changes to `treeTextFormat.ts`\n * should be accompanied by the same changes to this module.\n *\n * After that point, changes to `treeTextFormat.ts` will necessitate changes to codecs that deal with these types\n * (and types in this module should not be changed except in compliance with persisted type compatibility guidelines).\n *\n * Longer-term, usages of these types should likely be replaced with a more optimized format.\n * If that switch happens before SharedTree commits to back-compat, this persisted format file can be deleted.\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 */\ninterface EncodedFieldMapObject<TChild> {\n\t[key: string]: TChild[];\n}\nconst EncodedFieldMapObject = <Schema extends TSchema>(tChild: Schema) =>\n\tType.Record(Type.String(), Type.Array(tChild, { minItems: 1 }));\n\ntype EncodedNodeData = Static<typeof EncodedNodeData>;\nconst EncodedNodeData = Type.Object({\n\tvalue: Type.Optional(Type.Any()),\n\ttype: Type.Readonly(schemaFormat.TreeNodeSchemaIdentifierSchema),\n});\n\n/**\n * Json comparable field collection, generic over child type.\n * Json compatibility assumes `TChild` is also json compatible.\n */\ninterface EncodedGenericFieldsNode<TChild> {\n\tfields?: EncodedFieldMapObject<TChild>;\n\tglobalFields?: EncodedFieldMapObject<TChild>;\n}\nconst EncodedGenericFieldsNode = <Schema extends TSchema>(tChild: Schema) =>\n\tType.Object({\n\t\tfields: Type.Optional(EncodedFieldMapObject(tChild)),\n\t\tglobalFields: Type.Optional(EncodedFieldMapObject(tChild)),\n\t});\n\n/**\n * Json comparable tree node, generic over child type.\n * Json compatibility assumes `TChild` is also json compatible.\n */\ninterface EncodedGenericTreeNode<TChild>\n\textends EncodedGenericFieldsNode<TChild>,\n\t\tEncodedNodeData {}\nconst EncodedGenericTreeNode = <Schema extends TSchema>(tChild: Schema) =>\n\tType.Composite([EncodedGenericFieldsNode(tChild), EncodedNodeData], {\n\t\tadditionalProperties: false,\n\t});\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 must not store empty fields.\n */\nexport interface EncodedJsonableTree extends EncodedGenericTreeNode<EncodedJsonableTree> {}\nexport const EncodedJsonableTree = Type.Recursive((Self) => EncodedGenericTreeNode(Self));\n"]}

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

@@ -0,0 +1,91 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { FieldKey } from "../schema-stored";
+import { UpPath } from "./pathTree";
+/**
+ * Sparse Tree of nodes.
+ *
+ * Contains both child and parent pointers, which are kept in sync.
+ *
+ * Each node is equivalent to a path through the tree.
+ * This tree structure stores a collection of these paths, but deduplicating the common prefixes of the tree
+ * prefix-tree style.
+ */
+export declare class SparseNode<TData> implements UpPath {
+    parentField: FieldKey;
+    parentIndex: number;
+    /**
+     * The parent of this `SparseNode` (an up pointer in the `SparseNode` tree).
+     * If the status of this node is `Alive`, then there must be a corresponding down pointer from the
+     * `parentPath` node to this node.
+     * When undefined, this node is the root and thus has no parent.
+     *
+     * When updating the tree, it is valid to transiently leave the up and down pointers inconsistent
+     * (updating down pointers first), but they must be consistent when the update is completed.
+     */
+    parentPath: SparseNode<TData> | undefined;
+    data: TData;
+    /**
+     * SparseNode arrays are kept sorted the SparseNode's parentIndex for efficient search.
+     * Users of this field must take care to maintain invariants (correct parent pointers, not empty child arrays etc.)
+     *
+     * Performance Note:
+     * Large child lists could be updated more efficiently here using a data-structure optimized
+     * for efficient prefix sum updates, such as a Fenwick tree or Finger tree.
+     * This would be complicated by the need for parent pointers (including indexes),
+     * but is possible to do.
+     */
+    readonly children: Map<FieldKey, SparseNode<TData>[]>;
+    constructor(parentField: FieldKey, parentIndex: number, 
+    /**
+     * The parent of this `SparseNode` (an up pointer in the `SparseNode` tree).
+     * If the status of this node is `Alive`, then there must be a corresponding down pointer from the
+     * `parentPath` node to this node.
+     * When undefined, this node is the root and thus has no parent.
+     *
+     * When updating the tree, it is valid to transiently leave the up and down pointers inconsistent
+     * (updating down pointers first), but they must be consistent when the update is completed.
+     */
+    parentPath: SparseNode<TData> | undefined, data: TData);
+    /**
+     * @returns true iff this SparseNode is the special root node that sits above all the detached fields.
+     * In this case, the fields are detached sequences.
+     * Note that the special root node should never appear in an UpPath
+     * since UpPaths represent this root as `undefined`.
+     */
+    private isRoot;
+    get parent(): SparseNode<TData> | undefined;
+    /**
+     * Gets a child, adding a ref to it.
+     * Creates child (with 1 ref) if needed.
+     */
+    getOrCreateChild(key: FieldKey, index: number, data: () => TData): SparseNode<TData>;
+    /**
+     * Gets a child if it exists.
+     * Does NOT add a ref.
+     */
+    tryGetChild(key: FieldKey, index: number): SparseNode<TData> | undefined;
+    /**
+     * Removes reference from this to `child`.
+     * Since PathNodes are doubly linked,
+     * the caller must ensure that the reference from child to parent is also removed (or the child is no longer used).
+     */
+    removeChild(child: SparseNode<TData>): void;
+    /**
+     * Call this after directly editing the child array for a field to be empty.
+     * Handles cleaning up unneeded data
+     * (like the field in the map, and possibly this entire SparseNode and its parents if they are no longer needed.)
+     */
+    afterEmptyField(key: FieldKey): void;
+    /**
+     * Removes this from parent if alive, and sets this to disposed.
+     * Must only be called when this node is no longer needed (has no references and no children).
+     *
+     * Allowed when dangling (but not when disposed).
+     */
+    private disposeThis;
+}
+export declare function getDescendant<TData>(ancestor: SparseNode<TData>, path: UpPath | undefined): SparseNode<TData>;
+//# sourceMappingURL=sparseTree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sparseTree.d.ts","sourceRoot":"","sources":["../../../src/core/tree/sparseTree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAe,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;GAQG;AACH,qBAAa,UAAU,CAAC,KAAK,CAAE,YAAW,MAAM;IAcvC,WAAW,EAAE,QAAQ;IACrB,WAAW,EAAE,MAAM;IAC1B;;;;;;;;OAQG;IACI,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,SAAS;IACzC,IAAI,EAAE,KAAK;IAzBnB;;;;;;;;;OASG;IACH,SAAgB,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAa;gBAGjE,WAAW,EAAE,QAAQ,EACrB,WAAW,EAAE,MAAM;IAC1B;;;;;;;;OAQG;IACI,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,SAAS,EACzC,IAAI,EAAE,KAAK;IAGnB;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IAId,IAAW,MAAM,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,SAAS,CAUjD;IAED;;;OAGG;IACI,gBAAgB,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;IAiB3F;;;OAGG;IACI,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,SAAS;IAS/E;;;;OAIG;IACI,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI;IAalD;;;;OAIG;IACI,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAO3C;;;;;OAKG;IACH,OAAO,CAAC,WAAW;CAGnB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAClC,QAAQ,EAAE,UAAU,CAAC,KAAK,CAAC,EAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,GACtB,UAAU,CAAC,KAAK,CAAC,CAYnB"}

package/dist/core/tree/sparseTree.js

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