@fluidframework/tree 2.52.0 → 2.53.0

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -7,7 +7,11 @@ import { assert, Lazy, fail, debugAssert } from "@fluidframework/core-utils/inte
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
-import type { FieldKey } from "../../../core/index.js";
+import {
+	ObjectNodeStoredSchema,
+	type FieldKey,
+	type TreeFieldStoredSchema,
+} from "../../../core/index.js";
 import {
 	FieldKinds,
 	isTreeValue,
@@ -86,7 +90,7 @@ import {
 	type FactoryContentObject,
 	type InsertableContent,
 } from "../../unhydratedFlexTreeFromInsertable.js";
-import { convertFieldKind } from "../../toStoredSchema.js";
+import { convertField, convertFieldKind } from "../../toStoredSchema.js";
 
 /**
  * Generates the properties for an ObjectNode from its field schema object.
@@ -288,10 +292,19 @@ function createProxyHandler(
 					: false;
 			}
 
+			const innerNode = getOrCreateInnerNode(proxy);
+
+			const innerSchema = innerNode.context.schema.nodeSchema.get(brand(schema.identifier));
+			assert(
+				innerSchema instanceof ObjectNodeStoredSchema,
+				0xc18 /* Expected ObjectNodeStoredSchema */,
+			);
+
 			setField(
-				getOrCreateInnerNode(proxy).getBoxed(fieldInfo.storedKey),
+				innerNode.getBoxed(fieldInfo.storedKey),
 				fieldInfo.schema,
 				value,
+				innerSchema.getFieldSchema(fieldInfo.storedKey),
 			);
 			return true;
 		},
@@ -348,8 +361,14 @@ export function setField(
 	field: FlexTreeField,
 	simpleFieldSchema: FieldSchema,
 	value: InsertableContent | undefined,
+	destinationSchema: TreeFieldStoredSchema,
 ): void {
-	const mapTree = prepareForInsertion(value, simpleFieldSchema, field.context);
+	const mapTree = prepareForInsertion(
+		value,
+		simpleFieldSchema,
+		field.context,
+		destinationSchema,
+	);
 
 	switch (field.schema) {
 		case FieldKinds.required.identifier: {
@@ -585,6 +604,20 @@ export function objectSchema<
 					flexKeyMap.values(),
 					({ schema }) => normalizeFieldSchema(schema).annotatedAllowedTypes,
 				),
+				(storedOptions) => {
+					const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
+					for (const fieldSchema of flexKeyMap.values()) {
+						assert(
+							fieldSchema.schema instanceof FieldSchemaAlpha,
+							0xc19 /* Expected FieldSchemaAlpha */,
+						);
+						fields.set(
+							brand(fieldSchema.storedKey),
+							convertField(fieldSchema.schema, storedOptions),
+						);
+					}
+					return new ObjectNodeStoredSchema(fields, persistedMetadata);
+				},
 			));
 		}
 	}

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { Lazy } from "@fluidframework/core-utils/internal";
+import { assert, Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { type JsonCompatibleReadOnlyObject, brand } from "../../../util/index.js";
@@ -34,6 +34,7 @@ import {
 	type FlexContent,
 	CompatibilityLevel,
 	type TreeNodeSchemaPrivateData,
+	convertAllowedTypes,
 } from "../../core/index.js";
 import { getTreeNodeSchemaInitializedData } from "../../createContext.js";
 import { tryGetTreeNodeForField } from "../../getTreeNodeForField.js";
@@ -51,12 +52,14 @@ import type {
 	TreeRecordNode,
 } from "./recordNodeTypes.js";
 import {
+	FieldKinds,
 	isTreeValue,
 	type FlexTreeNode,
 	type FlexTreeOptionalField,
 } from "../../../feature-libraries/index.js";
 import { prepareForInsertion } from "../../prepareForInsertion.js";
 import { recordLikeDataToFlexContent } from "../common.js";
+import { MapNodeStoredSchema } from "../../../core/index.js";
 
 /**
  * Create a proxy which implements the {@link TreeRecordNode} API.
@@ -122,11 +125,17 @@ function createRecordNodeProxy(
 			const innerNode = getOrCreateInnerNode(receiver);
 			const field = innerNode.getBoxed(brand(key)) as FlexTreeOptionalField;
 			const kernel = getKernel(receiver);
+			const innerSchema = innerNode.context.schema.nodeSchema.get(brand(schema.identifier));
+			assert(
+				innerSchema instanceof MapNodeStoredSchema,
+				0xc1a /* Expected MapNodeStoredSchema */,
+			);
 
 			const mapTree = prepareForInsertion(
 				value,
 				createFieldSchema(FieldKind.Optional, kernel.schema.info as ImplicitAllowedTypes),
 				innerNode.context,
+				innerSchema.mapFields,
 			);
 
 			field.editor.set(mapTree, field.length === 0);
