@fluidframework/tree 2.74.0 → 2.81.0-374083

package/src/simple-tree/index.ts

@@ -160,7 +160,9 @@ export {
 	type SchemaStatics,
 	type ITreeAlpha,
 	type TransactionConstraint,
+	type TransactionConstraintAlpha,
 	type NodeInDocumentConstraint,
+	type NoChangeConstraint,
 	type RunTransactionParams,
 	type VoidTransactionCallbackStatus,
 	type TransactionCallbackStatus,
@@ -195,6 +197,9 @@ export {
 	checkCompatibility,
 	eraseSchemaDetails,
 	eraseSchemaDetailsSubclassable,
+	checkSchemaCompatibilitySnapshots,
+	type SnapshotFileSystem,
+	type SchemaCompatibilitySnapshotsOptions,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,
@@ -263,7 +268,7 @@ export {
 	type TreeRecordNode,
 } from "./node-kinds/index.js";
 export {
-	unhydratedFlexTreeFromInsertable,
+	flexTreeFromInsertable as unhydratedFlexTreeFromInsertable,
 	type InsertableContent,
 	type FactoryContent,
 	type FactoryContentObject,
@@ -271,6 +276,7 @@ export {
 export {
 	prepareForInsertion,
 	prepareForInsertionContextless,
+	type PreparedContent,
 } from "./prepareForInsertion.js";
 export {
 	toStoredSchema,

package/src/simple-tree/leafNodeSchema.ts

@@ -207,7 +207,9 @@ function mapValueWithFallbacks(
 				// Our serialized data format does not support -0.
 				// Map such input to +0.
 				return 0;
-			} else if (!Number.isFinite(value)) {
+			} else if (Number.isFinite(value)) {
+				return value;
+			} else {
 				// Our serialized data format does not support NaN nor +/-∞.
 				// If the schema supports `null`, fall back to that. Otherwise, throw.
 				// This is intended to match JSON's behavior for such values.
@@ -216,22 +218,23 @@ function mapValueWithFallbacks(
 				} else {
 					throw new UsageError(`Received unsupported numeric value: ${value}.`);
 				}
-			} else {
-				return value;
 			}
 		}
 		case "string":
 		// TODO:
 		// This should detect invalid strings. Something like @stdlib/regexp-utf16-unpaired-surrogate could be used to do this.
 		// See SchemaFactory.string for details.
-		case "boolean":
+		case "boolean": {
 			return value;
+		}
 		case "object": {
 			if (value === null || isFluidHandle(value)) {
 				return value;
 			}
 		}
-		default:
+		// fallthrough
+		default: {
 			throw new UsageError(`Received unsupported leaf value: ${value}.`);
+		}
 	}
 }

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -50,9 +50,9 @@ import {
 } from "../../core/index.js";
 import {
 	type FactoryContent,
+	flexTreeFromInsertableNode,
 	type InsertableContent,
 	unhydratedFlexTreeFromInsertable,
-	unhydratedFlexTreeFromInsertableNode,
 } from "../../unhydratedFlexTreeFromInsertable.js";
 import { prepareArrayContentForInsertion } from "../../prepareForInsertion.js";
 import {
@@ -543,11 +543,11 @@ const TreeNodeWithArrayFeatures = (() => {
 	> extends TreeNodeValid<Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>> {}
 
 	// Modify TreeNodeWithArrayFeaturesUntyped to add the members from Array.prototype
-	arrayPrototypeKeys.forEach((key) => {
+	for (const key of arrayPrototypeKeys) {
 		Object.defineProperty(TreeNodeWithArrayFeaturesUntyped.prototype, key, {
 			value: Array.prototype[key],
 		});
-	});
+	}
 
 	return TreeNodeWithArrayFeaturesUntyped as unknown as typeof NodeWithArrayFeatures;
 })();
@@ -888,7 +888,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		)[];
 
 		const contentArray = content.flatMap((c): InsertableContent[] =>
-			c instanceof IterableTreeArrayContent ? Array.from(c) : [c],
+			c instanceof IterableTreeArrayContent ? [...c] : [c],
 		);
 
 		const kernel = getKernel(this);
@@ -918,7 +918,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 
 	public toJSON(): unknown {
 		// This override causes the class instance to `JSON.stringify` as `[a, b]` rather than `{0: a, 1: b}`.
-		return Array.from(this as unknown as TreeArrayNode);
+		return [...(this as unknown as TreeArrayNode)];
 	}
 
 	// Instances of this class are used as the dispatch object for the proxy,
@@ -956,8 +956,10 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	public insertAt(index: number, ...value: Insertable<T>): void {
 		const field = getSequenceField(this);
 		validateIndex(index, field, "TreeArrayNode.insertAt", true);
-		const content = this.#mapTreesFromFieldData(value);
-		field.editor.insert(index, content);
+		field.context.runInTransaction(() => {
+			const content = this.#mapTreesFromFieldData(value);
+			field.editor.attach(index, content);
+		});
 	}
 	public insertAtStart(...value: Insertable<T>): void {
 		this.insertAt(0, ...value);
@@ -972,14 +974,14 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	}
 	public removeRange(start?: number, end?: number): void {
 		const field = getSequenceField(this);
-		const { length } = field;
+		const { length, editor } = field;
 		const removeStart = start ?? 0;
 		validateIndex(removeStart, field, "TreeArrayNode.removeRange", true);
 
 		const removeEnd = Math.min(length, end ?? length);
 		validateIndexRange(removeStart, removeEnd, field, "TreeArrayNode.removeRange");
 
-		field.editor.remove(removeStart, removeEnd - removeStart);
+		editor.remove(removeStart, removeEnd - removeStart);
 	}
 	public moveToStart(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
@@ -1044,7 +1046,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			kernel.context.flexContext.schema.nodeSchema.get(brand(kernel.schema.identifier)) ??
 			fail(0xc16 /* missing schema for array node */)
 		).getFieldSchema(EmptyKey).types;
-		const sourceField = source !== undefined ? getSequenceField(source) : destinationField;
+		const sourceField = source === undefined ? destinationField : getSequenceField(source);
 
 		validateIndex(destinationGap, destinationField, "TreeArrayNode.moveRangeToIndex", true);
 		validateIndexRange(
@@ -1074,7 +1076,24 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		}
 
 		const movedCount = sourceEnd - sourceStart;
-		if (!destinationField.context.isHydrated()) {
+		if (destinationField.context.isHydrated()) {
+			if (!sourceField.context.isHydrated()) {
+				throw new UsageError(
+					"Cannot move elements from an unhydrated array to a hydrated array.",
+				);
+			}
+			if (sourceField.context !== destinationField.context) {
+				throw new UsageError("Cannot move elements between two different TreeViews.");
+			}
+
+			destinationField.context.checkout.editor.move(
+				sourceField.getFieldPath(),
+				sourceStart,
+				movedCount,
+				destinationField.getFieldPath(),
+				destinationGap,
+			);
+		} else {
 			if (!(sourceField instanceof UnhydratedSequenceField)) {
 				throw new UsageError(
 					"Cannot move elements from a hydrated array to an unhydrated array.",
@@ -1105,23 +1124,6 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 					);
 				}
 			});
-		} else {
-			if (!sourceField.context.isHydrated()) {
-				throw new UsageError(
-					"Cannot move elements from an unhydrated array to a hydrated array.",
-				);
-			}
-			if (sourceField.context !== destinationField.context) {
-				throw new UsageError("Cannot move elements between two different TreeViews.");
-			}
-
-			destinationField.context.checkout.editor.move(
-				sourceField.getFieldPath(),
-				sourceStart,
-				movedCount,
-				destinationField.getFieldPath(),
-				destinationGap,
-			);
 		}
 	}
 
