@fluidframework/tree 2.117.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.117.0",
+  "version": "3.0.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -14,70 +14,32 @@
   "type": "module",
   "exports": {
     ".": {
-      "import": {
-        "types": "./lib/entrypoints/public.d.ts",
-        "default": "./lib/entrypoints/public.js"
-      },
-      "require": {
-        "types": "./dist/entrypoints/public.d.ts",
-        "default": "./dist/entrypoints/public.js"
-      }
+      "types": "./lib/entrypoints/public.d.ts",
+      "default": "./lib/entrypoints/public.js"
     },
     "./alpha": {
-      "import": {
-        "types": "./lib/entrypoints/alpha.d.ts",
-        "default": "./lib/entrypoints/alpha.js"
-      },
-      "require": {
-        "types": "./dist/entrypoints/alpha.d.ts",
-        "default": "./dist/entrypoints/alpha.js"
-      }
+      "types": "./lib/entrypoints/alpha.d.ts",
+      "default": "./lib/entrypoints/alpha.js"
     },
     "./beta": {
-      "import": {
-        "types": "./lib/entrypoints/beta.d.ts",
-        "default": "./lib/entrypoints/beta.js"
-      },
-      "require": {
-        "types": "./dist/entrypoints/beta.d.ts",
-        "default": "./dist/entrypoints/beta.js"
-      }
+      "types": "./lib/entrypoints/beta.d.ts",
+      "default": "./lib/entrypoints/beta.js"
     },
     "./internal": {
-      "import": {
-        "types": "./lib/entrypoints/internal.d.ts",
-        "default": "./lib/entrypoints/internal.js"
-      },
-      "require": {
-        "types": "./dist/entrypoints/internal.d.ts",
-        "default": "./dist/entrypoints/internal.js"
-      }
+      "types": "./lib/entrypoints/internal.d.ts",
+      "default": "./lib/entrypoints/internal.js"
     },
     "./legacy": {
-      "import": {
-        "types": "./lib/entrypoints/legacy.d.ts",
-        "default": "./lib/entrypoints/legacy.js"
-      },
-      "require": {
-        "types": "./dist/entrypoints/legacy.d.ts",
-        "default": "./dist/entrypoints/legacy.js"
-      }
+      "types": "./lib/entrypoints/legacy.d.ts",
+      "default": "./lib/entrypoints/legacy.js"
     },
     "./internal/test": {
       "allow-ff-test-exports": {
-        "import": {
-          "types": "./lib/test/testExports.d.ts",
-          "default": "./lib/test/testExports.js"
-        },
-        "require": {
-          "types": "./dist/test/testExports.d.ts",
-          "default": "./dist/test/testExports.js"
-        }
+        "types": "./lib/test/testExports.d.ts",
+        "default": "./lib/test/testExports.js"
       }
     }
   },
