@fluidframework/tree 2.1.0-281041 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.1.0-281041",
+  "version": "2.2.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -67,17 +67,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "2.1.0-281041",
-    "@fluidframework/container-runtime": "2.1.0-281041",
-    "@fluidframework/core-interfaces": "2.1.0-281041",
-    "@fluidframework/core-utils": "2.1.0-281041",
-    "@fluidframework/datastore-definitions": "2.1.0-281041",
-    "@fluidframework/driver-definitions": "2.1.0-281041",
-    "@fluidframework/id-compressor": "2.1.0-281041",
-    "@fluidframework/runtime-definitions": "2.1.0-281041",
-    "@fluidframework/runtime-utils": "2.1.0-281041",
-    "@fluidframework/shared-object-base": "2.1.0-281041",
-    "@fluidframework/telemetry-utils": "2.1.0-281041",
+    "@fluid-internal/client-utils": "~2.2.0",
+    "@fluidframework/container-runtime": "~2.2.0",
+    "@fluidframework/core-interfaces": "~2.2.0",
+    "@fluidframework/core-utils": "~2.2.0",
+    "@fluidframework/datastore-definitions": "~2.2.0",
+    "@fluidframework/driver-definitions": "~2.2.0",
+    "@fluidframework/id-compressor": "~2.2.0",
+    "@fluidframework/runtime-definitions": "~2.2.0",
+    "@fluidframework/runtime-utils": "~2.2.0",
+    "@fluidframework/shared-object-base": "~2.2.0",
+    "@fluidframework/telemetry-utils": "~2.2.0",
     "@sinclair/typebox": "^0.32.29",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@ungap/structured-clone": "^1.2.0",
@@ -86,20 +86,20 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.15.2",
     "@biomejs/biome": "~1.8.3",
-    "@fluid-internal/mocha-test-setup": "2.1.0-281041",
-    "@fluid-private/stochastic-test-utils": "2.1.0-281041",
-    "@fluid-private/test-dds-utils": "2.1.0-281041",
-    "@fluid-private/test-drivers": "2.1.0-281041",
-    "@fluid-tools/benchmark": "^0.48.0",
-    "@fluid-tools/build-cli": "^0.40.0",
+    "@fluid-internal/mocha-test-setup": "~2.2.0",
+    "@fluid-private/stochastic-test-utils": "~2.2.0",
+    "@fluid-private/test-dds-utils": "~2.2.0",
+    "@fluid-private/test-drivers": "~2.2.0",
+    "@fluid-tools/benchmark": "^0.50.0",
+    "@fluid-tools/build-cli": "^0.43.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.40.0",
-    "@fluidframework/container-definitions": "2.1.0-281041",
-    "@fluidframework/container-loader": "2.1.0-281041",
+    "@fluidframework/build-tools": "^0.43.0",
+    "@fluidframework/container-definitions": "~2.2.0",
+    "@fluidframework/container-loader": "~2.2.0",
     "@fluidframework/eslint-config-fluid": "^5.3.0",
-    "@fluidframework/test-runtime-utils": "2.1.0-281041",
-    "@fluidframework/test-utils": "2.1.0-281041",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.0.0",
+    "@fluidframework/test-runtime-utils": "~2.2.0",
+    "@fluidframework/test-utils": "~2.2.0",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.1.0",
     "@microsoft/api-extractor": "^7.45.1",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",
