@fluid-experimental/tree 0.58.2002 → 0.58.3000-61081

package/src/PayloadUtilities.ts

@@ -0,0 +1,124 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IFluidHandle } from '@fluidframework/core-interfaces';
+import { compareArrays } from './Common';
+import { Payload } from './persisted-types';
+
+/**
+ * @returns true if two `Payloads` are identical.
+ * May return false for equivalent payloads encoded differently.
+ *
+ * Object field order and object identity are not considered significant, and are ignored by this function.
+ * (This is because they may not be preserved through roundtrip).
+ *
+ * For other information which Fluid would lose on serialization round trip,
+ * behavior is unspecified other than this this function is reflective (all payloads are equal to themselves)
+ * and commutative (argument order does not matter).
+ *
+ * This means that any Payload is equal to itself and a deep clone of itself.
+ *
+ * Payloads might not be equal to a version of themselves that has been serialized then deserialized.
+ * If they are serialized then deserialized again, the two deserialized objects will compare equal,
+ * however the serialized strings may be unequal (due to field order for objects being unspecified).
+ *
+ * Fluid will cause lossy operations due to use of JSON.stringify().
+ * This includes:
+ * - Loss of object identity
+ * - Loss of field order (may be ordered arbitrarily)
+ * - -0 becomes +0
+ * - NaN, Infinity, -Infinity all become null
+ * - custom toJSON functions may cause arbitrary behavior
+ * - functions become undefined or null
+ * - non enumerable properties (including prototype) are lost
+ * - more (this is not a complete list)
+ *
+ * Inputs must not contain cyclic references other than fields set to their immediate parent (for the JavaScript feature detection pattern).
+ *
+ * IFluidHandle instances (detected via JavaScript feature detection pattern) are only compared by absolutePath.
+ *
+ * TODO:#54095: Is there a better way to do this comparison?
+ * @public
+ */
+export function comparePayloads(a: Payload, b: Payload): boolean {
+	// === is not reflective because of how NaN is handled, so use Object.is instead.
+	// This treats -0 and +0 as different.
+	// Since -0 is not preserved in serialization round trips,
+	// it can be handed in any way that is reflective and commutative, so this is fine.
+	if (Object.is(a, b)) {
+		return true;
+	}
+
+	// Primitives which are equal would have early returned above, so now if the values are not both objects, they are unequal.
+	if (typeof a !== 'object' || typeof b !== 'object') {
+		return false;
+	}
+
+	// null is of type object, and needs to be treated as distinct from the empty object.
+	// Handling it early also avoids type errors trying to access its keys.
+	// Rationale: 'undefined' payloads are reserved for future use (see 'SetValue' interface).
+	if (a === null || b === null) {
+		return false;
+	}
+
+	// Special case IFluidHandles, comparing them only by their absolutePath
+	// Detect them using JavaScript feature detection pattern: they have a `IFluidHandle` field that is set to the parent object.
+	{
+		const aHandle = a as IFluidHandle;
+		const bHandle = b as IFluidHandle;
+		if (aHandle.IFluidHandle === a) {
+			if (bHandle.IFluidHandle !== b) {
+				return false;
+			}
+			return a.absolutePath === b.absolutePath;
+		}
+	}
+
+	// Fluid Serialization (like Json) only keeps enumerable properties, so we can ignore non-enumerable ones.
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+
+	if (aKeys.length !== bKeys.length) {
+		return false;
+	}
+
+	// make sure objects with numeric keys (or no keys) compare unequal to arrays.
+	if (a instanceof Array !== b instanceof Array) {
+		return false;
+	}
+
+	// Fluid Serialization (like Json) orders object fields arbitrarily, so reordering fields is not considered considered a change.
+	// Therefor the keys arrays must be sorted here.
+	if (!(a instanceof Array)) {
+		aKeys.sort();
+		bKeys.sort();
+	}
+
+	// First check keys are equal.
+	// This will often early exit, and thus is worth doing as a separate pass than recursive check.
+	if (!compareArrays(aKeys, bKeys)) {
+		return false;
+	}
+
+	for (let i = 0; i < aKeys.length; i++) {
+		const aItem: Payload = a[aKeys[i]];
+		const bItem: Payload = b[bKeys[i]];
+
+		// The JavaScript feature detection pattern, used for IFluidHandle, uses a field that is set to the parent object.
+		// Detect this pattern and special case it to avoid infinite recursion.
+		const aSelf = Object.is(aItem, a);
+		const bSelf = Object.is(bItem, b);
+		if (aSelf !== bSelf) {
+			return false;
+		}
+		if (!aSelf) {
+			if (!comparePayloads(aItem, bItem)) {
+				return false;
+			}
+		}
+	}
+
+	return true;
+}

