@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/feature-libraries/treeCursorUtils.js

@@ -0,0 +1,374 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var _a, _b;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrefixedPath = exports.prefixPathPrefix = exports.prefixFieldPath = exports.prefixPath = exports.SynchronousCursor = exports.stackTreeFieldCursor = exports.stackTreeNodeCursor = void 0;
+const core_utils_1 = require("@fluidframework/core-utils");
+const core_1 = require("../core");
+const util_1 = require("../util");
+/**
+ * Create a cursor, in `nodes` mode at the root of the provided tree.
+ *
+ * @returns an {@link ITreeCursorSynchronous} for a single root in `nodes` mode.
+ * @internal
+ */
+function stackTreeNodeCursor(adapter, root) {
+    return new StackCursor(adapter, [], [], [root], 0);
+}
+exports.stackTreeNodeCursor = stackTreeNodeCursor;
+/**
+ * Create a cursor, in `fields` mode at the `detachedField` under the provided `root`.
+ *
+ * @returns an {@link ITreeCursorSynchronous} for `detachedField` of `root` in `fields` mode.
+ * @internal
+ */
+function stackTreeFieldCursor(adapter, root, detachedField = core_1.rootField) {
+    const cursor = stackTreeNodeCursor(adapter, root);
+    // Because the root node in `stackTreeNodeCursor` is treated as the above detached fields node,
+    // using it then just entering the correct field doesn't mess up the paths reported by the cursor.
+    cursor.enterField((0, core_1.detachedFieldAsKey)(detachedField));
+    return cursor;
+}
+exports.stackTreeFieldCursor = stackTreeFieldCursor;
+/**
+ * A class that satisfies part of the ITreeCursorSynchronous implementation.
+ */
+class SynchronousCursor {
+    constructor() {
+        this[_a] = true;
+        this.pending = false;
+    }
+    skipPendingFields() {
+        return true;
+    }
+}
+exports.SynchronousCursor = SynchronousCursor;
+_a = core_1.CursorMarker;
+/**
+ * A simple general purpose ITreeCursorSynchronous implementation.
+ *
+ * As this is a generic implementation, it's ability to optimize is limited.
+ *
+ * @privateRemarks
+ * Note that TNode can be `null` (and we should support `undefined` as well),
+ * so be careful using types like `TNode | undefined` and expressions like `TNode ??`.
+ *
+ * TODO:
+ * 1. Unit tests for this.
+ * 2. Support for cursors which are field cursors at the root.
+ */
+class StackCursor extends SynchronousCursor {
+    /**
+     * Might start at special root where fields are detached sequences.
+     *
+     * @param adapter - policy logic.
+     * @param siblingStack - Stack of collections of siblings along the path through the tree:
+     * does not include current level (which is stored in `siblings`).
+     * Even levels in the stack (starting from 0) are sequences of nodes and odd levels
+     * are for fields keys on a node.
+     * @param indexStack - Stack of indices into the corresponding levels in `siblingStack`.
+     * @param siblings - Siblings at the current level (not included in `siblingStack`).
+     * @param index - Index into `siblings`.
+     */
+    constructor(adapter, siblingStack, indexStack, siblings, index) {
+        super();
+        this.adapter = adapter;
+        this.siblingStack = siblingStack;
+        this.indexStack = indexStack;
+        this.siblings = siblings;
+        this.index = index;
+        this[_b] = true;
+        this.chunkLength = 1;
+    }
+    getFieldKey() {
+        // assert(this.mode === CursorLocationType.Fields, "must be in fields mode");
+        return this.siblings[this.index];
+    }
+    getStackedFieldKey(height) {
+        (0, core_utils_1.assert)(height % 2 === 1, 0x3b8 /* must field height */);
+        return this.siblingStack[height][this.indexStack[height]];
+    }
+    getStackedNodeIndex(height) {
+        // assert(height % 2 === 0, "must be node height");
+        return this.indexStack[height];
+    }
+    getStackedNode(height) {
+        const index = this.getStackedNodeIndex(height);
+        return this.siblingStack[height][index];
+    }
+    getFieldLength() {
+        // assert(this.mode === CursorLocationType.Fields, "must be in fields mode");
+        return this.getField().length;
+    }
+    enterNode(index) {
+        // assert(this.mode === CursorLocationType.Fields, "must be in fields mode");
+        const siblings = this.getField();
+        (0, core_utils_1.assert)(index in siblings, 0x405 /* child must exist at index */);
+        this.siblingStack.push(this.siblings);
+        this.indexStack.push(this.index);
+        this.index = index;
+        this.siblings = siblings;
+    }
+    getPath(prefix) {
+        (0, core_utils_1.assert)(this.mode === 0 /* CursorLocationType.Nodes */, 0x3b9 /* must be in nodes mode */);
+        return this.getOffsetPath(0, prefix);
+    }
+    getFieldPath(prefix) {
+        (0, core_utils_1.assert)(this.mode === 1 /* CursorLocationType.Fields */, 0x449 /* must be in fields mode */);
+        return {
+            field: this.indexStack.length === 1
+                ? prefix?.rootFieldOverride ?? this.getFieldKey()
+                : this.getFieldKey(),
+            parent: this.getOffsetPath(1, prefix),
+        };
+    }
+    getOffsetPath(offset, prefix) {
+        // It is more efficient to handle prefix directly in here rather than delegating to PrefixedPath.
+        const length = this.indexStack.length - offset;
+        if (length === 0) {
+            return prefix?.parent; // At root
+        }
+        (0, core_utils_1.assert)(length > 0, 0x44a /* invalid offset to above root */);
+        (0, core_utils_1.assert)(length % 2 === 0, 0x44b /* offset path must point to node not field */);
+        const getIndex = (height) => {
+            let parentIndex = height === this.indexStack.length ? this.index : this.getStackedNodeIndex(height);
+            if (prefix !== undefined && height === 2) {
+                parentIndex += prefix.indexOffset ?? 0;
+            }
+            return parentIndex;
+        };
+        // Perf Note:
+        // This is O(depth) in tree.
+        // If many different anchors are created, this could be optimized to amortize the costs.
+        // For example, the cursor could cache UpPaths from the anchorSet when creating an anchor,
+        // then reuse them as a starting point when making another.
+        // Could cache this at one depth, and remember the depth.
+        // When navigating up, adjust cached anchor if present.
+        let path = prefix?.parent;
+        // Skip top level, since root node in path is "undefined" and does not have a parent or index.
+        for (let height = 2; height <= length; height += 2) {
+            const fieldOverride = height === 2 ? prefix?.rootFieldOverride : undefined;
+            path = {
+                parent: path,
+                parentIndex: getIndex(height),
+                parentField: fieldOverride ?? this.getStackedFieldKey(height - 1),
+            };
+        }
+        return path;
+    }
+    fork() {
+        // Siblings arrays are not modified during navigation and do not need be be copied.
+        // This allows this copy to be shallow, and `this.siblings` below to not be copied as all.
+        return new StackCursor(this.adapter, [...this.siblingStack], [...this.indexStack], this.siblings, this.index);
+    }
+    enterField(key) {
+        // assert(this.mode === CursorLocationType.Nodes, "must be in nodes mode");
+        this.siblingStack.push(this.siblings);
+        this.indexStack.push(this.index);
+        // For fields, siblings are only used for key lookup and
+        // nextField and which has arbitrary iteration order,
+        // so making a array of just key here works.
+        // This adds an allocation, so it's optimizing code simplicity and for the other use case (enumeration)
+        // at the cost of an allocation here.
+        this.index = 0;
+        this.siblings = [key];
+    }
+    get mode() {
+        return this.siblingStack.length % 2 === 0
+            ? 0 /* CursorLocationType.Nodes */
+            : 1 /* CursorLocationType.Fields */;
+    }
+    nextField() {
+        this.index += 1;
+        if (this.index === this.siblings.length) {
+            this.exitField();
+            return false;
+        }
+        return true;
+    }
+    firstField() {
+        // assert(this.mode === CursorLocationType.Nodes, "must be in nodes mode");
+        const fields = this.adapter.keysFromNode(this.getNode());
+        if (fields.length === 0) {
+            return false;
+        }
+        this.siblingStack.push(this.siblings);
+        this.indexStack.push(this.index);
+        this.index = 0;
+        this.siblings = fields;
+        return true;
+    }
+    seekNodes(offset) {
+        // assert(this.mode === CursorLocationType.Nodes, "can only seekNodes when in Nodes");
+        this.index += offset;
+        if (this.index in this.siblings) {
+            return true;
+        }
+        this.exitNode();
+        return false;
+    }
+    firstNode() {
+        // assert(this.mode === CursorLocationType.Fields, "firstNode only allowed in fields mode");
+        const nodes = this.getField();
+        if (nodes.length === 0) {
+            return false;
+        }
+        this.siblingStack.push(this.siblings);
+        this.indexStack.push(this.index);
+        this.index = 0;
+        this.siblings = nodes;
+        return true;
+    }
+    nextNode() {
+        (0, core_utils_1.assert)(this.mode === 0 /* CursorLocationType.Nodes */, 0x406 /* can only nextNode when in Nodes */);
+        this.index++;
+        if (this.index < this.siblings.length) {
+            return true;
+        }
+        this.exitNode();
+        return false;
+    }
+    exitField() {
+        // assert(this.mode === CursorLocationType.Fields, "can only navigate up from field when in field");
+        this.siblings = this.siblingStack.pop() ?? (0, util_1.fail)("Unexpected siblingStack.length");
+        this.index = this.indexStack.pop() ?? (0, util_1.fail)("Unexpected indexStack.length");
+    }
+    exitNode() {
+        // assert(this.mode === CursorLocationType.Nodes, "can only navigate up from node when in node");
+        this.siblings = this.siblingStack.pop() ?? (0, util_1.fail)("Unexpected siblingStack.length");
+        this.index = this.indexStack.pop() ?? (0, util_1.fail)("Unexpected indexStack.length");
+    }
+    getNode() {
+        // assert(this.mode === CursorLocationType.Nodes, "can only get node when in node");
+        return this.siblings[this.index];
+    }
+    getField() {
+        // assert(this.mode === CursorLocationType.Fields, "can only get field when in fields");
+        const parent = this.getStackedNode(this.indexStack.length - 1);
+        const key = this.getFieldKey();
+        const field = this.adapter.getFieldFromNode(parent, key);
+        return field;
+    }
+    /**
+     * @returns the value of the current node
+     */
+    get value() {
+        return this.adapter.value(this.getNode());
+    }
+    /**
+     * @returns the type of the current node
+     */
+    get type() {
+        return this.adapter.type(this.getNode());
+    }
+    get fieldIndex() {
+        // assert(this.mode === CursorLocationType.Nodes, "can only node's index when in node");
+        return this.index;
+    }
+    get chunkStart() {
+        return this.fieldIndex;
+    }
+}
+_b = core_1.CursorMarker;
+/**
+ * Apply `prefix` to `path`.
+ * @internal
+ */
+function prefixPath(prefix, path) {
+    if (prefix === undefined) {
+        return path;
+    }
+    if (prefix.parent === undefined &&
+        prefix.rootFieldOverride === undefined &&
+        (prefix.indexOffset ?? 0) === 0) {
+        return path;
+    }
+    return applyPrefix(prefix, path);
+}
+exports.prefixPath = prefixPath;
+/**
+ * Apply `prefix` to `path`.
+ * @internal
+ */
+function prefixFieldPath(prefix, path) {
+    if (prefix === undefined) {
+        return path;
+    }
+    if (prefix.parent === undefined &&
+        prefix.rootFieldOverride === undefined &&
+        (prefix.indexOffset ?? 0) === 0) {
+        return path;
+    }
+    return {
+        field: path.parent === undefined ? prefix.rootFieldOverride ?? path.field : path.field,
+        parent: prefixPath(prefix, path.parent),
+    };
+}
+exports.prefixFieldPath = prefixFieldPath;
+/**
+ * Compose two prefixes together.
+ * `prefixFieldPath(root, prefixFieldPath(inner, path))` should be the same as `prefixFieldPath(prefixPathPrefix(root, inner), path))`
+ *
+ * TODO: tests for this.
+ */
+function prefixPathPrefix(root, inner) {
+    if (inner.parent !== undefined) {
+        const composedPrefix = {
+            parent: new PrefixedPath(root, inner.parent),
+            rootFieldOverride: inner.rootFieldOverride,
+            indexOffset: inner.indexOffset,
+        };
+        return composedPrefix;
+    }
+    else {
+        const composedPrefix = {
+            parent: root.parent,
+            rootFieldOverride: root.rootFieldOverride ?? inner.rootFieldOverride,
+            indexOffset: (inner.indexOffset ?? 0) + (root.indexOffset ?? 0),
+        };
+        return composedPrefix;
+    }
+}
+exports.prefixPathPrefix = prefixPathPrefix;
+function applyPrefix(prefix, path) {
+    if (path === undefined) {
+        return prefix.parent;
+    }
+    else {
+        // As an optimization, avoid double wrapping paths with multiple prefixes
+        if (path instanceof PrefixedPath) {
+            const composedPrefix = prefixPathPrefix(prefix, path.prefix);
+            return new PrefixedPath(composedPrefix, path.path);
+        }
+        else {
+            return new PrefixedPath(prefix, path);
+        }
+    }
+}
+/**
+ * Wrapper around a path that adds a prefix to the root.
+ *
+ * Exported for testing: use `prefixPath` and `prefixFieldPath` to construct.
+ */
+class PrefixedPath {
+    constructor(prefix, path) {
+        this.prefix = prefix;
+        this.path = path;
+        if (path.parent === undefined) {
+            this.parentField = prefix.rootFieldOverride ?? path.parentField;
+            this.parentIndex = path.parentIndex + (prefix.indexOffset ?? 0);
+        }
+        else {
+            this.parentField = path.parentField;
+            this.parentIndex = path.parentIndex;
+        }
+    }
+    get parent() {
+        return applyPrefix(this.prefix, this.path.parent);
+    }
+}
+exports.PrefixedPath = PrefixedPath;
+//# sourceMappingURL=treeCursorUtils.js.map

