@tanstack/table-core 9.0.0-alpha.46 → 9.0.0-alpha.48

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

@@ -5,13 +5,14 @@ import type { RowData } from '../../types/type-utils'
 import type { RowModel } from './coreRowModelsFeature.types'
 
 /**
- * Returns core row model for the table.
+ * Resolves the table's unmodified core row model.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * 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 value = table_getCoreRowModel(table)
+ * const coreRows = table_getCoreRowModel(table)
  * ```
  */
 export function table_getCoreRowModel<
@@ -28,13 +29,14 @@ export function table_getCoreRowModel<
 }
 
 /**
- * Returns pre filtered row model for the table.
+ * Reads the row model immediately before column/global filtering.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Filtering is the first derived row-model stage, so this currently aliases
+ * `table.getCoreRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPreFilteredRowModel(table)
+ * const rowsBeforeFiltering = table_getPreFilteredRowModel(table)
  * ```
  */
 export function table_getPreFilteredRowModel<
@@ -45,13 +47,15 @@ export function table_getPreFilteredRowModel<
 }
 
 /**
- * Returns filtered row model for the table.
+ * Resolves the row model after column and global filtering.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * 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 value = table_getFilteredRowModel(table)
+ * const filteredRows = table_getFilteredRowModel(table)
  * ```
  */
 export function table_getFilteredRowModel<
@@ -71,13 +75,13 @@ export function table_getFilteredRowModel<
 }
 
 /**
- * Returns pre grouped row model for the table.
+ * Reads the row model immediately before grouping.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Grouping runs after filtering, so this aliases `table.getFilteredRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPreGroupedRowModel(table)
+ * const rowsBeforeGrouping = table_getPreGroupedRowModel(table)
  * ```
  */
 export function table_getPreGroupedRowModel<
@@ -88,13 +92,14 @@ export function table_getPreGroupedRowModel<
 }
 
 /**
- * Returns grouped row model for the table.
+ * Resolves the row model after grouping has produced grouped and aggregated rows.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * When `manualGrouping` is enabled, or no grouped row-model factory was
+ * registered, this returns the pre-grouped row model unchanged.
  *
  * @example
  * ```ts
- * const value = table_getGroupedRowModel(table)
+ * const groupedRows = table_getGroupedRowModel(table)
  * ```
  */
 export function table_getGroupedRowModel<
@@ -114,13 +119,13 @@ export function table_getGroupedRowModel<
 }
 
 /**
- * Returns pre sorted row model for the table.
+ * Reads the row model immediately before sorting.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Sorting runs after grouping, so this aliases `table.getGroupedRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPreSortedRowModel(table)
+ * const rowsBeforeSorting = table_getPreSortedRowModel(table)
  * ```
  */
 export function table_getPreSortedRowModel<
@@ -131,13 +136,15 @@ export function table_getPreSortedRowModel<
 }
 
 /**
- * Returns sorted row model for the table.
+ * Resolves the row model after sorting has been applied.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * 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 value = table_getSortedRowModel(table)
+ * const sortedRows = table_getSortedRowModel(table)
  * ```
  */
 export function table_getSortedRowModel<
@@ -157,13 +164,13 @@ export function table_getSortedRowModel<
 }
 
 /**
- * Returns pre expanded row model for the table.
+ * Reads the row model immediately before row expansion.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Expansion runs after sorting, so this aliases `table.getSortedRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPreExpandedRowModel(table)
+ * const rowsBeforeExpansion = table_getPreExpandedRowModel(table)
  * ```
  */
 export function table_getPreExpandedRowModel<
@@ -174,13 +181,14 @@ export function table_getPreExpandedRowModel<
 }
 
 /**
- * Returns expanded row model for the table.
+ * Resolves the row model after expanded rows have been flattened into view.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * When `manualExpanding` is enabled, or no expanded row-model factory was
+ * registered, this returns the pre-expanded row model unchanged.
  *
  * @example
  * ```ts
- * const value = table_getExpandedRowModel(table)
+ * const expandedRows = table_getExpandedRowModel(table)
  * ```
  */
 export function table_getExpandedRowModel<
@@ -200,13 +208,14 @@ export function table_getExpandedRowModel<
 }
 
 /**
- * Returns pre paginated row model for the table.
+ * Reads the row model immediately before pagination.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Pagination is the final built-in row-model stage, so this aliases
+ * `table.getExpandedRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPrePaginatedRowModel(table)
+ * const rowsBeforePagination = table_getPrePaginatedRowModel(table)
  * ```
  */
 export function table_getPrePaginatedRowModel<
