@fluidframework/tree 2.3.0 → 2.4.0-294316

package/src/feature-libraries/modular-schema/modularChangeFamily.ts

@@ -38,6 +38,7 @@ import {
 	revisionMetadataSourceFromInfo,
 	areEqualChangeAtomIds,
 	type ChangeAtomId,
+	areEqualChangeAtomIdOpts,
 } from "../../core/index.js";
 import {
 	type IdAllocationState,
@@ -263,8 +264,6 @@ export class ModularChangeFamily
 		const genId: IdAllocator = idAllocatorFromState(idState);
 		const revisionMetadata: RevisionMetadataSource = revisionMetadataSourceFromInfo(revInfos);
 
-		const crossFieldTable = newComposeTable(change1, change2);
-
 		// We merge nodeChanges, nodeToParent, and nodeAliases from the two changesets.
 		// The merged tables will have correct entries for all nodes which are only referenced in one of the input changesets.
 		// During composeFieldMaps and composeInvalidatedElements we will find all nodes referenced in both input changesets
@@ -284,9 +283,12 @@ export class ModularChangeFamily
 			mergeBTrees(change1.nodeAliases, change2.nodeAliases),
 		);
 
+		const crossFieldTable = newComposeTable(change1, change2, composedNodeToParent);
+
 		const composedFields = this.composeFieldMaps(
 			change1.fieldChanges,
 			change2.fieldChanges,
+			undefined,
 			genId,
 			crossFieldTable,
 			revisionMetadata,
@@ -321,7 +323,7 @@ export class ModularChangeFamily
 	): void {
 		const context = crossFieldTable.fieldToContext.get(fieldChange);
 		assert(context !== undefined, 0x8cc /* Should have context for every invalidated field */);
-		const { change1: fieldChange1, change2: fieldChange2, composedChange } = context;
+		const { fieldId, change1: fieldChange1, change2: fieldChange2, composedChange } = context;
 
 		const rebaser = getChangeHandler(this.fieldKinds, composedChange.fieldKind).rebaser;
 		const composeNodes = (child1: NodeId | undefined, child2: NodeId | undefined): NodeId => {
@@ -342,7 +344,7 @@ export class ModularChangeFamily
 			fieldChange2,
 			composeNodes,
 			genId,
-			new ComposeManager(crossFieldTable, fieldChange, false),
+			new ComposeManager(crossFieldTable, fieldChange, fieldId, false),
 			revisionMetadata,
 		);
 		composedChange.change = brand(amendedChange);
@@ -470,7 +472,14 @@ export class ModularChangeFamily
 				? [fieldChange, emptyChange]
 				: [emptyChange, fieldChange];
 
-			const composedField = this.composeFieldChanges(change1, change2, genId, table, metadata);
+			const composedField = this.composeFieldChanges(
+				fieldId,
+				change1,
+				change2,
+				genId,
+				table,
+				metadata,
+			);
 
 			if (fieldId.nodeId === undefined) {
 				composedFields.set(fieldId.field, composedField);
@@ -499,6 +508,7 @@ export class ModularChangeFamily
 	private composeFieldMaps(
 		change1: FieldChangeMap | undefined,
 		change2: FieldChangeMap | undefined,
+		parentId: NodeId | undefined,
 		genId: IdAllocator,
 		crossFieldTable: ComposeTable,
 		revisionMetadata: RevisionMetadataSource,
@@ -509,10 +519,12 @@ export class ModularChangeFamily
 		}
 
 		for (const [field, fieldChange1] of change1) {
+			const fieldId: FieldId = { nodeId: parentId, field };
 			const fieldChange2 = change2.get(field);
 			const composedField =
 				fieldChange2 !== undefined
 					? this.composeFieldChanges(
+							fieldId,
 							fieldChange1,
 							fieldChange2,
 							genId,
@@ -545,6 +557,7 @@ export class ModularChangeFamily
 	 * Any composed `FieldChange` which is invalidated by new cross-field information will be added to `crossFieldTable.invalidatedFields`.
 	 */
 	private composeFieldChanges(
+		fieldId: FieldId,
 		change1: FieldChange,
 		change2: FieldChange,
 		idAllocator: IdAllocator,
@@ -558,7 +571,7 @@ export class ModularChangeFamily
 			change2: change2Normalized,
 		} = this.normalizeFieldChanges(change1, change2, idAllocator, revisionMetadata);
 
-		const manager = new ComposeManager(crossFieldTable, change1);
+		const manager = new ComposeManager(crossFieldTable, change1, fieldId);
 
 		const composedChange = changeHandler.rebaser.compose(
 			change1Normalized,
@@ -581,6 +594,7 @@ export class ModularChangeFamily
 		};
 
 		crossFieldTable.fieldToContext.set(change1, {
+			fieldId,
 			change1: change1Normalized,
 			change2: change2Normalized,
 			composedChange: composedField,
@@ -605,6 +619,7 @@ export class ModularChangeFamily
 		const nodeChangeset1 = nodeChangeFromId(nodeChanges1, id1);
 		const nodeChangeset2 = nodeChangeFromId(nodeChanges2, id2);
 		const composedNodeChangeset = this.composeNodeChanges(
+			id1,
 			nodeChangeset1,
 			nodeChangeset2,
 			idAllocator,
@@ -627,6 +642,7 @@ export class ModularChangeFamily
 	}
 
 	private composeNodeChanges(
+		nodeId: NodeId,
 		change1: NodeChangeset,
 		change2: NodeChangeset,
 		genId: IdAllocator,
@@ -638,6 +654,7 @@ export class ModularChangeFamily
 		const composedFieldChanges = this.composeFieldMaps(
 			change1.fieldChanges,
 			change2.fieldChanges,
+			nodeId,
 			genId,
 			crossFieldTable,
 			revisionMetadata,
@@ -887,7 +904,7 @@ export class ModularChangeFamily
 			rebasedNodes,
 		);
 
-		return makeModularChangeset(
+		const rebased = makeModularChangeset(
 			this.pruneFieldMap(rebasedFields, rebasedNodes),
 			rebasedNodes,
 			crossFieldTable.rebasedNodeToParent,
@@ -900,6 +917,8 @@ export class ModularChangeFamily
 			change.destroys,
 			change.refreshers,
 		);
+
+		return rebased;
 	}
 
 	// This performs a first pass on all fields which have both new and base changes.
@@ -1584,6 +1603,57 @@ export class ModularChangeFamily
 		const emptyChange = getChangeHandler(this.fieldKinds, fieldKind).createEmpty();
 		return { fieldKind, change: brand(emptyChange) };
 	}
+
+	public validateChangeset(change: ModularChangeset): void {
+		let numNodes = this.validateFieldChanges(change, change.fieldChanges, undefined);
+
+		for (const [[revision, localId], node] of change.nodeChanges.entries()) {
+			if (node.fieldChanges === undefined) {
+				continue;
+			}
+
+			const nodeId: NodeId = { revision, localId };
+			const numChildren = this.validateFieldChanges(change, node.fieldChanges, nodeId);
+
+			numNodes += numChildren;
+		}
+
+		assert(numNodes === change.nodeChanges.size, "Node table contains unparented nodes");
+	}
+
+	/**
+	 * Asserts that each child and cross field key in each field has a correct entry in
+	 * `nodeToParent` or `crossFieldKeyTable`.
+	 * @returns the number of children found.
+	 */
+	private validateFieldChanges(
+		change: ModularChangeset,
+		fieldChanges: FieldChangeMap,
+		nodeParent: NodeId | undefined,
+	): number {
+		let numChildren = 0;
+		for (const [field, fieldChange] of fieldChanges.entries()) {
+			const fieldId = { nodeId: nodeParent, field };
+			const handler = getChangeHandler(this.fieldKinds, fieldChange.fieldKind);
+			for (const [child, _index] of handler.getNestedChanges(fieldChange.change)) {
+				const parentFieldId = getParentFieldId(change, child);
+				assert(areEqualFieldIds(parentFieldId, fieldId), "Inconsistent node parentage");
+				numChildren += 1;
+			}
+
+			for (const keyRange of handler.getCrossFieldKeys(fieldChange.change)) {
+				const fields = getFieldsForCrossFieldKey(change, keyRange);
+				assert(
+					fields.length === 1 &&
+						fields[0] !== undefined &&
+						areEqualFieldIds(fields[0], fieldId),
+					"Inconsistent cross field keys",
+				);
+			}
+		}
+
+		return numChildren;
+	}
 }
 
 function replaceCrossFieldKeyTableRevisions(
@@ -2059,6 +2129,7 @@ interface RebaseFieldContext {
 function newComposeTable(
 	baseChange: ModularChangeset,
 	newChange: ModularChangeset,
+	composedNodeToParent: ChangeAtomIdBTree<FieldId>,
 ): ComposeTable {
 	return {
 		...newCrossFieldTable<FieldChange>(),
@@ -2068,6 +2139,7 @@ function newComposeTable(
 		newFieldToBaseField: new Map(),
 		newToBaseNodeId: newTupleBTree(),
 		composedNodes: new Set(),
+		composedNodeToParent,
 		pendingCompositions: {
 			nodeIdsToCompose: [],
 			affectedBaseFields: newTupleBTree(),
@@ -2087,6 +2159,7 @@ interface ComposeTable extends CrossFieldTable<FieldChange> {
 	readonly newFieldToBaseField: Map<FieldChange, FieldChange>;
 	readonly newToBaseNodeId: ChangeAtomIdBTree<NodeId>;
 	readonly composedNodes: Set<NodeChangeset>;
+	readonly composedNodeToParent: ChangeAtomIdBTree<FieldId>;
 	readonly pendingCompositions: PendingCompositions;
 }
 
@@ -2109,6 +2182,10 @@ interface PendingCompositions {
 }
 
 interface ComposeFieldContext {
+	/**
+	 * The field ID for this field in the composed changeset.
+	 */
+	fieldId: FieldId;
 	change1: FieldChangeset;
 	change2: FieldChangeset;
 	composedChange: FieldChange;
@@ -2324,7 +2401,12 @@ class RebaseManager extends CrossFieldManagerI<FieldChange> {
 
 // TODO: Deduplicate this with RebaseTable
 class ComposeManager extends CrossFieldManagerI<FieldChange> {
-	public constructor(table: ComposeTable, currentField: FieldChange, allowInval = true) {
+	public constructor(
+		table: ComposeTable,
+		currentField: FieldChange,
+		private readonly fieldId: FieldId,
+		allowInval = true,
+	) {
 		super(table, currentField, allowInval);
 	}
 
@@ -2377,15 +2459,16 @@ class ComposeManager extends CrossFieldManagerI<FieldChange> {
 	}
 
 	public override onMoveIn(id: ChangeAtomId): void {
-		throw new Error("Method not implemented.");
+		setInChangeAtomIdMap(this.table.composedNodeToParent, id, this.fieldId);
 	}
+
 	public override moveKey(
 		target: CrossFieldTarget,
 		revision: RevisionTag | undefined,
 		id: ChangesetLocalId,
 		count: number,
 	): void {
-		throw new Error("Method not implemented.");
+		throw new Error("Moving cross-field keys during compose is currently unsupported");
 	}
 
 	private get table(): ComposeTable {
@@ -3022,3 +3105,7 @@ function getFromChangeAtomIdMap<T>(
 function setInChangeAtomIdMap<T>(map: ChangeAtomIdBTree<T>, id: ChangeAtomId, value: T): void {
 	map.set([id.revision, id.localId], value);
 }
+
+function areEqualFieldIds(a: FieldId, b: FieldId): boolean {
+	return areEqualChangeAtomIdOpts(a.nodeId, b.nodeId) && a.field === b.field;
+}

package/src/feature-libraries/sequence-field/compose.ts

@@ -576,6 +576,9 @@ export class ComposeQueue {
 	private dequeueBase(length: number = Infinity): ComposeMarks {
 		const baseMark = this.baseMarks.dequeueUpTo(length);
 		const movedChanges = getMovedChangesFromMark(this.moveEffects, baseMark);
+		if (movedChanges !== undefined) {
+			this.moveEffects.onMoveIn(movedChanges);
+		}
 
 		const newMark = createNoopMark(baseMark.count, movedChanges, getOutputCellId(baseMark));
 		return { baseMark, newMark };

package/src/feature-libraries/sequence-field/utils.ts

@@ -10,6 +10,7 @@ import {
 	type ChangesetLocalId,
 	type RevisionMetadataSource,
 	type RevisionTag,
+	areEqualChangeAtomIdOpts,
 	areEqualChangeAtomIds,
 	makeChangeAtomId,
 } from "../../core/index.js";
@@ -118,10 +119,7 @@ export function isActiveReattach(
 }
 
 export function areEqualCellIds(a: CellId | undefined, b: CellId | undefined): boolean {
-	if (a === undefined || b === undefined) {
-		return a === b;
-	}
-	return areEqualChangeAtomIds(a, b);
+	return areEqualChangeAtomIdOpts(a, b);
 }
 
 export function getInputCellId(mark: Mark): CellId | undefined {

package/src/index.ts

@@ -82,6 +82,7 @@ export {
 	type TreeLeafValue,
 	FieldKind,
 	FieldSchema,
+	type FieldSchemaMetadata,
 	type ImplicitAllowedTypes,
 	type InsertableTreeFieldFromImplicitField,
 	type InsertableTypedNode,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.3.0";
+export const pkgVersion = "2.4.0-294316";

package/src/shared-tree/schematizingTreeView.ts

@@ -123,6 +123,10 @@ export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitField
 		);
 	}
 
+	public get schema(): TRootSchema {
+		return this.config.schema;
+	}
+
 	public initialize(content: InsertableTreeFieldFromImplicitField<TRootSchema>): void {
 		this.ensureUndisposed();
 

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

@@ -103,18 +103,10 @@ export interface JsonObjectNodeSchema extends JsonNodeSchemaBase<NodeKind.Object
 export interface JsonArrayNodeSchema extends JsonNodeSchemaBase<NodeKind.Array, "array"> {
 	/**
 	 * The kinds of items allowed under the array.
-	 * @remarks Always represented via references to {@link JsonTreeSchema.$defs}.
 	 *
 	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-items}.
 	 */
-	readonly items: {
-		/**
-		 * The kinds of items allowed under the array.
-		 * @remarks Always represented via references to {@link JsonTreeSchema.$defs}.
-		 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-anyof}.
-		 */
-		anyOf: JsonSchemaRef[];
-	};
+	readonly items: JsonFieldSchema;
 }
 
 /**
@@ -191,14 +183,24 @@ export type JsonNodeSchema =
  * @sealed
  * @alpha
  */
-export interface JsonFieldSchema {
+export type JsonFieldSchema = {
 	/**
-	 * The kinds of items allowed under the field.
-	 * @remarks Always represented via references to {@link JsonTreeSchema.$defs}.
-	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-anyof}.
+	 * Description of the field.
+	 * @remarks Derived from {@link FieldSchemaMetadata.description}.
+	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-validation#name-title-and-description}
 	 */
-	readonly anyOf: JsonSchemaRef[];
-}
+	readonly description?: string | undefined;
+} & (
+	| {
+			/**
+			 * The kinds of items allowed under the field, for polymorphic types.
+			 * @remarks Always represented via references to {@link JsonTreeSchema.$defs}.
+			 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-anyof}.
+			 */
+			readonly anyOf: JsonSchemaRef[];
+	  }
+	| JsonSchemaRef
+);
 
 /**
  * {@link https://json-schema.org/draft/2020-12/json-schema-core | JSON Schema} representation of a tree schema.
@@ -221,10 +223,10 @@ export interface JsonFieldSchema {
  * @sealed
  * @alpha
  */
-export interface JsonTreeSchema extends JsonFieldSchema {
+export type JsonTreeSchema = JsonFieldSchema & {
 	/**
 	 * The set of definitions reachable from this schema's root.
 	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-schema-re-use-with-defs}
 	 */
 	readonly $defs: Record<JsonSchemaId, JsonNodeSchema>;
-}
+};

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

@@ -552,11 +552,14 @@ export class SchemaFactory<
 	 *
 	 * @param t - The types allowed under the field.
 	 * @param props - Optional properties to associate with the field.
+	 *
+	 * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+	 * See {@link FieldSchemaMetadata.custom}.
 	 */
-	public optional<const T extends ImplicitAllowedTypes>(
+	public optional<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 		t: T,
-		props?: Omit<FieldProps, "defaultProvider">,
-	): FieldSchema<FieldKind.Optional, T> {
+		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	): FieldSchema<FieldKind.Optional, T, TCustomMetadata> {
 		const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => {
 			return undefined;
 		});
@@ -575,11 +578,14 @@ export class SchemaFactory<
 	 * @remarks
 	 * Fields are required by default, but this API can be used to make the required nature explicit in the schema,
 	 * and allows associating custom {@link FieldProps | properties} with the field.
+	 *
+	 * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+	 * See {@link FieldSchemaMetadata.custom}.
 	 */
-	public required<const T extends ImplicitAllowedTypes>(
+	public required<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 		t: T,
-		props?: Omit<FieldProps, "defaultProvider">,
-	): FieldSchema<FieldKind.Required, T> {
+		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	): FieldSchema<FieldKind.Required, T, TCustomMetadata> {
 		return createFieldSchema(FieldKind.Required, t, props);
 	}
 

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

@@ -110,6 +110,11 @@ export interface SimpleFieldSchema {
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
 	readonly allowedTypes: ReadonlySet<string>;
+
+	/**
+	 * {@inheritDoc FieldSchemaMetadata.description}
+	 */
+	readonly description?: string | undefined;
 }
 
 /**

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

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { unreachableCase } from "@fluidframework/core-utils/internal";
+import { oob, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { ValueSchema } from "../../core/index.js";
-import { getOrCreate } from "../../util/index.js";
+import { getOrCreate, type Mutable } from "../../util/index.js";
 import type {
 	JsonArrayNodeSchema,
 	JsonFieldSchema,
@@ -37,15 +37,20 @@ import { NodeKind } from "../core/index.js";
 export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
 	const definitions = convertDefinitions(schema.definitions);
 
-	const anyOf: JsonSchemaRef[] = [];
+	const allowedTypes: JsonSchemaRef[] = [];
 	for (const allowedType of schema.allowedTypes) {
-		anyOf.push(createSchemaRef(allowedType));
+		allowedTypes.push(createSchemaRef(allowedType));
 	}
 
-	return {
-		$defs: definitions,
-		anyOf,
-	};
+	return allowedTypes.length === 1
+		? {
+				...(allowedTypes[0] ?? oob()),
+				$defs: definitions,
+			}
+		: {
+				$defs: definitions,
+				anyOf: allowedTypes,
+			};
 }
 
 function convertDefinitions(
@@ -90,12 +95,14 @@ function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSch
 	schema.allowedTypes.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
+
+	const items: JsonFieldSchema =
+		allowedTypes.length === 1 ? allowedTypes[0] ?? oob() : { anyOf: allowedTypes };
+
 	return {
 		type: "array",
 		_treeNodeSchemaKind: NodeKind.Array,
-		items: {
-			anyOf: allowedTypes,
-		},
+		items,
 	};
 }
 
@@ -130,14 +137,25 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 	const properties: Record<string, JsonFieldSchema> = {};
 	const required: string[] = [];
 	for (const [key, value] of Object.entries(schema.fields)) {
-		const anyOf: JsonSchemaRef[] = [];
+		const allowedTypes: JsonSchemaRef[] = [];
 		for (const allowedType of value.allowedTypes) {
-			anyOf.push(createSchemaRef(allowedType));
+			allowedTypes.push(createSchemaRef(allowedType));
+		}
+
+		const output: Mutable<JsonFieldSchema> =
+			allowedTypes.length === 1
+				? allowedTypes[0] ?? oob()
+				: {
+						anyOf: allowedTypes,
+					};
+
+		// Don't include "description" property at all if it's not present in the input.
+		if (value.description !== undefined) {
+			output.description = value.description;
 		}
 
-		properties[key] = {
-			anyOf,
-		};
+		properties[key] = output;
+
 		if (value.kind === FieldKind.Required) {
 			required.push(key);
 		}
@@ -160,9 +178,12 @@ function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 		type: "object",
 		_treeNodeSchemaKind: NodeKind.Map,
 		patternProperties: {
-			"^.*$": {
-				anyOf: allowedTypes,
-			},
+			"^.*$":
+				allowedTypes.length === 1
+					? allowedTypes[0] ?? oob()
+					: {
+							anyOf: allowedTypes,
+						},
 		},
 	};
 }

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

@@ -411,6 +411,11 @@ export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposab
 	 * Events for the tree.
 	 */
 	readonly events: Listenable<TreeViewEvents>;
+
+	/**
+	 * The view schema used by this TreeView.
+	 */
+	readonly schema: TSchema;
 }
 
 /**

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

@@ -19,7 +19,7 @@ import type {
 	SimpleTreeSchema,
 } from "./simpleSchema.js";
 import type { ValueSchema } from "../../core/index.js";
-import { getOrCreate } from "../../util/index.js";
+import { getOrCreate, type Mutable } from "../../util/index.js";
 import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 
@@ -126,11 +126,16 @@ function fieldSchemaToSimpleSchema(schema: FieldSchema): SimpleFieldSchema {
 	}
 
 	const allowedTypes = allowedTypesFromFieldSchema(schema);
-	const result = {
+	const result: Mutable<SimpleFieldSchema> = {
 		kind: schema.kind,
 		allowedTypes,
 	};
 
+	// Don't include "description" property at all if it's not present.
+	if (schema.metadata?.description !== undefined) {
+		result.description = schema.metadata.description;
+	}
+
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	(schema as any)[simpleFieldSchemaCacheSymbol] = result;
 

package/src/simple-tree/index.ts

@@ -84,6 +84,7 @@ export {
 	type FieldProps,
 	normalizeFieldSchema,
 	type ApplyKind,
+	type FieldSchemaMetadata,
 } from "./schemaTypes.js";
 export { getOrCreateInnerNode } from "./proxyBinding.js";
 export { toFlexSchema } from "./toFlexSchema.js";