@fluidframework/tree 2.93.0 → 2.101.0

package/src/shared-tree-core/messageCodecVSharedBranches.ts

@@ -47,6 +47,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 						schema: context.schema,
 						idCompressor: context.idCompressor,
 						revision: message.commit.revision,
+						isSummary: false,
 					};
 
 					return {
@@ -54,6 +55,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 							originatorId: message.sessionId,
 							idCompressor: context.idCompressor,
 							revision: undefined,
+							isSummary: false,
 						}),
 						originatorId: message.sessionId,
 						changeset: changeCodec.encode(message.commit.change, changeContext),
@@ -84,10 +86,11 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 				branchId: encodedBranchId,
 			} = encoded;
 
-			const changeContext = {
+			const changeContext: ChangeEncodingContext = {
 				originatorId,
 				revision: undefined,
 				idCompressor: context.idCompressor,
+				isSummary: false,
 			};
 
 			const branchId = decodeBranchId(context.idCompressor, encodedBranchId, changeContext);
@@ -107,6 +110,7 @@ export function makeSharedBranchesCodecWithVersion<TChangeset>(
 						originatorId,
 						revision,
 						idCompressor: context.idCompressor,
+						isSummary: false,
 					}),
 				},
 				branchId,

package/src/shared-tree-core/sharedTreeCore.ts

@@ -73,7 +73,12 @@ export interface ClonableSchemaAndPolicy extends SchemaAndPolicy {
 	schema: TreeStoredSchemaRepository;
 }
 
-export interface SharedTreeCoreOptionsInternal extends CodecWriteOptions {}
+export interface SharedTreeCoreOptionsInternal extends CodecWriteOptions {
+	/**
+	 * See {@link SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode}.
+	 */
+	readonly healUnresolvableIdentifiersOnDecode?: boolean;
+}
 
 export interface EnrichmentConfig<TChange> {
 	readonly enricher: ChangeEnricher<TChange>;
@@ -192,6 +197,8 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				this.idCompressor,
 				options.minVersionForCollab,
 				this.schemaAndPolicy,
+				options.healUnresolvableIdentifiersOnDecode,
+				sharedObject.id,
 			),
 			...summarizables,
 		];

package/src/simple-tree/api/schemaFactory.ts

@@ -261,7 +261,7 @@ export const SchemaFactory_base = classWithStatics(schemaStaticsPublic);
  *
  * 1. Declaration: `class X extends schemaFactory.object("x", {}) {}`
  *
- * 2. Allows adding "local" (non-persisted) members: Yes. Members (including methods) can be added to the class.
+ * 2. Allows adding "local" (non-persisted) members: additional members (including methods) can be added to the class.
  *
  * 3. Prototype: The user-defined class.
  *
@@ -281,7 +281,7 @@ export const SchemaFactory_base = classWithStatics(schemaStaticsPublic);
  *
  * 1. Declaration: `const X = schemaFactory.object("x", {}); type X = NodeFromSchema<typeof X>;`
  *
- * 2. Allows adding "local" (non-persisted) members: No. Attempting to set non-field members will result in an error.
+ * 2. Does not allow adding "local" (non-persisted) members: attempting to set non-field members will result in an error.
  *
  * 3. Prototype: `Object.prototype`, `Map.prototype`, or `Array.prototype` depending on node kind.
  *
@@ -320,7 +320,7 @@ export const SchemaFactory_base = classWithStatics(schemaStaticsPublic);
  * Note: the comparison between the customizable and POJO modes is not done in a table because TSDoc does not currently have support for embedded markdown.
  *
  * @see {@link SchemaFactoryAlpha}
- *
+ * @see {@link SchemaFactoryBeta}
  * @sealed @public
  */
 export class SchemaFactory<

package/src/simple-tree/api/schemaFactoryAlpha.ts