@@ -217,13 +226,15 @@ export function table_getPrePaginatedRowModel<
 }
 
 /**
- * Returns paginated row model for the table.
+ * Resolves the row model after pagination has sliced rows for the current page.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * 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 value = table_getPaginatedRowModel(table)
+ * const pageRows = table_getPaginatedRowModel(table)
  * ```
  */
 export function table_getPaginatedRowModel<
@@ -243,13 +254,14 @@ export function table_getPaginatedRowModel<
 }
 
 /**
- * Returns row model for the table.
+ * Resolves the final row model consumed by renderers.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * This is the end of the built-in row-model pipeline: core -> filtering ->
+ * grouping -> sorting -> expanding -> pagination.
  *
  * @example
  * ```ts
- * const value = table_getRowModel(table)
+ * const visibleRows = table_getRowModel(table)
  * ```
  */
 export function table_getRowModel<

package/src/core/rows/constructRow.ts

@@ -14,8 +14,9 @@ function getRowPrototype<
 >(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)
+    const features = Object.values(table._features)
+    for (let i = 0; i < features.length; i++) {
+      features[i]!.assignRowPrototype?.(table._rowPrototype, table)
     }
   }
   return table._rowPrototype
@@ -56,8 +57,9 @@ export const constructRow = <
   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)
+  const features = Object.values(table._features)
+  for (let i = 0; i < features.length; i++) {
+    features[i]!.initRowInstanceData?.(row)
   }
 
   return row as Row<TFeatures, TData>

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

@@ -49,11 +49,11 @@ export interface Row_Row<
   TData extends RowData,
 > extends Row_CoreProperties<TFeatures, TData> {
   /**
-   * Returns all of the cells for the row by column id.
+   * Builds a lookup of this row's cells keyed by leaf column id.
    */
   getAllCellsByColumnId: () => Record<string, Cell<TFeatures, TData, unknown>>
   /**
-   * Returns all of the cells for the row.
+   * Builds one cell for each leaf column, including cells for hidden columns.
    */
   getAllCells: () => Array<Cell<TFeatures, TData, unknown>>
   /**
@@ -69,11 +69,11 @@ export interface Row_Row<
    */
   getParentRows: () => Array<Row<TFeatures, TData>>
   /**
-   * Returns a unique array of values from the row for a given columnId.
+   * Reads the values this row contributes to faceting/grouping for a column.
    */
   getUniqueValues: <TValue>(columnId: string) => Array<TValue>
   /**
-   * Returns the value from the row for a given columnId.
+   * Reads this row's accessor value for a column id and caches the result.
    */
   getValue: <TValue>(columnId: string) => TValue
   /**

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

@@ -7,13 +7,14 @@ import type { Row } from '../../types/Row'
 import type { Cell } from '../../types/Cell'
 
 /**
- * Returns value for a row.
+ * Reads and caches this row's value for a column.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * The value is produced by the column accessor. Missing columns or display
+ * columns without an accessor return `undefined`.
  *
  * @example
  * ```ts
- * const value = row_getValue(row)
+ * const firstName = row_getValue(row, 'firstName')
  * ```
  */
 export function row_getValue<
@@ -36,13 +37,14 @@ export function row_getValue<
 }
 
 /**
- * Returns unique values for a row.
+ * Reads and caches the values used by faceting/grouping for a column.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * If the column defines `getUniqueValues`, that result is used. Otherwise the
+ * row's accessor value is wrapped in a single-item array.
  *
  * @example
  * ```ts
- * const value = row_getUniqueValues(row)
+ * const values = row_getUniqueValues(row, 'tags')
  * ```
  */
 export function row_getUniqueValues<
@@ -80,7 +82,7 @@ export function row_getUniqueValues<
  *
  * @example
  * ```ts
- * const value = row_renderValue(row)
+ * const value = row_renderValue(row, 'firstName')
  * ```
  */
 export function row_renderValue<
@@ -91,13 +93,13 @@ export function row_renderValue<
 }
 
 /**
- * Returns leaf rows for a row.
+ * Flattens this row's descendant tree into leaf rows.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * The row itself is not included; only nested `subRows` are walked.
  *
  * @example
  * ```ts
- * const value = row_getLeafRows(row)
+ * const descendants = row_getLeafRows(row)
  * ```
  */
 export function row_getLeafRows<
