@fluid-experimental/tree 0.58.2001 → 0.59.2000-61729

package/src/TreeCompressor.ts

@@ -0,0 +1,213 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { isDetachedSequenceId } from './Identifiers';
+import type { Definition, DetachedSequenceId, InternedStringId, OpSpaceNodeId, TraitLabel } from './Identifiers';
+import type { StringInterner } from './StringInterner';
+import type { CompressedTraits, CompressedPlaceholderTree, PlaceholderTree, Payload } from './persisted-types';
+import type { ContextualizedNodeIdNormalizer } from './NodeIdUtilities';
+import { assert, fail, Mutable } from './Common';
+
+/**
+ * Compresses a given {@link PlaceholderTree} into a more compact serializable format.
+ */
+export interface TreeCompressor<TPlaceholder extends DetachedSequenceId | never> {
+	/**
+	 * @param node - The {@link PlaceholderTree} to compress.
+	 * @param interner - The StringInterner to use to intern strings.
+	 * @param idNormalizer - A normalizer to transform node IDs into op-space
+	 */
+	compress<TId extends OpSpaceNodeId>(
+		node: PlaceholderTree<TPlaceholder>,
+		interner: StringInterner,
+		idNormalizer: ContextualizedNodeIdNormalizer<TId>
+	): CompressedPlaceholderTree<TId, TPlaceholder>;
+
+	/**
+	 * @param node - The {@link PlaceholderTree} to compress.
+	 * @param interner - The StringInterner to use to intern strings.
+	 * @param idNormalizer - A normalizer to transform node IDs into op-space
+	 */
+	decompress<TId extends OpSpaceNodeId>(
+		node: CompressedPlaceholderTree<TId, TPlaceholder>,
+		interner: StringInterner,
+		idNormalizer: ContextualizedNodeIdNormalizer<TId>
+	): PlaceholderTree<TPlaceholder>;
+}
+
+/**
+ * Compresses a given {@link PlaceholderTree}
+ * (Such as a {@link ChangeNode} or {@link BuildNode}) into an array,
+ * while also string interning all node {@link Definition}s and {@link TraitLabel}s.
+ * See {@link CompressedPlaceholderTree} for format.
+ */
+export class InterningTreeCompressor<TPlaceholder extends DetachedSequenceId | never>
+	implements TreeCompressor<TPlaceholder>
+{
+	public compress<TId extends OpSpaceNodeId>(
+		node: PlaceholderTree<TPlaceholder>,
+		interner: StringInterner,
+		idNormalizer: ContextualizedNodeIdNormalizer<TId>
+	): CompressedPlaceholderTree<TId, TPlaceholder> {
+		this.previousId = undefined;
+		return this.compressI(node, interner, idNormalizer);
+	}
+
+	private compressI<TId extends OpSpaceNodeId>(
+		node: PlaceholderTree<TPlaceholder>,
+		interner: StringInterner,
+		idNormalizer: ContextualizedNodeIdNormalizer<TId>
+	): CompressedPlaceholderTree<TId, TPlaceholder> {
+		if (isDetachedSequenceId(node)) {
+			return node;
+		}
+
+		const internedDefinition = interner.getInternedId(node.definition) ?? node.definition;
+		const normalizedId = idNormalizer.normalizeToOpSpace(node.identifier);
+		const compressedId = canElideId(this.previousId, normalizedId) ? undefined : normalizedId;
+		this.previousId = normalizedId;
+		const compressedTraits: CompressedTraits<TId, TPlaceholder> = [];
+
+		// Omit traits if empty and payload is undefined.
+		const traits = Object.entries(node.traits).sort();
+		if (traits.length > 0 || node.payload !== undefined) {
+			for (const [label, trait] of traits) {
+				compressedTraits.push(
+					interner.getInternedId(label) ?? (label as TraitLabel),
+					trait.map((child) => this.compressI(child, interner, idNormalizer))
+				);
+			}
+		}
+
+		const payloadTraits = node.payload !== undefined ? [node.payload, ...compressedTraits] : compressedTraits;
+		if (payloadTraits.length > 0) {
+			if (compressedId !== undefined) {
+				return [internedDefinition, compressedId, payloadTraits];
+			}
+			return [internedDefinition, payloadTraits];
+		}
+
+		if (compressedId !== undefined) {
+			return [internedDefinition, compressedId];
+		}
+
+		return [internedDefinition];
+	}
+
+	/** The ID that was compressed or decompressed most recently */
+	private previousId?: OpSpaceNodeId;
+
+	public decompress<TId extends OpSpaceNodeId>(
+		node: CompressedPlaceholderTree<TId, TPlaceholder>,
+		interner: StringInterner,
+		idNormalizer: ContextualizedNodeIdNormalizer<TId>
+	): PlaceholderTree<TPlaceholder> {
+		if (isDetachedSequenceId(node)) {
+			return node;
+		}
+		const rootId = node[1];
+		assert(typeof rootId === 'number', 'Root node was compressed with no ID');
+		this.previousId = rootId;
+		return this.decompressI(node, interner, idNormalizer);
+	}
+
+	private decompressI<TId extends OpSpaceNodeId>(
+		node: CompressedPlaceholderTree<TId, TPlaceholder>,
+		interner: StringInterner,
+		idNormalizer: ContextualizedNodeIdNormalizer<TId>
+	): PlaceholderTree<TPlaceholder> {
+		if (isDetachedSequenceId(node)) {
+			return node;
+		}
+
+		let compressedId: TId | undefined;
+		let compressedTraits:
+			| [Payload, ...CompressedTraits<TId, TPlaceholder>]
+			| CompressedTraits<TId, TPlaceholder>
+			| undefined;
+		let payload: Payload | undefined;
+		const [maybeInternedDefinition, idOrPayloadTraits, payloadTraits] = node;
+		if (idOrPayloadTraits !== undefined) {
+			if (typeof idOrPayloadTraits === 'number') {
+				compressedId = idOrPayloadTraits;
+				if (payloadTraits !== undefined) {
+					compressedTraits = payloadTraits;
+				}
+			} else {
+				// TODO: This cast can be removed on typescript 4.6
+				compressedTraits = idOrPayloadTraits as typeof compressedTraits;
+			}
+		}
+
+		const definition =
+			typeof maybeInternedDefinition === 'string'
+				? maybeInternedDefinition
+				: // TODO: This cast can be removed on typescript 4.6
+				  (interner.getString(maybeInternedDefinition as number) as Definition);
+
+		let identifier: TId;
+		if (compressedId !== undefined) {
+			identifier = compressedId;
+		} else {
+			const prevId = this.previousId ?? fail();
+			identifier = prevId < 0 ? ((prevId - 1) as TId) : (((prevId as number) + 1) as TId);
+		}
+		this.previousId = identifier;
+
+		const traits = {};
+		if (compressedTraits !== undefined) {
+			let offset: number;
+			if (compressedTraits.length % 2 === 1) {
+				offset = 1;
+				payload = compressedTraits[0];
+			} else {
+				offset = 0;
+			}
+			const traitsLength = compressedTraits.length - offset;
+			for (let i = 0; i < traitsLength; i += 2) {
+				const offsetIndex = i + offset;
+				const maybeCompressedLabel = compressedTraits[offsetIndex] as InternedStringId;
+				const compressedChildren = compressedTraits[offsetIndex + 1] as (
+					| TPlaceholder
+					| CompressedPlaceholderTree<TId, TPlaceholder>
+				)[];
+
+				const decompressedTraits = compressedChildren.map((child) =>
+					this.decompressI(child, interner, idNormalizer)
+				);
+
+				const label =
+					typeof maybeCompressedLabel === 'string'
+						? maybeCompressedLabel
+						: (interner.getString(maybeCompressedLabel) as TraitLabel);
+				traits[label] = decompressedTraits;
+			}
+		}
+
+		const decompressedNode: Mutable<PlaceholderTree<TPlaceholder>> = {
+			identifier: idNormalizer.normalizeToSessionSpace(identifier),
+			definition,
+			traits,
+		};
+
+		if (payload !== undefined) {
+			decompressedNode.payload = payload;
+		}
+
+		return decompressedNode;
+	}
+}
+
+function canElideId<TId extends OpSpaceNodeId>(previousId: TId | undefined, id: TId): boolean {
+	if (previousId === undefined) {
+		return false;
+	}
+
+	const numericId: number = previousId;
+	if (numericId < 0) {
+		return id === numericId - 1;
+	}
+
+	return id === numericId + 1;
+}