-  "main": "lib/index.js",
-  "types": "lib/entrypoints/public.d.ts",
   "c8": {
     "all": true,
     "cache-dir": "nyc/.cache",
@@ -101,17 +63,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.117.0",
-    "@fluidframework/core-interfaces": "~2.117.0",
-    "@fluidframework/core-utils": "~2.117.0",
-    "@fluidframework/datastore-definitions": "~2.117.0",
-    "@fluidframework/driver-definitions": "~2.117.0",
-    "@fluidframework/id-compressor": "~2.117.0",
-    "@fluidframework/runtime-definitions": "~2.117.0",
-    "@fluidframework/runtime-utils": "~2.117.0",
-    "@fluidframework/shared-object-base": "~2.117.0",
-    "@fluidframework/telemetry-utils": "~2.117.0",
-    "@fluidframework/type-factory": "~2.117.0",
+    "@fluid-internal/client-utils": "~3.0.0",
+    "@fluidframework/core-interfaces": "~3.0.0",
+    "@fluidframework/core-utils": "~3.0.0",
+    "@fluidframework/datastore-definitions": "~3.0.0",
+    "@fluidframework/driver-definitions": "~3.0.0",
+    "@fluidframework/id-compressor": "~3.0.0",
+    "@fluidframework/runtime-definitions": "~3.0.0",
+    "@fluidframework/runtime-utils": "~3.0.0",
+    "@fluidframework/shared-object-base": "~3.0.0",
+    "@fluidframework/telemetry-utils": "~3.0.0",
+    "@fluidframework/type-factory": "~3.0.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^2.1.1",
     "semver-ts": "^1.0.3",
@@ -121,21 +83,21 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~2.117.0",
-    "@fluid-private/stochastic-test-utils": "~2.117.0",
-    "@fluid-private/test-dds-utils": "~2.117.0",
-    "@fluid-private/test-drivers": "~2.117.0",
+    "@fluid-internal/mocha-test-setup": "~3.0.0",
+    "@fluid-private/stochastic-test-utils": "~3.0.0",
+    "@fluid-private/test-dds-utils": "~3.0.0",
+    "@fluid-private/test-drivers": "~3.0.0",
     "@fluid-tools/benchmark": "^0.59.0",
     "@fluid-tools/build-cli": "^0.67.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.67.0",
-    "@fluidframework/container-definitions": "~2.117.0",
-    "@fluidframework/container-loader": "~2.117.0",
-    "@fluidframework/container-runtime": "~2.117.0",
+    "@fluidframework/container-definitions": "~3.0.0",
+    "@fluidframework/container-loader": "~3.0.0",
+    "@fluidframework/container-runtime": "~3.0.0",
     "@fluidframework/eslint-config-fluid": "^14.0.0",
-    "@fluidframework/local-driver": "~2.117.0",
-    "@fluidframework/test-runtime-utils": "~2.117.0",
-    "@fluidframework/test-utils": "~2.117.0",
+    "@fluidframework/local-driver": "~3.0.0",
+    "@fluidframework/test-runtime-utils": "~3.0.0",
+    "@fluidframework/test-utils": "~3.0.0",
     "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.116.0",
     "@microsoft/api-extractor": "7.58.1",
     "@types/diff": "^3.5.1",
@@ -157,23 +119,19 @@
     "mocha": "^11.7.5",
     "mocha-multi-reporters": "^1.5.1",
     "rimraf": "^6.1.3",
-    "typescript": "~5.4.5"
+    "typescript": "~6.0.3"
   },
   "comments": [
     "Tree test builds and eslint depend on the corresponding ID Compressor test builds because Tree tests import its internal/test-utils export, which resolves to generated test output."
   ],
   "fluidBuild": {
     "tasks": {
-      "build:test:cjs": [
-        "...",
-        "@fluidframework/id-compressor#build:test:cjs"
-      ],
       "build:test:esm": [
         "...",
         "@fluidframework/id-compressor#build:test:esm"
       ],
       "ci:build:docs": [
-        "build:esnext"
+        "build:esm"
       ],
       "eslint": [
         "...",
@@ -182,7 +140,24 @@
     }
   },
   "typeValidation": {
-    "broken": {},
+    "broken": {
+      "TypeAlias_IsListener": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "TypeAlias_Listenable": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "TypeAlias_Listeners": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "TypeAlias_Off": {
+        "backCompat": false,
+        "forwardCompat": false
+      }
+    },
     "entrypoint": "public"
   },
   "scripts": {
@@ -191,19 +166,17 @@
     "bench:profile": "cross-env FLUID_TEST_PERF_MODE=1 mocha --v8-prof --v8-logfile=profile.log --v8-no-logfile-per-isolate --timeout 999999 --fgrep @ExecutionTime --reporter @fluid-tools/benchmark/dist/mocha/Reporter.js && node --prof-process profile.log > profile.txt && rimraf profile.log && echo See results in profile.txt",
     "build": "fluid-build . --task build",
     "build:api-reports": "concurrently \"npm:build:api-reports:*\"",
-    "build:api-reports:current": "api-extractor run --local --config api-extractor/api-extractor.current.json",
-    "build:api-reports:legacy": "api-extractor run --local --config api-extractor/api-extractor.legacy.json",
+    "build:api-reports:current": "api-extractor run --local --config api-extractor/api-extractor-report.current.json",
+    "build:api-reports:legacy": "api-extractor run --local --config api-extractor/api-extractor-report.legacy.json",
+    "build:cjs": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
     "build:commonjs": "fluid-build . --task commonjs",
     "build:compile": "fluid-build . --task compile",
-    "build:docs": "api-extractor run --local",
-    "build:entrypoints": "fluid-build . --task build:entrypoints",
-    "build:entrypoints:node10": "flub generate node10Entrypoints",
-    "build:esnext": "tsc --project ./tsconfig.json",
+    "build:docs": "api-extractor run --local --config api-extractor/api-extractor-model.json",
+    "build:esm": "tsc --project ./tsconfig.json",
     "build:genver": "gen-version",
-    "build:test": "concurrently npm:build:test:esm npm:build:test:cjs",
-    "build:test:cjs": "fluid-tsc commonjs --project ./src/test/tsconfig.cjs.json",
+    "build:test": "npm run build:test:esm",
     "build:test:esm": "tsc --project ./src/test/tsconfig.json",
-    "check:are-the-types-wrong": "attw --pack . --exclude-entrypoints ./internal/test",
+    "check:are-the-types-wrong": "attw --pack . --profile esm-only --exclude-entrypoints ./internal/test",
     "check:biome": "biome check .",
     "check:exports": "concurrently \"npm:check:exports:*\"",
     "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json",
@@ -217,9 +190,9 @@
     "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json",
     "check:format": "npm run check:biome",
     "ci:build:api-reports": "concurrently \"npm:ci:build:api-reports:*\"",
-    "ci:build:api-reports:current": "api-extractor run --config api-extractor/api-extractor.current.json",
-    "ci:build:api-reports:legacy": "api-extractor run --config api-extractor/api-extractor.legacy.json",
-    "ci:build:docs": "api-extractor run",
+    "ci:build:api-reports:current": "api-extractor run --config api-extractor/api-extractor-report.current.json",
+    "ci:build:api-reports:legacy": "api-extractor run --config api-extractor/api-extractor-report.legacy.json",
+    "ci:build:docs": "api-extractor run --config api-extractor/api-extractor-model.json",
     "clean": "rimraf --glob dist lib {alpha,beta,internal,legacy}.d.ts \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
     "depcruise": "depcruise src/ --ignore-known",
     "depcruise:regen-known-issues": "depcruise-baseline src",
@@ -230,19 +203,18 @@
     "generate:entrypoint-sources": "scripts/generate-entrypoint-sources.sh",
     "lint": "fluid-build . --task lint",
     "lint:fix": "fluid-build . --task eslint:fix --task format",
-    "pack:tests": "tar -cf ./tree.test-files.tar ./src/test ./dist/test ./lib/test",
+    "pack:tests": "tar -cf ./tree.test-files.tar ./src/test ./lib/test",
+    "rebuild": "npm run clean && npm run build",
     "test": "npm run test:mocha",
     "test:coverage": "c8 npm test",
     "test:memory": "cross-env FLUID_TEST_PERF_MODE=1 mocha --fgrep @Memory --parallel --jobs 6",
-    "test:mocha": "echo skipping non-smoke cjs to avoid overhead && npm run test:mocha:cjs -- --fgrep @Smoke && npm run test:mocha:prod -- --fgrep @Smoke && npm run test:mocha:esm",
-    "test:mocha:cjs": "cross-env FLUID_TEST_MODULE_SYSTEM=CJS mocha",
+    "test:mocha": "npm run test:mocha:prod -- --fgrep @Smoke && npm run test:mocha:esm",
     "test:mocha:esm": "mocha",
     "test:mocha:prod": "mocha --emulateProduction",
     "test:mocha:prod-help": "echo run tests simulating production configurations as much as possible.",
     "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
     "test:snapshots:regen": "pnpm test:mocha:esm --snapshot",
     "test:stress": "cross-env FUZZ_TEST_COUNT=20 FUZZ_STRESS_RUN=normal mocha --ignore \"lib/test/memory/**/*\" --recursive \"lib/test/**/*.spec.js\"",
-    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
     "typetests:gen": "flub generate typetests --dir . -v"
   }
 }

