@tanstack/table-core 9.0.0-beta.2 → 9.0.0-beta.20

package/src/fns/sortFns.ts

@@ -1,7 +1,6 @@
 import type { RowData } from '../types/type-utils'
 import type { TableFeatures } from '../types/TableFeatures'
 import type { Row } from '../types/Row'
-import type { SortFn } from '../features/row-sorting/rowSortingFeature.types'
 
 /**
  * Regular expression used to split mixed text and numeric chunks.
@@ -16,12 +15,12 @@ export const reSplitAlphaNumeric = /([0-9]+)/gm
  *
  * This comparator returns ascending-order results; descending order is applied by the sorting row model.
  */
-export const sortFn_alphanumeric: SortFn<any, any> = <
+export const sortFn_alphanumeric = <
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(
-  rowA: Row<any, any>,
-  rowB: Row<any, any>,
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
   columnId: string,
 ) => {
   return compareAlphanumeric(
@@ -35,12 +34,12 @@ export const sortFn_alphanumeric: SortFn<any, any> = <
  *
  * This comparator returns ascending-order results; descending order is applied by the sorting row model.
  */
-export const sortFn_alphanumericCaseSensitive: SortFn<any, any> = <
+export const sortFn_alphanumericCaseSensitive = <
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(
-  rowA: Row<any, any>,
-  rowB: Row<any, any>,
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
   columnId: string,
 ) => {
   return compareAlphanumeric(
@@ -56,12 +55,12 @@ export const sortFn_alphanumericCaseSensitive: SortFn<any, any> = <
  *
  * This comparator returns ascending-order results; descending order is applied by the sorting row model.
  */
-export const sortFn_text: SortFn<any, any> = <
+export const sortFn_text = <
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(
-  rowA: Row<any, any>,
-  rowB: Row<any, any>,
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
   columnId: string,
 ) => {
   return compareBasic(
@@ -77,12 +76,12 @@ export const sortFn_text: SortFn<any, any> = <
  *
  * This comparator returns ascending-order results; descending order is applied by the sorting row model.
  */
-export const sortFn_textCaseSensitive: SortFn<any, any> = <
+export const sortFn_textCaseSensitive = <
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(
-  rowA: Row<any, any>,
-  rowB: Row<any, any>,
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
   columnId: string,
 ) => {
   return compareBasic(
@@ -96,12 +95,12 @@ export const sortFn_textCaseSensitive: SortFn<any, any> = <
  *
  * This comparator returns ascending-order results; descending order is applied by the sorting row model.
  */
-export const sortFn_datetime: SortFn<any, any> = <
+export const sortFn_datetime = <
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(
-  rowA: Row<any, any>,
-  rowB: Row<any, any>,
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
   columnId: string,
 ) => {
   const a: number | string = rowA.getValue(columnId)
@@ -118,12 +117,12 @@ export const sortFn_datetime: SortFn<any, any> = <
  *
  * This comparator returns ascending-order results; descending order is applied by the sorting row model.
  */
-export const sortFn_basic: SortFn<any, any> = <
+export const sortFn_basic = <
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(
-  rowA: Row<any, any>,
-  rowB: Row<any, any>,
+  rowA: Row<TFeatures, TData>,
+  rowB: Row<TFeatures, TData>,
   columnId: string,
 ) => {
   return compareBasic(rowA.getValue(columnId), rowB.getValue(columnId))
@@ -152,10 +151,8 @@ function toString(a: any) {
 // It handles numbers, mixed alphanumeric combinations, and even
 // null, undefined, and Infinity
 function compareAlphanumeric(aStr: string, bStr: string) {
-  // Split on number groups, but keep the delimiter
-  // Then remove falsey split values
-  const a = aStr.split(reSplitAlphaNumeric).filter(Boolean)
-  const b = bStr.split(reSplitAlphaNumeric).filter(Boolean)
+  const a = aStr.split(reSplitAlphaNumeric)
+  const b = bStr.split(reSplitAlphaNumeric)
 
   let ai = 0
   let bi = 0
@@ -163,16 +160,29 @@ function compareAlphanumeric(aStr: string, bStr: string) {
   const bLen = b.length
 
   while (ai < aLen && bi < bLen) {
+    // Skip the empty boundary chunks that .filter(Boolean) used to remove
+    if (!a[ai]) {
+      ai++
+      continue
+    }
+    if (!b[bi]) {
+      bi++
+      continue
+    }
+
     const aa = a[ai++]!
     const bb = b[bi++]!
 
+    // Chunks are either all-digit (parseInt always succeeds) or digit-free
+    // (parseInt is always NaN), so NaN-ness fully classifies each chunk
     const an = parseInt(aa, 10)
     const bn = parseInt(bb, 10)
 
-    const combo = [an, bn].sort()
+    const aIsNaN = isNaN(an)
+    const bIsNaN = isNaN(bn)
 
     // Both are string
-    if (isNaN(combo[0]!)) {
+    if (aIsNaN && bIsNaN) {
       if (aa > bb) {
         return 1
       }
@@ -182,9 +192,9 @@ function compareAlphanumeric(aStr: string, bStr: string) {
       continue
     }
 
-    // One is a string, one is a number
-    if (isNaN(combo[1]!)) {
-      return isNaN(an) ? -1 : 1
+    // One is a string, one is a number — the string chunk sorts first
+    if (aIsNaN || bIsNaN) {
+      return aIsNaN ? -1 : 1
     }
 
     // Both are numbers
@@ -196,7 +206,19 @@ function compareAlphanumeric(aStr: string, bStr: string) {
     }
   }
 
-  return aLen - ai - (bLen - bi)
+  // One side is exhausted — compare the counts of remaining non-empty chunks
+  let remaining = 0
+  for (; ai < aLen; ai++) {
+    if (a[ai]) {
+      remaining++
+    }
+  }
+  for (; bi < bLen; bi++) {
+    if (b[bi]) {
+      remaining--
+    }
+  }
+  return remaining
 }
 
 // Exports

package/src/helpers/columnHelper.ts

@@ -10,10 +10,10 @@ import type {
   IdentifiedColumnDef,
 } from '../types/ColumnDef'
 
-export type ColumnHelper<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> = {
+export interface ColumnHelper<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> {
   /**
    * Creates a data column definition with an accessor key or function to extract the cell value.
    * @example

package/src/helpers/metaHelper.ts

@@ -0,0 +1,24 @@
+/**
+ * A helper for declaring the `tableMeta`/`columnMeta` type-only slots in the
+ * `features` option without a type assertion.
+ *
+ * Equivalent to `{} as TMeta`, but reads as type-only at the call site and
+ * avoids `@typescript-eslint/no-unnecessary-type-assertion` false positives
+ * when the meta type has only optional properties (where an auto-fix removing
+ * the assertion would silently degrade the inferred meta type to `{}`).
+ *
+ * The returned value is a phantom — it is ignored and stripped from the
+ * table's registered features at runtime; only its type is used.
+ * @example
+ * ```
+ * import { metaHelper, tableFeatures, rowSortingFeature } from '@tanstack/react-table'
+ * const features = tableFeatures({
+ *   rowSortingFeature,
+ *   tableMeta: metaHelper<MyTableMeta>(),
+ *   columnMeta: metaHelper<MyColumnMeta>(),
+ * });
+ * ```
+ */
+export function metaHelper<TMeta extends object>(): TMeta {
+  return {} as TMeta
+}

package/src/helpers/tableFeatures.ts

@@ -1,18 +1,49 @@
-import type { TableFeatures } from '../types/TableFeatures'
+import type {
+  TableFeatures,
+  ValidateFeatureSlots,
+} from '../types/TableFeatures'
 
 /**
  * A helper function to help define the features that are to be imported and applied to a table instance.
  * Use this utility to make it easier to have the correct type inference for the features that are being imported.
  * **Note:** It is recommended to use this utility statically outside of a component.
+ *
+ * Alongside feature modules, this object carries everything else that is
+ * statically stitched into the table:
+ *
+ * - Row model factories (`sortedRowModel`, `filteredRowModel`, etc.)
+ * - Row model function registries (`sortFns`, `filterFns`, `aggregationFns`),
+ *   whose keys become the valid string values for `sortFn`, `filterFn`,
+ *   `globalFilterFn`, and `aggregationFn` with full inference
+ * - Type-only `tableMeta`/`columnMeta` slots for declaring per-table meta types
+ *   instead of using global declaration merging. The values are phantom
+ *   (ignored and stripped at runtime); only their types are used.
  * @example
  * ```
- * import { tableFeatures, columnVisibilityFeature, rowPinningFeature } from '@tanstack/react-table'
- * const features = tableFeatures({ columnVisibilityFeature, rowPinningFeature });
- * const table = useTable({ features, rowModels: {}, columns, data });
+ * import {
+ *   columnFilteringFeature,
+ *   createFilteredRowModel,
+ *   createSortedRowModel,
+ *   filterFns,
+ *   rowSortingFeature,
+ *   sortFns,
+ *   tableFeatures,
+ * } from '@tanstack/react-table'
+ * const features = tableFeatures({
+ *   columnFilteringFeature,
+ *   rowSortingFeature,
+ *   filteredRowModel: createFilteredRowModel(),
+ *   sortedRowModel: createSortedRowModel(),
+ *   filterFns: { ...filterFns, myCustomFilterFn },
+ *   sortFns,
+ *   tableMeta: {} as { updateData: (rowIndex: number, columnId: string, value: unknown) => void },
+ *   columnMeta: {} as { align?: 'left' | 'right' },
+ * });
+ * const table = useTable({ features, columns, data });
  * ```
  */
 export function tableFeatures<TFeatures extends TableFeatures>(
-  features: TFeatures,
+  features: TFeatures & ValidateFeatureSlots<TFeatures>,
 ): TFeatures {
   return features
 }

package/src/index.ts

@@ -22,6 +22,7 @@ export * from './types/type-utils'
 
 export * from './core/coreFeatures'
 export * from './helpers/columnHelper'
+export * from './helpers/metaHelper'
 export * from './helpers/tableFeatures'
 export * from './helpers/tableOptions'
 export * from './utils'

package/src/store-reactivity-bindings.ts

@@ -11,7 +11,7 @@ import type { TableReactivityBindings } from './core/reactivity/coreReactivityFe
  * import { storeReactivityBindings } from '@tanstack/table-core/store-reactivity-bindings'
  *
  * const table = constructTable({
- *   features: tableFeatures({ coreReativityFeature: storeReactivityBindings() }),
+ *   features: tableFeatures({ coreReactivityFeature: storeReactivityBindings() }),
  *   // ...
  * })
  * ```

package/src/types/Cell.ts

@@ -1,25 +1,11 @@
 import type { Cell_ColumnGrouping } from '../features/column-grouping/columnGroupingFeature.types'
 import type { CellData, RowData } from './type-utils'
-import type {
-  ExtractFeatureMapTypes,
-  ExtractFeatureTypes,
-  TableFeatures,
-} from './TableFeatures'
+import type { ExtractFeatureMapTypes, TableFeatures } from './TableFeatures'
 import type { Cell_Cell } from '../core/cells/coreCellsFeature.types'
 
-/**
- * Use this interface as a target for declaration merging to add your own plugin properties.
- * Note: This will affect the types of all tables in your project.
- */
-export interface Cell_Plugins<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue extends CellData = CellData,
-> {}
-
 export interface Cell_Core<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
   TValue extends CellData = CellData,
 > extends Cell_Cell<TFeatures, TData, TValue> {}
 
@@ -31,7 +17,5 @@ export type Cell<
   TFeatures extends TableFeatures,
   TData extends RowData,
   TValue extends CellData = CellData,
-> = Cell_Cell<TFeatures, TData, TValue> &
-  ExtractFeatureMapTypes<TFeatures, Cell_FeatureMap> &
-  ExtractFeatureTypes<'Cell', TFeatures> &
-  Cell_Plugins<TFeatures, TData, TValue>
+> = Cell_Core<TFeatures, TData, TValue> &
+  ExtractFeatureMapTypes<TFeatures, Cell_FeatureMap>

package/src/types/Column.ts

@@ -1,3 +1,4 @@
+import type { Table_Internal } from './Table'
 import type { Column_RowSorting } from '../features/row-sorting/rowSortingFeature.types'
 import type { Column_ColumnFaceting } from '../features/column-faceting/columnFacetingFeature.types'
 import type { Column_ColumnFiltering } from '../features/column-filtering/columnFilteringFeature.types'
@@ -10,32 +11,18 @@ import type { Column_ColumnSizing } from '../features/column-sizing/columnSizing
 import type { Column_ColumnVisibility } from '../features/column-visibility/columnVisibilityFeature.types'
 import type { ColumnDefBase_All } from './ColumnDef'
 import type { RowData } from './type-utils'
-import type {
-  ExtractFeatureMapTypes,
-  ExtractFeatureTypes,
-  TableFeatures,
-} from './TableFeatures'
+import type { ExtractFeatureMapTypes, TableFeatures } from './TableFeatures'
 import type { Column_Column } from '../core/columns/coreColumnsFeature.types'
 
-/**
- * Use this interface as a target for declaration merging to add your own plugin properties.
- * Note: This will affect the types of all tables in your project.
- */
-export interface Column_Plugins<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue = unknown,
-> {}
-
 export interface Column_Core<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
   TValue = unknown,
 > extends Column_Column<TFeatures, TData, TValue> {}
 
 export interface Column_FeatureMap<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   columnFacetingFeature: Column_ColumnFaceting<TFeatures, TData>
   columnFilteringFeature: Column_ColumnFiltering<TFeatures, TData>
@@ -54,14 +41,13 @@ export type Column<
   TData extends RowData,
   TValue = unknown,
 > = Column_Core<TFeatures, TData, TValue> &
-  ExtractFeatureMapTypes<TFeatures, Column_FeatureMap<TFeatures, TData>> &
-  ExtractFeatureTypes<'Column', TFeatures> &
-  Column_Plugins<TFeatures, TData, TValue>
+  ExtractFeatureMapTypes<TFeatures, Column_FeatureMap<TFeatures, TData>>
 
-export type Column_Internal<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+export interface Column_Internal<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
   TValue = unknown,
-> = Column<TFeatures, TData, TValue> & {
+> extends Omit<Column_Core<TFeatures, TData, TValue>, 'columnDef' | 'table'> {
   columnDef: ColumnDefBase_All<TFeatures, TData, TValue>
+  table: Table_Internal<TFeatures, TData>
 }

package/src/types/ColumnDef.ts

@@ -1,7 +1,7 @@
 import type { CellData, RowData, UnionToIntersection } from './type-utils'
 import type {
   ExtractFeatureMapTypes,
-  ExtractFeatureTypes,
+  IsAny,
   TableFeatures,
 } from './TableFeatures'
 import type { CellContext } from '../core/cells/coreCellsFeature.types'
@@ -15,21 +15,30 @@ import type { ColumnDef_ColumnVisibility } from '../features/column-visibility/c
 import type { ColumnDef_GlobalFiltering } from '../features/global-filtering/globalFilteringFeature.types'
 import type { ColumnDef_RowSorting } from '../features/row-sorting/rowSortingFeature.types'
 
-/**
- * Use this interface as a target for declaration merging to add your own plugin properties.
- * Note: This will affect the types of all tables in your project.
- */
-export interface ColumnDef_Plugins<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+export interface ColumnMeta<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
   TValue extends CellData = CellData,
 > {}
 
-export interface ColumnMeta<
+/**
+ * Resolves the type of `columnDef.meta` for a feature set.
+ *
+ * When the features object declares a `columnMeta` type-only slot
+ * (`tableFeatures({ ..., columnMeta: {} as MyColumnMeta })`), that type wins.
+ * Otherwise this falls back to the global declaration-merged `ColumnMeta`
+ * interface.
+ */
+export type ExtractColumnMeta<
   TFeatures extends TableFeatures,
   TData extends RowData,
   TValue extends CellData = CellData,
-> {}
+> =
+  IsAny<TFeatures> extends true
+    ? ColumnMeta<TFeatures, TData, TValue>
+    : TFeatures extends { columnMeta: infer TMeta extends object }
+      ? TMeta
+      : ColumnMeta<TFeatures, TData, TValue>
 
 /**
  * Reads a cell value from an original row object.
@@ -70,8 +79,8 @@ export interface StringHeaderIdentifier {
 }
 
 export interface IdIdentifier<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
   TValue extends CellData = CellData,
 > {
   /**
@@ -110,13 +119,16 @@ interface ColumnDefBase_Core<
   cell?: ColumnDefTemplate<CellContext<TFeatures, TData, TValue>>
   /**
    * User-defined metadata available on the resolved column definition.
+   *
+   * Declare its type per-table via the `columnMeta` type-only slot on the
+   * `features` option, or globally via declaration merging on `ColumnMeta`.
    */
-  meta?: ColumnMeta<TFeatures, TData, TValue>
+  meta?: ExtractColumnMeta<TFeatures, TData, TValue>
 }
 
 export interface ColumnDef_FeatureMap<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
   TValue extends CellData,
 > {
   columnVisibilityFeature: ColumnDef_ColumnVisibility
@@ -137,9 +149,7 @@ export type ColumnDefBase<
   ExtractFeatureMapTypes<
     TFeatures,
     ColumnDef_FeatureMap<TFeatures, TData, TValue>
-  > &
-  ExtractFeatureTypes<'ColumnDef', TFeatures> &
-  ColumnDef_Plugins<TFeatures, TData, TValue>
+  >
 
 export type ColumnDefBase_All<
   TFeatures extends TableFeatures,

package/src/types/Header.ts

@@ -1,26 +1,12 @@
 import type { Header_ColumnSizing } from '../features/column-sizing/columnSizingFeature.types'
 import type { CellData, RowData } from './type-utils'
-import type {
-  ExtractFeatureMapTypes,
-  ExtractFeatureTypes,
-  TableFeatures,
-} from './TableFeatures'
+import type { ExtractFeatureMapTypes, TableFeatures } from './TableFeatures'
 import type { Header_Header } from '../core/headers/coreHeadersFeature.types'
 import type { Header_ColumnResizing } from '../features/column-resizing/columnResizingFeature.types'
 
-/**
- * Use this interface as a target for declaration merging to add your own plugin properties.
- * Note: This will affect the types of all tables in your project.
- */
-export interface Header_Plugins<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue extends CellData = CellData,
-> {}
-
 export interface Header_Core<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
   TValue extends CellData = CellData,
 > extends Header_Header<TFeatures, TData, TValue> {}
 
@@ -34,6 +20,4 @@ export type Header<
   TData extends RowData,
   TValue extends CellData = CellData,
 > = Header_Core<TFeatures, TData, TValue> &
-  ExtractFeatureMapTypes<TFeatures, Header_FeatureMap> &
-  ExtractFeatureTypes<'Header', TFeatures> &
-  Header_Plugins<TFeatures, TData, TValue>
+  ExtractFeatureMapTypes<TFeatures, Header_FeatureMap>

package/src/types/HeaderGroup.ts

@@ -1,24 +1,13 @@
 import type { HeaderGroup_Header } from '../core/headers/coreHeadersFeature.types'
-import type { ExtractFeatureTypes, TableFeatures } from './TableFeatures'
+import type { TableFeatures } from './TableFeatures'
 import type { RowData } from './type-utils'
 
-/**
- * Use this interface as a target for declaration merging to add your own plugin properties.
- * Note: This will affect the types of all tables in your project.
- */
-export interface HeaderGroup_Plugins<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> {}
-
 export interface HeaderGroup_Core<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > extends HeaderGroup_Header<TFeatures, TData> {}
 
-export type HeaderGroup<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> = HeaderGroup_Core<TFeatures, TData> &
-  ExtractFeatureTypes<'HeaderGroup', TFeatures> &
-  HeaderGroup_Plugins<TFeatures, TData>
+export interface HeaderGroup<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> extends HeaderGroup_Core<TFeatures, TData> {}

package/src/types/Row.ts

@@ -6,30 +6,17 @@ import type { RowData } from './type-utils'
 import type { Row_RowExpanding } from '../features/row-expanding/rowExpandingFeature.types'
 import type { Row_RowPinning } from '../features/row-pinning/rowPinningFeature.types'
 import type { Row_RowSelection } from '../features/row-selection/rowSelectionFeature.types'
-import type {
-  ExtractFeatureMapTypes,
-  ExtractFeatureTypes,
-  TableFeatures,
-} from './TableFeatures'
+import type { ExtractFeatureMapTypes, TableFeatures } from './TableFeatures'
 import type { Row_Row } from '../core/rows/coreRowsFeature.types'
 
-/**
- * Use this interface as a target for declaration merging to add your own plugin properties.
- * Note: This will affect the types of all tables in your project.
- */
-export interface Row_Plugins<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> {}
-
 export interface Row_Core<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > extends Row_Row<TFeatures, TData> {}
 
 export interface Row_FeatureMap<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   columnFilteringFeature: Row_ColumnFiltering<TFeatures, TData>
   columnGroupingFeature: Row_ColumnGrouping
@@ -44,6 +31,4 @@ export type Row<
   TFeatures extends TableFeatures,
   TData extends RowData,
 > = Row_Core<TFeatures, TData> &
-  ExtractFeatureMapTypes<TFeatures, Row_FeatureMap<TFeatures, TData>> &
-  ExtractFeatureTypes<'Row', TFeatures> &
-  Row_Plugins<TFeatures, TData>
+  ExtractFeatureMapTypes<TFeatures, Row_FeatureMap<TFeatures, TData>>