@fluidframework/tree 2.11.0 → 2.13.0

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

@@ -11,8 +11,12 @@ import {
 	EmptyKey,
 	forEachField,
 	inCursorField,
+	LeafNodeStoredSchema,
 	mapCursorField,
+	ObjectNodeStoredSchema,
 	type ITreeCursor,
+	type TreeNodeSchemaIdentifier,
+	type TreeNodeStoredSchema,
 } from "../../core/index.js";
 import { fail } from "../../util/index.js";
 import type { TreeLeafValue } from "../schemaTypes.js";
@@ -25,6 +29,7 @@ import {
 	stringSchema,
 } from "../leafNodeSchema.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
+import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js";
 
 /**
  * Options for how to encode a tree.
@@ -63,7 +68,7 @@ export type CustomTreeNode<TChild> = TChild[] | { [key: string]: TChild };
 /**
  * Builds an {@link CustomTree} from a cursor in Nodes mode.
  */
-export function customFromCursorInner<TChild, THandle>(
+export function customFromCursor<TChild, THandle>(
 	reader: ITreeCursor,
 	options: Required<EncodeOptions<THandle>>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
@@ -118,3 +123,66 @@ export function customFromCursorInner<TChild, THandle>(
 		}
 	}
 }
+
+/**
+ * Builds an {@link CustomTree} from a cursor in Nodes mode.
+ * @remarks
+ * Uses stored keys and stored schema.
+ */
+export function customFromCursorStored<TChild>(
+	reader: ITreeCursor,
+	schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>,
+	childHandler: (
+		reader: ITreeCursor,
+		schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>,
+	) => TChild,
+): CustomTree<TChild, IFluidHandle> {
+	const type = reader.type;
+	const nodeSchema = schema.get(type) ?? fail("missing schema for type in cursor");
+
+	if (nodeSchema instanceof LeafNodeStoredSchema) {
+		assert(valueSchemaAllows(nodeSchema.leafValue, reader.value), 0xa9c /* invalid value */);
+		return reader.value;
+	}
+
+	assert(reader.value === undefined, 0xa9d /* out of schema: unexpected value */);
+
+	const arrayTypes = tryStoredSchemaAsArray(nodeSchema);
+	if (arrayTypes !== undefined) {
+		const field = inCursorField(reader, EmptyKey, () =>
+			mapCursorField(reader, () => childHandler(reader, schema)),
+		);
+		return field;
+	}
+
+	const fields: Record<string, TChild> = {};
+	forEachField(reader, () => {
+		const children = mapCursorField(reader, () => childHandler(reader, schema));
+		if (children.length === 1) {
+			const storedKey = reader.getFieldKey();
+			// Length is checked above.
+			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+			fields[storedKey] = children[0]!;
+		} else {
+			assert(children.length === 0, 0xa9e /* invalid children number */);
+		}
+	});
+	return fields;
+}
+
+/**
+ * Assumes `schema` corresponds to a simple-tree schema.
+ * If it is an array schema, returns the allowed types for the array field.
+ * Otherwise returns `undefined`.
+ */
+export function tryStoredSchemaAsArray(
+	schema: TreeNodeStoredSchema,
+): ReadonlySet<string> | undefined {
+	if (schema instanceof ObjectNodeStoredSchema) {
+		const empty = schema.getFieldSchema(EmptyKey);
+		if (empty.kind === FieldKinds.sequence.identifier) {
+			assert(schema.objectNodeFields.size === 1, 0xa9f /* invalid schema */);
+			return empty.types;
+		}
+	}
+}

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

@@ -17,7 +17,12 @@ export {
 	type TreeBranchEvents,
 	asTreeViewAlpha,
 } from "./tree.js";
-export { SchemaFactory, type ScopedSchemaName } from "./schemaFactory.js";
+export {
+	SchemaFactory,
+	type ScopedSchemaName,
+	type SchemaFactoryObjectOptions,
+} from "./schemaFactory.js";
+export { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 export type {
 	ValidateRecursiveSchema,
 	FixRecursiveArraySchema,
@@ -90,7 +95,13 @@ export {
 	verboseFromCursor,
 } from "./verboseTree.js";
 
-export type { EncodeOptions } from "./customTree.js";
+export {
+	type EncodeOptions,
+	customFromCursorStored,
+	type CustomTreeNode,
+	type CustomTreeValue,
+	tryStoredSchemaAsArray,
+} from "./customTree.js";
 
 export { type ConciseTree, conciseFromCursor } from "./conciseTree.js";
 

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

@@ -58,6 +58,13 @@ export interface JsonNodeSchemaBase<
 	 * {@inheritDoc JsonSchemaType}
 	 */
 	readonly type: TJsonSchemaType;
+
+	/**
+	 * Description of the node schema.
+	 * @remarks Derived from {@link NodeSchemaMetadata.description}.
+	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-validation#name-title-and-description}
+	 */
+	readonly description?: string | undefined;
 }
 
 /**

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

@@ -18,6 +18,9 @@ import {
 	getOrCreate,
 	isReadonlyArray,
 } from "../../util/index.js";
+// This import is required for intellisense in @link doc comments on mouseover in VSCode.
+// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
+import type { TreeAlpha } from "../../shared-tree/index.js";
 
 import {
 	booleanSchema,
@@ -37,6 +40,7 @@ import {
 	createFieldSchema,
 	type DefaultProvider,
 	getDefaultProvider,
+	type NodeSchemaOptions,
 } from "../schemaTypes.js";
 import { inPrototypeChain } from "../core/index.js";
 import type {
@@ -74,6 +78,7 @@ import type {
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
 import { TreeNodeValid } from "../treeNodeValid.js";
 import { isLazy } from "../flexList.js";
+
 /**
  * Gets the leaf domain schema compatible with a given {@link TreeValue}.
  */
@@ -97,6 +102,64 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
 	}
 }
 