package/dist/feature-libraries/treeCursorUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeCursorUtils.js","sourceRoot":"","sources":["../../src/feature-libraries/treeCursorUtils.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 {\n\tFieldKey,\n\tTreeType,\n\tUpPath,\n\tCursorLocationType,\n\tITreeCursorSynchronous,\n\tValue,\n\tFieldUpPath,\n\tPathRootPrefix,\n\tCursorMarker,\n\tDetachedField,\n\trootField,\n\tdetachedFieldAsKey,\n} from \"../core\";\nimport { fail } from \"../util\";\n\n/**\n * {@link ITreeCursorSynchronous} that can return the underlying node objects.\n * @internal\n */\nexport interface CursorWithNode<TNode> extends ITreeCursorSynchronous {\n\t/**\n\t * Gets the underlying object for the current node.\n\t *\n\t * Only valid when `mode` is `Nodes`.\n\t */\n\tgetNode(): TNode;\n\n\t/**\n\t * Create a copy of this cursor which navigates independently,\n\t * and is initially located at the same place as this one.\n\t *\n\t * Depending on the cursor implementation this may be significantly faster\n\t * than other ways to copy the cursor\n\t * (such as creating a new one and walking the path from this one).\n\t */\n\tfork(): CursorWithNode<TNode>;\n}\n\n/**\n * Create a cursor, in `nodes` mode at the root of the provided tree.\n *\n * @returns an {@link ITreeCursorSynchronous} for a single root in `nodes` mode.\n * @internal\n */\nexport function stackTreeNodeCursor<TNode>(\n\tadapter: CursorAdapter<TNode>,\n\troot: TNode,\n): CursorWithNode<TNode> {\n\treturn new StackCursor(adapter, [], [], [root], 0);\n}\n\n/**\n * Create a cursor, in `fields` mode at the `detachedField` under the provided `root`.\n *\n * @returns an {@link ITreeCursorSynchronous} for `detachedField` of `root` in `fields` mode.\n * @internal\n */\nexport function stackTreeFieldCursor<TNode>(\n\tadapter: CursorAdapter<TNode>,\n\troot: TNode,\n\tdetachedField: DetachedField = rootField,\n): CursorWithNode<TNode> {\n\tconst cursor = stackTreeNodeCursor(adapter, root);\n\t// Because the root node in `stackTreeNodeCursor` is treated as the above detached fields node,\n\t// using it then just entering the correct field doesn't mess up the paths reported by the cursor.\n\tcursor.enterField(detachedFieldAsKey(detachedField));\n\treturn cursor;\n}\n\n/**\n * Provides functionality to allow a {@link stackTreeNodeCursor} and {@link stackTreeFieldCursor} to implement cursors.\n * @internal\n */\nexport interface CursorAdapter<TNode> {\n\t/**\n\t * @returns the value of the given node.\n\t */\n\tvalue(node: TNode): Value;\n\t/**\n\t * @returns the type of the given node.\n\t */\n\ttype(node: TNode): TreeType;\n\t/**\n\t * @returns the keys for non-empty fields on the given node.\n\t */\n\tkeysFromNode(node: TNode): readonly FieldKey[];\n\t/**\n\t * @returns the child nodes for the given node and key.\n\t */\n\tgetFieldFromNode(node: TNode, key: FieldKey): readonly TNode[];\n}\n\ntype SiblingsOrKey<TNode> = readonly TNode[] | readonly FieldKey[];\n\n/**\n * A class that satisfies part of the ITreeCursorSynchronous implementation.\n */\nexport abstract class SynchronousCursor {\n\tpublic readonly [CursorMarker] = true;\n\tpublic readonly pending = false;\n\n\tpublic skipPendingFields(): boolean {\n\t\treturn true;\n\t}\n}\n\n/**\n * A simple general purpose ITreeCursorSynchronous implementation.\n *\n * As this is a generic implementation, it's ability to optimize is limited.\n *\n * @privateRemarks\n * Note that TNode can be `null` (and we should support `undefined` as well),\n * so be careful using types like `TNode | undefined` and expressions like `TNode ??`.\n *\n * TODO:\n * 1. Unit tests for this.\n * 2. Support for cursors which are field cursors at the root.\n */\nclass StackCursor<TNode> extends SynchronousCursor implements CursorWithNode<TNode> {\n\tpublic readonly [CursorMarker] = true;\n\t/**\n\t * Might start at special root where fields are detached sequences.\n\t *\n\t * @param adapter - policy logic.\n\t * @param siblingStack - Stack of collections of siblings along the path through the tree:\n\t * does not include current level (which is stored in `siblings`).\n\t * Even levels in the stack (starting from 0) are sequences of nodes and odd levels\n\t * are for fields keys on a node.\n\t * @param indexStack - Stack of indices into the corresponding levels in `siblingStack`.\n\t * @param siblings - Siblings at the current level (not included in `siblingStack`).\n\t * @param index - Index into `siblings`.\n\t */\n\tpublic constructor(\n\t\tprivate readonly adapter: CursorAdapter<TNode>,\n\t\tprivate readonly siblingStack: SiblingsOrKey<TNode>[],\n\t\tprivate readonly indexStack: number[],\n\t\tprivate siblings: SiblingsOrKey<TNode>,\n\t\tprivate index: number,\n\t) {\n\t\tsuper();\n\t}\n\n\tpublic getFieldKey(): FieldKey {\n\t\t// assert(this.mode === CursorLocationType.Fields, \"must be in fields mode\");\n\t\treturn this.siblings[this.index] as FieldKey;\n\t}\n\n\tprivate getStackedFieldKey(height: number): FieldKey {\n\t\tassert(height % 2 === 1, 0x3b8 /* must field height */);\n\t\treturn this.siblingStack[height][this.indexStack[height]] as FieldKey;\n\t}\n\n\tprivate getStackedNodeIndex(height: number): number {\n\t\t// assert(height % 2 === 0, \"must be node height\");\n\t\treturn this.indexStack[height];\n\t}\n\n\tprivate getStackedNode(height: number): TNode {\n\t\tconst index = this.getStackedNodeIndex(height);\n\t\treturn (this.siblingStack[height] as readonly TNode[])[index];\n\t}\n\n\tpublic getFieldLength(): number {\n\t\t// assert(this.mode === CursorLocationType.Fields, \"must be in fields mode\");\n\t\treturn this.getField().length;\n\t}\n\n\tpublic enterNode(index: number): void {\n\t\t// assert(this.mode === CursorLocationType.Fields, \"must be in fields mode\");\n\t\tconst siblings = this.getField();\n\t\tassert(index in siblings, 0x405 /* child must exist at index */);\n\t\tthis.siblingStack.push(this.siblings);\n\t\tthis.indexStack.push(this.index);\n\t\tthis.index = index;\n\t\tthis.siblings = siblings;\n\t}\n\n\tpublic getPath(prefix?: PathRootPrefix): UpPath | undefined {\n\t\tassert(this.mode === CursorLocationType.Nodes, 0x3b9 /* must be in nodes mode */);\n\t\treturn this.getOffsetPath(0, prefix);\n\t}\n\n\tpublic getFieldPath(prefix?: PathRootPrefix): FieldUpPath {\n\t\tassert(this.mode === CursorLocationType.Fields, 0x449 /* must be in fields mode */);\n\t\treturn {\n\t\t\tfield:\n\t\t\t\tthis.indexStack.length === 1\n\t\t\t\t\t? prefix?.rootFieldOverride ?? this.getFieldKey()\n\t\t\t\t\t: this.getFieldKey(),\n\t\t\tparent: this.getOffsetPath(1, prefix),\n\t\t};\n\t}\n\n\tprivate getOffsetPath(offset: number, prefix: PathRootPrefix | undefined): UpPath | undefined {\n\t\t// It is more efficient to handle prefix directly in here rather than delegating to PrefixedPath.\n\n\t\tconst length = this.indexStack.length - offset;\n\t\tif (length === 0) {\n\t\t\treturn prefix?.parent; // At root\n\t\t}\n\n\t\tassert(length > 0, 0x44a /* invalid offset to above root */);\n\t\tassert(length % 2 === 0, 0x44b /* offset path must point to node not field */);\n\n\t\tconst getIndex = (height: number): number => {\n\t\t\tlet parentIndex: number =\n\t\t\t\theight === this.indexStack.length ? this.index : this.getStackedNodeIndex(height);\n\t\t\tif (prefix !== undefined && height === 2) {\n\t\t\t\tparentIndex += prefix.indexOffset ?? 0;\n\t\t\t}\n\t\t\treturn parentIndex;\n\t\t};\n\n\t\t// Perf Note:\n\t\t// This is O(depth) in tree.\n\t\t// If many different anchors are created, this could be optimized to amortize the costs.\n\t\t// For example, the cursor could cache UpPaths from the anchorSet when creating an anchor,\n\t\t// then reuse them as a starting point when making another.\n\t\t// Could cache this at one depth, and remember the depth.\n\t\t// When navigating up, adjust cached anchor if present.\n\n\t\tlet path: UpPath | undefined = prefix?.parent;\n\t\t// Skip top level, since root node in path is \"undefined\" and does not have a parent or index.\n\t\tfor (let height = 2; height <= length; height += 2) {\n\t\t\tconst fieldOverride = height === 2 ? prefix?.rootFieldOverride : undefined;\n\t\t\tpath = {\n\t\t\t\tparent: path,\n\t\t\t\tparentIndex: getIndex(height),\n\t\t\t\tparentField: fieldOverride ?? this.getStackedFieldKey(height - 1),\n\t\t\t};\n\t\t}\n\n\t\treturn path;\n\t}\n\n\tpublic fork(): StackCursor<TNode> {\n\t\t// Siblings arrays are not modified during navigation and do not need be be copied.\n\t\t// This allows this copy to be shallow, and `this.siblings` below to not be copied as all.\n\t\treturn new StackCursor<TNode>(\n\t\t\tthis.adapter,\n\t\t\t[...this.siblingStack],\n\t\t\t[...this.indexStack],\n\t\t\tthis.siblings,\n\t\t\tthis.index,\n\t\t);\n\t}\n\n\tpublic enterField(key: FieldKey): void {\n\t\t// assert(this.mode === CursorLocationType.Nodes, \"must be in nodes mode\");\n\t\tthis.siblingStack.push(this.siblings);\n\t\tthis.indexStack.push(this.index);\n\n\t\t// For fields, siblings are only used for key lookup and\n\t\t// nextField and which has arbitrary iteration order,\n\t\t// so making a array of just key here works.\n\t\t// This adds an allocation, so it's optimizing code simplicity and for the other use case (enumeration)\n\t\t// at the cost of an allocation here.\n\t\tthis.index = 0;\n\t\tthis.siblings = [key];\n\t}\n\n\tpublic get mode(): CursorLocationType {\n\t\treturn this.siblingStack.length % 2 === 0\n\t\t\t? CursorLocationType.Nodes\n\t\t\t: CursorLocationType.Fields;\n\t}\n\n\tpublic nextField(): boolean {\n\t\tthis.index += 1;\n\t\tif (this.index === (this.siblings as []).length) {\n\t\t\tthis.exitField();\n\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\tpublic firstField(): boolean {\n\t\t// assert(this.mode === CursorLocationType.Nodes, \"must be in nodes mode\");\n\t\tconst fields = this.adapter.keysFromNode(this.getNode());\n\t\tif (fields.length === 0) {\n\t\t\treturn false;\n\t\t}\n\n\t\tthis.siblingStack.push(this.siblings);\n\t\tthis.indexStack.push(this.index);\n\t\tthis.index = 0;\n\t\tthis.siblings = fields;\n\t\treturn true;\n\t}\n\n\tpublic seekNodes(offset: number): boolean {\n\t\t// assert(this.mode === CursorLocationType.Nodes, \"can only seekNodes when in Nodes\");\n\t\tthis.index += offset;\n\t\tif (this.index in this.siblings) {\n\t\t\treturn true;\n\t\t}\n\t\tthis.exitNode();\n\t\treturn false;\n\t}\n\n\tpublic firstNode(): boolean {\n\t\t// assert(this.mode === CursorLocationType.Fields, \"firstNode only allowed in fields mode\");\n\t\tconst nodes = this.getField();\n\t\tif (nodes.length === 0) {\n\t\t\treturn false;\n\t\t}\n\t\tthis.siblingStack.push(this.siblings);\n\t\tthis.indexStack.push(this.index);\n\t\tthis.index = 0;\n\t\tthis.siblings = nodes;\n\t\treturn true;\n\t}\n\n\tpublic nextNode(): boolean {\n\t\tassert(this.mode === CursorLocationType.Nodes, 0x406 /* can only nextNode when in Nodes */);\n\t\tthis.index++;\n\t\tif (this.index < (this.siblings as []).length) {\n\t\t\treturn true;\n\t\t}\n\t\tthis.exitNode();\n\t\treturn false;\n\t}\n\n\tpublic exitField(): void {\n\t\t// assert(this.mode === CursorLocationType.Fields, \"can only navigate up from field when in field\");\n\t\tthis.siblings = this.siblingStack.pop() ?? fail(\"Unexpected siblingStack.length\");\n\t\tthis.index = this.indexStack.pop() ?? fail(\"Unexpected indexStack.length\");\n\t}\n\n\tpublic exitNode(): void {\n\t\t// assert(this.mode === CursorLocationType.Nodes, \"can only navigate up from node when in node\");\n\t\tthis.siblings = this.siblingStack.pop() ?? fail(\"Unexpected siblingStack.length\");\n\t\tthis.index = this.indexStack.pop() ?? fail(\"Unexpected indexStack.length\");\n\t}\n\n\tpublic getNode(): TNode {\n\t\t// assert(this.mode === CursorLocationType.Nodes, \"can only get node when in node\");\n\t\treturn (this.siblings as TNode[])[this.index];\n\t}\n\n\tprivate getField(): readonly TNode[] {\n\t\t// assert(this.mode === CursorLocationType.Fields, \"can only get field when in fields\");\n\t\tconst parent = this.getStackedNode(this.indexStack.length - 1);\n\t\tconst key: FieldKey = this.getFieldKey();\n\t\tconst field = this.adapter.getFieldFromNode(parent, key);\n\t\treturn field;\n\t}\n\n\t/**\n\t * @returns the value of the current node\n\t */\n\tpublic get value(): Value {\n\t\treturn this.adapter.value(this.getNode());\n\t}\n\n\t/**\n\t * @returns the type of the current node\n\t */\n\tpublic get type(): TreeType {\n\t\treturn this.adapter.type(this.getNode());\n\t}\n\n\tpublic get fieldIndex(): number {\n\t\t// assert(this.mode === CursorLocationType.Nodes, \"can only node's index when in node\");\n\t\treturn this.index;\n\t}\n\n\tpublic get chunkStart(): number {\n\t\treturn this.fieldIndex;\n\t}\n\n\tpublic readonly chunkLength = 1;\n}\n\n/**\n * Apply `prefix` to `path`.\n * @internal\n */\nexport function prefixPath(\n\tprefix: PathRootPrefix | undefined,\n\tpath: UpPath | undefined,\n): UpPath | undefined {\n\tif (prefix === undefined) {\n\t\treturn path;\n\t}\n\tif (\n\t\tprefix.parent === undefined &&\n\t\tprefix.rootFieldOverride === undefined &&\n\t\t(prefix.indexOffset ?? 0) === 0\n\t) {\n\t\treturn path;\n\t}\n\treturn applyPrefix(prefix, path);\n}\n\n/**\n * Apply `prefix` to `path`.\n * @internal\n */\nexport function prefixFieldPath(\n\tprefix: PathRootPrefix | undefined,\n\tpath: FieldUpPath,\n): FieldUpPath {\n\tif (prefix === undefined) {\n\t\treturn path;\n\t}\n\tif (\n\t\tprefix.parent === undefined &&\n\t\tprefix.rootFieldOverride === undefined &&\n\t\t(prefix.indexOffset ?? 0) === 0\n\t) {\n\t\treturn path;\n\t}\n\treturn {\n\t\tfield: path.parent === undefined ? prefix.rootFieldOverride ?? path.field : path.field,\n\t\tparent: prefixPath(prefix, path.parent),\n\t};\n}\n\n/**\n * Compose two prefixes together.\n * `prefixFieldPath(root, prefixFieldPath(inner, path))` should be the same as `prefixFieldPath(prefixPathPrefix(root, inner), path))`\n *\n * TODO: tests for this.\n */\nexport function prefixPathPrefix(root: PathRootPrefix, inner: PathRootPrefix): PathRootPrefix {\n\tif (inner.parent !== undefined) {\n\t\tconst composedPrefix: PathRootPrefix = {\n\t\t\tparent: new PrefixedPath(root, inner.parent),\n\t\t\trootFieldOverride: inner.rootFieldOverride,\n\t\t\tindexOffset: inner.indexOffset,\n\t\t};\n\t\treturn composedPrefix;\n\t} else {\n\t\tconst composedPrefix: PathRootPrefix = {\n\t\t\tparent: root.parent,\n\t\t\trootFieldOverride: root.rootFieldOverride ?? inner.rootFieldOverride,\n\t\t\tindexOffset: (inner.indexOffset ?? 0) + (root.indexOffset ?? 0),\n\t\t};\n\t\treturn composedPrefix;\n\t}\n}\n\nfunction applyPrefix(prefix: PathRootPrefix, path: UpPath | undefined): UpPath | undefined {\n\tif (path === undefined) {\n\t\treturn prefix.parent;\n\t} else {\n\t\t// As an optimization, avoid double wrapping paths with multiple prefixes\n\t\tif (path instanceof PrefixedPath) {\n\t\t\tconst composedPrefix: PathRootPrefix = prefixPathPrefix(prefix, path.prefix);\n\t\t\treturn new PrefixedPath(composedPrefix, path.path);\n\t\t} else {\n\t\t\treturn new PrefixedPath(prefix, path);\n\t\t}\n\t}\n}\n\n/**\n * Wrapper around a path that adds a prefix to the root.\n *\n * Exported for testing: use `prefixPath` and `prefixFieldPath` to construct.\n */\nexport class PrefixedPath implements UpPath {\n\tpublic readonly parentField: FieldKey;\n\tpublic readonly parentIndex: number;\n\tpublic constructor(\n\t\tpublic readonly prefix: PathRootPrefix,\n\t\tpublic readonly path: UpPath,\n\t) {\n\t\tif (path.parent === undefined) {\n\t\t\tthis.parentField = prefix.rootFieldOverride ?? path.parentField;\n\t\t\tthis.parentIndex = path.parentIndex + (prefix.indexOffset ?? 0);\n\t\t} else {\n\t\t\tthis.parentField = path.parentField;\n\t\t\tthis.parentIndex = path.parentIndex;\n\t\t}\n\t}\n\tpublic get parent(): UpPath | undefined {\n\t\treturn applyPrefix(this.prefix, this.path.parent);\n\t}\n}\n"]}