@@ -108,13 +110,14 @@ export function row_getLeafRows<
 }
 
 /**
- * Returns parent row for a row.
+ * Looks up this row's direct parent, if it has one.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * Parent lookup searches the pre-pagination row model so parent relationships
+ * are available even when the parent is not on the current page.
  *
  * @example
  * ```ts
- * const value = row_getParentRow(row)
+ * const parent = row_getParentRow(row)
  * ```
  */
 export function row_getParentRow<
@@ -125,13 +128,13 @@ export function row_getParentRow<
 }
 
 /**
- * Returns parent rows for a row.
+ * Collects this row's ancestor chain from root to direct parent.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * The current row is not included. Rows without a parent return an empty array.
  *
  * @example
  * ```ts
- * const value = row_getParentRows(row)
+ * const ancestors = row_getParentRows(row)
  * ```
  */
 export function row_getParentRows<
@@ -151,32 +154,38 @@ export function row_getParentRows<
 }
 
 /**
- * Returns all cells for a row.
+ * Constructs one cell for each leaf column in this row.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * The result follows `table.getAllLeafColumns()` order and includes hidden
+ * columns; visibility-specific APIs filter this list later.
  *
  * @example
  * ```ts
- * const value = row_getAllCells(row)
+ * const cells = row_getAllCells(row)
  * ```
  */
 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)
-  })
+  const columns = row.table.getAllLeafColumns()
+  const cells: Array<Cell<TFeatures, TData, unknown>> = new Array(
+    columns.length,
+  )
+  for (let i = 0; i < columns.length; i++) {
+    cells[i] = constructCell(columns[i]!, row, row.table)
+  }
+  return cells
 }
 
 /**
- * Returns all cells by column id for a row.
+ * Builds a lookup map of this row's cells keyed by column id.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * This is the static implementation behind `row.getAllCellsByColumnId()`.
  *
  * @example
  * ```ts
- * const value = row_getAllCellsByColumnId(row)
+ * const cellsById = row_getAllCellsByColumnId(row)
  * ```
  */
 export function row_getAllCellsByColumnId<
@@ -184,20 +193,23 @@ export function row_getAllCellsByColumnId<
   TData extends RowData,
 >(row: Row<TFeatures, TData>) {
   const result: Record<string, Cell<TFeatures, TData, unknown>> = {}
-  for (const cell of row.getAllCells()) {
+  const cells = row.getAllCells()
+  for (let i = 0; i < cells.length; i++) {
+    const cell = cells[i]!
     result[cell.column.id] = cell
   }
   return result
 }
 
 /**
- * Returns row id for the table.
+ * Resolves the stable id for a row.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * `options.getRowId` wins when provided. Otherwise root rows use their index
+ * and child rows append their index to the parent id, such as `0.2`.
  *
  * @example
  * ```ts
- * const value = table_getRowId(table)
+ * const id = table_getRowId(originalRow, table, index, parentRow)
  * ```
  */
 export function table_getRowId<
@@ -216,13 +228,14 @@ export function table_getRowId<
 }
 
 /**
- * Returns row for the table.
+ * Looks up a row by id from the current or full row model.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * By default this searches `table.getRowModel()`. Passing `searchAll` searches
+ * the pre-pagination model first, then falls back to the core model.
  *
  * @example
  * ```ts
- * const value = table_getRow(table)
+ * const row = table_getRow(table, rowId, true)
  * ```
  */
 export function table_getRow<

package/src/core/table/constructTable.ts

@@ -79,7 +79,8 @@ export function constructTable<
     string & keyof TableState<TFeatures>
   >
 
