@fluidframework/tree 2.61.0 → 2.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.61.0",
+  "version": "2.62.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -66,12 +66,12 @@
     "./internal/test": {
       "allow-ff-test-exports": {
         "import": {
-          "types": "./lib/test/index.d.ts",
-          "default": "./lib/test/index.js"
+          "types": "./lib/test/testExports.d.ts",
+          "default": "./lib/test/testExports.js"
         },
         "require": {
-          "types": "./dist/test/index.d.ts",
-          "default": "./dist/test/index.js"
+          "types": "./dist/test/testExports.d.ts",
+          "default": "./dist/test/testExports.js"
         }
       }
     }
@@ -101,17 +101,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.61.0",
-    "@fluidframework/container-runtime": "~2.61.0",
-    "@fluidframework/core-interfaces": "~2.61.0",
-    "@fluidframework/core-utils": "~2.61.0",
-    "@fluidframework/datastore-definitions": "~2.61.0",
-    "@fluidframework/driver-definitions": "~2.61.0",
-    "@fluidframework/id-compressor": "~2.61.0",
-    "@fluidframework/runtime-definitions": "~2.61.0",
-    "@fluidframework/runtime-utils": "~2.61.0",
-    "@fluidframework/shared-object-base": "~2.61.0",
-    "@fluidframework/telemetry-utils": "~2.61.0",
+    "@fluid-internal/client-utils": "~2.62.0",
+    "@fluidframework/container-runtime": "~2.62.0",
+    "@fluidframework/core-interfaces": "~2.62.0",
+    "@fluidframework/core-utils": "~2.62.0",
+    "@fluidframework/datastore-definitions": "~2.62.0",
+    "@fluidframework/driver-definitions": "~2.62.0",
+    "@fluidframework/id-compressor": "~2.62.0",
+    "@fluidframework/runtime-definitions": "~2.62.0",
+    "@fluidframework/runtime-utils": "~2.62.0",
+    "@fluidframework/shared-object-base": "~2.62.0",
+    "@fluidframework/telemetry-utils": "~2.62.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -121,19 +121,19 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.61.0",
-    "@fluid-private/stochastic-test-utils": "~2.61.0",
-    "@fluid-private/test-dds-utils": "~2.61.0",
-    "@fluid-private/test-drivers": "~2.61.0",
+    "@fluid-internal/mocha-test-setup": "~2.62.0",
+    "@fluid-private/stochastic-test-utils": "~2.62.0",
+    "@fluid-private/test-dds-utils": "~2.62.0",
+    "@fluid-private/test-drivers": "~2.62.0",
     "@fluid-tools/benchmark": "^0.51.0",
     "@fluid-tools/build-cli": "^0.58.3",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.58.3",
-    "@fluidframework/container-definitions": "~2.61.0",
-    "@fluidframework/container-loader": "~2.61.0",
+    "@fluidframework/container-definitions": "~2.62.0",
+    "@fluidframework/container-loader": "~2.62.0",
     "@fluidframework/eslint-config-fluid": "^6.0.0",
-    "@fluidframework/test-runtime-utils": "~2.61.0",
-    "@fluidframework/test-utils": "~2.61.0",
+    "@fluidframework/test-runtime-utils": "~2.62.0",
+    "@fluidframework/test-utils": "~2.62.0",
     "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.60.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/diff": "^3.5.1",
@@ -228,7 +228,7 @@
     "test:memory": "mocha --perfMode --config ./src/test/memory/.mocharc.cjs",
     "test:memory-profiling:report": "mocha --config ./src/test/memory/.mocharc.cjs",
     "test:mocha": "echo skipping non-smoke cjs to avoid overhead && npm run test:mocha:cjs -- --fgrep @Smoke && npm run test:mocha:esm",
-    "test:mocha:cjs": "cross-env MOCHA_SPEC=dist/test mocha",
+    "test:mocha:cjs": "cross-env FLUID_TEST_MODULE_SYSTEM=CJS mocha",
     "test:mocha:esm": "mocha",
     "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
     "test:snapshots:regen": "pnpm test:mocha:esm --snapshot",

