@fluidframework/tree 2.71.0 → 2.73.0

package/src/tableSchema.ts

@@ -6,7 +6,7 @@
 import { fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { Tree, TreeAlpha } from "./shared-tree/index.js";
+import { TreeAlpha } from "./shared-tree/index.js";
 import {
 	type FieldHasDefault,
 	type ImplicitAllowedTypes,
@@ -26,10 +26,10 @@ import {
 	type InternalTreeNode,
 	SchemaFactory,
 	type ImplicitFieldSchema,
-	isArrayNodeSchema,
-	type InsertableField,
 	withBufferedTreeEvents,
+	type TreeRecordNode,
 } from "./simple-tree/index.js";
+import { validateIndex, validateIndexRange } from "./util/index.js";
 
 // Future improvement TODOs:
 // - Omit `cells` property from Row insertion type.
@@ -44,52 +44,31 @@ import {
  */
 const tableSchemaFactorySubScope = "table";
 
-/**
- * Gets the table containing the provided row/column node, if the node is part of a table.
- * @remarks Assumes that the table is the grandparent of the row/column node.
- */
-function getParentTable(
-	rowOrColumnNode: TreeNode,
-):
-	| (TreeNode &
-			TableSchema.Table<
-				string | undefined,
-				ImplicitAllowedTypes,
-				System_TableSchema.ColumnSchemaBase,
-				System_TableSchema.RowSchemaBase
-			>)
-	| undefined {
-	const rowListNode = Tree.parent(rowOrColumnNode);
-	if (rowListNode === undefined || !isArrayNodeSchema(Tree.schema(rowListNode))) {
-		return undefined;
-	}
-	const tableNode = Tree.parent(rowListNode);
-	if (tableNode === undefined || !isTableNode(tableNode)) {
-		return undefined;
-	}
-
-	return tableNode;
-}
-
 /**
  * A private symbol put on table schema to help identify them.
  */
 const tableSchemaSymbol: unique symbol = Symbol("tableNode");
 
 /**
- * Type-guard to determine if a node is a table node.
- * @remarks Uses {@link tableSchemaSymbol} to identify table nodes.
+ * A row in a table.
+ * @typeParam TCell - The type of the cells in the {@link TableSchema.Table}.
+ * @typeParam TProps - Additional properties to associate with the row.
+ * @privateRemarks Private counterpart to the {@link TableSchema.Row}.
+ * Exposes internal properties needed for table operations (publicly exposed via {@link TableSchema.Table}).
+ * @sealed
  */
-function isTableNode(
-	node: TreeNode,
-): node is TreeNode &
-	TableSchema.Table<
-		string | undefined,
-		ImplicitAllowedTypes,
-		System_TableSchema.ColumnSchemaBase,
-		System_TableSchema.RowSchemaBase
-	> {
-	return tableSchemaSymbol in Tree.schema(node);
+export interface RowPrivate<
+	TCell extends ImplicitAllowedTypes,
+	TProps extends ImplicitFieldSchema = ImplicitFieldSchema,
+> extends TableSchema.Row<TCell, TProps> {
+	/**
+	 * The row's cells.
+	 * @remarks This is a user-defined schema that can be used to store additional information about the row.
+	 * @privateRemarks
+	 * Note: these docs are duplicated on the inline type definitions in {@link System_TableSchema.createRowSchema}.
+	 * If you update the docs here, please also update the inline type definitions.
+	 */
+	readonly cells: TreeRecordNode<TCell>;
 }
 
 /**
@@ -161,16 +140,10 @@ export namespace System_TableSchema {
 		const TInputScope extends string | undefined,
 		const TCellSchema extends ImplicitAllowedTypes,
 		const TPropsSchema extends ImplicitFieldSchema,
-	>(
-		inputSchemaFactory: SchemaFactoryBeta<TInputScope>,
-		cellSchema: TCellSchema,
-		propsSchema: TPropsSchema,
-	) {
+	>(inputSchemaFactory: SchemaFactoryBeta<TInputScope>, propsSchema: TPropsSchema) {
 		const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
 		type Scope = ScopedSchemaName<TInputScope, typeof tableSchemaFactorySubScope>;
 
-		type CellValueType = TreeNodeFromImplicitAllowedTypes<TCellSchema>;
-
 		// Note: `columnFields` is broken into two parts to work around a TypeScript bug
 		// that results in broken `.d.ts` output.
 		// See definition of `ColumnInsertableType` below.
@@ -205,33 +178,7 @@ export namespace System_TableSchema {
 				// Will make it easier to evolve this schema in the future.
 				allowUnknownOptionalFields: true,
 			})
-			implements TableSchema.Column<TCellSchema, TPropsSchema>
-		{
-			public getCells(): {
-				rowId: string;
-				cell: CellValueType;
-			}[] {
-				const tableNode = getParentTable(this);
-				if (tableNode === undefined) {
-					throw new UsageError(`Column with ID "${this.id}" is not contained in a table.`);
-				}
-
-				const result = [];
-				for (const row of tableNode.rows) {
-					const cell = row.getCell(this.id);
-					if (cell !== undefined) {
-						if (!Tree.is(cell, cellSchema)) {
-							throw new UsageError(
-								"Parent table contains a cell with incompatible with this column.",
-							);
-						}
-
-						result.push({ rowId: row.id, cell: cell as CellValueType });
-					}
-				}
-				return result;
-			}
-		}
+			implements TableSchema.Column<TCellSchema, TPropsSchema> {}
 
 		type ColumnValueType = TreeNode &
 			TableSchema.Column<TCellSchema, TPropsSchema> &
@@ -341,9 +288,6 @@ export namespace System_TableSchema {
 		const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
 		type Scope = ScopedSchemaName<TInputScope, typeof tableSchemaFactorySubScope>;
 
-		type CellValueType = TreeNodeFromImplicitAllowedTypes<TCellSchema>;
-		type CellInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TCellSchema>;
-
 		// Note: `rowFields` is broken into two parts to work around a TypeScript bug
 		// that results in broken `.d.ts` output.
 		// See definition of `RowInsertableType` below.
@@ -365,7 +309,7 @@ export namespace System_TableSchema {
 		} as const;
 
 		/**
-		 * {@link Row} fields.
+		 * {@link RowSchema} fields.
 		 * @remarks Extracted for re-use in returned type signature defined later in this function.
 		 * The implicit typing is intentional.
 		 * Note: ideally we would add a satisfies clause here to ensure that this satisfies
@@ -380,75 +324,12 @@ export namespace System_TableSchema {
 		/**
 		 * The Row schema - this is a map of Cells where the key is the column id
 		 */
-		class Row
+		class RowSchema
 			extends schemaFactory.object("Row", rowFields, {
 				// Will make it easier to evolve this schema in the future.
 				allowUnknownOptionalFields: true,
 			})
-			implements TableSchema.Row<TCellSchema, TPropsSchema>
-		{
-			public getCell(
-				columnOrId: TableSchema.Column<TCellSchema> | string,
-			): CellValueType | undefined {
-				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
-				// Unlike most objects, RecordNodes don't have the default inherited object properties, so this is safe
-				return this.cells[columnId];
-			}
-
-			public setCell(
-				columnOrId: TableSchema.Column<TCellSchema> | string,
-				value: CellInsertableType | undefined,
-			): void {
-				// TODO: throw if column does not exist in the owning table.
-
-				if (value === undefined) {
-					this.removeCell(columnOrId);
-				} else {
-					const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
-
-					// TypeScript is unable to narrow the types correctly here, hence the casts.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
-					this.cells[columnId] = TreeAlpha.create(
-						cellSchema,
-						value as InsertableField<TCellSchema>,
-					) as CellValueType;
-				}
-			}
-
-			public removeCell(
-				columnOrId: TableSchema.Column<TCellSchema> | string,
-			): CellValueType | undefined {
-				// TODO: throw if column does not exist in the owning table.
-
-				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
-
-				const cell: CellValueType | undefined = this.getCell(columnId);
-				if (cell === undefined) {
-					return undefined;
-				}
-
-				// eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- The record's values are non-optional, so setting `undefined` as a means to remove the cell is not supported.
-				delete this.cells[columnId];
-
-				return cell;
-			}
-
-			public getCells(): {
-				columnId: string;
-				cell: CellValueType;
-			}[] {
-				const result = [];
-				for (const [columnId, cell] of Object.entries(this.cells)) {
-					if (cell !== undefined) {
-						result.push({
-							columnId,
-							cell,
-						});
-					}
-				}
-				return result;
-			}
-		}
+			implements RowPrivate<TCellSchema, TPropsSchema> {}
 
 		type RowValueType = TreeNode &
 			TableSchema.Row<TCellSchema, TPropsSchema> &
@@ -491,14 +372,14 @@ export namespace System_TableSchema {
 		type RowSchemaModifiedType = Omit<
 			// Use mapped type to omit the constructor
 			{
-				[Property in keyof typeof Row]: (typeof Row)[Property];
+				[Property in keyof typeof RowSchema]: (typeof RowSchema)[Property];
 			},
 			"createFromInsertable"
 		> &
 			(new (
 				parameters: InternalTreeNode | RowInsertableType,
-			) => Row) & {
-				createFromInsertable(parameters: RowInsertableType): Row;
+			) => RowSchema) & {
+				createFromInsertable(parameters: RowInsertableType): RowSchema;
 			};
 
 		// Returning SingletonSchema without a type conversion results in TypeScript generating something like `readonly "__#124291@#brand": unknown;`
@@ -513,7 +394,7 @@ export namespace System_TableSchema {
 			/* TInsertable */ object & RowInsertableType,
 			/* ImplicitlyConstructable */ true,
 			/* Info */ typeof rowFields
-		> = Row as RowSchemaModifiedType;
+		> = RowSchema as RowSchemaModifiedType;
 
 		return RowSchemaType;
 	}
@@ -565,6 +446,9 @@ export namespace System_TableSchema {
 		type ColumnValueType = TreeNodeFromImplicitAllowedTypes<TColumnSchema>;
 		type RowValueType = TreeNodeFromImplicitAllowedTypes<TRowSchema>;
 
+		// Internal version of RowValueType that exposes the `cells` property for use within Table methods.
+		type RowValueInternalType = RowValueType & RowPrivate<TCellSchema>;
+
 		/**
 		 * {@link Table} fields.
 		 * @remarks Extracted for re-use in returned type signature defined later in this function.
@@ -592,45 +476,43 @@ export namespace System_TableSchema {
 			}
 
 			public getColumn(indexOrId: number | string): ColumnValueType | undefined {
-				return this._tryGetColumn(indexOrId);
+				return this.#tryGetColumn(indexOrId);
 			}
 
 			public getRow(indexOrId: number | string): RowValueType | undefined {
-				return this._tryGetRow(indexOrId);
+				return this.#tryGetRow(indexOrId);
 			}
 
 			public getCell(
 				key: TableSchema.CellKey<TColumnSchema, TRowSchema>,
 			): CellValueType | undefined {
 				const { column: columnOrIdOrIndex, row: rowOrIdOrIndex } = key;
-				const row = this._tryGetRow(rowOrIdOrIndex);
+				const row = this.#tryGetRow(rowOrIdOrIndex);
 				if (row === undefined) {
 					return undefined;
 				}
 
-				const column = this._tryGetColumn(columnOrIdOrIndex);
+				const column = this.#tryGetColumn(columnOrIdOrIndex);
 				if (column === undefined) {
 					return undefined;
 				}
 
-				return row.getCell(column);
+				return (row as RowValueInternalType).cells[column.id];
 			}
 
 			public insertColumns({
 				columns,
 				index,
 			}: TableSchema.InsertColumnsParameters<TColumnSchema>): ColumnValueType[] {
-				// Ensure index is valid
-				if (index !== undefined) {
-					Table.validateInsertionIndex(index, this.columns);
-				}
-
 				// TypeScript is unable to narrow the column type correctly here, hence the casts below.
 				// See: https://github.com/microsoft/TypeScript/issues/52144
 				if (index === undefined) {
 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
 					this.columns.insertAtEnd(TreeArrayNode.spread(columns) as any);
 				} else {
+					// Ensure specified index is valid
+					validateIndex(index, this.columns, "Table.insertColumns", true);
+
 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
 					this.columns.insertAt(index, TreeArrayNode.spread(columns) as any);
 				}
@@ -645,9 +527,9 @@ export namespace System_TableSchema {
 			}: TableSchema.InsertRowsParameters<TRowSchema>): RowValueType[] {
 				// #region Input validation
 
-				// Ensure index is valid
+				// Ensure specified index is valid
 				if (index !== undefined) {
-					Table.validateInsertionIndex(index, this.rows);
+					validateIndex(index, this.rows, "Table.insertRows", true);
 				}
 
 				// Note: TypeScript is unable to narrow the type of the row type correctly here, hence the casts below.
@@ -660,7 +542,7 @@ export namespace System_TableSchema {
 						// eslint-disable-next-line @typescript-eslint/no-explicit-any
 						const keys: string[] = Object.keys((newRow as any).cells);
 						for (const key of keys) {
-							if (!this._containsColumnWithId(key)) {
+							if (!this.#containsColumnWithId(key)) {
 								throw new UsageError(
 									`Attempted to insert row a cell under column ID "${key}", but the table does not contain a column with that ID.`,
 								);
@@ -691,10 +573,10 @@ export namespace System_TableSchema {
 			}: TableSchema.SetCellParameters<TCellSchema, TColumnSchema, TRowSchema>): void {
 				const { column: columnOrId, row: rowOrId } = key;
 
-				const row = this._getRow(rowOrId);
-				const column = this._getColumn(columnOrId);
+				const row = this.#getRow(rowOrId);
+				const column = this.#getColumn(columnOrId);
 
-				row.setCell(column, cell);
+				(row as RowValueInternalType).cells[column.id] = cell as CellValueType;
 			}
 
 			public removeColumns(
@@ -704,34 +586,28 @@ export namespace System_TableSchema {
 				if (typeof indexOrColumns === "number" || indexOrColumns === undefined) {
 					let removedColumns: ColumnValueType[] | undefined;
 					const startIndex = indexOrColumns ?? 0;
-					const _count = count ?? this.columns.length - startIndex;
+					const endIndex = count === undefined ? this.columns.length : startIndex + count;
 
 					// If there are no columns to remove, do nothing
-					if (_count === 0) {
+					if (startIndex === endIndex) {
 						return [];
 					}
 
-					Table._assertValidRange({ index: startIndex, count: _count }, this.columns);
+					validateIndexRange(startIndex, endIndex, this.columns, "Table.removeColumns");
 
-					this._applyEditsInBatch(() => {
+					this.#applyEditsInBatch(() => {
 						const columnsToRemove = this.columns.slice(
 							startIndex,
-							startIndex + _count,
+							endIndex,
 						) as ColumnValueType[];
 
 						// First, remove all cells that correspond to each column from each row:
 						for (const column of columnsToRemove) {
-							this._removeCells(column);
+							this.#removeCells(column);
 						}
 
 						// Second, remove the column nodes:
-						Table._removeRange(
-							{
-								index: startIndex,
-								count: _count,
-							},
-							this.columns,
-						);
+						removeRangeFromArray(startIndex, endIndex, this.columns, "Table.removeColumns");
 						removedColumns = columnsToRemove;
 					});
 					return removedColumns ?? fail(0xc1f /* Transaction did not complete. */);
@@ -746,10 +622,10 @@ export namespace System_TableSchema {
 					// This improves user-facing error experience.
 					const columnsToRemove: ColumnValueType[] = [];
 					for (const columnOrIdToRemove of indexOrColumns) {
-						columnsToRemove.push(this._getColumn(columnOrIdToRemove));
+						columnsToRemove.push(this.#getColumn(columnOrIdToRemove));
 					}
 
-					this._applyEditsInBatch(() => {
+					this.#applyEditsInBatch(() => {
 						// Note, throwing an error within a transaction will abort the entire transaction.
 						// So if we throw an error here for any column, no columns will be removed.
 						for (const columnToRemove of columnsToRemove) {
@@ -757,7 +633,10 @@ export namespace System_TableSchema {
 							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(columnToRemove);
+								this.removeCell({
+									column: columnToRemove,
+									row: row as RowValueType,
+								});
 							}
 
 							// We have already validated that all of the columns exist above, so this is safe.
@@ -774,20 +653,14 @@ export namespace System_TableSchema {
 			): RowValueType[] {
 				if (typeof indexOrRows === "number" || indexOrRows === undefined) {
 					const startIndex = indexOrRows ?? 0;
-					const _count = count ?? this.columns.length - startIndex;
+					const endIndex = count === undefined ? this.columns.length : startIndex + count;
 
 					// If there are no rows to remove, do nothing
-					if (_count === 0) {
+					if (startIndex === endIndex) {
 						return [];
 					}
 
-					return Table._removeRange(
-						{
-							index: startIndex,
-							count: _count,
-						},
-						this.rows,
-					);
+					return removeRangeFromArray(startIndex, endIndex, this.rows, "Table.removeRows");
 				}
 
 				// If there are no rows to remove, do nothing
@@ -800,10 +673,10 @@ export namespace System_TableSchema {
 				// This improves user-facing error experience.
 				const rowsToRemove: RowValueType[] = [];
 				for (const rowToRemove of indexOrRows) {
-					rowsToRemove.push(this._getRow(rowToRemove));
+					rowsToRemove.push(this.#getRow(rowToRemove));
 				}
 
-				this._applyEditsInBatch(() => {
+				this.#applyEditsInBatch(() => {
 					// Note, throwing an error within a transaction will abort the entire transaction.
 					// So if we throw an error here for any row, no rows will be removed.
 					for (const rowToRemove of rowsToRemove) {
@@ -819,48 +692,30 @@ export namespace System_TableSchema {
 				key: TableSchema.CellKey<TColumnSchema, TRowSchema>,
 			): CellValueType | undefined {
 				const { column: columnOrIdOrIndex, row: rowOrIdOrIndex } = key;
-				const row = this._getRow(rowOrIdOrIndex);
-				const column = this._getColumn(columnOrIdOrIndex);
+				const row = this.#getRow(rowOrIdOrIndex) as RowValueInternalType;
+				const column = this.#getColumn(columnOrIdOrIndex);
 
-				const cell: CellValueType | undefined = row.getCell(column.id);
+				const cell: CellValueType | undefined = row.cells[column.id];
 				if (cell === undefined) {
 					return undefined;
 				}
 
-				row.removeCell(column.id);
+				// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+				delete row.cells[column.id];
 				return cell;
 			}
 
 			/**
 			 * Removes the cell corresponding with the specified column from each row in the table.
 			 */
-			private _removeCells(column: ColumnValueType): void {
+			#removeCells(column: ColumnValueType): void {
 				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);
-				}
-			}
-
-			private static _assertValidRange<T>(
-				range: { index: number; count: number },
-				array: readonly T[],
-			): void {
-				const { index, count } = range;
-				if (index < 0 || index >= array.length) {
-					throw new UsageError(
-						`Start index out of bounds. Expected index to be on [0, ${array.length - 1}], but got ${index}.`,
-					);
-				}
-				if (count < 0) {
-					throw new UsageError(`Expected non-negative count. Got ${count}.`);
-				}
-
-				const end = index + count; // exclusive
-				if (end > array.length) {
-					throw new UsageError(
-						`End index out of bounds. Expected end to be on [${index}, ${array.length}], but got ${end}.`,
-					);
+					this.removeCell({
+						column,
+						row: row as RowValueType,
+					});
 				}
 			}
 
@@ -873,7 +728,7 @@ export namespace System_TableSchema {
 			 * Transactions are not supported for unhydrated trees, so we cannot run a transaction in that case.
 			 * But since there are no collaborators, this is not an issue.
 			 */
-			private _applyEditsInBatch(applyEdits: () => void): void {
+			#applyEditsInBatch(applyEdits: () => void): void {
 				const branch = TreeAlpha.branch(this);
 
 				// Ensure events are paused until all of the edits are applied.
@@ -898,7 +753,7 @@ export namespace System_TableSchema {
 			 * Returns `undefined` if there is no match.
 			 * @remarks Searches for a match based strictly on the ID and returns that result.
 			 */
-			private _tryGetColumn(
+			#tryGetColumn(
 				columnOrIdOrIndex: ColumnValueType | string | number,
 			): ColumnValueType | undefined {
 				if (typeof columnOrIdOrIndex === "number") {
@@ -932,10 +787,8 @@ export namespace System_TableSchema {
 			 * @throws Throws a `UsageError` if there is no match.
 			 * @remarks Searches for a match based strictly on the ID and returns that result.
 			 */
-			private _getColumn(
-				columnOrIdOrIndex: ColumnValueType | string | number,
-			): ColumnValueType {
-				const column = this._tryGetColumn(columnOrIdOrIndex);
+			#getColumn(columnOrIdOrIndex: ColumnValueType | string | number): ColumnValueType {
+				const column = this.#tryGetColumn(columnOrIdOrIndex);
 				if (column === undefined) {
 					Table._throwMissingColumnError(columnOrIdOrIndex);
 				}
@@ -945,8 +798,8 @@ export namespace System_TableSchema {
 			/**
 			 * Checks if a Column with the specified ID exists in the table.
 			 */
-			private _containsColumnWithId(columnId: string): boolean {
-				return this._tryGetColumn(columnId) !== undefined;
+			#containsColumnWithId(columnId: string): boolean {
+				return this.#tryGetColumn(columnId) !== undefined;
 			}
 
 			/**
@@ -975,9 +828,7 @@ export namespace System_TableSchema {
 			 * Returns `undefined` if there is no match.
 			 * @remarks Searches for a match based strictly on the ID and returns that result.
 			 */
-			private _tryGetRow(
-				rowOrIdOrIndex: RowValueType | string | number,
-			): RowValueType | undefined {
+			#tryGetRow(rowOrIdOrIndex: RowValueType | string | number): RowValueType | undefined {
 				if (typeof rowOrIdOrIndex === "number") {
 					if (rowOrIdOrIndex < 0 || rowOrIdOrIndex >= this.rows.length) {
 						return undefined;
@@ -1009,8 +860,8 @@ export namespace System_TableSchema {
 			 * @throws Throws a `UsageError` if there is no match.
 			 * @remarks Searches for a match based strictly on the ID and returns that result.
 			 */
-			private _getRow(rowOrIdOrIndex: RowValueType | string | number): RowValueType {
-				const row = this._tryGetRow(rowOrIdOrIndex);
+			#getRow(rowOrIdOrIndex: RowValueType | string | number): RowValueType {
+				const row = this.#tryGetRow(rowOrIdOrIndex);
 				if (row === undefined) {
 					Table._throwMissingRowError(rowOrIdOrIndex);
 				}
@@ -1035,47 +886,6 @@ export namespace System_TableSchema {
 					`The specified row node with ID "${rowOrIdOrIndex.id}" does not exist in the table.`,
 				);
 			}
-
-			private static _removeRange<TNodeSchema extends ImplicitAllowedTypes>(
-				range: { index: number; count: number },
-				array: TreeArrayNode<TNodeSchema>,
-			): TreeNodeFromImplicitAllowedTypes<TNodeSchema>[] {
-				Table._assertValidRange(range, array);
-
-				const { index, count } = range;
-				const end = index + count; // exclusive
-
-				// TypeScript is unable to narrow the array element type correctly here, hence the cast.
-				// See: https://github.com/microsoft/TypeScript/issues/52144
-				const removedRows = array.slice(
-					index,
-					end,
-				) as TreeNodeFromImplicitAllowedTypes<TNodeSchema>[];
-				array.removeRange(index, end);
-
-				return removedRows;
-			}
-
-			/**
-			 * Ensure that the specified index is a valid location for item insertion in the destination list.
-			 * @throws Throws a usage error if the destination is invalid.
-			 */
-			private static validateInsertionIndex(
-				index: number,
-				destinationList: readonly unknown[],
-			): void {
-				if (index < 0) {
-					throw new UsageError("The index must be greater than or equal to 0.");
-				}
-
-				if (index > destinationList.length) {
-					throw new UsageError("The index specified for insertion is out of bounds.");
-				}
-
-				if (!Number.isInteger(index)) {
-					throw new UsageError("The index must be an integer.");
-				}
-			}
 		}
 
 		// Set a private symbol on the schema class that marks it as having been generated by this factory.
@@ -1128,6 +938,29 @@ export namespace System_TableSchema {
 	// #endregion
 }
 
+/**
+ * Removes the specified range of elements from the array.
+ * @returns The removed elements.
+ */
+function removeRangeFromArray<TNodeSchema extends ImplicitAllowedTypes>(
+	startIndex: number,
+	endIndex: number,
+	array: TreeArrayNode<TNodeSchema>,
+	methodName: string,
+): TreeNodeFromImplicitAllowedTypes<TNodeSchema>[] {
+	validateIndexRange(startIndex, endIndex, array, methodName);
+
+	// TypeScript is unable to narrow the array element type correctly here, hence the cast.
+	// See: https://github.com/microsoft/TypeScript/issues/52144
+	const removedRows = array.slice(
+		startIndex,
+		endIndex,
+	) as TreeNodeFromImplicitAllowedTypes<TNodeSchema>[];
+	array.removeRange(startIndex, endIndex);
+
+	return removedRows;
+}
+
 /**
  * Contains types and factories for creating schema to represent dynamic tabular data.
  *
@@ -1253,6 +1086,7 @@ export namespace TableSchema {
 	 * @sealed @alpha
 	 */
 	export interface Column<
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reserving this for future use.
 		TCell extends ImplicitAllowedTypes,
 		TProps extends ImplicitFieldSchema = ImplicitFieldSchema,
 	> {
@@ -1271,15 +1105,6 @@ export namespace TableSchema {
 		 */
 		get props(): TreeFieldFromImplicitField<TProps>;
 		set props(value: InsertableTreeFieldFromImplicitField<TProps>);
-
-		/**
-		 * Gets all of the populated cells in the column, keyed by their associated row IDs.
-		 * @throws Throws an error if the  column is not in a table.
-		 */
-		getCells(): readonly {
-			rowId: string;
-			cell: TreeNodeFromImplicitAllowedTypes<TCell>;
-		}[];
 	}
 
 	/**
@@ -1323,7 +1148,7 @@ export namespace TableSchema {
 	}: System_TableSchema.CreateColumnOptionsBase & {
 		readonly props?: ImplicitFieldSchema;
 	}): TreeNodeSchema {
-		return System_TableSchema.createColumnSchema(schemaFactory, cell, props);
+		return System_TableSchema.createColumnSchema(schemaFactory, props);
 	}
 
 	// #endregion
@@ -1338,6 +1163,7 @@ export namespace TableSchema {
 	 * @sealed @alpha
 	 */
 	export interface Row<
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reserving this for future use.
 		TCell extends ImplicitAllowedTypes,
 		TProps extends ImplicitFieldSchema = ImplicitFieldSchema,
 	> {
@@ -1347,53 +1173,6 @@ export namespace TableSchema {
 		 */
 		readonly id: string;
 
-		/**
-		 * Gets the cell in the specified column.
-		 * @returns The cell if it exists, otherwise undefined.
-		 * @privateRemarks TODO: throw if the column does not belong to the same table as the row.
-		 */
-		getCell(column: Column<TCell>): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
-		/**
-		 * Gets the cell in the specified column, denoted by column ID.
-		 * @returns The cell if it exists, otherwise undefined.
-		 */
-		getCell(columnId: string): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
-
-		/**
-		 * Gets all of the populated cells in the row, keyed by their associated column IDs.
-		 */
-		getCells(): readonly {
-			columnId: string;
-			cell: TreeNodeFromImplicitAllowedTypes<TCell>;
-		}[];
-
-		/**
-		 * Sets the cell in the specified column.
-		 * @remarks To remove a cell, call {@link TableSchema.Row.(removeCell:1)} instead.
-		 * @privateRemarks TODO: Throw an error if the column does not exist in the table.
-		 */
-		setCell(
-			column: Column<TCell>,
-			value: InsertableTreeNodeFromImplicitAllowedTypes<TCell>,
-		): void;
-		/**
-		 * Sets the cell in the specified column, denoted by column ID.
-		 * @remarks To remove a cell, call {@link TableSchema.Row.(removeCell:2)} instead.
-		 */
-		setCell(columnId: string, value: InsertableTreeNodeFromImplicitAllowedTypes<TCell>): void;
-
-		/**
-		 * Removes the cell in the specified column.
-		 * @returns The cell if it exists, otherwise undefined.
-		 * @privateRemarks TODO: Throw if the column does not belong to the same table as the row.
-		 */
-		removeCell(column: Column<TCell>): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
-		/**
-		 * Removes the cell in the specified column, denoted by column ID.
-		 * @returns The cell if it exists, otherwise undefined.
-		 */
-		removeCell(columnId: string): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
-
 		/**
 		 * The row's properties.
 		 * @remarks This is a user-defined schema that can be used to store additional information about the row.