@fluidframework/tree 2.12.0 → 2.13.0

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/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 {

package/src/simple-tree/core/treeNodeSchema.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { TreeLeafValue } from "../schemaTypes.js";
+import type { NodeSchemaMetadata, TreeLeafValue } from "../schemaTypes.js";
 import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
 
 /**
@@ -27,11 +27,30 @@ export type TreeNodeSchema<
 	TBuild = never,
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
+	TCustomMetadata = unknown,
 > =
 	| (TNode extends TreeNode
-			? TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>
+			? TreeNodeSchemaClass<
+					Name,
+					Kind,
+					TNode,
+					TBuild,
+					ImplicitlyConstructable,
+					Info,
+					never,
+					TCustomMetadata
+				>
 			: never)
-	| TreeNodeSchemaNonClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;
+	| TreeNodeSchemaNonClass<
+			Name,
+			Kind,
+			TNode,
+			TBuild,
+			ImplicitlyConstructable,
+			Info,
+			never,
+			TCustomMetadata
+	  >;
 
 /**
  * Schema which is not a class.
@@ -49,7 +68,15 @@ export type TreeNodeSchemaNonClass<
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
 	TConstructorExtra = never,
-> = TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info, TInsertable> &
+	TCustomMetadata = unknown,
+> = TreeNodeSchemaCore<
+	Name,
+	Kind,
+	ImplicitlyConstructable,
+	Info,
+	TInsertable,
+	TCustomMetadata
+> &
 	(undefined extends TConstructorExtra
 		? {
 				/**
@@ -119,7 +146,15 @@ export type TreeNodeSchemaClass<
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
 	TConstructorExtra = never,
-> = TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info, TInsertable> &
+	TCustomMetadata = unknown,
+> = TreeNodeSchemaCore<
+	Name,
+	Kind,
+	ImplicitlyConstructable,
+	Info,
+	TInsertable,
+	TCustomMetadata
+> &
 	(undefined extends TConstructorExtra
 		? {
 				/**
@@ -157,6 +192,7 @@ export type TreeNodeSchemaBoth<
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
 	TConstructorExtra = never,
+	TCustomMetadata = unknown,
 > = TreeNodeSchemaClass<
 	Name,
 	Kind,
@@ -164,7 +200,8 @@ export type TreeNodeSchemaBoth<
 	TInsertable,
 	ImplicitlyConstructable,
 	Info,
-	TConstructorExtra
+	TConstructorExtra,
+	TCustomMetadata
 > &
 	TreeNodeSchemaNonClass<
 		Name,
@@ -173,7 +210,8 @@ export type TreeNodeSchemaBoth<
 		TInsertable,
 		ImplicitlyConstructable,
 		Info,
-		TConstructorExtra
+		TConstructorExtra,
+		TCustomMetadata
 	>;
 
 /**
@@ -188,6 +226,7 @@ export interface TreeNodeSchemaCore<
 	out ImplicitlyConstructable extends boolean,
 	out Info = unknown,
 	out TInsertable = never,
+	out TCustomMetadata = unknown,
 > {
 	/**
 	 * Unique (within a document's schema) identifier used to associate nodes with their schema.
@@ -244,6 +283,11 @@ export interface TreeNodeSchemaCore<
 	 */
 	readonly childTypes: ReadonlySet<TreeNodeSchema>;
 
+	/**
+	 * User-provided {@link NodeSchemaMetadata} for this schema.
+	 */
+	readonly metadata?: NodeSchemaMetadata<TCustomMetadata> | undefined;
+
 	/**
 	 * Constructs an instance of this node type.
 	 * @remarks

package/src/simple-tree/index.ts

@@ -35,6 +35,7 @@ export {
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
 	SchemaFactory,
+	SchemaFactoryAlpha,
 	type SchemaFactoryObjectOptions,
 	type ScopedSchemaName,
 	type ValidateRecursiveSchema,
@@ -155,6 +156,8 @@ export {
 	type Input,
 	type ReadableField,
 	type ReadSchema,
+	type NodeSchemaOptions,
+	type NodeSchemaMetadata,
 } from "./schemaTypes.js";
 export {
 	getTreeNodeForField,

package/src/simple-tree/mapNode.ts

@@ -17,6 +17,7 @@ import {
 	normalizeAllowedTypes,
 	type ImplicitAllowedTypes,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
+	type NodeSchemaMetadata,
 	type TreeNodeFromImplicitAllowedTypes,
 } from "./schemaTypes.js";
 import {
@@ -235,11 +236,13 @@ export function mapSchema<
 	TName extends string,
 	const T extends ImplicitAllowedTypes,
 	const ImplicitlyConstructable extends boolean,
+	const TCustomMetadata = unknown,
 >(
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
 	useMapPrototype: boolean,
+	metadata?: NodeSchemaMetadata<TCustomMetadata>,
 ) {
 	const lazyChildTypes = new Lazy(() => normalizeAllowedTypes(info));
 
@@ -283,6 +286,8 @@ export function mapSchema<
 		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 {
@@ -299,7 +304,8 @@ export function mapSchema<
 		MapNodeInsertableData<T>,
 		ImplicitlyConstructable,
 		T,
-		undefined
+		undefined,
+		TCustomMetadata
 	> = Schema;
 	return schemaErased;
 }

package/src/simple-tree/objectNode.ts

@@ -26,6 +26,7 @@ import {
 	normalizeFieldSchema,
 	type ImplicitAllowedTypes,
 	FieldKind,
+	type NodeSchemaMetadata,
 } from "./schemaTypes.js";
 import {
 	type TreeNodeSchema,
@@ -330,12 +331,15 @@ export function objectSchema<
 	TName extends string,
 	const T extends RestrictiveStringRecord<ImplicitFieldSchema>,
 	const ImplicitlyConstructable extends boolean,
+	const TCustomMetadata = unknown,
 >(
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
 	allowUnknownOptionalFields: boolean,
-): ObjectNodeSchema<TName, T, ImplicitlyConstructable> & ObjectNodeSchemaInternalData {
+	metadata?: NodeSchemaMetadata<TCustomMetadata>,
+): ObjectNodeSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> &
+	ObjectNodeSchemaInternalData {
 	// Ensure no collisions between final set of property keys, and final set of stored keys (including those
 	// implicitly derived from property keys)
 	assertUniqueKeys(identifier, info);
@@ -460,6 +464,8 @@ export function objectSchema<
 		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 {

package/src/simple-tree/objectNodeTypes.ts

@@ -23,13 +23,16 @@ export interface ObjectNodeSchema<
 	T extends
 		RestrictiveStringRecord<ImplicitFieldSchema> = RestrictiveStringRecord<ImplicitFieldSchema>,
 	ImplicitlyConstructable extends boolean = boolean,
+	TCustomMetadata = unknown,
 > extends TreeNodeSchemaClass<
 		TName,
 		NodeKind.Object,
 		TreeObjectNode<T, TName>,
 		object & InsertableObjectFromSchemaRecord<T>,
 		ImplicitlyConstructable,
-		T
+		T,
+		never,
+		TCustomMetadata
 	> {
 	/**
 	 * From property keys to the associated schema.

package/src/simple-tree/schemaTypes.ts

@@ -190,7 +190,10 @@ export interface FieldProps<TCustomMetadata = unknown> {
 
 	/**
 	 * Optional metadata to associate with the field.
-	 * @remarks Note: this metadata is not persisted in the document.
+	 *
+	 * @remarks
+	 * Note: this metadata is not persisted nor made part of the collaborative state; it is strictly client-local.
+	 * Different clients in the same collaborative session may see different metadata for the same field.
 	 */
 	readonly metadata?: FieldSchemaMetadata<TCustomMetadata>;
 }
