@fluidframework/tree 2.116.1 → 2.117.0

package/src/shared-tree-core/messageCodecV1ToV4.ts

@@ -15,10 +15,12 @@ import type {
 import {
 	type JsonCompatibleReadOnlyObject,
 	JsonCompatibleReadOnlySchema,
+	type Mutable,
 } from "../util/index.js";
 
 import type { MessageDecodingContext, MessageEncodingContext } from "./messageCodecs.js";
-import type { MessageFormatVersion } from "./messageFormat.js";
+import { MessageFormatVersion } from "./messageFormat.js";
+import { decodeCustomMetadataTree, encodeCustomMetadataTree } from "./customMetadataCodec.js";
 import { Message } from "./messageFormatV1ToV4.js";
 import type { DecodedMessage } from "./messageTypes.js";
 
@@ -35,9 +37,15 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 		| typeof MessageFormatVersion.v2
 		| typeof MessageFormatVersion.v3
 		| typeof MessageFormatVersion.v4
-		| typeof MessageFormatVersion.v6,
+		| typeof MessageFormatVersion.v6
+		| typeof MessageFormatVersion.v7,
 ): CodecAndSchema<DecodedMessage<TChangeset>, MessageEncodingContext, MessageDecodingContext> {
-	const schema = Message(changeCodec.encodedSchema ?? JsonCompatibleReadOnlySchema);
+	// Persisted commit metadata was introduced in v7; older formats must not write the field.
+	const supportsCustomMetadata = version >= MessageFormatVersion.v7;
+	const schema = Message(
+		changeCodec.encodedSchema ?? JsonCompatibleReadOnlySchema,
+		supportsCustomMetadata,
+	);
 	return {
 		schema,
 		encode: (
@@ -50,7 +58,7 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 				0xc69 /* Only commit messages to main are supported */,
 			);
 			const { commit, sessionId: originatorId } = decoded;
-			return {
+			const encoded: Mutable<Message & JsonCompatibleReadOnlyObject & Versioned> = {
 				revision: revisionTagCodec.encode(commit.revision, {
 					originatorId,
 					idCompressor: context.idCompressor,
@@ -67,12 +75,16 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 				}),
 				version,
 			};
+			if (supportsCustomMetadata && commit.customMetadata !== undefined) {
+				encoded.customMetadata = encodeCustomMetadataTree(commit.customMetadata);
+			}
+			return encoded;
 		},
 		decode: (
 			encoded: Message & JsonCompatibleReadOnlyObject & Versioned,
 			context: MessageDecodingContext,
 		): DecodedMessage<TChangeset> => {
-			const { revision: encodedRevision, originatorId, changeset } = encoded;
+			const { revision: encodedRevision, originatorId, changeset, customMetadata } = encoded;
 
 			const revision = revisionTagCodec.decode(encodedRevision, {
 				originatorId,
@@ -92,6 +104,7 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 						idCompressor: context.idCompressor,
 						isSummary: false,
 					}),
+					customMetadata: decodeCustomMetadataTree(customMetadata),
 				},
 				sessionId: originatorId,
 			};

package/src/shared-tree-core/messageCodecVSharedBranches.ts

@@ -14,9 +14,10 @@ import type {
 	EncodedRevisionTag,
 	RevisionTag,
 } from "../core/index.js";
-import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
+import type { JsonCompatibleReadOnlyObject, Mutable } from "../util/index.js";
 
 import { decodeBranchId, encodeBranchId } from "./branchIdCodec.js";
+import { decodeCustomMetadataTree, encodeCustomMetadataTree } from "./customMetadataCodec.js";
 import type { MessageDecodingContext, MessageEncodingContext } from "./messageCodecs.js";
 import type { MessageFormatVersion } from "./messageFormat.js";
 import { Message } from "./messageFormatVSharedBranches.js";
@@ -51,7 +52,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 						isSummary: false,
 					};
 