package/dist/feature-libraries/treeTextCursor.d.ts

@@ -0,0 +1,62 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { JsonableTree, ITreeCursor, ITreeCursorSynchronous, IForestSubscription, DetachedField } from "../core";
+import { CursorAdapter } from "./treeCursorUtils";
+/**
+ * This module provides support for reading and writing a 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.
+ *
+ * TODO: Use placeholders.
+ * build / add operations should be able to include detached ranges instead of children directly.
+ * summaries should be able to reference unloaded chunks instead of having children directly.
+ * Leverage placeholders in the types below to accomplish this.
+ * Determine how this relates to Cursor: should cursor be generic over placeholder values?
+ * (Could use them for errors to allow non erroring cursors?)
+ *
+ * Note:
+ * Currently a lot of Tree's codebase is using json for serialization.
+ * Because putting json strings inside json works poorly (adds lots of escaping),
+ * for now this library actually outputs and inputs the Json compatible type JsonableTree
+ * rather than actual strings.
+ */
+/**
+ * Create a cursor, in `nodes` mode at the root of the provided tree.
+ *
+ * @returns an {@link ITreeCursorSynchronous} in nodes mode for a single {@link JsonableTree}.
+ * @remarks
+ * Do not confuse this with {@link JsonableTree} with the JSON domain:
+ * this takes in data in a specific format that is json compatible (except for FluidHandle values).
+ * That is distinct from treating arbitrary JSON data as a tree in the JSON domain.
+ * @internal
+ */
+export declare function cursorForJsonableTreeNode(root: JsonableTree): ITreeCursorSynchronous;
+/**
+ * @returns an {@link ITreeCursorSynchronous} in fields mode for a JsonableTree field.
+ */
+export declare function cursorForJsonableTreeField(trees: JsonableTree[], detachedField?: DetachedField): ITreeCursorSynchronous;
+export declare const adapter: CursorAdapter<JsonableTree>;
+/**
+ * Extract a JsonableTree from the contents of the given ITreeCursor's current node.
+ * @internal
+ */
+export declare function jsonableTreeFromCursor(cursor: ITreeCursor): JsonableTree;
+/**
+ * Extract a JsonableTree from the contents of the given ITreeCursor's current node.
+ */
+export declare function jsonableTreeFromFieldCursor(cursor: ITreeCursor): JsonableTree[];
+/**
+ * Copy forest content into a JsonableTree.
+ * @remarks
+ * This is not a time or memory efficient way to pass around forest content:
+ * its intended for debugging and testing purposes when forest content is needed in a human readable serializable format.
+ */
+export declare function jsonableTreeFromForest(forest: IForestSubscription): JsonableTree[];
+//# sourceMappingURL=treeTextCursor.d.ts.map

