@fluidframework/tree 2.53.1 → 2.61.0-355054

package/lib/tableSchema.js

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { Tree, TreeAlpha } from "./shared-tree/index.js";
 import { TreeArrayNode, SchemaFactory, isArrayNodeSchema, } from "./simple-tree/index.js";
@@ -60,7 +60,7 @@ export var System_TableSchema;
      */
     // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
     function createColumnSchema(inputSchemaFactory, cellSchema, propsSchema) {
-        const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
+        const schemaFactory = inputSchemaFactory.scopedFactoryAlpha(tableSchemaFactorySubScope);
         // 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.
@@ -125,7 +125,7 @@ export var System_TableSchema;
      */
     // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
     function createRowSchema(inputSchemaFactory, cellSchema, propsSchema) {
-        const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
+        const schemaFactory = inputSchemaFactory.scopedFactoryAlpha(tableSchemaFactorySubScope);
         // 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.
@@ -220,7 +220,7 @@ export var System_TableSchema;
      */
     // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- Return type is too complex to be reasonable to specify
     function createTableSchema(inputSchemaFactory, _cellSchema, columnSchema, rowSchema) {
-        const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
+        const schemaFactory = inputSchemaFactory.scopedFactoryAlpha(tableSchemaFactorySubScope);
         /**
          * {@link Table} fields.
          * @remarks Extracted for re-use in returned type signature defined later in this function.
@@ -252,23 +252,16 @@ export var System_TableSchema;
             }
             getCell(key) {
                 const { column: columnOrId, row: rowOrId } = key;
-                const row = this._getRow(rowOrId);
+                const row = this._tryGetRow(rowOrId);
                 if (row === undefined) {
                     return undefined;
                 }
-                const column = this._getColumn(columnOrId);
+                const column = this._tryGetColumn(columnOrId);
                 if (column === undefined) {
                     return undefined;
                 }
                 return row.getCell(column);
             }
-            insertColumn({ column, index, }) {
-                const inserted = this.insertColumns({
-                    columns: [column],
-                    index,
-                });
-                return inserted[0] ?? oob();
-            }
             insertColumns({ columns, index, }) {
                 // Ensure index is valid
                 if (index !== undefined) {
@@ -287,13 +280,6 @@ export var System_TableSchema;
                 // Inserting the input nodes into the tree hydrates them, making them usable as nodes.
                 return columns;
             }
-            insertRow({ row, index, }) {
-                const inserted = this.insertRows({
-                    rows: [row],
-                    index,
-                });
-                return inserted[0] ?? oob();
-            }
             insertRows({ index, rows, }) {
                 // #region Input validation
                 // Ensure index is valid
@@ -310,7 +296,7 @@ export var System_TableSchema;
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any
                         const keys = Object.keys(newRow.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.`);
                             }
                         }
@@ -333,113 +319,101 @@ export var System_TableSchema;
             setCell({ key, cell, }) {
                 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);
             }
-            removeColumns(columns) {
-                // 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];
+            removeColumns(indexOrColumns, count = undefined) {
+                if (typeof indexOrColumns === "number" || indexOrColumns === undefined) {
+                    let removedColumns;
+                    const startIndex = indexOrColumns ?? 0;
+                    const _count = count ?? this.columns.length - startIndex;
+                    // If there are no columns to remove, do nothing
+                    if (_count === 0) {
+                        return [];
+                    }
+                    Table._assertValidRange({ index: startIndex, count: _count }, this.columns);
+                    this._applyEditsInBatch(() => {
+                        const columnsToRemove = this.columns.slice(startIndex, startIndex + _count);
+                        // First, remove all cells that correspond to each column from each row:
+                        for (const column of columnsToRemove) {
+                            this._removeCells(column);
+                        }
+                        // Second, remove the column nodes:
+                        Table._removeRange({
+                            index: startIndex,
+                            count: _count,
+                        }, this.columns);
+                        removedColumns = columnsToRemove;
+                    });
+                    return removedColumns ?? fail(0xc1f /* Transaction did not complete. */);
                 }
-                // If there are multiple columns to remove, remove them in a transaction.
-                const removedColumns = [];
-                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);
+                else {
+                    // If there are no columns to remove, do nothing
+                    if (indexOrColumns.length === 0) {
+                        return [];
                     }
-                });
-                return removedColumns;
-            }
-            removeColumn(columnOrId) {
-                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.`);
-                }
-                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.removeCell(column);
+                    // Resolve any IDs to actual nodes.
+                    // This validates that all of the rows exist before starting transaction.
+                    // This improves user-facing error experience.
+                    const columnsToRemove = [];
+                    for (const columnOrIdToRemove of indexOrColumns) {
+                        columnsToRemove.push(this._getColumn(columnOrIdToRemove));
                     }
-                    this.columns.removeAt(index);
-                });
-                return column;
-            }
-            removeAllColumns() {
-                // 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);
+                    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) {
+                            // 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.removeCell(columnToRemove);
+                            }
+                            // We have already validated that all of the columns exist above, so this is safe.
+                            this.columns.removeAt(this.columns.indexOf(columnToRemove));
+                        }
+                    });
+                    return columnsToRemove;
+                }
             }
-            removeRows(rows) {
+            removeRows(indexOrRows, count) {
+                if (typeof indexOrRows === "number" || indexOrRows === undefined) {
+                    const startIndex = indexOrRows ?? 0;
+                    const _count = count ?? this.columns.length - startIndex;
+                    // If there are no rows to remove, do nothing
+                    if (_count === 0) {
+                        return [];
+                    }
+                    return Table._removeRange({
+                        index: startIndex,
+                        count: _count,
+                    }, this.rows);
+                }
                 // If there are no rows to remove, do nothing
-                if (rows.length === 0) {
+                if (indexOrRows.length === 0) {
                     return [];
                 }
-                // If there is only one row to remove, remove it (and don't incur cost of transaction)
-                if (rows.length === 1) {
-                    const removedRow = this.removeRow(rows[0] ?? oob());
-                    return [removedRow];
+                // Resolve any IDs to actual nodes.
+                // This validates that all of the rows exist before starting transaction.
+                // This improves user-facing error experience.
+                const rowsToRemove = [];
+                for (const rowToRemove of indexOrRows) {
+                    rowsToRemove.push(this._getRow(rowToRemove));
                 }
-                // If there are multiple rows to remove, remove them in a transaction.
-                const removedRows = [];
-                Tree.runTransaction(this, () => {
+                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 rows) {
-                        const removedRow = this.removeRow(rowToRemove);
-                        removedRows.push(removedRow);
+                    for (const rowToRemove of rowsToRemove) {
+                        // We have already validated that all of the rows exist above, so this is safe.
+                        this.rows.removeAt(this.rows.indexOf(rowToRemove));
                     }
                 });
-                return removedRows;
-            }
-            removeRow(rowOrId) {
-                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;
-            }
-            removeAllRows() {
-                // 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);
+                return rowsToRemove;
             }
             removeCell(key) {
                 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 = row.getCell(column.id);
                 if (cell === undefined) {
                     return undefined;
@@ -447,28 +421,137 @@ export var System_TableSchema;
                 row.removeCell(column.id);
                 return cell;
             }
+            /**
+             * Removes the cell corresponding with the specified column from each row in the table.
+             */
+            _removeCells(column) {
+                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.removeCell(column);
+                }
+            }
+            static _assertValidRange(range, array) {
+                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}.`);
+                }
+            }
+            /**
+             * Applies the provided edits in a "batch".
+             *
+             * @remarks
+             * For hydrated trees, this will be done in a transaction to ensure atomicity.
+             *
+             * 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.
+             */
+            _applyEditsInBatch(applyEdits) {
+                const branch = TreeAlpha.branch(this);
+                if (branch === undefined) {
+                    // If this node does not have a corresponding branch, then it is unhydrated.
+                    // I.e., it is not part of a collaborative session yet.
+                    // Therefore, we don't need to run the edits as a transaction.
+                    applyEdits();
+                }
+                else {
+                    branch.runTransaction(() => {
+                        applyEdits();
+                    });
+                }
+            }
+            /**
+             * Attempts to resolve the provided Column node or ID to a Column node in the table.
+             * Returns `undefined` if there is no match.
+             * @remarks Searches for a match based strictly on the ID and returns that result.
+             */
+            _tryGetColumn(columnOrId) {
+                const columnId = this._getColumnId(columnOrId);
+                return this.getColumn(columnId);
+            }
+            /**
+             * Attempts to resolve the provided Column node or ID to a Column node in the table.
+             * @throws Throws a `UsageError` if there is no match.
+             * @remarks Searches for a match based strictly on the ID and returns that result.
+             */
             _getColumn(columnOrId) {
-                return typeof columnOrId === "string" ? this.getColumn(columnOrId) : columnOrId;
+                const column = this._tryGetColumn(columnOrId);
+                if (column === undefined) {
+                    this._throwMissingColumnError(this._getColumnId(columnOrId));
+                }
+                return column;
             }
