@fluidframework/tree 2.10.0 → 2.11.0

package/src/feature-libraries/indexing/anchorTreeIndex.ts

@@ -0,0 +1,453 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import { disposeSymbol, fail, getOrCreate } from "../../util/index.js";
+import {
+	type Anchor,
+	type AnchorNode,
+	type FieldKey,
+	type TreeNodeSchemaIdentifier,
+	forEachField,
+	forEachNode,
+	type ITreeSubscriptionCursor,
+	createAnnouncedVisitor,
+	type IForestSubscription,
+	type AnnouncedVisitor,
+	CursorLocationType,
+	rootField,
+	type UpPath,
+	type ProtoNodes,
+	keyAsDetachedField,
+	compareUpPaths,
+	TreeNavigationResult,
+} from "../../core/index.js";
+import type { TreeIndex, TreeIndexKey, TreeIndexNodes } from "./types.js";
+import { TreeStatus } from "../flex-tree/index.js";
+
+/**
+ * A function that gets the value to index a node on, must be pure and functional.
+ * The given cursor should point to the node that will be indexed.
+ *
+ * @returns a value the index will use as the key for the given node
+ *
+ * @remarks
+ * This function does not own the cursor in any way, it walks the cursor to find the key the node is indexed on
+ * but returns the cursor to the state it was in before being passed to the function. It should also not be disposed by this function
+ * and must be disposed elsewhere.
+ */
+export type KeyFinder<TKey extends TreeIndexKey> = (tree: ITreeSubscriptionCursor) => TKey;
+
+/**
+ * An index from some arbitrary keys to anchor nodes. Keys can be anything that is a {@link TreeValue}.
+ * A key can map to multiple nodes but each collection of nodes only results in a single value.
+ *
+ * @remarks
+ * Detached nodes are stored in the index but filtered out when any public facing apis are called. This means that
+ * calling {@link keys} will not include any keys that are stored in the index but only map to detached nodes.
+ */
+export class AnchorTreeIndex<TKey extends TreeIndexKey, TValue>
+	implements TreeIndex<TKey, TValue>
+{
+	public disposed = false;
+	/**
+	 * Caches {@link KeyFinder}s for each schema definition. If a schema maps to null, it does not
+	 * need to be considered at all for this index. This allows us to skip subtrees that aren't relevant
+	 * as a performance optimization.
+	 */
+	private readonly keyFinders = new Map<TreeNodeSchemaIdentifier, KeyFinder<TKey> | null>();
+	/**
+	 * The actual index from keys to anchor nodes.
+	 */
+	private readonly keyToNodes = new Map<TKey, AnchorNode[]>();
+	/**
+	 * Maintained for efficient removal of anchor nodes from the index when updating their keys
+	 */
+	private readonly nodeToKey = new Map<AnchorNode, TKey>();
+	/**
+	 * Keeps track of anchors for disposal.
+	 */
+	private readonly anchors = new Map<AnchorNode, Anchor[]>();
+	/**
+	 * The key finder that is registered on the forest to keep this index updated, maintained
+	 * here for deregistration on disposal
+	 */
+	private readonly keyFinder = this.acquireVisitor.bind(this);
+
+	/**
+	 * @param forest - the forest that is being indexed
+	 * @param indexer - a function that retrieves the key finder based on a given schema or undefined if the schema does not have an associated key finder
+	 * @param getValue - a pure and functional function that returns the associated value of one or more anchor nodes, can be used to map and filter the indexed anchor nodes
+	 * so that the values returned from the index are more usable
+	 * @param checkTreeStatus - a function that gets the tree status from an anchor node, used for filtering out detached nodes
+	 */
+	public constructor(
+		private readonly forest: IForestSubscription,
+		private readonly indexer: (
+			schemaId: TreeNodeSchemaIdentifier,
+		) => KeyFinder<TKey> | undefined,
+		private readonly getValue: (anchorNodes: TreeIndexNodes<AnchorNode>) => TValue | undefined,
+		private readonly checkTreeStatus: (node: AnchorNode) => TreeStatus | undefined,
+	) {
+		this.forest.registerAnnouncedVisitor(this.keyFinder);
+
+		const detachedFieldKeys: FieldKey[] = [];
+		const detachedFieldsCursor = forest.getCursorAboveDetachedFields();
+		forEachField(detachedFieldsCursor, (field) => {
+			detachedFieldKeys.push(field.getFieldKey());
+		});
+
+		// index all existing trees (this includes the primary document tree and all other detached/removed trees)
+		for (const fieldKey of detachedFieldKeys) {
+			const cursor = forest.allocateCursor();
+			forest.tryMoveCursorToField({ fieldKey, parent: undefined }, cursor);
+			this.indexField(cursor);
+			cursor.free();
+		}
+	}
+
+	/**
+	 * Creates an announced visitor that responds to edits to the forest and updates the index accordingly.
+	 */
+	private acquireVisitor(): AnnouncedVisitor {
+		this.checkNotDisposed(
+			"visitor getter should be deregistered from the forest when index is disposed",
+		);
+		let parentField: FieldKey | undefined;
+		let parent: UpPath | undefined;
+
+		return createAnnouncedVisitor({
+			// nodes (and their entire subtrees) are added to the index as soon as they are created
+			afterCreate: (content: ProtoNodes, destination: FieldKey) => {
+				const detachedCursor = this.forest.allocateCursor();
+				assert(
+					this.forest.tryMoveCursorToField(
+						{ fieldKey: destination, parent: undefined },
+						detachedCursor,
+					) === TreeNavigationResult.Ok,
+					0xa8a /* destination of created nodes must be a valid detached field */,
+				);
+				this.indexField(detachedCursor);
+				detachedCursor.free();
+			},
+			// when a replace happens, the keys of previously indexed nodes could be changed so we must re-index them
+			afterReplace: () => {
+				assert(parent !== undefined, 0xa8b /* must have a parent */);
+				const cursor = this.forest.allocateCursor();
+				this.forest.moveCursorToPath(parent, cursor);
+				assert(
+					cursor.mode === CursorLocationType.Nodes,
+					0xa8c /* replace should happen in a node */,
+				);
+				cursor.exitNode();
+				// we must re-index the spine because the key finders allow for any value under a subtree to be the key
+				// this means that a replace can cause the key for any node up its spine to be changed
+				this.indexSpine(cursor);
+				cursor.clear();
+			},
+			// the methods below are used to keep track of the path that has been traversed by the visitor
+			// this is required so that cursors can be moved to the correct location when index updates are required
+			enterNode(index: number): void {
+				assert(parentField !== undefined, 0xa8d /* must be in a field to enter node */);
+
+				parent = {
+					parent,
+					parentField,
+					parentIndex: index,
+				};
+				parentField = undefined;
+			},
+			exitNode(index: number): void {
+				assert(parent !== undefined, 0xa8e /* must have parent node */);
+				const temp = parent;
+				parentField = temp.parentField;
+				parent = temp.parent;
+			},
+			enterField: (key: FieldKey) => {
+				parentField = key;
+			},
+			exitField(key: FieldKey): void {
+				parentField = undefined;
+			},
+		});
+	}
+
+	/**
+	 * Returns the value associated with the given key if it has been indexed
+	 */
+	public get(key: TKey): TValue | undefined {
+		this.checkNotDisposed();
+		return this.getFilteredValue(this.keyToNodes.get(key));
+	}
+
+	/**
+	 * Returns true iff the key exists in the index
+	 */
+	public has(key: TKey): boolean {
+		this.checkNotDisposed();
+		return this.get(key) !== undefined;
+	}
+
+	/**
+	 * Returns the number of values that are indexed
+	 */
+	public get size(): number {
+		this.checkNotDisposed();
+		let s = 0;
+		for (const nodes of this.keyToNodes.values()) {
+			if (this.getFilteredValue(nodes) !== undefined) {
+				s += 1;
+			}
+		}
+		return s;
+	}
+
+	/**
+	 * Returns all keys in the index
+	 */
+	public *keys(): IterableIterator<TKey> {
+		this.checkNotDisposed();
+		for (const [key, nodes] of this.keyToNodes.entries()) {
+			if (this.getFilteredValue(nodes) !== undefined) {
+				yield key;
+			}
+		}
+	}
+
+	/**
+	 * Returns an iterable of values in the index
+	 */
+	public *values(): IterableIterator<TValue> {
+		this.checkNotDisposed();
+		for (const nodes of this.keyToNodes.values()) {
+			const filtered = this.getFilteredValue(nodes);
+			if (filtered !== undefined) {
+				yield filtered;
+			}
+		}
+	}
+
+	/**
+	 * Returns an iterable of key, value pairs for every entry in the index
+	 */
+	public *entries(): IterableIterator<[TKey, TValue]> {
+		this.checkNotDisposed();
+		for (const [key, nodes] of this.keyToNodes.entries()) {
+			const filtered = this.getFilteredValue(nodes);
+			if (filtered !== undefined) {
+				yield [key, filtered];
+			}
+		}
+	}
+
+	public [Symbol.iterator](): IterableIterator<[TKey, TValue]> {
+		this.checkNotDisposed();
+		return this.entries();
+	}
+
+	/**
+	 * Applies the provided callback to each entry in the index.
+	 */
+	public forEach(
+		callbackfn: (value: TValue, key: TKey, map: AnchorTreeIndex<TKey, TValue>) => void,
+		thisArg?: unknown,
+	): void {
+		this.checkNotDisposed();
+		for (const [key, nodes] of this.keyToNodes.entries()) {
+			const filtered = this.getFilteredValue(nodes);
+			if (filtered !== undefined) {
+				callbackfn.call(thisArg, filtered, key, this);
+			}
+		}
+	}
+
+	/**
+	 * Returns an iterable of key, value pairs for every entry in the index, including ones that are detached.
+	 * This function should only be used for testing purposes, it is not exposed as part of the public {@link TreeIndex} API.
+	 */
+	public *allEntries(): IterableIterator<[TKey, TValue]> {
+		this.checkNotDisposed();
+		for (const [key, nodes] of this.keyToNodes.entries()) {
+			const value = this.getValue(nodes as unknown as TreeIndexNodes<AnchorNode>);
+			if (value !== undefined) {
+				yield [key, value];
+			}
+		}
+	}
+
+	public dispose(): void {
+		this[disposeSymbol]();
+	}
+
+	/**
+	 * Disposes this index and all the anchors it holds onto.
+	 */
+	public [disposeSymbol](): void {
+		this.checkNotDisposed("index is already disposed");
+		for (const anchors of this.anchors.values()) {
+			for (const anchor of anchors) {
+				this.forest.forgetAnchor(anchor);
+			}
+		}
+		this.keyToNodes.clear();
+		this.anchors.clear();
+		this.forest.deregisterAnnouncedVisitor(this.keyFinder);
+		this.disposed = true;
+	}
+
+	private checkNotDisposed(errorMessage?: string): void {
+		if (this.disposed) {
+			if (errorMessage !== undefined) {
+				throw new Error(errorMessage);
+			}
+			assert(false, 0xa8f /* invalid operation on a disposed index */);
+		}
+	}
+
+	/**
+	 * Given a cursor in node mode, indexes it.
+	 */
+	private indexNode(nodeCursor: ITreeSubscriptionCursor): void {
+		const keyFinder = getOrCreate(
+			this.keyFinders,
+			// the node schema type to look up
+			nodeCursor.type,
+			// if the indexer does not return a key finder for this schema, we cache a null value to indicate the indexer
+			// does not need to be called if this schema is encountered in the future
+			(schema) => this.indexer(schema) ?? null,
+		);
+
+		if (keyFinder !== null) {
+			const expectedPath = nodeCursor.getPath();
+			const key = keyFinder(nodeCursor);
+			// TODO: determine perf impact of this check, alternative is not doing it in which case (if the key finder is not pure and functional),
+			// an error may be thrown further down the line if the structure of the nodes aren't expected or the contents of the index could be inaccurate
+			if (!compareUpPaths(nodeCursor.getPath(), expectedPath)) {
+				throw new Error("key finder should be pure and functional");
+			}
+			const anchor = nodeCursor.buildAnchor();
+			const anchorNode = this.forest.anchors.locate(anchor) ?? fail("expected anchor node");
+
+			// check if this anchor node already exists in the index
+			const existingKey = this.nodeToKey.get(anchorNode);
+			if (existingKey !== undefined) {
+				// if the node already exists but has the same key, we return early
+				if (existingKey === key) {
+					this.forest.forgetAnchor(anchor);
+					return;
+				} else {
+					// if the node has a different key, we remove the existing one first because it means the key had been detached
+					this.removeAnchor(anchorNode, existingKey);
+				}
+			}
+
+			getOrCreate(this.keyToNodes, key, () => []).push(anchorNode);
+			this.nodeToKey.set(anchorNode, key);
+
+			getOrCreate(this.anchors, anchorNode, () => []).push(anchor);
+			// when the anchor node is destroyed, delete it from the index
+			anchorNode.events.on("afterDestroy", () => {
+				this.removeAnchor(anchorNode, key);
+			});
+		}
+	}
+
+	/**
+	 * Given a cursor in field mode, recursively indexes all nodes under the field.
+	 */
+	private indexField(fieldCursor: ITreeSubscriptionCursor): void {
+		forEachNode(fieldCursor, (nodeCursor) => {
+			this.indexNode(nodeCursor);
+
+			forEachField(nodeCursor, (f) => {
+				this.indexField(f);
+			});
+		});
+	}
+
+	/**
+	 * Given a cursor in field mode, indexes all nodes under the field and then indexes all nodes up the spine.
+	 */
+	private indexSpine(cursor: ITreeSubscriptionCursor): void {
+		this.indexField(cursor);
+
+		if (keyAsDetachedField(cursor.getFieldKey()) !== rootField) {
+			cursor.exitField();
+			cursor.exitNode();
+		} else {
+			// return early if we're already at the root field
+			return;
+		}
+
+		// walk up the spine and index nodes until we reach the root
+		while (
+			cursor.mode === CursorLocationType.Fields &&
+			keyAsDetachedField(cursor.getFieldKey()) !== rootField
+		) {
+			forEachNode(cursor, (nodeCursor) => {
+				this.indexNode(nodeCursor);
+			});
+
+			cursor.exitField();
+			cursor.exitNode();
+		}
+	}
+
+	private removeAnchor(anchorNode: AnchorNode, key: TKey): void {
+		const indexedNodes = this.keyToNodes.get(key);
+		assert(
+			indexedNodes !== undefined,
+			0xa90 /* destroyed anchor node should be tracked by index */,
+		);
+		const index = indexedNodes.indexOf(anchorNode);
+		assert(index !== -1, 0xa91 /* destroyed anchor node should be tracked by index */);
+		const newNodes = filterNodes(indexedNodes, (n) => n !== anchorNode);
+		if (newNodes !== undefined && newNodes.length > 0) {
+			this.keyToNodes.set(key, newNodes);
+		} else {
+			this.keyToNodes.delete(key);
+		}
+		this.nodeToKey.delete(anchorNode);
+		assert(
+			this.anchors.delete(anchorNode),
+			0xa92 /* destroyed anchor should be tracked by index */,
+		);
+	}
+
+	/**
+	 * Filters out any anchor nodes that are detached and returns the value for the remaining nodes.
+	 */
+	private getFilteredValue(anchorNodes: AnchorNode[] | undefined): TValue | undefined {
+		const attachedNodes = filterNodes(anchorNodes, (anchorNode) => {
+			const nodeStatus = this.checkTreeStatus(anchorNode);
+			return nodeStatus === TreeStatus.InDocument;
+		});
+
+		if (attachedNodes !== undefined && hasElement(attachedNodes)) {
+			return this.getValue(attachedNodes);
+		}
+	}
+}
+
+/**
+ * Filters the given anchor nodes based on the given filter function.
+ */
+function filterNodes(
+	anchorNodes: readonly AnchorNode[] | undefined,
+	filter: (node: AnchorNode) => boolean,
+): AnchorNode[] | undefined {
+	if (anchorNodes !== undefined) {
+		return anchorNodes.filter(filter);
+	}
+
+	return undefined;
+}
+
+/**
+ * Checks that an array is of the type {@link TreeIndexNodes} and has at least one element.
+ */
+export function hasElement<T>(array: readonly T[]): array is TreeIndexNodes<T> {
+	return array.length >= 1;
+}

