@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/core/tree/cursor.js

@@ -0,0 +1,169 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inCursorNode = exports.inCursorField = exports.castCursorToSynchronous = exports.forEachNodeInSubtree = exports.forEachNode = exports.iterateCursorField = exports.mapCursorField = exports.forEachField = exports.mapCursorFields = exports.CursorLocationType = exports.isCursor = exports.CursorMarker = void 0;
+const core_utils_1 = require("@fluidframework/core-utils");
+/**
+ * A symbol for marking an object as an {@link ITreeCursor}.
+ *
+ * Useful when APIs want to take in tree data in multiple formats, including cursors.
+ */
+exports.CursorMarker = Symbol("CursorMarker");
+/**
+ * Check if something is an {@link ITreeCursor}.
+ *
+ * Useful when APIs want to take in tree data in multiple formats, including cursors.
+ */
+function isCursor(data) {
+    // Other than on null and undefined, looking up a missing symbol shouldn't type error.
+    // typeof check deals with undefined while providing an early out for other non-object types.
+    return data !== null && typeof data === "object" && data[exports.CursorMarker] === true;
+}
+exports.isCursor = isCursor;
+/**
+ * @internal
+ */
+var CursorLocationType;
+(function (CursorLocationType) {
+    /**
+     * Can iterate through nodes in a field.
+     * At a "current node".
+     */
+    CursorLocationType[CursorLocationType["Nodes"] = 0] = "Nodes";
+    /**
+     * Can iterate through fields of a node.
+     * At a "current field".
+     */
+    CursorLocationType[CursorLocationType["Fields"] = 1] = "Fields";
+})(CursorLocationType || (exports.CursorLocationType = CursorLocationType = {}));
+/**
+ * @param cursor - tree whose fields will be visited.
+ * @param f - builds output from field, which will be selected in cursor when cursor is provided.
+ * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.
+ * @returns array resulting from applying `f` to each field of the current node on `cursor`.
+ * Returns an empty array if the node is empty or not present (which are considered the same).
+ * Note that order is not specified for field iteration.
+ */
+function mapCursorFields(cursor, f) {
+    const output = [];
+    forEachField(cursor, (c) => {
+        output.push(f(c));
+    });
+    return output;
+}
+exports.mapCursorFields = mapCursorFields;
+/**
+ * @param cursor - cursor at a node whose fields will be visited.
+ * @param f - For on each field.
+ * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.
+ */
+function forEachField(cursor, f) {
+    (0, core_utils_1.assert)(cursor.mode === 0 /* CursorLocationType.Nodes */, 0x411 /* should be in nodes */);
+    for (let inField = cursor.firstField(); inField; inField = cursor.nextField()) {
+        f(cursor);
+    }
+}
+exports.forEachField = forEachField;
+/**
+ * @param cursor - tree whose field will be visited.
+ * @param f - builds output from field member, which will be selected in cursor when cursor is provided.
+ * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.
+ * @returns array resulting from applying `f` to each item of the current field on `cursor`.
+ * Returns an empty array if the field is empty or not present (which are considered the same).
+ */
+function mapCursorField(cursor, f) {
+    const output = [];
+    forEachNode(cursor, (c) => {
+        output.push(f(c));
+    });
+    return output;
+}
+exports.mapCursorField = mapCursorField;
+/**
+ * @param cursor - The tree whose field will be visited.
+ * @param f - Builds output from field member, which will be selected in cursor when cursor is provided.
+ * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.
+ * @returns An iterable of `T` resulting from applying `f` to each item of the current field on `cursor`.
+ * Yields nothing if an empty array if the field is empty or not present (which are considered the same).
+ */
+function* iterateCursorField(cursor, f) {
+    (0, core_utils_1.assert)(cursor.mode === 1 /* CursorLocationType.Fields */, 0x7a8 /* should be in fields */);
+    for (let inNodes = cursor.firstNode(); inNodes; inNodes = cursor.nextNode()) {
+        yield f(cursor);
+    }
+}
+exports.iterateCursorField = iterateCursorField;
+/**
+ * @param cursor - cursor at a field whose nodes will be visited.
+ * @param f - For on each node.
+ * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.
+ */
+function forEachNode(cursor, f) {
+    (0, core_utils_1.assert)(cursor.mode === 1 /* CursorLocationType.Fields */, 0x3bd /* should be in fields */);
+    for (let inNodes = cursor.firstNode(); inNodes; inNodes = cursor.nextNode()) {
+        f(cursor);
+    }
+}
+exports.forEachNode = forEachNode;
+/**
+ * @param cursor - cursor at a field or node.
+ * @param f - Function to invoke for each node.
+ * If `f` moves the cursor, it must put it back to where it was at the beginning of `f` before returning.
+ *
+ * Invokes `f` on each node in the subtree rooted at the current field or node.
+ * Traversal is pre-order.
+ * If the cursor is at a node, `f` will be invoked on that node.
+ *
+ * Returns the `cursor` to its initial position.
+ */
+function forEachNodeInSubtree(cursor, f) {
+    if (cursor.mode === 0 /* CursorLocationType.Nodes */) {
+        f(cursor);
+        forEachField(cursor, (c) => forEachNodeInSubtree(c, f));
+    }
+    else {
+        forEachNode(cursor, (c) => forEachNodeInSubtree(c, f));
+    }
+}
+exports.forEachNodeInSubtree = forEachNodeInSubtree;
+/**
+ * Casts a cursor to an {@link ITreeCursorSynchronous}.
+ *
+ * TODO: #1404: Handle this properly for partial data loading support.
+ */
+function castCursorToSynchronous(cursor) {
+    return cursor;
+}
+exports.castCursorToSynchronous = castCursorToSynchronous;
+/**
+ * Runs `f` inside of field `field` on `cursor`.
+ * @param cursor - Cursor whose field to enter and exit. Must be in `nodes` mode.
+ * @param field - Field to enter.
+ * @param f - Callback to run when in field.
+ * @returns return value of `f`
+ */
+function inCursorField(cursor, field, f) {
+    cursor.enterField(field);
+    const result = f(cursor);
+    cursor.exitField();
+    return result;
+}
+exports.inCursorField = inCursorField;
+/**
+ * Runs `f` inside of node `index` on `cursor`.
+ * @param cursor - Cursor whoso node to enter and exit. Must be in `fields` mode.
+ * @param index - Node to enter.
+ * @param f - Callback to run when in node.
+ * @returns return value of `f`
+ */
+function inCursorNode(cursor, index, f) {
+    cursor.enterNode(index);
+    const result = f(cursor);
+    cursor.exitNode();
+    return result;
+}
+exports.inCursorNode = inCursorNode;
+//# sourceMappingURL=cursor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../src/core/tree/cursor.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 { FieldUpPath, UpPath } from \"./pathTree\";\nimport { TreeType, Value } from \"./types\";\n\n/**\n * A symbol for marking an object as an {@link ITreeCursor}.\n *\n * Useful when APIs want to take in tree data in multiple formats, including cursors.\n */\nexport const CursorMarker: unique symbol = Symbol(\"CursorMarker\");\n\n/**\n * Check if something is an {@link ITreeCursor}.\n *\n * Useful when APIs want to take in tree data in multiple formats, including cursors.\n */\nexport function isCursor(data: unknown): data is ITreeCursor {\n\t// Other than on null and undefined, looking up a missing symbol shouldn't type error.\n\t// typeof check deals with undefined while providing an early out for other non-object types.\n\treturn data !== null && typeof data === \"object\" && (data as any)[CursorMarker] === true;\n}\n\n/**\n * A stateful low-level interface for reading tree data.\n * @internal\n *\n * @remarks Cursor exists so that specialized data formats can be viewed through\n * a common abstraction. This allows performance optimizations to be done based\n * on data.\n *\n * A tree cursor is similar to a database cursor in that it allows for the efficient\n * traversal over the contents of a tree. Note that unlike a database cursor,\n * tree cursors may be invalidated after any edit to the tree. For a cursor-like\n * structure that also remains valid across edits, see {@link AnchorNode}.\n */\nexport interface ITreeCursor {\n\t/**\n\t * Marks this object as a cursor.\n\t */\n\treadonly [CursorMarker]: true;\n\n\t/**\n\t * What kind of place the cursor is at.\n\t * Determines which operations are allowed.\n\t *\n\t * @remarks\n\t * Users of cursors frequently need to refer to places in trees, both fields and nodes.\n\t * Approaches other than having the cursor have separate modes for these\n\t * cases had issues even worse than having the two modes.\n\t *\n\t * For example, modeling fields as parent + key has issues when there is no\n\t * parent, and doesn't provide a great way to do iteration over fields while\n\t * also having a nice API and making it easy for the implementation to track\n\t * state (like its current location inside a sequence tree of fields) while\n\t * traversing without having to allocate some state management for that.\n\t *\n\t * Another approach, of using arrays of cursors for fields (like we currently\n\t * do for inserting content) is very inefficient and better addressed by a\n\t * dual mode cursor.\n\t *\n\t * Another approach, of using the first node in a field when referring to\n\t * the field gets confusing since it's unclear if a given cursor means that\n\t * node, or that node, and the ones after it, and in the second case, it's\n\t * hard to restore the cursor back to the right state when returning. It also\n\t * doesn't work for empty fields. Overall there just didn't seem to be a way\n\t * that sucked less than the dual mode API.\n\t */\n\treadonly mode: CursorLocationType;\n\n\t/*\n\t * True iff the current field or node (depending on mode) is \"pending\",\n\t * meaning that it has not been downloaded.\n\t */\n\treadonly pending: boolean;\n\n\t// ********** APIs for when mode = Fields ********** //\n\n\t/**\n\t * Moves the \"current field\" forward one in an arbitrary field traversal order,\n\t * skipping any empty fields.\n\t *\n\t * If there is no remaining field to iterate to,\n\t * returns false and navigates up to the parent setting the mode to `Nodes`.\n\t *\n\t * Order of fields is only guaranteed to be consistent through a single iteration.\n\t *\n\t * If skipPending, skip past fields which are currently pending.\n\t * This can be used to skip to the end of a large number of consecutive pending fields.\n\t *\n\t * Allowed when `mode` is `Fields`.\n\t */\n\tnextField(): boolean;\n\n\t/**\n\t * Navigate up to parent node.\n\t * Sets mode to `Nodes`\n\t *\n\t * Only valid when `mode` is `Fields`.\n\t *\n\t * TODO: what to do if at root?\n\t */\n\texitField(): void;\n\n\t/**\n\t * Moves the \"current field\" forward until `pending` is `false`.\n\t *\n\t * If there are no remaining field to iterate to,\n\t * returns false and navigates up to the parent setting the mode to `Nodes`.\n\t *\n\t * Order of fields is only guaranteed to be consistent through a single iteration.\n\t *\n\t * Allowed when `mode` is `Fields`.\n\t */\n\tskipPendingFields(): boolean;\n\n\t// ********** APIs for when mode = Fields, and not pending ********** //\n\n\t/**\n\t * Returns the FieldKey for the current field.\n\t *\n\t * Allowed when `mode` is `Fields`, and not `pending`.\n\t */\n\tgetFieldKey(): FieldKey;\n\n\t/**\n\t * @returns the number of immediate children in the current field.\n\t *\n\t * Allowed when `mode` is `Fields`, and not `pending`.\n\t */\n\tgetFieldLength(): number;\n\n\t/**\n\t * Moves to the first node of the selected field, setting mode to `Nodes`.\n\t *\n\t * If field is empty, returns false instead.\n\t *\n\t * Allowed when `mode` is `Fields`, and not `pending`.\n\t */\n\tfirstNode(): boolean;\n\n\t/**\n\t * Sets current node to the node at the provided `index` of the current field.\n\t *\n\t * Allowed when `mode` is `Fields`, and not `pending`.\n\t * Sets mode to `Nodes`.\n\t */\n\tenterNode(childIndex: number): void;\n\n\t/**\n\t * Returns a path to the current field. See {@link FieldUpPath}.\n\t *\n\t * Only valid when `mode` is `Fields`.\n\t *\n\t * If no prefix is provided, assumes this cursor is treated as if it has a root node where its field keys are actually detached sequences.\n\t * If the cursor is not rooted at such a node, the `prefix` should be used to ensure the path has the correct root.\n\t * This requirement exists because {@link FieldUpPath}s are absolute paths\n\t * and thus must be rooted in a detached sequence.\n\t *\n\t * @param prefix - optional overrides to apply to the root of the returned path.\n\t * See {@link PathRootPrefix}.\n\t * This adjusts the path as if the tree data accessible to this cursor is part of a larger tree.\n\t *\n\t * @returns a path to the current field.\n\t */\n\tgetFieldPath(prefix?: PathRootPrefix): FieldUpPath;\n\n\t// ********** APIs for when mode = Nodes ********** //\n\n\t/**\n\t * Returns a path to the current node. See {@link UpPath}.\n\t *\n\t * Only valid when `mode` is `Nodes`.\n\t *\n\t * If no prefix is provided, assumes this cursor is treated as if it has a root node where its field keys are actually detached sequences.\n\t * If the cursor is not rooted at such a node, the `prefix` should be used to ensure the path has the correct root.\n\t * This requirement exists because {@link UpPath}s are absolute paths\n\t * and thus must be rooted in a detached sequence.\n\t *\n\t * @param prefix - optional overrides to apply to the root of the returned path.\n\t * See {@link PathRootPrefix}.\n\t * This adjusts the path as if the tree data accessible to this cursor is part of a larger tree.\n\t *\n\t * @returns a path to the current node.\n\t */\n\tgetPath(prefix?: PathRootPrefix): UpPath | undefined;\n\n\t/**\n\t * Index (within its parent field) of the current node.\n\t *\n\t * Only valid when `mode` is `Nodes`.\n\t */\n\treadonly fieldIndex: number;\n\n\t/**\n\t * Index (within its parent field) of the first node in the current chunk.\n\t * Always less than or equal to `currentIndexInField`.\n\t *\n\t * Only valid when `mode` is `Nodes`.\n\t */\n\treadonly chunkStart: number;\n\n\t/**\n\t * Length of current chunk.\n\t * Since an entire chunk always has the same `pending` value,\n\t * can be used to help skip over all of a pending chunk at once.\n\t *\n\t * TODO:\n\t * Add optional APIs to access underlying chunks so readers can\n\t * accelerate processing of chunk formats they understand.\n\t *\n\t * Only valid when `mode` is `Nodes`.\n\t */\n\treadonly chunkLength: number;\n\n\t/**\n\t * Moves `offset` nodes in the field.\n\t * If seeking to exactly past either end,\n\t * returns false and navigates up to the parent field (setting mode to `Fields`).\n\t *\n\t * Allowed if mode is `Nodes`.\n\t */\n\tseekNodes(offset: number): boolean;\n\n\t/**\n\t * The same as `seekNodes(1)`, but might be faster.\n\t */\n\tnextNode(): boolean;\n\n\t/**\n\t * Navigate up to parent field.\n\t * Sets mode to `Fields`\n\t *\n\t * Same as seek Number.POSITIVE_INFINITY, but only valid when `mode` is `Nodes`.\n\t *\n\t * TODO: what to do if at root?\n\t * TODO: Maybe merge with upToNode to make a single \"Up\"?\n\t */\n\texitNode(): void;\n\n\t// ********** APIs for when mode = Nodes and not pending ********** //\n\n\t/**\n\t * Enters the first non-empty field (setting mode to `Fields`)\n\t * so fields can be iterated with `nextField` and `skipPendingFields`.\n\t *\n\t * If there are no fields, mode is returned to `Nodes` and false is returned.\n\t *\n\t * Allowed when `mode` is `Nodes` and not `pending`.\n\t */\n\tfirstField(): boolean;\n\n\t/**\n\t * Navigate to the field with the specified `key` and set the mode to `Fields`.\n\t *\n\t * Only valid when `mode` is `Nodes`, and not `pending`.\n\t */\n\tenterField(key: FieldKey): void;\n\n\t/**\n\t * The type of the currently selected node.\n\t *\n\t * Only valid when `mode` is `Nodes`, and not `pending`.\n\t */\n\treadonly type: TreeType;\n\n\t/**\n\t * The value associated with the currently selected node.\n\t *\n\t * Only valid when `mode` is `Nodes`, and not `pending`.\n\t */\n\treadonly value: Value;\n}\n\n/**\n * Prefix to apply as the root of a {@link UpPath} or {@link FieldUpPath}.\n *\n * @remarks This can be used to take a path relative to a subtree, and make it relative to a larger containing tree.\n * For example, if a node is being inserted in the 5th position in a field \"Foo\", you can update a path in that node's subtree to its new path by prefixing it with\n * `{ parent: theNodeAboveTheMovedNode, rootFieldOverride: Foo, indexOffset: 5 }`.\n * See {@link prefixPath} and {@link prefixFieldPath} for how to apply the prefix to the paths.\n * @internal\n */\nexport interface PathRootPrefix {\n\t/**\n\t * The new parent to place above root of the path which is being prefixed.\n\t * This replaces the `undefined` at the root of the path.\n\t *\n\t * @remarks specifying `undefined` here results in no change to the path.\n\t */\n\tparent?: UpPath | undefined;\n\n\t/**\n\t * The field of `parent` that the original path will be included under.\n\t *\n\t * If `undefined` the root field key from the original path will be used.\n\t */\n\trootFieldOverride?: FieldKey;\n\n\t/**\n\t * Offset to add to the uppermost `parentIndex` in the original path.\n\t */\n\tindexOffset?: number;\n}\n\n/**\n * @internal\n */\nexport const enum CursorLocationType {\n\t/**\n\t * Can iterate through nodes in a field.\n\t * At a \"current node\".\n\t */\n\tNodes,\n\n\t/**\n\t * Can iterate through fields of a node.\n\t * At a \"current field\".\n\t */\n\tFields,\n}\n\n/**\n * {@link ITreeCursor} that is never pending.\n * @internal\n */\nexport interface ITreeCursorSynchronous extends ITreeCursor {\n\treadonly pending: false;\n}\n\n/**\n * @param cursor - tree whose fields will be visited.\n * @param f - builds output from field, which will be selected in cursor when cursor is provided.\n * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.\n * @returns array resulting from applying `f` to each field of the current node on `cursor`.\n * Returns an empty array if the node is empty or not present (which are considered the same).\n * Note that order is not specified for field iteration.\n */\nexport function mapCursorFields<T, TCursor extends ITreeCursor = ITreeCursor>(\n\tcursor: TCursor,\n\tf: (cursor: TCursor) => T,\n): T[] {\n\tconst output: T[] = [];\n\tforEachField(cursor, (c) => {\n\t\toutput.push(f(c));\n\t});\n\treturn output;\n}\n\n/**\n * @param cursor - cursor at a node whose fields will be visited.\n * @param f - For on each field.\n * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.\n */\nexport function forEachField<TCursor extends ITreeCursor = ITreeCursor>(\n\tcursor: TCursor,\n\tf: (cursor: TCursor) => void,\n): void {\n\tassert(cursor.mode === CursorLocationType.Nodes, 0x411 /* should be in nodes */);\n\tfor (let inField = cursor.firstField(); inField; inField = cursor.nextField()) {\n\t\tf(cursor);\n\t}\n}\n\n/**\n * @param cursor - tree whose field will be visited.\n * @param f - builds output from field member, which will be selected in cursor when cursor is provided.\n * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.\n * @returns array resulting from applying `f` to each item of the current field on `cursor`.\n * Returns an empty array if the field is empty or not present (which are considered the same).\n */\nexport function mapCursorField<T, TCursor extends ITreeCursor = ITreeCursor>(\n\tcursor: TCursor,\n\tf: (cursor: TCursor) => T,\n): T[] {\n\tconst output: T[] = [];\n\tforEachNode(cursor, (c) => {\n\t\toutput.push(f(c));\n\t});\n\treturn output;\n}\n\n/**\n * @param cursor - The tree whose field will be visited.\n * @param f - Builds output from field member, which will be selected in cursor when cursor is provided.\n * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.\n * @returns An iterable of `T` resulting from applying `f` to each item of the current field on `cursor`.\n * Yields nothing if an empty array if the field is empty or not present (which are considered the same).\n */\nexport function* iterateCursorField<T, TCursor extends ITreeCursor = ITreeCursor>(\n\tcursor: TCursor,\n\tf: (cursor: TCursor) => T,\n): IterableIterator<T> {\n\tassert(cursor.mode === CursorLocationType.Fields, 0x7a8 /* should be in fields */);\n\tfor (let inNodes = cursor.firstNode(); inNodes; inNodes = cursor.nextNode()) {\n\t\tyield f(cursor);\n\t}\n}\n\n/**\n * @param cursor - cursor at a field whose nodes will be visited.\n * @param f - For on each node.\n * If `f` moves cursor, it must put it back to where it was at the beginning of `f` before returning.\n */\nexport function forEachNode<TCursor extends ITreeCursor = ITreeCursor>(\n\tcursor: TCursor,\n\tf: (cursor: TCursor) => void,\n): void {\n\tassert(cursor.mode === CursorLocationType.Fields, 0x3bd /* should be in fields */);\n\tfor (let inNodes = cursor.firstNode(); inNodes; inNodes = cursor.nextNode()) {\n\t\tf(cursor);\n\t}\n}\n\n/**\n * @param cursor - cursor at a field or node.\n * @param f - Function to invoke for each node.\n * If `f` moves the cursor, it must put it back to where it was at the beginning of `f` before returning.\n *\n * Invokes `f` on each node in the subtree rooted at the current field or node.\n * Traversal is pre-order.\n * If the cursor is at a node, `f` will be invoked on that node.\n *\n * Returns the `cursor` to its initial position.\n */\nexport function forEachNodeInSubtree<TCursor extends ITreeCursor = ITreeCursor>(\n\tcursor: TCursor,\n\tf: (cursor: TCursor) => void,\n): void {\n\tif (cursor.mode === CursorLocationType.Nodes) {\n\t\tf(cursor);\n\t\tforEachField(cursor, (c) => forEachNodeInSubtree(c, f));\n\t} else {\n\t\tforEachNode(cursor, (c) => forEachNodeInSubtree(c, f));\n\t}\n}\n\n/**\n * Casts a cursor to an {@link ITreeCursorSynchronous}.\n *\n * TODO: #1404: Handle this properly for partial data loading support.\n */\nexport function castCursorToSynchronous(cursor: ITreeCursor): ITreeCursorSynchronous {\n\treturn cursor as ITreeCursorSynchronous;\n}\n\n/**\n * Runs `f` inside of field `field` on `cursor`.\n * @param cursor - Cursor whose field to enter and exit. Must be in `nodes` mode.\n * @param field - Field to enter.\n * @param f - Callback to run when in field.\n * @returns return value of `f`\n */\nexport function inCursorField<T, TCursor extends ITreeCursor = ITreeCursor>(\n\tcursor: TCursor,\n\tfield: FieldKey,\n\tf: (cursor: TCursor) => T,\n): T {\n\tcursor.enterField(field);\n\tconst result = f(cursor);\n\tcursor.exitField();\n\treturn result;\n}\n\n/**\n * Runs `f` inside of node `index` on `cursor`.\n * @param cursor - Cursor whoso node to enter and exit. Must be in `fields` mode.\n * @param index - Node to enter.\n * @param f - Callback to run when in node.\n * @returns return value of `f`\n */\nexport function inCursorNode<T, TCursor extends ITreeCursor = ITreeCursor>(\n\tcursor: TCursor,\n\tindex: number,\n\tf: (cursor: TCursor) => T,\n): T {\n\tcursor.enterNode(index);\n\tconst result = f(cursor);\n\tcursor.exitNode();\n\treturn result;\n}\n"]}

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