@@ -142,7 +142,17 @@
     }
   },
   "typeValidation": {
-    "broken": {}
+    "broken": {
+      "Interface_FieldSchemaUnsafe": {
+        "forwardCompat": false
+      },
+      "Interface_ITreeViewConfiguration": {
+        "forwardCompat": false
+      },
+      "TypeAlias_ImplicitFieldSchema": {
+        "forwardCompat": false
+      }
+    }
   },
   "scripts": {
     "api": "fluid-build . --task api",
@@ -183,6 +193,7 @@
     "test": "npm run test:mocha",
     "test:benchmark:report": "mocha --exit --perfMode --parentProcess --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js --timeout 60000",
     "test:coverage": "c8 npm test",
+    "test:customBenchmarks": "mocha --config ./.mocharc.customBenchmarks.cjs",
     "test:memory": "mocha --config ./src/test/memory/.mocharc.cjs",
     "test:memory-profiling:report": "mocha --config ./src/test/memory/.mocharc.cjs",
     "test:mocha": "npm run test:mocha:esm && echo skipping cjs to avoid overhead - npm run test:mocha:cjs",

package/src/codec/discriminatedUnions.ts

@@ -25,6 +25,25 @@ export const unionOptions: ObjectOptions = {
 	maxProperties: 1,
 };
 
+/**
+ * An object containing functions for each member of the union.
+ *
+ * See {@link DiscriminatedUnionDispatcher}.
+ */
+export type DiscriminatedUnionLibrary<
+	TUnion extends object,
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	TArgs extends any[],
+	TResult,
+> = [
+	{
+		readonly [Property in keyof TUnion]-?: (
+			value: Required<TUnion>[Property],
+			...args: TArgs
+		) => TResult;
+	},
+][_InlineTrick];
+
 /**
  * Applies a function to the content of a [discriminated union](https://en.wikipedia.org/wiki/Tagged_union)
  * where the function to apply depends on which value from the union it holds.
@@ -91,16 +110,7 @@ export class DiscriminatedUnionDispatcher<
 		(value: unknown, ...args: TArgs) => TResult
 	>;
 
-	public constructor(
-		library: [
-			{
-				readonly [Property in keyof TUnion]-?: (
-					value: Required<TUnion>[Property],
-					...args: TArgs
-				) => TResult;
-			},
-		][_InlineTrick],
-	) {
+	public constructor(library: DiscriminatedUnionLibrary<TUnion, TArgs, TResult>) {
 		this.library = objectToMap(
 			library as Record<keyof TUnion, (value: unknown, ...args: TArgs) => TResult>,
 		);

package/src/codec/index.ts

@@ -19,7 +19,11 @@ export {
 	withDefaultBinaryEncoding,
 	withSchemaValidation,
 } from "./codec.js";
-export { DiscriminatedUnionDispatcher, unionOptions } from "./discriminatedUnions.js";
+export {
+	DiscriminatedUnionDispatcher,
+	type DiscriminatedUnionLibrary,
+	unionOptions,
+} from "./discriminatedUnions.js";
 export { noopValidator } from "./noopValidator.js";
 export {
 	Versioned,

package/src/core/forest/README.md

@@ -4,8 +4,10 @@ An abstraction for representing, editing, and observing collections of trees.
 Forest is focused on allowing the implementation to efficiently be viewed/read and apply deltas,
 while only keeping a subset of the data in memory.
 
-Forest is not supposed to provide a friendly API (See [flex-tree](../../feature-libraries/flex-tree/README.md) for that).
+Forest is not supposed to provide a friendly API.
 Instead, forest provides an abstraction that enables implementing nicer APIs on-top of it as a separate layer while abstracting the actual storage representation.
-This should allow forest implementations to implement compression without having to modify the forest API or its users.
+This should allow forest implementations (like [chunked-forest](../../feature-libraries/chunked-forest/README.md)) to implement compression without having to modify the forest API or its users.
+
+[flex-tree](../../feature-libraries/flex-tree/README.md) is the internal facing API abstracting forest which is wrapped by [simple-tree](../../simple-tree/README.md) to provide the public API.
 
 As the system matures more, and internal forest formats and its users are more settled, optional fast paths for accessing compressed data directly can be added when worth-while for performance reasons.

package/src/core/forest/editableForest.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { SessionSpaceCompressedId, IIdCompressor } from "@fluidframework/id-compressor";
 import { assert } from "@fluidframework/core-utils/internal";
 
 import type { RevisionTagCodec } from "../rebase/index.js";
@@ -20,11 +21,9 @@ import {
 } from "../tree/index.js";
 
 import type { IForestSubscription, ITreeSubscriptionCursor } from "./forest.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 /**
  * Editing APIs.
- * @internal
  */
 export interface IEditableForest extends IForestSubscription {
 	/**
@@ -61,12 +60,19 @@ export function initializeForest(
 	const delta: DeltaRoot = deltaForRootInitialization(content);
 	let visitor = forest.acquireVisitor();
 	if (visitAnchors) {
-		assert(forest.anchors.isEmpty(), "anchor set must be empty");
+		assert(forest.anchors.isEmpty(), 0x9b7 /* anchor set must be empty */);
 		const anchorVisitor = forest.anchors.acquireVisitor();
 		visitor = combineVisitors([visitor, anchorVisitor], [anchorVisitor]);
 	}
 
