TableSchema Namespace

Contains types and factories for creating schema to represent dynamic tabular data.

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

For more information about our API support guarantees, see here.

Signature

export declare namespace TableSchema

Remarks

WARNING: These APIs are in preview and are subject to change. Until these APIs have stabilized, it is not recommended to use them in production code. There may be breaking changes to these APIs and their underlying data format. Using these APIs in production code may result in data loss or corruption.

The primary APIs for create tabular data schema are:

• table(params)

• column(params)

• row(params)

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.

Cells in the table may become "orphaned." That is, it is possible to enter a state where one or more rows contain cells with no corresponding column. To reduce the likelihood of this, 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.

Usage

Example 1

Defining a Table schema

class MyTable extends TableSchema.table({
	schemaFactory,
	cell: schemaFactory.string,
}) {}
const table = new MyTable({
	columns: [{ id: "column-0" }],
	rows: [{ id: "row-0", cells: { "column-0": "Hello world!" } }],
});

Example 2

Customizing Column and Row schema

const Cell = schemaFactory.string;
class MyColumn extends TableSchema.column({
	schemaFactory,
	cell: Cell,
	props: schemaFactory.object("TableColumnProps", {
		label: schemaFactory.string,
	}),
}) {}
class MyRow extends TableSchema.row({
	schemaFactory,
	cell: Cell,
}) {}
class MyTable extends TableSchema.table({
	schemaFactory,
	cell: Cell,
	column: MyColumn,
	row: MyRow,
}) {}
const table = new MyTable({
	columns: [
		new MyColumn({ props: { label: "Entry" } }),
		new MyColumn({ props: { label: "Date" } }),
		new MyColumn({ props: { label: "Amount" } }),
	],
	rows: [],
});

Example 3

Listening for changes in the table

// Listen for any changes to the table and its children.
// The "treeChanged" event will fire when the associated node or any of its descendants change.
Tree.on(table, "treeChanged", () => {
	// Respond to the change.
});

Example 4

Listening for changes to the rows list only

// Listen for any changes to the list of rows.
// The "nodeChanged" event will fire only when the specified node itself changes (i.e., its own properties change).
// In this case, the event will fire when a row is added or removed, or the order of the list is changed.
// But it won't fire when a row's properties change, or when the row's cells change, etc.
Tree.on(table.rows, "nodeChanged", () => {
	// Respond to the change.
});

Example 5

Removing column and cells in a transaction

When removing a column, if you wish to ensure that all of its corresponding cells are also removed (and not orphaned), you can remove the column and all of the relevant cells in a transaction. Note that there are performance implications to this.

// Remove column1 and all of its cells.
// The "transaction" method will ensure that all changes are applied atomically.
Tree.runTransaction(table, () => {
	// Remove column1.
	table.removeColumn(column1);
	// Remove the cell at column1 for each row.
	for (const row of table.rows) {
		table.removeCell({
			column: column1,
			row,
		});
	}
});

Interfaces

Interface	Alerts	Modifiers	Description
CellKey	Alpha		A key to uniquely identify a cell within a table.
Column	Alpha	sealed	A column in a table.
InsertColumnParameters	Alpha		insertColumn(params) parameters.
InsertColumnsParameters	Alpha		insertColumns(params) parameters.
InsertRowParameters	Alpha		insertRow(params) parameters.
InsertRowsParameters	Alpha		insertRows(params) parameters.
Row	Alpha	sealed	A row in a table.
SetCellParameters	Alpha		setCell(params) parameters.
Table	Alpha	sealed	A table.

Functions

Function	Alerts	Return Type	Description
column(params)	Alpha	System_TableSchema.ColumnSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>	Factory for creating new table column schema.
column(params)	Alpha	System_TableSchema.ColumnSchemaBase<TScope, TCell, TProps>	Factory for creating new table column schema.
row(params)	Alpha	System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>	Factory for creating new table column schema.
row(params)	Alpha	System_TableSchema.RowSchemaBase<TScope, TCell, TProps>	Factory for creating new table row schema.
table(params)	Alpha	System_TableSchema.TableSchemaBase<TScope, TCell, System_TableSchema.ColumnSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>, System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>>	Factory for creating new table schema.
table(params)	Alpha	System_TableSchema.TableSchemaBase<TScope, TCell, TColumn, System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>>	Factory for creating new table schema with custom column schema.
table(params)	Alpha	System_TableSchema.TableSchemaBase<TScope, TCell, System_TableSchema.ColumnSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>, TRow>	Factory for creating new table schema with custom row schema.
table(params)	Alpha	System_TableSchema.TableSchemaBase<TScope, TCell, TColumn, TRow>	Factory for creating new table schema with custom column and row schema.

Function Details

column

Factory for creating new table column schema.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

function column<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes>(params: System_TableSchema.CreateColumnOptionsBase<SchemaFactoryAlpha<TScope>, TCell>): System_TableSchema.ColumnSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>;

Type Parameters

Parameter	Constraint	Description
TScope	string | undefined	The schema factory scope.
TCell	ImplicitAllowedTypes	The type of the cells in the Table.

Parameters

Parameter	Type	Description
params	System_TableSchema.CreateColumnOptionsBase<SchemaFactoryAlpha<TScope>, TCell>

Returns

Return type: System_TableSchema.ColumnSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>

column

Factory for creating new table column schema.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