-  for (const key of stateKeys) {
+  for (let i = 0; i < stateKeys.length; i++) {
+    const key = stateKeys[i]!
     // create writable base atom
     table.baseAtoms[key] = _reactivity.createWritableAtom(
       table.initialState[key],
@@ -107,7 +108,8 @@ export function constructTable<
     _reactivity.createReadonlyAtom(
       () => {
         const snapshot = {} as TableState<TFeatures>
-        for (const key of stateKeys) {
+        for (let i = 0; i < stateKeys.length; i++) {
+          const key = stateKeys[i]!
           snapshot[key] = table.atoms[key].get()
         }
         return snapshot
@@ -136,8 +138,8 @@ export function constructTable<
     )
   }
 
-  for (const feature of featuresList) {
-    feature.constructTableAPIs?.(table)
+  for (let i = 0; i < featuresList.length; i++) {
+    featuresList[i]!.constructTableAPIs?.(table)
   }
 
   return table

package/src/core/table/coreTablesFeature.types.ts

@@ -66,11 +66,15 @@ export interface TableOptions_Table<
   TData extends RowData,
 > {
   /**
-   * The features that you want to enable for the table.
+   * The feature modules registered on this table instance.
+   *
+   * Feature registration controls which state slices, options, and prototype
+   * APIs are available.
    */
   readonly _features: TFeatures
   /**
-   * The row model options that you want to enable for the table.
+   * Row model factories used by features such as filtering, grouping, sorting,
+   * expansion, and pagination.
    */
   readonly _rowModels?: CreateRowModels_All<TFeatures, TData>
   /**

package/src/core/table/coreTablesFeature.utils.ts

@@ -12,7 +12,7 @@ import type { TableOptions } from '../../types/TableOptions'
  *
  * @example
  * ```ts
- * const value = table_syncExternalStateToBaseAtoms(table)
+ * table_syncExternalStateToBaseAtoms(table)
  * ```
  */
 export function table_syncExternalStateToBaseAtoms<
@@ -56,7 +56,9 @@ export function table_reset<
 >(table: Table_Internal<TFeatures, TData>): void {
   const snap = cloneState(table.initialState)
   table._reactivity.batch(() => {
-    for (const key of Object.keys(snap) as Array<keyof typeof snap>) {
+    const keys = Object.keys(snap) as Array<keyof typeof snap>
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i]!
       ;(table.baseAtoms as any)[key].set(snap[key] as any)
     }
   })
@@ -70,7 +72,7 @@ export function table_reset<
  *
  * @example
  * ```ts
- * const value = table_mergeOptions(table)
+ * const options = table_mergeOptions(table, nextOptions)
  * ```
  */
 export function table_mergeOptions<

package/src/features/column-faceting/columnFacetingFeature.types.ts

@@ -8,15 +8,18 @@ export interface Column_ColumnFaceting<
   TData extends RowData,
 > {
   /**
-   * A function that **computes and returns** a min/max tuple derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
+   * Computes min/max numeric facet values for this column.
    */
   getFacetedMinMaxValues: () => undefined | [number, number]
   /**
-   * A function that **computes and returns** a row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts.
+   * Computes the row model used to derive this column's facet values.
+   *
+   * Other column filters are applied, while this column's own filter is
+   * excluded.
    */
   getFacetedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns a `Map` of unique values and their occurrences derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
+   * Computes unique facet values and occurrence counts for this column.
    */
   getFacetedUniqueValues: () => Map<any, number>
 }
@@ -26,18 +29,21 @@ export interface Table_RowModels_Faceted<
   TData extends RowData,
 > {
   /**
-   * A function that **computes and returns** a min/max tuple derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
-   * > Requires that you pass a valid `facetedMinMaxValues` row model factory in `_rowModels`. A default implementation is provided via the exported `createFacetedMinMaxValues` function.
+   * Computes min/max numeric facet values for the active faceting context.
+   *
+   * Requires a `facetedMinMaxValues` row-model factory in `_rowModels`.
    */
   getFacetedMinMaxValues: () => undefined | [number, number]
   /**
-   * Returns the row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts.
-   * > Requires that you pass a valid `facetedRowModel` row model factory in `_rowModels`. A default implementation is provided via the exported `createFacetedRowModel` function.
+   * Computes the row model used to derive facet values.
+   *
+   * Requires a `facetedRowModel` row-model factory in `_rowModels`.
    */
   getFacetedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * A function that **computes and returns** a `Map` of unique values and their occurrences derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
-   * > Requires that you pass a valid `facetedUniqueValues` row model factory in `_rowModels`. A default implementation is provided via the exported `createFacetedUniqueValues` function.
+   * Computes unique facet values and occurrence counts.
+   *
+   * Requires a `facetedUniqueValues` row-model factory in `_rowModels`.
    */
   getFacetedUniqueValues: () => Map<any, number>
 }
@@ -93,7 +99,7 @@ export interface Table_ColumnFaceting<
    */
   getGlobalFacetedMinMaxValues: () => undefined | [number, number]
   /**
-   * Returns the row model for the table after **global** filtering has been applied.
+   * Computes the row model used to derive global facet values.
    */
   getGlobalFacetedRowModel: () => RowModel<TFeatures, TData>
   /**