package/src/api.ts

@@ -4,6 +4,8 @@
  */
 
 import type {
+	ITree,
+	ITreeAlpha,
 	TreeView,
 	TreeViewAlpha,
 	TreeViewBeta,
@@ -21,8 +23,17 @@ import type {
  * Module entry points for retrieving alternate (alpha/beta) versions of tree APIs.
  * For each API (usually a class) that has an alpha/beta version, add overloads to the function(s) below.
  * These functions should only be used by external consumers, not referenced internally within the tree package, to avoid circular import dependencies.
+ *
+ * These are only valid if all implementations are guaranteed to implement the alpha API:
+ * cases like SchemaFactory which allow users to construct non-alpha versions must not be added here.
  */
 
+/**
+ * Retrieve the {@link ITreeAlpha | alpha API} for an {@link ITree}.
+ * @alpha
+ */
+export function asAlpha(tree: ITree): ITreeAlpha;
+
 /**
  * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.
  * @alpha

package/src/core/index.ts

@@ -69,6 +69,8 @@ export {
 	deltaForRootInitialization,
 	makeDetachedNodeId,
 	offsetDetachId,
+	offsetDetachIdOpt,
+	subtractDetachedNodeId,
 	emptyDelta,
 	type AnchorSlot,
 	type AnchorNode,
@@ -108,8 +110,9 @@ export {
 	DetachedFieldIndexFormatVersion,
 	detachedFieldIndexCodecBuilder,
 	areDetachedNodeIdsEqual,
-	deltaFieldMapHasVisibleChanges,
-	deltaFieldChangesHaveVisibleChanges,
+	deltaFieldMapHasChanges,
+	deltaFieldChangesHaveChanges,
+	getDeltaChangeProfile,
 	forEachNodeSubsequence,
 } from "./tree/index.js";
 
@@ -225,6 +228,7 @@ export {
 	isAncestor,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	comparePartialRevisions,
 	compareChangesetLocalIds,
 	comparePartialChangesetLocalIds,

package/src/core/rebase/index.ts

@@ -37,6 +37,7 @@ export {
 	subtractChangeAtomIds,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
+	newChangeAtomIdTransform,
 	comparePartialRevisions,
 	compareChangesetLocalIds,
 	comparePartialChangesetLocalIds,

package/src/core/rebase/types.ts

@@ -165,7 +165,11 @@ export interface GraphCommit<TChange> {
 	readonly revision: RevisionTag;
 	/** The change that will result from applying this commit */
 	readonly change: TChange;
-	/** The parent of this commit, on whose change this commit's change is based */
+	/**
+	 * The parent of this commit, on whose change this commit's change is based.
+	 * @remarks
+	 * This property is only `undefined` for the trunk base commit, which is the root of the commit graph.
+	 */
 	readonly parent?: GraphCommit<TChange>;
 	/**
 	 * Arbitrary, application-defined metadata that is persisted alongside this commit.
@@ -176,6 +180,13 @@ export interface GraphCommit<TChange> {
 	 * Always copy this property when copying a commit.
 	 */
 	readonly customMetadata: CustomMetadataTree | undefined;
+
+	/**
+	 * Indicates whether this commit was trimmed from the history.
+	 * @remarks
+	 * During trunk trimming, this property is set to `true` on all trimmed commits (including the new trunk base).
+	 */
+	readonly wasTrimmed?: true;
 }
 
 /**
@@ -559,6 +570,10 @@ export function newChangeAtomIdRangeMap<V>(
 	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetValue);
 }
 
+export function newChangeAtomIdTransform(): ChangeAtomIdRangeMap<ChangeAtomId> {
+	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetChangeAtomId);
+}
+
 export function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number {
 	const cmp = comparePartialRevisions(a.revision, b.revision);
 	if (cmp !== 0) {

package/src/core/tree/anchorSet.ts

@@ -24,7 +24,7 @@ import type { FieldKey } from "../schema-stored/index.js";
 
 import type { ITreeCursorSynchronous } from "./cursor.js";
 import type * as Delta from "./delta.js";
-import { offsetDetachId } from "./deltaUtil.js";
+import { offsetDetachIdOpt } from "./deltaUtil.js";
 import {
 	isDetachedUpPathRoot,
 	type INormalizedUpPath,
@@ -585,7 +585,7 @@ export class AnchorSet implements AnchorLocator {
 			node.parentField = destination.parentField;
 			// If the destination is a detached root, propagate its detachedNodeId, otherwise remove any existing one
 			node.detachedNodeId = isDetachedUpPathRoot(destination)
-				? offsetDetachId(
+				? offsetDetachIdOpt(
 						destination.detachedNodeId,
 						node.parentIndex - destination.parentIndex,
 					)

package/src/core/tree/deltaUtil.ts

@@ -4,6 +4,7 @@
  */
 
 import type { Mutable } from "../../util/index.js";
+import { comparePartialRevisions } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type { TreeChunk } from "./chunk.js";
@@ -37,12 +38,19 @@ export function makeDetachedNodeId(
 	return out;
 }
 
-export function offsetDetachId(id: DetachedNodeId, offset: number): DetachedNodeId;
-export function offsetDetachId(
+export function offsetDetachId(id: DetachedNodeId, offset: number): DetachedNodeId {
+	return {
+		...id,
+		minor: id.minor + offset,
+	};
+}
+
+export function offsetDetachIdOpt(id: DetachedNodeId, offset: number): DetachedNodeId;
+export function offsetDetachIdOpt(
 	id: DetachedNodeId | undefined,
 	offset: number,
 ): DetachedNodeId | undefined;
-export function offsetDetachId(
+export function offsetDetachIdOpt(
 	id: DetachedNodeId | undefined,
 	offset: number,
 ): DetachedNodeId | undefined {
@@ -55,21 +63,66 @@ export function offsetDetachId(
 	};
 }
 
+export function subtractDetachedNodeId(a: DetachedNodeId, b: DetachedNodeId): number {
+	const cmp = comparePartialRevisions(a.major, b.major);
+	if (cmp !== 0) {
+		return cmp * Number.POSITIVE_INFINITY;
+	}
+
+	return a.minor - b.minor;
+}
+
 export function areDetachedNodeIdsEqual(a: DetachedNodeId, b: DetachedNodeId): boolean {
 	return a.major === b.major && a.minor === b.minor;
 }
 
 /**
- * Returns true if a delta field map contains any changes that would be visible in the document (i.e., a detach or an attach)
- * @param fields - Delta FieldMap to check for visible changes
- * @returns True if change map contains any changes that would be visible in the document, false otherwise
+ * Describes the types of changes present in a delta.
+ */
+export interface DeltaChangeProfile {
+	/** Whether the delta includes any build operations. */
+	hasBuilds: boolean;
+	/** Whether the delta includes any destroy operations. */
+	hasDestroys: boolean;
+	/** Whether the delta includes any rename operations. */
+	hasRenames: boolean;
+	/** Whether the delta includes any changes in the document tree. */
+	hasChangesInDocumentTree: boolean;
+	/** Whether the delta includes any changes in detached trees. */
+	hasChangesInDetachedTrees: boolean;
+}
+
+/**
+ * Reports the kinds of changes present in a delta.
+ * @param delta - The delta to analyze.
+ * @returns An object indicating which kinds of changes are present.
+ */
+export function getDeltaChangeProfile(delta: Root): DeltaChangeProfile {
+	const profile: DeltaChangeProfile = {
+		hasBuilds: delta.build !== undefined && delta.build.length > 0,
+		hasDestroys: delta.destroy !== undefined && delta.destroy.length > 0,
+		hasRenames: delta.rename !== undefined && delta.rename.length > 0,
+		hasChangesInDocumentTree: deltaFieldMapHasChanges(delta.fields),
+		hasChangesInDetachedTrees:
+			delta.global?.some((detachedNodeChanges) =>
+				deltaFieldMapHasChanges(detachedNodeChanges.fields),
+			) === true,
+	};
+	return profile;
+}
+
+/**
+ * Returns true if a delta field map contains any changes.
+ * Note that the changes may not be noticeable to the user (e.g., a change that replaces a node with another structurally identical node).
+ * @param fields - Delta FieldMap to check for changes
+ * @returns True if change map contains any changes, false otherwise
  */
-export function deltaFieldMapHasVisibleChanges(fields: FieldMap | undefined): boolean {
+export function deltaFieldMapHasChanges(fields: FieldMap | undefined): boolean {
 	if (fields === undefined || fields.size === 0) {
 		return false;
 	}
 	for (const [, fieldChanges] of fields) {
-		if (deltaFieldChangesHaveVisibleChanges(fieldChanges)) {
+		if (deltaFieldChangesHaveChanges(fieldChanges)) {
 			return true;
 		}
 	}
@@ -77,16 +130,17 @@ export function deltaFieldMapHasVisibleChanges(fields: FieldMap | undefined): bo
 }
 
 /**
- * Returns true if the given field changes contains any changes that would be visible in the document (i.e., a detach or an attach)
- * @param fieldChanges - Field changes to check for visible changes
- * @returns True if the field changes contain any changes that would be visible in the document, false otherwise
+ * Returns true if the given field changes contain any changes.
+ * Note that the changes may not be noticeable to the user (e.g., a change that replaces a node with another structurally identical node).
+ * @param fieldChanges - Field changes to check for changes
+ * @returns True if the field changes contain any changes, false otherwise
  */
-export function deltaFieldChangesHaveVisibleChanges(fieldChanges: FieldChanges): boolean {
+export function deltaFieldChangesHaveChanges(fieldChanges: FieldChanges): boolean {
 	for (const mark of fieldChanges.marks) {
 		if (
 			mark.attach !== undefined ||
 			mark.detach !== undefined ||
-			deltaFieldMapHasVisibleChanges(mark.fields)
+			deltaFieldMapHasChanges(mark.fields)
 		) {
 			return true;
 		}

package/src/core/tree/index.ts

@@ -107,10 +107,13 @@ export {
 	deltaForRootInitialization,
 	makeDetachedNodeId,
 	offsetDetachId,
+	offsetDetachIdOpt,
 	emptyDelta,
 	areDetachedNodeIdsEqual,
-	deltaFieldMapHasVisibleChanges,
-	deltaFieldChangesHaveVisibleChanges,
+	subtractDetachedNodeId,
+	deltaFieldMapHasChanges,
+	deltaFieldChangesHaveChanges,
+	getDeltaChangeProfile,
 } from "./deltaUtil.js";
 
 export {