@@ -1308,7 +1310,7 @@ export function arraySchema<
 function arrayChildToFlexTree(
 	child: InsertableContent,
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
-): UnhydratedFlexTreeNode {
+): FlexTreeNode {
 	// We do not support undefined sequence entries.
 	// If we encounter an undefined entry, use null instead if supported by the schema, otherwise throw.
 	let childWithFallback = child;
@@ -1319,7 +1321,7 @@ function arrayChildToFlexTree(
 			throw new TypeError(`Received unsupported array entry value: ${child}.`);
 		}
 	}
-	return unhydratedFlexTreeFromInsertableNode(childWithFallback, allowedTypes);
+	return flexTreeFromInsertableNode(childWithFallback, allowedTypes);
 }
 
 /**

package/src/simple-tree/node-kinds/common.ts

@@ -17,7 +17,7 @@ import {
 } from "../core/index.js";
 import { getUnhydratedContext } from "../createContext.js";
 import {
-	unhydratedFlexTreeFromInsertableNode,
+	flexTreeFromInsertableNode,
 	type InsertableContent,
 } from "../unhydratedFlexTreeFromInsertable.js";
 import type { MapNodeSchema } from "./map/index.js";
@@ -44,10 +44,7 @@ export function recordLikeDataToFlexContent(
 
 		// Omit undefined values - an entry with an undefined value is equivalent to one that has been removed or omitted
 		if (value !== undefined) {
-			const child = unhydratedFlexTreeFromInsertableNode(
-				value,
-				allowedChildTypes.evaluateSet(),
-			);
+			const child = flexTreeFromInsertableNode(value, allowedChildTypes.evaluateSet());
 			const field = createField(context, FieldKinds.optional.identifier, brand(key), [child]);
 			transformedFields.set(brand(key), field);
 		}

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -11,7 +11,7 @@ import {
 	type FlexibleNodeContent,
 	type FlexTreeNode,
 	type FlexTreeOptionalField,
-	type OptionalFieldEditBuilder,
+	type OptionalFieldEditor,
 } from "../../../feature-libraries/index.js";
 import { tryGetTreeNodeForField } from "../../getTreeNodeForField.js";
 import { createFieldSchema, FieldKind } from "../../fieldSchema.js";
@@ -177,14 +177,14 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 		return getInnerNode(this);
 	}
 
-	private editor(key: string): OptionalFieldEditBuilder<FlexibleNodeContent> {
+	private editor(key: string): OptionalFieldEditor<FlexibleNodeContent, FlexTreeNode> {
 		const field = this.innerNode.getBoxed(brand(key)) as FlexTreeOptionalField;
 		return field.editor;
 	}
 
 	public delete(key: string): void {
 		const field = this.innerNode.getBoxed(brand(key));
-		this.editor(key).set(undefined, field.length === 0);
+		this.editor(key).clear(field.length === 0);
 	}
 	public *entries(): IterableIterator<[string, TreeNodeFromImplicitAllowedTypes<T>]> {
 		const node = this.innerNode;
@@ -227,7 +227,7 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 
 		const field = node.getBoxed(brand(key));
 
-		this.editor(key).set(mapTree, field.length === 0);
+		this.editor(key).attach(mapTree, field.length === 0);
 		return this;
 	}
 	public get size(): number {

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -81,7 +81,7 @@ import {
 import type { SimpleObjectFieldSchema } from "../../simpleSchema.js";
 import {
 	unhydratedFlexTreeFromInsertable,
-	unhydratedFlexTreeFromInsertableNode,
+	flexTreeFromInsertableNode,
 	type FactoryContent,
 	type FactoryContentObject,
 	type InsertableContent,
@@ -353,29 +353,32 @@ export function setField(
 	value: InsertableContent | undefined,
 	destinationSchema: TreeFieldStoredSchema,
 ): void {
-	const mapTree = prepareForInsertion(
-		value,
-		simpleFieldSchema,
-		field.context,
-		destinationSchema,
-	);
+	field.context.runInTransaction(() => {
+		const mapTree = prepareForInsertion(
+			value,
+			simpleFieldSchema,
+			field.context,
+			destinationSchema,
+		);
 
-	switch (field.schema) {
-		case FieldKinds.required.identifier: {
-			assert(mapTree !== undefined, 0xa04 /* Cannot set a required field to undefined */);
-			const typedField = field as FlexTreeRequiredField;
-			typedField.editor.set(mapTree);
-			break;
-		}
-		case FieldKinds.optional.identifier: {
-			const typedField = field as FlexTreeOptionalField;
-			typedField.editor.set(mapTree, typedField.length === 0);
-			break;
-		}
+		switch (field.schema) {
+			case FieldKinds.required.identifier: {
+				assert(mapTree !== undefined, 0xa04 /* Cannot set a required field to undefined */);
+				const typedField = field as FlexTreeRequiredField;
+				typedField.editor.attach(mapTree);
+				break;
+			}
+			case FieldKinds.optional.identifier: {
+				const typedField = field as FlexTreeOptionalField;
+				typedField.editor.attach(mapTree, typedField.length === 0);
+				break;
+			}
 
-		default:
-			fail(0xade /* invalid FieldKind */);
-	}
+			default: {
+				fail(0xade /* invalid FieldKind */);
+			}
+		}
+	});
 }
 
 /**
@@ -661,7 +664,7 @@ function objectToFlexContent(
 	for (const [key, fieldInfo] of schema.flexKeyMap) {
 		const value = getFieldProperty(data, key);
 
-		let children: UnhydratedFlexTreeNode[] | ContextualFieldProvider;
+		let children: FlexTreeNode[] | ContextualFieldProvider;
 		if (value === undefined) {
 			const defaultProvider =
 				fieldInfo.schema.props?.defaultProvider ??
@@ -669,9 +672,7 @@ function objectToFlexContent(
 			const fieldProvider = extractFieldProvider(defaultProvider);
 			children = isConstant(fieldProvider) ? fieldProvider() : fieldProvider;
 		} else {
-			children = [
-				unhydratedFlexTreeFromInsertableNode(value, fieldInfo.schema.allowedTypeSet),
-			];
+			children = [flexTreeFromInsertableNode(value, fieldInfo.schema.allowedTypeSet)];
 		}
 
 		const kind =
@@ -709,10 +710,8 @@ function shallowCompatibilityTest(
 
 	// If the schema has a required key which is not present in the input object, reject it.
 	for (const [fieldKey, fieldSchema] of schema.fields) {
-		if (fieldSchema.requiresValue) {
-			if (getFieldProperty(data, fieldKey) === undefined) {
-				return CompatibilityLevel.None;
-			}
+		if (fieldSchema.requiresValue && getFieldProperty(data, fieldKey) === undefined) {
+			return CompatibilityLevel.None;
 		}
 	}
 

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -99,9 +99,8 @@ function createRecordNodeProxy(
 						}
 						break;
 					}
-					default: {
-						// No-op
-					}
+					default:
+					// No-op
 				}
 			}
 
@@ -128,15 +127,16 @@ function createRecordNodeProxy(
 				innerSchema instanceof MapNodeStoredSchema,
 				0xc1a /* Expected MapNodeStoredSchema */,
 			);
-
-			const mapTree = prepareForInsertion(
-				value,
-				createFieldSchema(FieldKind.Optional, kernel.schema.info as ImplicitAllowedTypes),
-				innerNode.context,
-				innerSchema.mapFields,
-			);
-
-			field.editor.set(mapTree, field.length === 0);
+			field.context.runInTransaction(() => {
+				const mapTree = prepareForInsertion(
+					value,
+					createFieldSchema(FieldKind.Optional, kernel.schema.info as ImplicitAllowedTypes),
+					innerNode.context,
+					innerSchema.mapFields,
+				);
+
+				field.editor.attach(mapTree, field.length === 0);
+			});
 			return true;
 		},
 		has: (target, key): boolean => {