@tanstack/table-core 9.0.0-alpha.0 → 9.0.0-alpha.11

package/src/core/row-models/createCoreRowModel.ts

@@ -0,0 +1,88 @@
+import { constructRow } from '../rows/constructRow'
+import { tableMemo } from '../../utils'
+import { table_autoResetPageIndex } from '../../features/row-pagination/rowPaginationFeature.utils'
+import type { Table, Table_Internal } from '../../types/Table'
+import type { RowModel } from './coreRowModelsFeature.types'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+import type { RowData } from '../../types/type-utils'
+
+export function createCoreRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
+  return (_table) => {
+    const table = _table as Table_Internal<TFeatures, TData>
+    return tableMemo({
+      feature: 'coreRowModelsFeature',
+      table,
+      fnName: 'table.getCoreRowModel',
+      memoDeps: () => [table.options.data],
+      fn: () => _createCoreRowModel(table, table.options.data),
+      onAfterUpdate: () => table_autoResetPageIndex(table),
+    })
+  }
+}
+
+function _createCoreRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  data: Array<TData>,
+): {
+  rows: Array<Row<TFeatures, TData>>
+  flatRows: Array<Row<TFeatures, TData>>
+  rowsById: Record<string, Row<TFeatures, TData>>
+} {
+  const rowModel: RowModel<TFeatures, TData> = {
+    rows: [],
+    flatRows: [],
+    rowsById: {},
+  }
+
+  const accessRows = (
+    originalRows: Array<TData>,
+    depth = 0,
+    parentRow?: Row<TFeatures, TData>,
+  ): Array<Row<TFeatures, TData>> => {
+    const rows = [] as Array<Row<TFeatures, TData>>
+
+    for (let i = 0; i < originalRows.length; i++) {
+      const originalRow = originalRows[i]!
+      // Make the row
+      const row = constructRow(
+        table,
+        table.getRowId(originalRow, i, parentRow),
+        originalRow,
+        i,
+        depth,
+        undefined,
+        parentRow?.id,
+      )
+
+      // Keep track of every row in a flat array
+      rowModel.flatRows.push(row)
+      // Also keep track of every row by its ID
+      rowModel.rowsById[row.id] = row
+      // Push table row into parent
+      rows.push(row)
+
+      // Get the original subrows
+      if (table.options.getSubRows) {
+        row.originalSubRows = table.options.getSubRows(originalRow, i)
+
+        // Then recursively access them
+        if (row.originalSubRows?.length) {
+          row.subRows = accessRows(row.originalSubRows, depth + 1, row)
+        }
+      }
+    }
+
+    return rows
+  }
+
+  rowModel.rows = accessRows(data)
+
+  return rowModel
+}

package/src/core/rows/constructRow.ts

@@ -0,0 +1,59 @@
+import type { Table_Internal } from '../../types/Table'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+import type { Row_CoreProperties } from './coreRowsFeature.types'
+
+/**
+ * Creates or retrieves the row prototype for a table.
+ * The prototype is cached on the table and shared by all row instances.
+ */
+function getRowPrototype<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): object {
+  if (!table._rowPrototype) {
+    table._rowPrototype = { table }
+    for (const feature of Object.values(table._features)) {
+      feature.assignRowPrototype?.(table._rowPrototype, table)
+    }
+  }
+  return table._rowPrototype
+}
+
+export const constructRow = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  id: string,
+  original: TData,
+  rowIndex: number,
+  depth: number,
+  subRows?: Array<Row<TFeatures, TData>>,
+  parentId?: string,
+): Row<TFeatures, TData> => {
+  // Create row with shared prototype for memory efficiency
+  const rowPrototype = getRowPrototype(table)
+  const row = Object.create(rowPrototype) as Row_CoreProperties<
+    TFeatures,
+    TData
+  >
+
+  // Only assign instance-specific properties
+  row._uniqueValuesCache = {}
+  row._valuesCache = {}
+  row.depth = depth
+  row.id = id
+  row.index = rowIndex
+  row.original = original
+  row.parentId = parentId
+  row.subRows = subRows ?? []
+
+  // Initialize instance-specific data (e.g., caches) for features that need it
+  for (const feature of Object.values(table._features)) {
+    feature.initRowInstanceData?.(row as Row<TFeatures, TData>)
+  }
+
+  return row as Row<TFeatures, TData>
+}

package/src/core/rows/coreRowsFeature.ts

