@fluidframework/tree 2.74.0-365691 → 2.74.0

package/lib/tableSchema.js

@@ -10,8 +10,9 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 import { fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { TreeAlpha } from "./shared-tree/index.js";
-import { TreeArrayNode, SchemaFactory, withBufferedTreeEvents, } from "./simple-tree/index.js";
+import { SchemaFactoryBeta, TreeArrayNode, SchemaFactory, scoped, withBufferedTreeEvents, objectSchema, eraseSchemaDetailsSubclassable, } from "./simple-tree/index.js";
 import { validateIndex, validateIndexRange } from "./util/index.js";
+import { EmptyKey } from "./core/index.js";
 // Future improvement TODOs:
 // - Omit `cells` property from Row insertion type.
 // - Record-like type parameters / input parameters?
@@ -19,9 +20,10 @@ import { validateIndex, validateIndexRange } from "./util/index.js";
 // 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.
+ * Scope for table schema built-in types.
+ * @remarks User-provided factory scoping will be applied as `com.fluidframework.table<user-scope>`.
  */
-const tableSchemaFactorySubScope = "table";
+const baseSchemaScope = "com.fluidframework.table";
 /**
  * A private symbol put on table schema to help identify them.
  */
@@ -44,7 +46,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, propsSchema) {
-        const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
+        const schemaFactory = createTableScopedFactory(inputSchemaFactory);
         // 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.
@@ -92,7 +94,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 = createTableScopedFactory(inputSchemaFactory);
         // 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.
@@ -147,30 +149,79 @@ 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) {
-        var _Table_instances, _a, _Table_removeCells, _Table_applyEditsInBatch, _Table_tryGetColumn, _Table_getColumn, _Table_containsColumnWithId, _Table_tryGetRow, _Table_getRow;
-        const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
+        var _Table_instances, _a, _Table_removeCells, _Table_applyEditsInBatch, _Table_tryGetColumn, _Table_getColumn, _Table_tryGetRow, _Table_getRow, _Table_validateNewColumns, _Table_validateNewRows;
+        const schemaFactory = createTableScopedFactory(inputSchemaFactory);
+        /**
+         * {@link Table} inner fields.
+         * @remarks Extracted for re-use as construction parameters.
+         * @see {@link Table.create}.
+         */
+        const tableInnerFields = {
+            rows: schemaFactory.array("Table.rows", rowSchema),
+            columns: schemaFactory.array("Table.columns", columnSchema),
+        };
         /**
          * {@link Table} fields.
          * @remarks Extracted for re-use in returned type signature defined later in this function.
          * The implicit typing is intentional.
          */
         const tableFields = {
-            rows: schemaFactory.array("Table.rows", rowSchema),
-            columns: schemaFactory.array("Table.columns", columnSchema),
+            table: schemaFactory.required(schemaFactory.object("Table", tableInnerFields), {
+                // Use an empty key in the stored schema format to help prevent schema-unaware edits from being
+                // made to the table, which may violate intended invariants.
+                key: EmptyKey,
+            }),
         };
         /**
          * The Table schema
          */
-        class Table extends schemaFactory.object("Table", tableFields, {
+        class Table
+        // Calling the objectSchema factory directly rather than using the schemaFactory so we can specify
+        // `implicitlyConstructable: false`, which the SchemaFactory APIs do not yet support.
+        // TODO: when support for configuring `implicitlyConstructable` is added to SchemaFactory, switch to
+        // using that instead.
+         extends objectSchema(
+        /* identifier: */ scoped(schemaFactory, "TableRoot"), 
+        /* info: */ tableFields, 
+        /* implicitlyConstructable: */ false, 
+        /* nodeOptions: */ {
             // Will make it easier to evolve this schema in the future.
             allowUnknownOptionalFields: true,
         }) {
-            constructor() {
-                super(...arguments);
+            constructor(node) {
+                super(node ?? { table: { columns: [], rows: [] } });
                 _Table_instances.add(this);
             }
-            static empty() {
-                return new this({ columns: [], rows: [] });
+            static create(initialContents) {
+                // #region Input validation
+                const columns = initialContents?.columns ?? [];
+                const columnIds = new Set();
+                for (const column of columns) {
+                    columnIds.add(column.id);
+                }
+                const rows = initialContents?.rows ?? [];
+                _a._validateNewColumns(columns, 
+                // New table, so no existing columns to validate against
+                new Set());
+                _a._validateNewRows(rows, 
+                // New table, so no existing rows to validate against
+                new Set(), 
+                // No existing columns to validate cells against, but we do need to validate the new rows against the new columns
+                columnIds);
+                // #endregion
+                return new this(initialContents === undefined
+                    ? undefined
+                    : {
+                        table: initialContents,
+                        // We have typed our constructor to prevent users from calling it directly with insertable contents.
+                        // But the base constructor still allows it. Cast to work around this.
+                    });
+            }
+            get columns() {
+                return this.table.columns;
+            }
+            get rows() {
+                return this.table.rows;
             }
             getColumn(indexOrId) {
                 return __classPrivateFieldGet(this, _Table_instances, "m", _Table_tryGetColumn).call(this, indexOrId);
@@ -191,17 +242,23 @@ export var System_TableSchema;
                 return row.cells[column.id];
             }
             insertColumns({ columns, index, }) {
+                // #region Input validation
+                // Ensure specified index is valid
+                if (index !== undefined) {
+                    validateIndex(index, this.table.columns, "Table.insertColumns", true);
+                }
+                // Ensure the new columns being inserted are valid
+                __classPrivateFieldGet(this, _Table_instances, "m", _Table_validateNewColumns).call(this, columns);
+                // #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(TreeArrayNode.spread(columns));
+                    this.table.columns.insertAtEnd(TreeArrayNode.spread(columns));
                 }
                 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));
+                    this.table.columns.insertAt(index, TreeArrayNode.spread(columns));
                 }
                 // Inserting the input nodes into the tree hydrates them, making them usable as nodes.
                 return columns;
@@ -210,34 +267,20 @@ export var System_TableSchema;
                 // #region Input validation
                 // Ensure specified index is valid
                 if (index !== undefined) {
-                    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.
-                // See: https://github.com/microsoft/TypeScript/issues/52144
-                for (const newRow of rows) {
-                    // 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.cells !== undefined) {
-                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                        const keys = Object.keys(newRow.cells);
-                        for (const key of keys) {
-                            if (!__classPrivateFieldGet(this, _Table_instances, "m", _Table_containsColumnWithId).call(this, 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.`);
-                            }
-                        }
-                    }
+                    validateIndex(index, this.table.rows, "Table.insertRows", true);
                 }
+                // Ensure the new rows being inserted are valid
+                __classPrivateFieldGet(this, _Table_instances, "m", _Table_validateNewRows).call(this, rows);
                 // #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) {
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    this.rows.insertAtEnd(TreeArrayNode.spread(rows));
+                    this.table.rows.insertAtEnd(TreeArrayNode.spread(rows));
                 }
                 else {
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    this.rows.insertAt(index, TreeArrayNode.spread(rows));
+                    this.table.rows.insertAt(index, TreeArrayNode.spread(rows));
                 }
                 // Inserting the input nodes into the tree hydrates them, making them usable as nodes.
                 return rows;
@@ -252,20 +295,20 @@ export var System_TableSchema;
                 if (typeof indexOrColumns === "number" || indexOrColumns === undefined) {
                     let removedColumns;
                     const startIndex = indexOrColumns ?? 0;
-                    const endIndex = count === undefined ? this.columns.length : startIndex + count;
+                    const endIndex = count === undefined ? this.table.columns.length : startIndex + count;
                     // If there are no columns to remove, do nothing
                     if (startIndex === endIndex) {
                         return [];
                     }
-                    validateIndexRange(startIndex, endIndex, this.columns, "Table.removeColumns");
+                    validateIndexRange(startIndex, endIndex, this.table.columns, "Table.removeColumns");
                     __classPrivateFieldGet(this, _Table_instances, "m", _Table_applyEditsInBatch).call(this, () => {
-                        const columnsToRemove = this.columns.slice(startIndex, endIndex);
+                        const columnsToRemove = this.table.columns.slice(startIndex, endIndex);
                         // First, remove all cells that correspond to each column from each row:
                         for (const column of columnsToRemove) {
                             __classPrivateFieldGet(this, _Table_instances, "m", _Table_removeCells).call(this, column);
                         }
                         // Second, remove the column nodes:
-                        removeRangeFromArray(startIndex, endIndex, this.columns, "Table.removeColumns");
+                        removeRangeFromArray(startIndex, endIndex, this.table.columns, "Table.removeColumns");
                         removedColumns = columnsToRemove;
                     });
                     return removedColumns ?? fail(0xc1f /* Transaction did not complete. */);
@@ -287,7 +330,7 @@ export var System_TableSchema;
                         // 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) {
+                            for (const row of this.table.rows) {
                                 // TypeScript is unable to narrow the row type correctly here, hence the cast.
                                 // See: https://github.com/microsoft/TypeScript/issues/52144
                                 this.removeCell({
@@ -296,7 +339,7 @@ export var System_TableSchema;
                                 });
                             }
                             // We have already validated that all of the columns exist above, so this is safe.
-                            this.columns.removeAt(this.columns.indexOf(columnToRemove));
+                            this.table.columns.removeAt(this.table.columns.indexOf(columnToRemove));
                         }
                     });
                     return columnsToRemove;
@@ -305,12 +348,12 @@ export var System_TableSchema;
             removeRows(indexOrRows, count) {
                 if (typeof indexOrRows === "number" || indexOrRows === undefined) {
                     const startIndex = indexOrRows ?? 0;
-                    const endIndex = count === undefined ? this.columns.length : startIndex + count;
+                    const endIndex = count === undefined ? this.table.rows.length : startIndex + count;
                     // If there are no rows to remove, do nothing
                     if (startIndex === endIndex) {
                         return [];
                     }
-                    return removeRangeFromArray(startIndex, endIndex, this.rows, "Table.removeRows");
+                    return removeRangeFromArray(startIndex, endIndex, this.table.rows, "Table.removeRows");
                 }
                 // If there are no rows to remove, do nothing
                 if (indexOrRows.length === 0) {
@@ -328,8 +371,8 @@ export var System_TableSchema;
                     // So if we throw an error here for any row, no rows will be removed.
                     for (const rowToRemove of rowsToRemove) {
                         // We have already validated that all of the rows exist above, so this is safe.
-                        const index = this.rows.indexOf(rowToRemove);
-                        this.rows.removeAt(index);
+                        const index = this.table.rows.indexOf(rowToRemove);
+                        this.table.rows.removeAt(index);
                     }
                 });
                 return rowsToRemove;
@@ -358,6 +401,59 @@ export var System_TableSchema;
                 }
                 throw new UsageError(`The specified column node with ID "${columnOrIdOrIndex.id}" does not exist in the table.`);
             }
+            /**
+             * Validates the provided list of new columns being inserted into the table.
+             * @throws Throws a `UsageError` if any of the following conditions are met:
+             * - A column with a duplicate ID is being inserted.
+             */
+            static _validateNewColumns(newColumns, existingColumnIds) {
+                const newColumnIds = new Set();
+                for (const newColumn of newColumns) {
+                    // #region Ensure each column ID is unique
+                    const newColumnId = newColumn.id;
+                    if (existingColumnIds.has(newColumnId)) {
+                        throw new UsageError(`Attempted to insert a column with ID "${newColumnId}", but a column with that ID already exists in the table.`);
+                    }
+                    if (newColumnIds.has(newColumnId)) {
+                        throw new UsageError(`Attempted to insert multiple columns with ID "${newColumnId}". Column IDs must be unique.`);
+                    }
+                    newColumnIds.add(newColumnId);
+                }
+            }
+            /**
+             * Validates the provided list of new rows being inserted into the table.
+             * @throws Throws a `UsageError` if any of the following conditions are met:
+             * - A row with a duplicate ID is being inserted.
+             * - A row is being inserted that contains cells for columns that do not exist in the table.
+             */
+            static _validateNewRows(newRows, existingRowIds, columnIds) {
+                const newRowIds = new Set();
+                for (const newRow of newRows) {
+                    // #region Ensure each row ID is unique
+                    const newRowId = newRow.id;
+                    if (existingRowIds.has(newRowId)) {
+                        throw new UsageError(`Attempted to insert a row with ID "${newRowId}", but a row with that ID already exists in the table.`);
+                    }
+                    if (newRowIds.has(newRowId)) {
+                        throw new UsageError(`Attempted to insert multiple rows with ID "${newRowId}". Row IDs must be unique.`);
+                    }
+                    newRowIds.add(newRowId);
+                    // #endregion
+                    // #region 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.cells !== undefined) {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const keys = Object.keys(newRow.cells);
+                        for (const key of keys) {
+                            if (!columnIds.has(key)) {
+                                throw new UsageError(`Attempted to insert a row containing a cell under column ID "${key}", but the table does not contain a column with that ID.`);
+                            }
+                        }
+                    }
+                    // #endregion
+                }
+            }
             /**
              * Throw a `UsageError` for a missing Row by its ID or index.
              */
@@ -372,7 +468,7 @@ export var System_TableSchema;
             }
         }
         _a = Table, _Table_instances = new WeakSet(), _Table_removeCells = function _Table_removeCells(column) {
-            for (const row of this.rows) {
+            for (const row of this.table.rows) {
                 // TypeScript is unable to narrow the row type correctly here, hence the cast.
                 // See: https://github.com/microsoft/TypeScript/issues/52144
                 this.removeCell({
@@ -400,21 +496,21 @@ export var System_TableSchema;
             });
         }, _Table_tryGetColumn = function _Table_tryGetColumn(columnOrIdOrIndex) {
             if (typeof columnOrIdOrIndex === "number") {
-                if (columnOrIdOrIndex < 0 || columnOrIdOrIndex >= this.columns.length) {
+                if (columnOrIdOrIndex < 0 || columnOrIdOrIndex >= this.table.columns.length) {
                     return undefined;
                 }
                 // TypeScript is unable to narrow the types correctly here, hence the cast.
                 // See: https://github.com/microsoft/TypeScript/issues/52144
-                return this.columns[columnOrIdOrIndex];
+                return this.table.columns[columnOrIdOrIndex];
             }
             if (typeof columnOrIdOrIndex === "string") {
                 const columnId = columnOrIdOrIndex;
                 // TypeScript is unable to narrow the types correctly here, hence the casts.
                 // See: https://github.com/microsoft/TypeScript/issues/52144
-                return this.columns.find((col) => col.id === columnId);
+                return this.table.columns.find((col) => col.id === columnId);
             }
             // If the user provided a node, ensure it actually exists in this table.
-            if (!this.columns.includes(columnOrIdOrIndex)) {
+            if (!this.table.columns.includes(columnOrIdOrIndex)) {
                 return undefined;
             }
             return columnOrIdOrIndex;
@@ -424,25 +520,23 @@ export var System_TableSchema;
                 _a._throwMissingColumnError(columnOrIdOrIndex);
             }
             return column;
-        }, _Table_containsColumnWithId = function _Table_containsColumnWithId(columnId) {
-            return __classPrivateFieldGet(this, _Table_instances, "m", _Table_tryGetColumn).call(this, columnId) !== undefined;
         }, _Table_tryGetRow = function _Table_tryGetRow(rowOrIdOrIndex) {
             if (typeof rowOrIdOrIndex === "number") {
-                if (rowOrIdOrIndex < 0 || rowOrIdOrIndex >= this.rows.length) {
+                if (rowOrIdOrIndex < 0 || rowOrIdOrIndex >= this.table.rows.length) {
                     return undefined;
                 }
                 // TypeScript is unable to narrow the types correctly here, hence the cast.
                 // See: https://github.com/microsoft/TypeScript/issues/52144
-                return this.rows[rowOrIdOrIndex];
+                return this.table.rows[rowOrIdOrIndex];
             }
             if (typeof rowOrIdOrIndex === "string") {
                 const rowId = rowOrIdOrIndex;
                 // TypeScript is unable to narrow the types correctly here, hence the casts.
                 // See: https://github.com/microsoft/TypeScript/issues/52144
-                return this.rows.find((row) => row.id === rowId);
+                return this.table.rows.find((row) => row.id === rowId);
             }
             // If the user provided a node, ensure it actually exists in this table.
-            if (!this.rows.includes(rowOrIdOrIndex)) {
+            if (!this.table.rows.includes(rowOrIdOrIndex)) {
                 return undefined;
             }
             return rowOrIdOrIndex;
@@ -452,6 +546,10 @@ export var System_TableSchema;
                 _a._throwMissingRowError(rowOrIdOrIndex);
             }
             return row;
+        }, _Table_validateNewColumns = function _Table_validateNewColumns(newColumns) {
+            return _a._validateNewColumns(newColumns, new Set(this.table.columns.map((column) => column.id)));
+        }, _Table_validateNewRows = function _Table_validateNewRows(newRows) {
+            return _a._validateNewRows(newRows, new Set(this.table.rows.map((row) => row.id)), new Set(this.table.columns.map((column) => column.id)));
         };
         // Set a private symbol on the schema class that marks it as having been generated by this factory.
         // Column / Row functionality use this to validate that they are being used in a table.
@@ -463,14 +561,17 @@ export var System_TableSchema;
         // for the private brand field of TreeNode.
         // This numeric id doesn't seem to be stable over incremental builds, and thus causes diffs in the API extractor reports.
         // This is avoided by doing this type conversion.
-        // The conversion is done via assignment instead of `as` to get stronger type safety.
-        const TableSchemaType = Table;
+        // The conversion is done via eraseSubclassableSchemaDetails to erase internal details.
+        const TableSchemaType = eraseSchemaDetailsSubclassable()(Table);
         // Return the table schema
         return TableSchemaType;
     }
     System_TableSchema.createTableSchema = createTableSchema;
     // #endregion
 })(System_TableSchema || (System_TableSchema = {}));
+function createTableScopedFactory(inputSchemaFactory) {
+    return new SchemaFactoryBeta(`${baseSchemaScope}<${inputSchemaFactory.scope}>`);
+}
 /**
  * Removes the specified range of elements from the array.
  * @returns The removed elements.
@@ -528,7 +629,7 @@ function removeRangeFromArray(startIndex, endIndex, array, methodName) {
  * 	cell: schemaFactory.string,
  * }) {}
  *
- * const table = new MyTable({
+ * const table = MyTable.create({
  * 	columns: [{ id: "column-0" }],
  * 	rows: [{ id: "row-0", cells: { "column-0": "Hello world!" } }],
  * });