@fluidframework/tree 2.91.0 → 2.93.0

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -447,6 +447,35 @@ export interface TreeArrayNode<
 	values(): IterableIterator<T>;
 }
 
+/**
+ * {@link (TreeArrayNode:interface)} with additional alpha APIs.
+ * @alpha @sealed
+ */
+export interface TreeArrayNodeAlpha<
+	TAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe = ImplicitAllowedTypes,
+	out T = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? TreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: TreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+	in TNew = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+> extends TreeArrayNode<TAllowedTypes, T, TNew> {
+	/**
+	 * Removes existing item(s) and/or adds new item(s).
+	 * @param start - The index at which to start changing the array. If negative, it is treated as `array.length + start`.
+	 * Must be a positive in bounds index or a negative index such that `array.length + start` is a positive in bounds index.
+	 * @param deleteCount - The number of item(s) to remove. If not provided, it defaults to the end of the array.
+	 * Must be a non-negative integer no greater than the number of items from `start` to the end of the array.
+	 * @param items - The item(s) to insert at `start`.
+	 * @returns An array containing the item(s) that were removed.
+	 */
+	splice(
+		start: number,
+		deleteCount?: number,
+		...items: readonly (TNew | IterableTreeArrayContent<TNew>)[]
+	): T[];
+}
+
 /**
  * A {@link TreeNode} which implements 'readonly T[]' and the array mutation APIs.
  * @public
@@ -997,6 +1026,41 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 
 		editor.remove(removeStart, removeEnd - removeStart);
 	}
+	public splice(
+		start: number,
+		deleteCount?: number,
+		...items: Insertable<T>
+	): TreeNodeFromImplicitAllowedTypes<T>[] {
+		const length = this.length;
+		const actualStart = start < 0 ? Math.max(length + start, 0) : Math.min(start, length);
+		const actualDeleteCount =
+			deleteCount === undefined
+				? length - actualStart
+				: Math.min(Math.max(deleteCount, 0), length - actualStart);
+		validateIndexRange(
+			actualStart,
+			actualStart + actualDeleteCount,
+			getSequenceField(this),
+			"TreeArrayNode.splice",
+		);
+		const removed: TreeNodeFromImplicitAllowedTypes<T>[] = [];
+		for (let index = actualStart; index < actualStart + actualDeleteCount; index++) {
+			removed.push(this.at(index) ?? oob());
+		}
+
+		const innerNode = getInnerNode(this);
+		const transaction = innerNode.isHydrated()
+			? innerNode.context.checkout.transaction
+			: undefined;
+		transaction?.start();
+		this.removeRange(actualStart, actualStart + actualDeleteCount);
+		if (items.length > 0) {
+			this.insertAt(actualStart, ...items);
+		}
+		transaction?.commit();
+		return removed;
+	}
+
 	public moveToStart(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);

package/src/simple-tree/node-kinds/array/arrayNodeTypes.ts

@@ -14,7 +14,7 @@ import type {
 } from "../../core/index.js";
 import type { SchemaType, SimpleArrayNodeSchema } from "../../simpleSchema.js";
 
-import type { TreeArrayNode } from "./arrayNode.js";
+import type { TreeArrayNode, TreeArrayNodeAlpha } from "./arrayNode.js";
 
 /**
  * A schema for customizable {@link (TreeArrayNode:interface)}s.
@@ -37,6 +37,30 @@ export interface ArrayNodeCustomizableSchema<
 		>,
 		SimpleArrayNodeSchema<SchemaType.View, TCustomMetadata> {}
 
+/**
+ * A Schema for customizable {@link (TreeArrayNode:interface)}s with additional alpha APIs.
+ * @remarks
+ * Duplicates {@link ArrayNodeCustomizableSchema} with {@link TreeArrayNodeAlpha} as the node type,
+ * adding support for the alpha APIs on those nodes.
+ * @system @sealed @alpha
+ */
+export interface ArrayNodeCustomizableSchemaAlpha<
+	out TName extends string = string,
+	in out T extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	out ImplicitlyConstructable extends boolean = true,
+	out TCustomMetadata = unknown,
+> extends TreeNodeSchemaClass<
+			TName,
+			NodeKind.Array,
+			TreeArrayNodeAlpha<T> & WithType<TName, NodeKind.Array, T>,
+			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
+			ImplicitlyConstructable,
+			T,
+			undefined,
+			TCustomMetadata
+		>,
+		SimpleArrayNodeSchema<SchemaType.View, TCustomMetadata> {}
+
 /**
  * A schema for POJO emulation mode {@link (TreeArrayNode:interface)}s.
  * @system @sealed @alpha

package/src/simple-tree/node-kinds/array/index.ts

@@ -10,10 +10,12 @@ export {
 	TreeArrayNode,
 	type ReadonlyArrayNode,
 	type ArrayPlaceAnchor,
+	type TreeArrayNodeAlpha,
 	createArrayInsertionAnchor,
 } from "./arrayNode.js";
 export {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 	isArrayNodeSchema,

package/src/simple-tree/node-kinds/index.ts

@@ -5,6 +5,7 @@
 
 export {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 	arraySchema,
@@ -12,6 +13,7 @@ export {
 	isArrayNodeSchema,
 	IterableTreeArrayContent,
 	TreeArrayNode,
+	type TreeArrayNodeAlpha,
 	type ReadonlyArrayNode,
 	type ArrayPlaceAnchor,
 	createArrayInsertionAnchor,
@@ -25,6 +27,7 @@ export {
 	MapNodeSchema,
 	mapSchema,
 	type TreeMapNode,
+	type TreeMapNodeAlpha,
 } from "./map/index.js";
 
 export {

package/src/simple-tree/node-kinds/map/index.ts

@@ -7,6 +7,7 @@ export {
 	type MapNodeInsertableData,
 	mapSchema,
 	type TreeMapNode,
+	type TreeMapNodeAlpha,
 } from "./mapNode.js";
 export {
 	isMapNodeSchema,

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { FluidReadonlyMap } from "@fluidframework/core-interfaces/internal";
 import { assert, Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -152,10 +153,25 @@ export interface TreeMapNode<T extends ImplicitAllowedTypes = ImplicitAllowedTyp
 	): void;
 }
 
+/**
+ * {@link TreeMapNode} with FluidReadonlyMap-based iteration.
+ *
+ * @remarks
+ * This is the same as {@link TreeMapNode} except that it extends FluidReadonlyMap
+ * instead of the built-in `ReadonlyMap`, insulating against breaking changes
+ * in TypeScript's standard library iterator types.
+ *
+ * @sealed @alpha
+ */
+export interface TreeMapNodeAlpha<T extends ImplicitAllowedTypes = ImplicitAllowedTypes>
+	extends FluidReadonlyMap<string, TreeNodeFromImplicitAllowedTypes<T>>,
+		TreeNode,
+		Pick<TreeMapNode<T>, "set" | "delete"> {}
+
 // TreeMapNode is invariant over schema type, so for this handler to work with all schema, the only possible type for the schema is `any`.
 // This is not ideal, but no alternatives are possible.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const handler: ProxyHandler<TreeMapNode<any>> = {
