@fluidframework/tree 2.12.0 → 2.20.0

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

@@ -40,6 +40,7 @@ import {
 	createFieldSchema,
 	type DefaultProvider,
 	getDefaultProvider,
+	type NodeSchemaOptions,
 } from "../schemaTypes.js";
 import { inPrototypeChain } from "../core/index.js";
 import type {
@@ -103,11 +104,15 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
 
 /**
  * Options when declaring an {@link SchemaFactory.object|object node}'s schema
+ *
+ * @alpha
  */
-export interface SchemaFactoryObjectOptions {
+export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown>
+	extends NodeSchemaOptions<TCustomMetadata> {
 	/**
-	 * Opt in to viewing documents which have unknown optional fields for this object's identifier, i.e. optional fields
-	 * in the document schema which are not present in this object schema declaration.
+	 * Allow nodes typed with this object node schema to contain optional fields that are not present in the schema declaration.
+	 * Such nodes can come into existence either via import APIs (see remarks) or by way of collaboration with another client
+	 * that has upgraded the document's schema to include those optional fields.
 	 *
 	 * @defaultValue `false`
 	 * @remarks
@@ -149,7 +154,9 @@ export interface SchemaFactoryObjectOptions {
 	allowUnknownOptionalFields?: boolean;
 }
 
-export const defaultSchemaFactoryObjectOptions: Required<SchemaFactoryObjectOptions> = {
+export const defaultSchemaFactoryObjectOptions: Required<
+	Omit<SchemaFactoryObjectOptions, "metadata">
+> = {
 	allowUnknownOptionalFields: false,
 };
 
@@ -400,6 +407,8 @@ export class SchemaFactory<
 	/**
 	 * Define a structurally typed {@link TreeNodeSchema} for a {@link TreeMapNode}.
 	 *
+	 * @param allowedTypes - The types that may appear as values in the map.
+	 *
 	 * @remarks
 	 * The unique identifier for this Map is defined as a function of the provided types.
 	 * It is still scoped to this SchemaBuilder, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.
@@ -436,6 +445,7 @@ export class SchemaFactory<
 	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
+	 * @param allowedTypes - The types that may appear as values in the map.
 	 *
 	 * @example
 	 * ```typescript
@@ -456,6 +466,8 @@ export class SchemaFactory<
 	>;
 
 	/**
+	 * {@link SchemaFactory.map} implementation.
+	 *
 	 * @privateRemarks
 	 * This should return `TreeNodeSchemaBoth`, however TypeScript gives an error if one of the overloads implicitly up-casts the return type of the implementation.
 	 * This seems like a TypeScript bug getting variance backwards for overload return types since it's erroring when the relation between the overload
@@ -530,12 +542,15 @@ export class SchemaFactory<
 			implicitlyConstructable,
 			// The current policy is customizable nodes don't get fake prototypes.
 			!customizable,
+			undefined,
 		);
 	}
 
 	/**
 	 * Define a structurally typed {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.
 	 *
+	 * @param allowedTypes - The types that may appear in the array.
+	 *
 	 * @remarks
 	 * The identifier for this Array is defined as a function of the provided types.
 	 * It is still scoped to this SchemaFactory, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.
@@ -582,6 +597,7 @@ export class SchemaFactory<
 	 * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
+	 * @param allowedTypes - The types that may appear in the array.
 	 *
 	 * @example
 	 * ```typescript
@@ -604,6 +620,8 @@ export class SchemaFactory<
 	>;
 
 	/**
+	 * {@link SchemaFactory.array} implementation.
+	 *
 	 * @privateRemarks
 	 * This should return TreeNodeSchemaBoth: see note on "map" implementation for details.
 	 */
@@ -787,11 +805,20 @@ export class SchemaFactory<
 	 * `error TS2589: Type instantiation is excessively deep and possibly infinite.`
 	 * which otherwise gets reported at sometimes incorrect source locations that vary based on incremental builds.
 	 */
-	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	public objectRecursive<
 		const Name extends TName,
 		const T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>,
-	>(name: Name, t: T) {
+	>(
+		name: Name,
+		t: T,
+	): TreeNodeSchemaClass<
+		ScopedSchemaName<TScope, Name>,
+		NodeKind.Object,
+		TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,
+		object & InsertableObjectFromSchemaRecordUnsafe<T>,
+		false,
+		T
+	> {
 		type TScopedName = ScopedSchemaName<TScope, Name>;
 		return this.object(
 			name,

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

@@ -0,0 +1,253 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	ScopedSchemaName,
+	InsertableObjectFromSchemaRecord,
+	TreeObjectNodeUnsafe,
+	InsertableObjectFromSchemaRecordUnsafe,
+} from "../../internalTypes.js";
+import {
+	defaultSchemaFactoryObjectOptions,
+	SchemaFactory,
+	type SchemaFactoryObjectOptions,
+} from "./schemaFactory.js";
+import type {
+	ImplicitAllowedTypes,
+	ImplicitFieldSchema,
+	InsertableTreeNodeFromImplicitAllowedTypes,
+	NodeSchemaOptions,
+} from "../schemaTypes.js";
+import { type TreeObjectNode, objectSchema } from "../objectNode.js";
+import type { RestrictiveStringRecord } from "../../util/index.js";
+import type { NodeKind, TreeNodeSchemaClass, WithType } from "../core/index.js";
+import type {
+	InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
+	TreeArrayNodeUnsafe,
+	TreeMapNodeUnsafe,
+	Unenforced,
+} from "./typesUnsafe.js";
+import { mapSchema, type MapNodeInsertableData, type TreeMapNode } from "../mapNode.js";
+import { arraySchema, type TreeArrayNode } from "../arrayNode.js";
+
+/**
+ * {@link SchemaFactory} with additional alpha APIs.
+ *
+ * @alpha
+ * @privateRemarks
+ *
+ * Some private methods on `SchemaFactory` are intentionally duplicated here to avoid increasing their exposure to `protected`.
+ * If we were to do so, they would be exposed on the public API surface of `SchemaFactory`.
+ */
+export class SchemaFactoryAlpha<
+	out TScope extends string | undefined = string | undefined,
+	TName extends number | string = string,
+> extends SchemaFactory<TScope, TName> {
+	private scoped2<Name extends TName | string>(name: Name): ScopedSchemaName<TScope, Name> {
+		return (
+			this.scope === undefined ? `${name}` : `${this.scope}.${name}`
+		) as ScopedSchemaName<TScope, Name>;
+	}
+
+	/**
+	 * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.
+	 *
+	 * @param name - Unique identifier for this schema within this factory's scope.
+	 * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
+	 * @param options - Additional options for the schema.
+	 */
+	public override object<
+		const Name extends TName,
+		const T extends RestrictiveStringRecord<ImplicitFieldSchema>,
+		const TCustomMetadata = unknown,
+	>(
+		name: Name,
+		fields: T,
+		options?: SchemaFactoryObjectOptions<TCustomMetadata>,
+	): TreeNodeSchemaClass<
+		ScopedSchemaName<TScope, Name>,
+		NodeKind.Object,
+		TreeObjectNode<T, ScopedSchemaName<TScope, Name>>,
+		object & InsertableObjectFromSchemaRecord<T>,
+		true,
+		T,
+		never,
+		TCustomMetadata
+	> {
+		return objectSchema(
+			this.scoped2(name),
+			fields,
+			true,
+			options?.allowUnknownOptionalFields ??
+				defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
+			options?.metadata,
+		);
+	}
+
+	/**
+	 * {@inheritdoc SchemaFactory.objectRecursive}
+	 */
+	public override objectRecursive<
+		const Name extends TName,
+		const T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>,
+		const TCustomMetadata = unknown,
+	>(
+		name: Name,
+		t: T,
+		options?: SchemaFactoryObjectOptions<TCustomMetadata>,
+	): TreeNodeSchemaClass<
+		ScopedSchemaName<TScope, Name>,
+		NodeKind.Object,
+		TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,
+		object & InsertableObjectFromSchemaRecordUnsafe<T>,
+		false,
+		T,
+		never,
+		TCustomMetadata
+	> {
+		type TScopedName = ScopedSchemaName<TScope, Name>;
+		return this.object(
+			name,
+			t as T & RestrictiveStringRecord<ImplicitFieldSchema>,
+			options,
+		) as unknown as TreeNodeSchemaClass<
+			TScopedName,
+			NodeKind.Object,
+			TreeObjectNodeUnsafe<T, TScopedName>,
+			object & InsertableObjectFromSchemaRecordUnsafe<T>,
+			false,
+			T,
+			never,
+			TCustomMetadata
+		>;
+	}
+
+	/**
+	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
+	 *
+	 * @param name - Unique identifier for this schema within this factory's scope.
+	 * @param allowedTypes - The types that may appear as values in the map.
+	 * @param options - Additional options for the schema.
+	 *
+	 * @example
+	 * ```typescript
+	 * class NamedMap extends factory.map("name", factory.number, {
+	 * 	metadata: { description: "A map of numbers" }
+	 * }) {}
+	 * ```
+	 */
+	public mapAlpha<
+		Name extends TName,
+		const T extends ImplicitAllowedTypes,
+		const TCustomMetadata = unknown,
+	>(
+		name: Name,
+		allowedTypes: T,
+		options?: NodeSchemaOptions<TCustomMetadata>,
+	): TreeNodeSchemaClass<
+		ScopedSchemaName<TScope, Name>,
+		NodeKind.Map,
+		TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
+		MapNodeInsertableData<T>,
+		true,
+		T,
+		undefined,
+		TCustomMetadata
+	> {
+		return mapSchema(this.scoped2(name), allowedTypes, true, true, options?.metadata);
+	}
+
+	/**
+	 * {@inheritDoc SchemaFactory.objectRecursive}
+	 */
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+	public override mapRecursive<
+		Name extends TName,
+		const T extends Unenforced<ImplicitAllowedTypes>,
+		const TCustomMetadata = unknown,
+	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
+		return this.mapAlpha(
+			name,
+			allowedTypes as T & ImplicitAllowedTypes,
+			options,
+		) as unknown as TreeNodeSchemaClass<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Map,
+			TreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
+			| {
+					[Symbol.iterator](): Iterator<
+						[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
+					>;
+			  }
+			| {
+					readonly [P in string]: InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
+			  },
+			false,
+			T,
+			undefined,
+			TCustomMetadata
+		>;
+	}
+
+	/**
+	 * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.
+	 *
+	 * @param name - Unique identifier for this schema within this factory's scope.
+	 * @param allowedTypes - The types that may appear in the array.
+	 * @param options - Additional options for the schema.
+	 *
+	 * @example
+	 * ```typescript
+	 * class NamedArray extends factory.array("name", factory.number) {}
+	 * ```
+	 */
+	public arrayAlpha<
+		const Name extends TName,
+		const T extends ImplicitAllowedTypes,
+		const TCustomMetadata = unknown,
+	>(
+		name: Name,
+		allowedTypes: T,
+		options?: NodeSchemaOptions<TCustomMetadata>,
+	): TreeNodeSchemaClass<
+		ScopedSchemaName<TScope, Name>,
+		NodeKind.Array,
+		TreeArrayNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,
+		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
+		true,
+		T,
+		undefined,
+		TCustomMetadata
+	> {
+		return arraySchema(this.scoped2(name), allowedTypes, true, true, options?.metadata);
+	}
+
+	/**
+	 * {@inheritDoc SchemaFactory.objectRecursive}
+	 */
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+	public override arrayRecursive<
+		const Name extends TName,
+		const T extends Unenforced<ImplicitAllowedTypes>,
+		const TCustomMetadata = unknown,
+	>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>) {
+		return this.arrayAlpha(
+			name,
+			allowedTypes as T & ImplicitAllowedTypes,
+			options,
+		) as unknown as TreeNodeSchemaClass<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Array,
+			TreeArrayNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,
+			{
+				[Symbol.iterator](): Iterator<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>;
+			},
+			false,
+			T,
+			undefined,
+			TCustomMetadata
+		>;
+	}
+}

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

@@ -5,7 +5,7 @@
 
 import type { ValueSchema } from "../../core/index.js";
 import type { NodeKind } from "../core/index.js";
-import type { FieldKind, FieldSchemaMetadata } from "../schemaTypes.js";
+import type { FieldKind, FieldSchemaMetadata, NodeSchemaMetadata } from "../schemaTypes.js";
 
 /**
  * Base interface for all {@link SimpleNodeSchema} implementations.
@@ -20,6 +20,11 @@ export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
 	 * @remarks can be used to type-switch between implementations.
 	 */
 	readonly kind: TNodeKind;
+
+	/**
+	 * {@inheritDoc NodeSchemaMetadata}
+	 */
+	readonly metadata?: NodeSchemaMetadata | undefined;
 }
 
 /**

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

@@ -6,7 +6,7 @@
 import { unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { ValueSchema } from "../../core/index.js";
-import { getOrCreate, hasSingle, type Mutable } from "../../util/index.js";
+import { copyProperty, getOrCreate, hasSingle, type Mutable } from "../../util/index.js";
 import type {
 	JsonArrayNodeSchema,
 	JsonFieldSchema,
@@ -100,11 +100,15 @@ function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSch
 		? allowedTypes[0]
 		: { anyOf: allowedTypes };
 
-	return {
+	const output: Mutable<JsonArrayNodeSchema> = {
 		type: "array",
 		_treeNodeSchemaKind: NodeKind.Array,
 		items,
 	};
+
+	copyProperty(schema.metadata, "description", output);
+
+	return output;
 }
 
 function convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema {
@@ -137,9 +141,9 @@ function convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema
 function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {
 	const properties: Record<string, JsonFieldSchema> = {};
 	const required: string[] = [];
-	for (const [key, value] of Object.entries(schema.fields)) {
+	for (const [key, fieldSchema] of Object.entries(schema.fields)) {
 		const allowedTypes: JsonSchemaRef[] = [];
-		for (const allowedType of value.allowedTypes) {
+		for (const allowedType of fieldSchema.allowedTypes) {
 			allowedTypes.push(createSchemaRef(allowedType));
 		}
 
@@ -149,24 +153,25 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 					anyOf: allowedTypes,
 				};
 
-		// Don't include "description" property at all if it's not present in the input.
-		if (value.metadata?.description !== undefined) {
-			output.description = value.metadata.description;
-		}
-
+		copyProperty(fieldSchema.metadata, "description", output);
 		properties[key] = output;
 
-		if (value.kind === FieldKind.Required) {
+		if (fieldSchema.kind === FieldKind.Required) {
 			required.push(key);
 		}
 	}
-	return {
+
+	const transformedNode: Mutable<JsonObjectNodeSchema> = {
 		type: "object",
 		_treeNodeSchemaKind: NodeKind.Object,
 		properties,
 		required,
 		additionalProperties: false,
 	};
+
+	copyProperty(schema.metadata, "description", transformedNode);
+
+	return transformedNode;
 }
 
 function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
@@ -174,7 +179,8 @@ function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 	schema.allowedTypes.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
-	return {
+
+	const output: Mutable<JsonMapNodeSchema> = {
 		type: "object",
 		_treeNodeSchemaKind: NodeKind.Map,
 		patternProperties: {
@@ -185,6 +191,10 @@ function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 					},
 		},
 	};
+
+	copyProperty(schema.metadata, "description", output);
+
+	return output;
 }
 
 function createSchemaRef(schemaId: string): JsonSchemaRef {

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

@@ -12,9 +12,16 @@ import type {
 	RevertibleFactory,
 } from "../../core/index.js";
 
-// This is referenced by doc comments.
-// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
-import type { TreeAlpha } from "../../shared-tree/index.js";
+import type {
+	RunTransactionParams,
+	VoidTransactionCallbackStatus,
+	TransactionCallbackStatus,
+	TransactionResult,
+	TransactionResultExt,
+	// This is referenced by doc comments.
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
+	TreeAlpha,
+} from "../../shared-tree/index.js";
 
 import {
 	type ImplicitFieldSchema,
@@ -35,7 +42,6 @@ import { markSchemaMostDerived } from "./schemaFactory.js";
 import { fail, getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
-
 /**
  * A tree from which a {@link TreeView} can be created.
  *
@@ -542,6 +548,72 @@ export interface TreeViewAlpha<
 
 	// Override the base branch method to return a typed view rather than merely a branch.
 	fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;
+
+	/**
+	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
+	 * @param transaction - The function to run as the body of the transaction.
+	 * It should return a status object of {@link TransactionCallbackStatus | TransactionCallbackStatus } type.
+	 * It includes a "rollback" property which may be returned as true at any point during the transaction. This will
+	 * abort the transaction and discard any changes it made so far.
+	 * "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
+	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
+	 * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:
+	 * - A "success" flag indicating whether the transaction was successful or not.
+	 * - The success of failure value as returned by the transaction function.
+	 * @remarks
+	 * This API will throw an error if the constraints are not met or something unexpected happens.
+	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
+	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
+	 * However, using a transaction has the following additional consequences:
+	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
+	 *
+	 * Local change events will be emitted for each change as the transaction is being applied.
+	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
+	 *
+	 * Nested transactions:
+	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
+	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
+	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
+	 * for the outermost transaction which includes all inner transactions.
+	 * - Undo will undo the outermost transaction and all inner transactions.
+	 */
+	runTransaction<TSuccessValue, TFailureValue>(
+		transaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,
+		params?: RunTransactionParams,
+	): TransactionResultExt<TSuccessValue, TFailureValue>;
+	/**
+	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
+	 * @param transaction - The function to run as the body of the transaction. It may return the following:
+	 * - Nothing to indicate that the body of the transaction has successfully run.
+	 * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a "rollback" property which
+	 * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so
+	 * far. "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
+	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
+	 * @returns A result object of {@link TransactionResult | TransactionResult} type. It includes a "success" flag indicating whether the
+	 * transaction was successful or not.
+	 * @remarks
+	 * This API will throw an error if the constraints are not met or something unexpected happens.
+	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
+	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
+	 * However, using a transaction has the following additional consequences:
+	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
+	 *
+	 * Local change events will be emitted for each change as the transaction is being applied.
+	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
+	 *
+	 * Nested transactions:
+	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
+	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
+	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
+	 * for the outermost transaction which includes all inner transactions.
+	 * - Undo will undo the outermost transaction and all inner transactions.
+	 */
+	runTransaction(
+		transaction: () => VoidTransactionCallbackStatus | void,
+		params?: RunTransactionParams,
+	): TransactionResult;
 }
 
 /**

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

@@ -174,7 +174,7 @@ export const treeNodeApi: TreeNodeApi = {
 								changedFields,
 								(field) =>
 									nodeSchema.storedKeyToPropertyKey.get(field) ??
-									fail(`Could not find stored key '${field}' in schema.`),
+									fail("Could not find stored key in schema."),
 							),
 						);
 						listener({ changedProperties });

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

@@ -20,7 +20,7 @@ import type {
 	SimpleTreeSchema,
 } from "./simpleSchema.js";
 import type { ValueSchema } from "../../core/index.js";
-import { getOrCreate, type Mutable } from "../../util/index.js";
+import { copyProperty, getOrCreate, type Mutable } from "../../util/index.js";
 import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 
@@ -41,11 +41,7 @@ export function toSimpleTreeSchema(schema: ImplicitFieldSchema): SimpleTreeSchem
 		definitions,
 	};
 
-	// Include the "description" property only if it's present on the input.
-	if (normalizedSchema.metadata !== undefined) {
-		output.metadata = normalizedSchema.metadata;
-	}
-
+	copyProperty(normalizedSchema, "metadata", output);
 	return output;
 }
 
@@ -95,20 +91,28 @@ function leafSchemaToSimpleSchema(schema: TreeNodeSchema): SimpleLeafNodeSchema
 function arraySchemaToSimpleSchema(schema: TreeNodeSchema): SimpleArrayNodeSchema {
 	const fieldSchema = normalizeFieldSchema(schema.info as ImplicitAllowedTypes);
 	const allowedTypes = allowedTypesFromFieldSchema(fieldSchema);
-	return {
+	const output: Mutable<SimpleArrayNodeSchema> = {
 		kind: NodeKind.Array,
 		allowedTypes,
 	};
+
+	copyProperty(schema, "metadata", output);
+
+	return output;
 }
 
 // TODO: Use a stronger type for map schemas once one is available (see object schema handler for an example).
 function mapSchemaToSimpleSchema(schema: TreeNodeSchema): SimpleMapNodeSchema {
 	const fieldSchema = normalizeFieldSchema(schema.info as ImplicitAllowedTypes);
 	const allowedTypes = allowedTypesFromFieldSchema(fieldSchema);
-	return {
+	const output: Mutable<SimpleMapNodeSchema> = {
 		kind: NodeKind.Map,
 		allowedTypes,
 	};
+
+	copyProperty(schema, "metadata", output);
+
+	return output;
 }
 
 function objectSchemaToSimpleSchema(schema: ObjectNodeSchema): SimpleObjectNodeSchema {
@@ -116,10 +120,15 @@ function objectSchemaToSimpleSchema(schema: ObjectNodeSchema): SimpleObjectNodeS
 	for (const [key, field] of schema.fields) {
 		fields[key] = fieldSchemaToSimpleSchema(field);
 	}
-	return {
+
+	const output: Mutable<SimpleObjectNodeSchema> = {
 		kind: NodeKind.Object,
 		fields,
 	};
+
+	copyProperty(schema, "metadata", output);
+
+	return output;
 }
 
 /**
@@ -140,10 +149,7 @@ function fieldSchemaToSimpleSchema(schema: FieldSchema): SimpleFieldSchema {
 		allowedTypes,
 	};
 
-	// Don't include "metadata" property at all if it's not present.
-	if (schema.metadata !== undefined) {
-		result.metadata = schema.metadata;
-	}
+	copyProperty(schema, "metadata", result);
 
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	(schema as any)[simpleFieldSchemaCacheSymbol] = result;