@fluidframework/tree 2.111.0 → 2.112.0

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

@@ -11,6 +11,7 @@ import type {
 	IIdCompressor,
 	SessionId,
 	SessionSpaceCompressedId,
+	StableId,
 } from "@fluidframework/id-compressor";
 import type {
 	IExperimentalIncrementalSummaryContext,
@@ -23,7 +24,7 @@ import type {
 	IChannelView,
 	IFluidSerializer,
 } from "@fluidframework/shared-object-base/internal";
-import { createChildLogger } from "@fluidframework/telemetry-utils/internal";
+import { createChildLogger, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { CodecWriteOptions, DependentFormatVersion, IJsonCodec } from "../codec/index.js";
 import {
@@ -78,6 +79,11 @@ export interface SharedTreeCoreOptionsInternal extends CodecWriteOptions {
 	 * See {@link SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode}.
 	 */
 	readonly healUnresolvableIdentifiersOnDecode?: boolean;
+
+	/**
+	 * {@inheritDoc SharedTreeOptions.retainHistory}
+	 */
+	readonly retainHistory?: boolean;
 }
 
 export interface EnrichmentConfig<TChange> {
@@ -124,6 +130,8 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 
 	private readonly schemaAndPolicy: ClonableSchemaAndPolicy;
 
+	private static readonly maxBranchNameLength = 1024;
+
 	/**
 	 * @param summarizables - Summarizers for all indexes used by this tree
 	 * @param changeFamily - The change family
@@ -179,6 +187,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			this.mintRevisionTag,
 			(branchId) => this.registerSharedBranch(branchId),
 			rebaseLogger,
+			options.retainHistory ?? false,
 		);
 
 		this.registerSharedBranch("main");
@@ -391,9 +400,9 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		this.getResubmitMachine(branchId).onCommitSubmitted(enrichedCommit);
 	}
 
-	protected submitBranchCreation(branchId: BranchId): void {
+	protected submitBranchCreation(branchId: BranchId, branchName?: string): void {
 		this.submitMessage(
-			{ type: "branch", sessionId: this.editManager.localSessionId, branchId },
+			{ type: "branch", sessionId: this.editManager.localSessionId, branchId, branchName },
 			this.schemaAndPolicy,
 		);
 	}
@@ -471,6 +480,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 						messagesSessionId,
 						brand(envelope.referenceSequenceNumber),
 						message.branchId,
+						message.branchName,
 					);
 					break;
 				}
@@ -519,21 +529,34 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			.filter((id): id is SessionSpaceCompressedId => id !== "main")
 			.map((id) => this.idCompressor.decompress(id));
 	}
-	public createSharedBranch(): string {
+	public createSharedBranch(branchName?: string): string {
+		if (branchName !== undefined && branchName.length > SharedTreeCore.maxBranchNameLength) {
+			throw new UsageError(
+				`Branch name is too long: ${branchName.length} > maxBranchNameLength`,
+			);
+		}
 		const branchId = this.idCompressor.generateCompressedId();
-		this.addBranch(branchId);
-		this.submitBranchCreation(branchId);
+		this.addBranch(branchId, branchName);
+		this.submitBranchCreation(branchId, branchName);
 		return this.idCompressor.decompress(branchId);
 	}
 
-	protected addBranch(branchId: BranchId): void {
-		this.editManager.addNewBranch(branchId);
+	protected addBranch(branchId: BranchId, branchName?: string): void {
+		this.editManager.addNewBranch(branchId, branchName);
 	}
 
 	public getSharedBranch(branchId: BranchId): SharedTreeBranch<TEditor, TChange> {
 		return this.editManager.getLocalBranch(branchId);
 	}
 
+	public getSharedBranchName(branchId: string): string | undefined {
+		const compressedId = this.idCompressor.tryRecompress(branchId as StableId);
+		if (compressedId === undefined) {
+			throw new UsageError(`No branch found with id: ${branchId}`);
+		}
+		return this.editManager.getSharedBranchName(compressedId);
+	}
+
 	public didAttach(): void {
 		this.detachedRevision = undefined;
 	}
@@ -574,7 +597,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				break;
 			}
 			case "branch": {
-				this.submitBranchCreation(message.branchId);
+				this.submitBranchCreation(message.branchId, message.branchName);
 				break;
 			}
 			default: {
@@ -631,7 +654,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				break;
 			}
 			case "branch": {
-				this.editManager.addNewBranch(message.branchId);
+				this.editManager.addNewBranch(message.branchId, message.branchName);
 				break;
 			}
 			default: {

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

@@ -464,6 +464,17 @@ export class SquashingTransactionStack<
 								const change =
 									postProcessor === undefined ? squash : postProcessor.processChange(squash);
 
+								if (change !== squash) {
+									// The post-processor produced a change that differs from the
+									// one that was applied to the view as the transaction's edits
+									// were made. Roll back the transaction's changes on the transaction
+									// branch (which rolls back the view) and apply the post-processed
+									// change in their place so that the view fully reflects the modified
+									// `change`.
+									transactionBranch.removeAfter(startHead);
+									transactionBranch.apply(tagChange(change, transactionRevision));
+								}
+
 								if (targetPath.length === 0) {
 									// No changes were made on the original branch since the transaction began
 									// The transaction commit can be applied directly
@@ -548,8 +559,14 @@ export class SquashingTransactionStack<
 											);
 											const squash = rebaser.compose(nestedSteps);
 											const processedSquash = nestedPostProcessor.processChange(squash);
-											transactionBranch.removeAfter(nestedStartHead);
-											transactionBranch.apply(tagChange(processedSquash, transactionRevision));
+											// Roll back the transaction branch to the nested start head and apply the
+											// processed change if it differs from the original change.
+											if (processedSquash !== squash) {
+												transactionBranch.removeAfter(nestedStartHead);
+												transactionBranch.apply(
+													tagChange(processedSquash, transactionRevision),
+												);
+											}
 										}
 									}
 									break;

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

@@ -100,7 +100,7 @@ export {
 export type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 export { getJsonSchema } from "./getJsonSchema.js";
 export { getSimpleSchema } from "./getSimpleSchema.js";
-export { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
+export { checkSchemaCompatibility } from "./schemaCompatibilityTester.js";
 export type {
 	Unenforced,
 	FieldSchemaAlphaUnsafe,

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

@@ -12,58 +12,46 @@ import { getDiscrepanciesInAllowedContent } from "./discrepancies.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";
 
 /**
- * A collection of View information for schema
+ * Determines the compatibility of a stored document
+ * (based on its stored schema) with a viewer (based on its view schema).
+ *
  * @remarks
- * This contains everything needed to determine compatibility with a given stored schema.
+ * Adapters can be provided to handle differences between the two schema.
+ * Adapters should only use to types in the `view` SchemaRepository.
+ *
+ * TODO: this API violates the parse don't validate design philosophy.
+ * It should be wrapped with (or replaced by) a parse style API.
  */
-export class SchemaCompatibilityTester {
-	public constructor(
-		/**
-		 * Schema for the view
-		 */
-		public readonly viewSchema: TreeSchema,
-	) {}
-
-	/**
-	 * Determines the compatibility of a stored document
-	 * (based on its stored schema) with a viewer (based on its view schema).
-	 *
-	 * Adapters can be provided to handle differences between the two schema.
-	 * Adapters should only use to types in the `view` SchemaRepository.
-	 *
-	 * TODO: this API violates the parse don't validate design philosophy.
-	 * It should be wrapped with (or replaced by) a parse style API.
-	 */
-	public checkCompatibility(
-		stored: TreeStoredSchema,
-	): Omit<SchemaCompatibilityStatus, "canInitialize"> {
-		// The public API surface assumes defaultSchemaPolicy
-		const policy = defaultSchemaPolicy;
-
-		// View schema allows a subset of documents that stored schema does, and the discrepancies are allowed by policy
-		// determined by the view schema (i.e. objects with extra optional fields in the stored schema have opted into allowing this.
-		// In the future, this would also include things like:
-		// - fields with more allowed types in the stored schema than in the view schema have out-of-schema "unknown content" adapters
-		let canView = true;
-
-		for (const _discrepancy of getDiscrepanciesInAllowedContent(this.viewSchema, stored)) {
-			canView = false;
-			break;
-		}
+export function checkSchemaCompatibility(
+	viewSchema: TreeSchema,
+	stored: TreeStoredSchema,
+): Omit<SchemaCompatibilityStatus, "canInitialize"> {
+	// The public API surface assumes defaultSchemaPolicy
+	const policy = defaultSchemaPolicy;
+
+	// View schema allows a subset of documents that stored schema does, and the discrepancies are allowed by policy
+	// determined by the view schema (i.e. objects with extra optional fields in the stored schema have opted into allowing this.
+	// In the future, this would also include things like:
+	// - fields with more allowed types in the stored schema than in the view schema have out-of-schema "unknown content" adapters
+	let canView = true;
+
+	for (const _discrepancy of getDiscrepanciesInAllowedContent(viewSchema, stored)) {
+		canView = false;
+		break;
+	}
 
-		const wouldUpgradeTo = toUpgradeSchema(this.viewSchema.root);
+	const wouldUpgradeTo = toUpgradeSchema(viewSchema.root);
 
-		const canUpgrade = allowsRepoSuperset(policy, stored, wouldUpgradeTo);
+	const canUpgrade = allowsRepoSuperset(policy, stored, wouldUpgradeTo);
 
-		// If true, then upgrading has no effect on what can be stored in the document.
-		// TODO: This should likely be changed to indicate up a schema upgrade would be a no-op, including stored schema metadata.
-		const isEquivalent =
-			canView && canUpgrade && allowsRepoSuperset(policy, wouldUpgradeTo, stored);
+	// If true, then upgrading has no effect on what can be stored in the document.
+	// TODO: This should likely be changed to indicate up a schema upgrade would be a no-op, including stored schema metadata.
+	const isEquivalent =
+		canView && canUpgrade && allowsRepoSuperset(policy, wouldUpgradeTo, stored);
 
-		return {
-			canView,
-			canUpgrade,
-			isEquivalent,
-		};
-	}
+	return {
+		canView,
+		canUpgrade,
+		isEquivalent,
+	};
 }

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

@@ -80,6 +80,8 @@ import type {
  * Values should be preferred over generator functions when possible, as they are simpler and more efficient.
  * Generator functions should be used when the default value needs to be dynamic or when it is not possible to provide a value directly.
  *
+ * See {@link SchemaStaticsAlpha.withDefault} for the primary API that uses this type.
+ *
  * @example
  * ```typescript
  * // Provide a value directly
@@ -102,27 +104,63 @@ export type NodeProvider<T> = T | (() => T);
  */
 export interface SchemaStaticsAlpha {
 	/**
-	 * Creates a field schema with a default value. Fields with defaults (whether required or optional) are recognized by the type system as optional in constructors,
-	 * allowing them to be omitted when creating new nodes.
+	 * Creates a field schema with a default value.
+	 *
+	 * @remarks
+	 * Fields with defaults are optional in constructors, allowing them to be omitted when creating new nodes.
+	 * This works with both {@link SchemaStatics.required | required} and {@link SchemaStatics.optional | optional} fields:
+	 *
+	 * - **Required fields with defaults**: The field is always present in the tree, but can be omitted from the constructor.
+	 * The default value is used when the field is not provided.
+	 *
+	 * - **Optional fields with defaults**: Optional fields already default to `undefined`, but `withDefault` lets you
+	 * specify a different default value.
+	 *
+	 * The default value can be provided in two ways (see {@link NodeProvider}):
+	 *
+	 * 1. **A value**: The value is deep-copied for each use, ensuring independence between instances.
+	 * Prefer this when the default is a fixed value.
+	 *
+	 * 2. **A generator function**: A function called each time a default is needed. Use this for dynamic defaults
+	 * (e.g., timestamps, UUIDs) or when explicit control over value creation is required.
+	 *
+	 * Defaults are evaluated eagerly during node construction.
+	 *
+	 * For recursive schemas, use {@link SchemaStaticsAlpha.withDefaultRecursive} instead.
+	 *
+	 * See the {@link https://fluidframework.com/docs/data-structures/tree/schema-definition/default-field-values | Default Field Values documentation}
+	 * for a comprehensive guide with additional examples.
 	 *
 	 * @param fieldSchema - The field schema to add a default to (e.g., `factory.required(factory.string)` or `factory.optional(factory.number)`)
 	 * @param defaultValue - A {@link NodeProvider} specifying the default value.
 	 *
 	 * @example
+	 * A schema with a mix of required, defaulted, and dynamic fields:
 	 * ```typescript
-	 * const MySchema = factory.objectAlpha("MyObject", {
-	 *     // Provide values directly
-	 *     name: factory.withDefault(factory.required(factory.string), "untitled"),
-	 *     count: factory.withDefault(factory.required(factory.number), 0),
-	 *     metadata: factory.withDefault(factory.optional(Metadata), new Metadata({ version: 1 })),
-	 *
-	 *     // Use generator functions for dynamic values
-	 *     timestamp: factory.withDefault(factory.required(factory.number), () => Date.now()),
-	 *     id: factory.withDefault(factory.required(factory.string), () => crypto.randomUUID()),
-	 * });
-	 *
-	 * const obj1 = new MySchema({}); // All defaults applied
-	 * const obj2 = new MySchema({ name: "custom" }); // name="custom", other defaults applied
+	 * const factory = new SchemaFactoryAlpha("example");
+	 *
+	 * class Task extends factory.objectAlpha("Task", {
+	 *     // No default — must always be provided in the constructor
+	 *     title: factory.required(factory.string),
+	 *
+	 *     // Required field with a static default
+	 *     status: factory.withDefault(factory.required(factory.string), "todo"),
+	 *
+	 *     // Optional field with a custom default (instead of `undefined`)
+	 *     priority: factory.withDefault(factory.optional(factory.number), 0),
+	 *
+	 *     // Dynamic default using a generator function
+	 *     createdAt: factory.withDefault(factory.required(factory.number), () => Date.now()),
+	 * }) {}
+	 *
+	 * // Only `title` is required in the constructor; the rest use their defaults
+	 * const task = new Task({ title: "Write docs" });
+	 * // task.status === "todo"
+	 * // task.priority === 0
+	 * // task.createdAt is set to the current timestamp
+	 *
+	 * // Defaults can be overridden by providing explicit values
+	 * const urgentTask = new Task({ title: "Fix bug", status: "in-progress", priority: 1 });
 	 * ```
 	 *
 	 * @privateRemarks
@@ -208,6 +246,9 @@ export interface SchemaStaticsAlpha {
 	 * @remarks
 	 * This version of {@link SchemaStaticsAlpha.withDefault} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
 	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 *
+	 * See the {@link https://fluidframework.com/docs/data-structures/tree/schema-definition/default-field-values#recursive-types | Default Field Values — Recursive Types documentation}
+	 * for usage examples and guidance on avoiding infinite recursion with recursive defaults.
 	 */
 	withDefaultRecursive: <
 		Kind extends FieldKind,

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

@@ -94,9 +94,6 @@ export interface SchemaStaticsBeta {
 	 * A full code example of the schema migration process can be found in our {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/src/test/simple-tree/api/stagedSchemaUpgrade.spec.ts | tests}.
 	 *
 	 * @privateRemarks
-	 * TODO:#44317 staged allowed types rely on schema validation of stored schema to output errors, these errors are not very
-	 * user friendly and should be improved, particularly in the case of staged allowed types
-	 *
 	 * TODO: AB#45711: Update the docs above when recursive type support is added.
 	 */
 	readonly staged: <const T extends LazyItem<TreeNodeSchema>>(

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

@@ -13,7 +13,7 @@ import { toInitialSchema } from "../toStoredSchema.js";
 import { createTreeSchema } from "../treeSchema.js";
 
 import { TreeViewConfigurationAlpha, TreeViewConfiguration } from "./configuration.js";
-import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
+import { checkSchemaCompatibility } from "./schemaCompatibilityTester.js";
 import { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
 import {
 	decodeSchemaCompatibilitySnapshot,
@@ -78,8 +78,7 @@ export function checkCompatibility(
 ): Omit<SchemaCompatibilityStatus, "canInitialize"> {
 	const viewAsAlpha = new TreeViewConfigurationAlpha({ schema: view.schema });
 	const stored = toInitialSchema(viewWhichCreatedStoredSchema.schema);
-	const tester = new SchemaCompatibilityTester(viewAsAlpha);
-	return tester.checkCompatibility(stored);
+	return checkSchemaCompatibility(viewAsAlpha, stored);
 }
 
 /**

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

@@ -13,7 +13,7 @@ import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.j
 import { toStoredSchema } from "../toStoredSchema.js";
 
 import { TreeViewConfigurationAlpha } from "./configuration.js";
-import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
+import { checkSchemaCompatibility } from "./schemaCompatibilityTester.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";
 
 /**
@@ -104,6 +104,5 @@ export function comparePersistedSchema(
 	const config = new TreeViewConfigurationAlpha({
 		schema: normalizeFieldSchema(view),
 	});
-	const viewSchema = new SchemaCompatibilityTester(config);
-	return viewSchema.checkCompatibility(stored);
+	return checkSchemaCompatibility(config, stored);
 }

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

@@ -112,8 +112,20 @@ export interface ITreeAlpha extends ITree {
 	/**
 	 * Creates a fork of the current state of the main branch.
 	 * This new branch will be shared with and editable by all clients.
+	 * @param name - Optional name for the new branch.
+	 * This name is not guaranteed to be unique.
+	 * (Maximum {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length | length}: 1024)
+	 * @returns The ID of the new branch, which can be used to {@link ITreeAlpha.viewSharedBranchWith | view} the branch.
 	 */
-	createSharedBranch(): string;
+	createSharedBranch(name?: string): string;
+
+	/**
+	 * Retrieves the name, if any, of the shared branch with the given ID.
+	 * @param branchId - The ID of the shared branch to retrieve the name of.
+	 * @returns The name of the shared branch, or `undefined` if the branch has no assigned name.
+	 * @throws if the branch with the given ID does not exist.
+	 */
+	getSharedBranchName(branchId: string): string | undefined;
 
 	/**
 	 * Returns a list of all shared branches that currently exist on this tree.
@@ -376,6 +388,16 @@ export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
 	 * @throws UsageError if the branches are unrelated.
 	 */
 	isMissingEditsFrom(branch: TreeBranch): boolean;
+
+	/**
+	 * Computes the net change that would result if this branch were {@link TreeBranch.rebaseOnto | rebased onto} the given branch.
+	 * Note that this method does not actually perform the rebase and therefore has no effect on this branch.
+	 *
+	 * @param branch - The branch that would be rebased onto.
+	 * @returns The net change that would result if this branch were rebased onto the given branch,
+	 * or `undefined` if rebasing would have no impact.
+	 */
+	computeNetChangeIfRebasedOnto(branch: TreeBranch): JsonCompatibleReadOnly | undefined;
 }
 
 /**
@@ -578,7 +600,7 @@ export interface TreeViewAlpha<
  * See SharedTree's README for more information about choosing a compatibility policy.
  *
  * @privateRemarks
- * See {@link SchemaCompatibilityTester} for the implementation of this compatibility checking.
+ * See {@link checkSchemaCompatibility} for the implementation of this compatibility checking.
  *
  * @sealed @public
  */

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

@@ -21,6 +21,7 @@ import type {
 	TreeLeafValue,
 	FlexListToUnion,
 	LazyItem,
+	NumberKeys,
 	AnnotatedAllowedType,
 	AnnotatedAllowedTypes,
 } from "../core/index.js";
@@ -260,7 +261,7 @@ export namespace System_Unsafe {
 					>
 						? InsertableTypedNodeUnsafe<TSchema>
 						: never;
-				}[number];
+				}[NumberKeys<TList>];
 
 	/**
 	 * {@link Unenforced} version of {@link InsertableTypedNode}.

package/src/simple-tree/index.ts

@@ -140,7 +140,7 @@ export {
 	extractPersistedSchema,
 	comparePersistedSchema,
 	type ConciseTree,
-	SchemaCompatibilityTester,
+	checkSchemaCompatibility,
 	type Unenforced,
 	type System_Unsafe,
 	type ArrayNodeCustomizableSchemaUnsafe,