@@ -0,0 +1,84 @@
+import { assignPrototypeAPIs, assignTableAPIs } from '../../utils'
+import {
+  row_getAllCells,
+  row_getAllCellsByColumnId,
+  row_getLeafRows,
+  row_getParentRow,
+  row_getParentRows,
+  row_getUniqueValues,
+  row_getValue,
+  row_renderValue,
+  table_getRow,
+  table_getRowId,
+} from './coreRowsFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   Row_Row,
+//   TableOptions_Rows,
+//   Table_Rows,
+// } from './coreRowsFeature.types'
+
+interface CoreRowsFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Row: Row_Row<TFeatures, TData>
+  // TableOptions: TableOptions_Rows<TFeatures, TData>
+  // Table: Table_Rows<TFeatures, TData>
+}
+
+export function constructCoreRowsFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<CoreRowsFeatureConstructors<TFeatures, TData>> {
+  return {
+    assignRowPrototype: (prototype, table) => {
+      assignPrototypeAPIs('coreRowsFeature', prototype, table, {
+        row_getAllCellsByColumnId: {
+          fn: (row) => row_getAllCellsByColumnId(row),
+          memoDeps: (row) => [row.getAllCells()],
+        },
+        row_getAllCells: {
+          fn: (row) => row_getAllCells(row),
+          memoDeps: (row) => [row.table.getAllLeafColumns()],
+        },
+        row_getLeafRows: {
+          fn: (row) => row_getLeafRows(row),
+        },
+        row_getParentRow: {
+          fn: (row) => row_getParentRow(row),
+        },
+        row_getParentRows: {
+          fn: (row) => row_getParentRows(row),
+        },
+        row_getUniqueValues: {
+          fn: (row, columnId) => row_getUniqueValues(row, columnId),
+        },
+        row_getValue: {
+          fn: (row, columnId) => row_getValue(row, columnId),
+        },
+        row_renderValue: {
+          fn: (row, columnId) => row_renderValue(row, columnId),
+        },
+      })
+    },
+    constructTableAPIs: (table) => {
+      assignTableAPIs('coreRowsFeature', table, {
+        table_getRowId: {
+          fn: (originalRow, index, parent) =>
+            table_getRowId(originalRow, table, index, parent),
+        },
+        table_getRow: {
+          fn: (id: string, searchAll?: boolean) =>
+            table_getRow(table, id, searchAll),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Core Rows feature provides the core row functionality.
+ */
+export const coreRowsFeature = constructCoreRowsFeature()

package/src/core/rows/coreRowsFeature.types.ts

@@ -0,0 +1,111 @@
+import type { Table_Internal } from '../../types/Table'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+import type { Cell } from '../../types/Cell'
+
+export interface Row_CoreProperties<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  _uniqueValuesCache: Record<string, unknown>
+  _valuesCache: Record<string, unknown>
+  /**
+   * The depth of the row (if nested or grouped) relative to the root row array.
+   */
+  depth: number
+  /**
+   * The resolved unique identifier for the row resolved via the `options.getRowId` option. Defaults to the row's index (or relative index if it is a subRow).
+   */
+  id: string
+  /**
+   * The index of the row within its parent array (or the root data array).
+   */
+  index: number
+  /**
+   * The original row object provided to the table. If the row is a grouped row, the original row object will be the first original in the group.
+   */
+  original: TData
+  /**
+   * An array of the original subRows as returned by the `options.getSubRows` option.
+   */
+  originalSubRows?: Array<TData>
+  /**
+   * If nested, this row's parent row id.
+   */
+  parentId?: string
+  /**
+   * An array of subRows for the row as returned and created by the `options.getSubRows` option.
+   */
+  subRows: Array<Row<TFeatures, TData>>
+  /**
+   * Reference to the parent table instance.
+   */
+  table: Table_Internal<TFeatures, TData>
+}
+
+export interface Row_Row<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> extends Row_CoreProperties<TFeatures, TData> {
+  getAllCellsByColumnId: () => Record<string, Cell<TFeatures, TData, unknown>>
+  /**
+   * Returns all of the cells for the row.
+   */
+  getAllCells: () => Array<Cell<TFeatures, TData, unknown>>
+  /**
+   * Returns the leaf rows for the row, not including any parent rows.
+   */
+  getLeafRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Returns the parent row for the row, if it exists.
+   */
+  getParentRow: () => Row<TFeatures, TData> | undefined
+  /**
+   * Returns the parent rows for the row, all the way up to a root row.
+   */
+  getParentRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Returns a unique array of values from the row for a given columnId.
+   */
+  getUniqueValues: <TValue>(columnId: string) => Array<TValue>
+  /**
+   * Returns the value from the row for a given columnId.
+   */
+  getValue: <TValue>(columnId: string) => TValue
+  /**
+   * Renders the value for the row in a given columnId the same as `getValue`, but will return the `renderFallbackValue` if no value is found.
+   */
+  renderValue: <TValue>(columnId: string) => TValue
+}
+
+export interface TableOptions_Rows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * This optional function is used to derive a unique ID for any given row. If not provided the rows index is used (nested rows join together with `.` using their grandparents' index eg. `index.index.index`). If you need to identify individual rows that are originating from any server-side operations, it's suggested you use this function to return an ID that makes sense regardless of network IO/ambiguity eg. a userId, taskId, database ID field, etc.
+   * @example getRowId: row => row.userId
+   */
+  getRowId?: (
+    originalRow: TData,
+    index: number,
+    parent?: Row<TFeatures, TData>,
+  ) => string
+  /**
+   * This optional function is used to access the sub rows for any given row. If you are using nested rows, you will need to use this function to return the sub rows object (or undefined) from the row.
+   * @example getSubRows: row => row.subRows
+   */
+  getSubRows?: (originalRow: TData, index: number) => undefined | Array<TData>
+}
+
+export interface Table_Rows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  getRowId: (_: TData, index: number, parent?: Row<TFeatures, TData>) => string
+  /**
+   * Returns the row with the given ID.
+   */
+  getRow: (id: string, searchAll?: boolean) => Row<TFeatures, TData>
+}

package/src/core/rows/coreRowsFeature.utils.ts

@@ -0,0 +1,152 @@
+import { flattenBy } from '../../utils'
+import { constructCell } from '../cells/constructCell'
+import type { Table_Internal } from '../../types/Table'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+import type { Cell } from '../../types/Cell'
+
+export function row_getValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>, columnId: string) {
+  if (row._valuesCache.hasOwnProperty(columnId)) {
+    return row._valuesCache[columnId]
+  }
+
+  const column = row.table.getColumn(columnId)
+
+  if (!column?.accessorFn) {
+    return undefined
+  }
+
+  row._valuesCache[columnId] = column.accessorFn(row.original, row.index)
+
+  return row._valuesCache[columnId]
+}
+
+export function row_getUniqueValues<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>, columnId: string) {
+  if (row._uniqueValuesCache.hasOwnProperty(columnId)) {
+    return row._uniqueValuesCache[columnId]
+  }
+
+  const column = row.table.getColumn(columnId)
+
+  if (!column?.accessorFn) {
+    return undefined
+  }
+
+  if (!column.columnDef.getUniqueValues) {
+    row._uniqueValuesCache[columnId] = [row.getValue(columnId)]
+    return row._uniqueValuesCache[columnId]
+  }
+
+  row._uniqueValuesCache[columnId] = column.columnDef.getUniqueValues(
+    row.original,
+    row.index,
+  )
+
+  return row._uniqueValuesCache[columnId]
+}
+
+export function row_renderValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>, columnId: string) {
+  return row.getValue(columnId) ?? row.table.options.renderFallbackValue
+}
+
+export function row_getLeafRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>): Array<Row<TFeatures, TData>> {
+  return flattenBy(row.subRows, (d) => d.subRows)
+}
+
+export function row_getParentRow<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  return row.parentId ? row.table.getRow(row.parentId, true) : undefined
+}
+
+export function row_getParentRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  const parentRows: Array<Row<TFeatures, TData>> = []
+  let currentRow = row
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  while (true) {
+    const parentRow = currentRow.getParentRow()
+    if (!parentRow) break
+    parentRows.push(parentRow)
+    currentRow = parentRow
+  }
+  return parentRows.reverse()
+}
+
+export function row_getAllCells<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>): Array<Cell<TFeatures, TData, unknown>> {
+  return row.table.getAllLeafColumns().map((column) => {
+    return constructCell(column, row, row.table)
+  })
+}
+
+export function row_getAllCellsByColumnId<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  return row.getAllCells().reduce(
+    (acc, cell) => {
+      acc[cell.column.id] = cell
+      return acc
+    },
+    {} as Record<string, Cell<TFeatures, TData, unknown>>,
+  )
+}
+
+export function table_getRowId<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  originalRow: TData,
+  table: Table_Internal<TFeatures, TData>,
+  index: number,
+  parent?: Row<TFeatures, TData>,
+) {
+  return (
+    table.options.getRowId?.(originalRow, index, parent) ??
+    `${parent ? [parent.id, index].join('.') : index}`
+  )
+}
+
+export function table_getRow<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  rowId: string,
+  searchAll?: boolean,
+): Row<TFeatures, TData> {
+  // TODO - simplify this across different row models
+  let row = (searchAll ? table.getPrePaginatedRowModel() : table.getRowModel())
+    .rowsById[rowId]
+
+  if (!row) {
+    row = table.getCoreRowModel().rowsById[rowId]
+    if (!row) {
+      if (process.env.NODE_ENV === 'development') {
+        throw new Error(`getRow could not find row with ID: ${rowId}`)
+      }
+      throw new Error()
+    }
+  }
+
+  return row
+}