package/src/api.ts

@@ -0,0 +1,30 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	type TreeView,
+	type TreeViewAlpha,
+	type ImplicitFieldSchema,
+	// eslint-disable-next-line import/no-deprecated
+	asTreeViewAlpha,
+} from "./simple-tree/index.js";
+
+/**
+ * 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.
+ * In the future, `asBeta` may be added here too.
+ * These functions should only be used by external consumers, not referenced internally within the tree package, to avoid circular import dependencies.
+ */
+
+/**
+ * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.
+ * @alpha
+ */
+export function asAlpha<TSchema extends ImplicitFieldSchema>(
+	view: TreeView<TSchema>,
+): TreeViewAlpha<TSchema> {
+	// eslint-disable-next-line import/no-deprecated
+	return asTreeViewAlpha(view);
+}

package/src/codec/codec.ts

@@ -10,7 +10,6 @@ import type { Static, TAnySchema, TSchema } from "@sinclair/typebox";
 
 import type { ChangeEncodingContext } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
-import { noopValidator } from "./noopValidator.js";
 
 /**
  * Translates decoded data to encoded data.
@@ -37,7 +36,6 @@ export interface IDecoder<TDecoded, TEncoded, TContext> {
 /**
  * Validates data complies with some particular schema.
  * Implementations are typically created by a {@link JsonValidator}.
- * @alpha @input
  */
 export interface SchemaValidationFunction<Schema extends TSchema> {
 	/**
@@ -66,6 +64,15 @@ export interface SchemaValidationFunction<Schema extends TSchema> {
  */
 export interface FormatValidator extends ErasedType<"FormatValidator"> {}
 
+/**
+ * A {@link JsonValidator} implementation which performs no validation and accepts all data as valid.
+ * @privateRemarks Having this as an option unifies opting out of validation with selection of
+ * validators, simplifying code performing validation.
+ */
+const noopValidator: JsonValidator = {
+	compile: <Schema extends TSchema>() => ({ check: (data): data is Static<Schema> => true }),
+};
+
 /**
  * A {@link FormatValidator} which does no validation.
  * @alpha
@@ -122,11 +129,10 @@ export interface ICodecOptions {
 	 * SharedTree users are still encouraged to use a non-trivial validator (i.e. not `FormatValidatorNoOp`)
 	 * whenever reasonable: it gives better fail-fast behavior when unexpected encoded data is found,
 	 * which reduces the risk of unrecoverable data corruption.
-	 *
-	 * Use of {@link JsonValidator} here is deprecated and will be removed:
-	 * it is recommended to use {@link FormatValidator} instead.
+	 * @privateRemarks
+	 * This property should probably be renamed to `validator` before stabilizing the API.
 	 */
-	readonly jsonValidator: JsonValidator | FormatValidator;
+	readonly jsonValidator: FormatValidator;
 }
 
 /**

package/src/codec/index.ts

@@ -31,7 +31,6 @@ export {
 	type DiscriminatedUnionLibrary,
 	unionOptions,
 } from "./discriminatedUnions.js";
-export { noopValidator } from "./noopValidator.js";
 export {
 	Versioned,
 	makeVersionedCodec,

package/src/core/index.ts

@@ -207,6 +207,7 @@ export {
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
 	compareRevisions,
+	diffHistories,
 } from "./rebase/index.js";
 
 export {

package/src/core/rebase/index.ts

@@ -56,4 +56,5 @@ export {
 	type RebaseStatsWithDuration,
 	replaceChange,
 	isAncestor,
+	diffHistories,
 } from "./utils.js";

package/src/core/rebase/utils.ts

@@ -678,3 +678,30 @@ export function isAncestor<TNode extends { readonly parent?: TNode }>(
 
 	return false;
 }
+
+/**
+ * Returns a change that represents the different between two places in a commit graph.
+ * Applying this change to the state at `sourceCommit` will yield the state at `targetCommit`.
+ * @param changeRebaser - the change rebaser responsible for providing inverses to the changes in the commits.
+ * @param sourceCommit - the commit representing the initial state.
+ * @param targetCommit - the commit representing the final state.
+ * @param mintRevisionTag - a function which can be called to create revision tags for any rollback changes that need to be generated.
+ * @returns a change representing the difference between `sourceCommit` and `targetCommit`.
+ */
+export function diffHistories<TChange>(
+	changeRebaser: ChangeRebaser<TChange>,
+	sourceCommit: GraphCommit<TChange>,
+	targetCommit: GraphCommit<TChange>,
+	mintRevisionTag: () => RevisionTag,
+): TChange {
+	const sourcePath: GraphCommit<TChange>[] = [];
+	const targetPath: GraphCommit<TChange>[] = [];
+	const ancestor = findCommonAncestor([sourceCommit, sourcePath], [targetCommit, targetPath]);
+	assert(ancestor !== undefined, 0xc6f /* Branches must be related */);
+	const inverses = sourcePath.map((commit) =>
+		rollbackFromCommit(changeRebaser, commit, mintRevisionTag),
+	);
+
+	inverses.reverse();
+	return changeRebaser.compose([...inverses, ...targetPath]);
+}

