@fluidframework/tree 2.81.1 → 2.83.0

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

@@ -138,4 +138,14 @@ export interface RunTransactionParams {
 	 * this client and ignored by all other clients.
 	 */
 	readonly preconditions?: readonly TransactionConstraintAlpha[];
+	/**
+	 * A label for this transaction that allows it to be correlated with later edits (e.g. for controlling undo/redo grouping).
+	 *
+	 * @remarks
+	 * This label is associated with the commit produced by this transaction, and is surfaced through the
+	 * `label` property of {@link ChangeMetadata} in the `commitApplied` or `changed` event.
+	 *
+	 * If there is a nested transaction, only the outermost transaction label will be used.
+	 */
+	readonly label?: unknown;
 }

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

@@ -6,8 +6,8 @@
 import type { IFluidLoadable, IDisposable, Listenable } from "@fluidframework/core-interfaces";
 
 import type {
-	CommitMetadata,
 	ChangeMetadata,
+	CommitMetadata,
 	RevertibleAlphaFactory,
 	RevertibleFactory,
 } from "../../core/index.js";
@@ -211,7 +211,7 @@ export interface TreeBranchAlpha extends TreeBranch {
 	fork(): TreeBranchAlpha;
 
 	/**
-	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
+	 * Run a synchronous 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
@@ -236,19 +236,20 @@ export interface TreeBranchAlpha extends TreeBranch {
 	 * 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:
+	 * This API can be called from within the transaction callback of another `runTransaction` or `runTransactionAsync` 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.
+	 * - If a label is provided in the params, only the label for the outermost transaction will be used. All other labels will be ignored.
 	 */
 	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.
+	 * Run a synchronous 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.
@@ -273,7 +274,7 @@ export interface TreeBranchAlpha extends TreeBranch {
 	 * 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:
+	 * This API can be called from within the transaction callback of another `runTransaction` or `runTransactionAsync` 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
@@ -285,6 +286,87 @@ export interface TreeBranchAlpha extends TreeBranch {
 		params?: RunTransactionParams,
 	): TransactionResult;
 
+	/**
+	 * Run an asynchronous 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 promise that resolves to 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 promise that resolves to 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 or failure value as returned by the transaction function.
+	 *
+	 * The promise will reject if the constraints are not met or something unexpected happens.
+	 *
+	 * @remarks
+	 * As with synchronous transactions, using an asynchronous transaction has the following consequences:
+	 * - All of the changes in the transaction are treated as a unit, therefore no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.
+	 * - 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.
+	 *
+	 * Unlike with synchronous transactions, using an asynchronous transaction has the following consequences:
+	 * - It is possible that other changes (either from this client by merging a branch or from a remote client) may be applied to the branch while this transaction is in progress.
+	 * These other changes will be not be reflected on the branch until after this transaction completes,
+	 * at which point the transaction changes will be applied after these other changes.
+	 *
+	 * 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 `runTransactionAsync` 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.
+	 */
+	runTransactionAsync<TSuccessValue, TFailureValue>(
+		transaction: () => Promise<TransactionCallbackStatus<TSuccessValue, TFailureValue>>,
+		params?: RunTransactionParams,
+	): Promise<TransactionResultExt<TSuccessValue, TFailureValue>>;
+	/**
+	 * Run an asynchronous 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 must return a promise that can resolve to any of 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 promise that resolves to a result object of {@link TransactionResult | TransactionResult} type. It includes a "success" flag indicating whether the
+	 * transaction was successful or not. The promise will reject if the constraints are not met or something unexpected happens.
+	 *
+	 * @remarks
+	 * As with synchronous transactions, using an asynchronous transaction has the following consequences:
+	 * - All of the changes in the transaction are treated as a unit, therefore no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.
+	 * - 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.
+	 *
+	 * Unlike with synchronous transactions, using an asynchronous transaction has the following consequences:
+	 * - It is possible that other changes (either from this client by merging a branch or from a remote client) may be applied to the branch while this transaction is in progress.
+	 * These other changes will be not be reflected on the branch until after this transaction completes,
+	 * at which point the transaction changes will be applied after these other changes.
+	 *
+	 * 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 `runTransactionAsync` 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.
+	 */
+	runTransactionAsync(
+		transaction: () => Promise<VoidTransactionCallbackStatus | void>,
+		params?: RunTransactionParams,
+	): Promise<TransactionResult>;
+
 	/**
 	 * Apply a serialized change to this branch.
 	 * @param change - the change to apply.
@@ -343,7 +425,7 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 	 * @remarks
 	 * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.
 	 * See {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ | schema-evolution} for more guidance on how to change schema while maintaining compatibility.
-	 * Use {@link checkSchemaCompatibilitySnapshots} to write tests to validate that this compatibility behaves as desired across schema changes.
+	 * Use {@link snapshotSchemaCompatibility} to write tests to validate that this compatibility behaves as desired across schema changes.
 	 */
 	readonly compatibility: SchemaCompatibilityStatus;
 
@@ -544,7 +626,7 @@ export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied">
 	 * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,
 	 * this commit is not revertible.
 	 */
-	commitApplied(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;
+	commitApplied(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;
 }
 
 /**

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

@@ -120,7 +120,7 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
  * Extensions to {@link (Tree:interface)} which are not yet stable.
  * @remarks
  * Use via the {@link (TreeBeta:variable)} singleton.
- * @system @sealed @beta
+ * @sealed @beta
  */
 export interface TreeBeta {
 	/**

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

@@ -650,7 +650,7 @@ export type TreeNodeFromImplicitAllowedTypes<
  * This type exists only to be linked from documentation to provide a single linkable place to document some details of
  * "Input" types and how they handle schema.
  *
- * When a schema is used to describe data which is an input into an API, the API is {@link https://en.wikipedia.org/wiki/Type_variance | contravariant}) over the schema.
+ * When a schema is used to describe data which is an input into an API, the API is {@link https://en.wikipedia.org/wiki/Type_variance | contravariant} over the schema.
  * (See also {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations | TypeScript Variance Annotations}).
  *
  * Since these schema are expressed using TypeScript types, it is possible for the user of the API to provide non-exact values of these types which has implications that depended on the variance.

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

@@ -575,15 +575,12 @@ export function isTreeNodeSchemaClass<
  * If a schema is both TreeNodeSchemaClass and TreeNodeSchemaNonClass, prefer TreeNodeSchemaClass since that includes subclasses properly.
  * @public
  */
-export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchemaClass<
-	string,
-	NodeKind,
-	infer TNode
->
-	? TNode
-	: T extends TreeNodeSchemaNonClass<string, NodeKind, infer TNode>
+export type NodeFromSchema<T extends TreeNodeSchema> =
+	T extends TreeNodeSchemaClass<string, NodeKind, infer TNode>
 		? TNode
-		: never;
+		: T extends TreeNodeSchemaNonClass<string, NodeKind, infer TNode>
+			? TNode
+			: never;
 
 /**
  * Data which can be used as a node to be inserted.

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

@@ -59,7 +59,22 @@ import type { Context } from "./context.js";
 import type { TreeNode } from "./treeNode.js";
 
 interface UnhydratedTreeSequenceFieldEditBuilder
-	extends SequenceFieldEditBuilder<FlexibleFieldContent, UnhydratedFlexTreeNode[]> {}
+	extends SequenceFieldEditBuilder<FlexibleFieldContent, UnhydratedFlexTreeNode[]> {
+	/**
+	 * Moves elements from a source position to a destination position.
+	 * Can move within the same field or from another unhydrated sequence field.
+	 * @param sourceIndex - The index of the first element to move.
+	 * @param count - The number of elements to move.
+	 * @param destIndex - The index at which to insert the moved elements.
+	 * @param source - The source field to move from (defaults to this field for within-field moves).
+	 */
+	move(
+		sourceIndex: number,
+		count: number,
+		destIndex: number,
+		source?: UnhydratedSequenceField,
+	): void;
+}
 
 type UnhydratedFlexTreeNodeEvents = Pick<
 	AnchorEvents,
@@ -543,6 +558,33 @@ export class UnhydratedSequenceField
 			});
 			return removed ?? fail(0xb4a /* Expected removed to be set by edit */);
 		},
