@fluidframework/tree 2.74.0 → 2.81.0-374083

package/src/shared-tree/sharedTreeChangeCodecs.ts

@@ -56,7 +56,7 @@ export function makeSharedTreeChangeCodecFamily(
 			EncodedSharedTreeChange,
 			ChangeEncodingContext
 		>,
-	][] = Array.from(dependenciesForChangeFormat.entries()).map(
+	][] = [...dependenciesForChangeFormat.entries()].map(
 		([format, { modularChange, schemaChange }]) => [
 			format,
 			makeSharedTreeChangeCodec(
@@ -74,7 +74,10 @@ interface ChangeFormatDependencies {
 	readonly schemaChange: SchemaFormatVersion;
 }
 
-export type SharedTreeChangeFormatVersion = Brand<3 | 4, "SharedTreeChangeFormatVersion">;
+export type SharedTreeChangeFormatVersion = Brand<
+	3 | 4 | 5 | 101,
+	"SharedTreeChangeFormatVersion"
+>;
 
 /**
  * Defines for each SharedTree change format the corresponding dependent formats to use.
@@ -88,6 +91,8 @@ export const dependenciesForChangeFormat: Map<
 > = new Map([
 	[brand(3), { modularChange: brand(3), schemaChange: SchemaFormatVersion.v1 }],
 	[brand(4), { modularChange: brand(4), schemaChange: SchemaFormatVersion.v1 }],
+	[brand(5), { modularChange: brand(5), schemaChange: SchemaFormatVersion.v1 }],
+	[brand(101), { modularChange: brand(101), schemaChange: brand(SchemaFormatVersion.v1) }],
 ]);
 
 export function getCodecTreeForChangeFormat(
@@ -149,15 +154,15 @@ function makeSharedTreeChangeCodec(
 				for (const decodedChange of change.changes) {
 					if (decodedChange.type === "data") {
 						const schemaAndPolicy =
-							updatedSchema !== undefined
-								? {
+							updatedSchema === undefined
+								? context.schema
+								: {
 										policy:
-											context.schema !== undefined
-												? context.schema.policy
-												: defaultSchemaPolicy,
+											context.schema === undefined
+												? defaultSchemaPolicy
+												: context.schema.policy,
 										schema: updatedSchema,
-									}
-								: context.schema;
+									};
 						changes.push({
 							data: modularChangeCodec.encode(decodedChange.innerChange, {
 								originatorId: context.originatorId,

package/src/shared-tree/sharedTreeChangeEnricher.ts

@@ -20,6 +20,7 @@ import {
 	type TreeChunk,
 	chunkTree,
 	defaultChunkPolicy,
+	getBuildsIds,
 	intoDelta,
 	relevantRemovedRoots,
 	updateRefreshers as updateDataChangeRefreshers,
@@ -62,6 +63,7 @@ export class SharedTreeReadonlyChangeEnricher
 	public updateChangeEnrichments(change: SharedTreeChange): SharedTreeChange {
 		return updateRefreshers(
 			change,
+			getBuildsIds,
 			this.getDetachedRoot,
 			relevantRemovedRoots,
 			updateDataChangeRefreshers,
@@ -116,14 +118,16 @@ export class SharedTreeMutableChangeEnricher
 					visitor.free();
 					break;
 				}
-				case "schema":
+				case "schema": {
 					// This enricher doesn't need to maintain schema information.
 					// Note that the refreshers being generated through `updateChangeEnrichments` will be encoded using
 					// the schema that was used in the input context of the data changeset these refreshers are on.
 					// See the encoding logic in SharedTreeCore for details.
 					break;
-				default:
+				}
+				default: {
 					unreachableCase(type);
+				}
 			}
 		}
 	}

package/src/shared-tree/sharedTreeChangeFamily.ts

@@ -12,7 +12,9 @@ import {
 	type ChangeFamily,
 	type ChangeRebaser,
 	type DeltaDetachedNodeId,
+	type EditorOptions,
 	type RevisionMetadataSource,
+	type RevisionReplacer,
 	type RevisionTag,
 	type RevisionTagCodec,
 	type TaggedChange,
@@ -38,7 +40,7 @@ import {
 
 import { makeSharedTreeChangeCodecFamily } from "./sharedTreeChangeCodecs.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
-import { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
+import { IdBasedSharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 
 /**
  * Implementation of {@link ChangeFamily} that combines edits to fields and schema changes.
@@ -47,7 +49,7 @@ import { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
  */
 export class SharedTreeChangeFamily
 	implements
-		ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>,
+		ChangeFamily<IdBasedSharedTreeEditBuilder, SharedTreeChange>,
 		ChangeRebaser<SharedTreeChange>
 {
 	public static readonly emptyChange: SharedTreeChange = {
@@ -71,7 +73,11 @@ export class SharedTreeChangeFamily
 			codecOptions,
 			chunkCompressionStrategy,
 		);
-		this.modularChangeFamily = new ModularChangeFamily(fieldKinds, modularChangeCodec);
+		this.modularChangeFamily = new ModularChangeFamily(
+			fieldKinds,
+			modularChangeCodec,
+			codecOptions,
+		);
 		this.codecs = makeSharedTreeChangeCodecFamily(
 			this.modularChangeFamily.codecs,
 			codecOptions,
@@ -81,11 +87,13 @@ export class SharedTreeChangeFamily
 	public buildEditor(
 		mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<SharedTreeChange>) => void,
-	): SharedTreeEditBuilder {
-		return new SharedTreeEditBuilder(
+		options?: EditorOptions,
+	): IdBasedSharedTreeEditBuilder {
+		return new IdBasedSharedTreeEditBuilder(
 			this.modularChangeFamily,
 			mintRevisionTag,
 			changeReceiver,
+			options,
 		);
 	}
 
@@ -127,7 +135,7 @@ export class SharedTreeChangeFamily
 			innerChange: SharedTreeChange["changes"][number],
 		) => SharedTreeChange["changes"][number] = (innerChange) => {
 			switch (innerChange.type) {
-				case "data":
+				case "data": {
 					return {
 						type: "data",
 						innerChange: this.modularChangeFamily.invert(
@@ -136,6 +144,7 @@ export class SharedTreeChangeFamily
 							revision,
 						),
 					};
+				}
 				case "schema": {
 					return {
 						type: "schema",
@@ -148,8 +157,9 @@ export class SharedTreeChangeFamily
 						},
 					};
 				}
-				default:
+				default: {
 					fail(0xacc /* Unknown SharedTree change type. */);
+				}
 			}
 		};
 		return {
@@ -203,25 +213,28 @@ export class SharedTreeChangeFamily
 		};
 	}
 
+	public getRevisions(change: SharedTreeChange): Set<RevisionTag | undefined> {
+		const aggregated: Set<RevisionTag | undefined> = new Set();
+		for (const innerChange of change.changes) {
+			if (innerChange.type === "data") {
+				const innerRevisions = this.modularChangeFamily.rebaser.getRevisions(
+					innerChange.innerChange,
+				);
+				for (const tag of innerRevisions) {
+					aggregated.add(tag);
+				}
+			}
+		}
+		return aggregated;
+	}
+
 	public changeRevision(
 		change: SharedTreeChange,
-		newRevision: RevisionTag | undefined,
-		rollbackOf?: RevisionTag,
+		replacer: RevisionReplacer,
 	): SharedTreeChange {
-		return {
-			changes: change.changes.map((inner) => {
-				return inner.type === "data"
-					? {
-							...inner,
-							innerChange: this.modularChangeFamily.rebaser.changeRevision(
-								inner.innerChange,
-								newRevision,
-								rollbackOf,
-							),
-						}
-					: inner;
-			}),
-		};
+		return mapDataChanges(change, (inner) =>
+			this.modularChangeFamily.rebaser.changeRevision(inner, replacer),
+		);
 	}
 
 	public get rebaser(): ChangeRebaser<SharedTreeChange> {
@@ -259,6 +272,7 @@ function mapDataChanges(
  */
 export function updateRefreshers(
 	change: SharedTreeChange,
+	buildsFromDataChange: (taggedChange: ModularChangeset) => Iterable<DeltaDetachedNodeId>,
 	getDetachedNode: (id: DeltaDetachedNodeId) => TreeChunk | undefined,
 	relevantRemovedRootsFromDataChange: (
 		taggedChange: ModularChangeset,
@@ -305,13 +319,19 @@ export function updateRefreshers(
 	}
 	let isFirstDataChange = true;
 	return mapDataChanges(change, (dataChange) => {
+		const builtRoots = buildsFromDataChange(dataChange);
+		for (const id of builtRoots) {
+			// Detached root IDs that are used for builds are only ever used by a single node,
+			// so there is no risk of excluding needed refreshers by adding them to the list of already included roots.
+			addToNestedSet(includedRoots, id.major, id.minor);
+		}
 		const removedRoots = relevantRemovedRootsFromDataChange(dataChange);
 		if (isFirstDataChange) {
 			isFirstDataChange = false;
 			return updateDataChangeRefreshers(
 				dataChange,
 				getAndRememberDetachedNode,
-				removedRoots,
+				filterIncludedRoots(removedRoots),
 				true,
 			);
 		} else {

package/src/shared-tree/sharedTreeEditBuilder.ts

@@ -4,14 +4,22 @@
  */
 
 import type {
+	ChangeAtomId,
 	ChangeFamilyEditor,
+	EditorOptions,
 	RevisionTag,
 	TaggedChange,
+	TreeChunk,
 	TreeStoredSchema,
 } from "../core/index.js";
 import {
-	DefaultEditBuilder,
-	type IDefaultEditBuilder,
+	DefaultIdBasedDataEditor,
+	LocationBasedDataEditor,
+	type DetachedRootIds,
+	type DetachedRootLocation,
+	type DetachedRootsLocation,
+	type Locator,
+	type DataEditor,
 	type ModularChangeFamily,
 } from "../feature-libraries/index.js";
 
@@ -33,7 +41,16 @@ export interface ISchemaEditor {
 /**
  * SharedTree editor for transactional tree data and schema changes.
  */
-export interface ISharedTreeEditor extends IDefaultEditBuilder {
+export interface IIdBasedSharedTreeEditor
+	extends DataEditor<TreeChunk, ChangeAtomId, DetachedRootIds> {
+	/**
+	 * Editor for schema changes.
+	 */
+	schema: ISchemaEditor;
+}
+
+export interface ILocationBasedSharedTreeEditor
+	extends DataEditor<TreeChunk, DetachedRootLocation, DetachedRootsLocation> {
 	/**
 	 * Editor for schema changes.
 	 */
@@ -41,12 +58,12 @@ export interface ISharedTreeEditor extends IDefaultEditBuilder {
 }
 
 /**
- * Implementation of {@link IDefaultEditBuilder} based on the default set of supported field kinds.
+ * Implementation of {@link DataEditor} based on the default set of supported field kinds.
  * @sealed
  */
-export class SharedTreeEditBuilder
-	extends DefaultEditBuilder
-	implements ChangeFamilyEditor, ISharedTreeEditor
+export class IdBasedSharedTreeEditBuilder
+	extends DefaultIdBasedDataEditor
+	implements ChangeFamilyEditor, IIdBasedSharedTreeEditor
 {
 	public readonly schema: ISchemaEditor;
 
@@ -54,17 +71,23 @@ export class SharedTreeEditBuilder
 		modularChangeFamily: ModularChangeFamily,
 		mintRevisionTag: () => RevisionTag,
 		private readonly changeReceiver: (change: TaggedChange<SharedTreeChange>) => void,
+		options?: EditorOptions,
 	) {
-		super(modularChangeFamily, mintRevisionTag, (taggedChange) =>
-			changeReceiver({
-				...taggedChange,
-				change: { changes: [{ type: "data", innerChange: taggedChange.change }] },
-			}),
+		super(
+			modularChangeFamily,
+			mintRevisionTag,
+			(taggedChange) =>
+				changeReceiver({
+					...taggedChange,
+					change: { changes: [{ type: "data", innerChange: taggedChange.change }] },
+				}),
+			options,
+			modularChangeFamily.codecOptions,
 		);
 
 		this.schema = {
 			setStoredSchema: (oldSchema, newSchema) => {
-				this.changeReceiver({
+				changeReceiver({
 					revision: mintRevisionTag(),
 					change: {
 						changes: [
@@ -82,3 +105,15 @@ export class SharedTreeEditBuilder
 		};
 	}
 }
+
+export class LocationBasedSharedTreeEditBuilder
+	extends LocationBasedDataEditor
+	implements ILocationBasedSharedTreeEditor
+{
+	public readonly schema: ISchemaEditor;
+
+	public constructor(idBasedEditor: IIdBasedSharedTreeEditor, locator: Locator) {
+		super(idBasedEditor, locator);
+		this.schema = idBasedEditor.schema;
+	}
+}

package/src/shared-tree/treeAlpha.ts

@@ -12,7 +12,7 @@ import {
 import { createIdCompressor } from "@fluidframework/id-compressor/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type { IIdCompressor, SessionSpaceCompressedId } from "@fluidframework/id-compressor";
 
 import {
 	asIndex,
@@ -59,6 +59,7 @@ import {
 	contentSchemaSymbol,
 	type TreeNodeSchema,
 	getUnhydratedContext,
+	type TreeBranchAlpha,
 } from "../simple-tree/index.js";
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import {
@@ -83,32 +84,32 @@ import {
 	type Observer,
 	withObservation,
 } from "../feature-libraries/index.js";
-import type { TreeBranchAlpha } from "../simple-tree/index.js";
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
 import { isFluidHandle } from "@fluidframework/runtime-utils";
 
 const identifier: TreeIdentifierUtils = (node: TreeNode): string | undefined => {
-	const nodeIdentifier = getIdentifierFromNode(node, "uncompressed");
-	if (typeof nodeIdentifier === "number") {
-		throw new TypeError("identifier should be uncompressed.");
-	}
-	return nodeIdentifier;
+	return getIdentifierFromNode(node, "uncompressed");
 };
 
 identifier.shorten = (branch: TreeBranch, nodeIdentifier: string): number | undefined => {
-	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
-		.nodeKeyManager;
+	assert(
+		branch instanceof SchematizingSimpleTreeView,
+		0xcac /* Unexpected branch implementation */,
+	);
+	const { nodeKeyManager } = branch;
 	const localNodeKey = nodeKeyManager.tryLocalizeNodeIdentifier(nodeIdentifier);
-	return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : undefined;
+	return localNodeKey === undefined ? undefined : extractFromOpaque(localNodeKey);
 };
 
 identifier.lengthen = (branch: TreeBranch, nodeIdentifier: number): string => {
-	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
-		.nodeKeyManager;
-	return nodeKeyManager.stabilizeNodeIdentifier(
-		nodeIdentifier as unknown as LocalNodeIdentifier,
+	assert(
+		branch instanceof SchematizingSimpleTreeView,
+		0xcad /* Unexpected branch implementation */,
 	);
+	const { nodeKeyManager } = branch;
+	const local = brand<LocalNodeIdentifier>(nodeIdentifier as SessionSpaceCompressedId);
+	return nodeKeyManager.stabilizeNodeIdentifier(local);
 };
 
 identifier.getShort = (node: TreeNode): number | undefined => {
@@ -125,64 +126,70 @@ identifier.create = (branch: TreeBranch): string => {
 Object.freeze(identifier);
 
 /**
- * A utility interface for retrieving or converting node identifiers.
- *
+ * A utility interface for manipulating node identifiers.
  * @remarks
  * This provides methods to:
  *
- * - Retrieve long or short identifiers from nodes
- *
- * - Convert between long identifiers and short identifiers
- *
- * - Generates long identifiers
+ * - Retrieve identifiers from nodes
+ * - Generate identifiers
+ * - Convert between short numeric identifiers and long string identifiers
  *
  * @alpha @sealed
  */
 export interface TreeIdentifierUtils {
 	/**
-	 * Returns the contents of a node's {@link SchemaFactory.identifier} field as a stable identifier.
-	 * If the identifier field does not exist, returns undefined.
+	 * Returns the identifier of a node.
+	 * @remarks
+	 * This returns the node's UUID if and only if it has exactly one {@link SchemaFactory.identifier | identifier field}.
+	 * If it has no identifier field, this returns undefined.
+	 * If it has more than one identifier field, this throws an error.
+	 * In that case, query the identifier fields directly instead.
 	 *
 	 * @param node - The TreeNode you want to get the identifier from,
 	 */
 	(node: TreeNode): string | undefined;
 
 	/**
-	 * Returns the shortened identifier as a number given long identifier known by the id compressor on the branch if possible.
-	 * Otherwise, it will return the original string identifier provided.
-	 * If the id does not exist, or is unknown by the id compressor, it returns undefined.
+	 * Returns the shortened identifier as a number given a UUID known by the id compressor on the branch.
+	 * @remarks
+	 * If the given string is not a valid identifier and/or was not generated by the SharedTree, this will return `undefined`.
+	 *
+	 * See {@link TreeIdentifierUtils.getShort} for additional details about shortened identifiers.
 	 *
-	 * This method is the inverse of {@link TreeIdentifierUtils.lengthen}. If you shorten an identifier
-	 * and then immediately pass it to {@link TreeIdentifierUtils.lengthen}, you will get the original string back.
+	 * This method is the inverse of {@link TreeIdentifierUtils.lengthen}.
+	 * If you shorten an identifier and then immediately pass it to {@link TreeIdentifierUtils.lengthen}, you will get the original string back.
 	 *
-	 * @param branch - TreeBranch from where you get the idCompressor to do the decompression.
-	 * @param nodeIdentifier - the stable identifier that needs to be shortened.
+	 * @param branch - The branch (and/or view) of the SharedTree that will perform the compression.
+	 * @param nodeIdentifier - the stable identifier to be shortened.
 	 */
 	shorten(branch: TreeBranch, nodeIdentifier: string): number | undefined;
 
 	/**
-	 * Returns the stable id as a string if the identifier is decompressible and known by the id compressor. Otherwise, it will throw an error.
+	 * Returns the stable id as a string if the identifier is decompressible and known by the id compressor.
+	 * @remarks
+	 * If the given number does not correspond to a valid identifier generated by the SharedTree, this will return `undefined`.
 	 *
-	 * This method is the inverse of {@link TreeIdentifierUtils.shorten}. If you lengthen an identifier
-	 * and then immediately pass it to {@link TreeIdentifierUtils.shorten}, you will get the original short identifier back.
+	 * This method is the inverse of {@link TreeIdentifierUtils.shorten}.
+	 * If you lengthen an identifier and then immediately pass it to {@link TreeIdentifierUtils.shorten}, you will get the original short identifier back.
 	 *
-	 * @param branch - TreeBranch from where you want to get the id compressor to do the decompression.
-	 * @param nodeIdentifier - The local identifier that needs to be expanded.
+	 * @param branch - The branch (and/or view) of the SharedTree that will perform the decompression.
+	 * @param nodeIdentifier - The local identifier to be lengthened.
 	 */
 	lengthen(branch: TreeBranch, nodeIdentifier: number): string;
 
 	/**
-	 * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.
+	 * Returns the {@link TreeIdentifierUtils.shorten | shortened} form of the identifier {@link SchemaFactory.identifier | identifier} for the given node.
 	 * @remarks
 	 * If the node is {@link Unhydrated | hydrated} and its identifier is a valid UUID that was automatically generated by the SharedTree it is part of (or something else using the same {@link @fluidframework/id-compressor#IIdCompressor}), then this will return a process-unique integer corresponding to that identifier.
 	 * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.
-	 * Note that automatically generated identifiers that were accessed before the node was hydrated will return the generated UUID, not the process-unique integer.
+	 * Note that automatically generated identifiers that were accessed before the node was hydrated will not yield a short identifier until after hydration.
 	 *
-	 * If the node's identifier is any other user-provided string, then this will return undefined.
+	 * If the node's identifier is any other user-provided string, then this will return `undefined`.
 	 *
 	 * If the node has no identifier (that is, it has no {@link SchemaFactory.identifier | identifier} field), then this returns `undefined`.
 	 *
 	 * If the node has more than one identifier, then this will throw an error.
+	 * In that case, retrieve the identifiers individually via their fields instead.
 	 *
 	 * The returned integer should not be serialized or preserved outside of the current process.
 	 * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.
@@ -191,10 +198,11 @@ export interface TreeIdentifierUtils {
 	getShort(node: TreeNode): number | undefined;
 
 	/**
-	 * Creates and returns a long identifier.
-	 * The long identifier is a compressible, stable identifier generated by the tree's ID compressor.
+	 * Creates a new identifier.
+	 * @remarks
+	 * The returned UUID string can be {@link TreeIdentifierUtils.shorten | shortened} for high-performance scenarios.
 	 *
-	 * @param branch - TreeBranch from where you want to get the id compressor to generate the identifier from.
+	 * @param branch - The branch (and/or view) of the SharedTree that will generate and manage the identifier.
 	 */
 	create(branch: TreeBranch): string;
 }
@@ -629,12 +637,12 @@ class NodeSubscription {
 					return;
 				}
 				const subscription = subscriptions.get(flexNode);
-				if (subscription !== undefined) {
-					// Already subscribed to this node.
-					subscription.keys = undefined; // Now subscribed to all keys.
-				} else {
+				if (subscription === undefined) {
 					const newSubscription = new NodeSubscription(invalidate, flexNode);
 					subscriptions.set(flexNode, newSubscription);
+				} else {
+					// Already subscribed to this node.
+					subscription.keys = undefined; // Now subscribed to all keys.
 				}
 			},
 			observeNodeField(flexNode: FlexTreeNode, key: FieldKey): void {
@@ -643,15 +651,15 @@ class NodeSubscription {
 					return;
 				}
 				const subscription = subscriptions.get(flexNode);
-				if (subscription !== undefined) {
+				if (subscription === undefined) {
+					const newSubscription = new NodeSubscription(invalidate, flexNode);
+					newSubscription.keys = new Set([key]);
+					subscriptions.set(flexNode, newSubscription);
+				} else {
 					// Already subscribed to this node: if not subscribed to all keys, subscribe to this one.
 					// TODO:Performance: due to how JavaScript set ordering works,
 					// it might be faster to check `has` and only add if not present in case the same field is viewed many times.
 					subscription.keys?.add(key);
-				} else {
-					const newSubscription = new NodeSubscription(invalidate, flexNode);
-					newSubscription.keys = new Set([key]);
-					subscriptions.set(flexNode, newSubscription);
 				}
 			},
 			observeParentOf(node: FlexTreeNode): void {
@@ -943,11 +951,12 @@ export const TreeAlpha: TreeAlpha = {
 
 				return getOrCreateNodeFromInnerUnboxedNode(childFlexTree);
 			}
-			case NodeKind.Map:
+			case NodeKind.Map: {
 				if (typeof propertyKey !== "string") {
 					// Map nodes only support string keys.
 					return undefined;
 				}
+			}
 			// Fall through
 			case NodeKind.Record:
 			case NodeKind.Object: {