package/dist/feature-libraries/treeTextCursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeTextCursor.d.ts","sourceRoot":"","sources":["../../src/feature-libraries/treeTextCursor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAGN,YAAY,EACZ,WAAW,EAGX,sBAAsB,EAEtB,mBAAmB,EAGnB,aAAa,EAGb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,aAAa,EAA6C,MAAM,mBAAmB,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,sBAAsB,CAEpF;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACzC,KAAK,EAAE,YAAY,EAAE,EACrB,aAAa,GAAE,aAAyB,GACtC,sBAAsB,CAOxB;AAED,eAAO,MAAM,OAAO,EAAE,aAAa,CAAC,YAAY,CAK/C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAcxE;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,EAAE,CAG/E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,mBAAmB,GAAG,YAAY,EAAE,CAMlF"}

package/dist/feature-libraries/treeTextCursor.js

@@ -0,0 +1,104 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonableTreeFromForest = exports.jsonableTreeFromFieldCursor = exports.jsonableTreeFromCursor = exports.adapter = exports.cursorForJsonableTreeField = exports.cursorForJsonableTreeNode = void 0;
+const core_utils_1 = require("@fluidframework/core-utils");
+const core_1 = require("../core");
+const treeCursorUtils_1 = require("./treeCursorUtils");
+/**
+ * This module provides support for reading and writing a 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.
+ *
+ * TODO: Use placeholders.
+ * build / add operations should be able to include detached ranges instead of children directly.
+ * summaries should be able to reference unloaded chunks instead of having children directly.
+ * Leverage placeholders in the types below to accomplish this.
+ * Determine how this relates to Cursor: should cursor be generic over placeholder values?
+ * (Could use them for errors to allow non erroring cursors?)
+ *
+ * Note:
+ * Currently a lot of Tree's codebase is using json for serialization.
+ * Because putting json strings inside json works poorly (adds lots of escaping),
+ * for now this library actually outputs and inputs the Json compatible type JsonableTree
+ * rather than actual strings.
+ */
+/**
+ * Create a cursor, in `nodes` mode at the root of the provided tree.
+ *
+ * @returns an {@link ITreeCursorSynchronous} in nodes mode for a single {@link JsonableTree}.
+ * @remarks
+ * Do not confuse this with {@link JsonableTree} with the JSON domain:
+ * this takes in data in a specific format that is json compatible (except for FluidHandle values).
+ * That is distinct from treating arbitrary JSON data as a tree in the JSON domain.
+ * @internal
+ */
+function cursorForJsonableTreeNode(root) {
+    return (0, treeCursorUtils_1.stackTreeNodeCursor)(exports.adapter, root);
+}
+exports.cursorForJsonableTreeNode = cursorForJsonableTreeNode;
+/**
+ * @returns an {@link ITreeCursorSynchronous} in fields mode for a JsonableTree field.
+ */
+function cursorForJsonableTreeField(trees, detachedField = core_1.rootField) {
+    const key = (0, core_1.detachedFieldAsKey)(detachedField);
+    return (0, treeCursorUtils_1.stackTreeFieldCursor)(exports.adapter, { type: core_1.aboveRootPlaceholder, fields: { [key]: trees } }, detachedField);
+}
+exports.cursorForJsonableTreeField = cursorForJsonableTreeField;
+exports.adapter = {
+    value: (node) => node.value,
+    type: (node) => node.type,
+    keysFromNode: core_1.genericTreeKeys,
+    getFieldFromNode: (node, key) => (0, core_1.getGenericTreeField)(node, key, false),
+};
+/**
+ * Extract a JsonableTree from the contents of the given ITreeCursor's current node.
+ * @internal
+ */
+function jsonableTreeFromCursor(cursor) {
+    (0, core_utils_1.assert)(cursor.mode === 0 /* CursorLocationType.Nodes */, 0x3ba /* must start at node */);
+    const node = {
+        type: cursor.type,
+    };
+    // Normalize object by only including fields that are required.
+    if (cursor.value !== undefined) {
+        node.value = cursor.value;
+    }
+    for (let inFields = cursor.firstField(); inFields; inFields = cursor.nextField()) {
+        const field = (0, core_1.mapCursorField)(cursor, jsonableTreeFromCursor);
+        (0, core_1.setGenericTreeField)(node, cursor.getFieldKey(), field);
+    }
+    return node;
+}
+exports.jsonableTreeFromCursor = jsonableTreeFromCursor;
+/**
+ * Extract a JsonableTree from the contents of the given ITreeCursor's current node.
+ */
+function jsonableTreeFromFieldCursor(cursor) {
+    (0, core_utils_1.assert)(cursor.mode === 1 /* CursorLocationType.Fields */, 0x7ca /* must start at field */);
+    return (0, core_1.mapCursorField)(cursor, jsonableTreeFromCursor);
+}
+exports.jsonableTreeFromFieldCursor = jsonableTreeFromFieldCursor;
+/**
+ * Copy forest content into a JsonableTree.
+ * @remarks
+ * This is not a time or memory efficient way to pass around forest content:
+ * its intended for debugging and testing purposes when forest content is needed in a human readable serializable format.
+ */
+function jsonableTreeFromForest(forest) {
+    const readCursor = forest.allocateCursor();
+    (0, core_1.moveToDetachedField)(forest, readCursor);
+    const jsonable = jsonableTreeFromFieldCursor(readCursor);
+    readCursor.free();
+    return jsonable;
+}
+exports.jsonableTreeFromForest = jsonableTreeFromForest;
+//# sourceMappingURL=treeTextCursor.js.map

