@fluidframework/tree 2.11.0 → 2.13.0

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

@@ -200,6 +200,8 @@ export function createSimpleTreeIndex<
 				return treeNodeApi.status(simpleTree);
 			}
 		},
+		// simple tree indexes are shallow indexes, indicating so allows for a performance optimization
+		true,
 	);
 
 	// all the type checking guarantees that we put nodes of the correct type in the index

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

@@ -4,7 +4,7 @@
  */
 
 import type { ICodecOptions } from "../../codec/index.js";
-import { Compatibility, type TreeStoredSchema } from "../../core/index.js";
+import type { TreeStoredSchema } from "../../core/index.js";
 import {
 	defaultSchemaPolicy,
 	encodeTreeSchema,
@@ -59,7 +59,7 @@ export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompati
  * opening a document that used the `persisted` schema and provided `view` to {@link ViewableTree.viewWith}.
  *
  * @param persisted - Schema persisted for a document. Typically persisted alongside the data and assumed to describe that data.
- * @param view - Schema which would be used to view persisted content. Use {@link extractPersistedSchema} to convert the view schema into this format.
+ * @param view - Schema which would be used to view persisted content.
  * @param options - {@link ICodecOptions} used when parsing the provided schema.
  * @param canInitialize - Passed through to the return value unchanged and otherwise unused.
  * @returns The {@link SchemaCompatibilityStatus} a {@link TreeView} would report for this combination of schema.
@@ -75,7 +75,7 @@ export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompati
  * assert(
  * 	comparePersistedSchema(
  * 		require("./schema.json"),
- * 		extractPersistedSchema(MySchema),
+ * 		MySchema,
  * 		{ jsonValidator: typeboxValidator },
  * 		false,
  * 	).canUpgrade,
@@ -85,14 +85,13 @@ export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompati
  */
 export function comparePersistedSchema(
 	persisted: JsonCompatible,
-	view: JsonCompatible,
+	view: ImplicitFieldSchema,
 	options: ICodecOptions,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
 	const schemaCodec = makeSchemaCodec(options);
 	const stored = schemaCodec.decode(persisted as Format);
-	const viewParsed = schemaCodec.decode(view as Format);
-	const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, viewParsed);
+	const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, view);
 	return comparePersistedSchemaInternal(stored, viewSchema, canInitialize);
 }
 
@@ -105,22 +104,8 @@ export function comparePersistedSchemaInternal(
 	viewSchema: ViewSchema,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
-	const result = viewSchema.checkCompatibility(stored);
-
-	// TODO: AB#8121: Weaken this check to support viewing under additional circumstances.
-	// In the near term, this should support viewing documents with additional optional fields in their schema on object types.
-	// Longer-term (as demand arises), we could also add APIs to constructing view schema to allow for more flexibility
-	// (e.g. out-of-schema content handlers could allow support for viewing docs which have extra allowed types in a particular field)
-	const canView =
-		result.write === Compatibility.Compatible && result.read === Compatibility.Compatible;
-	const canUpgrade = result.read === Compatibility.Compatible;
-	const isEquivalent = canView && canUpgrade;
-	const compatibility: SchemaCompatibilityStatus = {
-		canView,
-		canUpgrade,
-		isEquivalent,
+	return {
+		...viewSchema.checkCompatibility(stored),
 		canInitialize,
 	};
-
-	return compatibility;
 }

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

@@ -12,6 +12,17 @@ import type {
 	RevertibleFactory,
 } from "../../core/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,
 	type InsertableField,
@@ -41,6 +52,7 @@ import { walkFieldSchema } from "../walkFieldSchema.js";
  * Maybe rename "exportJsonSchema" to align on "concise" terminology.
  * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).
  * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).
