@fluidframework/tree 2.74.0-365691 → 2.74.0-368706

package/src/core/rebase/utils.ts

@@ -327,7 +327,9 @@ export function rebaseBranch<TChange>(
 			},
 		},
 		"sourceChange",
-		() => changeRebaser.compose(editsToCompose),
+		() => {
+			return changeRebaser.compose(editsToCompose);
+		},
 	);
 }
 
@@ -375,23 +377,45 @@ export function rebaseChange<TChange>(
 export function revisionMetadataSourceFromInfo(
 	revInfos: readonly RevisionInfo[],
 ): RevisionMetadataSource {
-	const getIndex = (revision: RevisionTag): number | undefined => {
-		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
-		return index >= 0 ? index : undefined;
+	const compareRevisions = (revision1: RevisionTag, revision2: RevisionTag): number => {
+		const index1 = getIndex(revision1);
+		const index2 = getIndex(revision2);
+
+		if (index1 !== undefined) {
+			return index2 !== undefined ? index2 - index1 : -1;
+		}
+
+		return index2 !== undefined ? 1 : 0;
 	};
+
 	const tryGetInfo = (revision: RevisionTag | undefined): RevisionInfo | undefined => {
 		if (revision === undefined) {
 			return undefined;
 		}
-		const index = getIndex(revision);
-		return index === undefined ? undefined : revInfos[index];
+		return revInfos.find((info) => info.revision === revision);
 	};
 
 	const hasRollback = (revision: RevisionTag): boolean => {
 		return revInfos.find((info) => info.rollbackOf === revision) !== undefined;
 	};
 
-	return { getIndex, tryGetInfo, hasRollback };
+	const getIndex = (revision: RevisionTag): number | undefined => {
+		const index = revInfos.findIndex((revInfo) => revInfo.revision === revision);
+		if (index >= 0) {
+			return index;
+		}
+
+		const rollbackIndex = revInfos.findIndex((revInfo) => revInfo.rollbackOf === revision);
+		if (rollbackIndex >= 0) {
+			// This change is the forward revision of a rollback included in revInfos, so it comes after
+			// all revisions in revInfos. Earlier rollbacks have later forward revisions.
+			return 2 * revInfos.length - rollbackIndex;
+		}
+
+		return undefined;
+	};
+
+	return { compareRevisions, tryGetInfo, hasRollback };
 }
 
 export function rebaseChangeOverChanges<TChange>(

package/src/core/tree/detachedFieldIndex.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
@@ -37,10 +37,50 @@ import type {
 } from "./detachedFieldIndexTypes.js";
 import { makeDetachedFieldIndexCodec } from "./detachedFieldIndexCodecs.js";
 
+/**
+ * Readonly interface for {@link DetachedFieldIndex}.
+ */
+export interface ReadOnlyDetachedFieldIndex {
+	/**
+	 * Creates a deep clone of this `DetachedFieldIndex`.
+	 */
+	clone(): DetachedFieldIndex;
+
+	/**
+	 * Returns a field key for the given ID.
+	 * This does not save the field key on the index. To do so, call {@link createEntry}.
+	 */
+	toFieldKey(id: ForestRootId): FieldKey;
+
+	/**
+	 * Returns a node ID for the node in the given field.
+	 * @param field - The field key where the detached node resides.
+	 */
+	fromFieldKey(field: FieldKey): Delta.DetachedNodeId;
+
+	/**
+	 * Returns the `ForestRootId` associated with the given id.
+	 * Returns undefined if no such id is known to the index.
+	 */
+	tryGetEntry(id: Delta.DetachedNodeId): ForestRootId | undefined;
+
+	/**
+	 * Returns the `ForestRootId` associated with the given id.
+	 * Fails if no such id is known to the index.
+	 */
+	getEntry(id: Delta.DetachedNodeId): ForestRootId;
+}
+
+/**
+ * Restores the originating DetachedFieldIndex to the state it was in when the checkpoint was created.
+ * Can be invoked multiple times.
+ */
+export type DetachedFieldIndexCheckpoint = () => void;
+
 /**
  * The tree index records detached field IDs and associates them with a change atom ID.
  */
-export class DetachedFieldIndex {
+export class DetachedFieldIndex implements ReadOnlyDetachedFieldIndex {
 	/**
 	 * A mapping from detached node ids to detached fields.
 	 */
@@ -106,6 +146,25 @@ export class DetachedFieldIndex {
 		return clone;
 	}
 
+	/**
+	 * Creates a restorable checkpoint of the current state of the DetachedFieldIndex.
+	 */
+	public createCheckpoint(): DetachedFieldIndexCheckpoint {
+		const clone = this.clone();
+		return () => {
+			this.purge();
+			populateNestedMap(clone.detachedNodeToField, this.detachedNodeToField, true);
+			populateNestedMap(
+				clone.latestRelevantRevisionToFields,
+				this.latestRelevantRevisionToFields,
+				true,
+			);
+			this.rootIdAllocator = idAllocatorFromMaxId(
+				clone.rootIdAllocator.getMaxId(),
+			) as IdAllocator<ForestRootId>;
+		};
+	}
+
 	public *entries(): Generator<{
 		root: ForestRootId;
 		latestRelevantRevision?: RevisionTag;
@@ -201,26 +260,24 @@ export class DetachedFieldIndex {
 		}
 	}
 
-	/**
-	 * Returns a field key for the given ID.
-	 * This does not save the field key on the index. To do so, call {@link createEntry}.
-	 */
 	public toFieldKey(id: ForestRootId): FieldKey {
 		return brand(`${this.name}-${id}`);
 	}
 
-	/**
-	 * Returns the FieldKey associated with the given id.
-	 * Returns undefined if no such id is known to the index.
-	 */
+	public fromFieldKey(field: FieldKey): Delta.DetachedNodeId {
+		// TODO: maintain a lookup table or use field keys that encode the detached node ID
+		for (const { id, root } of this.entries()) {
+			if (this.toFieldKey(root) === field) {
+				return id;
+			}
+		}
+		fail("No known detached roots in the given field");
+	}
+
 	public tryGetEntry(id: Delta.DetachedNodeId): ForestRootId | undefined {
 		return tryGetFromNestedMap(this.detachedNodeToField, id.major, id.minor)?.root;
 	}
 
-	/**
-	 * Returns the FieldKey associated with the given id.
-	 * Fails if no such id is known to the index.
-	 */
 	public getEntry(id: Delta.DetachedNodeId): ForestRootId {
 		const key = this.tryGetEntry(id);
 		assert(key !== undefined, 0x7aa /* Unknown removed node ID */);

package/src/core/tree/index.ts

@@ -59,8 +59,9 @@ export {
 	type NodeIndex,
 	compareUpPaths,
 	compareFieldUpPaths,
-	isDetachedUpPathRoot as isDetachedUpPath,
+	isDetachedUpPathRoot,
 	getDetachedFieldContainingPath,
+	getDetachedFieldContainingFieldPath,
 	type UpPathDefault,
 } from "./pathTree.js";
 export {
@@ -117,9 +118,14 @@ export {
 	type ChunkedCursor,
 } from "./chunk.js";
 
-export { DetachedFieldIndex } from "./detachedFieldIndex.js";
+export {
+	DetachedFieldIndex,
+	type DetachedFieldIndexCheckpoint,
+	type ReadOnlyDetachedFieldIndex,
+} from "./detachedFieldIndex.js";
 
 export { getCodecTreeForDetachedFieldIndexFormat } from "./detachedFieldIndexCodecs.js";
-export { type DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
+export { DetachedFieldIndexFormatVersion } from "./detachedFieldIndexFormatCommon.js";
+export { type FormatV1 } from "./detachedFieldIndexFormatV1.js";
 
 export { type ForestRootId } from "./detachedFieldIndexTypes.js";

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/feature-libraries/chunked-forest/basicChunk.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob, fail } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail, debugAssert } from "@fluidframework/core-utils/internal";
 
 import {
 	CursorLocationType,
@@ -51,6 +51,12 @@ export class BasicChunk extends ReferenceCountedBase implements TreeChunk {
 		public value?: TreeValue,
 	) {
 		super();
+		debugAssert(() => {
+			for (const field of fields.values()) {
+				if (field.length === 0) return "field must have at least one child";
+			}
+			return true;
+		});
 	}
 
 	public clone(): BasicChunk {

package/src/feature-libraries/chunked-forest/chunkTree.ts

@@ -436,7 +436,12 @@ function newBasicChunkTree(
 ): BasicChunk {
 	return new BasicChunk(
 		cursor.type,
-		new Map(mapCursorFields(cursor, () => [cursor.getFieldKey(), chunkField(cursor, policy)])),
+		new Map(
+			mapCursorFields(cursor, () => {
+				debugAssert(() => cursor.getFieldLength() > 0 || "field must have at least one child");
+				return [cursor.getFieldKey(), chunkField(cursor, policy)];
+			}),
+		),
 		cursor.value,
 	);
 }

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

@@ -4,12 +4,20 @@
  */
 
 /**
- * Policy to determine whether a node / field should be incrementally encoded.
- * @param nodeIdentifier - The identifier of the node containing the field.
- * If undefined, the field is a root field.
- * @param fieldKey - The key of the field to check.
- * @returns whether the node / field should be incrementally encoded.
+ * Policy type to determine whether one of more fields of a {@link NodeKind | node} in a schema should be incrementally encoded.
+ * @param nodeIdentifier - The identifier of the node. The node is one of the kinds defined in {@link NodeKind}.
+ * @param fieldKey - An optional key for fields in the node. It must be one of the following based on the kind of node.
+ * Policy implementations may throw an error if the provided key is invalid for the node kind:
+ * - {@link NodeKind.Object | object} - Must be defined and should be the key of one of its fields. If the object node does not
+ * have a field with the specified key, returns false.
+ * - {@link NodeKind.Array | array} - Must be defined and be the "" (empty string) which is special value for arrays.
+ * - {@link NodeKind.Map | map} and {@link NodeKind.Record | record} - Must be undefined.
+ * - {@link NodeKind.Leaf | leaf} - Must be undefined. Leaf nodes do not support incremental encoding. If called for leaf nodes,
+ * returns false.
+ *
  * @remarks
+ * See {@link incrementalEncodingPolicyForAllowedTypes} for a reference policy implementation.
+ *
  * Incremental encoding has a significant size overhead,
  * but allows reuse of previously encoded unchanged subtrees.
  * Thus it should only be enabled for large subtrees which are modified infrequently.
@@ -18,7 +26,7 @@
  */
 export type IncrementalEncodingPolicy = (
 	nodeIdentifier: string | undefined,
-	fieldKey: string,
+	fieldKey?: string,
 ) => boolean;
 
 /**
@@ -26,7 +34,7 @@ export type IncrementalEncodingPolicy = (
  */
 export const defaultIncrementalEncodingPolicy: IncrementalEncodingPolicy = (
 	nodeIdentifier: string | undefined,
-	fieldKey: string,
+	fieldKey?: string,
 ): boolean => {
 	return false;
 };

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

@@ -180,16 +180,16 @@ export function getNodeEncoder(
 	schemaName: TreeNodeSchemaIdentifier,
 	incrementalEncoder?: IncrementalEncoder,
 ): NodeShapeBasedEncoder {
+	const shouldEncodeIncrementally =
+		incrementalEncoder?.shouldEncodeIncrementally ?? defaultIncrementalEncodingPolicy;
 	const schema =
 		storedSchema.nodeSchema.get(schemaName) ?? fail(0xb53 /* missing node schema */);
 
+	// This handles both object and array nodes.
 	if (schema instanceof ObjectNodeStoredSchema) {
 		// TODO:Performance:
 		// consider moving some optional and sequence fields to extra fields if they are commonly empty
 		// to reduce encoded size.
-
-		const shouldEncodeIncrementally =
-			incrementalEncoder?.shouldEncodeIncrementally ?? defaultIncrementalEncodingPolicy;
 		const objectNodeFields: KeyedFieldEncoder[] = [];
 		for (const [key, field] of schema.objectNodeFields ?? []) {
 			const fieldEncoder = shouldEncodeIncrementally(schemaName, key)
@@ -213,13 +213,13 @@ export function getNodeEncoder(
 		);
 		return shape;
 	}
+
+	// This handles both maps and record nodes.
 	if (schema instanceof MapNodeStoredSchema) {
-		const shape = new NodeShapeBasedEncoder(
-			schemaName,
-			false,
-			[],
-			fieldBuilder.fieldEncoderFromSchema(schema.mapFields),
-		);
+		const fieldEncoder = shouldEncodeIncrementally(schemaName)
+			? incrementalFieldEncoder
+			: fieldBuilder.fieldEncoderFromSchema(schema.mapFields);
+		const shape = new NodeShapeBasedEncoder(schemaName, false, [], fieldEncoder);
 		return shape;
 	}
 	fail(0xb54 /* unsupported node kind */);