@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/src/core/tree/index.ts

@@ -0,0 +1,114 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	Anchor,
+	AnchorLocator,
+	AnchorSet,
+	AnchorSlot,
+	AnchorNode,
+	anchorSlot,
+	AnchorEvents,
+	AnchorSetRootEvents,
+} from "./anchorSet";
+export {
+	ITreeCursor,
+	CursorLocationType,
+	castCursorToSynchronous,
+	mapCursorField,
+	mapCursorFields,
+	forEachNode,
+	forEachNodeInSubtree,
+	forEachField,
+	iterateCursorField,
+	ITreeCursorSynchronous,
+	PathRootPrefix,
+	inCursorField,
+	inCursorNode,
+	CursorMarker,
+	isCursor,
+} from "./cursor";
+export {
+	ProtoNodes,
+	Root as DeltaRoot,
+	ProtoNode as DeltaProtoNode,
+	Mark as DeltaMark,
+	DetachedNodeId as DeltaDetachedNodeId,
+	FieldMap as DeltaFieldMap,
+	DetachedNodeChanges as DeltaDetachedNodeChanges,
+	DetachedNodeBuild as DeltaDetachedNodeBuild,
+	DetachedNodeDestruction as DeltaDetachedNodeDestruction,
+	DetachedNodeRename as DeltaDetachedNodeRename,
+	FieldChanges as DeltaFieldChanges,
+} from "./delta";
+export { getMapTreeField, MapTree } from "./mapTree";
+export {
+	clonePath,
+	topDownPath,
+	getDepth,
+	UpPath,
+	FieldUpPath,
+	Range,
+	RangeUpPath,
+	PlaceUpPath,
+	PlaceIndex,
+	NodeIndex,
+	DetachedPlaceUpPath,
+	DetachedRangeUpPath,
+	compareUpPaths,
+	compareFieldUpPaths,
+	getDetachedFieldContainingPath,
+	UpPathDefault,
+} from "./pathTree";
+export {
+	FieldMapObject,
+	GenericFieldsNode,
+	genericTreeDeleteIfEmpty,
+	genericTreeKeys,
+	GenericTreeNode,
+	getGenericTreeField,
+	JsonableTree,
+	setGenericTreeField,
+} from "./treeTextFormat";
+export { EncodedJsonableTree } from "./persistedTreeTextFormat";
+export {
+	EmptyKey,
+	TreeType,
+	ChildLocation,
+	DetachedField,
+	ChildCollection,
+	RootField,
+	Value,
+	TreeValue,
+	detachedFieldAsKey,
+	keyAsDetachedField,
+	rootFieldKey,
+	NodeData,
+	rootField,
+	aboveRootPlaceholder,
+} from "./types";
+export { DeltaVisitor, visitDelta } from "./visitDelta";
+export {
+	AnnouncedVisitor,
+	announceDelta,
+	applyDelta,
+	combineVisitors,
+	makeDetachedFieldIndex,
+} from "./visitorUtils";
+export { PathVisitor } from "./visitPath";
+
+export { SparseNode, getDescendant } from "./sparseTree";
+
+export {
+	deltaForRootInitialization,
+	deltaForSet,
+	emptyFieldChanges,
+	isEmptyFieldChanges,
+	makeDetachedNodeId,
+	offsetDetachId,
+	emptyDelta,
+} from "./deltaUtil";
+
+export { DetachedFieldIndex, ForestRootId } from "./detachedFieldIndex";

package/src/core/tree/mapTree.ts

@@ -0,0 +1,37 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { FieldKey } from "../schema-stored";
+import { NodeData } from "./types";
+
+/**
+ * This modules provides a simple in memory tree format.
+ */
+
+/**
+ * Simple in memory tree representation based on Maps.
+ * MapTrees should not store empty fields.
+ * @internal
+ */
+export interface MapTree extends NodeData {
+	fields: Map<FieldKey, MapTree[]>;
+}
+
+/**
+ * Get a field from `node`, optionally modifying the tree to create it if missing.
+ */
+export function getMapTreeField(node: MapTree, key: FieldKey, createIfMissing: boolean): MapTree[] {
+	const field = node.fields.get(key);
+	if (field !== undefined) {
+		return field;
+	}
+	// Handle missing field:
+	if (createIfMissing === false) {
+		return [];
+	}
+	const newField: MapTree[] = [];
+	node.fields.set(key, newField);
+	return newField;
+}