package/src/feature-libraries/indexing/index.ts

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	AnchorTreeIndex,
+	type KeyFinder,
+	hasElement,
+} from "./anchorTreeIndex.js";
+export type { TreeIndex, TreeIndexKey, TreeIndexNodes } from "./types.js";

package/src/feature-libraries/indexing/types.ts

@@ -0,0 +1,37 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+
+/**
+ * an array of nodes that is guaranteed to have at least one element
+ *
+ * @alpha
+ */
+export type TreeIndexNodes<TNode> = readonly [first: TNode, ...rest: TNode[]];
+
+/**
+ * Value that may be used as keys in a {@link TreeIndex}.
+ *
+ * @privateRemarks
+ * no-new-null is disabled for this type so that it supports the TreeValue type.
+ *
+ * @alpha
+ */
+// eslint-disable-next-line @rushstack/no-new-null
+export type TreeIndexKey = number | string | boolean | IFluidHandle | null;
+
+/**
+ * A index where values are keyed on {@link TreeIndexKey}s.
+ *
+ * @alpha
+ */
+export interface TreeIndex<TKey extends TreeIndexKey, TValue>
+	extends ReadonlyMap<TKey, TValue> {
+	/**
+	 * Disposes the index such that it can no longer be used and receives no updates from the forest
+	 */
+	dispose(): void;
+}

