@tanstack/table-core 9.0.0-alpha.6 → 9.0.0-beta.1

package/src/core/reactivity/coreReactivityFeature.utils.ts

@@ -0,0 +1,44 @@
+import type { Atom, ReadonlyAtom, ReadonlyStore, Store } from '@tanstack/store'
+
+/**
+ * Converts a writable atom to the store-compatible shape expected by core.
+ *
+ * @example
+ * ```ts
+ * const store = atomToStore(atom)
+ * ```
+ */
+export function atomToStore<T>(atom: Atom<T>): Store<T>
+/**
+ * Converts a readonly atom to a readonly store-compatible shape.
+ *
+ * @example
+ * ```ts
+ * const store = atomToStore(atom)
+ * ```
+ */
+export function atomToStore<T>(atom: ReadonlyAtom<T>): ReadonlyStore<T>
+/**
+ * Bridges atom instances to the `Store`/`ReadonlyStore` API by exposing
+ * a `state` getter backed by `atom.get()`, and wiring `setState` for
+ * writable atoms.
+ *
+ * @example
+ * ```ts
+ * const store = atomToStore(atom)
+ * ```
+ */
+export function atomToStore<T>(
+  atom: Atom<T> | ReadonlyAtom<T>,
+): Store<T> | ReadonlyStore<T> {
+  const store: Store<T> = atom as Store<T>
+  Object.defineProperty(atom, 'state', {
+    get() {
+      return atom.get()
+    },
+  })
+  if ('set' in atom) {
+    store.setState = atom.set.bind(atom)
+  }
+  return store
+}

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

@@ -0,0 +1,83 @@
+import { assignTableAPIs } from '../../utils'
+import {
+  table_getCoreRowModel,
+  table_getExpandedRowModel,
+  table_getFilteredRowModel,
+  table_getGroupedRowModel,
+  table_getPaginatedRowModel,
+  table_getPreExpandedRowModel,
+  table_getPreFilteredRowModel,
+  table_getPreGroupedRowModel,
+  table_getPrePaginatedRowModel,
+  table_getPreSortedRowModel,
+  table_getRowModel,
+  table_getSortedRowModel,
+} from './coreRowModelsFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type { Table_RowModels } from './coreRowModelsFeature.types'
+
+export interface CoreRowModelsFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Table: Table_RowModels<TFeatures, TData>
+}
+
+/**
+ * Creates the stock core row models feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
+export function constructCoreRowModelsFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<CoreRowModelsFeatureConstructors<TFeatures, TData>> {
+  return {
+    constructTableAPIs: (table) => {
+      assignTableAPIs('coreRowModelsFeature', table, {
+        table_getCoreRowModel: {
+          fn: () => table_getCoreRowModel(table),
+        },
+        table_getPreFilteredRowModel: {
+          fn: () => table_getPreFilteredRowModel(table),
+        },
+        table_getFilteredRowModel: {
+          fn: () => table_getFilteredRowModel(table),
+        },
+        table_getPreGroupedRowModel: {
+          fn: () => table_getPreGroupedRowModel(table),
+        },
+        table_getGroupedRowModel: {
+          fn: () => table_getGroupedRowModel(table),
+        },
+        table_getPreSortedRowModel: {
+          fn: () => table_getPreSortedRowModel(table),
+        },
+        table_getSortedRowModel: {
+          fn: () => table_getSortedRowModel(table),
+        },
+        table_getPreExpandedRowModel: {
+          fn: () => table_getPreExpandedRowModel(table),
+        },
+        table_getExpandedRowModel: {
+          fn: () => table_getExpandedRowModel(table),
+        },
+        table_getPrePaginatedRowModel: {
+          fn: () => table_getPrePaginatedRowModel(table),
+        },
+        table_getPaginatedRowModel: {
+          fn: () => table_getPaginatedRowModel(table),
+        },
+        table_getRowModel: {
+          fn: () => table_getRowModel(table),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Core Row Models feature provides the core row model functionality.
+ */
+export const coreRowModelsFeature = constructCoreRowModelsFeature()

package/src/core/row-models/coreRowModelsFeature.types.ts

