@fluidframework/tree 2.92.0 → 2.93.0

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,

package/src/util/index.ts

@@ -66,7 +66,6 @@ export { StackyIterator } from "./stackyIterator.js";
 export {
 	asMutable,
 	balancedReduce,
-	clone,
 	compareSets,
 	getOrAddEmptyToMap,
 	getOrCreate,

package/src/util/utils.ts

@@ -44,8 +44,6 @@ export function asMutable<T>(readonly: T): Mutable<T> {
 	return readonly as Mutable<T>;
 }
 
-export { default as clone } from "@ungap/structured-clone";
-
 /**
  * Checks whether or not the given object is a `readonly` array.
  *

package/.mocharc.customBenchmarks.cjs

@@ -1,25 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/**
- * Mocha configuration file to run memory-profiling tests
- */
-"use strict";
-
-const getFluidTestMochaConfig = require("@fluid-internal/mocha-test-setup/mocharc-common");
-
-const packageDir = __dirname;
-const baseConfig = getFluidTestMochaConfig(packageDir);
-
-baseConfig["node-option"].push("gc-global");
-
-module.exports = {
-	...baseConfig,
-	"fgrep": ["@CustomBenchmark"],
-	"recursive": true,
-	"reporter": "@fluid-tools/benchmark/dist/MochaReporter.js",
-	"reporterOptions": ["reportDir=.customBenchmarksOutput/"],
-	"spec": ["lib/test/**/*.*js"],
-};