package/src/feature-libraries/object-forest/objectForest.ts

@@ -4,10 +4,13 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable } from "@fluidframework/core-interfaces";
 
 import {
 	type Anchor,
 	AnchorSet,
+	type AnnouncedVisitor,
 	type CursorLocationType,
 	type DeltaVisitor,
 	type DetachedField,
@@ -31,9 +34,9 @@ import {
 	type UpPath,
 	type Value,
 	aboveRootPlaceholder,
+	combineVisitors,
 	deepCopyMapTree,
 } from "../../core/index.js";
-import { createEmitter, type Listenable } from "../../events/index.js";
 import {
 	assertNonNegativeSafeInteger,
 	assertValidIndex,
@@ -72,6 +75,7 @@ export class ObjectForest implements IEditableForest {
 
 	// All cursors that are in the "Current" state. Must be empty when editing.
 	public readonly currentCursors: Set<Cursor> = new Set();
+	private readonly deltaVisitors: Set<() => AnnouncedVisitor> = new Set();
 
 	readonly #events = createEmitter<ForestEvents>();
 	public readonly events: Listenable<ForestEvents> = this.#events;
@@ -254,9 +258,23 @@ export class ObjectForest implements IEditableForest {
 			}
 		}
 
-		const visitor = new Visitor(this);
-		this.activeVisitor = visitor;
-		return visitor;
+		const forestVisitor = new Visitor(this);
+		const announcedVisitors: AnnouncedVisitor[] = [];
+		this.deltaVisitors.forEach((getVisitor) => announcedVisitors.push(getVisitor()));
+		const combinedVisitor = combineVisitors(
+			[forestVisitor, ...announcedVisitors],
+			announcedVisitors,
+		);
+		this.activeVisitor = combinedVisitor;
+		return combinedVisitor;
+	}
+
+	public registerAnnouncedVisitor(visitor: () => AnnouncedVisitor): void {
+		this.deltaVisitors.add(visitor);
+	}
+
+	public deregisterAnnouncedVisitor(visitor: () => AnnouncedVisitor): void {
+		this.deltaVisitors.delete(visitor);
 	}
 
 	private nextRange = 0;

package/src/feature-libraries/sequence-field/invert.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase, oob } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import type { RevisionTag } from "../../core/index.js";
-import { type IdAllocator, type Mutable, fail } from "../../util/index.js";
+import { type IdAllocator, type Mutable, fail, hasSingle } from "../../util/index.js";
 import {
 	type CrossFieldManager,
 	CrossFieldTarget,
@@ -257,11 +257,11 @@ function invertMark(
 			}
 
 			assert(
-				detachInverses.length === 1,
+				hasSingle(detachInverses),
 				0x80d /* Only expected MoveIn marks to be split when inverting */,
 			);
 
-			let detachInverse = detachInverses[0] ?? oob();
+			let detachInverse = detachInverses[0];
 			assert(isAttach(detachInverse), 0x80e /* Inverse of a detach should be an attach */);
 
 			const inverses: Mark[] = [];

package/src/feature-libraries/sequence-field/sequenceFieldToDelta.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase, oob } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import {
 	type DeltaDetachedNodeChanges,
@@ -12,7 +12,7 @@ import {
 	type DeltaMark,
 	areEqualChangeAtomIds,
 } from "../../core/index.js";
-import type { Mutable } from "../../util/index.js";
+import { getLast, hasSome, type Mutable } from "../../util/index.js";
 import { nodeIdFromChangeAtom } from "../deltaUtils.js";
 
 import { isMoveIn, isMoveOut } from "./moveEffectTable.js";
@@ -176,8 +176,8 @@ export function sequenceFieldToDelta(
 		}
 	}
 	// Remove trailing no-op marks
