@fluidframework/tree 2.40.0 → 2.41.0-338186

package/lib/tableSchema.js

@@ -5,7 +5,7 @@
 import { oob } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { Tree } from "./shared-tree/index.js";
-import { TreeArrayNode, SchemaFactory, } from "./simple-tree/index.js";
+import { TreeArrayNode, SchemaFactory, isArrayNodeSchema, } from "./simple-tree/index.js";
 // Future improvement TODOs:
 // - Omit `cells` property from Row insertion type.
 // - Record-like type parameters / input parameters?
@@ -16,6 +16,32 @@ import { TreeArrayNode, SchemaFactory, } from "./simple-tree/index.js";
  * The sub-scope applied to user-provided {@link SchemaFactory}s by table schema factories.
  */
 const tableSchemaFactorySubScope = "table";
+/**
+ * Gets the table containing the provided row/column node, if the node is part of a table.
+ * @remarks Assumes that the table is the grandparent of the row/column node.
+ */
+function getParentTable(rowOrColumnNode) {
+    const rowListNode = Tree.parent(rowOrColumnNode);
+    if (rowListNode === undefined || !isArrayNodeSchema(Tree.schema(rowListNode))) {
+        return undefined;
+    }
+    const tableNode = Tree.parent(rowListNode);
+    if (tableNode === undefined || !isTableNode(tableNode)) {
+        return undefined;
+    }
+    return tableNode;
+}
+/**
+ * A private symbol put on table schema to help identify them.
+ */
+const tableSchemaSymbol = Symbol("tableNode");
+/**
+ * Type-guard to determine if a node is a table node.
+ * @remarks Uses {@link tableSchemaSymbol} to identify table nodes.
+ */
+function isTableNode(node) {
+    return tableSchemaSymbol in Tree.schema(node);
+}
 /**
  * Not intended for use outside of this package.
  *
@@ -29,11 +55,11 @@ const tableSchemaFactorySubScope = "table";
 export var System_TableSchema;
 (function (System_TableSchema) {
     /**
-     * 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
-    function createColumnInternal(inputSchemaFactory, propsSchema) {
+    function createColumnSchema(inputSchemaFactory, cellSchema, propsSchema) {
         const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
         // Note: `columnFields` is broken into two parts to work around a TypeScript bug
         // that results in broken `.d.ts` output.
@@ -66,6 +92,23 @@ export var System_TableSchema;
             // Will make it easier to evolve this schema in the future.
             allowUnknownOptionalFields: true,
         }) {
+            getCells() {
+                const tableNode = getParentTable(this);
+                if (tableNode === undefined) {
+                    throw new UsageError(`Column with ID "${this.id}" is not contained in a table.`);
+                }
+                const result = [];
+                for (const row of tableNode.rows) {
+                    const cell = row.getCell(this.id);
+                    if (cell !== undefined) {
+                        if (!Tree.is(cell, cellSchema)) {
+                            throw new UsageError("Parent table contains a cell with incompatible with this column.");
+                        }
+                        result.push({ rowId: row.id, cell: cell });
+                    }
+                }
+                return result;
+            }
         }
         // Returning SingletonSchema without a type conversion results in TypeScript generating something like `readonly "__#124291@#brand": unknown;`
         // for the private brand field of TreeNode.
@@ -75,14 +118,13 @@ export var System_TableSchema;
         const ColumnSchemaType = Column;
         return ColumnSchemaType;
     }
-    System_TableSchema.createColumnInternal = createColumnInternal;
+    System_TableSchema.createColumnSchema = createColumnSchema;
     /**
-     * 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
-    function createRowInternal(inputSchemaFactory, cellSchema, propsSchema) {
+    function createRowSchema(inputSchemaFactory, cellSchema, propsSchema) {
         const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
         // Note: `rowFields` is broken into two parts to work around a TypeScript bug
         // that results in broken `.d.ts` output.
@@ -136,6 +178,18 @@ export var System_TableSchema;
                 this.cells.delete(columnId);
                 return cell;
             }
+            getCells() {
+                const result = [];
+                for (const [columnId, cell] of this.cells.entries()) {
+                    if (cell !== undefined) {
+                        result.push({
+                            columnId,
+                            cell,
+                        });
+                    }
+                }
+                return result;
+            }
         }
         // Returning SingletonSchema without a type conversion results in TypeScript generating something like `readonly "__#124291@#brand": unknown;`
         // for the private brand field of TreeNode.
@@ -145,13 +199,13 @@ export var System_TableSchema;
         const RowSchemaType = Row;
         return RowSchemaType;
     }
-    System_TableSchema.createRowInternal = createRowInternal;
+    System_TableSchema.createRowSchema = createRowSchema;
     /**
-     * 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
-    function createTableInternal(inputSchemaFactory, _cellSchema, columnSchema, rowSchema) {
+    function createTableSchema(inputSchemaFactory, _cellSchema, columnSchema, rowSchema) {
         const schemaFactory = inputSchemaFactory.scopedFactory(tableSchemaFactorySubScope);
         /**
          * {@link Table} fields.
@@ -169,6 +223,9 @@ export var System_TableSchema;
             // Will make it easier to evolve this schema in the future.
             allowUnknownOptionalFields: true,
         }) {
+            static empty() {
+                return new this({ columns: [], rows: [] });
+            }
             getColumn(id) {
                 // TypeScript is unable to narrow the types correctly here, hence the casts.
                 // See: https://github.com/microsoft/TypeScript/issues/52144
@@ -199,21 +256,10 @@ export var System_TableSchema;
                 return inserted[0] ?? oob();
             }
             insertColumns({ columns, index, }) {
-                // #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.id;
-                    if (maybeId !== undefined && this.containsColumnWithId(maybeId)) {
-                        throw new UsageError(`A column with ID "${column.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) {
@@ -243,11 +289,6 @@ export var System_TableSchema;
                 // 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.id;
-                    if (maybeId !== undefined && this.containsRowWithId(maybeId)) {
-                        throw new UsageError(`A row with ID "${newRow.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
@@ -398,13 +439,13 @@ export var System_TableSchema;
             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);
+                return (this.columns.find((column) => column.id === columnId) !== undefined);
             }
             containsRowWithId(rowId) {
                 // 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.id === rowId) !== undefined;
+                return (this.rows.find((row) => row.id === rowId) !==
+                    undefined);
             }
             /**
              * Ensure that the specified index is a valid location for item insertion in the destination list.
@@ -422,6 +463,12 @@ export var System_TableSchema;
                 }
             }
         }
+        // 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.
+        // This is effectively a work-around that allows columns and rows to invoke table methods
+        // without having to pass the table as a parameter to their construction, which isn't possible.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        Table[tableSchemaSymbol] = true;
         // Returning SingletonSchema without a type conversion results in TypeScript generating something like `readonly "__#124291@#brand": unknown;`
         // 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.
@@ -431,7 +478,7 @@ export var System_TableSchema;
         // Return the table schema
         return TableSchemaType;
     }
-    System_TableSchema.createTableInternal = createTableInternal;
+    System_TableSchema.createTableSchema = createTableSchema;
     // #endregion
 })(System_TableSchema || (System_TableSchema = {}));
 /**
@@ -465,7 +512,7 @@ export var System_TableSchema;
  * 	value: schemaFactory.string,
  * }) {}
  *
- * class Table extends TableSchema.createTable({
+ * class Table extends TableSchema.table({
  * 	schemaFactory,
  * 	cell: Cell,
  * }) {}
@@ -490,17 +537,18 @@ export var System_TableSchema;
  * 	dataType: schemaFactory.optional(schemaFactory.string),
  * }) {}
  *
- * class Column extends TableSchema.createColumn({
+ * class Column extends TableSchema.column({
  * 	schemaFactory,
+ * 	cell: Cell,
  * 	props: ColumnProps,
  * }) {}
  *
- * class Row extends TableSchema.createRow({
+ * class Row extends TableSchema.row({
  * 	schemaFactory,
  * 	cell: Cell,
  * }) {}
  *
- * class Table extends TableSchema.createTable({
+ * class Table extends TableSchema.table({
  * 	schemaFactory,
  * 	cell: Cell,
  * 	column: Column,
@@ -529,29 +577,30 @@ export var TableSchema;
     /**
      * Overload implementation
      */