function column<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes, const TProps extends ImplicitAnnotatedFieldSchema>(params: System_TableSchema.CreateColumnOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & {
        readonly props: TProps;
    }): System_TableSchema.ColumnSchemaBase<TScope, TCell, TProps>;

Type Parameters

Parameter	Constraint	Description
TScope	string | undefined	The schema factory scope.
TCell	ImplicitAllowedTypes	The type of the cells in the Table.
TProps	ImplicitAnnotatedFieldSchema	Additional properties to associate with the column.

Parameters

Parameter	Type	Description
params	System_TableSchema.CreateColumnOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & { readonly props: TProps; }

Returns

Return type: System_TableSchema.ColumnSchemaBase<TScope, TCell, TProps>

row

Factory for creating new table column schema.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

function row<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes>(params: System_TableSchema.CreateRowOptionsBase<SchemaFactoryAlpha<TScope>, TCell>): System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>;

Type Parameters

Parameter	Constraint	Description
TScope	string | undefined	The schema factory scope.
TCell	ImplicitAllowedTypes	The type of the cells in the Table.

Parameters

Parameter	Type	Description
params	System_TableSchema.CreateRowOptionsBase<SchemaFactoryAlpha<TScope>, TCell>

Returns

Return type: System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>

row

Factory for creating new table row schema.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

function row<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes, const TProps extends ImplicitAnnotatedFieldSchema>(params: System_TableSchema.CreateRowOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & {
        readonly props: TProps;
    }): System_TableSchema.RowSchemaBase<TScope, TCell, TProps>;

Type Parameters

Parameter	Constraint	Description
TScope	string | undefined	The schema factory scope.
TCell	ImplicitAllowedTypes	The type of the cells in the Table.
TProps	ImplicitAnnotatedFieldSchema	Additional properties to associate with the row.

Parameters

Parameter	Type	Description
params	System_TableSchema.CreateRowOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & { readonly props: TProps; }

Returns

Return type: System_TableSchema.RowSchemaBase<TScope, TCell, TProps>

table

Factory for creating new table schema.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

function table<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes>(params: System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell>): System_TableSchema.TableSchemaBase<TScope, TCell, System_TableSchema.ColumnSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>, System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>>;

Type Parameters

Parameter	Constraint	Description
TScope	string | undefined	The schema factory scope.
TCell	ImplicitAllowedTypes	The type of the cells in the table.

Parameters

Parameter	Type	Description
params	System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell>

Returns

Return type: System_TableSchema.TableSchemaBase<TScope, TCell, System_TableSchema.ColumnSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>, System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>>

table

Factory for creating new table schema with custom column schema.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

function table<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes, const TColumn extends System_TableSchema.ColumnSchemaBase<TScope, TCell>>(params: System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & {
        readonly column: TColumn;
    }): System_TableSchema.TableSchemaBase<TScope, TCell, TColumn, System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>>;

Type Parameters

Parameter	Constraint	Description
TScope	string | undefined	The schema factory scope.
TCell	ImplicitAllowedTypes	The type of the cells in the table.
TColumn	System_TableSchema.ColumnSchemaBase<TScope, TCell>	The type of the columns in the table.

Parameters

Parameter	Type	Description
params	System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & { readonly column: TColumn; }

Returns

Return type: System_TableSchema.TableSchemaBase<TScope, TCell, TColumn, System_TableSchema.RowSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>>

table

Factory for creating new table schema with custom row schema.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

function table<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes, const TRow extends System_TableSchema.RowSchemaBase<TScope, TCell>>(params: System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & {
        readonly row: TRow;
    }): System_TableSchema.TableSchemaBase<TScope, TCell, System_TableSchema.ColumnSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>, TRow>;

Type Parameters

Parameter	Constraint	Description
TScope	string | undefined	The schema factory scope.
TCell	ImplicitAllowedTypes	The type of the cells in the table.
TRow	System_TableSchema.RowSchemaBase<TScope, TCell>	The type of the rows in the table.

Parameters

Parameter	Type	Description
params	System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & { readonly row: TRow; }

Returns

Return type: System_TableSchema.TableSchemaBase<TScope, TCell, System_TableSchema.ColumnSchemaBase<TScope, TCell, System_TableSchema.DefaultPropsType>, TRow>

table

Factory for creating new table schema with custom column and row schema.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

function table<const TScope extends string | undefined, const TCell extends ImplicitAllowedTypes, const TColumn extends System_TableSchema.ColumnSchemaBase<TScope, TCell>, const TRow extends System_TableSchema.RowSchemaBase<TScope, TCell>>(params: System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & {
        readonly column: TColumn;
        readonly row: TRow;
    }): System_TableSchema.TableSchemaBase<TScope, TCell, TColumn, TRow>;

Type Parameters

Parameter	Constraint	Description
TScope	string | undefined	The schema factory scope.
TCell	ImplicitAllowedTypes	The type of the cells in the table.
TColumn	System_TableSchema.ColumnSchemaBase<TScope, TCell>	The type of the columns in the table.
TRow	System_TableSchema.RowSchemaBase<TScope, TCell>	The type of the rows in the table.

Parameters

Parameter	Type	Description
params	System_TableSchema.TableFactoryOptionsBase<SchemaFactoryAlpha<TScope>, TCell> & { readonly column: TColumn; readonly row: TRow; }

Returns

Return type: System_TableSchema.TableSchemaBase<TScope, TCell, TColumn, TRow>