@@ -0,0 +1,241 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { FieldKey } from "../schema-stored";
+import { ITreeCursorSynchronous } from "./cursor";
+/**
+ * This format describes changes that must be applied to a forest in order to update it.
+ * Instances of this format are generated based on incoming changesets and consumed by a view layer (e.g., Forest) to
+ * update itself.
+ *
+ * Because this format is only meant for updating document state, it does not fully represent user intentions.
+ * For example, if some concurrent edits A and B insert content at the same location, then a Delta that represents
+ * represents the state update for edit A would not include information that allows B's insertion to be ordered
+ * relative to A's insertion. This format is therefore not fit to be rebased in the face of concurrent changes.
+ * Instead this format is used to describe the end product of rebasing user intentions over concurrent edits.
+ *
+ * This format is self-contained in the following ways:
+ *
+ * 1. It uses integer indices (offsets, technically) to describe the locations of necessary changes.
+ * As such, it does not rely on document nodes being accessible/locatable by ID.
+ *
+ * 2. This format does not require historical information in order to apply the changes it describes.
+ * For example, if a user undoes the deletion of a subtree, then the Delta generated for the undo edit will contain all
+ * information necessary to restore that subtree.
+ *
+ * This format can be generated from any Changeset without having access to the current document state.
+ *
+ * This format is meant to serve as the lowest common denominator to represent state changes resulting from any kind
+ * of operation on any kind of field.
+ * This means all such operations must be expressible in terms of this format.
+ *
+ * Within the above design constrains, this format is designed with the following goals in mind:
+ *
+ * 1. Make it easy to walk both a document tree and the delta tree to apply the changes described in the delta
+ * with a minimum amount of backtracking over the contents of the tree.
+ * This a boon for both code simplicity and performance.
+ *
+ * 2. Make the format terse.
+ *
+ * 3. Make the format uniform.
+ *
+ * These goals are reflected in the following design choices (this is very much optional reading for users of this
+ * format):
+ *
+ * 1. All marks that apply to field elements are represented in a single linear structure where marks that affect later
+ * elements of the document field appear after marks that affect earlier elements of the document field.
+ *
+ * If the marks were not ordered in this fashion then a consumer would need to backtrack within the document field.
+ *
+ * If the marks were represented in multiple such linear structures then it would be necessary to either:
+ * - backtrack when iterating over one structure fully, then the next
+ * - maintain a pointer within each such linear structure and advance them in lock-step (like in a k-way merge-sort but
+ * more fiddly because of the offsets).
+ *
+ * 2. Nested changes are not inlined within `ProtoNode`s.
+ *
+ * Inlining them would force the consuming code to detect such changes within the `ProtoNode` and handle them
+ * within the context of the content creation.
+ * This would be cumbersome because either the code that is responsible for consuming the `ProtoNode` would need to
+ * be aware of and have the context to handle such changes, or some caller of that code would need to find and extract such
+ * change information ahead to calling that code.
+ */
+/**
+ * Represents the change made to a document.
+ * Immutable, therefore safe to retain for async processing.
+ * @internal
+ */
+export interface Root<TTree = ProtoNode> {
+    /**
+     * Changes to apply to the root fields.
+     */
+    readonly fields?: FieldMap<TTree>;
+    /**
+     * New detached nodes to be constructed.
+     * The ordering has no significance.
+     *
+     * Build instructions for a root that is undergoing a rename should be listed under the starting name.
+     * For example, if one wishes to build a tree which is being renamed from ID A to ID B,
+     * then the build should be listed under ID A.
+     */
+    readonly build?: readonly DetachedNodeBuild<TTree>[];
+    /**
+     * New detached nodes to be destroyed.
+     * The ordering has no significance.
+     *
+     * Destruction instructions for a root that is undergoing a rename should be listed under the final name.
+     * For example, if one wishes to destroy a tree which is being renamed from ID A to ID B,
+     * then the destruction should be listed under ID B.
+     */
+    readonly destroy?: readonly DetachedNodeDestruction[];
+}
+/**
+ * The default representation for inserted content.
+ *
+ * TODO:
+ * Ownership and lifetime of data referenced by this cursor is unclear,
+ * so it is a poor abstraction for this use-case which needs to hold onto the data in a non-exclusive (readonly) way.
+ * Cursors can be one supported way to input data, but aren't a good storage format.
+ * @internal
+ */
+export type ProtoNode = ITreeCursorSynchronous;
+/**
+ * The default representation a chunk (sub-sequence) of inserted content.
+ *
+ * TODO:
+ * See issue TODO with ProtoNode.
+ * Additionally, Cursors support sequences, so if using cursors, there are better ways to handle this than an array of cursors,
+ * like using a cursor over all the content (starting in fields mode).
+ * Long term something like TreeChunk should probably be used here.
+ * @internal
+ */
+export type ProtoNodes = readonly ProtoNode[];
+/**
+ * Represents a change being made to a part of the document tree.
+ * @internal
+ */
+export interface Mark<TTree = ProtoNode> {
+    /**
+     * The number of nodes affected.
+     * When `isAttachMark(mark)` is true, this is the number of new nodes being attached.
+     * When `isAttachMark(mark)` is false, this the number of existing nodes affected.
+     * Must be 1 when `fields` is populated.
+     */
+    readonly count: number;
+    /**
+     * Modifications to the pre-existing content.
+     * Must be undefined when `attach` is set but `detach` is not.
+     */
+    readonly fields?: FieldMap<TTree>;
+    /**
+     * When set, indicates that some pre-existing content is being detached and sent to the given detached field.
+     */
+    readonly detach?: DetachedNodeId;
+    /**
+     * When set, indicates that some content is being attached from the given detached field.
+     */
+    readonly attach?: DetachedNodeId;
+}
+/**
+ * A globally unique ID for a node in a detached field.
+ * @internal
+ */
+export interface DetachedNodeId {
+    readonly major?: string | number;
+    readonly minor: number;
+}
+/**
+ * @internal
+ */
+export type FieldMap<TTree = ProtoNode> = ReadonlyMap<FieldKey, FieldChanges<TTree>>;
+/**
+ * Represents changes made to a detached node
+ * @internal
+ */
+export interface DetachedNodeChanges<TTree = ProtoNode> {
+    readonly id: DetachedNodeId;
+    readonly fields: FieldMap<TTree>;
+}
+/**
+ * Represents the creation of detached nodes.
+ *
+ * Tree creation is idempotent: if a tree with the same ID already exists,
+ * then this build is ignored in favor of the existing tree.
+ * @internal
+ */
+export interface DetachedNodeBuild<TTree = ProtoNode> {
+    readonly id: DetachedNodeId;
+    readonly trees: readonly TTree[];
+}
+/**
+ * Represents the destruction of detached nodes
+ * @internal
+ */
+export interface DetachedNodeDestruction {
+    readonly id: DetachedNodeId;
+    readonly count: number;
+}
+/**
+ * Represents a detached node being assigned a new `DetachedNodeId`.
+ * @internal
+ */
+export interface DetachedNodeRename {
+    readonly count: number;
+    readonly oldId: DetachedNodeId;
+    readonly newId: DetachedNodeId;
+}
+/**
+ * Represents the changes to perform on a given field.
+ * @internal
+ */
+export interface FieldChanges<TTree = ProtoNode> {
+    /**
+     * Represents a list of changes to the nodes in the field.
+     * The index of each mark within the range of nodes, before
+     * applying any of the changes, is not represented explicitly.
+     * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.
+     */
+    readonly local?: readonly Mark<TTree>[];
+    /**
+     * Changes to apply to detached nodes.
+     * The ordering has no significance.
+     *
+     * Nested changes for a root that is undergoing a rename should be listed under the starting name.
+     * For example, if one wishes to change a tree which is being renamed from ID A to ID B,
+     * then the changes should be listed under ID A.
+     */
+    readonly global?: readonly DetachedNodeChanges<TTree>[];
+    /**
+     * New detached nodes to be constructed.
+     * The ordering has no significance.
+     *
+     * @deprecated - Builds should be set at the root.
+     * TODO:6308 migrate all reader/writers away from this and remove it.
+     *
+     * Build instructions for a root that is undergoing a rename should be listed under the starting name.
+     * For example, if one wishes to build a tree which is being renamed from ID A to ID B,
+     * then the build should be listed under ID A.
+     */
+    readonly build?: readonly DetachedNodeBuild<TTree>[];
+    /**
+     * New detached nodes to be destroyed.
+     * The ordering has no significance.
+     *
+     * @deprecated - Destroys should be set at the root.
+     * TODO:6308 migrate all reader/writers away from this and remove it.
+     *
+     * Destruction instructions for a root that is undergoing a rename should be listed under the final name.
+     * For example, if one wishes to destroy a tree which is being renamed from ID A to ID B,
+     * then the destruction should be listed under ID B.
+     */
+    readonly destroy?: readonly DetachedNodeDestruction[];
+    /**
+     * Detached whose associated ID needs to be updated.
+     * The ordering has no significance.
+     * Note that the renames may need to be performed in a specific order to avoid collisions.
+     * This ordering problem is left to the consumer of this format.
+     */
+    readonly rename?: readonly DetachedNodeRename[];
+}
+//# sourceMappingURL=delta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.ts","sourceRoot":"","sources":["../../../src/core/tree/delta.ts"],"names":[],"mappings":"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"}