@@ -0,0 +1,68 @@
+import type { Table } from '../../types/Table'
+import type { Table_RowModels_Faceted } from '../../features/column-faceting/columnFacetingFeature.types'
+import type { Table_RowModels_Filtered } from '../../features/column-filtering/columnFilteringFeature.types'
+import type { Table_RowModels_Grouped } from '../../features/column-grouping/columnGroupingFeature.types'
+import type { Table_RowModels_Expanded } from '../../features/row-expanding/rowExpandingFeature.types'
+import type { Table_RowModels_Paginated } from '../../features/row-pagination/rowPaginationFeature.types'
+import type { Table_RowModels_Sorted } from '../../features/row-sorting/rowSortingFeature.types'
+import type { Row } from '../../types/Row'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowData } from '../../types/type-utils'
+
+export interface RowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  rows: Array<Row<TFeatures, TData>>
+  flatRows: Array<Row<TFeatures, TData>>
+  rowsById: Record<string, Row<TFeatures, TData>>
+}
+
+export interface CreateRowModel_Plugins {}
+
+export interface CreateRowModel_Core<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> extends CreateRowModel_Plugins {
+  /**
+   * Optional factory for the core row model. When omitted, the built-in
+   * `createCoreRowModel()` factory is used.
+   */
+  coreRowModel?: (
+    table: Table<TFeatures, TData>,
+  ) => () => RowModel<TFeatures, TData>
+}
+
+export interface CachedRowModel_Plugins {}
+
+export interface CachedRowModel_Core<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> extends CachedRowModel_Plugins {
+  coreRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface Table_RowModels_Core<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns the core row model before any processing has been applied.
+   */
+  getCoreRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Returns the final model after all processing from other used features has been applied. This is the row model that is most commonly used for rendering.
+   */
+  getRowModel: () => RowModel<TFeatures, TData>
+}
+
+export type Table_RowModels<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = Table_RowModels_Core<TFeatures, TData> &
+  Table_RowModels_Faceted<TFeatures, TData> &
+  Table_RowModels_Filtered<TFeatures, TData> &
+  Table_RowModels_Grouped<TFeatures, TData> &
+  Table_RowModels_Expanded<TFeatures, TData> &
+  Table_RowModels_Paginated<TFeatures, TData> &
+  Table_RowModels_Sorted<TFeatures, TData>

package/src/core/row-models/coreRowModelsFeature.utils.ts

