@fluidframework/tree 2.82.0 → 2.90.0-378676

package/src/core/tree/index.ts

@@ -30,17 +30,17 @@ export {
 	CursorMarker,
 	isCursor,
 } from "./cursor.js";
-export type {
-	ProtoNodes,
-	Root as DeltaRoot,
-	Mark as DeltaMark,
-	DetachedNodeId as DeltaDetachedNodeId,
-	FieldMap as DeltaFieldMap,
-	DetachedNodeChanges as DeltaDetachedNodeChanges,
-	DetachedNodeBuild as DeltaDetachedNodeBuild,
-	DetachedNodeDestruction as DeltaDetachedNodeDestruction,
-	DetachedNodeRename as DeltaDetachedNodeRename,
-	FieldChanges as DeltaFieldChanges,
+export {
+	type ProtoNodes,
+	type Root as DeltaRoot,
+	type Mark as DeltaMark,
+	type DetachedNodeId as DeltaDetachedNodeId,
+	type FieldMap as DeltaFieldMap,
+	type DetachedNodeChanges as DeltaDetachedNodeChanges,
+	type DetachedNodeBuild as DeltaDetachedNodeBuild,
+	type DetachedNodeDestruction as DeltaDetachedNodeDestruction,
+	type DetachedNodeRename as DeltaDetachedNodeRename,
+	type FieldChanges as DeltaFieldChanges,
 } from "./delta.js";
 export { type MapTree, type ExclusiveMapTree, deepCopyMapTree } from "./mapTree.js";
 export {
@@ -59,8 +59,9 @@ export {
 	type NodeIndex,
 	compareUpPaths,
 	compareFieldUpPaths,
-	isDetachedUpPathRoot as isDetachedUpPath,
+	isDetachedUpPathRoot,
 	getDetachedFieldContainingPath,
+	getDetachedFieldContainingFieldPath,
 	type UpPathDefault,
 } from "./pathTree.js";
 export {

package/src/core/tree/pathTree.ts

@@ -126,7 +126,7 @@ export interface FieldUpPath<TUpPath = UpPath> {
  */
 export function isDetachedUpPathRoot<T>(
 	path: UpPath<T> | NormalizedUpPath,
-): path is NormalizedUpPathRoot {
+): path is NormalizedUpPathRoot & { readonly detachedNodeId: DetachedNodeId } {
 	return (path as NormalizedUpPathRoot).detachedNodeId !== undefined;
 }
 
@@ -219,8 +219,8 @@ export function clonePath(path: UpPath | undefined): UpPath | undefined {
  * Gets the elements of the given `path`, ordered from root-most to child-most.
  * @remarks These elements are unchanged and therefore still point "up".
  */
-export function topDownPath(path: UpPath | undefined): UpPath[] {
-	const out: UpPath[] = [];
+export function topDownPath<T extends UpPath<T>>(path: T | undefined): T[] {
+	const out: T[] = [];
 	let curr = path;
 	while (curr !== undefined) {
 		out.push(curr);
@@ -262,7 +262,7 @@ export function compareFieldUpPaths(a: FieldUpPath, b: FieldUpPath): boolean {
 }
 
 /**
- * Checks whether or not a given path is parented under the root field.
+ * Returns the field key for the root field.
  * @param path - the path you want to check.
  * @returns the {@link DetachedField} which contains the path.
  */
@@ -277,3 +277,15 @@ export function getDetachedFieldContainingPath(path: UpPath): DetachedField {
 	}
 	return keyAsDetachedField(path.parentField);
 }
+
+/**
+ * Returns the field key for the root field.
+ * @param path - the path you want to check.
+ * @returns the {@link DetachedField} which contains the path.
+ */
+export function getDetachedFieldContainingFieldPath(path: FieldUpPath): DetachedField {
+	if (path.parent === undefined) {
+		return keyAsDetachedField(path.field);
+	}
+	return getDetachedFieldContainingPath(path.parent);
+}

package/src/core/tree/visitDelta.ts

@@ -166,7 +166,9 @@ function transferRoots(
 	refreshers: NestedMap<Major, Minor, ITreeCursorSynchronous>,
 	revision?: RevisionTag,
 ): void {
-	type AtomizedNodeRename = Omit<Delta.DetachedNodeRename, "count">;
+	type AtomizedNodeRename = Omit<Delta.DetachedNodeRename, "count"> & {
+		isAttachable?: boolean;
+	};
 	let nextBatch = rootTransfers.flatMap(({ oldId, newId, count }) => {
 		const atomized: AtomizedNodeRename[] = [];
 		// It's possible for a detached node to be revived transiently such that it ends up back in the same detached field.
@@ -176,7 +178,12 @@ function transferRoots(
 		// This if statement prevents that from happening.
 		if (!areDetachedNodeIdsEqual(oldId, newId)) {
 			for (let i = 0; i < count; i += 1) {
-				atomized.push({ oldId: offsetDetachId(oldId, i), newId: offsetDetachId(newId, i) });
+				const source = detachedFieldIndex.isAttachable(offsetDetachId(oldId, i));
+				atomized.push({
+					oldId: offsetDetachId(oldId, i),
+					newId: offsetDetachId(newId, i),
+					isAttachable: source,
+				});
 			}
 		}
 		return atomized;
@@ -184,30 +191,29 @@ function transferRoots(
 	while (nextBatch.length > 0) {
 		const delayed: AtomizedNodeRename[] = [];
 		const priorSize = nextBatch.length;
-		for (const { oldId, newId } of nextBatch) {
+		for (const { oldId, newId, isAttachable } of nextBatch) {
 			let oldRootId = detachedFieldIndex.tryGetEntry(oldId);
 			if (oldRootId === undefined) {
 				const tree = tryGetFromNestedMap(refreshers, oldId.major, oldId.minor);
 				if (tree !== undefined) {
-					buildTrees(oldId, [tree], detachedFieldIndex, revision, visitor);
+					buildTrees(oldId, [tree], detachedFieldIndex, revision, false, visitor);
 					oldRootId = detachedFieldIndex.getEntry(oldId);
 				}
 			}
 			if (oldRootId === undefined) {
 				// The source field is not populated.
 				// This can happen when another rename needs to be performed first.
-				delayed.push({ oldId, newId });
+				delayed.push({ oldId, newId, isAttachable });
 				continue;
 			}
 			let newRootId = detachedFieldIndex.tryGetEntry(newId);
 			if (newRootId !== undefined) {
 				// The destination field is already occupied.
 				// This can happen when another rename needs to be performed first.
-				delayed.push({ oldId, newId });
+				delayed.push({ oldId, newId, isAttachable });
 				continue;
 			}
-			// eslint-disable-next-line @typescript-eslint/strict-boolean-expressions -- intentional behavior
-			newRootId = detachedFieldIndex.createEntry(newId, revision);
+			newRootId = detachedFieldIndex.createEntry(newId, revision, isAttachable);
 			const fields = mapToUpdate.get(oldRootId);
 			if (fields !== undefined) {
 				mapToUpdate.delete(oldRootId);
@@ -413,7 +419,11 @@ function detachPass(
 		if (mark.detach !== undefined) {
 			for (let i = 0; i < mark.count; i += 1) {
 				const id = offsetDetachId(mark.detach, i);
-				const root = config.detachedFieldIndex.createEntry(id, config.latestRevision);
+				const root = config.detachedFieldIndex.createEntry(
+					id,
+					config.latestRevision,
+					fieldChanges.allowReattach,
+				);
 				if (mark.fields !== undefined) {
 					config.attachPassRoots.set(root, mark.fields);
 				}
@@ -432,13 +442,14 @@ function buildTrees(
 	trees: readonly ITreeCursorSynchronous[],
 	detachedFieldIndex: DetachedFieldIndex,
 	latestRevision: RevisionTag | undefined,
+	isAttachable: boolean,
 	visitor: DeltaVisitor,
 ): void {
 	for (const [i, tree] of trees.entries()) {
 		const offsettedId = offsetDetachId(id, i);
 		let root = detachedFieldIndex.tryGetEntry(offsettedId);
 		assert(root === undefined, 0x929 /* Unable to build tree that already exists */);
-		root = detachedFieldIndex.createEntry(offsettedId, latestRevision);
+		root = detachedFieldIndex.createEntry(offsettedId, latestRevision, isAttachable);
 		const field = detachedFieldIndex.toFieldKey(root);
 		visitor.create([tree], field);
 	}
@@ -456,6 +467,7 @@ function processBuilds(
 				nodeCursorsFromChunk(trees),
 				config.detachedFieldIndex,
 				config.latestRevision,
+				true,
 				visitor,
 			);
 		}
@@ -473,7 +485,14 @@ function processGlobal(
 			if (root === undefined) {
 				const tree = tryGetFromNestedMap(config.refreshers, id.major, id.minor);
 				assert(tree !== undefined, 0x928 /* refresher data not found */);
-				buildTrees(id, [tree], config.detachedFieldIndex, config.latestRevision, visitor);
+				buildTrees(
+					id,
+					[tree],
+					config.detachedFieldIndex,
+					config.latestRevision,
+					false,
+					visitor,
+				);
 				root = config.detachedFieldIndex.getEntry(id);
 			}
 			// the revision is updated for any refresher data included in the delta that is used
@@ -529,6 +548,7 @@ function attachPass(
 						[tree],
 						config.detachedFieldIndex,
 						config.latestRevision,
+						false,
 						visitor,
 					);
 					sourceRoot = config.detachedFieldIndex.getEntry(offsetAttachId);

package/src/{extensibleSchemaUnion.ts → extensibleUnionNode.ts}

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
 import { TreeAlpha, Tree } from "./shared-tree/index.js";
 import type {
 	TreeNodeSchema,
@@ -15,15 +17,16 @@ import type {
 import {
 	createCustomizedFluidFrameworkScopedFactory,
 	eraseSchemaDetailsSubclassable,
+	getInnerNode,
 	SchemaFactory,
 	TreeBeta,
 } from "./simple-tree/index.js";
 import type { UnionToIntersection } from "./util/index.js";
 
 /**
- * Utilities for creating extensible schema unions.
+ * Utilities for creating extensible unions using a node.
  * @remarks
- * Use {@link ExtensibleSchemaUnion.extensibleSchemaUnion} to create the union schema.
+ * Use {@link ExtensibleUnionNode.createSchema} to create the union schema.
  *
  * Unlike a schema union created using {@link SchemaStaticsBeta.staged | staged} allowed types, this union allows for unknown future types to exist in addition to the known types.
  * This allows for faster roll-outs of new types without waiting for old clients to be updated to be aware of them.
@@ -35,42 +38,68 @@ import type { UnionToIntersection } from "./util/index.js";
  *
  * @example
  * ```typescript
- * const sf = new SchemaFactoryBeta("extensibleSchemaUnionExample.items");
+ * const sf = new SchemaFactoryBeta("extensibleUnionNodeExample.items");
  * class ItemA extends sf.object("A", { x: sf.string }) {}
  * class ItemB extends sf.object("B", { x: sf.number }) {}
  *
- * class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(
+ * class AnyItem extends ExtensibleUnionNode.createSchema(
  * 	[ItemA, ItemB], // Future versions may add more members here
  * 	sf,
  * 	"ExtensibleUnion",
  * ) {}
  * // Instances of the union are created using `create`.
  * const anyItem = AnyItem.create(new ItemA({ x: "hello" }));
- * // Reading the content from the union is done via `child`,
+ * // Reading the content from the union is done via the `union` property,
  * // which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.
- * const childNode: ItemA | ItemB | undefined = anyItem.child;
+ * const childNode: ItemA | ItemB | undefined = anyItem.union;
  * // To determine which member of the union was present, its schema can be inspected:
  * const aSchema = Tree.schema(childNode ?? assert.fail("No child"));
  * assert.equal(aSchema, ItemA);
  * ```
- * @alpha
+ * @beta
  */
-export namespace ExtensibleSchemaUnion {
+export namespace ExtensibleUnionNode {
 	/**
-	 * Members for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
-	 * @alpha
+	 * Members for classes created by {@link ExtensibleUnionNode.createSchema}.
+	 * @beta
 	 */
 	export interface Members<T> {
 		/**
-		 * The child wrapped by this node, which is has one of the type allowed by the union,
+		 * The child wrapped by this node has one of the types allowed by the union,
 		 * or `undefined` if the type is one which was added to the union by a future version of this schema.
+		 *
+		 * @throws if {@link ExtensibleUnionNode.Members.isValid} is false.
+		 */
+		readonly union: T | undefined;
+
+		/**
+		 * Returns true, unless this node is in an invalid state.
+		 * @remarks
+		 * A well behaved application should not need this API.
+		 * If an application is hitting errors when accessing {@link ExtensibleUnionNode.Members.union},
+		 * this API can be used to help detect and recover from the invalid state which causes those errors (for example by replacing the invalid nodes with new ones).
+		 *
+		 * In this context "invalid" means that the internal implementation details of this node have had their invariants violated.
+		 * This can happen when:
+		 * - Using weakly typed construction APIs like {@link (TreeBeta:interface).importConcise} or {@link (TreeAlpha:interface).importVerbose} to construct an invalid state directly.
+		 * Using such APIs, even when not creating invalid nodes, is not supported for this schema,
+		 * since doing so requires knowing the implementation details of this node which are subject to change.
+		 * - By editing a document using a different client using a different schema for this node.
+		 * - Violating the TypeScript types to directly manipulate the node internals.
+		 * - A bug in this node's implementation (possibly in a different client) corrupted the node.
+		 * - Corruption of the document this node is contained in.
+		 *
+		 * @privateRemarks
+		 * We could support {@link (TreeBeta:interface).exportVerbose} using {@link KeyEncodingOptions.allStoredKeys}
+		 * then {@link (TreeAlpha:interface).importVerbose} with {@link KeyEncodingOptions.knownStoredKeys}.
+		 * However, even this will error (but will not produce an invalid node) if there is a node of an unknown type in the union.
 		 */
-		readonly child: T | undefined;
+		isValid(): boolean;
 	}
 
 	/**
-	 * Statics for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
-	 * @alpha
+	 * Statics for classes created by {@link ExtensibleUnionNode.createSchema}.
+	 * @beta
 	 */
 	export interface Statics<T extends readonly TreeNodeSchema[]> {
 		/**
@@ -86,11 +115,11 @@ export namespace ExtensibleSchemaUnion {
 	 * Create an extensible schema union which currently supports the types in `types`,
 	 * but tolerates collaboration with future versions that may include additional types.
 	 * @remarks
-	 * See {@link ExtensibleSchemaUnion} for an example use.
-	 * @alpha
+	 * See {@link ExtensibleUnionNode} for an example use.
+	 * @beta
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-	export function extensibleSchemaUnion<
+	export function createSchema<
 		const T extends readonly TreeNodeSchema[],
 		const TScope extends string,
 		const TName extends string,
@@ -101,19 +130,32 @@ export namespace ExtensibleSchemaUnion {
 		}
 		const schemaFactory = createCustomizedFluidFrameworkScopedFactory(
 			inputSchemaFactory,
-			"extensibleSchemaUnion",
+			"extensibleUnionNode",
 		);
+
 		class Union
 			extends schemaFactory.object(name, record, { allowUnknownOptionalFields: true })
 			implements Members<TreeNodeFromImplicitAllowedTypes<T>>
 		{
-			public get child(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+			public get union(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+				if (!this.isValid()) {
+					throw new UsageError(
+						`This ExtensibleUnionNode (${Union.identifier}) is in an invalid state. It must have been edited by another client using a different schema or been directly imported or constructed in an invalid state.`,
+					);
+				}
 				for (const [_key, child] of TreeAlpha.children(this)) {
 					return child as TreeNodeFromImplicitAllowedTypes<T>;
 				}
 				return undefined;
 			}
 
+			public isValid(): boolean {
+				// Use inner node, since it includes populated fields even when they are unknown.
+				const inner = getInnerNode(this);
+				// Fields only includes non-empty fields, so this is what we need to check the one child invariant.
+				return [...inner.fields].length === 1;
+			}
+
 			public static create<TThis extends TreeNodeSchema>(
 				this: TThis,
 				child: TreeNodeFromImplicitAllowedTypes<T>,

package/src/feature-libraries/changeAtomIdBTree.ts

@@ -4,13 +4,19 @@
  */
 
 import {
+	subtractChangeAtomIds,
 	compareChangesetLocalIds,
 	comparePartialRevisions,
 	type ChangeAtomId,
 	type ChangesetLocalId,
 	type RevisionTag,
 } from "../core/index.js";
-import { createTupleComparator, newTupleBTree, type TupleBTree } from "../util/index.js";
+import {
+	createTupleComparator,
+	newTupleBTree,
+	type RangeQueryResult,
+	type TupleBTree,
+} from "../util/index.js";
 
 /**
  * A BTree which uses ChangeAtomId flattened into a tuple as the key.
@@ -42,6 +48,25 @@ export function setInChangeAtomIdMap<T>(
 	map: ChangeAtomIdBTree<T>,
 	id: ChangeAtomId,
 	value: T,
-): void {
-	map.set([id.revision, id.localId], value);
+): boolean {
+	return map.set([id.revision, id.localId], value);
+}
+
+export function rangeQueryChangeAtomIdMap<T>(
+	map: ChangeAtomIdBTree<T>,
+	id: ChangeAtomId,
+	count: number,
+): RangeQueryResult<T | undefined> {
+	const pair = map.getPairOrNextHigher([id.revision, id.localId]);
+	if (pair === undefined) {
+		return { value: undefined, length: count };
+	}
+
+	const [[revision, localId], value] = pair;
+	const lengthBefore = subtractChangeAtomIds({ revision, localId }, id);
+	if (lengthBefore === 0) {
+		return { value, length: 1 };
+	}
+
+	return { value: undefined, length: Math.min(lengthBefore, count) };
 }

package/src/feature-libraries/chunked-forest/codec/codecs.ts

@@ -35,13 +35,7 @@ import { TreeCompressionStrategy } from "../../treeCompressionUtils.js";
 
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
-import {
-	type EncodedFieldBatch,
-	validVersions,
-	FieldBatchFormatVersion,
-	EncodedFieldBatchV1,
-	EncodedFieldBatchV2,
-} from "./format.js";
+import { EncodedFieldBatch, validVersions, FieldBatchFormatVersion } from "./format.js";
 import type { IncrementalEncodingPolicy } from "./incrementalEncodingPolicy.js";
 import { schemaCompressedEncodeV1, schemaCompressedEncodeV2 } from "./schemaBasedEncode.js";
 import { uncompressedEncodeV1, uncompressedEncodeV2 } from "./uncompressedEncode.js";
@@ -157,18 +151,15 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 	let schemaCompressedEncodeFn:
 		| typeof schemaCompressedEncodeV1
 		| typeof schemaCompressedEncodeV2;
-	let encodedFieldBatchType: typeof EncodedFieldBatchV1 | typeof EncodedFieldBatchV2;
 	switch (writeVersion) {
 		case unbrand(FieldBatchFormatVersion.v1): {
 			uncompressedEncodeFn = uncompressedEncodeV1;
 			schemaCompressedEncodeFn = schemaCompressedEncodeV1;
-			encodedFieldBatchType = EncodedFieldBatchV1;
 			break;
 		}
 		case unbrand(FieldBatchFormatVersion.v2): {
 			uncompressedEncodeFn = uncompressedEncodeV2;
 			schemaCompressedEncodeFn = schemaCompressedEncodeV2;
-			encodedFieldBatchType = EncodedFieldBatchV2;
 			break;
 		}
 		default: {
@@ -176,7 +167,10 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 		}
 	}
 
-	return makeVersionedValidatedCodec(options, validVersions, encodedFieldBatchType, {
+	// Both the encode and decode logic here support both v1 and v2, as does `validVersions` and `EncodedFieldBatch`.
+	// This makes this use of makeVersionedValidatedCodec atypical as it is a single call being used to make a codec that supports all versions,
+	// instead of one call per version, then using another utility to select between them based on version.
+	return makeVersionedValidatedCodec(options, validVersions, EncodedFieldBatch, {
 		encode: (data: FieldBatch, context: FieldBatchEncodingContext): EncodedFieldBatch => {
 			for (const cursor of data) {
 				assert(