@fluidframework/tree 2.32.0 → 2.33.0

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

@@ -27,17 +27,35 @@ import type { EncodedChunkShape, EncodedFieldShape, EncodedValueShape } from "./
 import { isStableId } from "@fluidframework/id-compressor/internal";
 
 export class NodeShape extends Shape<EncodedChunkShape> implements NodeEncoder {
-	// TODO: Ensure uniform chunks, encoding and identifier generation sort fields the same.
-	private readonly explicitKeys: Set<FieldKey>;
+	/**
+	 * Set of keys for fields that are encoded using {@link NodeShape.specializedFieldEncoders}.
+	 * TODO: Ensure uniform chunks, encoding and identifier generation sort fields the same.
+	 */
+	private readonly specializedFieldKeys: Set<FieldKey>;
 
 	public constructor(
 		public readonly type: undefined | TreeNodeSchemaIdentifier,
 		public readonly value: EncodedValueShape,
-		public readonly fields: readonly KeyedFieldEncoder[],
-		public readonly extraLocal: undefined | FieldEncoder,
+		/**
+		 * Encoders for a specific set of fields, by key, in the order they will be encoded.
+		 * These are fields for which specialized encoding is provided as an optimization.
+		 * Using these for a given field instead of falling back to {@link NodeShape.specializedFieldEncoders} is often more efficient:
+		 * this avoids the need to explicitly include the key and shape in the encoded data for each node instance.
+		 * Instead, this information is here, and thus is encoded only once as part of the node shape.
+		 * These encoders will be used, even if the field they apply to is empty (which can add overhead for fields which are usually empty).
+		 *
+		 * Any fields not included here will be encoded using {@link NodeShape.otherFieldsEncoder}.
+		 * If {@link NodeShape.otherFieldsEncoder} is undefined, then this must handle all non-empty fields.
+		 */
+		public readonly specializedFieldEncoders: readonly KeyedFieldEncoder[],
+		/**
+		 * Encoder for all other fields that are not in {@link NodeShape.specializedFieldEncoders}. These fields must
+		 * be encoded after the specialized fields.
+		 */
+		public readonly otherFieldsEncoder: undefined | FieldEncoder,
 	) {
 		super();
-		this.explicitKeys = new Set(this.fields.map((f) => f.key));
+		this.specializedFieldKeys = new Set(this.specializedFieldEncoders.map((f) => f.key));
 	}
 
 	private getValueToEncode(cursor: ITreeCursorSynchronous, cache: EncoderCache): Value {
@@ -64,28 +82,28 @@ export class NodeShape extends Shape<EncodedChunkShape> implements NodeEncoder {
 			assert(cursor.type === this.type, 0x741 /* type must match shape */);
 		}
 		encodeValue(this.getValueToEncode(cursor, cache), this.value, outputBuffer);
-		for (const field of this.fields) {
-			cursor.enterField(brand(field.key));
-			field.shape.encodeField(cursor, cache, outputBuffer);
+		for (const fieldEncoder of this.specializedFieldEncoders) {
+			cursor.enterField(brand(fieldEncoder.key));
+			fieldEncoder.encoder.encodeField(cursor, cache, outputBuffer);
 			cursor.exitField();
 		}
 
-		const localBuffer: BufferFormat<EncodedChunkShape> = [];
+		const otherFieldsBuffer: BufferFormat<EncodedChunkShape> = [];
 
 		forEachField(cursor, () => {
 			const key = cursor.getFieldKey();
-			if (!this.explicitKeys.has(key)) {
+			if (!this.specializedFieldKeys.has(key)) {
 				assert(
-					this.extraLocal !== undefined,
+					this.otherFieldsEncoder !== undefined,
 					0x742 /* had extra local fields when shape does not support them */,
 				);
-				localBuffer.push(new IdentifierToken(key));
-				this.extraLocal.encodeField(cursor, cache, localBuffer);
+				otherFieldsBuffer.push(new IdentifierToken(key));
+				this.otherFieldsEncoder.encodeField(cursor, cache, otherFieldsBuffer);
 			}
 		});
 
-		if (this.extraLocal !== undefined) {
-			outputBuffer.push(localBuffer);
+		if (this.otherFieldsEncoder !== undefined) {
+			outputBuffer.push(otherFieldsBuffer);
 		}
 	}
 
@@ -97,8 +115,8 @@ export class NodeShape extends Shape<EncodedChunkShape> implements NodeEncoder {
 			c: {
 				type: encodeOptionalIdentifier(this.type, identifiers),
 				value: this.value,
-				fields: encodeFieldShapes(this.fields, identifiers, shapes),
-				extraFields: encodeOptionalFieldShape(this.extraLocal, shapes),
+				fields: encodeFieldShapes(this.specializedFieldEncoders, identifiers, shapes),
+				extraFields: encodeOptionalFieldShape(this.otherFieldsEncoder, shapes),
 			},
 		};
 	}
@@ -111,13 +129,13 @@ export class NodeShape extends Shape<EncodedChunkShape> implements NodeEncoder {
 			identifiers.add(this.type);
 		}
 
-		for (const field of this.fields) {
-			identifiers.add(field.key);
-			shapes(field.shape.shape);
+		for (const fieldEncoder of this.specializedFieldEncoders) {
+			identifiers.add(fieldEncoder.key);
+			shapes(fieldEncoder.encoder.shape);
 		}
 
-		if (this.extraLocal !== undefined) {
-			shapes(this.extraLocal.shape);
+		if (this.otherFieldsEncoder !== undefined) {
+			shapes(this.otherFieldsEncoder.shape);
 		}
 	}
 
@@ -127,18 +145,18 @@ export class NodeShape extends Shape<EncodedChunkShape> implements NodeEncoder {
 }
 
 export function encodeFieldShapes(
-	fields: readonly KeyedFieldEncoder[],
+	fieldEncoders: readonly KeyedFieldEncoder[],
 	identifiers: DeduplicationTable<string>,
 	shapes: DeduplicationTable<Shape<EncodedChunkShape>>,
 ): EncodedFieldShape[] | undefined {
-	if (fields.length === 0) {
+	if (fieldEncoders.length === 0) {
 		return undefined;
 	}
-	return fields.map((field) => [
+	return fieldEncoders.map((fieldEncoder) => [
 		// key
-		encodeIdentifier(field.key, identifiers),
+		encodeIdentifier(fieldEncoder.key, identifiers),
 		// shape
-		shapes.valueToIndex.get(field.shape.shape) ?? fail(0xb50 /* missing shape */),
+		shapes.valueToIndex.get(fieldEncoder.encoder.shape) ?? fail(0xb50 /* missing shape */),
 	]);
 }
 

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

@@ -122,7 +122,7 @@ export function treeShaper(
 
 		const objectNodeFields: KeyedFieldEncoder[] = [];
 		for (const [key, field] of schema.objectNodeFields ?? []) {
-			objectNodeFields.push({ key, shape: fieldHandler.shapeFromField(field) });
+			objectNodeFields.push({ key, encoder: fieldHandler.shapeFromField(field) });
 		}
 
 		const shape = new NodeShape(schemaName, false, objectNodeFields, undefined);

package/src/feature-libraries/flex-tree/context.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert } from "@fluidframework/core-utils/internal";
 
 import {
 	type ForestEvents,
@@ -43,6 +43,11 @@ export interface FlexTreeContext {
 	 * If false, this context was created for use in a unhydrated tree, and the full document schema is unknown.
 	 */
 	isHydrated(): this is FlexTreeHydratedContext;
+
+	/**
+	 * If true, none of the nodes in this context can be used.
+	 */
+	isDisposed(): boolean;
 }
 
 /**
@@ -106,9 +111,14 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 	}
 
 	public isHydrated(): this is FlexTreeHydratedContext {
+		debugAssert(() => !this.disposed || "Disposed");
 		return true;
 	}
 
+	public isDisposed(): boolean {
+		return this.disposed;
+	}
+
 	public get schema(): TreeStoredSchema {
 		return this.checkout.storedSchema;
 	}

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -94,6 +94,14 @@ export enum TreeStatus {
 
 	/**
 	 * Is removed and cannot be added back to the original document tree.
+	 * @remarks
+	 * Nodes can enter this state for multiple reasons:
+	 * - The node was removed and nothing (e.g. undo/redo history) kept it from being cleaned up.
+	 * - The {@link TreeView} was disposed or had a schema change which made the tree incompatible.
+	 * @privateRemarks
+	 * There was planned work (AB#17948) to make the first reason a node could become "Deleted" impossible,
+	 * at least as an opt in feature,
+	 * by lifetime extending all nodes which are still possible to reach automatically.
 	 */
 	Deleted = 2,
 

package/src/feature-libraries/indexing/anchorTreeIndex.ts

@@ -139,27 +139,14 @@ export class AnchorTreeIndex<TKey extends TreeIndexKey, TValue>
 				assert(parent !== undefined, 0xa99 /* must have a parent */);
 				this.reIndexSpine(parent);
 			},
-			afterDetach: () => {
-				assert(parent !== undefined, 0xa9a /* must have a parent */);
-				this.reIndexSpine(parent);
-			},
-			// when a replace happens, the keys of previously indexed nodes could be changed so we must re-index them
-			afterReplace: () => {
-				assert(parent !== undefined, 0xa8b /* must have a parent */);
-				const cursor = this.forest.allocateCursor();
-				this.forest.moveCursorToPath(parent, cursor);
-				assert(
-					cursor.mode === CursorLocationType.Nodes,
-					0xa8c /* replace should happen in a node */,
-				);
-				cursor.exitNode();
-				this.indexField(cursor);
-				if (!this.isShallowIndex) {
-					// we must also re-index the spine if the key finders allow for any value under a subtree to be the key
-					// this means that a replace can cause the key for any node up its spine to be changed
-					this.indexSpine(cursor);
+			afterDetach: (_source, _count_, _destination, isReplaced) => {
+				if (isReplaced) {
+					// If the node will be replaced, we defer re-indexing until the corresponding attach event.
+					// This has performance benefits but is also required to avoid experiencing the error case where the field that is used as the indexing key is empty.
+				} else {
+					assert(parent !== undefined, 0xa9a /* must have a parent */);
+					this.reIndexSpine(parent);
 				}
-				cursor.clear();
 			},
 			// the methods below are used to keep track of the path that has been traversed by the visitor
 			// this is required so that cursors can be moved to the correct location when index updates are required
@@ -315,17 +302,19 @@ export class AnchorTreeIndex<TKey extends TreeIndexKey, TValue>
 	 * Checks if the spine needs to be re-indexed and if so, re-indexes it starting from the given path.
 	 */
 	private reIndexSpine(path: UpPath): void {
+		const cursor = this.forest.allocateCursor();
+		this.forest.moveCursorToPath(path, cursor);
+		assert(
+			cursor.mode === CursorLocationType.Nodes,
+			0xa9b /* attach should happen in a node */,
+		);
+		cursor.exitNode();
+		// TODO ADO:36390 avoid re-indexing the whole field when not necessary
+		this.indexField(cursor);
 		if (!this.isShallowIndex) {
-			const cursor = this.forest.allocateCursor();
-			this.forest.moveCursorToPath(path, cursor);
-			assert(
-				cursor.mode === CursorLocationType.Nodes,
-				0xa9b /* attach should happen in a node */,
-			);
-			cursor.exitNode();
 			this.indexSpine(cursor);
-			cursor.clear();
 		}
+		cursor.clear();
 	}
 
 	private checkNotDisposed(errorMessage?: string): void {

package/src/feature-libraries/node-identifier/nodeIdentifierManager.ts

@@ -46,46 +46,47 @@ export interface NodeIdentifierManager {
 export function createNodeIdentifierManager(
 	idCompressor?: IIdCompressor | undefined,
 ): NodeIdentifierManager {
-	return {
-		generateLocalNodeIdentifier: () => {
-			assert(
-				idCompressor !== undefined,
-				0x6e4 /* Runtime IdCompressor must be available to generate local node identifiers */,
-			);
-			return brand(idCompressor.generateCompressedId());
-		},
-
-		localizeNodeIdentifier: (identifier: StableNodeIdentifier) => {
-			assert(
-				idCompressor !== undefined,
-				0x6e5 /* Runtime IdCompressor must be available to convert node identifiers */,
-			);
-			return brand(idCompressor.recompress(identifier));
-		},
+	return new DefaultNodeIdentifierManager(idCompressor);
+}
 
-		stabilizeNodeIdentifier: (identifier: LocalNodeIdentifier) => {
-			assert(
-				idCompressor !== undefined,
-				0x6e6 /* Runtime IdCompressor must be available to convert node identifiers */,
-			);
-			return brand(
-				// TODO: The assert below is required for type safety but is maybe slow
-				assertIsStableId(idCompressor.decompress(extractFromOpaque(identifier))),
-			);
-		},
-		tryLocalizeNodeIdentifier: (identifier: string) => {
-			assert(
-				idCompressor !== undefined,
-				0x6e9 /* Runtime IdCompressor must be available to convert node identifiers */,
-			);
-			if (isStableNodeIdentifier(identifier)) {
-				const compressedIdentifier = idCompressor.tryRecompress(identifier);
-				if (compressedIdentifier !== undefined) {
-					return brand(compressedIdentifier);
-				}
+class DefaultNodeIdentifierManager implements NodeIdentifierManager {
+	public constructor(private readonly idCompressor: IIdCompressor | undefined) {}
+	public generateLocalNodeIdentifier(): LocalNodeIdentifier {
+		assert(
+			this.idCompressor !== undefined,
+			0x6e4 /* Runtime IdCompressor must be available to generate local node identifiers */,
+		);
+		return brand(this.idCompressor.generateCompressedId());
+	}
+	public localizeNodeIdentifier(identifier: StableNodeIdentifier): LocalNodeIdentifier {
+		assert(
+			this.idCompressor !== undefined,
+			0x6e5 /* Runtime IdCompressor must be available to convert node identifiers */,
+		);
+		return brand(this.idCompressor.recompress(identifier));
+	}
+	public stabilizeNodeIdentifier(identifier: LocalNodeIdentifier): StableNodeIdentifier {
+		assert(
+			this.idCompressor !== undefined,
+			0x6e6 /* Runtime IdCompressor must be available to convert node identifiers */,
+		);
+		return brand(
+			// TODO: The assert below is required for type safety but is maybe slow
+			assertIsStableId(this.idCompressor.decompress(extractFromOpaque(identifier))),
+		);
+	}
+	public tryLocalizeNodeIdentifier(identifier: string): LocalNodeIdentifier | undefined {
+		assert(
+			this.idCompressor !== undefined,
+			0x6e9 /* Runtime IdCompressor must be available to convert node identifiers */,
+		);
+		if (isStableNodeIdentifier(identifier)) {
+			const compressedIdentifier = this.idCompressor.tryRecompress(identifier);
+			if (compressedIdentifier !== undefined) {
+				return brand(compressedIdentifier);
 			}
-		},
-	};
+		}
+	}
 }
 
 export function isStableNodeIdentifier(

package/src/feature-libraries/object-forest/objectForest.ts

@@ -236,20 +236,6 @@ export class ObjectForest implements IEditableForest {
 					parent.fields.delete(key);
 				}
 			}
-			public replace(
-				newContentSource: FieldKey,
-				range: Range,
-				oldContentDestination: FieldKey,
-				oldContentId: DeltaDetachedNodeId,
-			): void {
-				preEdit();
-				assert(
-					newContentSource !== oldContentDestination,
-					0x7ba /* Replace detached source field and detached destination field must be different */,
-				);
-				this.detachEdit(range, oldContentDestination);
-				this.attachEdit(newContentSource, range.end - range.start, range.start);
-			}
 			public enterNode(index: number): void {
 				cursor.enterNode(index);
 			}
@@ -267,10 +253,7 @@ export class ObjectForest implements IEditableForest {
 		const forestVisitor = new Visitor(this);
 		const announcedVisitors: AnnouncedVisitor[] = [];
 		this.deltaVisitors.forEach((getVisitor) => announcedVisitors.push(getVisitor()));
-		const combinedVisitor = combineVisitors(
-			[forestVisitor, ...announcedVisitors],
-			announcedVisitors,
-		);
+		const combinedVisitor = combineVisitors([forestVisitor, ...announcedVisitors]);
 		this.activeVisitor = combinedVisitor;
 		return combinedVisitor;
 	}

package/src/feature-libraries/schema-index/codec.ts

@@ -17,7 +17,6 @@ import {
 	encodeFieldSchema,
 	schemaFormat,
 	storedSchemaDecodeDispatcher,
-	toTreeNodeSchemaDataFormat,
 } from "../../core/index.js";
 import { brand } from "../../util/index.js";
 
@@ -33,7 +32,7 @@ export function encodeRepo(repo: TreeStoredSchema): Format {
 			enumerable: true,
 			configurable: true,
 			writable: true,
-			value: toTreeNodeSchemaDataFormat(schema.encode()),
+			value: schema.encode(),
 		});
 	}
 	return {

package/src/index.ts

@@ -124,17 +124,7 @@ export {
 	// Can not be moved to internalTypes since doing so causes app code to throw errors like:
 	// error TS2742: The inferred type of 'Inventory' cannot be named without a reference to '../node_modules/@fluidframework/tree/lib/internalTypes.js'. This is likely not portable. A type annotation is necessary.
 	type AllowedTypes,
-	type ImplicitAllowedTypesUnsafe,
-	type ImplicitFieldSchemaUnsafe,
-	type TreeObjectNodeUnsafe,
-	type InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
-	type TreeArrayNodeUnsafe,
-	type TreeMapNodeUnsafe,
-	type InsertableObjectFromSchemaRecordUnsafe,
-	type InsertableTreeFieldFromImplicitFieldUnsafe,
-	type FieldSchemaUnsafe,
-	type TreeNodeSchemaClassUnsafe,
-	type InsertableTreeNodeFromAllowedTypesUnsafe,
+	type System_Unsafe,
 	type FieldSchemaAlphaUnsafe,
 	type ArrayNodeCustomizableSchemaUnsafe,
 	type MapNodeCustomizableSchemaUnsafe,
@@ -233,6 +223,7 @@ export {
 	replaceHandles,
 	replaceVerboseTreeHandles,
 	type HandleConverter,
+	allowUnused,
 	type LeafSchema,
 	type ArrayNodeCustomizableSchema,
 	type ArrayNodePojoEmulationSchema,
@@ -240,6 +231,7 @@ export {
 	type MapNodeCustomizableSchema,
 	type MapNodePojoEmulationSchema,
 	MapNodeSchema,
+	type ObjectFromSchemaRecord,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,

package/src/internalTypes.ts

@@ -17,25 +17,6 @@ export type {
 	DefaultProvider,
 	typeNameSymbol,
 	InsertableObjectFromSchemaRecord,
-	ObjectFromSchemaRecord,
-	// Recursive Schema APIs
-	FieldHasDefaultUnsafe,
-	ObjectFromSchemaRecordUnsafe,
-	TreeObjectNodeUnsafe,
-	TreeFieldFromImplicitFieldUnsafe,
-	TreeNodeFromImplicitAllowedTypesUnsafe,
-	InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
-	TreeArrayNodeUnsafe,
-	TreeMapNodeUnsafe,
-	InsertableObjectFromSchemaRecordUnsafe,
-	InsertableTreeFieldFromImplicitFieldUnsafe,
-	InsertableTypedNodeUnsafe,
-	NodeBuilderDataUnsafe,
-	NodeFromSchemaUnsafe,
-	ReadonlyMapInlined,
-	TreeNodeSchemaUnsafe,
-	AllowedTypesUnsafe,
-	TreeNodeSchemaNonClassUnsafe,
 } from "./simple-tree/index.js";
 export type { FlexList, FlexListToUnion, ExtractItemType } from "./simple-tree/index.js";
 

package/src/jsonDomainSchema.ts

@@ -12,14 +12,12 @@ import type {
 	ValidateRecursiveSchema,
 	// #region Unused imports to make d.ts cleaner
 	/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars */
-	InsertableTypedNodeUnsafe,
+	System_Unsafe,
 	TreeNodeSchemaNonClass,
 	TreeNodeSchemaClass,
-	TreeMapNodeUnsafe,
 	NodeKind,
 	TreeNodeSchemaCore,
 	WithType,
-	TreeArrayNodeUnsafe,
 	LeafSchema,
 	/* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars */
 	// #endregion

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.32.0";
+export const pkgVersion = "2.33.0";

package/src/shared-tree/checkoutFlexTreeView.ts

@@ -34,6 +34,8 @@ export class CheckoutFlexTreeView<out TCheckout extends ITreeCheckout = ITreeChe
 	 */
 	public readonly flexTree: FlexTreeField;
 
+	private disposed = false;
+
 	public constructor(
 		/**
 		 * Access non-view schema specific aspects of this branch.
@@ -52,6 +54,9 @@ export class CheckoutFlexTreeView<out TCheckout extends ITreeCheckout = ITreeChe
 	}
 
 	public [disposeSymbol](): void {
+		assert(!this.disposed, 0xb80 /* Double disposed */);
+		this.disposed = true;
+
 		for (const anchorNode of this.checkout.forest.anchors) {
 			tryDisposeTreeNode(anchorNode);
 		}
@@ -65,6 +70,7 @@ export class CheckoutFlexTreeView<out TCheckout extends ITreeCheckout = ITreeChe
 	 * Any mutations of the new view will not apply to this view until the new view is merged back into this view via `merge()`.
 	 */
 	public fork(): CheckoutFlexTreeView<ITreeCheckout & ITreeCheckoutFork> {
+		assert(!this.disposed, 0xb81 /* disposed */);
 		const branch = this.checkout.branch();
 		return new CheckoutFlexTreeView(branch, this.schema, this.nodeKeyManager);
 	}

package/src/shared-tree/index.ts

@@ -4,11 +4,10 @@
  */
 
 export {
-	type ISharedTree,
 	type ITreePrivate,
 	type SharedTreeOptionsInternal,
 	type SharedTreeOptions,
-	SharedTree,
+	SharedTreeKernel,
 	getBranch,
 	type ForestType,
 	type SharedTreeContentSnapshot,
@@ -40,7 +39,11 @@ export { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 
 export { CheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
 
-export type { ISharedTreeEditor, ISchemaEditor } from "./sharedTreeEditBuilder.js";
+export type {
+	ISharedTreeEditor,
+	ISchemaEditor,
+	SharedTreeEditBuilder,
+} from "./sharedTreeEditBuilder.js";
 
 export {
 	treeApi as Tree,
@@ -55,3 +58,5 @@ export {
 	type ViewContent,
 	independentView,
 } from "./independentView.js";
+
+export type { SharedTreeChange } from "./sharedTreeChangeTypes.js";