package/src/core/tree/pathTree.ts

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

package/src/core/tree/persistedTreeTextFormat.ts

@@ -0,0 +1,93 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Static, TSchema, Type } from "@sinclair/typebox";
+import { schemaFormat } from "../schema-stored";
+
+/**
+ * This module contains persisted types for a simple, human-readable tree format.
+ *
+ * It was forked from `treeTextFormat.ts` to more cleanly separate compatibility concerns: in the long-term,
+ * treeTextFormat.ts is intended to be useful for debugging/test purposes but not for persisted document storage
+ * due to its unoptimized nature.
+ *
+ * However, at the time of forking it was also used as a persisted format for several of SharedTree's indexes.
+ * Using the same types for both scenarios is problematic since `treeTextFormat.ts` types are exposed to the
+ * public API.
+ * These types should be used instead for all persisted format concerns.
+ *
+ * Before SharedTree has committed to persisted format backwards-compatibility, changes to `treeTextFormat.ts`
+ * should be accompanied by the same changes to this module.
+ *
+ * After that point, changes to `treeTextFormat.ts` will necessitate changes to codecs that deal with these types
+ * (and types in this module should not be changed except in compliance with persisted type compatibility guidelines).
+ *
+ * Longer-term, usages of these types should likely be replaced with a more optimized format.
+ * If that switch happens before SharedTree commits to back-compat, this persisted format file can be deleted.
+ */
+
+/**
+ * Json compatible map as object.
+ * Keys are FieldKey strings.
+ * Values are the content of the field specified by the key.
+ *
+ * WARNING:
+ * Be very careful when using objects as maps:
+ * Use `Object.prototype.hasOwnProperty.call(fieldMap, key)` to safely check for keys.
+ * Do NOT simply read the field and check for undefined as this will return values for `__proto__`
+ * and various methods on Object.prototype, like `hasOwnProperty` and `toString`.
+ * This exposes numerous bug possibilities, including prototype pollution.
+ *
+ * Due to the above issue, try to avoid this type (and the whole object as map pattern).
+ * Only use this type when needed for json compatible maps,
+ * but even in those cases consider lists of key value pairs for serialization and using `Map`
+ * for runtime.
+ */
+interface EncodedFieldMapObject<TChild> {
+	[key: string]: TChild[];
+}
+const EncodedFieldMapObject = <Schema extends TSchema>(tChild: Schema) =>
+	Type.Record(Type.String(), Type.Array(tChild, { minItems: 1 }));
+
+type EncodedNodeData = Static<typeof EncodedNodeData>;
+const EncodedNodeData = Type.Object({
+	value: Type.Optional(Type.Any()),
+	type: Type.Readonly(schemaFormat.TreeNodeSchemaIdentifierSchema),
+});
+
+/**
+ * Json comparable field collection, generic over child type.
+ * Json compatibility assumes `TChild` is also json compatible.
+ */
+interface EncodedGenericFieldsNode<TChild> {
+	fields?: EncodedFieldMapObject<TChild>;
+	globalFields?: EncodedFieldMapObject<TChild>;
+}
+const EncodedGenericFieldsNode = <Schema extends TSchema>(tChild: Schema) =>
+	Type.Object({
+		fields: Type.Optional(EncodedFieldMapObject(tChild)),
+		globalFields: Type.Optional(EncodedFieldMapObject(tChild)),
+	});
+
+/**
+ * Json comparable tree node, generic over child type.
+ * Json compatibility assumes `TChild` is also json compatible.
+ */
+interface EncodedGenericTreeNode<TChild>
+	extends EncodedGenericFieldsNode<TChild>,
+		EncodedNodeData {}
+const EncodedGenericTreeNode = <Schema extends TSchema>(tChild: Schema) =>
+	Type.Composite([EncodedGenericFieldsNode(tChild), EncodedNodeData], {
+		additionalProperties: false,
+	});
+
+/**
+ * A tree represented using plain JavaScript objects.
+ * Can be passed to `JSON.stringify()` to produce a human-readable/editable JSON tree.
+ *
+ * JsonableTrees must not store empty fields.
+ */
+export interface EncodedJsonableTree extends EncodedGenericTreeNode<EncodedJsonableTree> {}
+export const EncodedJsonableTree = Type.Recursive((Self) => EncodedGenericTreeNode(Self));

package/src/core/tree/sparseTree.ts

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