@@ -153,7 +153,7 @@ export interface SchemaStaticsAlpha {
 	 * The migration path is:
 	 *
 	 * 1. Start with `sf.required(T)` — all clients require the field.
-	 * 2. Deploy `sf.stagedOptional(T)` — new clients can read documents where the field is present or absent, but the stored schema stays Required (so old clients are unaffected). Writing `undefined` is blocked at runtime.
+	 * 2. Deploy `sf.stagedOptional(T)` — new clients can read documents where the field is present or absent, but the stored schema stays Required (so old clients are unaffected). Setting the field to `undefined` is rejected because the stored schema still declares the field as required.
 	 * 3. Deploy `sf.optional(T)` once all clients support the staged optional field — the stored schema becomes Optional and the field can be cleared.
 	 *
 	 * Analogous to {@link SchemaStaticsBeta.staged} for allowed types, but for field optionality.
@@ -179,6 +179,28 @@ export interface SchemaStaticsAlpha {
 		TCustomMetadata,
 		FieldPropsAlpha<TCustomMetadata>
 	>;
+	/**
+	 * {@link SchemaStaticsAlpha.stagedOptional} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStaticsAlpha.stagedOptional} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 */
+	readonly stagedOptionalRecursive: <
+		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+		const TCustomMetadata = unknown,
+	>(
+		t: T,
+		props?: Omit<
+			FieldPropsAlpha<TCustomMetadata>,
+			"defaultProvider" | "stagedOptionalUpgrade"
+		>,
+	) => FieldSchemaAlphaUnsafe<
+		FieldKind.Optional,
+		T,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata>
+	>;
 
 	/**
 	 * {@link SchemaStaticsAlpha.withDefault} except tweaked to work better for recursive types.
@@ -280,10 +302,9 @@ const stagedOptional = <const T extends ImplicitAllowedTypes, const TCustomMetad
 
 const schemaStaticsAlpha: SchemaStaticsAlpha = {
 	withDefault,
-
 	withDefaultRecursive: withDefault as SchemaStaticsAlpha["withDefaultRecursive"],
-
 	stagedOptional,
+	stagedOptionalRecursive: stagedOptional as SchemaStaticsAlpha["stagedOptionalRecursive"],
 };
 
 /**
@@ -512,6 +533,16 @@ export class SchemaFactoryAlpha<
 	 */
 	public static readonly stagedOptional = schemaStaticsAlpha.stagedOptional;
 
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.stagedOptionalRecursive}
+	 */
+	public readonly stagedOptionalRecursive = schemaStaticsAlpha.stagedOptionalRecursive;
+
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.stagedOptionalRecursive}
+	 */
+	public static readonly stagedOptionalRecursive = schemaStaticsAlpha.stagedOptionalRecursive;
+
 	/**
 	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNodeAlpha}.
 	 *

package/src/tableSchema.ts

@@ -7,7 +7,7 @@ import { fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { EmptyKey } from "./core/index.js";
-import { TreeAlpha } from "./shared-tree/index.js";
+import { Tree, TreeAlpha } from "./shared-tree/index.js";
 import {
 	type FieldHasDefault,
 	type ImplicitAllowedTypes,
@@ -951,6 +951,58 @@ export namespace System_TableSchema {
 				return cell;
 			}
 
+			// #region ID lookup caches
+
+			// Looking up rows/columns by string ID is a hot path (every getCell / setCell / etc. call goes
+			// through #tryGetRow or #tryGetColumn). Rather than scanning the arrays linearly on every call,
+			// we maintain lazily-built Maps from ID → node.
+			//
+			// Cache invalidation:
+			//   Each cache is marked stale (reset to `undefined`) by a `nodeChanged` listener registered on
+			//   the corresponding array node (this.table.rows / this.table.columns). `nodeChanged` fires on
+			//   an array node whenever an element is inserted, removed, or moved — exactly the set of
+			//   operations that could change which ID maps to which node. The event fires after the full
+			//   batch of edits has been applied (including remote edits received from collaborators), so the
+			//   cache is always rebuilt from a consistent, in-schema state.
+			//   TODO: Consider if we should do more fine-grained invalidation here. E.g. look at the specific deltas
+			//   returned by the `nodeChanged` event and only invalidate entries as needed.
+			//
+			// Listener lifetime:
+			//   The listener is registered exactly once per cache (guarded by the non-undefined check on the
+			//   stored unsubscribe callback).  Subsequent cache rebuilds after invalidation reuse the same
+			//   listener — no additional subscriptions accumulate.  The unsubscribe callback is stored so
+			//   that explicit cleanup is possible in the future if needed.
+
+			/**
+			 * Cache from row ID → row node for O(1) lookups in {@link Table.#tryGetRow}.
+			 * `undefined` means the cache is stale and must be rebuilt before use.
+			 */
+			#rowCache: Map<string, RowValueType> | undefined = undefined;
+
+			/**
+			 * Unsubscribe function for the `nodeChanged` listener on `this.table.rows`.
+			 * `undefined` means the listener has not yet been registered (first cache build is pending).
+			 * After the first build, this is always defined and the listener remains active for the
+			 * lifetime of the Table node.
+			 */
+			#rowCacheUnsubscribe: (() => void) | undefined = undefined;
+
+			/**
+			 * Cache from column ID → column node for O(1) lookups in {@link Table.#tryGetColumn}.
+			 * `undefined` means the cache is stale and must be rebuilt before use.
+			 */
+			#columnCache: Map<string, ColumnValueType> | undefined = undefined;
+
+			/**
+			 * Unsubscribe function for the `nodeChanged` listener on `this.table.columns`.
+			 * `undefined` means the listener has not yet been registered (first cache build is pending).
+			 * After the first build, this is always defined and the listener remains active for the
+			 * lifetime of the Table node.
+			 */
+			#columnCacheUnsubscribe: (() => void) | undefined = undefined;
+
+			// #endregion
+
 			/**
 			 * Applies the provided edits in a "batch".
 			 *
@@ -994,6 +1046,40 @@ export namespace System_TableSchema {
 				});
 			}
 
+			/**
+			 * Returns the column ID → column node cache, building and caching it first if stale.
+			 *
+			 * @remarks
+			 * The first time this is called, it builds the map from the current contents of
+			 * `this.table.columns` and registers a `nodeChanged` listener on that array.
+			 * The listener invalidates the cache (sets `#columnCache` to `undefined`) whenever
+			 * the column array is structurally modified (insert / remove / move), so every
+			 * subsequent call that follows a structural change automatically triggers a rebuild.
+			 * The listener is registered only once — it is not re-registered on cache rebuilds.
+			 */
+			#getColumnCache(): Map<string, ColumnValueType> {
+				let cache = this.#columnCache;
+				if (cache === undefined) {
+					cache = new Map<string, ColumnValueType>();
+					for (const column of this.table.columns) {
+						// TypeScript is unable to narrow array element types correctly here.
+						// See: https://github.com/microsoft/TypeScript/issues/52144
+						cache.set((column as ColumnValueType).id, column as ColumnValueType);
+					}
+					this.#columnCache = cache;
+
+					// Register the invalidation listener once. The `nodeChanged` event fires on the
+					// array node itself after any structural change (insert / remove / move), which is
+					// exactly the set of changes that can alter the ID → node mapping.
+					if (this.#columnCacheUnsubscribe === undefined) {
+						this.#columnCacheUnsubscribe = Tree.on(this.columns, "nodeChanged", () => {
+							this.#columnCache = undefined;
+						});
+					}
+				}
+				return cache;
+			}
+
 			/**
 			 * Attempts to resolve the provided Column node or ID to a Column node in the table.
 			 * Returns `undefined` if there is no match.
@@ -1011,21 +1097,14 @@ export namespace System_TableSchema {
 					return this.table.columns[columnOrIdOrIndex] as ColumnValueType;
 				}
 
+				const columnCache = this.#getColumnCache();
 				if (typeof columnOrIdOrIndex === "string") {
-					const columnId = columnOrIdOrIndex;
-					// TypeScript is unable to narrow the types correctly here, hence the casts.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
-					return this.table.columns.find((col) => (col as ColumnValueType).id === columnId) as
-						| ColumnValueType
-						| undefined;
+					return columnCache.get(columnOrIdOrIndex);
 				}
 
 				// If the user provided a node, ensure it actually exists in this table.
-				if (!this.table.columns.includes(columnOrIdOrIndex)) {
-					return undefined;
-				}
-
-				return columnOrIdOrIndex;
+				const cached = columnCache.get(columnOrIdOrIndex.id);
+				return cached === columnOrIdOrIndex ? columnOrIdOrIndex : undefined;
 			}
 
 			/**
@@ -1062,6 +1141,40 @@ export namespace System_TableSchema {
 				);
 			}
 
+			/**
+			 * Returns the row ID → row node cache, building and caching it first if stale.
+			 *
+			 * @remarks
+			 * The first time this is called, it builds the map from the current contents of
+			 * `this.table.rows` and registers a `nodeChanged` listener on that array.
+			 * The listener invalidates the cache (sets `#rowCache` to `undefined`) whenever
+			 * the row array is structurally modified (insert / remove / move), so every
+			 * subsequent call that follows a structural change automatically triggers a rebuild.
+			 * The listener is registered only once — it is not re-registered on cache rebuilds.
+			 */
+			#getRowCache(): Map<string, RowValueType> {
+				let cache = this.#rowCache;
+				if (cache === undefined) {
+					cache = new Map<string, RowValueType>();
+					for (const row of this.table.rows) {
+						// TypeScript is unable to narrow array element types correctly here.
+						// See: https://github.com/microsoft/TypeScript/issues/52144
+						cache.set((row as RowValueType).id, row as RowValueType);
+					}
+					this.#rowCache = cache;
+
+					// Register the invalidation listener once. The `nodeChanged` event fires on the
+					// array node itself after any structural change (insert / remove / move), which is
+					// exactly the set of changes that can alter the ID → node mapping.
+					if (this.#rowCacheUnsubscribe === undefined) {
+						this.#rowCacheUnsubscribe = Tree.on(this.rows, "nodeChanged", () => {
+							this.#rowCache = undefined;
+						});
+					}
+				}
+				return cache;
+			}
+
 			/**
 			 * Attempts to resolve the provided Row node or ID to a Row node in the table.
 			 * Returns `undefined` if there is no match.
@@ -1077,21 +1190,14 @@ export namespace System_TableSchema {
 					return this.table.rows[rowOrIdOrIndex] as RowValueType;
 				}
 
+				const rowCache = this.#getRowCache();
 				if (typeof rowOrIdOrIndex === "string") {
-					const rowId = rowOrIdOrIndex;
-					// TypeScript is unable to narrow the types correctly here, hence the casts.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
-					return this.table.rows.find((row) => (row as RowValueType).id === rowId) as
-						| RowValueType
-						| undefined;
+					return rowCache.get(rowOrIdOrIndex);
 				}
 
 				// If the user provided a node, ensure it actually exists in this table.
-				if (!this.table.rows.includes(rowOrIdOrIndex)) {
-					return undefined;
-				}
-
-				return rowOrIdOrIndex;
+				const cached = rowCache.get(rowOrIdOrIndex.id);
+				return cached === rowOrIdOrIndex ? rowOrIdOrIndex : undefined;
 			}
 
 			/**
@@ -1113,10 +1219,7 @@ export namespace System_TableSchema {
 			 * - A column with a duplicate ID is being inserted.
 			 */
 			#validateNewColumns(newColumns: readonly ColumnInsertableType[]): void {