+const handler: ProxyHandler<TreeMapNodeAlpha<any>> = {
 	getPrototypeOf: () => {
 		return Map.prototype;
 	},
@@ -239,7 +255,7 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 			yield value;
 		}
 	}
-	public forEach<TThis extends TreeMapNode<T>>(
+	public forEach<TThis extends TreeMapNodeAlpha<T>>(
 		this: TThis,
 		callbackFn: (value: TreeNodeFromImplicitAllowedTypes<T>, key: string, map: TThis) => void,
 		thisArg?: unknown,
@@ -283,7 +299,8 @@ export function mapSchema<
 	let privateData: TreeNodeSchemaPrivateData | undefined;
 	const persistedMetadata = nodeOptions.persistedMetadata;
 
-	class Schema extends CustomMapNodeBase<T> implements TreeMapNode<T> {
+	class Schema extends CustomMapNodeBase<T> implements TreeMapNodeAlpha<T> {
+		public readonly [Symbol.toStringTag] = "TreeMapNodeSchema";
 		public static override prepareInstance<T2>(
 			this: typeof TreeNodeValid<T2>,
 			instance: TreeNodeValid<T2>,

package/src/simple-tree/node-kinds/map/mapNodeTypes.ts

@@ -13,10 +13,10 @@ import type {
 } from "../../core/index.js";
 import type { SchemaType, SimpleMapNodeSchema } from "../../simpleSchema.js";
 
-import type { MapNodeInsertableData, TreeMapNode } from "./mapNode.js";
+import type { MapNodeInsertableData, TreeMapNodeAlpha } from "./mapNode.js";
 
 /**
- * A schema for customizable {@link (TreeMapNode:interface)}s.
+ * A schema for customizable {@link (TreeMapNodeAlpha:interface)}s.
  * @system @sealed @alpha
  */
 export interface MapNodeCustomizableSchema<
@@ -27,7 +27,7 @@ export interface MapNodeCustomizableSchema<
 > extends TreeNodeSchemaClass<
 			TName,
 			NodeKind.Map,
-			TreeMapNode<T> & WithType<TName, NodeKind.Map, T>,
+			TreeMapNodeAlpha<T> & WithType<TName, NodeKind.Map, T>,
 			MapNodeInsertableData<T>,
 			ImplicitlyConstructable,
 			T,
@@ -37,7 +37,7 @@ export interface MapNodeCustomizableSchema<
 		SimpleMapNodeSchema<SchemaType.View, TCustomMetadata> {}
 
 /**
- * A schema for POJO emulation mode {@link (TreeMapNode:interface)}s.
+ * A schema for POJO emulation mode {@link (TreeMapNodeAlpha:interface)}s.
  * @system @sealed @alpha
  */
 export interface MapNodePojoEmulationSchema<
@@ -48,7 +48,7 @@ export interface MapNodePojoEmulationSchema<
 > extends TreeNodeSchemaNonClass<
 			TName,
 			NodeKind.Map,
-			TreeMapNode<T> & WithType<TName, NodeKind.Map, T>,
+			TreeMapNodeAlpha<T> & WithType<TName, NodeKind.Map, T>,
 			MapNodeInsertableData<T>,
 			ImplicitlyConstructable,
 			T,
@@ -58,7 +58,7 @@ export interface MapNodePojoEmulationSchema<
 		SimpleMapNodeSchema<SchemaType.View, TCustomMetadata> {}
 
 /**
- * A schema for {@link (TreeMapNode:interface)}s.
+ * A schema for {@link (TreeMapNodeAlpha:interface)}s.
  * @privateRemarks
  * This could have generic arguments added and forwarded.
  * The expected use-cases for this don't need them however, and if they did want an argument it would probably be the allowed types;

package/src/simple-tree/simpleSchema.ts

@@ -286,6 +286,26 @@ export interface SimpleFieldSchema<Type extends SchemaType = SchemaType> {
 	 * Set via {@link FieldPropsAlpha.persistedMetadata}.
 	 */
 	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
+
+	/**
+	 * Indicates that this field is a {@link SchemaStaticsAlpha.stagedOptional | staged optional} field,
+	 * allowing the view schema to be compatible with stored schema where the field is required (pre-upgrade) or optional (post-upgrade).
+	 * New documents and schema upgrades will keep the field as required in the stored schema.
+	 *
+	 * `false` if this is a view schema field that is not staged optional.
+	 * Absent (`undefined`) if derived from a stored schema (where staged optional has no meaning).
+	 *
+	 * `false` and `undefined` are both "not staged optional," but distinct: `false` means "view schema field, not staged
+	 * optional" while `undefined` means "stored schema field." Consumers that need to check for staged optional should
+	 * compare against `false` (e.g., `!== false`) rather than checking truthiness.
+	 *
+	 * @privateRemarks
+	 * Analogous to {@link SimpleAllowedTypeAttributes.isStaged} for allowed types.
+	 * Optional (`?`) so that existing code constructing `SimpleFieldSchema` object literals does not need to be updated.
+	 */
+	readonly isStagedOptional?: Type extends SchemaType.Stored
+		? undefined
+		: false | SchemaUpgrade;
 }
 
 /**

package/src/simple-tree/toStoredSchema.ts

@@ -36,6 +36,7 @@ import {
 import {
 	ExpectStored,
 	NodeKind,
+	SchemaUpgrade,
 	Unchanged,
 	type SimpleSchemaTransformationOptions,
 	type StoredFromViewSchemaGenerationOptions,
@@ -76,6 +77,7 @@ const viewToStoredCache = new WeakMap<
 export const restrictiveStoredSchemaGenerationOptions: StoredFromViewSchemaGenerationOptions =
 	{
 		includeStaged: () => false,
+		includeStagedOptional: () => false,
 	};
 
 /**
@@ -92,6 +94,7 @@ export const restrictiveStoredSchemaGenerationOptions: StoredFromViewSchemaGener
  */
 export const permissiveStoredSchemaGenerationOptions: StoredFromViewSchemaGenerationOptions = {
 	includeStaged: () => true,
+	includeStagedOptional: () => true,
 };
 
 /**
@@ -423,8 +426,12 @@ function filterFieldAllowedTypes(
 	f: SimpleFieldSchema,
 	options: SimpleSchemaTransformationOptions,
 ): SimpleFieldSchema {
+	const isStagedOptional =
+		preservesViewData(options) && f.isStagedOptional instanceof SchemaUpgrade
+			? f.isStagedOptional
+			: undefined;
 	return {
-		kind: f.kind,
+		kind: getStoredFieldKind(f, options),
 		persistedMetadata: f.persistedMetadata,
 		metadata: preservesViewData(options)
 			? {
@@ -433,9 +440,29 @@ function filterFieldAllowedTypes(
 				}
 			: {},
 		simpleAllowedTypes: filterAllowedTypes(f.simpleAllowedTypes, options),
+		...(isStagedOptional === undefined ? {} : { isStagedOptional }),
 	};
 }
 
+/**
+ * Returns the field kind to use in the stored schema for the given view field schema.
+ * @remarks
+ * For {@link SchemaFactoryAlpha.stagedOptional | staged optional} fields, the stored field kind is Required
+ * when the staged optional is not being included (i.e., restrictive options).
+ */
+function getStoredFieldKind(
+	f: SimpleFieldSchema,
+	options: SimpleSchemaTransformationOptions,
+): FieldKind {
+	if (!isStoredFromView(options)) {
+		return f.kind;
+	}
+	const { isStagedOptional } = f;
+	if (isStagedOptional === undefined || isStagedOptional === false) return f.kind;
+	// isStagedOptional is a SchemaUpgrade — use includeStagedOptional to decide the stored kind.
+	return options.includeStagedOptional(isStagedOptional) ? f.kind : FieldKind.Required;
+}
+
 /**
  * Converts a stored {@link SimpleAllowedTypes} to a {@link TreeTypeSet}.
  */

package/src/tableSchema.ts

@@ -8,13 +8,13 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { EmptyKey } from "./core/index.js";
 import { TreeAlpha } from "./shared-tree/index.js";
-import type { SchemaFactoryBeta } from "./simple-tree/index.js";
 import {
 	type FieldHasDefault,
 	type ImplicitAllowedTypes,
 	type InsertableObjectFromSchemaRecord,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
 	type NodeKind,
+	type SchemaFactoryBeta,
 	type ScopedSchemaName,
 	TreeArrayNode,
 	type TreeNode,
@@ -32,8 +32,12 @@ import {
 	type TreeRecordNode,
 	objectSchema,
 	eraseSchemaDetailsSubclassable,
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports -- This makes the API report slightly cleaner.
+	// #region Unused imports to make d.ts cleaner
+	/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars */
 	TreeNodeSchemaCore,
+	FieldKind,
+	/* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars */
+	// #endregion
 	type TransactionConstraintAlpha,
 	createCustomizedFluidFrameworkScopedFactory,
 } from "./simple-tree/index.js";
@@ -792,7 +796,12 @@ export namespace System_TableSchema {
 
 							// First, remove all cells that correspond to each column from each row:
 							for (const column of columnsToRemove) {
-								this.#removeCells(column);
+								for (const row of this.table.rows) {
+									// TypeScript is unable to narrow the row type correctly here, hence the cast.
+									// See: https://github.com/microsoft/TypeScript/issues/52144
+									// eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- This is currently how Record node entries are deleted.
+									delete (row as RowValueInternalType).cells[column.id];
+								}
 							}
 
 							// Second, remove the column nodes:
@@ -830,10 +839,8 @@ export namespace System_TableSchema {
 								for (const row of this.table.rows) {
 									// TypeScript is unable to narrow the row type correctly here, hence the cast.
 									// See: https://github.com/microsoft/TypeScript/issues/52144
-									this.removeCell({
-										column: columnToRemove,
-										row: row as RowValueType,
-									});
+									// eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- This is currently how Record node entries are deleted.
+									delete (row as RowValueInternalType).cells[columnToRemove.id];
 								}
 
 								// We have already validated that all of the columns exist above, so this is safe.
@@ -930,7 +937,7 @@ export namespace System_TableSchema {
 
 				this.#applyEditsInBatch({
 					applyEdits: () => {
-						// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+						// eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- This is currently how Record node entries are deleted.
 						delete row.cells[column.id];
 					},
 					// Relevant invariant: each cell corresponds to an existing row and column
@@ -938,31 +945,12 @@ export namespace System_TableSchema {
 					// Example scenario: Client A removes a cell, then Client B removes the column for that cell.
 					// If A's cell removal is later reverted, the cell would be restored but B's column removal means there's no column for it.
 					// This constraint on revert ensures the column still exists, ensuring restored cells correspond to existing columns.
-					preconditionsOnRevert: [
-						{
-							type: "nodeInDocument",
-							node: column,
-						},
-					],
+					preconditionsOnRevert: [{ type: "nodeInDocument", node: column }],
 				});
 
 				return cell;
 			}
 
-			/**
-			 * Removes the cell corresponding with the specified column from each row in the table.
-			 */
-			#removeCells(column: ColumnValueType): void {
-				for (const row of this.table.rows) {
-					// TypeScript is unable to narrow the row type correctly here, hence the cast.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
-					this.removeCell({
-						column,
-						row: row as RowValueType,
-					});
-				}
-			}
-
 			/**
 			 * Applies the provided edits in a "batch".
 			 *

package/src/text/textDomain.ts

@@ -4,6 +4,14 @@
  */
 
 import { compareArrays, debugAssert } from "@fluidframework/core-utils/internal";
+import {
+	buildFunc,
+	exposeMethodsSymbol,
+	type ExposedMethods,
+	type IExposedMethods,
+	// eslint-disable-next-line import-x/no-internal-modules
+} from "@fluidframework/type-factory/alpha";
+import { typeFactory as tf } from "@fluidframework/type-factory/internal";
 
 import { EmptyKey, mapCursorField, type ITreeCursorSynchronous } from "../core/index.js";
 import {
@@ -26,8 +34,67 @@ class TextNode
 	extends sf.object("Text", {
 		content: SchemaFactory.required([() => StringArray], { key: EmptyKey }),
 	})
-	implements TextAsTree.Members
+	implements TextAsTree.Members, IExposedMethods
 {
+	public static [exposeMethodsSymbol](methods: ExposedMethods): void {
+		methods.exposeMethod(
+			TextNode,
+			"insertAt",
+			buildFunc(
+				{
+					description:
+						"Insert characters into the text at the given character index (Unicode code points).",
+					returns: tf.void(),
+				},
+				["index", tf.number()],
+				["additionalCharacters", tf.string()],
+			),
+		);
+		methods.exposeMethod(
+			TextNode,
+			"removeRange",
+			buildFunc(
+				{
+					description:
+						"Remove a range of characters from the text by character index (Unicode code points). startIndex defaults to 0 and endIndex defaults to the length of the text.",
+					returns: tf.void(),
+				},
+				["startIndex", tf.union([tf.number(), tf.undefined()])],
+				["endIndex", tf.union([tf.number(), tf.undefined()])],
+			),
+		);
+		methods.exposeMethod(
+			TextNode,
+			"fullString",
+			buildFunc({
+				description: "Return a copy of this text node's content as a string.",
+				returns: tf.string(),
+			}),
+		);
+		methods.exposeMethod(
+			TextNode,
+			"characterCount",
+			buildFunc({
+				description:
+					"Gets the number of characters (Unicode code points) currently in the text. Joined emojis and other grapheme clusters count as multiple characters.",
+				returns: tf.number(),
+			}),
+		);
+		methods.exposeMethod(
+			TextNode,
+			"charactersCopy",
+			buildFunc({
+				description:
+					"Returns all characters in the text as an array, where each element is a single Unicode code point. Joined emojis and other grapheme clusters are split into separate elements.",
+				returns: tf.array(tf.string()),
+			}),
+		);
+	}
+
+	public [exposeMethodsSymbol](methods: ExposedMethods): void {
+		TextNode[exposeMethodsSymbol](methods);
+	}
+
 	public insertAt(index: number, additionalCharacters: string): void {
 		this.content.insertAt(
 			index,