+/**
+ * Options when declaring an {@link SchemaFactory.object|object node}'s schema
+ *
+ * @alpha
+ */
+export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown>
+	extends NodeSchemaOptions<TCustomMetadata> {
+	/**
+	 * 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
+	 * The advantage of enabling this option is that it allows an application ecosystem with staged rollout to more quickly
+	 * upgrade documents to include schema for new optional features.
+	 *
+	 * However, it does come with trade-offs that applications should weigh carefully when it comes to interactions between
+	 * code and documents.
+	 * When opening such documents, the API presented is still determined by the view schema.
+	 * This can have implications on the behavior of edits or code which uses portions of the view schema,
+	 * since this may inadvertently drop data which is present in those optional fields in the document schema.
+	 *
+	 * Consider the following example:
+	 *
+	 * ```typescript
+	 * const sf = new SchemaFactory("com.example");
+	 * class PersonView extends sf.object("Person", { name: sf.string }, { allowUnknownOptionalFields: true }) {}
+	 * class PersonStored extends sf.object("Person", { name: sf.string, nickname: sf.optional(sf.string) }) {}
+	 *
+	 * // Say we have a document which uses `PersonStored` in its schema, and application code constructs
+	 * // a tree view using `PersonView`. If the application for some reason had implemented a function like this:
+	 * function clonePerson(a: PersonView): PersonView {
+	 * 	return new PersonView({ name: a.name });
+	 * }
+	 * // ...or even like this:
+	 * function clonePerson(a: PersonView): PersonView {
+	 *  return new PersonView({ ...a})
+	 * }
+	 * // Then the alleged clone wouldn't actually clone the entire person in either case, it would drop the nickname.
+	 * ```
+	 *
+	 * If an application wants to be particularly careful to preserve all data on a node when editing it, it can use
+	 * {@link TreeAlpha.(importVerbose:2)|import}/{@link TreeAlpha.(exportVerbose:2)|export} APIs with persistent keys.
+	 *
+	 * Note that public API methods which operate on entire nodes (such as `moveTo`, `moveToEnd`, etc. on arrays) do not encounter
+	 * this problem as SharedTree's implementation stores the entire node in its lower layers. It's only when application code
+	 * reaches into a node (either by accessing its fields, spreading it, or some other means) that this problem arises.
+	 */
+	allowUnknownOptionalFields?: boolean;
+}
+
+export const defaultSchemaFactoryObjectOptions: Required<
+	Omit<SchemaFactoryObjectOptions, "metadata">
+> = {
+	allowUnknownOptionalFields: false,
+};
+
 /**
  * The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.
  *
@@ -333,12 +396,19 @@ export class SchemaFactory<
 		true,
 		T
 	> {
-		return objectSchema(this.scoped(name), fields, true);
+		return objectSchema(
+			this.scoped(name),
+			fields,
+			true,
+			defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
+		);
 	}
 
 	/**
 	 * 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.
@@ -375,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
@@ -395,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
@@ -469,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.
@@ -521,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
@@ -543,6 +620,8 @@ export class SchemaFactory<
 	>;
 
 	/**
+	 * {@link SchemaFactory.array} implementation.
+	 *
 	 * @privateRemarks
 	 * This should return TreeNodeSchemaBoth: see note on "map" implementation for details.
 	 */
@@ -726,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;
 }
 
 /**
@@ -30,7 +35,9 @@ export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
  */
 export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Object> {
 	/**
-	 * Schemas for each of the object's fields, keyed off of schema's property keys.
+	 * Schemas for each of the object's fields, keyed off of schema's keys.
+	 * @remarks
+	 * Depending on how this schema was exported, the string keys may be either the property keys or the stored keys.
 	 */
 	readonly fields: Record<string, SimpleFieldSchema>;
 }

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 {