-    function createColumn({ schemaFactory, props = SchemaFactory.optional(SchemaFactory.null), }) {
-        return System_TableSchema.createColumnInternal(schemaFactory, props);
+    function column({ schemaFactory, cell, props = SchemaFactory.optional(SchemaFactory.null), }) {
+        return System_TableSchema.createColumnSchema(schemaFactory, cell, props);
     }
-    TableSchema.createColumn = createColumn;
+    TableSchema.column = column;
     /**
      * Overload implementation
      */
-    function createRow({ schemaFactory, cell, props = SchemaFactory.optional(SchemaFactory.null), }) {
-        return System_TableSchema.createRowInternal(schemaFactory, cell, props);
+    function row({ schemaFactory, cell, props = SchemaFactory.optional(SchemaFactory.null), }) {
+        return System_TableSchema.createRowSchema(schemaFactory, cell, props);
     }
-    TableSchema.createRow = createRow;
+    TableSchema.row = row;
     /**
      * Overload implementation
      */
-    function createTable({ schemaFactory, cell, column = createColumn({
+    function table({ schemaFactory, cell: cellSchema, column: columnSchema = column({
         schemaFactory,
-    }), row = createRow({
+        cell: cellSchema,
+    }), row: rowSchema = row({
         schemaFactory,
-        cell,
+        cell: cellSchema,
     }), }) {
-        return System_TableSchema.createTableInternal(schemaFactory, cell, column, row);
+        return System_TableSchema.createTableSchema(schemaFactory, cellSchema, columnSchema, rowSchema);
     }
-    TableSchema.createTable = createTable;
+    TableSchema.table = table;
     // #endregion
 })(TableSchema || (TableSchema = {}));
 //# sourceMappingURL=tableSchema.js.map