package/dist/core/tree/delta.js

@@ -0,0 +1,7 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=delta.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delta.js","sourceRoot":"","sources":["../../../src/core/tree/delta.ts"],"names":[],"mappings":";AAAA;;;GAGG","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 { ITreeCursorSynchronous } from \"./cursor\";\n\n/**\n * This format describes changes that must be applied to a forest in order to update it.\n * Instances of this format are generated based on incoming changesets and consumed by a view layer (e.g., Forest) to\n * update itself.\n *\n * Because this format is only meant for updating document state, it does not fully represent user intentions.\n * For example, if some concurrent edits A and B insert content at the same location, then a Delta that represents\n * represents the state update for edit A would not include information that allows B's insertion to be ordered\n * relative to A's insertion. This format is therefore not fit to be rebased in the face of concurrent changes.\n * Instead this format is used to describe the end product of rebasing user intentions over concurrent edits.\n *\n * This format is self-contained in the following ways:\n *\n * 1. It uses integer indices (offsets, technically) to describe the locations of necessary changes.\n * As such, it does not rely on document nodes being accessible/locatable by ID.\n *\n * 2. This format does not require historical information in order to apply the changes it describes.\n * For example, if a user undoes the deletion of a subtree, then the Delta generated for the undo edit will contain all\n * information necessary to restore that subtree.\n *\n * This format can be generated from any Changeset without having access to the current document state.\n *\n * This format is meant to serve as the lowest common denominator to represent state changes resulting from any kind\n * of operation on any kind of field.\n * This means all such operations must be expressible in terms of this format.\n *\n * Within the above design constrains, this format is designed with the following goals in mind:\n *\n * 1. Make it easy to walk both a document tree and the delta tree to apply the changes described in the delta\n * with a minimum amount of backtracking over the contents of the tree.\n * This a boon for both code simplicity and performance.\n *\n * 2. Make the format terse.\n *\n * 3. Make the format uniform.\n *\n * These goals are reflected in the following design choices (this is very much optional reading for users of this\n * format):\n *\n * 1. All marks that apply to field elements are represented in a single linear structure where marks that affect later\n * elements of the document field appear after marks that affect earlier elements of the document field.\n *\n * If the marks were not ordered in this fashion then a consumer would need to backtrack within the document field.\n *\n * If the marks were represented in multiple such linear structures then it would be necessary to either:\n * - backtrack when iterating over one structure fully, then the next\n * - maintain a pointer within each such linear structure and advance them in lock-step (like in a k-way merge-sort but\n * more fiddly because of the offsets).\n *\n * 2. Nested changes are not inlined within `ProtoNode`s.\n *\n * Inlining them would force the consuming code to detect such changes within the `ProtoNode` and handle them\n * within the context of the content creation.\n * This would be cumbersome because either the code that is responsible for consuming the `ProtoNode` would need to\n * be aware of and have the context to handle such changes, or some caller of that code would need to find and extract such\n * change information ahead to calling that code.\n */\n\n/**\n * Represents the change made to a document.\n * Immutable, therefore safe to retain for async processing.\n * @internal\n */\nexport interface Root<TTree = ProtoNode> {\n\t/**\n\t * Changes to apply to the root fields.\n\t */\n\treadonly fields?: FieldMap<TTree>;\n\t/**\n\t * New detached nodes to be constructed.\n\t * The ordering has no significance.\n\t *\n\t * Build instructions for a root that is undergoing a rename should be listed under the starting name.\n\t * For example, if one wishes to build a tree which is being renamed from ID A to ID B,\n\t * then the build should be listed under ID A.\n\t */\n\treadonly build?: readonly DetachedNodeBuild<TTree>[];\n\t/**\n\t * New detached nodes to be destroyed.\n\t * The ordering has no significance.\n\t *\n\t * Destruction instructions for a root that is undergoing a rename should be listed under the final name.\n\t * For example, if one wishes to destroy a tree which is being renamed from ID A to ID B,\n\t * then the destruction should be listed under ID B.\n\t */\n\treadonly destroy?: readonly DetachedNodeDestruction[];\n}\n/**\n * The default representation for inserted content.\n *\n * TODO:\n * Ownership and lifetime of data referenced by this cursor is unclear,\n * so it is a poor abstraction for this use-case which needs to hold onto the data in a non-exclusive (readonly) way.\n * Cursors can be one supported way to input data, but aren't a good storage format.\n * @internal\n */\nexport type ProtoNode = ITreeCursorSynchronous;\n\n/**\n * The default representation a chunk (sub-sequence) of inserted content.\n *\n * TODO:\n * See issue TODO with ProtoNode.\n * Additionally, Cursors support sequences, so if using cursors, there are better ways to handle this than an array of cursors,\n * like using a cursor over all the content (starting in fields mode).\n * Long term something like TreeChunk should probably be used here.\n * @internal\n */\nexport type ProtoNodes = readonly ProtoNode[];\n\n/**\n * Represents a change being made to a part of the document tree.\n * @internal\n */\nexport interface Mark<TTree = ProtoNode> {\n\t/**\n\t * The number of nodes affected.\n\t * When `isAttachMark(mark)` is true, this is the number of new nodes being attached.\n\t * When `isAttachMark(mark)` is false, this the number of existing nodes affected.\n\t * Must be 1 when `fields` is populated.\n\t */\n\treadonly count: number;\n\n\t/**\n\t * Modifications to the pre-existing content.\n\t * Must be undefined when `attach` is set but `detach` is not.\n\t */\n\treadonly fields?: FieldMap<TTree>;\n\n\t/**\n\t * When set, indicates that some pre-existing content is being detached and sent to the given detached field.\n\t */\n\treadonly detach?: DetachedNodeId;\n\n\t/**\n\t * When set, indicates that some content is being attached from the given detached field.\n\t */\n\treadonly attach?: DetachedNodeId;\n}\n\n/**\n * A globally unique ID for a node in a detached field.\n * @internal\n */\nexport interface DetachedNodeId {\n\treadonly major?: string | number;\n\treadonly minor: number;\n}\n\n/**\n * @internal\n */\nexport type FieldMap<TTree = ProtoNode> = ReadonlyMap<FieldKey, FieldChanges<TTree>>;\n\n/**\n * Represents changes made to a detached node\n * @internal\n */\nexport interface DetachedNodeChanges<TTree = ProtoNode> {\n\treadonly id: DetachedNodeId;\n\treadonly fields: FieldMap<TTree>;\n}\n\n/**\n * Represents the creation of detached nodes.\n *\n * Tree creation is idempotent: if a tree with the same ID already exists,\n * then this build is ignored in favor of the existing tree.\n * @internal\n */\nexport interface DetachedNodeBuild<TTree = ProtoNode> {\n\treadonly id: DetachedNodeId;\n\treadonly trees: readonly TTree[];\n}\n\n/**\n * Represents the destruction of detached nodes\n * @internal\n */\nexport interface DetachedNodeDestruction {\n\treadonly id: DetachedNodeId;\n\treadonly count: number;\n}\n\n/**\n * Represents a detached node being assigned a new `DetachedNodeId`.\n * @internal\n */\nexport interface DetachedNodeRename {\n\treadonly count: number;\n\treadonly oldId: DetachedNodeId;\n\treadonly newId: DetachedNodeId;\n}\n\n/**\n * Represents the changes to perform on a given field.\n * @internal\n */\nexport interface FieldChanges<TTree = ProtoNode> {\n\t/**\n\t * Represents a list of changes to the nodes in the field.\n\t * The index of each mark within the range of nodes, before\n\t * applying any of the changes, is not represented explicitly.\n\t * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.\n\t */\n\treadonly local?: readonly Mark<TTree>[];\n\t/**\n\t * Changes to apply to detached nodes.\n\t * The ordering has no significance.\n\t *\n\t * Nested changes for a root that is undergoing a rename should be listed under the starting name.\n\t * For example, if one wishes to change a tree which is being renamed from ID A to ID B,\n\t * then the changes should be listed under ID A.\n\t */\n\treadonly global?: readonly DetachedNodeChanges<TTree>[];\n\t/**\n\t * New detached nodes to be constructed.\n\t * The ordering has no significance.\n\t *\n\t * @deprecated - Builds should be set at the root.\n\t * TODO:6308 migrate all reader/writers away from this and remove it.\n\t *\n\t * Build instructions for a root that is undergoing a rename should be listed under the starting name.\n\t * For example, if one wishes to build a tree which is being renamed from ID A to ID B,\n\t * then the build should be listed under ID A.\n\t */\n\treadonly build?: readonly DetachedNodeBuild<TTree>[];\n\t/**\n\t * New detached nodes to be destroyed.\n\t * The ordering has no significance.\n\t *\n\t * @deprecated - Destroys should be set at the root.\n\t * TODO:6308 migrate all reader/writers away from this and remove it.\n\t *\n\t * Destruction instructions for a root that is undergoing a rename should be listed under the final name.\n\t * For example, if one wishes to destroy a tree which is being renamed from ID A to ID B,\n\t * then the destruction should be listed under ID B.\n\t */\n\treadonly destroy?: readonly DetachedNodeDestruction[];\n\t/**\n\t * Detached whose associated ID needs to be updated.\n\t * The ordering has no significance.\n\t * Note that the renames may need to be performed in a specific order to avoid collisions.\n\t * This ordering problem is left to the consumer of this format.\n\t */\n\treadonly rename?: readonly DetachedNodeRename[];\n}\n"]}

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

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ITreeCursorSynchronous } from "./cursor";
+import { Root, DetachedNodeId, FieldChanges, Mark } from "./delta";
+export declare const emptyDelta: Root<never>;
+export declare const emptyFieldChanges: FieldChanges<never>;
+export declare function isAttachMark(mark: Mark): boolean;
+export declare function isDetachMark(mark: Mark): boolean;
+export declare function isReplaceMark(mark: Mark): boolean;
+export declare function isEmptyFieldChanges(fieldChanges: FieldChanges): boolean;
+export declare function deltaForRootInitialization(content: readonly ITreeCursorSynchronous[]): Root;
+export declare function deltaForSet(newNode: ITreeCursorSynchronous, buildId: DetachedNodeId, detachId?: DetachedNodeId): FieldChanges;
+export declare function makeDetachedNodeId(major: DetachedNodeId["major"], minor: DetachedNodeId["minor"]): DetachedNodeId;
+export declare function offsetDetachId(id: DetachedNodeId, offset: number): DetachedNodeId;
+export declare function offsetDetachId(id: DetachedNodeId | undefined, offset: number): DetachedNodeId | undefined;
+export declare function areDetachedNodeIdsEqual(a: DetachedNodeId, b: DetachedNodeId): boolean;
+//# sourceMappingURL=deltaUtil.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deltaUtil.d.ts","sourceRoot":"","sources":["../../../src/core/tree/deltaUtil.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAGnE,eAAO,MAAM,UAAU,EAAE,IAAI,CAAC,KAAK,CAAM,CAAC;AAE1C,eAAO,MAAM,iBAAiB,EAAE,YAAY,CAAC,KAAK,CAAM,CAAC;AAEzD,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEhD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEhD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEjD;AAED,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAOvE;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GAAG,IAAI,CAiB3F;AAED,wBAAgB,WAAW,CAC1B,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,cAAc,EACvB,QAAQ,CAAC,EAAE,cAAc,GACvB,YAAY,CASd;AAED,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,EAC9B,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,GAC5B,cAAc,CAMhB;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC;AACnF,wBAAgB,cAAc,CAC7B,EAAE,EAAE,cAAc,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,GACZ,cAAc,GAAG,SAAS,CAAC;AAc9B,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAErF"}