+		move: (sourceIndex, count, destIndex, source?): void => {
+			const sourceField = source ?? this;
+			if (sourceField === this) {
+				// Within-field move: do both operations in a single edit to emit only one event
+				this.edit((mapTrees) => {
+					const removed = mapTrees.splice(sourceIndex, count);
+					// Adjust destination index if it comes after the source
+					const adjustedDest = destIndex > sourceIndex ? destIndex - count : destIndex;
+					if (removed.length < 1000) {
+						// For "smallish arrays" (`1000` is not empirically derived), the `splice` function is appropriate...
+						mapTrees.splice(adjustedDest, 0, ...removed);
+					} else {
+						// ...but we avoid using `splice` + spread for very large arrays since there is a limit on how many elements can be spread (too many will overflow the stack).
+						return [
+							...mapTrees.slice(0, adjustedDest),
+							...removed,
+							...mapTrees.slice(adjustedDest),
+						];
+					}
+				});
+			} else {
+				// Cross-field move: remove from source, insert into destination
+				// Each field emits one event (correct behavior for different fields)
+				const removed = sourceField.editor.remove(sourceIndex, count);
+				this.editor.insert(destIndex, removed);
+			}
+		},
 	} satisfies UnhydratedTreeSequenceFieldEditBuilder;
 
 	public at(index: number): FlexTreeUnknownUnboxed | undefined {

package/src/simple-tree/index.ts

@@ -197,9 +197,10 @@ export {
 	checkCompatibility,
 	eraseSchemaDetails,
 	eraseSchemaDetailsSubclassable,
-	checkSchemaCompatibilitySnapshots,
+	snapshotSchemaCompatibility,
 	type SnapshotFileSystem,
-	type SchemaCompatibilitySnapshotsOptions,
+	type SnapshotSchemaCompatibilityOptions,
+	createCustomizedFluidFrameworkScopedFactory,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,
@@ -266,6 +267,8 @@ export {
 	type RecordNodePojoEmulationSchema,
 	RecordNodeSchema,
 	type TreeRecordNode,
+	type ArrayPlaceAnchor,
+	createArrayInsertionAnchor,
 } from "./node-kinds/index.js";
 export {
 	unhydratedFlexTreeFromInsertable,

package/src/simple-tree/leafNodeSchema.ts

@@ -7,7 +7,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { type TreeValue, ValueSchema } from "../core/index.js";
+import { type FieldKey, type TreeValue, ValueSchema } from "../core/index.js";
 import {
 	type FlexTreeNode,
 	isFlexTreeNode,
@@ -28,6 +28,7 @@ import {
 	type TreeNodeSchemaInitializedData,
 	CompatibilityLevel,
 	type FlexContent,
+	type UnhydratedFlexTreeField,
 } from "./core/index.js";
 import { getTreeNodeSchemaInitializedData } from "./createContext.js";
 import type { SimpleLeafNodeSchema } from "./simpleSchema.js";
@@ -185,7 +186,7 @@ export function leafToFlexContent(
 			value: mappedValue,
 			type: brand(mappedSchema.identifier),
 		},
-		new Map(),
+		new Map<FieldKey, UnhydratedFlexTreeField>(),
 	];
 
 	return result;

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

@@ -52,7 +52,6 @@ import {
 	createTreeNodeSchemaPrivateData,
 	type FlexContent,
 	type TreeNodeSchemaPrivateData,
-	withBufferedTreeEvents,
 	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import {
@@ -128,6 +127,19 @@ export interface TreeArrayNode<
 	 */
 	insertAtEnd(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
 
+	/**
+	 * Inserts new item(s) at the end of the array.
+	 *
+	 * @remarks
+	 * The order of the inserted items relative to other concurrently inserted items at the same location is only partially specified:
+	 * Concurrently inserting `[A, B]` and `[X, Y]` at the same location may yield
+	 * either `[A, B, X, Y]` or `[X, Y, A, B]`, regardless of the order in which those edits are sequenced.
+	 * No other interleavings are possible. (e.g. `[A, X, B, Y]` is not possible.)
+	 *
+	 * @param value - The content to insert.
+	 */
+	push(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
+
 	/**
 	 * Removes the item at the specified location.
 	 * @param index - The index at which to remove the item.
@@ -966,6 +978,9 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	public insertAtEnd(...value: Insertable<T>): void {
 		this.insertAt(this.length, ...value);
 	}
+	public push(...value: Insertable<T>): void {
+		this.insertAt(this.length, ...value);
+	}
 	public removeAt(index: number): void {
 		const field = getSequenceField(this);
 		validateIndex(index, field, "TreeArrayNode.removeAt");
@@ -1105,24 +1120,19 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 				);
 			}
 
-			// We implement move here via subsequent `remove` and `insert`.
-			// This is strictly an implementation detail and should not be observable by the user.
-			// TODO:AB#47457: Implement proper move support for unhydrated trees.
-			// As a temporary mitigation, we will pause tree events until both edits have been completed.
-			// That way, users will only see a single change event for the array instead of 2.
-			withBufferedTreeEvents(() => {
-				if (sourceField !== destinationField || destinationGap < sourceStart) {
-					destinationField.editor.insert(
-						destinationGap,
-						sourceField.editor.remove(sourceStart, movedCount),
-					);
-				} else if (destinationGap > sourceStart + movedCount) {
-					destinationField.editor.insert(
-						destinationGap - movedCount,
-						sourceField.editor.remove(sourceStart, movedCount),
-					);
-				}
-			});
+			assert(
+				destinationField instanceof UnhydratedSequenceField,
+				0xcd5 /* destinationField should be unhydrated since we're in the else branch of isHydrated() check */,
+			);
+
+			// Use native move which handles the operation atomically for within-field moves
+			// to ensure only a single event is emitted per affected field.
+			destinationField.editor.move(
+				sourceStart,
+				movedCount,
+				destinationGap,
+				sourceField === destinationField ? undefined : sourceField,
+			);
 		}
 	}
 
@@ -1389,3 +1399,73 @@ function shallowCompatibilityTest(
 
 	return CompatibilityLevel.None;
 }
+
+/**
+ * A location in a {@link (TreeArrayNode:interface)}.
+ * @remarks
+ * Tracks a location even as the array is mutated.
+ * How this is adjusted for edits depends on the specific anchor being used.
+ * See {@link createArrayInsertionAnchor} for one way to create such an anchor.
+ * @privateRemarks
+ * This being sealed is not important for its current behaviors as nothing downcasts this,
+ * however it is possible we might want to add additional members in the future:
+ * sealing this ensures that such additions are a non-breaking change.
+ * Things we might want to add include status (for example if its deleted) or events (for example to notify when its index changes).
+ * Some specific anchors might even want to add additional method members for things like confidence
+ * (so we can indicate when the anchor goes from being truly robust to a heuristic guess due to an edit).
+ * @alpha
+ * @sealed
+ */
+export interface ArrayPlaceAnchor {
+	/**
+	 * The current index within the array that this anchor refers to.
+	 * @remarks
+	 * This value is updated as the array is edited in a way that depends on the specific anchor implementation.
+	 * This index may take on a value from 0 to the length of the array (inclusive).
+	 * If used as the index to insert content into the array, this means it can point to any location in the array,
+	 * including just after the last child.
+	 */
+	get index(): number;
+}
+
+/**
+ * Create an {@link ArrayPlaceAnchor} tracking an insertion point in the array which is currently at the provided index.
+ *
+ * @param node - The array node to anchor into.
+ * @param currentIndex - The current index of the place to track.
+ * @remarks
+ * This anchor will track the logical position in the array across changes.
+ * As long as the subsection of the array surrounding the anchor point is not edited,
+ * this anchor will move with them, keeping its relative position to those children fixed.
+ * How exactly it behaves when the adjacent portion of the array is modified is subject to change,
+ * but this will always report a valid index to insert content at (which can be the index after the last item in the array).
+ *
+ * This is intended to track a location that might be used for an insertion point (for example in a text editor): future changes to its details should
+ * make it behave better for such uses.
+ *
+ * The current implementation is known to behave particularly poorly if the child which was at the original anchor point's index is removed
+ * (jumps to the end of the array): this behavior is subject to change.
+ * @privateRemarks
+ * When stabilized, this should probably become a method on {@link (TreeArrayNode:interface)}.
+ * Future versions of this should use rebaser / changeset logic to do a better job of tracking a location across removals or reinsertion.
+ * How this would work, especially for unhydrated nodes is not yet clear.
+ * @alpha
+ */
+export function createArrayInsertionAnchor(
+	node: TreeArrayNode,
+	currentIndex: number,
+): ArrayPlaceAnchor {
+	const field = getInnerNode(node).getBoxed(EmptyKey);
+	const child = field.boxedAt(currentIndex);
+	return {
+		get index() {
+			if (child === undefined) {
+				return field.length;
+			}
+			if (child.parentField.parent !== field) {
+				return field.length;
+			}
+			return child.parentField.index;
+		},
+	};
+}

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

@@ -9,6 +9,8 @@ export {
 	IterableTreeArrayContent,
 	TreeArrayNode,
 	type ReadonlyArrayNode,
+	type ArrayPlaceAnchor,
+	createArrayInsertionAnchor,
 } from "./arrayNode.js";
 export {
 	type ArrayNodeCustomizableSchema,

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

@@ -13,6 +13,8 @@ export {
 	IterableTreeArrayContent,
 	TreeArrayNode,
 	type ReadonlyArrayNode,
+	type ArrayPlaceAnchor,
+	createArrayInsertionAnchor,
 } from "./array/index.js";
 
 export {

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

@@ -189,24 +189,25 @@ export type FieldHasDefault<T extends ImplicitFieldSchema> = [T] extends [
  */
 export type InsertableObjectFromSchemaRecord<
 	T extends RestrictiveStringRecord<ImplicitFieldSchema>,
-> = RestrictiveStringRecord<ImplicitFieldSchema> extends T
-	? { arbitraryKey: "arbitraryValue" } extends T
-		? // {} case
-			Record<string, never>
-		: // RestrictiveStringRecord<ImplicitFieldSchema> case
-			never
-	: FlattenKeys<
-			{
-				readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
-					T[Property & string]
-				>;
-			} & {
-				// Field does not have a known default, make it required:
-				readonly [Property in keyof T as FieldHasDefault<T[Property & string]> extends false
-					? Property
-					: never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
-			}
-		>;
+> =
+	RestrictiveStringRecord<ImplicitFieldSchema> extends T
+		? { arbitraryKey: "arbitraryValue" } extends T
+			? // {} case
+				Record<string, never>
+			: // RestrictiveStringRecord<ImplicitFieldSchema> case
+				never
+		: FlattenKeys<
+				{
+					readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
+						T[Property & string]
+					>;
+				} & {
+					// Field does not have a known default, make it required:
+					readonly [Property in keyof T as FieldHasDefault<T[Property & string]> extends false
+						? Property
+						: never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
+				}
+			>;
 
 /**
  * Maps from simple field keys ("property" keys) to information about the field.

package/src/simple-tree/unhydratedFlexTreeFromInsertable.ts

@@ -4,7 +4,7 @@
  */
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import { assert, fail } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { filterIterable, hasSingle, oneFromIterable } from "../util/index.js";
@@ -58,7 +58,9 @@ export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent |
 	if (data === undefined) {
 		// TODO: this code-path should support defaults
 		if (normalizedFieldSchema.kind !== FieldKind.Optional) {
-			throw new UsageError("Got undefined for non-optional field.");
+			throw new UsageError(
+				`Got undefined for non-optional field expecting one of ${quotedAllowedTypesWithNames(normalizedFieldSchema.allowedTypeSet)}`,
+			);
 		}
 		return undefined as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
 	}
@@ -71,6 +73,47 @@ export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent |
 	return flexTree as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
 }
 
+/**
+ * Throw a usage error with a helpful message about `schema` not being in `allowedTypes` for insertable content.
+ */
+function allowedTypesInsertableSchemaError(
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
+	schema: TreeNodeSchema,
+): never {
+	debugAssert(
+		() =>
+			!allowedTypes.has(schema) ||
+			"This function should only be called if the schema is not in the allowed types.",
+	);
+	const map = new Map([...allowedTypes].map((s) => [s.identifier, s]));
+	const expected = map.get(schema.identifier);
+	if (expected !== undefined) {
+		throw new UsageError(
+			`A node with schema ${quotedSchemaIdentifierWithName(schema)} was provided where a node with that identifier is allowed, but the actual schema required (${quotedSchemaIdentifierWithName(expected)}) is not the same schema object.
+TreeNodeSchema have significant object identity and thus the exact same object must be used as the schema when defining what nodes are allowed and when constructing the node to use.`,
+		);
+	}
+	throw new UsageError(
+		`Expected insertable for one of ${quotedAllowedTypesWithNames(allowedTypes)}. Got node with schema ${quotedSchemaIdentifierWithName(schema)}.
+Nodes are valid insertable objects, but only if their schema are in the allowed list.`,
+	);
+}
+
+/**
+ * Gets a description of a schema for use in error messages.
+ */
+function quotedSchemaIdentifierWithName(schema: TreeNodeSchema): string {
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+	return `${JSON.stringify(schema.identifier)} (name: ${JSON.stringify((schema as Function).name)})`;
+}
+
+/**
+ * Gets a description of an allowedTypes for use in error messages.
+ */
+function quotedAllowedTypesWithNames(allowedTypes: Iterable<TreeNodeSchema>): string {
+	return `[${[...allowedTypes].map(quotedSchemaIdentifierWithName).join(", ")}]`;
+}
+
 /**
  * Copy content from `data` into a UnhydratedFlexTreeNode.
  */
@@ -83,10 +126,12 @@ export function unhydratedFlexTreeFromInsertableNode(
 		const inner = kernel.getInnerNodeIfUnhydrated();
 		if (inner === undefined) {
 			// The node is already hydrated, meaning that it already got inserted into the tree previously
-			throw new UsageError("A node may not be inserted into the tree more than once");
+			throw new UsageError(
+				`A node with schema ${quotedSchemaIdentifierWithName(kernel.schema)} was inserted into the tree more than once. This is not supported.`,
+			);
 		} else {
 			if (!allowedTypes.has(kernel.schema)) {
-				throw new UsageError("Invalid schema for this context.");
+				allowedTypesInsertableSchemaError(allowedTypes, kernel.schema);
 			}
 			return inner;
 		}
@@ -112,17 +157,13 @@ function getType(
 	const possibleTypes = getPossibleTypes(allowedTypes, data);
 	if (possibleTypes.length === 0) {
 		throw new UsageError(
-			`The provided data is incompatible with all of the types allowed by the schema. The set of allowed types is: ${JSON.stringify(
-				[...allowedTypes].map((schema) => schema.identifier),
-			)}.`,
+			`The provided data is incompatible with all of the types allowed by the schema. The set of allowed types is: ${quotedAllowedTypesWithNames(allowedTypes)}.`,
 		);
 	}
 	if (!hasSingle(possibleTypes)) {
 		throw new UsageError(
 			`The provided data is compatible with more than one type allowed by the schema.
-The set of possible types is ${JSON.stringify([
-				...possibleTypes.map((schema) => schema.identifier),
-			])}.
+The set of possible types is ${quotedAllowedTypesWithNames(possibleTypes)}.
 Explicitly construct an unhydrated node of the desired type to disambiguate.
 For class-based schema, this can be done by replacing an expression like "{foo: 1}" with "new MySchema({foo: 1})".`,
 		);