package/src/TreeNodeHandle.ts

@@ -4,25 +4,24 @@
  */
 
 import { Definition, NodeId } from './Identifiers';
-import { ChangeNode, Payload, TraitMap, TreeNode } from './generic';
-import { Snapshot } from './Snapshot';
-import { memoizeGetter } from './Common';
-import { getChangeNodeFromSnapshot } from './SnapshotUtilities';
+import { fail, memoizeGetter } from './Common';
+import { Payload, TraitMap, TreeNode } from './persisted-types';
+import { TreeView, TreeViewNode } from './TreeView';
 
 /**
- * A handle to a `TreeNode` that exists within a specific `Snapshot`. This type provides a convenient
- * API for traversing trees of nodes in a Snapshot and is not designed to provide maximum runtime
- * performance; if performance is a concern, consider using the Snapshot and SnapshotNode APIs directly.
+ * A handle to a `TreeNode` that exists within a specific `TreeView`. This type provides a convenient
+ * API for traversing trees of nodes in a TreeView and is not designed to provide maximum runtime
+ * performance; if performance is a concern, consider using the TreeView and TreeViewNode APIs directly.
  * @public
  */
-export class TreeNodeHandle implements TreeNode<TreeNodeHandle> {
-	private readonly snapshot: Snapshot;
-	private readonly nodeId: NodeId;
+export class TreeNodeHandle implements TreeNode<TreeNodeHandle, NodeId> {
+	private readonly view: TreeView;
+	private readonly viewNode: TreeViewNode;
 
-	/** Construct a handle which references the node with the given id in the given `Snapshot` */
-	public constructor(snapshot: Snapshot, nodeId: NodeId) {
-		this.snapshot = snapshot;
-		this.nodeId = nodeId;
+	/** Construct a handle which references the node with the given id in the given `TreeView` */
+	public constructor(view: TreeView, nodeId: NodeId) {
+		this.view = view;
+		this.viewNode = view.tryGetViewNode(nodeId) ?? fail('Failed to create handle: node is not present in view');
 	}
 
 	public get payload(): Payload | undefined {
@@ -40,11 +39,11 @@ export class TreeNodeHandle implements TreeNode<TreeNodeHandle> {
 	public get traits(): TraitMap<TreeNodeHandle> {
 		// Construct a new trait map that wraps each node in each trait in a handle
 		const traitMap: TraitMap<TreeNodeHandle> = {};
-		const { snapshot } = this;
-		for (const [label, trait] of Object.entries(this.node.traits)) {
+		const { view } = this;
+		for (const [label, trait] of this.node.traits.entries()) {
 			Object.defineProperty(traitMap, label, {
 				get() {
-					const handleTrait = trait.map((node) => new TreeNodeHandle(snapshot, node.identifier));
+					const handleTrait = trait.map((node) => new TreeNodeHandle(view, node));
 					return memoizeGetter(this as TraitMap<TreeNodeHandle>, label, handleTrait);
 				},
 				configurable: true,
@@ -56,21 +55,9 @@ export class TreeNodeHandle implements TreeNode<TreeNodeHandle> {
 	}
 
 	/**
-	 * Get a `ChangeNode` for the snapshot node that this handle references
+	 * Get a `TreeViewNode` for the tree view node that this handle references
 	 */
-	public get node(): ChangeNode {
-		return memoizeGetter(this, 'node', getChangeNodeFromSnapshot(this.snapshot, this.nodeId, true));
-	}
-
-	/**
-	 * Generate a new `ChangeNode` for the snapshot node that this handle references. The returned node will be fully
-	 * demanded, i.e. will contain no lazy/virtualized subtrees.
-	 */
-	public demandTree(): ChangeNode {
-		return getChangeNodeFromSnapshot(this.snapshot, this.nodeId, false);
-	}
-
-	public toString(): string {
-		return JSON.stringify(this.demandTree());
+	public get node(): TreeViewNode {
+		return memoizeGetter(this, 'node', this.viewNode);
 	}
 }

package/src/TreeView.ts

@@ -0,0 +1,322 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert, copyPropertyIfDefined, fail } from './Common';
+import { NodeId, TraitLabel } from './Identifiers';
+import { Delta, Forest, isParentedForestNode } from './Forest';
+import { NodeData, Side } from './persisted-types';
+
+/**
+ * Specifies the location of a trait (a labeled sequence of nodes) within the tree.
+ * @public
+ */
+export interface TraitLocation {
+	readonly parent: NodeId;
+	readonly label: TraitLabel;
+}
+
+/**
+ * An immutable view of a distributed tree node.
+ * @public
+ */
+export interface TreeViewNode extends NodeData<NodeId> {
+	/** The IDs of the children under this node */
+	readonly traits: ReadonlyMap<TraitLabel, readonly NodeId[]>;
+	/** The parent and trait under which this node resides. Undefined iff this is the root node of the tree (i.e. {@link initialTree}). */
+	readonly parentage?: TraitLocation;
+}
+
+/**
+ * Index of a place within a trait.
+ * 0 = before all nodes,
+ * 1 = after first node,
+ * etc.
+ * @public
+ */
+export type PlaceIndex = number & { readonly PlaceIndex: unique symbol };
+
+/**
+ * Index of a node within a trait.
+ * 0 = first node,
+ * 1 = second node,
+ * etc.
+ * @public
+ */
+export type TraitNodeIndex = number & { readonly TraitNodeIndex: unique symbol };
+
+/**
+ * A place within a particular `TreeView` that is anchored relative to a specific node in the tree, or relative to the outside of the trait.
+ * Valid iff 'trait' is valid and, if provided, sibling is in the Location specified by 'trait'.
+ * @public
+ */
+export interface TreeViewPlace {
+	readonly sibling?: NodeId;
+	readonly side: Side;
+	readonly trait: TraitLocation;
+}
+
+/**
+ * Specifies the range of nodes from `start` to `end` within a trait within a particular `TreeView`.
+ * Valid iff start and end are valid and are within the same trait.
+ * @public
+ */
+export interface TreeViewRange {
+	readonly start: TreeViewPlace;
+	readonly end: TreeViewPlace;
+}
+
+/**
+ * Contains some redundant information. Use only in computations between edits. Do not store.
+ * @public
+ */
+export interface NodeInTrait {
+	readonly trait: TraitLocation;
+	readonly index: TraitNodeIndex;
+}
+
+/**
+ * A view of a distributed tree.
+ * @public
+ */
+export abstract class TreeView {
+	public readonly root: NodeId;
+	protected readonly forest: Forest;
+	private readonly rootNode: TreeViewNode;
+
+	/**
+	 * A cache of node's index within their parent trait.
+	 * Used to avoid redundant linear scans of traits.
+	 * Not shared across views; initialized to empty each time a TreeView is created.
+	 */
+	private traitIndicesCache?: Map<NodeId, TraitNodeIndex>;
+
+	protected constructor(root: NodeId, forest: Forest) {
+		this.root = root;
+		this.forest = forest;
+		this.rootNode = this.getViewNode(root);
+	}
+
+	/** @returns the number of nodes in this view */
+	public get size(): number {
+		return this.forest.size;
+	}
+
+	/** @returns true iff a node with the given id exists in this view */
+	public hasNode(id: NodeId): boolean {
+		return this.forest.has(id);
+	}
+
+	/**
+	 * @returns the index just after place (which specifies a location between items).
+	 * Performance note: this is O(siblings in trait).
+	 */
+	public findIndexWithinTrait(place: TreeViewPlace): PlaceIndex {
+		if (place.sibling === undefined) {
+			return this.getIndexOfSide(place.side, place.trait);
+		}
+		return getIndex(place.side, this.getIndexInTrait(place.sibling));
+	}
+
+	/** @returns the node associated with the given id in this view. Fails if the node does not exist in this view. */
+	public getViewNode(id: NodeId): TreeViewNode {
+		return this.tryGetViewNode(id) ?? fail('NodeId not found');
+	}
+
+	/** @returns the node associated with the given id in this view, or undefined if the node does not exist in this view */
+	public tryGetViewNode(id: NodeId): TreeViewNode | undefined {
+		const forestNode = this.forest.tryGet(id);
+		if (forestNode !== undefined && isParentedForestNode(forestNode)) {
+			const viewNode: TreeViewNode = {
+				definition: forestNode.definition,
+				identifier: forestNode.identifier,
+				traits: forestNode.traits,
+				parentage: {
+					label: forestNode.traitParent,
+					parent: forestNode.parentId,
+				},
+			};
+			copyPropertyIfDefined(forestNode, viewNode, 'payload');
+			return viewNode;
+		}
+
+		return forestNode;
+	}
+
+	/**
+	 * @returns the label of the trait under which a node with the given id resides. Fails if the node does not exist in this view or if
+	 * it is the root node.
+	 */
+	public getTraitLabel(id: NodeId): TraitLabel {
+		return this.forest.getParent(id).traitParent;
+	}
+
+	/**
+	 * @returns the label of the trait under which a node with the given id resides, or undefined if the node is not present in this
+	 * view or if it is the root node
+	 */
+	public tryGetTraitLabel(id: NodeId): TraitLabel | undefined {
+		return this.forest.tryGetParent(id)?.traitParent;
+	}
+
+	/**
+	 * @returns the parent of the node with the given id. Fails if the node does not exist in this view or if it is the root node.
+	 */
+	public getParentViewNode(id: NodeId): TreeViewNode {
+		const parentInfo = this.forest.getParent(id);
+		return this.getViewNode(parentInfo.parentId);
+	}
+
+	/**
+	 * @returns the parent of the node with the given id. Returns undefined if the node does not exist in this view or if it is the root
+	 * node.
+	 */
+	public tryGetParentViewNode(id: NodeId): TreeViewNode | undefined {
+		const parentInfo = this.forest.tryGetParent(id);
+		if (parentInfo === undefined) {
+			return undefined;
+		}
+		return this.getViewNode(parentInfo.parentId);
+	}
+
+	/**
+	 * @returns the trait location of the node with the given id. Fails if the node does not exist in this view or of it is the root
+	 * node
+	 */
+	public getTraitLocation(id: NodeId): TraitLocation {
+		const parentData = this.forest.getParent(id);
+		return {
+			parent: parentData.parentId,
+			label: parentData.traitParent,
+		};
+	}
+
+	/**
+	 * @returns the trait location of the node with the given id, or undefined if the node does not exist in this view or if it is the root
+	 * node
+	 */
+	public tryGetTraitLocation(id: NodeId): TraitLocation | undefined {
+		const parentData = this.forest.tryGetParent(id);
+		if (parentData === undefined) {
+			return undefined;
+		}
+		return {
+			parent: parentData.parentId,
+			label: parentData.traitParent,
+		};
+	}
+
+	/**
+	 * @returns the index within the trait under which the node with the given id resides. The node must exist in this view and must have a
+	 * parent.
+	 * Performance note: this is O(siblings in trait).
+	 */
+	public getIndexInTrait(id: NodeId): TraitNodeIndex {
+		const index = this.tryGetIndexInTrait(id);
+		return index ?? fail('ID does not exist in the forest.');
+	}
+
+	/**
+	 * @returns the index within the trait under which the node with the given id resides, or undefined if the node does not exist in this
+	 * view or does not have a parent.
+	 * Performance note: this is O(siblings in trait).
+	 */
+	public tryGetIndexInTrait(id: NodeId): TraitNodeIndex | undefined {
+		const cachedIndex = this.traitIndicesCache?.get(id);
+		if (cachedIndex !== undefined) {
+			return cachedIndex;
+		}
+
+		const parentData = this.forest.tryGetParent(id);
+		if (parentData === undefined) {
+			return undefined;
+		}
+
+		const parent = this.forest.tryGet(parentData.parentId);
+		if (parent === undefined) {
+			return undefined;
+		}
+
+		const trait = parent.traits.get(parentData.traitParent) ?? fail('inconsistent forest: trait parent not found');
+		let foundIndex: TraitNodeIndex | undefined;
+		if (trait.length === 0) {
+			return foundIndex;
+		}
+
+		this.traitIndicesCache ??= new Map();
+		for (let i = 0; i < trait.length; i++) {
+			const nodeInTrait = trait[i];
+			const index = i as TraitNodeIndex;
+			this.traitIndicesCache.set(nodeInTrait, index);
+			if (nodeInTrait === id) {
+				foundIndex = index;
+			}
+		}
+
+		return foundIndex;
+	}
+
+	/**
+	 * @returns the trait at the given location. If no such trait exists, returns an empty trait.
+	 */
+	public getTrait(traitLocation: TraitLocation): readonly NodeId[] {
+		return this.getViewNode(traitLocation.parent).traits.get(traitLocation.label) ?? [];
+	}
+
+	/** Asserts that the view's internal state is consistent. Useful for testing/validation. */
+	public assertConsistent(): void {
+		this.forest.assertConsistent();
+	}
+
+	public [Symbol.iterator](): IterableIterator<TreeViewNode> {
+		return this.iterateNodeDescendants(this.rootNode);
+	}
+
+	/** @returns true iff the given view is equal to this view */
+	public abstract equals(view: TreeView): boolean;
+
+	/**
+	 * @returns true iff the given view's forest of nodes is equivalent to this view's forest of nodes
+	 * @param strict - if true, the views' forests must be the same object, otherwise they must merely be equivalent
+	 */
+	public hasEqualForest(view: TreeView, strict = false): boolean {
+		if (this.root === view.root) {
+			// TODO:#49100:Perf: make this faster and/or remove use by PrefetchingCheckout.
+			return strict ? this.forest === view.forest : this.forest.equals(view.forest);
+		}
+
+		return false;
+	}
+
+	private *iterateNodeDescendants(node: TreeViewNode): IterableIterator<TreeViewNode> {
+		yield node;
+		for (const label of [...node.traits.keys()].sort()) {
+			const trait = node.traits.get(label);
+			for (const childId of trait ?? fail('Expected trait with label')) {
+				const child = this.getViewNode(childId);
+				yield* this.iterateNodeDescendants(child);
+			}
+		}
+	}
+
+	private getIndexOfSide(side: Side, traitLocation: TraitLocation): PlaceIndex {
+		return side === Side.After ? (0 as PlaceIndex) : (this.getTrait(traitLocation).length as PlaceIndex);
+	}
+
+	/**
+	 * Calculate the difference between two `TreeView`s
+	 * @param view - the other view to compare to this one
+	 * @returns A {@link Delta} which nodes must be changed, added, and removed to get from `this` to `view`.
+	 * The views must share a root.
+	 */
+	public delta(view: TreeView): Delta<NodeId> {
+		assert(this.root === view.root, 'Delta can only be calculated between views that share a root');
+		return this.forest.delta(view.forest);
+	}
+}
+
+function getIndex(side: Side, index: TraitNodeIndex): PlaceIndex {
+	// eslint-disable-next-line @typescript-eslint/restrict-plus-operands
+	return (side + index) as PlaceIndex;
+}

package/src/TreeViewUtilities.ts

@@ -0,0 +1,77 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { StablePlace, StableRange } from './ChangeTypes';
+import { assert, fail } from './Common';
+import { TraitLocation, TreeView, TreeViewPlace, TreeViewRange } from './TreeView';
+
+/**
+ * Express the given {@link (StableRange:interface)} as a {@link TreeViewRange}
+ */
+export function rangeFromStableRange(view: TreeView, range: StableRange): TreeViewRange {
+	const location = getTraitLocationOfRange(view, range);
+	// This can be optimized for better constant factors.
+	return {
+		start: sideOfRange(range, SideOfRange.Start, location),
+		end: sideOfRange(range, SideOfRange.End, location),
+	};
+}
+
+/**
+ * Express the given {@link (StablePlace:interface)} as a {@link TreeViewPlace}
+ */
+export function placeFromStablePlace(view: TreeView, stablePlace: StablePlace): TreeViewPlace {
+	const { side } = stablePlace;
+	if (stablePlace.referenceSibling === undefined) {
+		assert(stablePlace.referenceTrait !== undefined);
+		return {
+			trait: stablePlace.referenceTrait,
+			side,
+		};
+	}
+	return {
+		trait: view.getTraitLocation(stablePlace.referenceSibling),
+		side: stablePlace.side,
+		sibling: stablePlace.referenceSibling,
+	};
+}
+
+/**
+ * Return the trait under which the given range resides
+ * @param view - the {@link TreeView} within which to retrieve the trait location
+ * @param range - must be well formed and valid
+ */
+export function getTraitLocationOfRange(view: TreeView, range: StableRange): TraitLocation {
+	const referenceTrait = range.start.referenceTrait ?? range.end.referenceTrait;
+	if (referenceTrait) {
+		return referenceTrait;
+	}
+	const sibling =
+		range.start.referenceSibling ?? range.end.referenceSibling ?? fail('malformed range does not indicate trait');
+	return view.getTraitLocation(sibling);
+}
+
+function sideOfRange(range: StableRange, sideOfRange: SideOfRange, trait: TraitLocation): TreeViewPlace {
+	const siblingRelative = sideOfRange === SideOfRange.Start ? range.start : range.end;
+	return {
+		trait,
+		side: siblingRelative.side,
+		sibling: siblingRelative.referenceSibling,
+	};
+}
+
+/**
+ * Denotes either the start or end of a range
+ */
+enum SideOfRange {
+	/**
+	 * The start of the range
+	 */
+	Start = 0,
+	/**
+	 * The end of the range
+	 */
+	End = 1,
+}