@fluidframework/tree 2.92.0 → 2.100.0

package/src/entrypoints/alpha.ts

@@ -102,10 +102,6 @@ export {
 	AnnotatedAllowedTypeUnsafe, 
 	AnnotatedAllowedTypes, 
 	AnnotatedAllowedTypesUnsafe, 
-	ArrayNodeDeltaOp, 
-	ArrayNodeInsertOp, 
-	ArrayNodeRemoveOp, 
-	ArrayNodeRetainOp, 
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ExtensibleUnionNode, 
@@ -116,13 +112,11 @@ export {
 	ForestTypeExpensiveDebug, 
 	ForestTypeOptimized, 
 	ForestTypeReference, 
+	IdentifierIndex, 
 	JsonCompatible, 
 	JsonCompatibleObject, 
 	KeyEncodingOptions, 
-	NodeChangedData,
-	NodeChangedDataAlpha,
-	NodeChangedDataDelta,
-	NodeChangedDataProperties,
+	NodeChangedData, 
 	ObjectSchemaOptions, 
 	PopUnion, 
 	RecordNodeInsertableData, 
@@ -136,9 +130,11 @@ export {
 	TableSchema, 
 	TreeBeta, 
 	TreeBranch, 
-	TreeChangeEventsBeta,
-	TreeChangeEventsAlpha,
+	TreeChangeEventsBeta, 
 	TreeEncodingOptions, 
+	TreeIndex, 
+	TreeIndexKey, 
+	TreeIndexNodes, 
 	TreeRecordNode, 
 	TreeRecordNodeUnsafe, 
 	TreeViewBeta, 
@@ -149,7 +145,9 @@ export {
 	adaptEnum, 
 	asBeta, 
 	configuredSharedTreeBeta, 
+	createIdentifierIndex, 
 	createIndependentTreeBeta, 
+	createTreeIndex, 
 	enumFromStrings, 
 	singletonSchema, 
 	snapshotSchemaCompatibility,
@@ -160,8 +158,14 @@ export {
 	ArrayNodeCustomizableSchema, 
 	ArrayNodeCustomizableSchemaAlpha, 
 	ArrayNodeCustomizableSchemaUnsafe, 
+	ArrayNodeDeltaOp, 
+	ArrayNodeInsertOp, 
 	ArrayNodePojoEmulationSchema, 
+	ArrayNodeRemoveOp, 
+	ArrayNodeRetainOp, 
 	ArrayNodeSchema, 
+	ArrayNodeTreeChangedDeltaOp, 
+	ArrayNodeTreeChangedRetainOp, 
 	ArrayPlaceAnchor, 
 	ChangeMetadata, 
 	CodecName, 
@@ -187,7 +191,6 @@ export {
 	HandleConverter, 
 	ICodecOptions, 
 	ITreeAlpha, 
-	IdentifierIndex, 
 	IncrementalEncodingPolicy, 
 	IndependentViewOptions, 
 	Insertable, 
@@ -220,6 +223,10 @@ export {
 	MapNodePojoEmulationSchema, 
 	MapNodeSchema, 
 	NoChangeConstraint, 
+	NodeChangedDataAlpha, 
+	NodeChangedDataDelta, 
+	NodeChangedDataProperties, 
+	NodeChangedDataTreeDelta, 
 	NodeProvider, 
 	NodeSchemaOptionsAlpha, 
 	ObjectNodeSchema, 
@@ -263,12 +270,11 @@ export {
 	TreeArrayNodeAlpha, 
 	TreeBranchAlpha, 
 	TreeBranchEvents, 
+	TreeChangeEventsAlpha, 
 	TreeCompressionStrategy, 
 	TreeContextAlpha, 
 	TreeIdentifierUtils, 
-	TreeIndex, 
-	TreeIndexKey, 
-	TreeIndexNodes, 
+	TreeMapNodeAlpha, 
 	TreeParsingOptions, 
 	TreeSchema, 
 	TreeSchemaEncodingOptions, 
@@ -290,9 +296,7 @@ export {
 	configuredSharedTreeAlpha, 
 	contentSchemaSymbol, 
 	createArrayInsertionAnchor, 
-	createIdentifierIndex, 
 	createIndependentTreeAlpha, 
-	createTreeIndex, 
 	decodeSchemaCompatibilitySnapshot, 
 	encodeSchemaCompatibilitySnapshot, 
 	eraseSchemaDetails, 

package/src/entrypoints/beta.ts

@@ -112,10 +112,11 @@ export {
 	ForestTypeExpensiveDebug, 
 	ForestTypeOptimized, 
 	ForestTypeReference, 
+	IdentifierIndex, 
 	JsonCompatible, 
 	JsonCompatibleObject, 
 	KeyEncodingOptions, 
-	NodeChangedData,
+	NodeChangedData, 
 	ObjectSchemaOptions, 
 	PopUnion, 
 	RecordNodeInsertableData, 
@@ -131,6 +132,9 @@ export {
 	TreeBranch, 
 	TreeChangeEventsBeta, 
 	TreeEncodingOptions, 
+	TreeIndex, 
+	TreeIndexKey, 
+	TreeIndexNodes, 
 	TreeRecordNode, 
 	TreeRecordNodeUnsafe, 
 	TreeViewBeta, 
@@ -141,7 +145,9 @@ export {
 	adaptEnum, 
 	asBeta, 
 	configuredSharedTreeBeta, 
+	createIdentifierIndex, 
 	createIndependentTreeBeta, 
+	createTreeIndex, 
 	enumFromStrings, 
 	singletonSchema, 
 	snapshotSchemaCompatibility

package/src/entrypoints/legacy.ts

@@ -102,10 +102,6 @@ export {
 	AnnotatedAllowedTypeUnsafe, 
 	AnnotatedAllowedTypes, 
 	AnnotatedAllowedTypesUnsafe, 
-	ArrayNodeDeltaOp, 
-	ArrayNodeInsertOp, 
-	ArrayNodeRemoveOp, 
-	ArrayNodeRetainOp, 
 	CodecWriteOptionsBeta, 
 	ConciseTree, 
 	ExtensibleUnionNode, 
@@ -116,13 +112,11 @@ export {
 	ForestTypeExpensiveDebug, 
 	ForestTypeOptimized, 
 	ForestTypeReference, 
+	IdentifierIndex, 
 	JsonCompatible, 
 	JsonCompatibleObject, 
 	KeyEncodingOptions, 
-	NodeChangedData,
-	NodeChangedDataAlpha,
-	NodeChangedDataDelta,
-	NodeChangedDataProperties,
+	NodeChangedData, 
 	ObjectSchemaOptions, 
 	PopUnion, 
 	RecordNodeInsertableData, 
@@ -136,9 +130,11 @@ export {
 	TableSchema, 
 	TreeBeta, 
 	TreeBranch, 
-	TreeChangeEventsBeta,
-	TreeChangeEventsAlpha,
+	TreeChangeEventsBeta, 
 	TreeEncodingOptions, 
+	TreeIndex, 
+	TreeIndexKey, 
+	TreeIndexNodes, 
 	TreeRecordNode, 
 	TreeRecordNodeUnsafe, 
 	TreeViewBeta, 
@@ -149,7 +145,9 @@ export {
 	adaptEnum, 
 	asBeta, 
 	configuredSharedTreeBeta, 
+	createIdentifierIndex, 
 	createIndependentTreeBeta, 
+	createTreeIndex, 
 	enumFromStrings, 
 	singletonSchema, 
 	snapshotSchemaCompatibility,

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,
@@ -166,10 +166,19 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		if (this.nestedCursor !== undefined) {
 			return this.nestedCursor.mode;
 		}
-		// Compute the number of nodes deep the current depth is.
-		// We want the floor of the result, which can computed using a bitwise shift assuming the depth is less than 2^31, which seems safe.
-		// eslint-disable-next-line no-bitwise
-		const halfHeight = (this.siblingStack.length + 1) >> 1;
+		this.assertChunkStacksMatchNodeDepth();
+		return this.siblingStack.length % 2 === 0
+			? CursorLocationType.Fields
+			: CursorLocationType.Nodes;
+	}
+
+	/**
+	 * Asserts that the node-only stacks (`indexOfChunkStack` and `indexWithinChunkStack`) are in sync with `siblingStack`.
+	 * Since `siblingStack` interleaves field and node levels while the node-only stacks are pushed/popped only on node-level transitions,
+	 * their length should always equal the number of node levels traversed.
+	 */
+	private assertChunkStacksMatchNodeDepth(): void {
+		const halfHeight = this.getNodeOnlyHeightFromHeight();
 		assert(
 			this.indexOfChunkStack.length === halfHeight,
 			0x51c /* unexpected indexOfChunkStack */,
@@ -178,9 +187,6 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 			this.indexWithinChunkStack.length === halfHeight,
 			0x51d /* unexpected indexWithinChunkStack */,
 		);
-		return this.siblingStack.length % 2 === 0
-			? CursorLocationType.Fields
-			: CursorLocationType.Nodes;
 	}
 
 	public getFieldKey(): FieldKey {
@@ -203,9 +209,32 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		return this.indexStack[height] ?? oob();
 	}
 
-	private getStackedNode(height: number): BasicChunk {
-		const index = this.getStackedNodeIndex(height);
-		return (this.siblingStack[height] as readonly TreeChunk[])[index] as BasicChunk;
+	private getStackedChunkIndex(height: number): number {
+		assert(height % 2 === 1, 0xcf3 /* must be node height */);
+		assert(height >= 0, 0xcf4 /* must not be above root */);
+		return this.indexOfChunkStack[this.getNodeOnlyHeightFromHeight(height)] ?? oob();
+	}
+
+	private getStackedChunk(height: number): BasicChunk {
+		const index = this.getStackedChunkIndex(height);
+		const chunk = (this.siblingStack[height] as readonly TreeChunk[])[index];
+		debugAssert(() => chunk instanceof BasicChunk || "only basic chunks are expected");
+		return chunk as BasicChunk;
+	}
+
+	/**
+	 * Converts a {@link height}, which contains field and node levels, into the corresponding depth/index
+	 * for the node-only stacks ({@link indexOfChunkStack} and {@link indexWithinChunkStack}), which are
+	 * only pushed on node-level transitions.
+	 *
+	 * @param height - A depth in {@link siblingStack} to convert. Defaults to {@link siblingStack}'s
+	 * current length, which gives the current depth of the node-only stacks.
+	 * @returns `floor(height / 2)` — the number of node levels at or below the given stack height.
+	 */
+	private getNodeOnlyHeightFromHeight(height: number = this.siblingStack.length): number {
+		// The bitwise shift computes the floor, which is valid assuming the depth is less than 2^31, which seems safe.
+		// eslint-disable-next-line no-bitwise
+		return height >> 1;
 	}
 
 	public getFieldLength(): number {
@@ -322,6 +351,11 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		assert(this.mode === CursorLocationType.Nodes, 0x528 /* must be in nodes mode */);
 		this.siblingStack.push(this.siblings);
 		this.indexStack.push(this.index);
+		// Save the chunk array position of the current node. When siblings contain
+		// multi node chunks, the flat node index diverges from the array position,
+		// so getField needs this to locate the parent in the sibling array.
+		this.indexOfChunkStack.push(this.indexOfChunk);
+		this.indexWithinChunkStack.push(this.indexWithinChunk);
 
 		// For fields, siblings are only used for key lookup and
 		// nextField and which has arbitrary iteration order,
@@ -330,6 +364,7 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		// at the cost of an allocation here.
 		this.index = 0;
 		this.siblings = [key];
+		this.assertChunkStacksMatchNodeDepth();
 	}
 
 	public nextField(): boolean {
@@ -355,8 +390,11 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 
 		this.siblingStack.push(this.siblings);
 		this.indexStack.push(this.index);
+		this.indexOfChunkStack.push(this.indexOfChunk);
+		this.indexWithinChunkStack.push(this.indexWithinChunk);
 		this.index = 0;
 		this.siblings = [...fields.keys()]; // TODO: avoid this copy
+		this.assertChunkStacksMatchNodeDepth();
 		return true;
 	}
 
@@ -422,12 +460,11 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		}
 		this.siblingStack.push(this.siblings);
 		this.indexStack.push(this.index);
-		this.indexOfChunkStack.push(this.indexOfChunk);
-		this.indexWithinChunkStack.push(this.indexWithinChunk);
 		this.index = 0;
 		this.siblings = siblings;
 		this.indexOfChunk = 0;
 		this.indexWithinChunk = 0;
+		this.assertChunkStacksMatchNodeDepth();
 		this.initNestedCursor();
 		return true;
 	}
@@ -486,6 +523,12 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		this.siblings =
 			this.siblingStack.pop() ?? fail(0xaf0 /* Unexpected siblingStack.length */);
 		this.index = this.indexStack.pop() ?? fail(0xaf1 /* Unexpected indexStack.length */);
+		this.indexOfChunk =
+			this.indexOfChunkStack.pop() ?? fail(0xcf5 /* Unexpected indexOfChunkStack.length */);
+		this.indexWithinChunk =
+			this.indexWithinChunkStack.pop() ??
+			fail(0xcf6 /* Unexpected indexWithinChunkStack.length */);
+		this.assertChunkStacksMatchNodeDepth();
 	}
 
 	public exitNode(): void {
@@ -502,18 +545,27 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		this.siblings =
 			this.siblingStack.pop() ?? fail(0xaf2 /* Unexpected siblingStack.length */);
 		this.index = this.indexStack.pop() ?? fail(0xaf3 /* Unexpected indexStack.length */);
-		this.indexOfChunk =
-			this.indexOfChunkStack.pop() ?? fail(0xaf4 /* Unexpected indexOfChunkStack.length */);
-		this.indexWithinChunk =
-			this.indexWithinChunkStack.pop() ??
-			fail(0xaf5 /* Unexpected indexWithinChunkStack.length */);
+		// At the Fields level these aren't semantically used, but reset for consistent state
+		// (so a fully-iterated cursor matches a fresh cursor at the same logical position).
+		this.indexOfChunk = 0;
+		this.indexWithinChunk = 0;
+		this.assertChunkStacksMatchNodeDepth();
 	}
 
 	private getNode(): BasicChunk {
 		assert(this.mode === CursorLocationType.Nodes, 0x52f /* can only get node when in node */);
-		return (this.siblings as TreeChunk[])[this.index] as BasicChunk;
+		const chunk = (this.siblings as TreeChunk[])[this.indexOfChunk];
+		debugAssert(() => chunk instanceof BasicChunk || "only basic chunks are expected");
+		return chunk as BasicChunk;
 	}
 
+	/**
+	 * Resolves the chunks that make up the field the cursor is currently in. At the root, this is
+	 * {@link root} directly. Otherwise, the cursor must be in {@link CursorLocationType.Fields} mode,
+	 * and the result is looked up on the parent node using the current field key.
+	 *
+	 * @returns The chunks that make up the field the cursor is currently in.
+	 */
 	private getField(): readonly TreeChunk[] {
 		if (this.siblingStack.length === 0) {
 			return this.root;
@@ -522,7 +574,11 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 			this.mode === CursorLocationType.Fields,
 			0x530 /* can only get field when in fields */,
 		);
-		const parent = this.getStackedNode(this.indexStack.length - 1);
+		// The parent node is the `BasicChunk` in the node array at the top of
+		// `siblingStack` while we are in `CursorLocationType.Fields` mode. We need the parent
+		// since a field's chunks are stored on the parent node's `BasicChunk.fields` map, not on
+		// the cursor itself.
+		const parent = this.getStackedChunk(this.siblingStack.length - 1);
 		const key: FieldKey = this.getFieldKey();
 		const field = parent.fields.get(key) ?? [];
 		return field;

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

@@ -424,8 +424,8 @@ export interface ChunkCompressor {
 	/**
 	 * If the idCompressor is provided, {@link UniformChunk}s with identifiers will be encoded for its in-memory representation.
 	 * @remarks
-	 * This compression applies to {@link UniformChunk}s when {@link TreeShape.maybeDecompressedStringAsNumber} is set.
-	 * If the `policy` does not use UniformChunks or does not set `maybeDecompressedStringAsNumber`, then no compression will be applied even when providing `idCompressor`.
+	 * This compression applies to {@link UniformChunk}s when {@link TreeShape.mayContainCompressedIds} is set.
+	 * If the `policy` does not use UniformChunks or does not set `mayContainCompressedIds`, then no compression will be applied even when providing `idCompressor`.
 	 */
 	readonly idCompressor: IIdCompressor | undefined;
 }
@@ -583,6 +583,7 @@ export function insertValues(
 	// Slow path: walk shape and cursor together, inserting values.
 	if (shape.hasValue) {
 		if (
+			shape.mayContainCompressedIds &&
 			typeof cursor.value === "string" &&
 			idCompressor !== undefined &&
 			isStableNodeIdentifier(cursor.value)

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

@@ -49,8 +49,8 @@ import {
 	type EncodedNestedArrayShape,
 	type EncodedNodeShape,
 	type EncodedValueShape,
-	FieldBatchFormatVersion,
 	SpecialField,
+	supportsIncrementalEncoding,
 } from "./format/index.js";
 
 export interface IdDecodingContext {
@@ -256,7 +256,7 @@ export class IncrementalChunkDecoder implements ChunkDecoder {
 
 		const chunkDecoder = (batch: EncodedFieldBatchV2): TreeChunk => {
 			assert(
-				batch.version >= FieldBatchFormatVersion.v2,
+				supportsIncrementalEncoding(batch.version),
 				0xc9f /* Unsupported FieldBatchFormatVersion for incremental chunks; must be v2 or higher */,
 			);
 			const context = new DecoderContext(

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

@@ -30,6 +30,7 @@ import {
 	EncodedFieldBatchV1,
 	EncodedFieldBatchV2,
 	FieldBatchFormatVersion,
+	supportsIncrementalEncoding,
 	type EncodedFieldBatchV1OrV2,
 } from "./format/index.js";
 import type { IncrementalEncodingPolicy } from "./incrementalEncodingPolicy.js";
@@ -147,7 +148,7 @@ function makeFieldBatchCodecForVersion(
 				}
 				case TreeCompressionStrategy.CompressedIncremental: {
 					assert(
-						version >= FieldBatchFormatVersion.v2,
+						supportsIncrementalEncoding(version),
 						0xca0 /* Unsupported FieldBatchFormatVersion for incremental encoding; must be v2 or higher */,
 					);
 					// Incremental encoding is only supported for CompressedIncremental.

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

@@ -36,8 +36,9 @@ import {
 	type EncodedFieldBatchV1OrV2,
 	type EncodedNestedArrayShape,
 	type EncodedValueShape,
-	FieldBatchFormatVersion,
+	type FieldBatchFormatVersion,
 	SpecialField,
+	supportsIncrementalEncoding,
 } from "./format/index.js";
 
 /**
@@ -461,7 +462,7 @@ export const incrementalFieldEncoder: FieldEncoder = {
 			0xc88 /* incremental encoder must be defined to use incrementalFieldEncoder */,
 		);
 		assert(
-			context.version >= FieldBatchFormatVersion.v2,
+			supportsIncrementalEncoding(context.version),
 			0xca1 /* Unsupported FieldBatchFormatVersion for incremental encoding; must be v2 or higher */,
 		);
 

package/src/feature-libraries/chunked-forest/codec/format/formatGeneric.ts

@@ -28,7 +28,6 @@ export const Count = Type.Number({ multipleOf: 1, minimum: 0 });
 
 const EncodedFieldBatchBase = Type.Object(
 	{
-		version: Type.Number(),
 		identifiers: Type.Array(Type.String()),
 		/**
 		 * Top level array is list of field from batch.

package/src/feature-libraries/chunked-forest/codec/format/index.ts

@@ -20,6 +20,7 @@ export {
 	FieldBatchFormatVersion,
 	EncodedFieldBatchV1,
 	EncodedFieldBatchV2,
+	supportsIncrementalEncoding,
 	type EncodedFieldBatchV1OrV2,
 	type EncodedFieldBatchV1AndV2,
 	type EncodedChunkShapeV1OrV2,

package/src/feature-libraries/chunked-forest/codec/format/versions.ts

@@ -31,6 +31,21 @@ export const FieldBatchFormatVersion = strictEnum("FieldBatchFormatVersion", {
 	v2: 2,
 });
 
+/**
+ * Whether the given format version supports incremental chunk encoding.
+ *
+ * @remarks
+ * This helper should be used for comparison since experimental versions
+ * can be a string.
+ */
+export function supportsIncrementalEncoding(version: FieldBatchFormatVersion): boolean {
+	if (version === FieldBatchFormatVersion.v1) {
+		return false;
+	}
+
+	return true;
+}
+
 /**
  * Encoded {@link FieldBatch} using V1 format.
  * @remarks

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

@@ -5,7 +5,6 @@
 
 import { assert, compareArrays, oob, fail } from "@fluidframework/core-utils/internal";
 import type { SessionSpaceCompressedId, IIdCompressor } from "@fluidframework/id-compressor";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	CursorLocationType,
@@ -21,7 +20,7 @@ import {
 	cursorChunk,
 	dummyRoot,
 } from "../../core/index.js";
-import { ReferenceCountedBase, hasSome } from "../../util/index.js";
+import { ReferenceCountedBase, getOrCreate, hasSome } from "../../util/index.js";
 import { SynchronousCursor, prefixFieldPath, prefixPath } from "../treeCursorUtils.js";
 
 /**
@@ -54,7 +53,7 @@ export class UniformChunk extends ReferenceCountedBase implements TreeChunk {
 		idCompressor?: IIdCompressor,
 	) {
 		super();
-		this.idCompressor = idCompressor;
+		this.idCompressor = shape.treeShape.mayContainCompressedIds ? idCompressor : undefined;
 		assert(
 			shape.treeShape.valuesPerTopLevelNode * shape.topLevelLength === values.length,
 			0x4c3 /* invalid number of values for shape */,
@@ -84,6 +83,23 @@ export class UniformChunk extends ReferenceCountedBase implements TreeChunk {
  */
 export type FieldShape = readonly [FieldKey, TreeShape, number];
 
+/**
+ * Maximum topLevelLength value (exclusive) for which {@link TreeShape.withTopLevelLength}
+ * caches the resulting {@link ChunkShape}. Values at or above this threshold always
+ * create a new instance to prevent unbounded cache growth.
+ *
+ * @remarks
+ * This value is an estimation of the general size needed to cover current workflows,
+ * not a researched constant, and is safe to tune as workloads change.
+ *
+ * Raising this value captures more chunk sizes in the cache, at the cost of
+ * each `TreeShape` retaining up to `chunkShapeCacheLimit - 1` cached entries for the
+ * lifetime of the shape. Lowering it reduces memory held per `TreeShape` but forces
+ * small chunks, where the relative cost of rebuilding `positions` is highest, to pay
+ * the construction cost on every call.
+ */
+const chunkShapeCacheLimit = 8;
+
 /**
  * The "shape" of a tree.
  * Does not contain the actual values from  the tree, but describes everything else,
@@ -101,29 +117,50 @@ export class TreeShape {
 	public readonly positions: readonly NodePositionInfo[];
 
 	/**
+	 * Whether chunks using this shape (including any descendant leaf within it) may contain values compressed by the {@link UniformChunk.idCompressor}.
 	 *
+	 * @remarks
+	 * For string leaf nodes, this can be explicitly set to `true` to indicate that the value may be a compressed id
+	 * stored as a number that needs to be decompressed back to a string.
+	 * For non-leaf nodes, this is automatically derived from whether any child shapes have it set.
+	 */
+	public readonly mayContainCompressedIds: boolean;
+
+	/**
+	 * Cache for ChunkShape instances created by {@link withTopLevelLength}.
+	 * `topLevelLength` is always a positive integer (enforced by the {@link ChunkShape} constructor),
+	 * so the cache only ever holds entries for values in `1..chunkShapeCacheLimit - 1` to prevent unbounded growth.
+	 */
+	private readonly chunkShapeCache: Map<number, ChunkShape> = new Map();
+
+	/**
 	 * @param type - {@link TreeNodeSchemaIdentifier} used to compare shapes.
 	 * @param hasValue - whether or not the TreeShape has a value.
 	 * @param fieldsArray - an array of {@link FieldShape} values, which contains a TreeShape for each FieldKey.
 	 *
-	 * @param maybeDecompressedStringAsNumber - used to check whether or not the value could have been compressed by the idCompressor.
-	 * This flag can only be set on string leaf nodes, and will throw a usage error otherwise.
-	 * If set to true, an additional check can be made (example: getting the value of {@link Cursor}) to return the original uncompressed value.
+	 * @param maybeCompressedIdLeaf - whether the value may have been compressed by the {@link UniformChunk.idCompressor}.
+	 * Can only be explicitly set to `true` on string leaf nodes; otherwise this constructor asserts.
+	 * For non-leaf nodes, {@link TreeShape.mayContainCompressedIds} is automatically derived from child shapes.
 	 */
 	public constructor(
 		public readonly type: TreeNodeSchemaIdentifier,
 		public readonly hasValue: boolean,
 		public readonly fieldsArray: readonly FieldShape[],
-		public readonly maybeDecompressedStringAsNumber: boolean = false,
+		maybeCompressedIdLeaf: boolean = false,
 	) {
-		if (
-			maybeDecompressedStringAsNumber &&
-			!(hasValue && type === "com.fluidframework.leaf.string")
-		) {
-			throw new UsageError(
-				"maybeDecompressedStringAsNumber flag can only be set to true for string leaf node.",
+		assert(
+			hasValue === false || fieldsArray.length === 0,
+			0xcef /* only non-leaf can have fields */,
+		);
+		if (maybeCompressedIdLeaf) {
+			assert(
+				hasValue && type === "com.fluidframework.leaf.string",
+				0xcf0 /* only strings can opt into maybeCompressedIdLeaf */,
 			);
 		}
+		// For non-leaf nodes, derive from whether any child shapes contain compressed ids.
+		this.mayContainCompressedIds =
+			maybeCompressedIdLeaf || fieldsArray.some(([, shape]) => shape.mayContainCompressedIds);
 		const fields: Map<FieldKey, OffsetShape> = new Map();
 		let numberOfValues = hasValue ? 1 : 0;
 		const infos: NodePositionInfo[] = [
@@ -146,7 +183,7 @@ export class TreeShape {
 	}
 
 	public equals(other: TreeShape): boolean {
-		// TODO: either dedup instances and/or store a collision resistant hash for fast compare.
+		// TODO: either dedupe instances and/or store a collision resistant hash for fast compare.
 
 		if (
 			!compareArrays(
@@ -157,10 +194,21 @@ export class TreeShape {
 		) {
 			return false;
 		}
-		return this.type === other.type && this.hasValue === other.hasValue;
+		return (
+			this.type === other.type &&
+			this.hasValue === other.hasValue &&
+			this.mayContainCompressedIds === other.mayContainCompressedIds
+		);
 	}
 
 	public withTopLevelLength(topLevelLength: number): ChunkShape {
+		if (topLevelLength < chunkShapeCacheLimit) {
+			return getOrCreate(
+				this.chunkShapeCache,
+				topLevelLength,
+				() => new ChunkShape(this, topLevelLength),
+			);
+		}
 		return new ChunkShape(this, topLevelLength);
 	}
 }
@@ -548,16 +596,20 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 	}
 
 	public get value(): Value {
-		const idCompressor = this.chunk.idCompressor;
 		const info = this.nodeInfo(CursorLocationType.Nodes);
-		// If the maybeDecompressedStringAsNumber flag is set to true, we check if the value is a number.
-		// This flag can only ever be set on string leaf nodes, so if the value is a number, we can assume it is a compressible, known stable id.
-		if (info.shape.hasValue && info.shape.maybeDecompressedStringAsNumber) {
+		if (info.shape.hasValue) {
 			const value = this.chunk.values[info.valueOffset];
-			if (typeof value === "number" && idCompressor !== undefined) {
+			// If mayContainCompressedIds is set, check if the value is a number (i.e. a compressed ID that needs decompression).
+			if (info.shape.mayContainCompressedIds && typeof value === "number") {
+				const idCompressor = this.chunk.idCompressor;
+				assert(
+					idCompressor !== undefined,
+					0xcf1 /* chunk required idCompressor but did not provide it */,
+				);
 				return idCompressor.decompress(value as SessionSpaceCompressedId);
 			}
+			return value;
 		}
-		return info.shape.hasValue ? this.chunk.values[info.valueOffset] : undefined;
+		return undefined;
 	}
 }