package/dist/feature-libraries/treeTextCursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeTextCursor.js","sourceRoot":"","sources":["../../src/feature-libraries/treeTextCursor.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,2DAAoD;AACpD,kCAeiB;AACjB,uDAA6F;AAE7F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;GASG;AACH,SAAgB,yBAAyB,CAAC,IAAkB;IAC3D,OAAO,IAAA,qCAAmB,EAAC,eAAO,EAAE,IAAI,CAAC,CAAC;AAC3C,CAAC;AAFD,8DAEC;AAED;;GAEG;AACH,SAAgB,0BAA0B,CACzC,KAAqB,EACrB,gBAA+B,gBAAS;IAExC,MAAM,GAAG,GAAG,IAAA,yBAAkB,EAAC,aAAa,CAAC,CAAC;IAC9C,OAAO,IAAA,sCAAoB,EAC1B,eAAO,EACP,EAAE,IAAI,EAAE,2BAAoB,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,EACxD,aAAa,CACb,CAAC;AACH,CAAC;AAVD,gEAUC;AAEY,QAAA,OAAO,GAAgC;IACnD,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI;IACzB,YAAY,EAAE,sBAAe;IAC7B,gBAAgB,EAAE,CAAC,IAAI,EAAE,GAAG,EAA2B,EAAE,CAAC,IAAA,0BAAmB,EAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;CAC/F,CAAC;AAEF;;;GAGG;AACH,SAAgB,sBAAsB,CAAC,MAAmB;IACzD,IAAA,mBAAM,EAAC,MAAM,CAAC,IAAI,qCAA6B,EAAE,KAAK,CAAC,wBAAwB,CAAC,CAAC;IACjF,MAAM,IAAI,GAAiB;QAC1B,IAAI,EAAE,MAAM,CAAC,IAAI;KACjB,CAAC;IACF,+DAA+D;IAC/D,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE;QAC/B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;KAC1B;IACD,KAAK,IAAI,QAAQ,GAAG,MAAM,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,SAAS,EAAE,EAAE;QACjF,MAAM,KAAK,GAAmB,IAAA,qBAAc,EAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;QAC7E,IAAA,0BAAmB,EAAC,IAAI,EAAE,MAAM,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;KACvD;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAdD,wDAcC;AAED;;GAEG;AACH,SAAgB,2BAA2B,CAAC,MAAmB;IAC9D,IAAA,mBAAM,EAAC,MAAM,CAAC,IAAI,sCAA8B,EAAE,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACnF,OAAO,IAAA,qBAAc,EAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AACvD,CAAC;AAHD,kEAGC;AAED;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,MAA2B;IACjE,MAAM,UAAU,GAAG,MAAM,CAAC,cAAc,EAAE,CAAC;IAC3C,IAAA,0BAAmB,EAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,2BAA2B,CAAC,UAAU,CAAC,CAAC;IACzD,UAAU,CAAC,IAAI,EAAE,CAAC;IAClB,OAAO,QAAQ,CAAC;AACjB,CAAC;AAND,wDAMC","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 {\n\tgenericTreeKeys,\n\tgetGenericTreeField,\n\tJsonableTree,\n\tITreeCursor,\n\tCursorLocationType,\n\tmapCursorField,\n\tITreeCursorSynchronous,\n\tsetGenericTreeField,\n\tIForestSubscription,\n\tmoveToDetachedField,\n\taboveRootPlaceholder,\n\tDetachedField,\n\trootField,\n\tdetachedFieldAsKey,\n} from \"../core\";\nimport { CursorAdapter, stackTreeFieldCursor, stackTreeNodeCursor } from \"./treeCursorUtils\";\n\n/**\n * This module provides support for reading and writing a human readable (and\n * 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 * TODO: Use placeholders.\n * build / add operations should be able to include detached ranges instead of children directly.\n * summaries should be able to reference unloaded chunks instead of having children directly.\n * Leverage placeholders in the types below to accomplish this.\n * Determine how this relates to Cursor: should cursor be generic over placeholder values?\n * (Could use them for errors to allow non erroring cursors?)\n *\n * Note:\n * Currently a lot of Tree's codebase is using json for serialization.\n * Because putting json strings inside json works poorly (adds lots of escaping),\n * for now this library actually outputs and inputs the Json compatible type JsonableTree\n * rather than actual strings.\n */\n\n/**\n * Create a cursor, in `nodes` mode at the root of the provided tree.\n *\n * @returns an {@link ITreeCursorSynchronous} in nodes mode for a single {@link JsonableTree}.\n * @remarks\n * Do not confuse this with {@link JsonableTree} with the JSON domain:\n * this takes in data in a specific format that is json compatible (except for FluidHandle values).\n * That is distinct from treating arbitrary JSON data as a tree in the JSON domain.\n * @internal\n */\nexport function cursorForJsonableTreeNode(root: JsonableTree): ITreeCursorSynchronous {\n\treturn stackTreeNodeCursor(adapter, root);\n}\n\n/**\n * @returns an {@link ITreeCursorSynchronous} in fields mode for a JsonableTree field.\n */\nexport function cursorForJsonableTreeField(\n\ttrees: JsonableTree[],\n\tdetachedField: DetachedField = rootField,\n): ITreeCursorSynchronous {\n\tconst key = detachedFieldAsKey(detachedField);\n\treturn stackTreeFieldCursor(\n\t\tadapter,\n\t\t{ type: aboveRootPlaceholder, fields: { [key]: trees } },\n\t\tdetachedField,\n\t);\n}\n\nexport const adapter: CursorAdapter<JsonableTree> = {\n\tvalue: (node) => node.value,\n\ttype: (node) => node.type,\n\tkeysFromNode: genericTreeKeys,\n\tgetFieldFromNode: (node, key): readonly JsonableTree[] => getGenericTreeField(node, key, false),\n};\n\n/**\n * Extract a JsonableTree from the contents of the given ITreeCursor's current node.\n * @internal\n */\nexport function jsonableTreeFromCursor(cursor: ITreeCursor): JsonableTree {\n\tassert(cursor.mode === CursorLocationType.Nodes, 0x3ba /* must start at node */);\n\tconst node: JsonableTree = {\n\t\ttype: cursor.type,\n\t};\n\t// Normalize object by only including fields that are required.\n\tif (cursor.value !== undefined) {\n\t\tnode.value = cursor.value;\n\t}\n\tfor (let inFields = cursor.firstField(); inFields; inFields = cursor.nextField()) {\n\t\tconst field: JsonableTree[] = mapCursorField(cursor, jsonableTreeFromCursor);\n\t\tsetGenericTreeField(node, cursor.getFieldKey(), field);\n\t}\n\treturn node;\n}\n\n/**\n * Extract a JsonableTree from the contents of the given ITreeCursor's current node.\n */\nexport function jsonableTreeFromFieldCursor(cursor: ITreeCursor): JsonableTree[] {\n\tassert(cursor.mode === CursorLocationType.Fields, 0x7ca /* must start at field */);\n\treturn mapCursorField(cursor, jsonableTreeFromCursor);\n}\n\n/**\n * Copy forest content into a JsonableTree.\n * @remarks\n * This is not a time or memory efficient way to pass around forest content:\n * its intended for debugging and testing purposes when forest content is needed in a human readable serializable format.\n */\nexport function jsonableTreeFromForest(forest: IForestSubscription): JsonableTree[] {\n\tconst readCursor = forest.allocateCursor();\n\tmoveToDetachedField(forest, readCursor);\n\tconst jsonable = jsonableTreeFromFieldCursor(readCursor);\n\treadCursor.free();\n\treturn jsonable;\n}\n"]}