-					return {
+					const encoded: Mutable<Message & JsonCompatibleReadOnlyObject & Versioned> = {
 						revision: revisionTagCodec.encode(message.commit.revision, {
 							originatorId: message.sessionId,
 							idCompressor: context.idCompressor,
@@ -63,6 +64,10 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 						branchId: encodeBranchId(context.idCompressor, message.branchId),
 						version,
 					};
+					if (message.commit.customMetadata !== undefined) {
+						encoded.customMetadata = encodeCustomMetadataTree(message.commit.customMetadata);
+					}
+					return encoded;
 				}
 				case "branch": {
 					return {
@@ -87,6 +92,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 				changeset,
 				branchId: encodedBranchId,
 				branchName: encodedBranchName,
+				customMetadata,
 			} = encoded;
 
 			const changeContext: ChangeEncodingContext = {
@@ -120,6 +126,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 						idCompressor: context.idCompressor,
 						isSummary: false,
 					}),
+					customMetadata: decodeCustomMetadataTree(customMetadata),
 				},
 				branchId,
 				sessionId: originatorId,

package/src/shared-tree-core/messageCodecs.ts

@@ -125,6 +125,18 @@ export function makeMessageCodecBuilder<TChangeset>(): VersionDispatchingCodecBu
 					MessageFormatVersion.v6,
 				),
 		},