+            /**
+             * Resolves a Column node or ID to its ID.
+             * If an ID is provided, it is returned as-is.
+             * If a node is provided, its ID is returned.
+             */
             _getColumnId(columnOrId) {
                 return typeof columnOrId === "string" ? columnOrId : columnOrId.id;
             }
+            /**
+             * Checks if a Column with the specified ID exists in the table.
+             */
+            _containsColumnWithId(columnId) {
+                return this._tryGetColumn(columnId) !== undefined;
+            }
+            /**
+             * Throw a `UsageError` for a missing Column by its ID.
+             */
+            _throwMissingColumnError(columnId) {
+                throw new UsageError(`No column with ID "${columnId}" exists in the table.`);
+            }
+            /**
+             * Attempts to resolve the provided Row node or ID to a Row node in the table.
+             * Returns `undefined` if there is no match.
+             * @remarks Searches for a match based strictly on the ID and returns that result.
+             */
+            _tryGetRow(rowOrId) {
+                const rowId = this._getRowId(rowOrId);
+                return this.getRow(rowId);
+            }
+            /**
+             * Attempts to resolve the provided Row node or ID to a Row node in the table.
+             * @throws Throws a `UsageError` if there is no match.
+             * @remarks Searches for a match based strictly on the ID and returns that result.
+             */
             _getRow(rowOrId) {
-                return typeof rowOrId === "string" ? this.getRow(rowOrId) : rowOrId;
+                const row = this._tryGetRow(rowOrId);
+                if (row === undefined) {
+                    this._throwMissingRowError(this._getRowId(rowOrId));
+                }
+                return row;
             }
+            /**
+             * Resolves a Row node or ID to its ID.
+             * If an ID is provided, it is returned as-is.
+             * If a node is provided, its ID is returned.
+             */
             _getRowId(rowOrId) {
                 return typeof rowOrId === "string" ? rowOrId : rowOrId.id;
             }
-            containsColumnWithId(columnId) {
-                // 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.id === columnId) !== undefined);
+            /**
+             * Throw a `UsageError` for a missing Row by its ID.
+             */
+            _throwMissingRowError(rowId) {
+                throw new UsageError(`No row with ID "${rowId}" exists in the table.`);
             }
-            containsRowWithId(rowId) {
-                // TypeScript is unable to narrow the types correctly here, hence the cast.
+            static _removeRange(range, array) {
+                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
-                return (this.rows.find((row) => row.id === rowId) !==
-                    undefined);
+                const removedRows = array.slice(index, end);
+                array.removeRange(index, end);
+                return removedRows;
             }
             /**
              * Ensure that the specified index is a valid location for item insertion in the destination list.