@fluidframework/tree 2.116.1 → 2.118.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.116.1",
+  "version": "2.118.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -101,17 +101,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.116.1",
-    "@fluidframework/core-interfaces": "~2.116.1",
-    "@fluidframework/core-utils": "~2.116.1",
-    "@fluidframework/datastore-definitions": "~2.116.1",
-    "@fluidframework/driver-definitions": "~2.116.1",
-    "@fluidframework/id-compressor": "~2.116.1",
-    "@fluidframework/runtime-definitions": "~2.116.1",
-    "@fluidframework/runtime-utils": "~2.116.1",
-    "@fluidframework/shared-object-base": "~2.116.1",
-    "@fluidframework/telemetry-utils": "~2.116.1",
-    "@fluidframework/type-factory": "~2.116.1",
+    "@fluid-internal/client-utils": "~2.118.0",
+    "@fluidframework/core-interfaces": "~2.118.0",
+    "@fluidframework/core-utils": "~2.118.0",
+    "@fluidframework/datastore-definitions": "~2.118.0",
+    "@fluidframework/driver-definitions": "~2.118.0",
+    "@fluidframework/id-compressor": "~2.118.0",
+    "@fluidframework/runtime-definitions": "~2.118.0",
+    "@fluidframework/runtime-utils": "~2.118.0",
+    "@fluidframework/shared-object-base": "~2.118.0",
+    "@fluidframework/telemetry-utils": "~2.118.0",
+    "@fluidframework/type-factory": "~2.118.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^2.1.1",
     "semver-ts": "^1.0.3",
@@ -121,21 +121,21 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~2.116.1",
-    "@fluid-private/stochastic-test-utils": "~2.116.1",
-    "@fluid-private/test-dds-utils": "~2.116.1",
-    "@fluid-private/test-drivers": "~2.116.1",
+    "@fluid-internal/mocha-test-setup": "~2.118.0",
+    "@fluid-private/stochastic-test-utils": "~2.118.0",
+    "@fluid-private/test-dds-utils": "~2.118.0",
+    "@fluid-private/test-drivers": "~2.118.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.116.1",
-    "@fluidframework/container-loader": "~2.116.1",
-    "@fluidframework/container-runtime": "~2.116.1",
+    "@fluidframework/container-definitions": "~2.118.0",
+    "@fluidframework/container-loader": "~2.118.0",
+    "@fluidframework/container-runtime": "~2.118.0",
     "@fluidframework/eslint-config-fluid": "^14.0.0",
-    "@fluidframework/local-driver": "~2.116.1",
-    "@fluidframework/test-runtime-utils": "~2.116.1",
-    "@fluidframework/test-utils": "~2.116.1",
+    "@fluidframework/local-driver": "~2.118.0",
+    "@fluidframework/test-runtime-utils": "~2.118.0",
+    "@fluidframework/test-utils": "~2.118.0",
     "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.116.0",
     "@microsoft/api-extractor": "7.58.1",
     "@types/diff": "^3.5.1",

package/src/codec/codec.ts

@@ -540,6 +540,25 @@ export const FluidClientVersion = {
 	 * - ModularChangeFormatVersion.v5 - written when minVersionForCollab \>= 2.80
 	 */
 	v2_80: "2.80.0",
+
+	/**
+	 * Fluid Framework Client 2.117 and newer.
+	 * @remarks
+	 * New formats introduced in 2.117:
+	 * - MessageFormatVersion.v7 - written when minVersionForCollab \>= 2.117
+	 * - EditManagerFormatVersion.v7 - written when minVersionForCollab \>= 2.117
+	 *
+	 * @privateRemarks
+	 * These formats are gated at 2.117.0 rather than 3.0.0 so that they can also be carried by a
+	 * 2.117.0 minor cut from the last pre-3.0 commit on main, should one be needed for consumers
+	 * that cannot yet absorb the 3.0 breaking changes. Since 3.0.0 \> 2.117.0, 3.x clients select
+	 * these formats for any minVersionForCollab at or above 2.117.0 whether or not that release
+	 * ever ships.
+	 *
+	 * Every client at or above 2.117.0 must therefore be able to read and write these formats. A
+	 * client that maps 2.117.0 to an older format would silently strip metadata when encoding.
+	 */
+	v2_117: "2.117.0",
 } as const satisfies Record<string, OldestSupportedClientVersion>;
 
 /**

package/src/core/index.ts

@@ -188,6 +188,7 @@ export {
 	type RemoteChangeMetadata,
 	type ChangeMetadata,
 	type LabelTree,
+	type CustomMetadataTree,
 	type TransactionLabels,
 	type RevisionTag,
 	RevisionTagSchema,
@@ -202,6 +203,7 @@ export {
 	tagRollbackInverse,
 	SessionIdSchema,
 	mintCommit,
+	flattenCustomMetadata,
 	rebaseBranch,
 	type BranchRebaseResult,
 	rebaseChange,
@@ -236,4 +238,6 @@ export {
 	type RevertibleFactory,
 	type RevertibleAlphaFactory,
 	type RevertibleAlpha,
+	type RevertOptionsAlpha,
+	type RevertToOptionsAlpha,
 } from "./revertible.js";

package/src/core/rebase/index.ts

@@ -9,6 +9,7 @@ export {
 	makeChangeAtomId,
 	asChangeAtomId,
 	mintCommit,
+	flattenCustomMetadata,
 	type GraphCommit,
 	CommitKind,
 	type CommitMetadata,
@@ -18,6 +19,7 @@ export {
 	type RemoteChangeMetadata,
 	type ChangeMetadata,
 	type LabelTree,
+	type CustomMetadataTree,
 	type TransactionLabels,
 	type RevisionTag,
 	RevisionTagSchema,

package/src/core/rebase/types.ts

@@ -15,6 +15,7 @@ import * as Type from "@sinclair/typebox";
 import {
 	type Brand,
 	type JsonCompatibleReadOnly,
+	type JsonCompatibleReadOnlyObject,
 	type NestedMap,
 	RangeMap,
 	brand,
@@ -166,6 +167,74 @@ export interface GraphCommit<TChange> {
 	readonly change: TChange;
 	/** The parent of this commit, on whose change this commit's change is based */
 	readonly parent?: GraphCommit<TChange>;