+		{
+			minVersionForCollab: FluidClientVersion.v2_117,
+			formatVersion: MessageFormatVersion.v7,
+			codec: (options: MessageCodecBuilderOptions<TChangeset>) =>
+				makeV1ToV4CodecWithVersion(
+					options.changeCodecs.resolve(
+						options.dependentChangeFormatVersion.lookup(MessageFormatVersion.v7),
+					),
+					options.revisionTagCodec,
+					MessageFormatVersion.v7,
+				),
+		},
 		{
 			minVersionForCollab: undefined,
 			formatVersion: MessageFormatVersion.vSharedBranches,

package/src/shared-tree-core/messageFormat.ts

@@ -52,6 +52,11 @@ export const MessageFormatVersion = strictEnum("MessageFormatVersion", {
 	 * Adds support for "no change" constraints.
 	 */
 	v6: 6,
+	/**
+	 * Introduced and made available for writing in 2.117.0.
+	 * Adds support for {@link GraphCommit.customMetadata | persisted commit metadata}.
+	 */
+	v7: 7,
 	/**
 	 * Not yet released.
 	 * Only used for testing shared branches.
@@ -63,5 +68,6 @@ export const supportedMessageFormatVersions: ReadonlySet<MessageFormatVersion> =
 	MessageFormatVersion.v3,
 	MessageFormatVersion.v4,
 	MessageFormatVersion.v6,
+	MessageFormatVersion.v7,
 	MessageFormatVersion.vSharedBranches,
 ]);

package/src/shared-tree-core/messageFormatV1ToV4.ts

@@ -10,6 +10,7 @@ import type { TSchema } from "@sinclair/typebox";
 import { type EncodedRevisionTag, RevisionTagSchema, SessionIdSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 
+import { EncodedCustomMetadataTree } from "./customMetadataFormat.js";
 import { MessageFormatVersion } from "./messageFormat.js";
 
 /**
@@ -29,6 +30,12 @@ export interface Message {
 	 */
 	readonly changeset: JsonCompatibleReadOnly;
 
+	/**
+	 * Arbitrary, application-defined metadata to persist alongside the commit in this message.
+	 * @remarks Only written at {@link MessageFormatVersion.v7} and later.
+	 */
+	readonly customMetadata?: EncodedCustomMetadataTree;
+
 	/**
 	 * The version of the message. This controls how the message is encoded.
 	 *
@@ -40,16 +47,25 @@ export interface Message {
 		| typeof MessageFormatVersion.v2
 		| typeof MessageFormatVersion.v3
 		| typeof MessageFormatVersion.v4
-		| typeof MessageFormatVersion.v6;
+		| typeof MessageFormatVersion.v6
+		| typeof MessageFormatVersion.v7;
 }
 
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
 // Return type is intentionally derived.
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+// Unlike the summary formats, this schema does not set `additionalProperties: false`: the op envelope
+// has always tolerated unknown properties, and tightening it could reject ops from other versions.
+export const Message = <ChangeSchema extends TSchema>(
+	tChange: ChangeSchema,
+	includeCustomMetadata: boolean,
+) =>
 	Type.Object({
 		revision: RevisionTagSchema,
 		originatorId: SessionIdSchema,
 		changeset: tChange,
+		...(includeCustomMetadata
+			? { customMetadata: Type.Optional(EncodedCustomMetadataTree) }
+			: {}),
 		version: Type.Optional(
 			Type.Union([
 				Type.Literal(MessageFormatVersion.v1),
@@ -57,6 +73,8 @@ export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 				Type.Literal(MessageFormatVersion.v3),
 				Type.Literal(MessageFormatVersion.v4),
 				Type.Literal(MessageFormatVersion.v6),
+				Type.Literal(MessageFormatVersion.v7),
 			]),
 		),
 	});
+/* eslint-enable @typescript-eslint/explicit-function-return-type */

package/src/shared-tree-core/messageFormatVSharedBranches.ts

@@ -11,6 +11,7 @@ import { type EncodedRevisionTag, RevisionTagSchema, SessionIdSchema } from "../
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 
 import type { EncodedBranchId } from "./branch.js";
+import { EncodedCustomMetadataTree } from "./customMetadataFormat.js";
 import { MessageFormatVersion } from "./messageFormat.js";
 
 /**
@@ -41,6 +42,12 @@ export interface Message {
 	 */
 	readonly branchName?: string;
 
+	/**
+	 * Arbitrary, application-defined metadata to persist alongside the commit in this message.
+	 * @remarks See {@link GraphCommit.customMetadata}.
+	 */
+	readonly customMetadata?: EncodedCustomMetadataTree;
+
 	/**
 	 * The version of the message format.
 	 */
@@ -56,5 +63,6 @@ export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 		changeset: Type.Optional(tChange),
 		branchId: Type.Optional(Type.Number()),
 		branchName: Type.Optional(Type.String()),
+		customMetadata: Type.Optional(EncodedCustomMetadataTree),
 		version: Type.Literal(MessageFormatVersion.vSharedBranches),
 	});

package/src/shared-tree-core/sharedTreeCore.ts

@@ -30,6 +30,7 @@ import type { CodecWriteOptions, DependentFormatVersion, IJsonCodec } from "../c
 import {
 	type ChangeFamily,
 	type ChangeFamilyEditor,
+	CommitKind,
 	type GraphCommit,
 	replaceChange,
 	type RevisionTag,
@@ -669,10 +670,12 @@ export class SharedTreeCore<
 		switch (type) {
 			case "commit": {
 				const {
-					commit: { revision, change },
+					commit: { revision, change, customMetadata },
 					branchId,
 				} = message;
-				this.editManager.getLocalBranch(branchId).apply({ change, revision });
+				this.editManager
+					.getLocalBranch(branchId)
+					.apply({ change, revision }, CommitKind.Default, customMetadata);
 				break;
 			}
 			case "branch": {

package/src/shared-tree-core/transaction.ts

@@ -15,15 +15,25 @@ import {
 	mintCommit,
 	rebaseBranch,
 	tagChange,
+	CommitKind,
 	type ChangeFamilyEditor,
+	type CustomMetadataTree,
 	type GraphCommit,
 	type ProcessChangeFn,
 	type RevisionTag,
 } from "../core/index.js";
-import { getLast, getOrCreate } from "../util/index.js";
+import { getLast, getOrCreate, type JsonCompatibleReadOnlyObject } from "../util/index.js";
 
 import type { SharedTreeBranch, SharedTreeBranchEvents } from "./branch.js";
 
+/**
+ * A {@link CustomMetadataTree} under construction.
+ */
+interface MutableCustomMetadataTree {
+	metadata: JsonCompatibleReadOnlyObject | undefined;
+	children: MutableCustomMetadataTree[];
+}
+
 /**
  * Describes the result of a transaction.
  * Transactions may either succeed and commit, or fail and abort.
@@ -290,6 +300,15 @@ export interface SquashingTransactionOptions<TChange, TChangeProcessingContext>
 	 * {@link ChangeProcessor.applicability | applicability}.
 	 */
 	readonly postProcessor?: ChangeProcessor<TChange, TChangeProcessingContext>;
+
+	/**
+	 * Arbitrary, application-defined metadata to attach to the commit that this transaction produces.
+	 *
+	 * @remarks
+	 * Each transaction in the stack contributes a node to the resulting {@link CustomMetadataTree}. If
+	 * the transaction produces no commit, the metadata is discarded.
+	 */
+	readonly customMetadata?: JsonCompatibleReadOnlyObject;
 }
 
 /**
@@ -409,6 +428,15 @@ export class SquashingTransactionStack<
 				startOptions?: SquashingTransactionOptions<TChange, TChangeProcessingContext>,
 			): Callbacks<SquashingTransactionOptions<TChange, TChangeProcessingContext>> => {
 				postProcessorStack.push(resolvePostProcessor(startOptions?.postProcessor));
+				// Each transaction in the stack contributes a node to a tree mirroring the nesting, which is
+				// attached to the single commit they produce. `openMetadataNode` is the innermost open node.
+				const rootMetadataNode: MutableCustomMetadataTree = {
+					metadata: startOptions?.customMetadata,
+					children: [],
+				};
+				let openMetadataNode = rootMetadataNode;
+				const hasCustomMetadata = (node: CustomMetadataTree): boolean =>
+					node.metadata !== undefined || node.children.some(hasCustomMetadata);
 				// Keep track of the commit that each transaction was on when it started
 				const startHead = this.activeBranch.getHead();
 				const changeFamily = this.branch.changeFamily;
@@ -490,19 +518,31 @@ export class SquashingTransactionStack<
 									// change in their place so that the view fully reflects the modified
 									// `change`.
 									transactionBranch.removeAfter(startHead);
-									transactionBranch.apply(tagChange(change, transactionRevision));
+									transactionBranch.apply(
+										tagChange(change, transactionRevision),
+										CommitKind.Default,
+										undefined,
+									);
 								}
 
+								const customMetadata = hasCustomMetadata(rootMetadataNode)
+									? rootMetadataNode
+									: undefined;
 								if (targetPath.length === 0) {
 									// No changes were made on the original branch since the transaction began
 									// The transaction commit can be applied directly
-									this.branch.apply(tagChange(change, transactionRevision));
+									this.branch.apply(
+										tagChange(change, transactionRevision),
+										CommitKind.Default,
+										customMetadata,
+									);
 									// The view is already up-to-date so there's nothing more to do
 								} else {
 									// Some changes were made on `branch` since the transaction began
 									const unrebasedHead = mintCommit(startHead, {
 										change,
 										revision: transactionRevision,
+										customMetadata,
 									});
 									// We need to rebase the transaction commit on top of the new changes
 									const rebased = rebaseBranch(
@@ -515,7 +555,7 @@ export class SquashingTransactionStack<
 										rebased.newSourceHead.revision === transactionRevision,
 										0xcd0 /* The transaction commit should be rebased to the tip */,
 									);
-									this.branch.apply(rebased.newSourceHead);
+									this.branch.apply(rebased.newSourceHead, CommitKind.Default, customMetadata);
 									viewUpdate = rebased.sourceChange;
 								}
 							} else {
@@ -546,6 +586,13 @@ export class SquashingTransactionStack<
 					SquashingTransactionOptions<TChange, TChangeProcessingContext>
 				> = (nestedStartOptions) => {
 					postProcessorStack.push(resolvePostProcessor(nestedStartOptions?.postProcessor));
+					const nestedMetadataNode: MutableCustomMetadataTree = {
+						metadata: nestedStartOptions?.customMetadata,
+						children: [],
+					};
+					const metadataParent = openMetadataNode;
+					metadataParent.children.push(nestedMetadataNode);
+					openMetadataNode = nestedMetadataNode;
 					const nestedStartHead = this.activeBranch.getHead();
 					const nestedOuterOnPop = onPush?.();
 					transactionBranch.editor.enterTransaction();
@@ -553,9 +600,12 @@ export class SquashingTransactionStack<
 						// Invoked when a nested transaction ends
 						onPop: (result) => {
 							const nestedPostProcessor = postProcessorStack.pop();
+							openMetadataNode = metadataParent;
 							transactionBranch.editor.exitTransaction();
 							switch (result) {
 								case TransactionResult.Abort: {
+									// The aborted transaction contributed nothing; its node is necessarily the last child.
+									metadataParent.children.pop();
 									// When a transaction is aborted, roll back all the transaction's changes on the current branch
 									transactionBranch.removeAfter(nestedStartHead);
 									break;
@@ -585,6 +635,8 @@ export class SquashingTransactionStack<
 												transactionBranch.removeAfter(nestedStartHead);
 												transactionBranch.apply(
 													tagChange(processedSquash, transactionRevision),
+													CommitKind.Default,
+													undefined,
 												);
 											}
 										}

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

@@ -13,6 +13,7 @@ export {
 	TreeViewConfigurationAlpha,
 } from "./configuration.js";
 export type {
+	CommitRevision,
 	ITree,
 	TreeView,
 	ViewableTree,
@@ -20,9 +21,13 @@ export type {
 	SchemaCompatibilityStatus,
 	TreeViewAlpha,
 	TreeViewBeta,
+	UntypedTreeView,
 	TreeBranch,
 	TreeBranchAlpha,
+	UntypedTreeViewAlpha,
 	TreeBranchEvents,
+	TreeBranchCommitMetadata,
+	TreeBranchHistory,
 	TreeContextAlpha,
 	ITreeAlpha,
 } from "./tree.js";

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

@@ -6,6 +6,7 @@
 import type { ErasedType } from "@fluidframework/core-interfaces";
 
 import type { TreeNode } from "../core/index.js";
+import type { JsonCompatibleReadOnlyObject } from "../../util/index.js";
 
 /**
  * A special object that signifies when a SharedTree {@link RunTransaction | transaction} should "roll back".
@@ -103,7 +104,7 @@ export type TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue> =
 	};
 
 /**
- * The result of a {@link TreeBranchAlpha.(runTransaction:2) | transaction} that doesn't return a value.
+ * The result of a {@link UntypedTreeViewAlpha.(runTransaction:2) | transaction} that doesn't return a value.
  * @input
  * @alpha
  */
@@ -181,7 +182,7 @@ export interface RunTransactionParamsBeta {
 	/**
 	 * A label for this transaction that allows it to be correlated with later edits (e.g. for controlling undo/redo grouping).
 	 * @remarks
-	 * If this transaction is applied to a {@link TreeBranchAlpha | branch}, the label will be available in the {@link LocalChangeMetadata.label | metadata} of the {@link TreeBranchEvents.changed | `changed`} event.
+	 * If this transaction is applied to an {@link UntypedTreeViewAlpha | untyped view}, the label will be available in the {@link LocalChangeMetadata.label | metadata} of the {@link TreeBranchEvents.changed | `changed`} event.
 	 *
 	 * If there is a nested transaction, only the outermost transaction label will be used.
 	 */
@@ -218,4 +219,30 @@ export interface RunTransactionParamsAlpha extends RunTransactionParamsBeta {
 	 * reserving the behavior; a real post-processor will be provided in a future change.
 	 */
 	readonly postProcessor?: TransactionPostProcessor;
+
+	/**
+	 * Arbitrary, application-defined metadata to persist alongside the commit that this transaction produces.
+	 * @remarks
+	 * The metadata is replicated to all collaborating clients and persisted in the document, and is readable
+	 * via {@link TreeBranchCommitMetadata.custom} while walking the branch's
+	 * {@link UntypedTreeViewAlpha.branchHistory | history}. It shares the lifetime of the commit it is attached
+	 * to: once that commit is trimmed from the trunk, the metadata goes with it. If the transaction produces no
+	 * commit — because its body made no changes, or because it was rolled back — the metadata is discarded.
+	 *
+	 * Nested transactions all contribute to the single commit they produce, and their metadata is available
+	 * both flattened via {@link TreeBranchCommitMetadata.custom} and structurally via
+	 * {@link TreeBranchCommitMetadata.customTree}.
+	 *
+	 * To attach metadata to the commit produced by
+	 * {@link RevertibleAlpha.(revert:3) | reverting}, use {@link RevertOptionsAlpha.customMetadata} instead.
+	 *
+	 * The value is snapshotted when the transaction starts and normalized as `JSON.stringify` would. An error is
+	 * thrown if it cannot be represented as a JSON object at all, such as when it contains a cycle or a
+	 * `bigint`. Because it is persisted, it should be kept small; it is also bounded by the runtime's maximum
+	 * op size.
+	 *
+	 * Metadata is only written to the document when `minVersionForCollab` is set to `"2.117.0"` or later.
+	 * Otherwise it is retained in memory for the local session but not persisted or replicated.
+	 */
+	readonly customMetadata?: JsonCompatibleReadOnlyObject;
 }