-				return Table._validateNewColumns(
-					newColumns,
-					new Set(this.table.columns.map((column) => (column as ColumnValueType).id)),
-				);
+				return Table._validateNewColumns(newColumns, this.#getColumnCache());
 			}
 
 			/**
@@ -1126,11 +1229,7 @@ export namespace System_TableSchema {
 			 * - A row is being inserted that contains cells for columns that do not exist in the table.
 			 */
 			#validateNewRows(newRows: readonly RowInsertableType[]): void {
-				return Table._validateNewRows(
-					newRows,
-					new Set(this.table.rows.map((row) => (row as RowValueType).id)),
-					new Set(this.table.columns.map((column) => (column as ColumnValueType).id)),
-				);
+				return Table._validateNewRows(newRows, this.#getRowCache(), this.#getColumnCache());
 			}
 
 			/**
@@ -1140,7 +1239,7 @@ export namespace System_TableSchema {
 			 */
 			private static _validateNewColumns(
 				newColumns: Iterable<ColumnInsertableType>,
-				existingColumnIds: Set<string>,
+				existingColumnIds: { readonly has: (id: string) => boolean },
 			): void {
 				const newColumnIds = new Set<string>();
 				for (const newColumn of newColumns) {
@@ -1168,8 +1267,8 @@ export namespace System_TableSchema {
 			 */
 			private static _validateNewRows(
 				newRows: Iterable<RowInsertableType>,
-				existingRowIds: Set<string>,
-				columnIds: Set<string>,
+				existingRowIds: { readonly has: (id: string) => boolean },
+				columnIds: { readonly has: (id: string) => boolean },
 			): void {
 				const newRowIds = new Set<string>();
 				for (const newRow of newRows) {