@@ -824,3 +827,49 @@ export type NodeBuilderData<T extends TreeNodeSchemaCore<string, NodeKind, boole
  */
 // eslint-disable-next-line @rushstack/no-new-null
 export type TreeLeafValue = number | string | boolean | IFluidHandle | null;
+
+/**
+ * Additional information to provide to Node Schema creation.
+ *
+ * @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.
+ * See {@link NodeSchemaMetadata.custom}.
+ *
+ * @sealed
+ * @public
+ */
+export interface NodeSchemaOptions<out TCustomMetadata = unknown> {
+	/**
+	 * Optional metadata to associate with the Node Schema.
+	 *
+	 * @remarks
+	 * Note: this metadata is not persisted nor made part of the collaborative state; it is strictly client-local.
+	 * Different clients in the same collaborative session may see different metadata for the same field.
+	 */
+	readonly metadata?: NodeSchemaMetadata<TCustomMetadata> | undefined;
+}
+
+/**
+ * Metadata associated with a Node Schema.
+ *
+ * @remarks Specified via {@link NodeSchemaOptions.metadata}.
+ *
+ * @sealed
+ * @public
+ */
+export interface NodeSchemaMetadata<out TCustomMetadata = unknown> {
+	/**
+	 * User-defined metadata.
+	 */
+	readonly custom?: TCustomMetadata | undefined;
+
+	/**
+	 * The description of the Node Schema.
+	 *
+	 * @remarks
+	 *
+	 * If provided, will be used by the system in scenarios where a description of the kind of node is useful.
+	 * E.g., when converting a Node Schema to {@link https://json-schema.org/ | JSON Schema}, this description will be
+	 * used as the `description` property.
+	 */
+	readonly description?: string | undefined;
+}

package/src/util/index.ts

@@ -94,6 +94,7 @@ export {
 	hasSome,
 	hasSingle,
 	defineLazyCachedProperty,
+	copyPropertyIfDefined as copyProperty,
 } from "./utils.js";
 export { ReferenceCountedBase, type ReferenceCounted } from "./referenceCounting.js";
 
@@ -120,13 +121,8 @@ export {
 } from "./brandedMap.js";
 
 export {
-	getFirstEntryFromRangeMap,
-	getFromRangeMap,
-	type RangeEntry,
-	type RangeMap,
+	RangeMap,
 	type RangeQueryResult,
-	setInRangeMap,
-	deleteFromRangeMap,
 } from "./rangeMap.js";
 
 export {