+ * Some of these APIs are on ISharedTree and can get moved here.
  * @system @sealed @public
  */
 export interface ViewableTree {
@@ -536,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/verboseTree.ts

@@ -38,7 +38,7 @@ import {
 } from "../leafNodeSchema.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
 import {
-	customFromCursorInner,
+	customFromCursor,
 	type CustomTreeNode,
 	type CustomTreeValue,
 	type EncodeOptions,
@@ -344,7 +344,7 @@ function verboseFromCursorInner<TCustom>(
 	options: Required<EncodeOptions<TCustom>>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): VerboseTree<TCustom> {
-	const fields = customFromCursorInner(reader, options, schema, verboseFromCursorInner);
+	const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);
 	const nodeSchema = schema.get(reader.type) ?? fail("missing schema for type in cursor");
 	if (nodeSchema.kind === NodeKind.Leaf) {
 		return fields as CustomTreeValue<TCustom>;

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

@@ -5,32 +5,56 @@
 
 import {
 	AdaptedViewSchema,
+	type TreeNodeStoredSchema,
 	type Adapters,
-	Compatibility,
 	type TreeFieldStoredSchema,
 	type TreeNodeSchemaIdentifier,
-	type TreeNodeStoredSchema,
 	type TreeStoredSchema,
 } from "../../core/index.js";
 import { fail } from "../../util/index.js";
 import {
+	FieldKinds,
 	type FullSchemaPolicy,
-	allowsRepoSuperset,
+	type FieldDiscrepancy,
+	getAllowedContentDiscrepancies,
 	isNeverTree,
+	PosetComparisonResult,
+	fieldRealizer,
+	comparePosetElements,
 } from "../../feature-libraries/index.js";
+import {
+	normalizeFieldSchema,
+	type FieldSchema,
+	type ImplicitFieldSchema,
+} from "../schemaTypes.js";
+import { toStoredSchema } from "../toStoredSchema.js";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
+import type { SchemaCompatibilityStatus } from "./tree.js";
 
 /**
  * A collection of View information for schema, including policy.
  */
 export class ViewSchema {
 	/**
-	 * @param schema - Cached conversion of view schema in the stored schema format.
+	 * Cached conversion of the view schema in the stored schema format.
+	 */
+	private readonly viewSchemaAsStored: TreeStoredSchema;
+	/**
+	 * Normalized view schema (implicitly allowed view schema types are converted to their canonical form).
+	 */
+	public readonly schema: FieldSchema;
+
+	/**
+	 * @param viewSchema - Schema for the root field of this view.
 	 */
 	public constructor(
 		public readonly policy: FullSchemaPolicy,
 		public readonly adapters: Adapters,
-		public readonly schema: TreeStoredSchema,
-	) {}
+		viewSchema: ImplicitFieldSchema,
+	) {
+		this.schema = normalizeFieldSchema(viewSchema);
+		this.viewSchemaAsStored = toStoredSchema(this.schema);
+	}
 
 	/**
 	 * Determines the compatibility of a stored document
@@ -42,53 +66,168 @@ export class ViewSchema {
 	 * 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): {
-		read: Compatibility;
-		write: Compatibility;
-		writeAllowingStoredSchemaUpdates: Compatibility;
-	} {
+	public checkCompatibility(
+		stored: TreeStoredSchema,
+	): Omit<SchemaCompatibilityStatus, "canInitialize"> {
 		// TODO: support adapters
 		// const adapted = this.adaptRepo(stored);
 
-		const read = allowsRepoSuperset(this.policy, stored, this.schema)
-			? Compatibility.Compatible
-			: // TODO: support adapters
-				// : allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
-				// ? Compatibility.RequiresAdapters
-				Compatibility.Incompatible;
-		// TODO: Extract subset of adapters that are valid to use on stored
-		// TODO: separate adapters from schema updates
-		const write = allowsRepoSuperset(this.policy, this.schema, stored)
-			? Compatibility.Compatible
-			: // TODO: support adapters
-				// : allowsRepoSuperset(this.policy, this.storedSchema, adapted.adaptedForViewSchema)
-				// TODO: IThis assumes adapters are bidirectional.
-				//   Compatibility.RequiresAdapters
-				Compatibility.Incompatible;
-
-		// TODO: compute this properly (and maybe include the set of schema changes needed for it?).
-		// Maybe updates would happen lazily when needed to store data?
-		// When willingness to updates can avoid need for some adapters,
-		// how should it be decided if the adapter should be used to avoid the update?
-		// TODO: is this case actually bi-variant, making this correct if we did it for each schema independently?
-		let writeAllowingStoredSchemaUpdates =
-			// TODO: This should consider just the updates needed
-			// (ex: when view covers a subset of stored after stored has a update to that subset).
-			allowsRepoSuperset(this.policy, stored, this.schema)
-				? Compatibility.Compatible
-				: // TODO: this assumes adapters can translate in both directions. In general this will not be true.
-					// TODO: this also assumes that schema updates to the adapted repo would translate to
-					// updates on the stored schema, which is also likely untrue.
-					// // TODO: support adapters
-					// allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
-					// ? Compatibility.RequiresAdapters // Requires schema updates. TODO: consider adapters that can update writes.
-					Compatibility.Incompatible;
-
-		// Since the above does not consider partial updates,
-		// we can improve the tolerance a bit by considering the op-op update:
-		writeAllowingStoredSchemaUpdates = Math.max(writeAllowingStoredSchemaUpdates, write);
-
-		return { read, write, writeAllowingStoredSchemaUpdates };
+		// 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;
+		// View schema allows a superset of documents that stored schema does, hence the document could be upgraded to use a persisted version
+		// of this view schema as its stored schema.
+		let canUpgrade = true;
+
+		const updateCompatibilityFromFieldDiscrepancy = (discrepancy: FieldDiscrepancy): void => {
+			switch (discrepancy.mismatch) {
+				case "allowedTypes": {
+					// Since we only track the symmetric difference between the allowed types in the view and
+					// stored schemas, it's sufficient to check if any extra allowed types still exist in the
+					// stored schema.
+					if (
+						discrepancy.stored.some(
+							(identifier) =>
+								!isNeverTree(this.policy, stored, stored.nodeSchema.get(identifier)),
+						)
+					) {
+						// Stored schema has extra allowed types that the view schema does not.
+						canUpgrade = false;
+						canView = false;
+					}
+
+					if (
+						discrepancy.view.some(
+							(identifier) =>
+								!isNeverTree(
+									this.policy,
+									this.viewSchemaAsStored,
+									this.viewSchemaAsStored.nodeSchema.get(identifier),
+								),
+						)
+					) {
+						// View schema has extra allowed types that the stored schema does not.
+						canView = false;
+					}
+					break;
+				}
+				case "fieldKind": {
+					const result = comparePosetElements(
+						discrepancy.stored,
+						discrepancy.view,
+						fieldRealizer,
+					);
+
+					if (result === PosetComparisonResult.Greater) {
+						// Stored schema is more relaxed than view schema.
+						canUpgrade = false;
+						if (
+							discrepancy.view === FieldKinds.forbidden.identifier &&
+							discrepancy.identifier !== undefined &&
+							this.policy.allowUnknownOptionalFields(discrepancy.identifier)
+						) {
+							// When the application has opted into it, we allow viewing documents which have additional
+							// optional fields in the stored schema that are not present in the view schema.
+						} else {
+							canView = false;
+						}
+					}
+
+					if (result === PosetComparisonResult.Less) {
+						// View schema is more relaxed than stored schema.
+						canView = false;
+					}
+
+					if (result === PosetComparisonResult.Incomparable) {
+						canUpgrade = false;
+						canView = false;
+					}
+
+					break;
+				}
+				case "valueSchema": {
+					canView = false;
+					canUpgrade = false;
+					break;
+				}
+				default:
+					unreachableCase(discrepancy);
+			}
+		};
+
+		for (const discrepancy of getAllowedContentDiscrepancies(
+			this.viewSchemaAsStored,
+			stored,
+		)) {
+			if (!canView && !canUpgrade) {
+				break;
+			}
+
+			switch (discrepancy.mismatch) {
+				case "nodeKind": {
+					const viewNodeSchema = this.viewSchemaAsStored.nodeSchema.get(
+						discrepancy.identifier,
+					);
+					const storedNodeSchema = stored.nodeSchema.get(discrepancy.identifier);
+					// We conservatively do not allow node types to change.
+					// The only time this might be valid in the sense that the data canonically converts is converting an object node
+					// to a map node over the union of all the object fields' types.
+					if (discrepancy.stored === undefined) {
+						const viewIsNever =
+							viewNodeSchema !== undefined
+								? isNeverTree(this.policy, this.viewSchemaAsStored, viewNodeSchema)
+								: true;
+						if (!viewIsNever) {
+							// View schema has added a node type that the stored schema doesn't know about.
+							canView = false;
+						}
+					} else if (discrepancy.view === undefined) {
+						const storedIsNever =
+							storedNodeSchema !== undefined
+								? isNeverTree(this.policy, stored, storedNodeSchema)
+								: true;
+						if (!storedIsNever) {
+							// Stored schema has a node type that the view schema doesn't know about.
+							canUpgrade = false;
+						}
+					} else {
+						// Node type exists in both schemas but has changed. We conservatively never allow this.
+						const storedIsNever =
+							storedNodeSchema !== undefined
+								? isNeverTree(this.policy, stored, storedNodeSchema)
+								: true;
+						const viewIsNever =
+							viewNodeSchema !== undefined
+								? isNeverTree(this.policy, this.viewSchemaAsStored, viewNodeSchema)
+								: true;
+						if (!storedIsNever || !viewIsNever) {
+							canView = false;
+							canUpgrade = false;
+						}
+					}
+					break;
+				}
+				case "valueSchema":
+				case "allowedTypes":
+				case "fieldKind": {
+					updateCompatibilityFromFieldDiscrepancy(discrepancy);
+					break;
+				}
+				case "fields": {
+					discrepancy.differences.forEach(updateCompatibilityFromFieldDiscrepancy);
+					break;
+				}
+				// No default
+			}
+		}
+
+		return {
+			canView,
+			canUpgrade,
+			isEquivalent: canView && canUpgrade,
+		};
 	}
 
 	/**
@@ -102,8 +241,15 @@ export class ViewSchema {
 		// since there never is a reason to have a never type as an adapter input,
 		// and its impossible for an adapter to be correctly implemented if its output type is never
 		// (unless its input is also never).
+
 		for (const adapter of this.adapters?.tree ?? []) {
-			if (isNeverTree(this.policy, this.schema, this.schema.nodeSchema.get(adapter.output))) {
+			if (
+				isNeverTree(
+					this.policy,
+					this.viewSchemaAsStored,
+					this.viewSchemaAsStored.nodeSchema.get(adapter.output),
+				)
+			) {
 				fail("tree adapter for stored adapter.output should not be never");
 			}
 		}

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;

package/src/simple-tree/arrayNode.ts

@@ -18,6 +18,7 @@ import {
 	normalizeAllowedTypes,
 	type ImplicitAllowedTypes,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
+	type NodeSchemaMetadata,
 	type TreeLeafValue,
 	type TreeNodeFromImplicitAllowedTypes,
 } from "./schemaTypes.js";
@@ -1062,11 +1063,13 @@ export function arraySchema<
 	TName extends string,
 	const T extends ImplicitAllowedTypes,
 	const ImplicitlyConstructable extends boolean,
+	const TCustomMetadata = unknown,
 >(
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
 	customizable: boolean,
+	metadata?: NodeSchemaMetadata<TCustomMetadata>,
 ) {
 	type Output = TreeNodeSchemaBoth<
 		TName,
@@ -1075,7 +1078,8 @@ export function arraySchema<
 		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 		ImplicitlyConstructable,
 		T,
-		undefined
+		undefined,
+		TCustomMetadata
 	>;
 
 	const lazyChildTypes = new Lazy(() => normalizeAllowedTypes(info));
@@ -1157,6 +1161,8 @@ export function arraySchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;
 		}
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> | undefined =
+			metadata;
 
 		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {