@fluidframework/tree 2.40.0-336023 → 2.41.0-337492

package/src/tableSchema.ts

@@ -4,12 +4,12 @@
  */
 
 import { oob } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { Tree } from "./shared-tree/index.js";
 import {
 	type FieldHasDefault,
 	type ImplicitAllowedTypes,
-	type ImplicitFieldSchema,
 	type InsertableObjectFromSchemaRecord,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
 	type NodeKind,
@@ -24,17 +24,22 @@ import {
 	type TreeFieldFromImplicitField,
 	type InsertableTreeFieldFromImplicitField,
 	type InternalTreeNode,
-	type FieldSchema,
-	type FieldKind,
 	SchemaFactory,
 	type ImplicitAnnotatedFieldSchema,
 	type UnannotateImplicitFieldSchema,
 } from "./simple-tree/index.js";
 
-// Future improvement TODOs (ideally to be done before promoting these APIs to `@alpha`):
+// Future improvement TODOs:
+// - Omit `cells` property from Row insertion type.
 // - Record-like type parameters / input parameters?
 // - Omit `props` properties from Row and Column schemas when not provided?
 
+// Longer-term work:
+// - Add constraint APIs to make it possible to avoid situations that could yield "orphaned" cells.
+
+/**
+ * The sub-scope applied to user-provided {@link SchemaFactory}s by table schema factories.
+ */
 const tableSchemaFactorySubScope = "table";
 
 /**
@@ -48,20 +53,28 @@ const tableSchemaFactorySubScope = "table";
  * @system @internal
  */
 export namespace System_TableSchema {
+	/**
+	 * Default type used for column and row "props" fields.
+	 * @privateRemarks
+	 * Longer term, it would be better to simply omit "props" altogether by default.
+	 * For now, this ensures that the user doesn't have to specify a "props" entry when initializing column/row nodes
+	 * and ensures that they cannot set anything that might conflict with future evolutions of the schema.
+	 * @system @internal
+	 */
+	export type DefaultPropsType = ReturnType<typeof SchemaFactory.optional<[]>>;
+
 	/**
 	 * A base interface for factory input options which include an schema factory.
 	 * @remarks This interface should not be referenced directly.
 	 * @privateRemarks This interface primarily exists to provide a single home for property documentation.
 	 * @system @internal
 	 */
-	export interface OptionsWithSchemaFactory<
-		TScope extends string | undefined = string | undefined,
-	> {
+	export interface OptionsWithSchemaFactory<TSchemaFactory extends SchemaFactoryAlpha> {
 		/**
 		 * Schema factory with which the Column schema will be associated.
 		 * @remarks Can be used to associate the resulting schema with an existing {@link SchemaFactory.scope|scope}.
 		 */
-		readonly schemaFactory: SchemaFactoryAlpha<TScope>;
+		readonly schemaFactory: TSchemaFactory;
 	}
 
 	/**
@@ -70,9 +83,7 @@ export namespace System_TableSchema {
 	 * @privateRemarks This interface primarily exists to provide a single home for property documentation.
 	 * @system @internal
 	 */
-	export interface OptionsWithCellSchema<
-		TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes,
-	> {
+	export interface OptionsWithCellSchema<TCellSchema extends ImplicitAllowedTypes> {
 		/**
 		 * Schema for the table's cells.
 		 */
@@ -87,15 +98,15 @@ export namespace System_TableSchema {
 	 * @system @internal
 	 */
 	export type CreateColumnOptionsBase<
-		TInputScope extends string | undefined = string | undefined,
-	> = OptionsWithSchemaFactory<TInputScope>;
+		TSchemaFactory extends SchemaFactoryAlpha = SchemaFactoryAlpha,
+	> = OptionsWithSchemaFactory<TSchemaFactory>;
 
 	/**
-	 * Factory for creating new table column schema.
+	 * Factory for creating column schema.
 	 * @system @internal
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
-	export function createColumnInternal<
+	export function createColumnSchema<
 		const TInputScope extends string | undefined,
 		const TPropsSchema extends ImplicitAnnotatedFieldSchema,
 	>(inputSchemaFactory: SchemaFactoryAlpha<TInputScope>, propsSchema: TPropsSchema) {
@@ -136,10 +147,10 @@ export namespace System_TableSchema {
 				// Will make it easier to evolve this schema in the future.
 				allowUnknownOptionalFields: true,
 			})
-			implements TableSchema.IColumn<TPropsSchema> {}
+			implements TableSchema.Column<TPropsSchema> {}
 
 		type ColumnValueType = TreeNode &
-			TableSchema.IColumn<TPropsSchema> &
+			TableSchema.Column<TPropsSchema> &
 			WithType<ScopedSchemaName<Scope, "Column">>;
 
 		// Note: ideally this type would just leverage `InsertableObjectFromSchemaRecord<typeof columnFields>`,
@@ -151,7 +162,7 @@ export namespace System_TableSchema {
 			typeof columnFieldsBuiltInParts
 		> &
 			(FieldHasDefault<UnannotateImplicitFieldSchema<TPropsSchema>> extends true
-				? // Note: The docs on the below properties are copied from `IRow.props`' docs to ensure that the
+				? // Note: The docs on the below properties are copied from `IColumn.props`' docs to ensure that the
 					// documentation appears in the data insertion scenario.
 					// The contents are duplicated instead of using `@inheritdoc`, as intellisense does not correctly
 					// support `@inheritDoc`.
@@ -215,8 +226,8 @@ export namespace System_TableSchema {
 	 */
 	export type ColumnSchemaBase<
 		TScope extends string | undefined = string | undefined,
-		TPropsSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
-	> = ReturnType<typeof TableSchema.createColumn<TScope, TPropsSchema>>;
+		TPropsSchema extends ImplicitAnnotatedFieldSchema = ImplicitAnnotatedFieldSchema,
+	> = ReturnType<typeof createColumnSchema<TScope, TPropsSchema>>;
 
 	// #endregion
 
@@ -228,20 +239,19 @@ export namespace System_TableSchema {
 	 * @system @internal
 	 */
 	export type CreateRowOptionsBase<
-		TScope extends string | undefined = string | undefined,
+		TSchemaFactory extends SchemaFactoryAlpha = SchemaFactoryAlpha,
 		TCell extends ImplicitAllowedTypes = ImplicitAllowedTypes,
-	> = OptionsWithSchemaFactory<TScope> & OptionsWithCellSchema<TCell>;
+	> = OptionsWithSchemaFactory<TSchemaFactory> & OptionsWithCellSchema<TCell>;
 
 	/**
-	 * Factory for creating new table row schema.
-	 *
+	 * Factory for creating row schema.
 	 * @sealed @internal
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
-	export function createRowInternal<
+	export function createRowSchema<
 		const TInputScope extends string | undefined,
 		const TCellSchema extends ImplicitAllowedTypes,
-		const TPropsSchema extends ImplicitFieldSchema,
+		const TPropsSchema extends ImplicitAnnotatedFieldSchema,
 	>(
 		inputSchemaFactory: SchemaFactoryAlpha<TInputScope>,
 		cellSchema: TCellSchema,
@@ -289,32 +299,40 @@ export namespace System_TableSchema {
 				// Will make it easier to evolve this schema in the future.
 				allowUnknownOptionalFields: true,
 			})
-			implements TableSchema.IRow<TCellSchema, TPropsSchema>
+			implements TableSchema.Row<TCellSchema, TPropsSchema>
 		{
-			public getCell(columnOrId: TableSchema.IColumn | string): CellValueType | undefined {
+			public getCell(columnOrId: TableSchema.Column | string): CellValueType | undefined {
 				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
 				return this.cells.get(columnId) as CellValueType | undefined;
 			}
 
 			public setCell(
-				columnOrId: TableSchema.IColumn | string,
+				columnOrId: TableSchema.Column | string,
 				value: CellInsertableType | undefined,
 			): void {
+				// TODO: throw if column does not exist in the owning table.
+
 				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
 				this.cells.set(columnId, value);
 			}
 
-			public removeCell(columnOrId: TableSchema.IColumn | string): void {
+			public removeCell(columnOrId: TableSchema.Column | string): CellValueType | undefined {
+				// TODO: throw if column does not exist in the owning table.
+
 				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
-				if (!this.cells.has(columnId)) {
-					return;
+
+				const cell: CellValueType | undefined = this.cells.get(columnId);
+				if (cell === undefined) {
+					return undefined;
 				}
+
 				this.cells.delete(columnId);
+				return cell;
 			}
 		}
 
 		type RowValueType = TreeNode &
-			TableSchema.IRow<TCellSchema, TPropsSchema> &
+			TableSchema.Row<TCellSchema, TPropsSchema> &
 			WithType<ScopedSchemaName<Scope, "Row">>;
 
 		// Note: ideally this type would just leverage `InsertableObjectFromSchemaRecord<typeof rowFields>`,
@@ -324,7 +342,7 @@ export namespace System_TableSchema {
 		// the issue.
 		// type RowInsertableType = InsertableObjectFromSchemaRecord<typeof rowFields>;
 		type RowInsertableType = InsertableObjectFromSchemaRecord<typeof rowFieldsBuiltInParts> &
-			(FieldHasDefault<TPropsSchema> extends true
+			(FieldHasDefault<UnannotateImplicitFieldSchema<TPropsSchema>> extends true
 				? // Note: The docs on the below properties are copied from `IRow.props`' docs to ensure that the
 					// documentation appears in the data insertion scenario.
 					// The contents are duplicated instead of using `@inheritdoc`, as intellisense does not correctly
@@ -336,7 +354,9 @@ export namespace System_TableSchema {
 						 * @remarks This is a user-defined schema that can be used to store additional information
 						 * about the row.
 						 */
-						props?: InsertableTreeFieldFromImplicitField<TPropsSchema>;
+						props?: InsertableTreeFieldFromImplicitField<
+							UnannotateImplicitFieldSchema<TPropsSchema>
+						>;
 					}
 				: {
 						/**
@@ -344,10 +364,12 @@ export namespace System_TableSchema {
 						 * @remarks This is a user-defined schema that can be used to store additional information
 						 * about the row.
 						 */
-						props: InsertableTreeFieldFromImplicitField<TPropsSchema>;
+						props: InsertableTreeFieldFromImplicitField<
+							UnannotateImplicitFieldSchema<TPropsSchema>
+						>;
 					});
 
-		// Modified version of `Column` that ensures the constructor (and `createFromInsertable`) are
+		// Modified version of `Row` that ensures the constructor (and `createFromInsertable`) are
 		// typed correctly in terms of our insertable type.
 		// This lets us be selective in our type-cast for the value returned from this function,
 		// preserving as much type-safety as we reasonably can.
@@ -388,8 +410,8 @@ export namespace System_TableSchema {
 	export type RowSchemaBase<
 		TScope extends string | undefined = string | undefined,
 		TCellSchema extends ImplicitAllowedTypes = ImplicitAllowedTypes,
-		TPropsSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
-	> = ReturnType<typeof TableSchema.createRow<TScope, TCellSchema, TPropsSchema>>;
+		TPropsSchema extends ImplicitAnnotatedFieldSchema = ImplicitAnnotatedFieldSchema,
+	> = ReturnType<typeof createRowSchema<TScope, TCellSchema, TPropsSchema>>;
 
 	// #endregion
 
@@ -401,23 +423,20 @@ export namespace System_TableSchema {
 	 * @system @internal
 	 */
 	export type TableFactoryOptionsBase<
-		TScope extends string | undefined = string | undefined,
+		TSchemaFactory extends SchemaFactoryAlpha = SchemaFactoryAlpha,
 		TCell extends ImplicitAllowedTypes = ImplicitAllowedTypes,
-	> = OptionsWithSchemaFactory<TScope> & OptionsWithCellSchema<TCell>;
+	> = OptionsWithSchemaFactory<TSchemaFactory> & OptionsWithCellSchema<TCell>;
 
 	/**
-	 * Factory for creating new table schema.
+	 * Factory for creating table schema.
 	 * @system @internal
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
-	export function createTableInternal<
+	export function createTableSchema<
 		const TInputScope extends string | undefined,
 		const TCellSchema extends ImplicitAllowedTypes,
-		const TColumnSchema extends ColumnSchemaBase<TInputScope> = ColumnSchemaBase<TInputScope>,
-		const TRowSchema extends RowSchemaBase<TInputScope, TCellSchema> = RowSchemaBase<
-			TInputScope,
-			TCellSchema
-		>,
+		const TColumnSchema extends ColumnSchemaBase<TInputScope>,
+		const TRowSchema extends RowSchemaBase<TInputScope, TCellSchema>,
 	>(
 		inputSchemaFactory: SchemaFactoryAlpha<TInputScope>,
 		_cellSchema: TCellSchema,
@@ -428,13 +447,8 @@ export namespace System_TableSchema {
 		type Scope = ScopedSchemaName<TInputScope, typeof tableSchemaFactorySubScope>;
 
 		type CellValueType = TreeNodeFromImplicitAllowedTypes<TCellSchema>;
-		type CellInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TCellSchema>;
-
 		type ColumnValueType = TreeNodeFromImplicitAllowedTypes<TColumnSchema>;
-		type ColumnInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TColumnSchema>;
-
 		type RowValueType = TreeNodeFromImplicitAllowedTypes<TRowSchema>;
-		type RowInsertableType = InsertableTreeNodeFromImplicitAllowedTypes<TRowSchema>;
 
 		/**
 		 * {@link Table} fields.
@@ -444,7 +458,7 @@ export namespace System_TableSchema {
 		const tableFields = {
 			rows: schemaFactory.array("Table.rows", rowSchema),
 			columns: schemaFactory.array("Table.columns", columnSchema),
-		} as const satisfies Record<string, ImplicitFieldSchema>;
+		} as const satisfies Record<string, ImplicitAnnotatedFieldSchema>;
 
 		/**
 		 * The Table schema
@@ -454,7 +468,7 @@ export namespace System_TableSchema {
 				// Will make it easier to evolve this schema in the future.
 				allowUnknownOptionalFields: true,
 			})
-			implements TableSchema.ITable<TCellSchema, TColumnSchema, TRowSchema>
+			implements TableSchema.Table<TCellSchema, TColumnSchema, TRowSchema>
 		{
 			public getColumn(id: string): ColumnValueType | undefined {
 				// TypeScript is unable to narrow the types correctly here, hence the casts.
@@ -472,51 +486,130 @@ export namespace System_TableSchema {
 					| undefined;
 			}
 
-			public getCell(key: TableSchema.CellKey): CellValueType | undefined {
-				const { columnId, rowId } = key;
-				const row = this.getRow(rowId);
-				if (row !== undefined) {
-					const column = this.getColumn(columnId);
-					if (column !== undefined) {
-						return row.getCell(column.id);
-					}
+			public getCell(
+				key: TableSchema.CellKey<TColumnSchema, TRowSchema>,
+			): CellValueType | undefined {
+				const { column: columnOrId, row: rowOrId } = key;
+				const row = this._getRow(rowOrId);
+				if (row === undefined) {
+					return undefined;
+				}
+
+				const column = this._getColumn(columnOrId);
+				if (column === undefined) {
+					return undefined;
 				}
-				// If the cell does not exist return undefined
-				return undefined;
+
+				return row.getCell(column);
 			}
 
 			public insertColumn({
 				column,
 				index,
-			}: TableSchema.InsertColumnParameters<ColumnInsertableType>): ColumnValueType {
-				if (index === undefined) {
-					// TypeScript is unable to narrow the types correctly here, hence the cast.
+			}: TableSchema.InsertColumnParameters<TColumnSchema>): ColumnValueType {
+				const inserted = this.insertColumns({
+					columns: [column],
+					index,
+				});
+				return inserted[0] ?? oob();
+			}
+
+			public insertColumns({
+				columns,
+				index,
+			}: TableSchema.InsertColumnsParameters<TColumnSchema>): ColumnValueType[] {
+				// #region Input validation
+
+				// Ensure index is valid
+				if (index !== undefined) {
+					Table.validateInsertionIndex(index, this.columns);
+				}
+
+				// Check all of the columns being inserted an ensure the table does not already contain any with the same ID.
+				for (const column of columns) {
+					// TypeScript is unable to narrow the type of the column type correctly here, hence the casts below.
 					// See: https://github.com/microsoft/TypeScript/issues/52144
+					const maybeId = (column as ColumnValueType).id;
+					if (maybeId !== undefined && this.containsColumnWithId(maybeId)) {
+						throw new UsageError(
+							`A column with ID "${(column as ColumnValueType).id}" already exists in the table.`,
+						);
+					}
+				}
+
+				// #endregion
+
+				// 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(column as any);
+					this.columns.insertAtEnd(TreeArrayNode.spread(columns) as any);
 				} else {
-					// TypeScript is unable to narrow the types correctly here, hence the cast.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
-					this.columns.insertAt(index, column as any);
+					this.columns.insertAt(index, TreeArrayNode.spread(columns) as any);
 				}
 
-				// Inserting the input node into the tree hydrates it, making it usable as a node.
-				return column as ColumnValueType;
+				// Inserting the input nodes into the tree hydrates them, making them usable as nodes.
+				return columns as unknown as ColumnValueType[];
+			}
+
+			public insertRow({
+				row,
+				index,
+			}: TableSchema.InsertRowParameters<TRowSchema>): RowValueType {
+				const inserted = this.insertRows({
+					rows: [row],
+					index,
+				});
+				return inserted[0] ?? oob();
 			}
 
 			public insertRows({
 				index,
 				rows,
-			}: TableSchema.InsertRowsParameters<RowInsertableType>): RowValueType[] {
+			}: TableSchema.InsertRowsParameters<TRowSchema>): RowValueType[] {
+				// #region Input validation
+
+				// Ensure index is valid
+				if (index !== undefined) {
+					Table.validateInsertionIndex(index, this.rows);
+				}
+
+				// Note: TypeScript is unable to narrow the type of the row type correctly here, hence the casts below.
+				// See: https://github.com/microsoft/TypeScript/issues/52144
+				for (const newRow of rows) {
+					// Check all of the rows being inserted an ensure the table does not already contain any with the same ID.
+					const maybeId = (newRow as RowValueType).id;
+					if (maybeId !== undefined && this.containsRowWithId(maybeId)) {
+						throw new UsageError(
+							`A row with ID "${(newRow as RowValueType).id}" already exists in the table.`,
+						);
+					}
+
+					// If the row contains cells, verify that the table contains the columns for those cells.
+					// Note: we intentionally hide `cells` on `IRow` to avoid leaking the internal data representation as much as possible, so we have to cast here.
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+					if ((newRow as any).cells !== undefined) {
+						// 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)) {
+								throw new UsageError(
+									`Attempted to insert row a cell under column ID "${key}", but the table does not contain a column with that ID.`,
+								);
+							}
+						}
+					}
+				}
+
+				// #endregion
+
+				// TypeScript is unable to narrow the row type correctly here, hence the casts below.
+				// See: https://github.com/microsoft/TypeScript/issues/52144
 				if (index === undefined) {
-					// TypeScript is unable to narrow the types correctly here, hence the cast.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
 					this.rows.insertAtEnd(TreeArrayNode.spread(rows) as any);
 				} else {
-					// TypeScript is unable to narrow the types correctly here, hence the cast.
-					// See: https://github.com/microsoft/TypeScript/issues/52144
 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
 					this.rows.insertAt(index, TreeArrayNode.spread(rows) as any);
 				}
@@ -525,65 +618,204 @@ export namespace System_TableSchema {
 				return rows as unknown as RowValueType[];
 			}
 
-			public setCell({ key, cell }: TableSchema.SetCellParameters<CellInsertableType>): void {
-				const { columnId, rowId } = key;
-				const row = this.getRow(rowId);
-				if (row !== undefined) {
-					const column = this.getColumn(columnId);
-					if (column !== undefined) {
-						row.setCell(column.id, cell);
-					}
+			public setCell({
+				key,
+				cell,
+			}: TableSchema.SetCellParameters<TCellSchema, TColumnSchema, TRowSchema>): void {
+				const { column: columnOrId, row: rowOrId } = key;
+
+				const row = this._getRow(rowOrId);
+				if (row === undefined) {
+					const rowId = this._getRowId(rowOrId);
+					throw new UsageError(`No row with ID "${rowId}" exists in the table.`);
 				}
+
+				const column = this._getColumn(columnOrId);
+				if (column === undefined) {
+					const columnId = this._getColumnId(columnOrId);
+					throw new UsageError(`No column with ID "${columnId}" exists in the table.`);
+				}
+
+				row.setCell(column, cell);
 			}
 
-			public removeColumn(column: ColumnValueType): void {
-				const index = this.columns.indexOf(column);
-				// If the column is not in the table, do nothing
-				if (index === -1) return;
+			public removeColumns(
+				columns: readonly string[] | readonly ColumnValueType[],
+			): ColumnValueType[] {
+				// If there are no columns to remove, do nothing
+				if (columns.length === 0) {
+					return [];
+				}
+
+				// If there is only one column to remove, remove it (and don't incur cost of transaction)
+				if (columns.length === 1) {
+					const removedColumn = this.removeColumn(columns[0] ?? oob());
+					return [removedColumn];
+				}
+
+				// If there are multiple columns to remove, remove them in a transaction.
+				const removedColumns: ColumnValueType[] = [];
+				Tree.runTransaction(this, () => {
+					// Note, throwing an error within a transaction will abort the entire transaction.
+					// So if we throw an error here for any row, no columns will be removed.
+					for (const columnToRemove of columns) {
+						const removedRow = this.removeColumn(columnToRemove);
+						removedColumns.push(removedRow);
+					}
+				});
+				return removedColumns;
+			}
+
+			public removeColumn(columnOrId: string | ColumnValueType): ColumnValueType {
+				const column = this._getColumn(columnOrId);
+				const index = column === undefined ? -1 : this.columns.indexOf(column);
+				if (index === -1) {
+					const columnId = this._getColumnId(columnOrId);
+					throw new UsageError(
+						`Specified column with ID "${columnId}" does not exist in the table.`,
+					);
+				}
 				this.columns.removeAt(index);
+				return column as ColumnValueType;
+			}
+
+			public removeAllColumns(): ColumnValueType[] {
+				// TypeScript is unable to narrow the row type correctly here, hence the cast.
+				// See: https://github.com/microsoft/TypeScript/issues/52144
+				return this.removeColumns(this.columns as unknown as ColumnValueType[]);
 			}
 
-			public removeRows(rows: readonly RowValueType[]): void {
+			public removeRows(rows: readonly string[] | readonly RowValueType[]): RowValueType[] {
 				// If there are no rows to remove, do nothing
 				if (rows.length === 0) {
-					return;
+					return [];
 				}
 
-				// If there is only one row to remove, remove it
+				// If there is only one row to remove, remove it (and don't incur cost of transaction)
 				if (rows.length === 1) {
-					const index = this.rows.indexOf(rows[0] ?? oob());
-					this.rows.removeAt(index);
-					return;
+					const removedRow = this.removeRow(rows[0] ?? oob());
+					return [removedRow];
 				}
-				// If there are multiple rows to remove, remove them in a transaction
-				// This is to avoid the performance issues of deleting multiple rows at once
+
+				// If there are multiple rows to remove, remove them in a transaction.
+				const removedRows: RowValueType[] = [];
 				Tree.runTransaction(this, () => {
-					// Iterate over the rows and remove them
-					for (const row of rows) {
-						const index = this.rows.indexOf(row);
-						this.rows.removeAt(index);
+					// 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 rows) {
+						const removedRow = this.removeRow(rowToRemove);
+						removedRows.push(removedRow);
 					}
 				});
+				return removedRows;
+			}
+
+			public removeRow(rowOrId: string | RowValueType): RowValueType {
+				const rowToRemove = this._getRow(rowOrId);
+				const index = rowToRemove === undefined ? -1 : this.rows.indexOf(rowToRemove);
+
+				// If the row does not exist in the table, throw an error.
+				if (index === -1) {
+					const rowId = this._getRowId(rowOrId);
+					throw new UsageError(
+						`Specified row with ID "${rowId}" does not exist in the table.`,
+					);
+				}
+
+				this.rows.removeAt(index);
+				return rowToRemove as RowValueType;
 			}
 
-			public removeAllRows(): void {
-				this.rows.removeRange();
+			public removeAllRows(): RowValueType[] {
+				// TypeScript is unable to narrow the row type correctly here, hence the cast.
+				// See: https://github.com/microsoft/TypeScript/issues/52144
+				return this.removeRows(this.rows as unknown as RowValueType[]);
 			}
 
-			public removeCell(key: TableSchema.CellKey): void {
-				const { columnId, rowId } = key;
-				const row = this.getRow(rowId);
-				if (row !== undefined) {
-					const column = this.getColumn(columnId);
-					if (column !== undefined) {
-						row.removeCell(column.id);
-					}
+			public removeCell(
+				key: TableSchema.CellKey<TColumnSchema, TRowSchema>,
+			): CellValueType | undefined {
+				const { column: columnOrId, row: rowOrId } = key;
+				const row = this._getRow(rowOrId);
+				if (row === undefined) {
+					const rowId = this._getRowId(rowOrId);
+					throw new UsageError(
+						`Specified row with ID "${rowId}" does not exist in the table.`,
+					);
+				}
+
+				const column = this._getColumn(columnOrId);
+				if (column === undefined) {
+					const columnId = this._getColumnId(columnOrId);
+					throw new UsageError(
+						`Specified column with ID "${columnId}" does not exist in the table.`,
+					);
+				}
+
+				const cell: CellValueType | undefined = row.getCell(column.id);
+				if (cell === undefined) {
+					return undefined;
+				}
+
+				row.removeCell(column.id);
+				return cell;
+			}
+
+			private _getColumn(columnOrId: string | ColumnValueType): ColumnValueType | undefined {
+				return typeof columnOrId === "string" ? this.getColumn(columnOrId) : columnOrId;
+			}
+
+			private _getColumnId(columnOrId: string | ColumnValueType): string {
+				return typeof columnOrId === "string" ? columnOrId : columnOrId.id;
+			}
+
+			private _getRow(rowOrId: string | RowValueType): RowValueType | undefined {
+				return typeof rowOrId === "string" ? this.getRow(rowOrId) : rowOrId;
+			}
+
+			private _getRowId(rowOrId: string | RowValueType): string {
+				return typeof rowOrId === "string" ? rowOrId : rowOrId.id;
+			}
+
+			private containsColumnWithId(columnId: string): boolean {
+				// TypeScript is unable to narrow the types correctly here, hence the cast.
+				// See: https://github.com/microsoft/TypeScript/issues/52144
+				return (
+					this.columns.find((column) => (column as TableSchema.Column).id === columnId) !==
+					undefined
+				);
+			}
+
+			private containsRowWithId(rowId: string): boolean {
+				// TypeScript is unable to narrow the types correctly here, hence the cast.
+				// See: https://github.com/microsoft/TypeScript/issues/52144
+				return this.rows.find((row) => (row as TableSchema.Row).id === rowId) !== undefined;
+			}
+
+			/**
+			 * 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.");
 				}
 			}
 		}
 
 		type TableValueType = TreeNode &
-			TableSchema.ITable<TCellSchema, TColumnSchema, TRowSchema> &
+			TableSchema.Table<TCellSchema, TColumnSchema, TRowSchema> &
 			WithType<ScopedSchemaName<Scope, "Table">>;
 		type TableInsertableType = InsertableObjectFromSchemaRecord<typeof tableFields>;
 
@@ -612,20 +844,100 @@ export namespace System_TableSchema {
 	export type TableSchemaBase<
 		TScope extends string | undefined,
 		TCell extends ImplicitAllowedTypes,
-		TColumn extends ColumnSchemaBase<TScope> = ColumnSchemaBase<TScope>,
-		TRow extends RowSchemaBase<TScope, TCell, ImplicitAllowedTypes> = RowSchemaBase<
-			TScope,
-			TCell,
-			ImplicitAllowedTypes
-		>,
-	> = ReturnType<typeof TableSchema.createTable<TScope, TCell, TColumn, TRow>>;
+		TColumn extends ColumnSchemaBase<TScope>,
+		TRow extends RowSchemaBase<TScope, TCell>,
+	> = ReturnType<typeof createTableSchema<TScope, TCell, TColumn, TRow>>;
 
 	// #endregion
 }
 
 /**
  * Contains types and factories for creating schema to represent dynamic tabular data.
- * @privateRemarks TODO: document in more detail and add `@example`s.
+ *
+ * @remarks
+ *
+ * Tables created using these APIs are...
+ *
+ * - sparse, meaning that cells may be omitted, and new rows are empty by default.
+ *
+ * - dynamic, meaning that their structure can be modified at runtime.
+ * Columns and rows can be inserted, removed, modified, and reordered.
+ * Cells can be inserted, removed, and modified.
+ *
+ * - row-major, meaning that operating on rows (including inserts, removal, moves, and traversal) is more efficient than operating on columns.
+ *
+ * Column and Row schema created using these APIs are extensible via the `props` field.
+ * This allows association of additional properties with column and row nodes.
+ *
+ * Note: for now it is possible for table cells to become "orphaned".
+ * That is, it is possible to enter a state where one or more rows contain cells with no corresponding column.
+ * To help avoid this situation, you can manually remove corresponding cells when removing columns.
+ * Either way, it is possible to enter such a state via the merging of edits.
+ * For example: one client might add a row while another concurrently removes a column, orphaning the cell where the column and row intersected.
+ *
+ * @example Using default Column and Row schema
+ *
+ * ```typescript
+ * class Cell extends schemaFactory.object("TableCell", {
+ * 	value: schemaFactory.string,
+ * }) {}
+ *
+ * class Table extends TableSchema.table({
+ * 	schemaFactory,
+ * 	cell: Cell,
+ * }) {}
+ *
+ * const table = new Table({
+ * 	columns: [{ id: "column-0" }],
+ * 	rows: [{ id: "row-0", cells: {} }],
+ * });
+ * ```
+ *
+ * @example Customizing Column and Row schema
+ *
+ * ```typescript
+ * class Cell extends schemaFactory.object("TableCell", {
+ * 	value: schemaFactory.string,
+ * }) {}
+ *
+ * class ColumnProps extends schemaFactory.object("TableColumnProps", {
+ * 	// Column label to display.
+ * 	label: schemaFactory.string,
+ * 	// The type of data represented by the cells. Default: string.
+ * 	dataType: schemaFactory.optional(schemaFactory.string),
+ * }) {}
+ *
+ * class Column extends TableSchema.column({
+ * 	schemaFactory,
+ * 	props: ColumnProps,
+ * }) {}
+ *
+ * class Row extends TableSchema.row({
+ * 	schemaFactory,
+ * 	cell: Cell,
+ * }) {}
+ *
+ * class Table extends TableSchema.table({
+ * 	schemaFactory,
+ * 	cell: Cell,
+ * 	column: Column,
+ * 	row: Row,
+ * }) {}
+ *
+ * const table = new Table({
+ * 	columns: [
+ * 		new Column({ props: { label: "Entry", dataType: "string" } }),
+ * 		new Column({ props: { label: "Date", dataType: "date" } }),
+ * 		new Column({ props: { label: "Amount", dataType: "number" } }),
+ * 	],
+ * 	rows: [],
+ * });
+ * ```
+ *
+ * @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.
+ *
  * @internal
  */
 export namespace TableSchema {
@@ -633,10 +945,10 @@ export namespace TableSchema {
 
 	/**
 	 * A column in a table.
-	 * @remarks Implemented by the schema class returned from {@link TableSchema.(createColumn:2)}.
+	 * @remarks Implemented by the schema class returned from {@link TableSchema.(column:2)}.
 	 * @sealed @internal
 	 */
-	export interface IColumn<
+	export interface Column<
 		TProps extends ImplicitAnnotatedFieldSchema = ImplicitAnnotatedFieldSchema,
 	> {
 		/**
@@ -649,10 +961,10 @@ export namespace TableSchema {
 		 * The column's properties.
 		 * @remarks This is a user-defined schema that can be used to store additional information about the column.
 		 * @privateRemarks
-		 * Note: these docs are duplicated on the inline type definitions in {@link createColumn}.
+		 * Note: these docs are duplicated on the inline type definitions in {@link System_TableSchema.createColumnSchema}.
 		 * If you update the docs here, please also update the inline type definitions.
 		 */
-		get props(): TreeFieldFromImplicitField<UnannotateImplicitFieldSchema<TProps>> | undefined;
+		get props(): TreeFieldFromImplicitField<UnannotateImplicitFieldSchema<TProps>>;
 		set props(value: InsertableTreeFieldFromImplicitField<
 			UnannotateImplicitFieldSchema<TProps>
 		>);
@@ -662,40 +974,34 @@ export namespace TableSchema {
 	 * Factory for creating new table column schema.
 	 * @internal
 	 */
-	export function createColumn<const TScope extends string | undefined>({
-		schemaFactory,
-	}: System_TableSchema.CreateColumnOptionsBase<TScope>): ReturnType<
-		typeof System_TableSchema.createColumnInternal<
-			TScope,
-			FieldSchema<FieldKind.Optional, typeof SchemaFactoryAlpha.null>
-		>
-	>;
+	export function column<const TScope extends string | undefined>(
+		params: System_TableSchema.CreateColumnOptionsBase<SchemaFactoryAlpha<TScope>>,
+	): System_TableSchema.ColumnSchemaBase<TScope, System_TableSchema.DefaultPropsType>;
 	/**
 	 * Factory for creating new table column schema.
 	 * @internal
 	 */
-	export function createColumn<
+	export function column<
 		const TScope extends string | undefined,
-		const TProps extends ImplicitFieldSchema,
-	>({
-		schemaFactory,
-		props,
-	}: System_TableSchema.CreateColumnOptionsBase<TScope> & {
-		/**
-		 * Optional column properties.
-		 */
-		readonly props: TProps;
-	}): ReturnType<typeof System_TableSchema.createColumnInternal<TScope, TProps>>;
+		const TProps extends ImplicitAnnotatedFieldSchema,
+	>(
+		params: System_TableSchema.CreateColumnOptionsBase<SchemaFactoryAlpha<TScope>> & {
+			/**
+			 * Optional column properties.
+			 */
+			readonly props: TProps;
+		},
+	): System_TableSchema.ColumnSchemaBase<TScope, TProps>;
 	/**
 	 * Overload implementation
 	 */
-	export function createColumn({
+	export function column({
 		schemaFactory,
 		props = SchemaFactory.optional(SchemaFactory.null),
 	}: System_TableSchema.CreateColumnOptionsBase & {
-		readonly props?: ImplicitFieldSchema;
+		readonly props?: ImplicitAnnotatedFieldSchema;
 	}): TreeNodeSchema {
-		return System_TableSchema.createColumnInternal(schemaFactory, props);
+		return System_TableSchema.createColumnSchema(schemaFactory, props);
 	}
 
 	// #endregion
@@ -707,8 +1013,8 @@ export namespace TableSchema {
 	 * @remarks Implemented by the schema class returned from {@link TableSchema.(createRow:2)}.
 	 * @sealed @internal
 	 */
-	export interface IRow<
-		TCell extends ImplicitAllowedTypes,
+	export interface Row<
+		TCell extends ImplicitAllowedTypes = ImplicitAllowedTypes,
 		TProps extends ImplicitAnnotatedFieldSchema = ImplicitAnnotatedFieldSchema,
 	> {
 		/**
@@ -720,8 +1026,9 @@ export namespace TableSchema {
 		/**
 		 * 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: IColumn): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
+		getCell(column: Column): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
 		/**
 		 * Gets the cell in the specified column, denoted by column ID.
 		 * @returns The cell if it exists, otherwise undefined.
@@ -730,31 +1037,33 @@ export namespace TableSchema {
 
 		/**
 		 * Sets the cell in the specified column.
-		 * @remarks To remove a cell, call {@link TableSchema.IRow.(removeCell:1)} instead.
+		 * @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: IColumn, value: InsertableTreeNodeFromImplicitAllowedTypes<TCell>): void;
+		setCell(column: Column, value: InsertableTreeNodeFromImplicitAllowedTypes<TCell>): void;
 		/**
 		 * Sets the cell in the specified column, denoted by column ID.
-		 * @remarks To remove a cell, call {@link TableSchema.IRow.(removeCell:2)} instead.
+		 * @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.
-		 * @privateRemarks TODO: return removed cell
+		 * @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: IColumn): void;
+		removeCell(column: Column): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
 		/**
 		 * Removes the cell in the specified column, denoted by column ID.
-		 * @privateRemarks TODO: return removed cell
+		 * @returns The cell if it exists, otherwise undefined.
 		 */
-		removeCell(columnId: string): void;
+		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.
 		 * @privateRemarks
-		 * Note: these docs are duplicated on the inline type definitions in {@link createColumn}.
+		 * 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.
 		 */
 		get props(): TreeFieldFromImplicitField<UnannotateImplicitFieldSchema<TProps>>;
@@ -767,48 +1076,39 @@ export namespace TableSchema {
 	 * Factory for creating new table column schema.
 	 * @internal
 	 */
-	export function createRow<
+	export function row<
 		const TScope extends string | undefined,
 		const TCell extends ImplicitAllowedTypes,
-	>({
-		schemaFactory,
-		cell,
-	}: System_TableSchema.CreateRowOptionsBase<TScope, TCell>): ReturnType<
-		typeof System_TableSchema.createRowInternal<
-			TScope,
-			TCell,
-			FieldSchema<FieldKind.Optional, typeof SchemaFactoryAlpha.null>
-		>
-	>;
+	>(
+		params: System_TableSchema.CreateRowOptionsBase<SchemaFactoryAlpha<TScope>, TCell>,
+	): System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>;
 	/**
-	 * Factory for creating new table column schema.
+	 * Factory for creating new table row schema.
 	 * @internal
 	 */
-	export function createRow<
+	export function row<
 		const TScope extends string | undefined,
 		const TCell extends ImplicitAllowedTypes,
-		const TProps extends ImplicitFieldSchema,
-	>({
-		schemaFactory,
-		cell,
-		props,
-	}: System_TableSchema.CreateRowOptionsBase<TScope, TCell> & {
-		/**
-		 * Optional row properties.
-		 */
-		readonly props: TProps;
-	}): ReturnType<typeof System_TableSchema.createRowInternal<TScope, TCell, TProps>>;
+		const TProps extends ImplicitAnnotatedFieldSchema,
+	>(
+		params: System_TableSchema.CreateRowOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & {
+			/**
+			 * Optional row properties.
+			 */
+			readonly props: TProps;
+		},
+	): System_TableSchema.RowSchemaBase<TScope, TCell, TProps>;
 	/**
 	 * Overload implementation
 	 */
-	export function createRow({
+	export function row({
 		schemaFactory,
 		cell,
 		props = SchemaFactory.optional(SchemaFactory.null),
 	}: System_TableSchema.CreateRowOptionsBase & {
-		readonly props?: ImplicitFieldSchema;
+		readonly props?: ImplicitAnnotatedFieldSchema;
 	}): TreeNodeSchema {
-		return System_TableSchema.createRowInternal(schemaFactory, cell, props);
+		return System_TableSchema.createRowSchema(schemaFactory, cell, props);
 	}
 
 	// #endregion
@@ -816,26 +1116,29 @@ export namespace TableSchema {
 	// #region Table
 
 	/**
-	 * A key to uniquely identify a cell in a table.
+	 * A key to uniquely identify a cell within a table.
 	 * @internal
 	 */
-	export interface CellKey {
+	export interface CellKey<
+		TColumn extends ImplicitAllowedTypes,
+		TRow extends ImplicitAllowedTypes,
+	> {
 		/**
-		 * {@link TableSchema.IColumn.id} of the containing {@link TableSchema.IColumn}.
+		 * {@link TableSchema.Column} or {@link TableSchema.Column.id} at which the cell is located.
 		 */
-		readonly columnId: string;
+		readonly column: string | TreeNodeFromImplicitAllowedTypes<TColumn>;
 
 		/**
-		 * {@link TableSchema.IRow.id} of the containing {@link TableSchema.IRow}.
+		 * {@link TableSchema.Row} or {@link TableSchema.Row.id} at which the cell is located.
 		 */
-		readonly rowId: string;
+		readonly row: string | TreeNodeFromImplicitAllowedTypes<TRow>;
 	}
 
 	/**
-	 * {@link TableSchema.ITable.insertColumn} parameters.
+	 * {@link TableSchema.Table.insertColumn} parameters.
 	 * @internal
 	 */
-	export interface InsertColumnParameters<TInsertableColumn> {
+	export interface InsertColumnParameters<TColumn extends ImplicitAllowedTypes> {
 		/**
 		 * The index at which to insert the new column.
 		 * @remarks If not provided, the column will be appended to the end of the table.
@@ -845,14 +1148,48 @@ export namespace TableSchema {
 		/**
 		 * The column to insert.
 		 */
-		readonly column: TInsertableColumn;
+		readonly column: InsertableTreeNodeFromImplicitAllowedTypes<TColumn>;
 	}
 
 	/**
-	 * {@link TableSchema.ITable.insertRows} parameters.
+	 * {@link TableSchema.Table.insertColumns} parameters.
 	 * @internal
 	 */
-	export interface InsertRowsParameters<TInsertableRow> {
+	export interface InsertColumnsParameters<TColumn extends ImplicitAllowedTypes> {
+		/**
+		 * The index at which to insert the new columns.
+		 * @remarks If not provided, the columns will be appended to the end of the table.
+		 */
+		readonly index?: number | undefined;
+
+		/**
+		 * The columns to insert.
+		 */
+		readonly columns: InsertableTreeNodeFromImplicitAllowedTypes<TColumn>[];
+	}
+
+	/**
+	 * {@link TableSchema.Table.insertRow} parameters.
+	 * @internal
+	 */
+	export interface InsertRowParameters<TRow extends ImplicitAllowedTypes> {
+		/**
+		 * The index at which to insert the new row.
+		 * @remarks If not provided, the row will be appended to the end of the table.
+		 */
+		readonly index?: number | undefined;
+
+		/**
+		 * The row to insert.
+		 */
+		readonly row: InsertableTreeNodeFromImplicitAllowedTypes<TRow>;
+	}
+
+	/**
+	 * {@link TableSchema.Table.insertRows} parameters.
+	 * @internal
+	 */
+	export interface InsertRowsParameters<TRow extends ImplicitAllowedTypes> {
 		/**
 		 * The index at which to insert the new rows.
 		 * @remarks If not provided, the rows will be appended to the end of the table.
@@ -862,30 +1199,34 @@ export namespace TableSchema {
 		/**
 		 * The rows to insert.
 		 */
-		readonly rows: TInsertableRow[];
+		readonly rows: InsertableTreeNodeFromImplicitAllowedTypes<TRow>[];
 	}
 
 	/**
-	 * {@link TableSchema.ITable.setCell} parameters.
+	 * {@link TableSchema.Table.setCell} parameters.
 	 * @internal
 	 */
-	export interface SetCellParameters<TInsertableCell> {
+	export interface SetCellParameters<
+		TCell extends ImplicitAllowedTypes,
+		TColumn extends ImplicitAllowedTypes,
+		TRow extends ImplicitAllowedTypes,
+	> {
 		/**
 		 * The key to uniquely identify a cell in a table.
 		 */
-		readonly key: CellKey;
+		readonly key: CellKey<TColumn, TRow>;
 
 		/**
 		 * The cell to set.
 		 */
-		readonly cell: TInsertableCell;
+		readonly cell: InsertableTreeNodeFromImplicitAllowedTypes<TCell>;
 	}
 
 	/**
 	 * A table.
 	 * @sealed @internal
 	 */
-	export interface ITable<
+	export interface Table<
 		TCell extends ImplicitAllowedTypes,
 		TColumn extends ImplicitAllowedTypes,
 		TRow extends ImplicitAllowedTypes,
@@ -901,139 +1242,252 @@ export namespace TableSchema {
 		readonly rows: TreeArrayNode<TRow>;
 
 		/**
-		 * Gets a table column by its {@link TableSchema.IRow.id}.
+		 * Gets a table column by its {@link TableSchema.Column.id}.
 		 */
 		getColumn(id: string): TreeNodeFromImplicitAllowedTypes<TColumn> | undefined;
 
 		/**
-		 * Gets a table row by its {@link TableSchema.IRow.id}.
+		 * Gets a table row by its {@link TableSchema.Row.id}.
 		 */
 		getRow(id: string): TreeNodeFromImplicitAllowedTypes<TRow> | undefined;
 
 		/**
 		 * Gets a cell in the table by column and row IDs.
 		 * @param key - A key that uniquely distinguishes a cell in the table, represented as a combination of the column ID and row ID.
-		 * @privateRemarks TODO: add overload that takes row and column nodes.
 		 */
-		getCell(key: CellKey): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
+		getCell(key: CellKey<TColumn, TRow>): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
 
 		/**
 		 * Inserts a column into the table.
-		 * @throws Throws an error if the column is already in the tree, or if the specified index is out of range.
+		 *
+		 * @throws
+		 * Throws an error in the following cases:
+		 *
+		 * - The column, or a column with the same ID is already in the tree.
+		 *
+		 * - The specified index is out of range.
+		 *
+		 * No column is inserted in these cases.
 		 */
 		insertColumn(
-			params: InsertColumnParameters<InsertableTreeNodeFromImplicitAllowedTypes<TColumn>>,
+			params: InsertColumnParameters<TColumn>,
 		): TreeNodeFromImplicitAllowedTypes<TColumn>;
 
+		/**
+		 * Inserts 0 or more columns into the table.
+		 *
+		 * @throws
+		 * Throws an error in the following cases:
+		 *
+		 * - At least one column, or a column with the same ID is already in the tree.
+		 *
+		 * - The specified index is out of range.
+		 *
+		 * No columns are inserted in these cases.
+		 */
+		insertColumns(
+			params: InsertColumnsParameters<TColumn>,
+		): TreeNodeFromImplicitAllowedTypes<TColumn>[];
+
+		/**
+		 * Inserts a row into the table.
+		 *
+		 * @throws
+		 * Throws an error in the following cases:
+		 *
+		 * - The row, or a row with the same ID is already in the tree.
+		 *
+		 * - The row contains cells, but the table does not contain matching columns for one or more of those cells.
+		 *
+		 * - The specified index is out of range.
+		 *
+		 * No row is inserted in these cases.
+		 */
+		insertRow(params: InsertRowParameters<TRow>): TreeNodeFromImplicitAllowedTypes<TRow>;
+
 		/**
 		 * Inserts 0 or more rows into the table.
-		 * @throws Throws an error if any of the rows are already in the tree, or if the specified index is out of range.
+		 *
+		 * @throws
+		 * Throws an error in the following cases:
+		 *
+		 * - At least one row, or a row with the same ID is already in the tree.
+		 *
+		 * - The row contains cells, but the table does not contain matching columns for one or more of those cells.
+		 *
+		 * - The specified index is out of range.
+		 *
+		 * No rows are inserted in these cases.
 		 */
-		insertRows(
-			params: InsertRowsParameters<InsertableTreeNodeFromImplicitAllowedTypes<TRow>>,
-		): TreeNodeFromImplicitAllowedTypes<TRow>[];
+		insertRows(params: InsertRowsParameters<TRow>): TreeNodeFromImplicitAllowedTypes<TRow>[];
 
 		/**
 		 * Sets the cell at the specified location in the table.
-		 * @remarks To remove a cell, call {@link TableSchema.ITable.removeCell} instead.
-		 * @privateRemarks TODO: add overload that takes column/row nodes?
+		 * @remarks To remove a cell, call {@link TableSchema.Table.removeCell} instead.
 		 */
-		setCell(
-			params: SetCellParameters<InsertableTreeNodeFromImplicitAllowedTypes<TCell>>,
-		): void;
+		setCell(params: SetCellParameters<TCell, TColumn, TRow>): void;
 
 		/**
 		 * Removes the specified column from the table.
-		 * @remarks Note: this does not remove any cells from the table's rows.
-		 * @privateRemarks
-		 * TODO:
-		 * - Policy for when the column is not in the table.
-		 * - Actually remove corresponding cells from table rows.
+		 *
+		 * @remarks
+		 * Note: this does not remove any cells from the table's rows.
+		 * To remove the corresponding cells, use {@link TableSchema.Table.removeCell}.
+		 *
+		 * @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.
 		 */
-		removeColumn: (column: TreeNodeFromImplicitAllowedTypes<TColumn>) => void;
+		removeColumn(
+			column: string | TreeNodeFromImplicitAllowedTypes<TColumn>,
+		): TreeNodeFromImplicitAllowedTypes<TColumn>;
 
+		/**
+		 * 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}.
+		 *
+		 * @param columns - The columns to remove.
+		 * @throws Throws an error if any of the columns are not in the table.
+		 * In this case, no columns are removed.
+		 */
+		removeColumns(
+			columns: readonly TreeNodeFromImplicitAllowedTypes<TColumn>[],
+		): TreeNodeFromImplicitAllowedTypes<TColumn>[];
+		/**
+		 * 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}.
+		 *
+		 * @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.
+		 * In this case, no columns are removed.
+		 */
+		removeColumns(columns: readonly string[]): TreeNodeFromImplicitAllowedTypes<TColumn>[];
+
+		/**
+		 * Removes all columns from the table.
+		 * @returns The removed columns.
+		 */
+		removeAllColumns(): TreeNodeFromImplicitAllowedTypes<TColumn>[];
+
+		/**
+		 * 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.
+		 */
+		removeRow(
+			row: string | TreeNodeFromImplicitAllowedTypes<TRow>,
+		): TreeNodeFromImplicitAllowedTypes<TRow>;
+
+		/**
+		 * Removes 0 or more rows from the table.
+		 * @param rows - The rows to remove.
+		 * @throws Throws an error if any of the rows are not in the table.
+		 * In this case, no rows are removed.
+		 */
+		removeRows(
+			rows: readonly TreeNodeFromImplicitAllowedTypes<TRow>[],
+		): TreeNodeFromImplicitAllowedTypes<TRow>[];
 		/**
 		 * Removes 0 or more rows from the table.
-		 * @privateRemarks TODO: policy for when 1 or more rows are not in the table.
+		 * @param rows - The rows to remove, specified by their {@link TableSchema.Row.id}.
+		 * @throws Throws an error if any of the rows are not in the table.
+		 * In this case, no rows are removed.
 		 */
-		removeRows: (rows: readonly TreeNodeFromImplicitAllowedTypes<TRow>[]) => void;
+		removeRows(rows: readonly string[]): TreeNodeFromImplicitAllowedTypes<TRow>[];
 
 		/**
 		 * Removes all rows from the table.
+		 * @returns The removed rows.
 		 */
-		removeAllRows: () => void;
+		removeAllRows(): TreeNodeFromImplicitAllowedTypes<TRow>[];
 
 		/**
 		 * Removes the cell at the specified location in the table.
-		 * @privateRemarks TODO: add overload that takes column/row nodes?
+		 * @returns The cell if it exists, otherwise undefined.
+		 * @throws Throws an error if the location does not exist in the table.
 		 */
-		removeCell: (key: CellKey) => void;
+		removeCell(
+			key: CellKey<TColumn, TRow>,
+		): TreeNodeFromImplicitAllowedTypes<TCell> | undefined;
 	}
 
 	/**
 	 * Factory for creating new table schema without specifying row or column schema.
 	 * @internal
 	 */
-	export function createTable<
+	export function table<
 		const TScope extends string | undefined,
 		const TCell extends ImplicitAllowedTypes,
-	>({
-		schemaFactory,
-		cell,
-	}: System_TableSchema.TableFactoryOptionsBase<TScope, TCell>): ReturnType<
-		typeof System_TableSchema.createTableInternal<TScope, TCell>
+	>(
+		params: System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell>,
+	): System_TableSchema.TableSchemaBase<
+		TScope,
+		TCell,
+		System_TableSchema.ColumnSchemaBase<TScope, System_TableSchema.DefaultPropsType>,
+		System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>
 	>;
 	/**
 	 * Factory for creating new table schema without specifying row schema.
 	 * @internal
 	 */
-	export function createTable<
+	export function table<
 		const TScope extends string | undefined,
 		const TCell extends ImplicitAllowedTypes,
 		const TColumn extends System_TableSchema.ColumnSchemaBase<TScope>,
-	>({
-		schemaFactory,
-		cell,
-		column,
-	}: System_TableSchema.TableFactoryOptionsBase<TScope, TCell> & {
-		readonly column: TColumn;
-	}): ReturnType<typeof System_TableSchema.createTableInternal<TScope, TCell, TColumn>>;
+	>(
+		params: System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & {
+			readonly column: TColumn;
+		},
+	): System_TableSchema.TableSchemaBase<
+		TScope,
+		TCell,
+		TColumn,
+		System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>
+	>;
 	/**
 	 * Factory for creating new table schema.
 	 * @internal
 	 */
-	export function createTable<
+	export function table<
 		const TScope extends string | undefined,
 		const TCell extends ImplicitAllowedTypes,
 		const TColumn extends System_TableSchema.ColumnSchemaBase<TScope>,
 		const TRow extends System_TableSchema.RowSchemaBase<TScope, TCell>,
-	>({
-		schemaFactory,
-		cell,
-		column,
-		row,
-	}: System_TableSchema.TableFactoryOptionsBase<TScope, TCell> & {
-		readonly column: TColumn;
-		readonly row: TRow;
-	}): ReturnType<typeof System_TableSchema.createTableInternal<TScope, TCell, TColumn, TRow>>;
+	>(
+		params: System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & {
+			readonly column: TColumn;
+			readonly row: TRow;
+		},
+	): System_TableSchema.TableSchemaBase<TScope, TCell, TColumn, TRow>;
 	/**
 	 * Overload implementation
 	 */
-	export function createTable({
+	export function table({
 		schemaFactory,
-		cell,
-		column = createColumn({
+		cell: cellSchema,
+		column: columnSchema = column({
 			schemaFactory,
 		}),
-		row = createRow({
+		row: rowSchema = row({
 			schemaFactory,
-			cell,
+			cell: cellSchema,
 		}),
 	}: System_TableSchema.TableFactoryOptionsBase & {
 		readonly column?: System_TableSchema.ColumnSchemaBase;
 		readonly row?: System_TableSchema.RowSchemaBase;
 	}): TreeNodeSchema {
-		return System_TableSchema.createTableInternal(schemaFactory, cell, column, row);
+		return System_TableSchema.createTableSchema(
+			schemaFactory,
+			cellSchema,
+			columnSchema,
+			rowSchema,
+		);
 	}
 
 	// #endregion