package/src/core/tree/detachedFieldIndex.ts

@@ -9,8 +9,8 @@ import type { IIdCompressor } from "@fluidframework/id-compressor";
 import {
 	type CodecWriteOptions,
 	FluidClientVersion,
+	FormatValidatorNoOp,
 	type IJsonCodec,
-	noopValidator,
 } from "../../codec/index.js";
 import {
 	type IdAllocator,
@@ -83,7 +83,7 @@ export class DetachedFieldIndex {
 		options?: CodecWriteOptions,
 	) {
 		this.options = options ?? {
-			jsonValidator: noopValidator,
+			jsonValidator: FormatValidatorNoOp,
 			oldestCompatibleClient: FluidClientVersion.v2_0,
 		};
 		this.codec = makeDetachedFieldIndexCodec(revisionTagCodec, this.options, idCompressor);

package/src/external-utilities/index.ts

@@ -3,4 +3,4 @@
  * Licensed under the MIT License.
  */
 
-export { typeboxValidator, FormatValidatorBasic } from "./typeboxValidator.js";
+export { FormatValidatorBasic } from "./typeboxValidator.js";

package/src/external-utilities/typeboxValidator.ts

@@ -18,10 +18,8 @@ import { toFormatValidator, type JsonValidator } from "../codec/index.js";
  * (i.e. a JSON validator is only included in an application's bundle if that application references it).
  *
  * Defining this validator in its own file also helps to ensure it is tree-shakeable.
- *
- * @alpha
  */
-export const typeboxValidator: JsonValidator = {
+const typeboxValidator: JsonValidator = {
 	compile: <Schema extends TSchema>(schema: Schema) => {
 		const compiledFormat = TypeCompiler.Compile(schema);
 		return {

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -151,6 +151,8 @@ export enum TreeStatus {
  *
  * @remarks
  * All editing is actually done via {@link FlexTreeField}s: the nodes are immutable other than that they contain mutable fields.
+ *
+ * All implementations should track read access in {@link currentObserver}'s observation methods as appropriate.
  */
 export interface FlexTreeNode extends FlexTreeEntity, MapTreeNodeViewGeneric<FlexTreeNode> {
 	readonly [flexTreeMarker]: FlexTreeEntityKind.Node;

package/src/feature-libraries/flex-tree/index.ts

@@ -42,3 +42,5 @@ export { getOrCreateHydratedFlexTreeNode } from "./lazyNode.js";
 export { getSchemaAndPolicy, indexForAt } from "./utilities.js";
 
 export { treeStatusFromAnchorCache } from "./utilities.js";
+
+export { currentObserver, withObservation, type Observer } from "./observer.js";

package/src/feature-libraries/flex-tree/lazyNode.ts

@@ -33,6 +33,7 @@ import {
 } from "./flexTreeTypes.js";
 import { LazyEntity } from "./lazyEntity.js";
 import { makeField } from "./lazyField.js";
+import { currentObserver } from "./observer.js";
 
 /**
  * Get or create a {@link HydratedFlexTreeNode} for the given context at node indicated by the cursor.
@@ -118,18 +119,23 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements HydratedFlexTree
 	public readonly fields: Pick<Map<FieldKey, FlexTreeField>, typeof Symbol.iterator | "get"> =
 		{
 			get: (key: FieldKey): FlexTreeField | undefined => this.tryGetField(key),
-			[Symbol.iterator]: (): IterableIterator<[FieldKey, FlexTreeField]> =>
-				mapCursorFields(this.cursor, (cursor) => {
+			[Symbol.iterator]: (): IterableIterator<[FieldKey, FlexTreeField]> => {
+				currentObserver?.observeNodeFields(this);
+
+				return mapCursorFields(this.cursor, (cursor) => {
 					const key: FieldKey = cursor.getFieldKey();
 					const pair: [FieldKey, FlexTreeField] = [
 						key,
 						makeField(this.context, this.storedSchema.getFieldSchema(key).kind, cursor),
 					];
 					return pair;
-				}).values(),
+				}).values();
+			},
 		};
 
 	public tryGetField(fieldKey: FieldKey): FlexTreeField | undefined {
+		currentObserver?.observeNodeField(this, fieldKey);
+
 		const schema = this.storedSchema.getFieldSchema(fieldKey);
 		return inCursorField(this.cursor, fieldKey, (cursor) => {
 			if (cursor.getFieldLength() === 0) {
@@ -140,6 +146,8 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements HydratedFlexTree
 	}
 
 	public getBoxed(key: FieldKey): FlexTreeField {
+		currentObserver?.observeNodeField(this, key);
+
 		const fieldSchema = this.storedSchema.getFieldSchema(key);
 		return inCursorField(this.cursor, key, (cursor) => {
 			return makeField(this.context, fieldSchema.kind, cursor);
@@ -157,6 +165,8 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements HydratedFlexTree
 	}
 
 	public get parentField(): { readonly parent: FlexTreeField; readonly index: number } {
+		currentObserver?.observeParentOf(this);
+
 		const cursor = this.cursor;
 		const index = this.anchorNode.parentIndex;
 		assert(cursor.fieldIndex === index, 0x786 /* mismatched indexes */);

package/src/feature-libraries/flex-tree/observer.ts

@@ -0,0 +1,64 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { debugAssert } from "@fluidframework/core-utils/internal";
+import type { FlexTreeNode } from "./flexTreeTypes.js";
+import type { FieldKey } from "../../core/index.js";
+
+/*
+ * This file sets up a static observation tracking system.
+ *
+ * This library used to contain a more general variant of this which was deleted in https://github.com/microsoft/FluidFramework/pull/18659.
+ * This pattern somewhat resembles the approach in https://github.com/tc39/proposal-signals.
+ */
+
+/**
+ * An object informed about observation made to trees.
+ * @remarks
+ * See {@link withObservation} and {@link currentObserver}.
+ */
+export interface Observer {
+	observeNodeFields(node: FlexTreeNode): void;
+	observeNodeField(node: FlexTreeNode, key: FieldKey): void;
+	observeParentOf(node: FlexTreeNode): void;
+}
+
+/**
+ * The current observer, if any.
+ * @remarks
+ * Set via {@link setObserver} as used by {@link withObservation}.
+ * It should not be assigned in any other way.
+ * @privateRemarks
+ * This is exported directly as a property instead of via a getter for reduced overhead (less code, faster access) as this is used on some hot paths and its performance matters.
+ * The case where this is undefined (no observation) is particularly important for performance as we do not want to regress code which is not using this feature very much.
+ * Since it is not exported outside the package, this seems like a fine tradeoff, but could be reevaluated with some benchmarking if needed.
+ */
+export let currentObserver: Observer | undefined;
+
+const observerStack: (Observer | undefined)[] = [];
+
+function setObserver(newObserver: Observer | undefined): void {
+	observerStack.push(newObserver);
+	currentObserver = newObserver;
+}
+
+function clearObserver(): void {
+	debugAssert(() => observerStack.length > 0 || "Empty Observer stack on clear");
+	const popped = observerStack.pop();
+	debugAssert(() => popped === currentObserver || "Mismatched observer stack");
+	currentObserver = observerStack[observerStack.length - 1];
+}
+
+/**
+ * For the duration of `f`, pushes `newObserver` onto the observer stack, making it the {@link currentObserver}.
+ */
+export function withObservation<T>(newObserver: Observer | undefined, f: () => T): T {
+	setObserver(newObserver);
+	try {
+		return f();
+	} finally {
+		clearObserver();
+	}
+}

package/src/feature-libraries/index.ts

@@ -171,6 +171,9 @@ export {
 	type FlexTreeHydratedContextMinimal,
 	type HydratedFlexTreeNode,
 	getOrCreateHydratedFlexTreeNode,
+	currentObserver,
+	withObservation,
+	type Observer,
 } from "./flex-tree/index.js";
 
 export {

package/src/index.ts

@@ -57,6 +57,7 @@ export {
 export {
 	type ITreeInternal,
 	type SharedTreeOptions,
+	type SharedTreeOptionsBeta,
 	type ForestType,
 	type SharedTreeFormatOptions,
 	SharedTreeFormatVersion,
@@ -69,6 +70,7 @@ export {
 	independentInitializedView,
 	type ViewContent,
 	TreeAlpha,
+	type ObservationResults,
 	type TreeIdentifierUtils,
 	independentView,
 	ForestTypeOptimized,
@@ -275,6 +277,8 @@ export {
 export {
 	SharedTree,
 	configuredSharedTree,
+	configuredSharedTreeBeta,
+	configuredSharedTreeBetaLegacy,
 } from "./treeFactory.js";
 export { SharedTreeAttributes, SharedTreeFactoryType } from "./sharedTreeAttributes.js";
 export { persistedToSimpleSchema } from "./shared-tree/index.js";
@@ -282,14 +286,11 @@ export { persistedToSimpleSchema } from "./shared-tree/index.js";
 export {
 	type ICodecOptions,
 	type CodecWriteOptions,
-	type JsonValidator,
-	type SchemaValidationFunction,
 	FluidClientVersion,
 	type FormatValidator,
 	FormatValidatorNoOp,
 } from "./codec/index.js";
-export { noopValidator } from "./codec/index.js";
-export { typeboxValidator, FormatValidatorBasic } from "./external-utilities/index.js";
+export { FormatValidatorBasic } from "./external-utilities/index.js";
 
 export type {
 	// Type Testing
@@ -332,3 +333,4 @@ export type { MapNodeInsertableData } from "./simple-tree/index.js";
 export { JsonAsTree } from "./jsonDomainSchema.js";
 export { FluidSerializableAsTree } from "./serializableDomainSchema.js";
 export { TableSchema, type System_TableSchema } from "./tableSchema.js";
+export { asAlpha } from "./api.js";

package/src/packageVersion.ts

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

package/src/shared-tree/index.ts

@@ -7,6 +7,7 @@ export {
 	type ITreePrivate,
 	type SharedTreeOptionsInternal,
 	type SharedTreeOptions,
+	type SharedTreeOptionsBeta,
 	SharedTreeKernel,
 	getBranch,
 	type ForestType,
@@ -49,6 +50,7 @@ export type { RunTransaction } from "./tree.js";
 export {
 	TreeAlpha,
 	type TreeIdentifierUtils,
+	type ObservationResults,
 } from "./treeAlpha.js";
 
 export {

package/src/shared-tree/schematizingTreeView.ts

@@ -420,8 +420,8 @@ export class SchematizingSimpleTreeView<
 		this.checkout.forest.anchors.slots.delete(ViewSlot);
 		this.currentCompatibility = undefined;
 		this.onDispose?.();
-		if (this.checkout.isBranch && !this.checkout.disposed) {
-			// All (non-main) branches are 1:1 with views, so if a user manually disposes a view, we should also dispose the checkout/branch.
+		if (!this.checkout.isSharedBranch && !this.checkout.disposed) {
+			// All non-shared branches are 1:1 with views, so if a user manually disposes a view, we should also dispose the checkout/branch.
 			this.checkout.dispose();
 		}
 	}