@fluidframework/tree 2.110.0 → 2.112.0

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

@@ -40,15 +40,17 @@ export enum TransactionResult {
 
 /**
  * A simple API for managing transactions.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
  */
-export interface Transactor {
+export interface Transactor<TOptions> {
 	/**
 	 * Start a new transaction.
+	 * @param options - Options controlling how the transaction is committed.
 	 * @remarks
 	 * If a transaction is already in progress when this new transaction starts, then this transaction will be "nested" inside of it,
 	 * i.e. the outer transaction will still be in progress after this new transaction is committed or aborted.
 	 */
-	start(): void;
+	start(options?: TOptions): void;
 	/**
 	 * Close this transaction by squashing its edits and committing them as a single edit.
 	 * @remarks If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.
@@ -89,8 +91,9 @@ export interface TransactionEvents {
 
 /**
  * Callbacks for transaction lifecycle events.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
  */
-export interface Callbacks {
+export interface Callbacks<TOptions> {
 	/**
 	 * Called when the current transaction is popped from the {@link TransactionStack | stack}.
 	 */
@@ -104,37 +107,42 @@ export interface Callbacks {
 	 * Put another way, a transaction always results in a call to exactly one `OnPush` callback - whichever is closest to the transaction.
 	 * The event "bubbles up" to (and no further past) its first registered callback.
 	 */
-	readonly onPush?: OnPush;
+	readonly onPush?: OnPush<TOptions>;
 }
 
 /**
  * A function that will be called when a transaction is pushed to the {@link TransactionStack | stack}.
  * @remarks This function may return other functions that will be called when the transaction is popped from the stack or a nested transaction is pushed onto the stack.
  * This function runs just before the transaction begins, so if this is the beginning of an outermost (not nested) transaction then {@link Transactor.size} will be 0 during its execution.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
+ * @param options - The options passed to {@link Transactor.start | start}.
  */
-export type OnPush = () => Callbacks | void;
+export type OnPush<TOptions> = (options?: TOptions) => Callbacks<TOptions> | void;
 
 /**
  * A function that will be called when a transaction is popped from the {@link TransactionStack | stack}.
  * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.size} will be 0 during its execution.
+ * @param result - The result of the transaction.
  */
 export type OnPop = (result: TransactionResult) => void;
 
 /**
  * A frame in the transaction stack.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
  */
-interface TransactionStackFrame {
+interface TransactionStackFrame<TOptions> {
 	/** The callbacks provided when this transaction frame was pushed onto the stack. */
-	readonly callbacks: Callbacks;
+	readonly callbacks: Callbacks<TOptions>;
 }
 
 /**
  * An implementation of {@link Transactor} that uses a stack to manage transactions.
  * @remarks Using a stack allows transactions to nest - i.e. an inner transaction may be started while an outer transaction is already in progress.
+ * @typeParam TOptions - The type of the options passed to {@link Transactor.start | start}.
  */
-export class TransactionStack implements Transactor, IDisposable {
-	readonly #stack: TransactionStackFrame[] = [];
-	readonly #onPush?: OnPush;
+export class TransactionStack<TOptions> implements Transactor<TOptions>, IDisposable {
+	readonly #stack: TransactionStackFrame<TOptions>[] = [];
+	readonly #onPush?: OnPush<TOptions>;
 
 	readonly #events = createEmitter<TransactionEvents>();
 	public get events(): Listenable<TransactionEvents> {
@@ -150,7 +158,7 @@ export class TransactionStack implements Transactor, IDisposable {
 	 * Construct a new {@link TransactionStack}.
 	 * @param onPush - A {@link OnPush | function} that will be called when a transaction begins.
 	 */
-	public constructor(onPush?: OnPush) {
+	public constructor(onPush?: OnPush<TOptions>) {
 		this.#onPush = onPush;
 	}
 
@@ -159,11 +167,11 @@ export class TransactionStack implements Transactor, IDisposable {
 		return this.#stack.length;
 	}
 
-	public start(): void {
+	public start(options?: TOptions): void {
 		this.ensureNotDisposed();
 		const last = getLast(this.#stack);
 		const onPushCurrent = last === undefined ? this.#onPush : last.callbacks.onPush;
-		const { onPush, onPop } = onPushCurrent?.() ?? {};
+		const { onPush, onPop } = onPushCurrent?.(options) ?? {};
 		this.#stack.push({
 			callbacks: { onPop, onPush: onPush ?? onPushCurrent },
 		});
@@ -216,6 +224,73 @@ export type OnPopWithViewUpdate<TChange> = (
 	viewUpdate: TChange | undefined,
 ) => void;
 
+/**
+ * Informs the caller of {@link ChangeProcessor} what context it should be invoked for.
+ * @remarks This is purely a recommendation to the caller of the processor and
+ * not a strict rule.
+ */
+export enum ChangeProcessorApplicability {
+	/**
+	 * Invoke the processor if no later (outer) instance of this change processor
+	 * may be applied to related changes before changes are "visible".
+	 *
+	 * @remarks
+	 * This designation is meant for processors that only need to be applied
+	 * once to a set of related changes independent of scope or nesting,
+	 * with the understanding that the processor should still be applied no
+	 * later than when the changes are "visible" (e.g. committed to a branch).
+	 * For example, a processor that removes extraneous information from a
+	 * change (e.g. data for nodes that were both created and removed within a
+	 * transaction) only needs to be applied once to the squashed change
+	 * produced by the outermost transaction.
+	 */
+	IfOutermost,
+	/**
+	 * Invoke the processor in all contexts.
+	 */
+	Always,
+}
+
+/**
+ * Processes a change altering its representation.
+ *
+ * @remarks
+ * A change processor receives a change and returns a change with the
+ * same observable effect but otherwise transformed.
+ *
+ * Currently this is the internal counterpart of the type-erased post-processor
+ * exposed on the public transaction API. The public boundary type-erases this
+ * (see the conversion helpers in the `shared-tree` layer) so that its internal
+ * change representation does not leak into the public API.
+ */
+export interface ChangeProcessor<TChange> {
+	/**
+	 * Informs what context it should be invoked for.
+	 */
+	readonly applicability: ChangeProcessorApplicability;
+	/**
+	 * Processes the given change, returning a change with the same observable effect.
+	 */
+	readonly processChange: (change: TChange) => TChange;
+}
+
+/**
+ * Options for {@link Transactor.start | starting} a transaction.
+ */
+export interface SquashingTransactionOptions<TChange> {
+	/**
+	 * An optional {@link ChangeProcessor} applied to the squashed change produced when a transaction that was started
+	 * with this option is committed.
+	 *
+	 * @remarks
+	 * When omitted, the transaction's edits are squashed without any post-processing.
+	 *
+	 * How often the processor is invoked across nested transactions is governed by its
+	 * {@link ChangeProcessor.applicability | applicability}.
+	 */
+	readonly postProcessor?: ChangeProcessor<TChange>;
+}
+
 /**
  * An implementation of {@link Transactor} that {@link TransactionStack | uses a stack} and a {@link SharedTreeBranch | branch} to manage transactions.
  * @remarks Given a branch, this class will fork the branch when a transaction begins and squash the forked branch back into the original branch when the transaction ends.
@@ -225,7 +300,7 @@ export type OnPopWithViewUpdate<TChange> = (
 export class SquashingTransactionStack<
 	TEditor extends ChangeFamilyEditor,
 	TChange,
-> extends TransactionStack {
+> extends TransactionStack<SquashingTransactionOptions<TChange>> {
 	#transactionBranch?: SharedTreeBranch<TEditor, TChange>;
 
 	/**
@@ -284,15 +359,41 @@ export class SquashingTransactionStack<
 	 * Construct a new {@link SquashingTransactionStack}.
 	 * @param branch - The {@link SquashingTransactionStack.branch | branch} that will be forked off of when a transaction begins.
 	 * @param onPush - A function that will be called when a transaction is pushed to the {@link TransactionStack | stack}.
+	 * @remarks To post-process the squashed change produced when a transaction is committed (for example, to "minimize"
+	 * it so that it contains no extraneous information), start the transaction with a
+	 * {@link SquashingTransactionOptions.postProcessor | post-processor}. The post-processor is injected via the transaction
+	 * options rather than baked into this stack, so different transactions may supply different post-processors (or none).
 	 */
 	public constructor(
 		public readonly branch: SharedTreeBranch<TEditor, TChange>,
 		mintRevisionTag: () => RevisionTag,
 		onPush?: () => OnPopWithViewUpdate<TChange> | void,
 	) {
+		// A stack of the post-processors to apply when each in-progress transaction commits, ordered from outermost to
+		// innermost. Each in-progress transaction contributes exactly one entry: either the processor to apply when it
+		// commits, or `undefined` when none should be applied.
+		const postProcessorStack: (ChangeProcessor<TChange> | undefined)[] = [];
+		// Determines the entry to push for a transaction that was started with the given `requested` processor (if any).
+		// A processor with "outermost" applicability that is already active in an enclosing transaction resolves to
+		// `undefined` so that it is only applied once (at the outermost transaction that supplied it).
+		const resolvePostProcessor = (
+			requested: ChangeProcessor<TChange> | undefined,
+		): ChangeProcessor<TChange> | undefined => {
+			if (
+				requested?.applicability === ChangeProcessorApplicability.IfOutermost &&
+				postProcessorStack.includes(requested)
+			) {
+				return undefined;
+			}
+			return requested;
+		};
+
 		super(
 			// Invoked when an outer transaction starts
-			(): Callbacks => {
+			(
+				startOptions?: SquashingTransactionOptions<TChange>,
+			): Callbacks<SquashingTransactionOptions<TChange>> => {
+				postProcessorStack.push(resolvePostProcessor(startOptions?.postProcessor));
 				// Keep track of the commit that each transaction was on when it started
 				const startHead = this.activeBranch.getHead();
 				const rebaser = this.branch.changeFamily.rebaser;
@@ -309,6 +410,7 @@ export class SquashingTransactionStack<
 				// Invoked when an outer transaction ends
 				const onOuterTransactionPop: OnPop = (result) => {
 					assert(this.size === 0, 0xcae /* The outer transaction should be ending */);
+					const postProcessor = postProcessorStack.pop();
 					transactionBranch.editor.exitTransaction();
 
 					const sourcePath: GraphCommit<TChange>[] = [];
@@ -357,16 +459,31 @@ export class SquashingTransactionStack<
 								}
 								// Squash all the new commits on the transaction branch into a new commit on the original branch
 								const squash = rebaser.compose(transactionSteps);
+								// Apply this transaction's post-processor (if any) to the squashed change (for example, to
+								// "minimize" it so that it contains no extraneous information).
+								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
-									this.branch.apply(tagChange(squash, transactionRevision));
+									this.branch.apply(tagChange(change, transactionRevision));
 									// 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: squash,
+										change,
 										revision: transactionRevision,
 									});
 									// We need to rebase the transaction commit on top of the new changes
@@ -407,13 +524,17 @@ export class SquashingTransactionStack<
 					outerOnPop?.(result, viewUpdate);
 				};
 				// Invoked when a nested transaction begins
-				const onNestedTransactionPush: OnPush = () => {
+				const onNestedTransactionPush: OnPush<SquashingTransactionOptions<TChange>> = (
+					nestedStartOptions,
+				) => {
+					postProcessorStack.push(resolvePostProcessor(nestedStartOptions?.postProcessor));
 					const nestedStartHead = this.activeBranch.getHead();
 					const nestedOuterOnPop = onPush?.();
 					transactionBranch.editor.enterTransaction();
 					return {
 						// Invoked when a nested transaction ends
 						onPop: (result) => {
+							const nestedPostProcessor = postProcessorStack.pop();
 							transactionBranch.editor.exitTransaction();
 							switch (result) {
 								case TransactionResult.Abort: {
@@ -422,6 +543,32 @@ export class SquashingTransactionStack<
 									break;
 								}
 								case TransactionResult.Commit: {
+									// When this nested transaction supplied a post-processor that should be applied here, squash its
+									// edits into a single (post-processed) commit on the transaction branch rather than leaving them to
+									// be squashed only when the outermost transaction is committed.
+									if (nestedPostProcessor !== undefined) {
+										const nestedSteps: GraphCommit<TChange>[] = [];
+										findAncestor(
+											[transactionBranch.getHead(), nestedSteps],
+											(c) => c === nestedStartHead,
+										);
+										if (nestedSteps.length > 0) {
+											assert(
+												transactionRevision !== undefined,
+												0xd07 /* Expected transaction revision in the presence of transaction steps */,
+											);
+											const squash = rebaser.compose(nestedSteps);
+											const processedSquash = nestedPostProcessor.processChange(squash);
+											// 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;
 								}
 								default: {

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,
@@ -179,19 +179,23 @@ export {
 } from "./storedSchema.js";
 
 export {
+	type NoChangeConstraint,
+	type NodeInDocumentConstraint,
+	rollback,
+	type RunTransactionParamsAlpha,
+	type RunTransactionParamsBeta,
+	type TransactionCallbackStatusAlpha,
+	type TransactionCallbackStatusBeta,
 	type TransactionConstraint,
 	type TransactionConstraintAlpha,
-	type NodeInDocumentConstraint,
-	type NoChangeConstraint,
-	type RunTransactionParams,
-	type VoidTransactionCallbackStatus,
-	type TransactionCallbackStatus,
-	type TransactionResult,
-	type TransactionResultExt,
-	type TransactionResultSuccess,
+	type TransactionPostProcessor,
 	type TransactionResultFailed,
+	type TransactionResultSuccess,
+	type TransactionValueResult,
+	type TransactionVoidResult,
+	type VoidTransactionCallbackStatusAlpha,
+	type VoidTransactionCallbackStatusBeta,
 	type WithValue,
-	rollback,
 } from "./transactionTypes.js";
 
 export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";

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/schemaCreationUtilities.ts

@@ -78,7 +78,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 }
 
 /**
- * Converts an enum into a collection of schema which can be used in a union.
+ * Converts an enum into a collection of schemas which can be used in a union.
  *
  * @typeParam TScope - The scope of the provided factory.
  * There is a known issue where if a factory is provided that is typed as a {@link SchemaFactoryAlpha}, and its scope contains a "." character,
@@ -88,7 +88,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * @remarks
  * The string value of the enum is used as the name of the schema: callers must ensure that it is stable and unique.
  * Numeric enums values have the value implicitly converted into a string.
- * Consider making a dedicated schema factory with a nested scope (for example using {@link SchemaFactoryBeta.scopedFactory}) to avoid the enum members colliding with other schema.
+ * Consider making a dedicated schema factory with a nested scope (for example using {@link SchemaFactoryBeta.scopedFactory}) to avoid the enum members colliding with other schemas.
  * @example
  * ```typescript
  * const schemaFactory = new SchemaFactory("com.myApp");
@@ -213,7 +213,7 @@ export function enumEntries(
 }
 
 /**
- * Converts an array of distinct strings into a collection of schema which can be used like an enum style union.
+ * Converts an array of distinct strings into a collection of schemas which can be used like an enum style union.
  * @remarks
  * The returned collection is also a function which can be used to convert strings into {@link Unhydrated} nodes in the union.
  * Each node type has a `.value` getter which returns the associated string.

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

@@ -339,7 +339,7 @@ export class SchemaFactory<
 	/**
 	 * Construct a SchemaFactory with a given {@link SchemaFactory.scope|scope}.
 	 * @remarks
-	 * There are no restrictions on mixing schema from different schema factories.
+	 * There are no restrictions on mixing schemas from different schema factories.
 	 * Typically each library will create one or more SchemaFactories and use them to define its schema.
 	 */
 	public constructor(
@@ -698,7 +698,7 @@ export class SchemaFactory<
 		const same = compareSets({ a: inputTypes, b: outputTypes });
 		if (!same) {
 			throw new UsageError(
-				`Structurally named schema collision: two schema named "${fullName}" were defined with different input schema.`,
+				`Structurally named schema collision: two schemas named "${fullName}" were defined with different input schemas.`,
 			);
 		}
 		return structural;

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);
 }
 
 /**
@@ -422,11 +421,11 @@ export interface SnapshotSchemaCompatibilityOptions {
  * Libraries which export schema for use by others will need to take special care to ensure the stability contract they offer their users aligns which what is validated by this utility.
  *
  * This utility only tests compatibility of the historical snapshots against the current schema; it does not test them against each-other.
- * Generally any historical schema should have been tested against the ones before them at the time they were current.
+ * Generally any historical schemas should have been tested against the ones before them at the time they were current.
  * If for some reason a version of a schema made it into production that was not compatible with a previous version,
  * that can still be represented here (but may require manually generating a snapshot for that version)
  * and this will still allow testing that all historical version can be upgraded to the current one.
- * If a sufficiently incompatible historical schema were used in production, it may be impossible to make a single schema which can accommodate all of them:
+ * If a sufficiently incompatible historical schemas were used in production, it may be impossible to make a single schema which can accommodate all of them:
  * this utility can be used to confirm that is the case, as well as to avoid the problem in the first place by testing schema before each one is deployed.
  *
  * @example Mocha test which validates the current `config` can collaborate with all historical version back to 2.0.0, and load and update any versions older than that.