+	/**
+	 * Arbitrary, application-defined metadata that is persisted alongside this commit.
+	 * @remarks
+	 * Set via {@link RunTransactionParamsAlpha.customMetadata}. This is a tree rather than a single
+	 * object because a commit may be produced by nested transactions.
+	 * @privateRemarks
+	 * Always copy this property when copying a commit.
+	 */
+	readonly customMetadata: CustomMetadataTree | undefined;
+}
+
+/**
+ * A tree representing the nesting structure of transaction metadata.
+ *
+ * @remarks
+ * Each transaction contributes a node whose {@link CustomMetadataTree.metadata} is its
+ * {@link RunTransactionParamsAlpha.customMetadata | metadata} (or `undefined` if none was provided).
+ * When transactions are nested, inner transaction nodes become
+ * {@link CustomMetadataTree.children | children} of outer ones.
+ *
+ * @sealed @alpha
+ */
+export interface CustomMetadataTree {
+	/**
+	 * The metadata supplied by this transaction, or `undefined` if it supplied none.
+	 */
+	readonly metadata: JsonCompatibleReadOnlyObject | undefined;
+
+	/**
+	 * The metadata trees of any nested transactions within this one.
+	 */
+	readonly children: readonly CustomMetadataTree[];
+}
+
+/**
+ * Flattens a {@link CustomMetadataTree} into a single object.
+ * @remarks
+ * Where two transactions used the same property, the outermost one wins. Among siblings, the later one
+ * wins. Returns `undefined` if no transaction in the tree supplied any metadata.
+ */
+export function flattenCustomMetadata(
+	tree: CustomMetadataTree | undefined,
+): JsonCompatibleReadOnlyObject | undefined {
+	if (tree === undefined) {
+		return undefined;
+	}
+	let flattened: Record<string, JsonCompatibleReadOnly | undefined> | undefined;
+	const visit = (node: CustomMetadataTree): void => {
+		// Descendants first, so that a containing transaction's metadata wins on conflict.
+		for (const child of node.children) {
+			visit(child);
+		}
+		if (node.metadata !== undefined) {
+			flattened ??= {};
+			// `defineProperty` rather than assignment: assigning the valid JSON key "__proto__" would
+			// invoke the inherited setter and set the prototype instead of creating a property.
+			for (const key of Object.keys(node.metadata)) {
+				Object.defineProperty(flattened, key, {
+					value: node.metadata[key],
+					writable: true,
+					enumerable: true,
+					configurable: true,
+				});
+			}
+		}
+	};
+	visit(tree);
+	return flattened;
 }
 
 /**
@@ -210,7 +279,7 @@ export interface LocalChangeMetadata extends CommitMetadata {
 	/**
 	 * Returns a serializable object that encodes the change.
 	 * @remarks This is only available for local changes.
-	 * This change object can be {@link TreeBranchAlpha.applyChange | applied to another branch} in the same state as the one which generated it.
+	 * This change object can be {@link UntypedTreeViewAlpha.applyChange | applied to another view} in the same state as the one which generated it.
 	 * The change object must be applied to a SharedTree with the same IdCompressor session ID as it was created from.
 	 * @privateRemarks
 	 * This is a `SerializedChange` from treeCheckout.ts.
@@ -473,11 +542,12 @@ export function mintCommit<TChange>(
 	parent: GraphCommit<TChange>,
 	commit: Omit<GraphCommit<TChange>, "parent">,
 ): GraphCommit<TChange> {
-	const { revision, change } = commit;
+	const { revision, change, customMetadata } = commit;
 	return {
 		revision,
 		change,
 		parent,
+		customMetadata,
 	};
 }
 

package/src/core/rebase/utils.ts

@@ -303,6 +303,7 @@ export function rebaseBranch<TChange>(
 				revision: c.revision,
 				change,
 				parent: newHead,
+				customMetadata: c.customMetadata,
 			};
 			sourceCommits.push(newHead);
 			editsToCompose.push(tagChange(change, c.revision));

package/src/core/revertible.ts

@@ -3,7 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import type { TreeBranch } from "../simple-tree/index.js";
+import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
+
+import type { UntypedTreeView } from "../simple-tree/index.js";
 
 /**
  * Allows reversion of a change made to SharedTree.
@@ -21,6 +23,9 @@ export interface Revertible {
 
 	/**
 	 * Reverts the associated change and disposes it.
+	 *
+	 * @remarks
+	 * Concurrent changes that are sequenced before the revert will not be overwritten by the revert if they affect different parts of the document.
 	 */
 	revert(): void;
 	/**
@@ -29,6 +34,9 @@ export interface Revertible {
 	 * @param dispose - If true, the revertible will be disposed after being reverted.
 	 * If false, the revertible will remain valid. This can be useful for scenarios where the revert may be dropped
 	 * due to merge conflicts, and one wants to attempt reverting again.
+	 *
+	 * @remarks
+	 * Concurrent changes that are sequenced before the revert will not be overwritten by the revert if they affect different parts of the document.
 	 */
 	revert(dispose: boolean): void;
 