@@ -0,0 +1,272 @@
+import { createCoreRowModel } from './createCoreRowModel'
+import type { Table_Internal } from '../../types/Table'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowData } from '../../types/type-utils'
+import type { RowModel } from './coreRowModelsFeature.types'
+
+/**
+ * Resolves the table's unmodified core row model.
+ *
+ * The factory is created once per table, either from `options.rowModels.coreRowModel`
+ * or the built-in `createCoreRowModel()`, then reused for later calls.
+ *
+ * @example
+ * ```ts
+ * const coreRows = table_getCoreRowModel(table)
+ * ```
+ */
+export function table_getCoreRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  if (!table._rowModels.coreRowModel) {
+    table._rowModels.coreRowModel =
+      table.options.rowModels?.coreRowModel?.(table) ??
+      createCoreRowModel<TFeatures, TData>()(table)
+  }
+
+  return table._rowModels.coreRowModel()
+}
+
+/**
+ * Reads the row model immediately before column/global filtering.
+ *
+ * Filtering is the first derived row-model stage, so this currently aliases
+ * `table.getCoreRowModel()`.
+ *
+ * @example
+ * ```ts
+ * const rowsBeforeFiltering = table_getPreFilteredRowModel(table)
+ * ```
+ */
+export function table_getPreFilteredRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  return table.getCoreRowModel()
+}
+
+/**
+ * Resolves the row model after column and global filtering.
+ *
+ * When `manualFiltering` is enabled, or no filtered row-model factory was
+ * registered, this returns the pre-filtered row model because filtering is
+ * expected to happen outside the table.
+ *
+ * @example
+ * ```ts
+ * const filteredRows = table_getFilteredRowModel(table)
+ * ```
+ */
+export function table_getFilteredRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  if (!table._rowModels.filteredRowModel) {
+    table._rowModels.filteredRowModel =
+      table.options.rowModels?.filteredRowModel?.(table)
+  }
+
+  if (table.options.manualFiltering || !table._rowModels.filteredRowModel) {
+    return table.getPreFilteredRowModel()
+  }
+
+  return table._rowModels.filteredRowModel()
+}
+
+/**
+ * Reads the row model immediately before grouping.
+ *
+ * Grouping runs after filtering, so this aliases `table.getFilteredRowModel()`.
+ *
+ * @example
+ * ```ts
+ * const rowsBeforeGrouping = table_getPreGroupedRowModel(table)
+ * ```
+ */
+export function table_getPreGroupedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  return table.getFilteredRowModel()
+}
+
+/**
+ * Resolves the row model after grouping has produced grouped and aggregated rows.
+ *
+ * When `manualGrouping` is enabled, or no grouped row-model factory was
+ * registered, this returns the pre-grouped row model unchanged.
+ *
+ * @example
+ * ```ts
+ * const groupedRows = table_getGroupedRowModel(table)
+ * ```
+ */
+export function table_getGroupedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  if (!table._rowModels.groupedRowModel) {
+    table._rowModels.groupedRowModel =
+      table.options.rowModels?.groupedRowModel?.(table)
+  }
+
+  if (table.options.manualGrouping || !table._rowModels.groupedRowModel) {
+    return table.getPreGroupedRowModel()
+  }
+
+  return table._rowModels.groupedRowModel()
+}
+
+/**
+ * Reads the row model immediately before sorting.
+ *
+ * Sorting runs after grouping, so this aliases `table.getGroupedRowModel()`.
+ *
+ * @example
+ * ```ts
+ * const rowsBeforeSorting = table_getPreSortedRowModel(table)
+ * ```
+ */
+export function table_getPreSortedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  return table.getGroupedRowModel()
+}
+
+/**
+ * Resolves the row model after sorting has been applied.
+ *
+ * When `manualSorting` is enabled, or no sorted row-model factory was
+ * registered, this returns the pre-sorted row model because sorted data is
+ * expected to be supplied by the caller.
+ *
+ * @example
+ * ```ts
+ * const sortedRows = table_getSortedRowModel(table)
+ * ```
+ */
+export function table_getSortedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  if (!table._rowModels.sortedRowModel) {
+    table._rowModels.sortedRowModel =
+      table.options.rowModels?.sortedRowModel?.(table)
+  }
+
+  if (table.options.manualSorting || !table._rowModels.sortedRowModel) {
+    return table.getPreSortedRowModel()
+  }
+
+  return table._rowModels.sortedRowModel()
+}
+
+/**
+ * Reads the row model immediately before row expansion.
+ *
+ * Expansion runs after sorting, so this aliases `table.getSortedRowModel()`.
+ *
+ * @example
+ * ```ts
+ * const rowsBeforeExpansion = table_getPreExpandedRowModel(table)
+ * ```
+ */
+export function table_getPreExpandedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  return table.getSortedRowModel()
+}
+
+/**
+ * Resolves the row model after expanded rows have been flattened into view.
+ *
+ * When `manualExpanding` is enabled, or no expanded row-model factory was
+ * registered, this returns the pre-expanded row model unchanged.
+ *
+ * @example
+ * ```ts
+ * const expandedRows = table_getExpandedRowModel(table)
+ * ```
+ */
+export function table_getExpandedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  if (!table._rowModels.expandedRowModel) {
+    table._rowModels.expandedRowModel =
+      table.options.rowModels?.expandedRowModel?.(table)
+  }
+
+  if (table.options.manualExpanding || !table._rowModels.expandedRowModel) {
+    return table.getPreExpandedRowModel()
+  }
+
+  return table._rowModels.expandedRowModel()
+}
+
+/**
+ * Reads the row model immediately before pagination.
+ *
+ * Pagination is the final built-in row-model stage, so this aliases
+ * `table.getExpandedRowModel()`.
+ *
+ * @example
+ * ```ts
+ * const rowsBeforePagination = table_getPrePaginatedRowModel(table)
+ * ```
+ */
+export function table_getPrePaginatedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  return table.getExpandedRowModel()
+}
+
+/**
+ * Resolves the row model after pagination has sliced rows for the current page.
+ *
+ * When `manualPagination` is enabled, or no paginated row-model factory was
+ * registered, this returns the pre-paginated row model because pagination is
+ * expected to happen before data reaches the table.
+ *
+ * @example
+ * ```ts
+ * const pageRows = table_getPaginatedRowModel(table)
+ * ```
+ */
+export function table_getPaginatedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  if (!table._rowModels.paginatedRowModel) {
+    table._rowModels.paginatedRowModel =
+      table.options.rowModels?.paginatedRowModel?.(table)
+  }
+
+  if (table.options.manualPagination || !table._rowModels.paginatedRowModel) {
+    return table.getPrePaginatedRowModel()
+  }
+
+  return table._rowModels.paginatedRowModel()
+}
+
+/**
+ * Resolves the final row model consumed by renderers.
+ *
+ * This is the end of the built-in row-model pipeline: core -> filtering ->
+ * grouping -> sorting -> expanding -> pagination.
+ *
+ * @example
+ * ```ts
+ * const visibleRows = table_getRowModel(table)
+ * ```
+ */
+export function table_getRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  return table.getPaginatedRowModel()
+}

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

@@ -0,0 +1,93 @@
+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'
+
+/**
+ * Creates a memoized core row model factory.
+ *
+ * The factory reads the relevant table state atoms and options, then returns a row model function used by the table row-model pipeline.
+ */
+export function createCoreRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
+  return (_table) => {
+    const table: Table_Internal<TFeatures, TData> = _table
+    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: ReadonlyArray<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: ReadonlyArray<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,66 @@
+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 }
+    const features = Object.values(table._features)
+    for (let i = 0; i < features.length; i++) {
+      features[i]!.assignRowPrototype?.(table._rowPrototype, table)
+    }
+  }
+  return table._rowPrototype
+}
+
+/**
+ * Constructs a row instance from normalized table internals.
+ *
+ * This wires core properties, feature prototype APIs, and instance data used by table rendering and row-model operations.
+ */
+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
+  const features = Object.values(table._features)
+  for (let i = 0; i < features.length; i++) {
+    features[i]!.initRowInstanceData?.(row)
+  }
+
+  return row as Row<TFeatures, TData>
+}