package/src/core/table/constructTable.ts

@@ -0,0 +1,95 @@
+import { Derived, Store } from '@tanstack/store'
+import {} from '../../utils'
+import { coreFeatures } from '../coreFeatures'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+import type { Table, Table_Internal } from '../../types/Table'
+import type { TableOptions } from '../../types/TableOptions'
+import type { TableState } from '../../types/TableState'
+
+export function getInitialTableState<TFeatures extends TableFeatures>(
+  features: TFeatures,
+  initialState: Partial<TableState<TFeatures>> | undefined = {},
+): TableState<TFeatures> {
+  Object.values(features).forEach((feature) => {
+    initialState =
+      feature.getInitialState?.(initialState as TableState<TFeatures>) ??
+      initialState
+  })
+  return structuredClone(initialState) as TableState<TFeatures>
+}
+
+export function createTableStore<TFeatures extends TableFeatures>(
+  features: TFeatures,
+  initialState: Partial<TableState<TFeatures>> | undefined = {},
+): Store<TableState<TFeatures>> {
+  return new Store(getInitialTableState(features, initialState))
+}
+
+export function constructTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(tableOptions: TableOptions<TFeatures, TData>): Table<TFeatures, TData> {
+  const table = {
+    _features: { ...coreFeatures, ...tableOptions._features },
+    _rowModels: {},
+    _rowModelFns: {},
+  } as Table_Internal<TFeatures, TData>
+
+  const featuresList: Array<TableFeature<{}>> = Object.values(table._features)
+
+  const defaultOptions = featuresList.reduce((obj, feature) => {
+    return Object.assign(obj, feature.getDefaultTableOptions?.(table))
+  }, {}) as TableOptions<TFeatures, TData>
+
+  table.options = {
+    ...defaultOptions,
+    ...tableOptions,
+  }
+
+  table.initialState = getInitialTableState(
+    table._features,
+    table.options.initialState,
+  )
+
+  table.baseStore =
+    table.options.store ?? (new Store(table.initialState) as any)
+
+  // @ts-ignore - complex TFeatures type inference does not work with Derived
+  table.store = new Derived({
+    deps: [table.baseStore],
+    fn: ({ currDepVals }) => {
+      const baseState = currDepVals[0]
+      // Merge base state with user-provided external state (table.options.state takes precedence)
+      return {
+        ...baseState,
+        ...(table.options.state ?? {}),
+      } as TableState<TFeatures>
+    },
+  })
+
+  if (
+    process.env.NODE_ENV === 'development' &&
+    (tableOptions.debugAll || tableOptions.debugTable)
+  ) {
+    const features = Object.keys(table._features)
+    const rowModels = Object.keys(table.options._rowModels || {})
+    const states = Object.keys(table.initialState)
+
+    console.log(
+      `Constructing Table Instance
+    
+  Features:   ${features.join('\n              ')}
+    
+  Row Models: ${rowModels.length ? rowModels.join('\n              ') : '(none)'}
+    
+  States:     ${states.join('\n              ')}`,
+    )
+  }
+
+  for (const feature of featuresList) {
+    feature.constructTableAPIs?.(table)
+  }
+
+  return table
+}

package/src/core/table/coreTablesFeature.ts

@@ -0,0 +1,36 @@
+import { assignTableAPIs } from '../../utils'
+import { table_reset, table_setOptions } from './coreTablesFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type { TableOptions_Table, Table_Table } from './coreTablesFeature.types'
+
+interface CoreTablesFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Table: Table_Table<TFeatures, TData>
+  // TableOptions: TableOptions_Table<TFeatures, TData>
+}
+
+export function constructCoreTablesFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<CoreTablesFeatureConstructors<TFeatures, TData>> {
+  return {
+    constructTableAPIs: (table) => {
+      assignTableAPIs('coreTablesFeature', table, {
+        table_reset: {
+          fn: () => table_reset(table),
+        },
+        table_setOptions: {
+          fn: (updater) => table_setOptions(table, updater),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Core Tables feature provides the core table functionality for handling state and options.
+ */
+export const coreTablesFeature = constructCoreTablesFeature()