package/dist/core/tree/deltaUtil.js

@@ -0,0 +1,82 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.areDetachedNodeIdsEqual = exports.offsetDetachId = exports.makeDetachedNodeId = exports.deltaForSet = exports.deltaForRootInitialization = exports.isEmptyFieldChanges = exports.isReplaceMark = exports.isDetachMark = exports.isAttachMark = exports.emptyFieldChanges = exports.emptyDelta = void 0;
+const types_1 = require("./types");
+exports.emptyDelta = {};
+exports.emptyFieldChanges = {};
+function isAttachMark(mark) {
+    return mark.attach !== undefined && mark.detach === undefined;
+}
+exports.isAttachMark = isAttachMark;
+function isDetachMark(mark) {
+    return mark.detach !== undefined && mark.attach === undefined;
+}
+exports.isDetachMark = isDetachMark;
+function isReplaceMark(mark) {
+    return mark.detach !== undefined && mark.attach !== undefined;
+}
+exports.isReplaceMark = isReplaceMark;
+function isEmptyFieldChanges(fieldChanges) {
+    return (fieldChanges.local === undefined &&
+        fieldChanges.global === undefined &&
+        fieldChanges.build === undefined &&
+        fieldChanges.rename === undefined);
+}
+exports.isEmptyFieldChanges = isEmptyFieldChanges;
+function deltaForRootInitialization(content) {
+    if (content.length === 0) {
+        return exports.emptyDelta;
+    }
+    const buildId = { minor: 0 };
+    const delta = {
+        build: [{ id: buildId, trees: content }],
+        fields: new Map([
+            [
+                types_1.rootFieldKey,
+                {
+                    local: [{ count: content.length, attach: buildId }],
+                },
+            ],
+        ]),
+    };
+    return delta;
+}
+exports.deltaForRootInitialization = deltaForRootInitialization;
+function deltaForSet(newNode, buildId, detachId) {
+    const mark = { count: 1, attach: buildId };
+    if (detachId !== undefined) {
+        mark.detach = detachId;
+    }
+    return {
+        build: [{ id: buildId, trees: [newNode] }],
+        local: [mark],
+    };
+}
+exports.deltaForSet = deltaForSet;
+function makeDetachedNodeId(major, minor) {
+    const out = { minor };
+    if (major !== undefined) {
+        out.major = major;
+    }
+    return out;
+}
+exports.makeDetachedNodeId = makeDetachedNodeId;
+function offsetDetachId(id, offset) {
+    if (id === undefined) {
+        return undefined;
+    }
+    return {
+        ...id,
+        minor: id.minor + offset,
+    };
+}
+exports.offsetDetachId = offsetDetachId;
+function areDetachedNodeIdsEqual(a, b) {
+    return a.major === b.major && a.minor === b.minor;
+}
+exports.areDetachedNodeIdsEqual = areDetachedNodeIdsEqual;
+//# sourceMappingURL=deltaUtil.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deltaUtil.js","sourceRoot":"","sources":["../../../src/core/tree/deltaUtil.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAMH,mCAAuC;AAE1B,QAAA,UAAU,GAAgB,EAAE,CAAC;AAE7B,QAAA,iBAAiB,GAAwB,EAAE,CAAC;AAEzD,SAAgB,YAAY,CAAC,IAAU;IACtC,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC;AAC/D,CAAC;AAFD,oCAEC;AAED,SAAgB,YAAY,CAAC,IAAU;IACtC,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC;AAC/D,CAAC;AAFD,oCAEC;AAED,SAAgB,aAAa,CAAC,IAAU;IACvC,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC;AAC/D,CAAC;AAFD,sCAEC;AAED,SAAgB,mBAAmB,CAAC,YAA0B;IAC7D,OAAO,CACN,YAAY,CAAC,KAAK,KAAK,SAAS;QAChC,YAAY,CAAC,MAAM,KAAK,SAAS;QACjC,YAAY,CAAC,KAAK,KAAK,SAAS;QAChC,YAAY,CAAC,MAAM,KAAK,SAAS,CACjC,CAAC;AACH,CAAC;AAPD,kDAOC;AAED,SAAgB,0BAA0B,CAAC,OAA0C;IACpF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE;QACzB,OAAO,kBAAU,CAAC;KAClB;IACD,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAS;QACnB,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACxC,MAAM,EAAE,IAAI,GAAG,CAAyB;YACvC;gBACC,oBAAY;gBACZ;oBACC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;iBACnD;aACD;SACD,CAAC;KACF,CAAC;IACF,OAAO,KAAK,CAAC;AACd,CAAC;AAjBD,gEAiBC;AAED,SAAgB,WAAW,CAC1B,OAA+B,EAC/B,OAAuB,EACvB,QAAyB;IAEzB,MAAM,IAAI,GAAkB,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC1D,IAAI,QAAQ,KAAK,SAAS,EAAE;QAC3B,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;KACvB;IACD,OAAO;QACN,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,KAAK,EAAE,CAAC,IAAI,CAAC;KACb,CAAC;AACH,CAAC;AAbD,kCAaC;AAED,SAAgB,kBAAkB,CACjC,KAA8B,EAC9B,KAA8B;IAE9B,MAAM,GAAG,GAA4B,EAAE,KAAK,EAAE,CAAC;IAC/C,IAAI,KAAK,KAAK,SAAS,EAAE;QACxB,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;KAClB;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AATD,gDASC;AAOD,SAAgB,cAAc,CAC7B,EAA8B,EAC9B,MAAc;IAEd,IAAI,EAAE,KAAK,SAAS,EAAE;QACrB,OAAO,SAAS,CAAC;KACjB;IACD,OAAO;QACN,GAAG,EAAE;QACL,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,MAAM;KACxB,CAAC;AACH,CAAC;AAXD,wCAWC;AAED,SAAgB,uBAAuB,CAAC,CAAiB,EAAE,CAAiB;IAC3E,OAAO,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC;AAFD,0DAEC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { Mutable } from \"../../util\";\nimport { FieldKey } from \"../schema-stored\";\nimport { ITreeCursorSynchronous } from \"./cursor\";\nimport { Root, DetachedNodeId, FieldChanges, Mark } from \"./delta\";\nimport { rootFieldKey } from \"./types\";\n\nexport const emptyDelta: Root<never> = {};\n\nexport const emptyFieldChanges: FieldChanges<never> = {};\n\nexport function isAttachMark(mark: Mark): boolean {\n\treturn mark.attach !== undefined && mark.detach === undefined;\n}\n\nexport function isDetachMark(mark: Mark): boolean {\n\treturn mark.detach !== undefined && mark.attach === undefined;\n}\n\nexport function isReplaceMark(mark: Mark): boolean {\n\treturn mark.detach !== undefined && mark.attach !== undefined;\n}\n\nexport function isEmptyFieldChanges(fieldChanges: FieldChanges): boolean {\n\treturn (\n\t\tfieldChanges.local === undefined &&\n\t\tfieldChanges.global === undefined &&\n\t\tfieldChanges.build === undefined &&\n\t\tfieldChanges.rename === undefined\n\t);\n}\n\nexport function deltaForRootInitialization(content: readonly ITreeCursorSynchronous[]): Root {\n\tif (content.length === 0) {\n\t\treturn emptyDelta;\n\t}\n\tconst buildId = { minor: 0 };\n\tconst delta: Root = {\n\t\tbuild: [{ id: buildId, trees: content }],\n\t\tfields: new Map<FieldKey, FieldChanges>([\n\t\t\t[\n\t\t\t\trootFieldKey,\n\t\t\t\t{\n\t\t\t\t\tlocal: [{ count: content.length, attach: buildId }],\n\t\t\t\t},\n\t\t\t],\n\t\t]),\n\t};\n\treturn delta;\n}\n\nexport function deltaForSet(\n\tnewNode: ITreeCursorSynchronous,\n\tbuildId: DetachedNodeId,\n\tdetachId?: DetachedNodeId,\n): FieldChanges {\n\tconst mark: Mutable<Mark> = { count: 1, attach: buildId };\n\tif (detachId !== undefined) {\n\t\tmark.detach = detachId;\n\t}\n\treturn {\n\t\tbuild: [{ id: buildId, trees: [newNode] }],\n\t\tlocal: [mark],\n\t};\n}\n\nexport function makeDetachedNodeId(\n\tmajor: DetachedNodeId[\"major\"],\n\tminor: DetachedNodeId[\"minor\"],\n): DetachedNodeId {\n\tconst out: Mutable<DetachedNodeId> = { minor };\n\tif (major !== undefined) {\n\t\tout.major = major;\n\t}\n\treturn out;\n}\n\nexport function offsetDetachId(id: DetachedNodeId, offset: number): DetachedNodeId;\nexport function offsetDetachId(\n\tid: DetachedNodeId | undefined,\n\toffset: number,\n): DetachedNodeId | undefined;\nexport function offsetDetachId(\n\tid: DetachedNodeId | undefined,\n\toffset: number,\n): DetachedNodeId | undefined {\n\tif (id === undefined) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\t...id,\n\t\tminor: id.minor + offset,\n\t};\n}\n\nexport function areDetachedNodeIdsEqual(a: DetachedNodeId, b: DetachedNodeId): boolean {\n\treturn a.major === b.major && a.minor === b.minor;\n}\n"]}