@@ -390,7 +399,19 @@ export function recordSchema<
 		}
 
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
-			return (privateData ??= createTreeNodeSchemaPrivateData(this, [info]));
+			return (privateData ??= createTreeNodeSchemaPrivateData(
+				this,
+				[info],
+				(storedOptions) =>
+					new MapNodeStoredSchema(
+						{
+							kind: FieldKinds.optional.identifier,
+							types: convertAllowedTypes(info, storedOptions),
+							persistedMetadata,
+						},
+						persistedMetadata,
+					),
+			));
 		}
 	}
 

package/src/simple-tree/prepareForInsertion.ts

@@ -11,6 +11,7 @@ import type {
 	FieldKey,
 	DetachedField,
 	TreeFieldStoredSchema,
+	TreeTypeSet,
 } from "../core/index.js";
 import {
 	type FlexTreeContext,
@@ -21,7 +22,7 @@ import {
 	type FlexibleNodeContent,
 	throwOutOfSchema,
 } from "../feature-libraries/index.js";
-import { normalizeFieldSchema, type ImplicitAnnotatedFieldSchema } from "./fieldSchema.js";
+import type { ImplicitAnnotatedFieldSchema } from "./fieldSchema.js";
 import {
 	type InsertableContent,
 	unhydratedFlexTreeFromInsertable,
@@ -36,7 +37,6 @@ import {
 } from "./core/index.js";
 import { debugAssert, oob } from "@fluidframework/core-utils/internal";
 import { isFieldInSchema } from "../feature-libraries/index.js";
-import { convertField } from "./toStoredSchema.js";
 
 /**
  * For now, schema validation for inserted content is always enabled.
@@ -58,12 +58,14 @@ export function prepareForInsertion<TIn extends InsertableContent | undefined>(
 	data: TIn,
 	schema: ImplicitAnnotatedFieldSchema,
 	destinationContext: FlexTreeContext,
+	destinationSchema: TreeFieldStoredSchema,
 ): TIn extends undefined ? undefined : FlexibleNodeContent {
 	return prepareForInsertionContextless(
 		data,
 		schema,
 		getSchemaAndPolicy(destinationContext),
 		destinationContext.isHydrated() ? destinationContext : undefined,
+		destinationSchema,
 	);
 }
 
@@ -84,19 +86,18 @@ export function prepareArrayContentForInsertion(
 	data: readonly InsertableContent[],
 	schema: ImplicitAnnotatedAllowedTypes,
 	destinationContext: FlexTreeContext,
+	destinationSchema: TreeTypeSet,
 ): FlexibleFieldContent {
 	const mapTrees: UnhydratedFlexTreeNode[] = data.map((item) =>
 		unhydratedFlexTreeFromInsertable(item, schema),
 	);
 
-	const fieldSchema = convertField(normalizeFieldSchema(schema));
-
 	validateAndPrepare(
 		getSchemaAndPolicy(destinationContext),
 		destinationContext.isHydrated() ? destinationContext : undefined,
 		{
 			kind: FieldKinds.sequence.identifier,
-			types: fieldSchema.types,
+			types: destinationSchema,
 			persistedMetadata: undefined,
 		},
 		mapTrees,
@@ -119,12 +120,12 @@ export function prepareForInsertionContextless<TIn extends InsertableContent | u
 	schema: ImplicitAnnotatedFieldSchema,
 	schemaAndPolicy: SchemaAndPolicy,
 	hydratedData: FlexTreeHydratedContextMinimal | undefined,
+	destinationSchema: TreeFieldStoredSchema,
 ): TIn extends undefined ? undefined : FlexibleNodeContent {
 	const mapTree = unhydratedFlexTreeFromInsertable(data, schema);
 
 	const contentArray = mapTree === undefined ? [] : [mapTree];
-	const fieldSchema = convertField(normalizeFieldSchema(schema));
-	validateAndPrepare(schemaAndPolicy, hydratedData, fieldSchema, contentArray);
+	validateAndPrepare(schemaAndPolicy, hydratedData, destinationSchema, contentArray);
 
 	return mapTree;
 }
@@ -146,6 +147,10 @@ function validateAndPrepare(
 		// This ensures that when `isFieldInSchema` requests identifiers (or any other contextual defaults),
 		// they were already creating used the more specific context we have access to from `hydratedData`.
 		prepareContentForHydration(mapTrees, hydratedData.checkout.forest, hydratedData);
+		// TODO: AB#45723
+		// Now that staged schema rely on this validation, its a bit odd we don't do it for insertion into unhydrated contexts.
+		// We can't simply enable it for them however due to contextual default fields which would not have been created yet (see comment above).
+		// Specifically at least clone can result in unhydrated trees which can end up violating their stored schema (but not view schema) just using the type safe APIs.
 		if (validateSchema === true) {
 			isFieldInSchema(mapTrees, fieldSchema, schemaAndPolicy, throwOutOfSchema);
 		}

package/src/simple-tree/simpleSchema.ts

@@ -5,7 +5,7 @@
 
 import type { ValueSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
-import type { NodeKind, NodeSchemaMetadata } from "./core/index.js";
+import type { NodeKind, SimpleNodeSchemaBase } from "./core/index.js";
 import type { FieldKind, FieldSchemaMetadata } from "./fieldSchema.js";
 
 /*
@@ -13,30 +13,6 @@ import type { FieldKind, FieldSchemaMetadata } from "./fieldSchema.js";
  * - Customize their JSON serialization to use these formats or provide some other serialization scheme.
  */
 
-/**
- * Base interface for {@link TreeNodeSchema} and {@link SimpleNodeSchema} types.
- * Once simple schema is stable this doesn't have a reason to be kept `@system`, but it could be.
- * @system
- * @public
- * @sealed
- */
-export interface SimpleNodeSchemaBase<
-	out TNodeKind extends NodeKind,
-	out TCustomMetadata = unknown,
-> {
-	/**
-	 * The {@link NodeKind}.
-	 *
-	 * @remarks can be used to type-switch between implementations.
-	 */
-	readonly kind: TNodeKind;
-
-	/**
-	 * User-provided {@link NodeSchemaMetadata} for this schema.
-	 */
-	readonly metadata: NodeSchemaMetadata<TCustomMetadata>;
-}
-
 /**
  * A {@link SimpleNodeSchema} containing fields for alpha features.
  *
@@ -230,7 +206,11 @@ export interface SimpleTreeSchema {
 	/**
 	 * The complete set of node schema definitions recursively referenced by the tree's {@link SimpleTreeSchema.root}.
 	 *
-	 * @remarks the keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
+	 * @remarks
+	 * The keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
+	 *
+	 * Information about if a schema is {@link SchemaStaticsAlpha.staged | staged} or not is not available as the "Simple Schema" layer of abstraction: they are included unconditionally.
+	 * Options for filtering out staged schemas from view schema are available in {@link extractPersistedSchema}.
 	 */
 	readonly definitions: ReadonlyMap<string, SimpleNodeSchema>;
 }

package/src/simple-tree/toStoredSchema.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
+import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -20,27 +20,81 @@ import {
 	type TreeTypeSet,
 } from "../core/index.js";
 import { FieldKinds, type FlexFieldKind } from "../feature-libraries/index.js";
-import { brand, getOrCreate } from "../util/index.js";
+import { brand, getOrCreate, type JsonCompatibleReadOnlyObject } from "../util/index.js";
 
-import { NodeKind } from "./core/index.js";
-import { FieldKind, normalizeFieldSchema, type ImplicitFieldSchema } from "./fieldSchema.js";
-import type {
-	SimpleFieldSchema,
-	SimpleNodeSchema,
-	SimpleNodeSchemaBase,
-	SimpleTreeSchema,
-} from "./simpleSchema.js";
+import {
+	allowedTypeFilter,
+	convertAllowedTypes,
+	getTreeNodeSchemaPrivateData,
+	isClassBasedSchema,
+	NodeKind,
+	type SimpleNodeSchemaBase,
+	type StoredSchemaGenerationOptions,
+} from "./core/index.js";
+import {
+	FieldKind,
+	FieldSchemaAlpha,
+	normalizeFieldSchema,
+	type ImplicitAnnotatedFieldSchema,
+	type ImplicitFieldSchema,
+} from "./fieldSchema.js";
+import type { SimpleFieldSchema, SimpleNodeSchema } from "./simpleSchema.js";
 import { walkFieldSchema } from "./walkFieldSchema.js";
 
-const viewToStoredCache = new WeakMap<ImplicitFieldSchema, TreeStoredSchema>();
+const viewToStoredCache = new WeakMap<
+	StoredSchemaGenerationOptions,
+	WeakMap<ImplicitFieldSchema, TreeStoredSchema>
+>();
+
+export const restrictiveStoredSchemaGenerationOptions: StoredSchemaGenerationOptions = {
+	includeStaged: () => false,
+};
+
+export const permissiveStoredSchemaGenerationOptions: StoredSchemaGenerationOptions = {
+	includeStaged: () => true,
+};
+
+/**
+ * Converts a {@link ImplicitAnnotatedFieldSchema} into a {@link TreeStoredSchema} for use in schema upgrades.
+ *
+ * TODO: once upgrades are more flexible, this should take in more options, including the old schema and specific upgrades to enable.
+ */
+export function toUpgradeSchema(root: ImplicitAnnotatedFieldSchema): TreeStoredSchema {
+	return toStoredSchema(root, restrictiveStoredSchemaGenerationOptions);
+}
+
+/**
+ * Converts a {@link ImplicitAnnotatedFieldSchema} into a {@link TreeStoredSchema} for use as initial document schema.
+ */
+export function toInitialSchema(root: ImplicitAnnotatedFieldSchema): TreeStoredSchema {
+	return toStoredSchema(root, restrictiveStoredSchemaGenerationOptions);
+}
+
+/**
+ * Converts a {@link ImplicitAnnotatedFieldSchema} into a {@link TreeStoredSchema} to used for unhydrated nodes.
+ * @remarks
+ * This allows as much as possible, relying on further validation when inserting the content.
+ *
+ * TODO: this should get additional options to enable support for unknown optional fields.
+ */
+export const toUnhydratedSchema = permissiveStoredSchemaGenerationOptions;
 
 /**
- * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema}.
+ * Converts a {@link ImplicitAnnotatedFieldSchema} into a {@link TreeStoredSchema}.
+ *
+ * @privateRemarks
+ * TODO:#38722 When runtime schema upgrades are implemented, this will need to be updated to check if
+ * a staged allowed type has been upgraded and if so, include it in the conversion.
+ *
  * @throws
  * Throws a `UsageError` if multiple schemas are encountered with the same identifier.
  */
-export function toStoredSchema(root: ImplicitFieldSchema): TreeStoredSchema {
-	return getOrCreate(viewToStoredCache, root, () => {
+export function toStoredSchema(
+	root: ImplicitAnnotatedFieldSchema,
+	options: StoredSchemaGenerationOptions,
+): TreeStoredSchema {
+	const cache = getOrCreate(viewToStoredCache, options, () => new WeakMap());
+	return getOrCreate(cache, root, () => {
 		const normalized = normalizeFieldSchema(root);
 		const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
 		walkFieldSchema(normalized, {
@@ -55,42 +109,39 @@ export function toStoredSchema(root: ImplicitFieldSchema): TreeStoredSchema {
 				}
 				nodeSchema.set(
 					brand(schema.identifier),
-					getStoredSchema(schema as SimpleNodeSchemaBase<NodeKind> as SimpleNodeSchema),
+					getStoredSchema(
+						schema as SimpleNodeSchemaBase<NodeKind> as SimpleNodeSchema,
+						options,
+					),
 				);
 			},
+			allowedTypeFilter: (allowedType) => allowedTypeFilter(allowedType, options),
 		});
 
 		const result: TreeStoredSchema = {
 			nodeSchema,
-			rootFieldSchema: convertField(normalized),
+			rootFieldSchema: convertField(normalized, options),
 		};
 		return result;
 	});
 }
 
-/**
- * Converts a {@link SimpleTreeSchema} into a {@link TreeStoredSchema}.
- */
-export function simpleToStoredSchema(root: SimpleTreeSchema): TreeStoredSchema {
-	const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
-	for (const [identifier, schema] of root.definitions) {
-		nodeSchema.set(brand(identifier), getStoredSchema(schema));
-	}
-
-	const result: TreeStoredSchema = {
-		nodeSchema,
-		rootFieldSchema: convertField(root.root),
-	};
-	return result;
-}
-
 /**
  * Normalizes an {@link ImplicitFieldSchema} into a {@link TreeFieldSchema}.
  */
-export function convertField(schema: SimpleFieldSchema): TreeFieldStoredSchema {
+export function convertField(
+	schema: SimpleFieldSchema | FieldSchemaAlpha,
+	options: StoredSchemaGenerationOptions,
+): TreeFieldStoredSchema {
 	const kind: FieldKindIdentifier =
 		convertFieldKind.get(schema.kind)?.identifier ?? fail(0xae3 /* Invalid field kind */);
-	const types: TreeTypeSet = schema.allowedTypesIdentifiers as TreeTypeSet;
+	let types: TreeTypeSet;
+	// eslint-disable-next-line unicorn/prefer-ternary
+	if (schema instanceof FieldSchemaAlpha) {
+		types = convertAllowedTypes(schema.annotatedAllowedTypesNormalized, options);
+	} else {
+		types = schema.allowedTypesIdentifiers as TreeTypeSet;
+	}
 	return { kind, types, persistedMetadata: schema.persistedMetadata };
 }
 
@@ -114,11 +165,16 @@ export const convertFieldKind: ReadonlyMap<FieldKind, FlexFieldKind> = new Map<
  * TODO: AB#43548: Using a stored schema for unhydrated flex trees does not handle schema evolution features like "allowUnknownOptionalFields".
  * Usage of this and the conversion which wrap it should be audited and reduced.
  */
-export function getStoredSchema(schema: SimpleNodeSchema): TreeNodeStoredSchema {
+export function getStoredSchema(
+	schema: SimpleNodeSchema,
+	options: StoredSchemaGenerationOptions,
+): TreeNodeStoredSchema {
+	if (isClassBasedSchema(schema)) {
+		return getTreeNodeSchemaPrivateData(schema).toStored(options);
+	}
 	const kind = schema.kind;
 	switch (kind) {
 		case NodeKind.Leaf: {
-			assert(schema.kind === NodeKind.Leaf, 0xa4a /* invalid kind */);
 			return new LeafNodeStoredSchema(schema.leafKind);
 		}
 		case NodeKind.Map:
@@ -136,18 +192,12 @@ export function getStoredSchema(schema: SimpleNodeSchema): TreeNodeStoredSchema
 		}
 		case NodeKind.Array: {
 			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
-			const field = {
-				kind: FieldKinds.sequence.identifier,
-				types,
-				persistedMetadata: schema.persistedMetadata,
-			};
-			const fields = new Map([[EmptyKey, field]]);
-			return new ObjectNodeStoredSchema(fields, schema.persistedMetadata);
+			return arrayNodeStoredSchema(types, schema.persistedMetadata);
 		}
 		case NodeKind.Object: {
 			const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
 			for (const fieldSchema of schema.fields.values()) {
-				fields.set(brand(fieldSchema.storedKey), convertField(fieldSchema));
+				fields.set(brand(fieldSchema.storedKey), convertField(fieldSchema, options));
 			}
 			return new ObjectNodeStoredSchema(fields, schema.persistedMetadata);
 		}
@@ -156,3 +206,16 @@ export function getStoredSchema(schema: SimpleNodeSchema): TreeNodeStoredSchema
 		}
 	}
 }
+
+export function arrayNodeStoredSchema(
+	types: TreeTypeSet,
+	persistedMetadata: JsonCompatibleReadOnlyObject | undefined,
+): ObjectNodeStoredSchema {
+	const field = {
+		kind: FieldKinds.sequence.identifier,
+		types,
+		persistedMetadata,
+	};
+	const fields = new Map([[EmptyKey, field]]);
+	return new ObjectNodeStoredSchema(fields, persistedMetadata);
+}

package/src/tableSchema.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { oob } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { Tree, TreeAlpha } from "./shared-tree/index.js";
@@ -780,8 +780,20 @@ export namespace System_TableSchema {
 						`Specified column with ID "${columnId}" does not exist in the table.`,
 					);
 				}
-				this.columns.removeAt(index);
-				return column as ColumnValueType;
+				assert(column !== undefined, 0xc10 /* column should not be undefined */);
+
+				Tree.runTransaction(this, () => {
+					// Remove the corresponding cell from all rows.
+					for (const row of this.rows) {
+						// TypeScript is unable to narrow the row type correctly here, hence the cast.
+						// See: https://github.com/microsoft/TypeScript/issues/52144
+						(row as RowValueType).removeCell(column);
+					}
+
+					this.columns.removeAt(index);
+				});
+
+				return column;
 			}
 
 			public removeAllColumns(): ColumnValueType[] {
@@ -1081,29 +1093,6 @@ export namespace System_TableSchema {
  * });
  * ```
  *
- * @example Removing column and cells in a transaction
- *
- * When removing a column, if you wish to ensure that all of its corresponding cells are also removed (and not
- * orphaned), you can remove the column and all of the relevant cells in a transaction.
- * Note that there are performance implications to this.
- *
- * ```typescript
- * // Remove column1 and all of its cells.
- * // The "transaction" method will ensure that all changes are applied atomically.
- * Tree.runTransaction(table, () => {
- * 	// Remove column1.
- * 	table.removeColumn(column1);
- *
- * 	// Remove the cell at column1 for each row.
- * 	for (const row of table.rows) {
- * 		table.removeCell({
- * 			column: column1,
- * 			row,
- * 		});
- * 	}
- * });
- * ```
- *
  * @privateRemarks
  * The above examples are backed by tests in `tableSchema.spec.ts`.
  * Those tests and these examples should be kept in-sync to ensure that the examples are correct.
@@ -1530,14 +1519,16 @@ export namespace TableSchema {
 
 		/**
 		 * Removes the specified column from the table.
-		 *
 		 * @remarks
-		 * Note: this does not remove any cells from the table's rows.
-		 * To remove the corresponding cells, use {@link TableSchema.Table.removeCell}.
+		 * Also removes any corresponding cells from the table's rows.
+		 *
+		 * Note: this operation can be slow for tables with many rows.
+		 * We are actively working on improving the performance of this operation, but for now it may have a negative
+		 * impact on performance.
 		 *
 		 * @param column - The {@link TableSchema.Column | column} or {@link TableSchema.Column.id | column ID} to remove.
 		 * @throws Throws an error if the column is not in the table.
-		 * @privateRemarks TODO (future): Actually remove corresponding cells from table rows.
+		 * In this case, no columns are removed.
 		 */
 		removeColumn(
 			column: string | TreeNodeFromImplicitAllowedTypes<TColumn>,
@@ -1545,10 +1536,12 @@ export namespace TableSchema {
 
 		/**
 		 * Removes 0 or more columns from the table.
-		 *
 		 * @remarks
-		 * Note: this does not remove any cells from the table's rows.
-		 * To remove the corresponding cells, use {@link TableSchema.Table.removeCell}.
+		 * Also removes any corresponding cells from the table's rows.
+		 *
+		 * Note: this operation can be slow for tables with many rows.
+		 * We are actively working on improving the performance of this operation, but for now it may have a negative
+		 * impact on performance.
 		 *
 		 * @param columns - The columns to remove.
 		 * @throws Throws an error if any of the columns are not in the table.
@@ -1561,8 +1554,11 @@ export namespace TableSchema {
 		 * Removes 0 or more columns from the table.
 		 *
 		 * @remarks
-		 * Note: this does not remove any cells from the table's rows.
-		 * To remove the corresponding cells, use {@link TableSchema.Table.removeCell}.
+		 * Also removes any corresponding cells from the table's rows.
+		 *
+		 * Note: this operation can be slow for tables with many rows.
+		 * We are actively working on improving the performance of this operation, but for now it may have a negative
+		 * impact on performance.
 		 *
 		 * @param columns - The columns to remove, specified by their {@link TableSchema.Column.id}.
 		 * @throws Throws an error if any of the columns are not in the table.
@@ -1572,6 +1568,14 @@ export namespace TableSchema {
 
 		/**
 		 * Removes all columns from the table.
+		 *
+		 * @remarks
+		 * Also removes any corresponding cells from the table's rows.
+		 *
+		 * Note: this operation can be slow for tables with many rows.
+		 * We are actively working on improving the performance of this operation, but for now it may have a negative
+		 * impact on performance.
+		 *
 		 * @returns The removed columns.
 		 */
 		removeAllColumns(): TreeNodeFromImplicitAllowedTypes<TColumn>[];
@@ -1580,6 +1584,7 @@ export namespace TableSchema {
 		 * Removes the specified row from the table.
 		 * @param row - The {@link TableSchema.Row | row} or {@link TableSchema.Row.id | row ID} to remove.
 		 * @throws Throws an error if the row is not in the table.
+		 * In this case, no rows are removed.
 		 */
 		removeRow(
 			row: string | TreeNodeFromImplicitAllowedTypes<TRow>,