package/src/ReconciliationPath.ts

@@ -3,15 +3,18 @@
  * Licensed under the MIT License.
  */
 
-import { Snapshot } from './Snapshot';
+import { ChangeInternal } from './persisted-types';
+import { TransactionView } from './RevisionView';
+import { TreeView } from './TreeView';
 
 /**
- * The path of edits from the snapshot where a change was meant to have been applied to the snapshot where the edit that contains the change
- * is actually applied.
+ * The path of edits from the revision view where a change was meant to have been applied to the view where the edit that contains the
+ * change is actually applied.
  * The path only contains edits that were successfully applied.
  * This path is always empty for a change that has no concurrent edits.
+ * @public
  */
-export interface ReconciliationPath<TChange> {
+export interface ReconciliationPath {
 	/**
 	 * The number of edits in the path.
 	 */
@@ -20,21 +23,22 @@ export interface ReconciliationPath<TChange> {
 	 * Allows access to edit information.
 	 * @returns Reconciliation information for the edit at the given `index`.
 	 */
-	readonly [index: number]: ReconciliationEdit<TChange>;
+	readonly [index: number]: ReconciliationEdit;
 }
 
 /**
  * An edit in the `ReconciliationPath`.
+ * @public
  */
-export interface ReconciliationEdit<TChange> {
+export interface ReconciliationEdit {
 	/**
 	 * The state before the edit was applied.
 	 */
-	readonly before: Snapshot;
+	readonly before: TreeView;
 	/**
 	 * The state after the edit was applied.
 	 */
-	readonly after: Snapshot;
+	readonly after: TreeView;
 	/**
 	 * The number of changes in the edit.
 	 */
@@ -43,20 +47,21 @@ export interface ReconciliationEdit<TChange> {
 	 * Allows access to change information.
 	 * @returns Reconciliation information for the change at the given `index`.
 	 */
-	readonly [index: number]: ReconciliationChange<TChange>;
+	readonly [index: number]: ReconciliationChange;
 }
 
 /**
  * A change in the `ReconciliationPath`.
+ * @public
  */
-export interface ReconciliationChange<TChange> {
+export interface ReconciliationChange {
 	/**
 	 * The resolved change that was applied during the edit.
 	 * Resolved changes are guaranteed to be expressed with valid tree locations instead of anchors that need resolution.
 	 */
-	readonly resolvedChange: TChange;
+	readonly resolvedChange: ChangeInternal;
 	/**
-	 * The resulting snapshot state from applying the resolved change.
+	 * The resulting view from applying the resolved change.
 	 */
-	readonly after: Snapshot;
+	readonly after: TransactionView;
 }

package/src/RevisionValueCache.ts

@@ -5,9 +5,17 @@
 
 import BTree from 'sorted-btree';
 import LRU from 'lru-cache';
-import { assert, fail } from './Common';
-import { Revision } from './LogViewer';
-import { compareFiniteNumbers } from './SnapshotUtilities';
+import { assert, fail, compareFiniteNumbers } from './Common';
+
+/**
+ * A revision corresponds to an index in an `EditLog`.
+ *
+ * It is associated with the output `RevisionView` of applying the edit at the index to the previous revision.
+ * For example:
+ *  - revision 0 corresponds to the initialRevision.
+ *  - revision 1 corresponds to the output of editLog[0] applied to the initialRevision.
+ */
+export type Revision = number;
 
 /**
  * A cache of `TValue`s corresponding to `Revision`s.
@@ -27,9 +35,10 @@ export class RevisionValueCache<TValue> {
 	private readonly sortedEntries = new BTree<Revision, TValue>(undefined, compareFiniteNumbers);
 
 	/**
-	 * Least recently used cache of evictable entries.
+	 * Cache of most recently used evictable entries.
 	 * Subset of 'sortedValues` eligible for eviction:
 	 * All entries are also in `sortedValues`, and are removed from `sortedValues` when evicted from this cache.
+	 * Evicts least recently used entries.
 	 */
 	private readonly evictableRevisions: LRU<Revision, TValue>;
 
@@ -115,7 +124,7 @@ export class RevisionValueCache<TValue> {
 		if (fromLRU !== undefined) {
 			return [requestedRevision, fromLRU];
 		}
-		return this.sortedEntries.nextLowerPair(requestedRevision + 1) ?? undefined;
+		return this.sortedEntries.getPairOrNextLower(requestedRevision) ?? undefined;
 	}
 
 	/**

package/src/RevisionView.ts

@@ -0,0 +1,252 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { copyPropertyIfDefined, fail, Mutable, MutableMap } from './Common';
+import { Forest } from './Forest';
+import { NodeId, StableNodeId, TraitLabel } from './Identifiers';
+import { NodeIdConverter } from './NodeIdUtilities';
+import { Payload, TreeNode, TreeNodeSequence } from './persisted-types';
+import { TreeView, TreeViewNode, TreeViewPlace, TreeViewRange } from './TreeView';
+import { HasVariadicTraits } from './ChangeTypes';
+
+/**
+ * An immutable view of a distributed tree.
+ * @public
+ */
+export class RevisionView extends TreeView {
+	/**
+	 * Constructs a {@link RevisionView} using the supplied tree.
+	 * @param root - the root of the tree to use as the contents of the {@link RevisionView}
+	 * @param expensiveValidation - whether or not to perform additional validation, e.g. to catch errors when testing
+	 */
+	public static fromTree<T extends TreeNode<T, NodeId>>(root: T, expensiveValidation?: boolean): RevisionView;
+	/**
+	 * Constructs a {@link RevisionView} using the supplied tree.
+	 * @param root - the root of the tree to use as the contents of the `RevisionView`
+	 * @param idConverter - the {@link NodeIdConverter} that will recompress the IDs the in the tree
+	 * @param expensiveValidation - whether or not to perform additional validation, e.g. to catch errors when testing
+	 */
+	public static fromTree<T extends TreeNode<T, StableNodeId>>(
+		root: T,
+		idConverter: NodeIdConverter,
+		expensiveValidation?: boolean
+	): RevisionView;
+
+	public static fromTree<T extends TreeNode<T, NodeId> | TreeNode<T, StableNodeId>>(
+		root: T,
+		idConverterOrExpensiveValidation?: NodeIdConverter | boolean,
+		expensiveValidation = false
+	): RevisionView {
+		if (typeof idConverterOrExpensiveValidation === 'object') {
+			const rootId = idConverterOrExpensiveValidation.convertToNodeId(root.identifier as StableNodeId);
+
+			const treeViewNodes = convertTreeNodesToViewNodes(root, (node) => {
+				const identifier = idConverterOrExpensiveValidation.convertToNodeId(node.identifier as StableNodeId);
+				const viewNode = {
+					definition: node.definition,
+					identifier,
+				};
+				copyPropertyIfDefined(node, viewNode, 'payload');
+				return viewNode;
+			});
+
+			return new RevisionView(rootId, Forest.create(expensiveValidation).add(treeViewNodes));
+		} else {
+			return new RevisionView(
+				root.identifier as NodeId,
+				Forest.create(expensiveValidation).add(
+					convertTreeNodesToViewNodes(root, (node) => {
+						const viewNode = {
+							definition: node.definition,
+							identifier: node.identifier as NodeId,
+						};
+						copyPropertyIfDefined(node, viewNode, 'payload');
+						return viewNode;
+					})
+				)
+			);
+		}
+	}
+
+	/** Begin a transaction by generating a mutable `TransactionView` from this view */
+	public openForTransaction(): TransactionView {
+		return new TransactionView(this.root, this.forest);
+	}
+
+	public equals(view: TreeView): boolean {
+		if (!(view instanceof RevisionView)) {
+			return false;
+		}
+
+		return this.hasEqualForest(view);
+	}
+}
+
+/**
+ * An view of a distributed tree that is part of an ongoing transaction between `RevisionView`s.
+ * @public
+ */
+export class TransactionView extends TreeView {
+	/** Conclude a transaction by generating an immutable `RevisionView` from this view */
+	public close(): RevisionView {
+		return new RevisionView(this.root, this.forest);
+	}
+
+	/** Inserts all nodes in a NodeSequence into the view */
+	public addNodes(sequence: Iterable<TreeViewNode>): TransactionView {
+		return new TransactionView(this.root, this.forest.add(sequence));
+	}
+
+	/** Remove all nodes with the given ids from the view */
+	public deleteNodes(nodes: Iterable<NodeId>): TransactionView {
+		return new TransactionView(this.root, this.forest.delete(nodes, true));
+	}
+
+	/**
+	 * Parents a set of detached nodes at a specified place.
+	 * @param nodesToAttach - the nodes to parent in the specified place. The nodes must already be present in the view.
+	 * @param place - the location to insert the nodes.
+	 */
+	public attachRange(nodesToAttach: readonly NodeId[], place: TreeViewPlace): TransactionView {
+		const { parent, label } = place.trait;
+		const index = this.findIndexWithinTrait(place);
+		return new TransactionView(this.root, this.forest.attachRangeOfChildren(parent, label, index, nodesToAttach));
+	}
+
+	/**
+	 * Detaches a range of nodes from their parent. The detached nodes remain in the view.
+	 * @param rangeToDetach - the range of nodes to detach
+	 */
+	public detachRange(rangeToDetach: TreeViewRange): { view: TransactionView; detached: readonly NodeId[] } {
+		const { start, end } = rangeToDetach;
+		const { trait: traitLocation } = start;
+		const { parent, label } = traitLocation;
+		const startIndex = this.findIndexWithinTrait(start);
+		const endIndex = this.findIndexWithinTrait(end);
+		const { forest, detached } = this.forest.detachRangeOfChildren(parent, label, startIndex, endIndex);
+		return { view: new TransactionView(this.root, forest), detached };
+	}
+
+	/**
+	 * Sets or overwrites a node's value. The node must exist in this view.
+	 * @param nodeId - the id of the node
+	 * @param value - the new value
+	 */
+	public setNodeValue(nodeId: NodeId, value: Payload): TransactionView {
+		return new TransactionView(this.root, this.forest.setValue(nodeId, value));
+	}
+
+	public equals(view: TreeView): boolean {
+		if (!(view instanceof TransactionView)) {
+			return false;
+		}
+
+		return this.hasEqualForest(view);
+	}
+}
+
+/**
+ * Transform an input tree into a list of {@link TreeViewNode}s.
+ * @param tree - the input tree
+ * @param convert - a conversion function that will run on each node in the input tree to produce the output nodes.
+ * Returning undefined means that conversion for the given node was impossible, at which time the entire tree conversion will be aborted
+ * and return undefined.
+ */
+export function convertTreeNodesToViewNodes<
+	TIn extends HasVariadicTraits<TIn>,
+	TOut extends TreeViewNode = TreeViewNode
+>(root: TIn, convert: (node: TIn) => Omit<TOut, 'traits'>): TOut[];
+
+/**
+ * Transform an input tree into a list of {@link TreeViewNode}s.
+ * @param tree - the input tree
+ * @param convert - a conversion function that will run on each node in the input tree to produce the output nodes.
+ */
+export function convertTreeNodesToViewNodes<
+	TIn extends HasVariadicTraits<TIn>,
+	TOut extends TreeViewNode = TreeViewNode
+>(root: TIn, convert: (node: TIn) => Omit<TOut, 'traits'> | undefined): TOut[] | undefined;
+
+/**
+ * Transform an input tree into a list of {@link TreeViewNode}s.
+ * @param tree - the input tree
+ * @param convert - a conversion function that will run on each node in the input tree to produce the output nodes.
+ * Returning undefined means that conversion for the given node was impossible, at which time the entire tree conversion will be aborted
+ * and return undefined.
+ */
+export function convertTreeNodesToViewNodes<
+	TIn extends HasVariadicTraits<TIn>,
+	TOut extends TreeViewNode = TreeViewNode
+>(root: TIn, convert: (node: TIn) => Omit<TOut, 'traits'> | undefined): TOut[] | undefined {
+	const convertedRoot = convert(root) as Mutable<TOut>;
+	if (convertedRoot === undefined || root.traits === undefined) {
+		return undefined;
+	}
+	// `convertedRoot` might be the same as `root`, in which case stash the children of `root` before wiping them from `convertedRoot`
+	const rootTraits = (root as unknown as TOut) === convertedRoot ? { traits: root.traits } : root;
+	convertedRoot.traits = new Map();
+	const pendingNodes: {
+		childIterator: Iterator<[TraitLabel, TIn]>;
+		newNode: Mutable<TOut>;
+	}[] = [{ childIterator: iterateChildren(rootTraits)[Symbol.iterator](), newNode: convertedRoot }];
+	const resultNodes: TOut[] = [];
+
+	while (pendingNodes.length > 0) {
+		const { childIterator, newNode } = pendingNodes[pendingNodes.length - 1] ?? fail('Undefined node');
+		const { value, done } = childIterator.next();
+		if (done === true) {
+			resultNodes.push(
+				pendingNodes.pop()?.newNode ?? fail('covertTreeNodesToViewNodes incorrectly coordinated parentage')
+			);
+		} else {
+			const [traitLabel, child] = value as [TraitLabel, TIn];
+			const convertedChild = convert(child) as TOut;
+			if (convertedChild === undefined) {
+				return undefined;
+			}
+			if (child.traits !== undefined) {
+				const childTraits = (child as unknown as TOut) === convertedChild ? { traits: child.traits } : child;
+				(convertedChild as Mutable<TOut>).traits = new Map();
+				pendingNodes.push({
+					childIterator: iterateChildren(childTraits)[Symbol.iterator](),
+					newNode: convertedChild,
+				});
+			}
+
+			const newTraits = newNode.traits as MutableMap<TOut['traits']>;
+			let newTrait = newTraits.get(traitLabel);
+			if (newTrait === undefined) {
+				newTrait = [];
+				newTraits.set(traitLabel, newTrait);
+			}
+			(newTrait as NodeId[]).push(convertedChild.identifier);
+		}
+	}
+
+	return resultNodes;
+}
+
+/**
+ * Returns an iterable of the supplied node's traits in a stable order.
+ */
+export function* iterateChildren<T>(hasTraits: HasVariadicTraits<T>): Iterable<[TraitLabel, T]> {
+	if (hasTraits.traits !== undefined) {
+		for (const [label, trait] of Object.entries(hasTraits.traits).sort()) {
+			if (trait !== undefined) {
+				if (isTreeNodeSequence(trait)) {
+					for (const child of trait) {
+						yield [label as TraitLabel, child];
+					}
+				} else {
+					yield [label as TraitLabel, trait];
+				}
+			}
+		}
+	}
+}
+
+function isTreeNodeSequence<TChild>(sequence: TreeNodeSequence<TChild> | TChild): sequence is TreeNodeSequence<TChild> {
+	return Array.isArray(sequence);
+}

package/src/SerializationUtilities.ts

@@ -0,0 +1,130 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { copyPropertyIfDefined, memoizeGetter } from './Common';
+import { NodeId, TraitLabel } from './Identifiers';
+import { NodeIdConverter } from './NodeIdUtilities';
+import { ChangeNode, ChangeNode_0_0_2, TraitMap } from './persisted-types';
+import { TreeView } from './TreeView';
+
+/**
+ * Converts this tree view to an equivalent `ChangeNode`.
+ * @param view - the view to convert
+ */
+export function getChangeNodeFromView(view: TreeView): ChangeNode {
+	return getChangeNodeFromViewNode(view, view.root);
+}
+
+/**
+ * Converts a node in this tree view to an equivalent `ChangeNode`.
+ * @param view - the view of the tree that contains the node to convert
+ * @param id - the id of the node to convert
+ * @param lazyTraits - whether or not traits should be populated lazily. If true, the subtrees under each trait will not be read until
+ * the trait is first accessed.
+ */
+export function getChangeNodeFromViewNode(view: TreeView, id: NodeId, lazyTraits = false): ChangeNode {
+	const node = view.getViewNode(id);
+	const nodeData = {
+		definition: node.definition,
+		identifier: node.identifier,
+	};
+	copyPropertyIfDefined(node, nodeData, 'payload');
+
+	if (lazyTraits) {
+		return {
+			...nodeData,
+			get traits() {
+				return memoizeGetter(this, 'traits', makeTraits(view, node.traits, lazyTraits));
+			},
+		};
+	}
+
+	return {
+		...nodeData,
+		traits: makeTraits(view, node.traits, lazyTraits),
+	};
+}
+
+/** Given the traits of a TreeViewNode, return the corresponding traits on a Node */
+function makeTraits(
+	view: TreeView,
+	traits: ReadonlyMap<TraitLabel, readonly NodeId[]>,
+	lazyTraits = false
+): TraitMap<ChangeNode> {
+	const traitMap = {};
+	for (const [label, trait] of traits.entries()) {
+		if (lazyTraits) {
+			Object.defineProperty(traitMap, label, {
+				get() {
+					const treeNodeTrait = trait.map((id) => getChangeNodeFromViewNode(view, id, lazyTraits));
+					return memoizeGetter(this as TraitMap<ChangeNode>, label, treeNodeTrait);
+				},
+				configurable: true,
+				enumerable: true,
+			});
+		} else {
+			Object.defineProperty(traitMap, label, {
+				value: trait.map((id) => getChangeNodeFromViewNode(view, id, lazyTraits)),
+				enumerable: true,
+			});
+		}
+	}
+
+	return traitMap;
+}
+
+/**
+ * Converts this tree view to an equivalent `ChangeNode`.
+ * @param view - the view to convert
+ */
+export function getChangeNode_0_0_2FromView(view: TreeView, idConverter: NodeIdConverter): ChangeNode_0_0_2 {
+	return getChangeNode_0_0_2FromViewNode(view, view.root, idConverter);
+}
+
+/**
+ * Converts a node in this tree view to an equivalent `ChangeNode`.
+ * @param view - the view of the tree that contains the node to convert
+ * @param id - the id of the node to convert
+ * @param lazyTraits - whether or not traits should be populated lazily. If true, the subtrees under each trait will not be read until
+ * the trait is first accessed.
+ * @deprecated Remove by March 2022
+ */
+export function getChangeNode_0_0_2FromViewNode(
+	view: TreeView,
+	id: NodeId,
+	idConverter: NodeIdConverter
+): ChangeNode_0_0_2 {
+	const node = view.getViewNode(id);
+	const nodeData = {
+		definition: node.definition,
+		identifier: idConverter.convertToStableNodeId(node.identifier),
+	};
+	copyPropertyIfDefined(node, nodeData, 'payload');
+
+	return {
+		...nodeData,
+		traits: makeTraits_0_0_2(view, node.traits, idConverter),
+	};
+}
+
+/**
+ * Given the traits of a TreeViewNode, return the corresponding traits on a Node
+ * @deprecated Remove by march 2022
+ */
+function makeTraits_0_0_2(
+	view: TreeView,
+	traits: ReadonlyMap<TraitLabel, readonly NodeId[]>,
+	idConverter: NodeIdConverter
+): TraitMap<ChangeNode_0_0_2> {
+	const traitMap = {};
+	for (const [label, trait] of traits.entries()) {
+		Object.defineProperty(traitMap, label, {
+			value: trait.map((id) => getChangeNode_0_0_2FromViewNode(view, id, idConverter)),
+			enumerable: true,
+		});
+	}
+
+	return traitMap;
+}