@@ -38,6 +46,43 @@ export interface Revertible {
 	dispose(): void;
 }
 
+/**
+ * Options for {@link RevertibleAlpha.(revert:3) | RevertibleAlpha.revert}.
+ *
+ * @sealed @alpha
+ */
+export interface RevertOptionsAlpha {
+	/**
+	 * If true (the default), the revertible will be disposed after being reverted.
+	 * If false, the revertible will remain valid. This can be useful for scenarios where the revert may be dropped
+	 * due to merge conflicts, and one wants to attempt reverting again.
+	 */
+	readonly dispose?: boolean;
+
+	/**
+	 * Arbitrary, application-defined metadata to attach to the commit that the revert produces.
+	 *
+	 * @remarks
+	 * See {@link RunTransactionParamsAlpha.customMetadata} for how this metadata is persisted and read back.
+	 */
+	readonly customMetadata?: JsonCompatibleReadOnlyObject;
+}
+
+/**
+ * Options for {@link UntypedTreeViewAlpha.revertTo}.
+ *
+ * @sealed @alpha
+ */
+export interface RevertToOptionsAlpha {
+	/**
+	 * Arbitrary, application-defined metadata to attach to the commit that the revert produces.
+	 *
+	 * @remarks
+	 * See {@link RunTransactionParamsAlpha.customMetadata} for how this metadata is persisted and read back.
+	 */
+	readonly customMetadata?: JsonCompatibleReadOnlyObject;
+}
+
 /**
  * A {@link Revertible} with features that are not yet stable.
  *
@@ -45,14 +90,30 @@ export interface Revertible {
  */
 export interface RevertibleAlpha extends Revertible {
 	/**
-	 * Clones the {@link Revertible} to a target branch.
+	 * {@inheritDoc Revertible.(revert:1)}
+	 */
+	revert(): void;
+	/**
+	 * {@inheritDoc Revertible.(revert:2)}
+	 */
+	revert(dispose: boolean): void;
+	/**
+	 * Reverts the associated change according to the given options.
+	 *
+	 * @remarks
+	 * Concurrent changes that are sequenced before the revert will not be overwritten by the revert if they affect different parts of the document.
+	 */
+	revert(options: RevertOptionsAlpha): void;
+
+	/**
+	 * Clones the {@link Revertible} to a target view.
 	 *
-	 * @param branch - A target branch to apply the revertible to.
-	 * The target branch must contain the same commit that this revertible is meant to revert, otherwise will throw an error.
+	 * @param view - A target view to apply the revertible to.
+	 * The target view must contain the same commit that this revertible is meant to revert, otherwise will throw an error.
 	 * @returns A cloned revertible is independent of the original, meaning disposing of one will not affect the other,
-	 * provided they do not belong to the same branch. Both revertibles can be reverted independently.
+	 * provided they do not belong to the same view. Both revertibles can be reverted independently.
 	 */
-	clone: (branch: TreeBranch) => RevertibleAlpha;
+	clone: (view: UntypedTreeView) => RevertibleAlpha;
 }
 
 /**

package/src/entrypoints/alpha.ts

@@ -121,6 +121,8 @@ export {
 	PopUnion, 
 	RecordNodeInsertableData, 
 	RunTransactionParamsBeta, 
+	SchemaCompatibilityStatusBeta,
+	SchemaDiscrepancy,
 	SchemaFactoryBeta, 
 	SchemaStaticsBeta, 
 	SchemaUpgrade, 
@@ -148,6 +150,7 @@ export {
 	UnannotateAllowedTypesList, 
 	UnannotateAllowedTypesListUnsafe, 
 	UnionToTuple, 
+	UntypedTreeView, 
 	VoidTransactionCallbackStatusBeta, 
 	WithValue, 
 	adaptEnum, 
@@ -179,8 +182,10 @@ export {
 	CodecName, 
 	CodecWriteOptions, 
 	CommitOutcome, 
+	CommitRevision, 
 	Component, 
 	CreateIndependentTreeAlphaOptions, 
+	CustomMetadataTree, 
 	DirtyTreeMap, 
 	DirtyTreeStatus, 
 	ErasedNode, 
@@ -256,6 +261,8 @@ export {
 	RemoteChangeMetadata, 
 	RevertibleAlpha, 
 	RevertibleAlphaFactory, 
+	RevertOptionsAlpha, 
+	RevertToOptionsAlpha, 
 	RunTransactionParamsAlpha, 
 	SchemaFactoryAlpha, 
 	SchemaStaticsAlpha, 
@@ -276,6 +283,7 @@ export {
 	SimpleTreeSchema, 
 	StagedSchemaUpgradePolicy, 
 	StagedSchemaUpgradePolicyFactory, 
+	StagedUpgradeStatus,
 	StringSchema, 
 	TransactionCallbackStatusAlpha, 
 	TransactionConstraintAlpha, 
@@ -284,7 +292,9 @@ export {
 	TreeAlpha, 
 	TreeArrayNodeAlpha, 
 	TreeBranchAlpha, 
+	TreeBranchCommitMetadata, 
 	TreeBranchEvents, 
+	TreeBranchHistory, 
 	TreeChangeEventsAlpha, 
 	TreeCompressionStrategy, 
 	TreeContextAlpha, 
@@ -297,6 +307,7 @@ export {
 	TreeViewAlpha, 
 	TreeViewConfigurationAlpha, 
 	UnsafeUnknownSchema, 
+	UntypedTreeViewAlpha, 
 	ValueSchema, 
 	VerboseTree, 
 	VerboseTreeNode, 

package/src/entrypoints/beta.ts

@@ -121,6 +121,8 @@ export {
 	PopUnion, 
 	RecordNodeInsertableData, 
 	RunTransactionParamsBeta, 
+	SchemaCompatibilityStatusBeta,
+	SchemaDiscrepancy,
 	SchemaFactoryBeta, 
 	SchemaStaticsBeta, 
 	SchemaUpgrade, 
@@ -148,6 +150,7 @@ export {
 	UnannotateAllowedTypesList, 
 	UnannotateAllowedTypesListUnsafe, 
 	UnionToTuple, 
+	UntypedTreeView, 
 	VoidTransactionCallbackStatusBeta, 
 	WithValue, 
 	adaptEnum, 

package/src/entrypoints/legacy.ts

@@ -121,6 +121,8 @@ export {
 	PopUnion, 
 	RecordNodeInsertableData, 
 	RunTransactionParamsBeta, 
+	SchemaCompatibilityStatusBeta,
+	SchemaDiscrepancy,
 	SchemaFactoryBeta, 
 	SchemaStaticsBeta, 
 	SchemaUpgrade, 
@@ -148,6 +150,7 @@ export {
 	UnannotateAllowedTypesList, 
 	UnannotateAllowedTypesListUnsafe, 
 	UnionToTuple, 
+	UntypedTreeView, 
 	VoidTransactionCallbackStatusBeta, 
 	WithValue, 
 	adaptEnum, 

package/src/feature-libraries/index.ts

@@ -155,7 +155,7 @@ export {
 
 export {
 	SchemaValidationError,
-	type SchemaValidationErrorContext,
+	type SchemaValidationErrorDetails,
 	isNodeInSchema,
 	isFieldInSchema,
 	throwOutOfSchema,

package/src/feature-libraries/indexing/types.ts

@@ -15,7 +15,7 @@ export type TreeIndexNodes<TNode> = readonly [first: TNode, ...rest: TNode[]];
 /**
  * An index allows lookup content from a tree using keys.
  * @remarks
- * The index will be kept up to date with the {@link TreeBranchAlpha} it is associated with.
+ * The index will be kept up to date with the {@link UntypedTreeViewAlpha} it is associated with.
  * Keeping an index up to date incurs overhead.
  * Therefore, indexes should only be created when needed and disposed when no longer needed.
  * @privateRemarks