-	while (local.length > 0) {
-		const lastMark = local[local.length - 1] ?? oob();
+	while (hasSome(local)) {
+		const lastMark = getLast(local);
 		if (
 			lastMark.attach !== undefined ||
 			lastMark.detach !== undefined ||

package/src/index.ts

@@ -29,19 +29,24 @@ export {
 	MapNodeStoredSchema,
 	LeafNodeStoredSchema,
 	type RevertibleFactory,
+	type RevertibleAlphaFactory,
+	type RevertibleAlpha,
 } from "./core/index.js";
 export { type Brand } from "./util/index.js";
 
-export {
-	type Listeners,
-	type IsListener,
-	type Listenable,
-	type Off,
-} from "./events/index.js";
+export type {
+	Listeners,
+	IsListener,
+	Listenable,
+	Off,
+} from "@fluidframework/core-interfaces";
 
 export {
 	TreeStatus,
 	TreeCompressionStrategy,
+	type TreeIndex,
+	type TreeIndexKey,
+	type TreeIndexNodes,
 } from "./feature-libraries/index.js";
 
 export {
@@ -126,6 +131,11 @@ export {
 	// Recursive Schema APIs
 	type ValidateRecursiveSchema,
 	type FixRecursiveArraySchema,
+	// Index APIs
+	type SimpleTreeIndex,
+	type IdentifierIndex,
+	createSimpleTreeIndex,
+	createIdentifierIndex,
 	// experimental @alpha APIs:
 	adaptEnum,
 	enumFromStrings,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.10.0";
+export const pkgVersion = "2.11.0";

package/src/shared-tree/index.ts

@@ -22,9 +22,7 @@ export {
 	createTreeCheckout,
 	TreeCheckout,
 	type ITreeCheckout,
-	runSynchronous,
 	type CheckoutEvents,
-	type ITransaction,
 	type ITreeCheckoutFork,
 	type BranchableTree,
 	type TreeBranchFork,