-	visitDelta(delta, visitor, makeDetachedFieldIndex("init", revisionTagCodec, idCompressor));
+	// any detached trees built here are immediately attached so the revision used here doesn't matter
+	// we use a dummy revision to make correctness checks in the detached field index easier
+	visitDelta(
+		delta,
+		visitor,
+		makeDetachedFieldIndex("init", revisionTagCodec, idCompressor),
+		0 as SessionSpaceCompressedId,
+	);
 	visitor.free();
 }
 
@@ -74,12 +80,10 @@ export function initializeForest(
 
 /**
  * Ways to refer to a node in an IEditableForest.
- * @internal
  */
 export type ForestLocation = ITreeSubscriptionCursor | Anchor;
 
 /**
- * @internal
  */
 export interface TreeLocation {
 	readonly range: FieldLocation | DetachedField;
@@ -92,7 +96,6 @@ export function isFieldLocation(range: FieldLocation | DetachedField): range is
 
 /**
  * Location of a field within a tree that is not a detached/root field.
- * @internal
  */
 export interface FieldLocation {
 	readonly key: FieldKey;

package/src/core/forest/forest.ts

@@ -33,7 +33,6 @@ import type { IEditableForest } from "./editableForest.js";
  * Events for {@link IForestSubscription}.
  *
  * TODO: consider having before and after events per subtree instead while applying anchor (and this just shows what happens at the root).
- * @internal
  */
 export interface ForestEvents {
 	/**
@@ -58,7 +57,6 @@ export interface ForestEvents {
  * Not invalidated when schema changes.
  *
  * When invalidating, all outstanding cursors must be freed or cleared.
- * @internal
  */
 export interface IForestSubscription extends Listenable<ForestEvents> {
 	/**
@@ -162,7 +160,6 @@ export function moveToDetachedField(
 /**
  * Anchor to a field.
  * This is structurally based on the parent, so it will move only as the parent moves.
- * @internal
  */
 export interface FieldAnchor {
 	/**
@@ -175,7 +172,6 @@ export interface FieldAnchor {
 
 /**
  * ITreeCursor supporting IForestSubscription and its changes over time.
- * @internal
  */
 export interface ITreeSubscriptionCursor extends ITreeCursor {
 	/**
@@ -226,7 +222,6 @@ export interface ITreeSubscriptionCursor extends ITreeCursor {
 }
 
 /**
- * @internal
  */
 export enum ITreeSubscriptionCursorState {
 	/**
@@ -244,7 +239,6 @@ export enum ITreeSubscriptionCursorState {
 }
 
 /**
- * @internal
  */
 export const enum TreeNavigationResult {
 	/**

package/src/core/index.ts

@@ -96,6 +96,8 @@ export {
 	type DeltaDetachedNodeDestruction,
 	type DeltaDetachedNodeRename,
 	type DeltaFieldChanges,
+	type ExclusiveMapTree,
+	deepCopyMapTree,
 } from "./tree/index.js";
 
 export {
@@ -190,8 +192,6 @@ export {
 	taggedOptAtomId,
 	offsetChangeAtomId,
 	replaceAtomRevisions,
-	getFromChangeAtomIdMap,
-	setInChangeAtomIdMap,
 	replaceChange,
 	type RebaseStats,
 	type RebaseStatsWithDuration,

package/src/core/rebase/changeRebaser.ts

@@ -92,7 +92,6 @@ export interface ChangeRebaser<TChangeset> {
 }
 
 /**
- * @internal
  */
 export interface TaggedChange<TChangeset, TTag = RevisionTag | undefined> {
 	readonly revision: TTag;
@@ -120,12 +119,10 @@ export function mapTaggedChange<TIn, TOut>(
  * being produced.
  *
  * During rebase, the indices of the base changes are all lower than the indices of the change being rebased.
- * @internal
  */
 export type RevisionIndexer = (tag: RevisionTag) => number | undefined;
 
 /**
- * @internal
  */
 export interface RevisionMetadataSource {
 	readonly getIndex: RevisionIndexer;
@@ -134,7 +131,6 @@ export interface RevisionMetadataSource {
 }
 
 /**
- * @internal
  */
 export interface RevisionInfo {
 	readonly revision: RevisionTag;

package/src/core/rebase/index.ts

@@ -23,8 +23,6 @@ export {
 	taggedOptAtomId,
 	offsetChangeAtomId,
 	replaceAtomRevisions,
-	getFromChangeAtomIdMap,
-	setInChangeAtomIdMap,
 	replaceChange,
 } from "./types.js";
 export { RevisionTagCodec } from "./revisionTagCodec.js";

package/src/core/rebase/types.ts

@@ -17,8 +17,6 @@ import {
 	brand,
 	brandedNumberType,
 	brandedStringType,
-	setInNestedMap,
-	tryGetFromNestedMap,
 } from "../../util/index.js";
 import type { TaggedChange } from "./changeRebaser.js";
 
@@ -33,7 +31,6 @@ export const SessionIdSchema = brandedStringType<SessionId>();
  *
  * The constant 'root' is reserved for the trunk base: minting a SessionSpaceCompressedId is not
  * possible on readonly clients. These clients generally don't need ids, but  must be done at tree initialization time.
- * @internal
  */
 export type RevisionTag = SessionSpaceCompressedId | "root";
 export type EncodedRevisionTag = Brand<OpSpaceCompressedId, "EncodedRevisionTag"> | "root";
@@ -46,14 +43,12 @@ export const RevisionTagSchema = Type.Union([
  * An ID which is unique within a revision of a `ModularChangeset`.
  * A `ModularChangeset` which is a composition of multiple revisions may contain duplicate `ChangesetLocalId`s,
  * but they are unique when qualified by the revision of the change they are used in.
- * @internal
  */
 export type ChangesetLocalId = Brand<number, "ChangesetLocalId">;
 
 /**
  * A globally unique ID for an atom of change, or a node associated with the atom of change.
- * @internal
- *
+ * *
  * @privateRemarks
  * TODO: Rename this to be more general.
  */
@@ -72,27 +67,10 @@ export interface ChangeAtomId {
 export type EncodedChangeAtomId = [ChangesetLocalId, EncodedRevisionTag] | ChangesetLocalId;
 
 /**
- * @internal
  */
 export type ChangeAtomIdMap<T> = NestedMap<RevisionTag | undefined, ChangesetLocalId, T>;
 
-export function getFromChangeAtomIdMap<T>(
-	map: ChangeAtomIdMap<T>,
-	id: ChangeAtomId,
-): T | undefined {
-	return tryGetFromNestedMap(map, id.revision, id.localId);
-}
-
-export function setInChangeAtomIdMap<T>(
-	map: ChangeAtomIdMap<T>,
-	id: ChangeAtomId,
-	value: T,
-): void {
-	setInNestedMap(map, id.revision, id.localId, value);
-}
-
 /**
- * @internal
  */
 export type ChangeAtomIdRangeMap<T> = Map<RevisionTag | undefined, RangeMap<T>>;
 

package/src/core/rebase/utils.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 
 import type { Mutable } from "../../util/index.js";
 
@@ -204,11 +204,13 @@ export function rebaseBranch<TChange>(
 	if (targetCommitIndex === -1) {
 		// If the targetCommit is not in the target path, then it is either disjoint from `target` or it is behind/at
 		// the commit where source and target diverge (ancestor), in which case there is nothing more to rebase
-		// TODO: Ideally, this would be an "assertExpensive"
-		assert(
-			findCommonAncestor(targetCommit, targetHead) !== undefined,
-			0x676 /* target commit is not in target branch */,
-		);
+		// TODO: Ideally, this would be an "assertExpensive". It is commented out because it causes O(N²) behavior when
+		// processing N inbound commits from the same client whose ref seq# is not advancing (which is a common case).
+		// N can be large when the client is sending a burst of changes (potentially on reconnection).
+		// assert(
+		// 	findCommonAncestor(targetCommit, targetHead) !== undefined,
+		// 	0x676 /* target commit is not in target branch */,
+		// );
 		return {
 			newSourceHead: sourceHead,
 			sourceChange: undefined,
@@ -228,8 +230,7 @@ export function rebaseBranch<TChange>(
 	const sourceSet = new Set(sourcePath.map((r) => r.revision));
 	let newBaseIndex = targetCommitIndex;
 
-	for (let i = 0; i < targetPath.length; i += 1) {
-		const { revision } = targetPath[i];
+	for (const [i, { revision }] of targetPath.entries()) {
 		if (sourceSet.has(revision)) {
 			sourceSet.delete(revision);
 			newBaseIndex = Math.max(newBaseIndex, i);
@@ -239,7 +240,7 @@ export function rebaseBranch<TChange>(
 	}
 
 	/** The commit on the target branch that the new source branch branches off of (i.e. the new common ancestor) */
-	const newBase = targetPath[newBaseIndex];
+	const newBase = targetPath[newBaseIndex] ?? oob();
 	// Figure out how much of the trunk to start rebasing over.
 	const targetCommits = targetPath.slice(0, newBaseIndex + 1);
 	const deletedSourceCommits = [...sourcePath];
@@ -249,7 +250,9 @@ export function rebaseBranch<TChange>(
 	const targetRebasePath = [...targetCommits];
 	const minLength = Math.min(sourcePath.length, targetRebasePath.length);
 	for (let i = 0; i < minLength; i++) {
-		if (sourcePath[0].revision === targetRebasePath[0].revision) {
+		const firstSourcePath = sourcePath[0] ?? oob();
+		const firstTargetRebasePath = targetRebasePath[0] ?? oob();
+		if (firstSourcePath.revision === firstTargetRebasePath.revision) {
 			sourcePath.shift();
 			targetRebasePath.shift();
 		}
@@ -371,7 +374,6 @@ export function rebaseChange<TChange>(
 }
 
 /**
- * @internal
  */
 export function revisionMetadataSourceFromInfo(
 	revInfos: readonly RevisionInfo[],

package/src/core/schema-stored/multiplicity.ts

@@ -7,7 +7,6 @@
  * Describes how a particular field functions.
  *
  * This determine its reading and editing APIs, multiplicity, and what merge resolution policies it will use.
- * @internal
  */
 export enum Multiplicity {
 	/**

package/src/core/schema-stored/schema.ts

@@ -65,8 +65,6 @@ export type TreeTypeSet = ReadonlySet<TreeNodeSchemaIdentifier> | undefined;
  *
  * @remarks
  * Enough info about a field kind to know if a given tree is is schema.
- *
- * @internal
  */
 export interface FieldKindData {
 	readonly identifier: FieldKindIdentifier;
@@ -83,7 +81,6 @@ export interface SchemaAndPolicy {
 
 /**
  * Extra data needed to interpret schema.
- * @internal
  */
 export interface SchemaPolicy {
 	/**
@@ -122,8 +119,6 @@ export interface TreeFieldStoredSchema {
  * This mainly show up in:
  * 1. The root default field for documents.
  * 2. The schema used for out of schema fields (which thus must be empty/not exist) on object and leaf nodes.
- *
- * @internal
  */
 export const forbiddenFieldKindIdentifier = "Forbidden";
 
@@ -140,8 +135,6 @@ export const storedEmptyFieldSchema: TreeFieldStoredSchema = {
 
 /**
  * Identifier used for the FieldKind for fields of type identifier.
- *
- * @internal
  */
 export const identifierFieldKindIdentifier = "Identifier";
 

package/src/core/schema-stored/storedSchemaRepository.ts

@@ -21,7 +21,6 @@ import {
  * Events for {@link TreeStoredSchemaSubscription}.
  *
  * TODO: consider having before and after events per subtree instead while applying anchor (and this just shows what happens at the root).
- * @internal
  */
 export interface SchemaEvents {
 	/**
@@ -37,7 +36,6 @@ export interface SchemaEvents {
 
 /**
  * A collection of stored schema that fires events in response to changes.
- * @internal
  */
 export interface TreeStoredSchemaSubscription
 	extends Listenable<SchemaEvents>,
@@ -45,7 +43,6 @@ export interface TreeStoredSchemaSubscription
 
 /**
  * Mutable collection of stored schema.
- * @internal
  */
 export interface MutableTreeStoredSchema extends TreeStoredSchemaSubscription {
 	/**

package/src/core/schema-view/view.ts

@@ -24,7 +24,6 @@ export enum Compatibility {
  * What kinds of updates to stored schema to permit.
  *
  * Bit flags enum.
- * @internal
  */
 export enum AllowedUpdateType {
 	/**
@@ -53,7 +52,6 @@ export enum AllowedUpdateType {
 }
 
 /**
- * @internal
  */
 export interface TreeAdapter {
 	readonly output: TreeNodeSchemaIdentifier;
@@ -68,7 +66,6 @@ export interface TreeAdapter {
  *
  * TODO: Support more kinds of adapters
  * TODO: support efficient lookup of adapters
- * @internal
  */
 export interface Adapters {
 	readonly tree?: readonly TreeAdapter[];