@fluidframework/tree 2.13.0 → 2.20.0

package/src/feature-libraries/optional-field/optionalField.ts

@@ -11,7 +11,6 @@ import {
 	type ChangesetLocalId,
 	type DeltaDetachedNodeChanges,
 	type DeltaDetachedNodeId,
-	type DeltaFieldChanges,
 	type DeltaMark,
 	type RevisionTag,
 	areEqualChangeAtomIds,
@@ -40,6 +39,7 @@ import {
 	type RelevantRemovedRootsFromChild,
 	type ToDelta,
 	type NestedChangesIndices,
+	type FieldChangeDelta,
 } from "../modular-schema/index.js";
 
 import type {
@@ -657,8 +657,8 @@ export const optionalFieldEditor: OptionalFieldEditor = {
 export function optionalFieldIntoDelta(
 	change: OptionalChangeset,
 	deltaFromChild: ToDelta,
-): DeltaFieldChanges {
-	const delta: Mutable<DeltaFieldChanges> = {};
+): FieldChangeDelta {
+	const delta: Mutable<FieldChangeDelta> = {};
 
 	let markIsANoop = true;
 	const mark: Mutable<DeltaMark> = { count: 1 };

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

@@ -101,7 +101,7 @@ export function getMoveEffect(
 	id: MoveId,
 	count: number,
 	addDependency: boolean = true,
-): RangeQueryResult<MoveEffect> {
+): RangeQueryResult<ChangeAtomId, MoveEffect> {
 	const result = moveEffects.get(target, revision, id, count, addDependency);
 	return result.value !== undefined
 		? { ...result, value: adjustMoveEffectBasis(result.value as MoveEffectWithBasis, id) }

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

@@ -545,9 +545,14 @@ function getMovedChangesFromBaseMark(
 	baseMark: Mark,
 ): NodeId | undefined {
 	if (isMoveIn(baseMark)) {
-		return getMovedNodeChanges(moveEffects, baseMark.revision, baseMark.id);
+		return getMovedNodeChanges(moveEffects, baseMark.revision, baseMark.id, baseMark.count);
 	} else if (isAttachAndDetachEffect(baseMark) && isMoveIn(baseMark.attach)) {
-		return getMovedNodeChanges(moveEffects, baseMark.attach.revision, baseMark.attach.id);
+		return getMovedNodeChanges(
+			moveEffects,
+			baseMark.attach.revision,
+			baseMark.attach.id,
+			baseMark.count,
+		);
 	} else {
 		return undefined;
 	}
@@ -557,7 +562,8 @@ function getMovedNodeChanges(
 	moveEffects: MoveEffectTable,
 	revision: RevisionTag | undefined,
 	id: MoveId,
+	count: number,
 ): NodeId | undefined {
-	return getMoveEffect(moveEffects, CrossFieldTarget.Destination, revision, id, 1).value
+	return getMoveEffect(moveEffects, CrossFieldTarget.Destination, revision, id, count).value
 		?.rebasedChanges;
 }

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

@@ -145,7 +145,7 @@ export function makeV1Codec(
 						context,
 					);
 				case NoopMarkType:
-					fail(`Mark type: ${type} should not be encoded.`);
+					fail("Mark type: NoopMarkType should not be encoded.");
 				default:
 					unreachableCase(type);
 			}

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

@@ -132,7 +132,7 @@ export function makeV2CodecHelpers(
 						context,
 					);
 				case NoopMarkType:
-					fail(`Mark type: ${type} should not be encoded.`);
+					fail("Mark type: NoopMarkType should not be encoded.");
 				default:
 					unreachableCase(type);
 			}

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

@@ -8,7 +8,6 @@ import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import {
 	type DeltaDetachedNodeChanges,
 	type DeltaDetachedNodeRename,
-	type DeltaFieldChanges,
 	type DeltaMark,
 	areEqualChangeAtomIds,
 } from "../../core/index.js";
@@ -25,12 +24,12 @@ import {
 	getInputCellId,
 	isAttachAndDetachEffect,
 } from "./utils.js";
-import type { ToDelta } from "../modular-schema/index.js";
+import type { FieldChangeDelta, ToDelta } from "../modular-schema/index.js";
 
 export function sequenceFieldToDelta(
 	change: MarkList,
 	deltaFromChild: ToDelta,
-): DeltaFieldChanges {
+): FieldChangeDelta {
 	const local: DeltaMark[] = [];
 	const global: DeltaDetachedNodeChanges[] = [];
 	const rename: DeltaDetachedNodeRename[] = [];
@@ -187,7 +186,7 @@ export function sequenceFieldToDelta(
 		}
 		local.pop();
 	}
-	const delta: Mutable<DeltaFieldChanges> = {};
+	const delta: Mutable<FieldChangeDelta> = {};
 	if (local.length > 0) {
 		delta.local = local;
 	}

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

@@ -942,13 +942,45 @@ function getCrossFieldKeysForMarkEffect(
 			// An insert behaves like a move where the source and destination are at the same location.
 			// An insert can become a move when after rebasing.
 			return [
-				[CrossFieldTarget.Source, effect.revision, effect.id, count],
-				[CrossFieldTarget.Destination, effect.revision, effect.id, count],
+				{
+					key: {
+						target: CrossFieldTarget.Source,
+						revision: effect.revision,
+						localId: effect.id,
+					},
+					count,
+				},
+				{
+					key: {
+						target: CrossFieldTarget.Destination,
+						revision: effect.revision,
+						localId: effect.id,
+					},
+					count,
+				},
 			];
 		case "MoveOut":
-			return [[CrossFieldTarget.Source, effect.revision, effect.id, count]];
+			return [
+				{
+					key: {
+						target: CrossFieldTarget.Source,
+						revision: effect.revision,
+						localId: effect.id,
+					},
+					count,
+				},
+			];
 		case "MoveIn":
-			return [[CrossFieldTarget.Destination, effect.revision, effect.id, count]];
+			return [
+				{
+					key: {
+						target: CrossFieldTarget.Destination,
+						revision: effect.revision,
+						localId: effect.id,
+					},
+					count,
+				},
+			];
 		case "AttachAndDetach":
 			return [
 				...getCrossFieldKeysForMarkEffect(effect.attach, count),

package/src/feature-libraries/treeCursorUtils.ts

@@ -20,6 +20,7 @@ import {
 	rootField,
 } from "../core/index.js";
 import { fail } from "../util/index.js";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * {@link ITreeCursorSynchronous} that can return the underlying node objects.
@@ -177,7 +178,11 @@ class StackCursor<TNode> extends SynchronousCursor implements CursorWithNode<TNo
 	public enterNode(index: number): void {
 		// assert(this.mode === CursorLocationType.Fields, "must be in fields mode");
 		const siblings = this.getField();
-		assert(index in siblings, 0x405 /* child must exist at index */);
+		if (!(index in siblings)) {
+			throw new UsageError(
+				"A child does not exist at the specified index, check the status of a node using `Tree.status()`.",
+			);
+		}
 		this.siblingStack.push(this.siblings);
 		this.indexStack.push(this.index);
 		this.index = index;

package/src/index.ts

@@ -14,13 +14,38 @@ export {
 	type RevertibleAlpha,
 } from "./core/index.js";
 
-export type {
-	Listeners,
-	IsListener,
-	Listenable,
-	Off,
+import type {
+	Listeners as EventListeners,
+	IsListener as EventIsListener,
+	Listenable as EventListenable,
+	Off as EventOff,
 } from "@fluidframework/core-interfaces";
 
+/**
+ * {@inheritdoc @fluidframework/core-interfaces#Listeners}
+ * @public
+ * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
+ */
+export type Listeners<T extends object> = EventListeners<T>;
+/**
+ * {@inheritdoc @fluidframework/core-interfaces#IsListener}
+ * @public
+ * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
+ */
+export type IsListener<T> = EventIsListener<T>;
+/**
+ * {@inheritdoc @fluidframework/core-interfaces#Listenable}
+ * @public
+ * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
+ */
+export type Listenable<T extends object> = EventListenable<T>;
+/**
+ * {@inheritdoc @fluidframework/core-interfaces#Off}
+ * @public
+ * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
+ */
+export type Off = EventOff;
+
 export {
 	TreeStatus,
 	TreeCompressionStrategy,
@@ -32,7 +57,7 @@ export {
 export {
 	type ITreeInternal,
 	type SharedTreeOptions,
-	ForestType,
+	type ForestType,
 	type SharedTreeFormatOptions,
 	SharedTreeFormatVersion,
 	Tree,
@@ -55,6 +80,9 @@ export {
 	type TransactionResultExt,
 	type TransactionResultSuccess,
 	type TransactionResultFailed,
+	ForestTypeOptimized,
+	ForestTypeExpensiveDebug,
+	ForestTypeReference,
 } from "./shared-tree/index.js";
 
 export {

package/src/packageVersion.ts

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

package/src/shared-tree/index.ts

@@ -9,7 +9,7 @@ export {
 	type SharedTreeOptions,
 	SharedTree,
 	getBranch,
-	ForestType,
+	type ForestType,
 	type SharedTreeContentSnapshot,
 	type SharedTreeFormatOptions,
 	SharedTreeFormatVersion,
@@ -17,6 +17,9 @@ export {
 	defaultSharedTreeOptions,
 	type ForestOptions,
 	type ITreeInternal,
+	ForestTypeOptimized,
+	ForestTypeExpensiveDebug,
+	ForestTypeReference,
 } from "./sharedTree.js";
 
 export {

package/src/shared-tree/sharedTree.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
-import type { IFluidHandle } from "@fluidframework/core-interfaces/internal";
+import { assert } from "@fluidframework/core-utils/internal";
+import type { ErasedType, IFluidHandle } from "@fluidframework/core-interfaces/internal";
 import type {
 	IChannelAttributes,
 	IChannelFactory,
@@ -186,30 +186,6 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 	return versions;
 }
 
-/**
- * Build and return a forest of the requested type.
- */
-export function buildConfiguredForest(
-	type: ForestType,
-	schema: TreeStoredSchemaSubscription,
-	idCompressor: IIdCompressor,
-): IEditableForest {
-	switch (type) {
-		case ForestType.Optimized:
-			return buildChunkedForest(
-				makeTreeChunker(schema, defaultSchemaPolicy),
-				undefined,
-				idCompressor,
-			);
-		case ForestType.Reference:
-			return buildForest();
-		case ForestType.Expensive:
-			return buildForest(undefined, true);
-		default:
-			unreachableCase(type);
-	}
-}
-
 /**
  * Shared tree, configured with a good set of indexes and field kinds which will maintain compatibility over time.
  *
@@ -596,26 +572,70 @@ export interface SharedTreeFormatOptions {
 
 /**
  * Used to distinguish between different forest types.
+ * @remarks
+ * Current options are {@link ForestTypeReference}, {@link ForestTypeOptimized} and {@link ForestTypeExpensiveDebug}.
+ * @sealed @alpha
+ */
+export interface ForestType extends ErasedType<"ForestType"> {}
+
+/**
+ * Reference implementation of forest.
+ * @remarks
+ * A simple implementation with minimal complexity and moderate debuggability, validation and performance.
+ * @privateRemarks
+ * The "ObjectForest" forest type.
  * @alpha
  */
-export enum ForestType {
-	/**
-	 * The "ObjectForest" forest type.
-	 */
-	Reference = 0,
-	/**
-	 * The "ChunkedForest" forest type.
-	 */
-	Optimized = 1,
-	/**
-	 * The "ObjectForest" forest type with expensive asserts for debugging.
-	 */
-	Expensive = 2,
+export const ForestTypeReference = toForestType(() => buildForest());
+
+/**
+ * Optimized implementation of forest.
+ * @remarks
+ * A complex optimized forest implementation, which has minimal validation and debuggability to optimize for performance.
+ * Uses an internal representation optimized for size designed to scale to larger datasets with reduced overhead.
+ * @privateRemarks
+ * The "ChunkedForest" forest type.
+ * @alpha
+ */
+export const ForestTypeOptimized = toForestType(
+	(schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
+		buildChunkedForest(makeTreeChunker(schema, defaultSchemaPolicy), undefined, idCompressor),
+);
+
+/**
+ * Slow implementation of forest intended only for debugging.
+ * @remarks
+ * Includes validation with scales poorly.
+ * May be asymptotically slower than {@link ForestTypeReference}, and may perform very badly with larger data sizes.
+ * @privateRemarks
+ * The "ObjectForest" forest type with expensive asserts for debugging.
+ * @alpha
+ */
+export const ForestTypeExpensiveDebug = toForestType(() => buildForest(undefined, true));
+
+type ForestFactory = (
+	schema: TreeStoredSchemaSubscription,
+	idCompressor: IIdCompressor,
+) => IEditableForest;
+
+function toForestType(factory: ForestFactory): ForestType {
+	return factory as unknown as ForestType;
+}
+
+/**
+ * Build and return a forest of the requested type.
+ */
+export function buildConfiguredForest(
+	factory: ForestType,
+	schema: TreeStoredSchemaSubscription,
+	idCompressor: IIdCompressor,
+): IEditableForest {
+	return (factory as unknown as ForestFactory)(schema, idCompressor);
 }
 
 export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	jsonValidator: noopValidator,
-	forest: ForestType.Reference,
+	forest: ForestTypeReference,
 	treeEncodeType: TreeCompressionStrategy.Compressed,
 	formatVersion: SharedTreeFormatVersion.v3,
 	disposeForksAfterTransaction: true,

package/src/shared-tree/treeCheckout.ts

@@ -41,6 +41,7 @@ import {
 	type RevertibleAlphaFactory,
 	type RevertibleAlpha,
 	type GraphCommit,
+	isAncestor,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -605,21 +606,27 @@ export class TreeCheckout implements ITreeCheckoutFork {
 					revertible.dispose();
 				}
 			},
-			clone: (forkedBranch: TreeBranch) => {
-				if (forkedBranch === undefined) {
-					return this.createRevertible(revision, kind, checkout, onRevertibleDisposed);
-				}
-
+			clone: (targetBranch: TreeBranch) => {
 				// TODO:#23442: When a revertible is cloned for a forked branch, optimize to create a fork of a revertible branch once per revision NOT once per revision per checkout.
-				const forkedCheckout = getCheckout(forkedBranch);
+				const targetCheckout = getCheckout(targetBranch);
+
 				const revertibleBranch = this.revertibleCommitBranches.get(revision);
-				assert(
-					revertibleBranch !== undefined,
-					0xa82 /* change to revert does not exist on the given forked branch */,
-				);
-				forkedCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
+				if (revertibleBranch === undefined) {
+					throw new UsageError("Unable to clone a revertible that has been disposed.");
+				}
+
+				const commitToRevert = revertibleBranch.getHead();
+				const activeBranchHead = targetCheckout.#transaction.activeBranch.getHead();
+
+				if (isAncestor(commitToRevert, activeBranchHead, true) === false) {
+					throw new UsageError(
+						"Cannot clone revertible for a commit that is not present on the given branch.",
+					);
+				}
+
+				targetCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
 
-				return this.createRevertible(revision, kind, forkedCheckout, onRevertibleDisposed);
+				return this.createRevertible(revision, kind, targetCheckout, onRevertibleDisposed);
 			},
 			dispose: () => {
 				if (revertible.status === RevertibleStatus.Disposed) {

package/src/simple-tree/api/treeNodeApi.ts

@@ -174,7 +174,7 @@ export const treeNodeApi: TreeNodeApi = {
 								changedFields,
 								(field) =>
 									nodeSchema.storedKeyToPropertyKey.get(field) ??
-									fail(`Could not find stored key '${field}' in schema.`),
+									fail("Could not find stored key in schema."),
 							),
 						);
 						listener({ changedProperties });

package/src/simple-tree/arrayNode.ts

@@ -993,7 +993,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		if (!destinationField.context.isHydrated()) {
 			if (!(sourceField instanceof UnhydratedTreeSequenceField)) {
 				throw new UsageError(
-					"Cannot move elements from an unhydrated array to a hydrated array.",
+					"Cannot move elements from a hydrated array to an unhydrated array.",
 				);
 			}
 

package/src/simple-tree/toMapTree.ts

@@ -196,7 +196,7 @@ function nodeDataToMapTree(
 			result = objectToMapTree(data, schema);
 			break;
 		default:
-			fail(`Unrecognized schema kind: ${schema.kind}.`);
+			fail("Unrecognized schema kind");
 	}
 
 	return result;

package/src/util/bTreeUtils.ts

@@ -0,0 +1,60 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { BTree } from "@tylerbu/sorted-btree-es6";
+import { brand, type Brand } from "./brand.js";
+
+export type TupleBTree<K, V> = Brand<BTree<K, V>, "TupleBTree">;
+
+export function newTupleBTree<K extends readonly unknown[], V>(
+	entries?: [K, V][],
+): TupleBTree<K, V> {
+	return brand(new BTree<K, V>(entries, compareTuples));
+}
+
+// This assumes that the arrays are the same length.
+function compareTuples(arrayA: readonly unknown[], arrayB: readonly unknown[]): number {
+	for (let i = 0; i < arrayA.length; i++) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const a = arrayA[i] as any;
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const b = arrayB[i] as any;
+
+		// Less-than and greater-than always return false if either value is undefined,
+		// so we handle undefined separately, treating it as less than all other values.
+		if (a === undefined && b !== undefined) {
+			return -1;
+		} else if (b === undefined && a !== undefined) {
+			return 1;
+		} else if (a < b) {
+			return -1;
+		} else if (a > b) {
+			return 1;
+		}
+	}
+
+	return 0;
+}
+
+export function mergeTupleBTrees<K extends readonly unknown[], V>(
+	tree1: TupleBTree<K, V> | undefined,
+	tree2: TupleBTree<K, V> | undefined,
+	preferLeft = true,
+): TupleBTree<K, V> {
+	if (tree1 === undefined) {
+		return tree2 !== undefined ? brand(tree2.clone()) : newTupleBTree<K, V>();
+	}
+
+	const result: TupleBTree<K, V> = brand(tree1.clone());
+	if (tree2 === undefined) {
+		return result;
+	}
+
+	for (const [key, value] of tree2.entries()) {
+		result.set(key, value, !preferLeft);
+	}
+
+	return result;
+}

package/src/util/idAllocator.ts

@@ -26,8 +26,6 @@ export interface IdAllocationState {
 	maxId: number;
 }
 
-/**
- */
 export function idAllocatorFromMaxId(maxId: number | undefined = undefined): IdAllocator {
 	return idAllocatorFromState({ maxId: maxId ?? -1 });
 }

package/src/util/index.ts

@@ -123,6 +123,7 @@ export {
 export {
 	RangeMap,
 	type RangeQueryResult,
+	newIntegerRangeMap,
 } from "./rangeMap.js";
 
 export {
@@ -140,3 +141,5 @@ export {
 	throwIfBroken,
 	breakingClass,
 } from "./breakable.js";
+
+export { type TupleBTree, newTupleBTree, mergeTupleBTrees } from "./bTreeUtils.js";