@tanstack/table-core 9.0.0-beta.5 → 9.0.0-beta.51

package/src/features/row-sorting/sortFns.ts

@@ -0,0 +1,366 @@
+import type { CreatedSortFn, SortFnDef } from './rowSortingFeature.types'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+
+/**
+ * Regular expression used to split mixed text and numeric chunks.
+ *
+ * The alphanumeric sort functions use these chunks for natural sorting of
+ * strings like `item2` before `item10`.
+ */
+export const reSplitAlphaNumeric = /([0-9]+)/gm
+
+/**
+ * Builds a `SortFn` from a value-level comparator plus an optional
+ * `resolveDataValue` normalizer.
+ *
+ * The `sort` comparator receives both rows' data values, each already passed
+ * through `resolveDataValue` when one is defined. Keeping normalization in the
+ * resolver means a variant of an existing sorting function only has to swap
+ * the resolver, not re-implement the comparison.
+ *
+ * The definition is attached to the returned function, so a variant can be
+ * created by spreading a built-in sorting function and overriding what
+ * differs:
+ *
+ * ```ts
+ * const stripDiacritics = (value: string) =>
+ *   value.normalize('NFD').replace(/\p{Diacritic}/gu, '')
+ *
+ * const alphanumericIgnoreDiacritics = constructSortFn({
+ *   ...sortFn_alphanumeric,
+ *   resolveDataValue: (value) =>
+ *     stripDiacritics(sortFn_alphanumeric.resolveDataValue!(value)),
+ * })
+ * ```
+ */
+export function constructSortFn<
+  TFeatures extends TableFeatures = any,
+  TData extends RowData = any,
+>(def: SortFnDef<TFeatures, TData>): CreatedSortFn<TFeatures, TData> {
+  const sortFn: CreatedSortFn<TFeatures, TData> = Object.assign(
+    <TRowFeatures extends TableFeatures, TRowData extends RowData>(
+      rowA: Row<TRowFeatures, TRowData>,
+      rowB: Row<TRowFeatures, TRowData>,
+      columnId: string,
+    ): number => {
+      let dataValueA = rowA.getValue(columnId)
+      let dataValueB = rowB.getValue(columnId)
+      const resolveDataValue = sortFn.resolveDataValue
+      if (resolveDataValue) {
+        dataValueA = resolveDataValue(dataValueA)
+        dataValueB = resolveDataValue(dataValueB)
+      }
+      // The def's comparator is typed against the factory's TFeatures/TData;
+      // the caller's row generics are erased at this boundary.
+      return sortFn.sort(
+        dataValueA,
+        dataValueB,
+        rowA as any,
+        rowB as any,
+        columnId,
+      )
+    },
+    def,
+  )
+  return sortFn
+}
+
+/**
+ * Sorts rows with the built-in alphanumeric strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_alphanumeric = constructSortFn({
+  resolveDataValue: (dataValue) => toString(dataValue).toLowerCase(),
+  sort: (dataValueA, dataValueB) => compareAlphanumeric(dataValueA, dataValueB),
+})
+
+/**
+ * Sorts rows with the built-in alphanumeric case sensitive strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_alphanumericCaseSensitive = constructSortFn({
+  resolveDataValue: (dataValue) => toString(dataValue),
+  sort: (dataValueA, dataValueB) => compareAlphanumeric(dataValueA, dataValueB),
+})
+
+// The text sort is more basic (less numeric support)
+// but is much faster
+/**
+ * Sorts rows with the built-in text strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_text = constructSortFn({
+  resolveDataValue: (dataValue) => toString(dataValue).toLowerCase(),
+  sort: (dataValueA, dataValueB) => compareBasic(dataValueA, dataValueB),
+})
+
+// The text sort is more basic (less numeric support)
+// but is much faster
+/**
+ * Sorts rows with the built-in text case sensitive strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_textCaseSensitive = constructSortFn({
+  resolveDataValue: (dataValue) => toString(dataValue),
+  sort: (dataValueA, dataValueB) => compareBasic(dataValueA, dataValueB),
+})
+
+/**
+ * Sorts rows with the built-in datetime strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_datetime = constructSortFn({
+  resolveDataValue: (dataValue) => toDateSortValue(dataValue),
+  // Can handle nullish values
+  // Use > and < because == (and ===) doesn't work with
+  // Date objects (would require calling getTime()).
+  sort: (dataValueA, dataValueB) =>
+    dataValueA > dataValueB ? 1 : dataValueA < dataValueB ? -1 : 0,
+})
+
+/**
+ * Sorts rows with the built-in basic strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_basic = constructSortFn({
+  sort: (dataValueA, dataValueB) => compareBasic(dataValueA, dataValueB),
+})
+
+// Utils
+
+function compareBasic(a: any, b: any) {
+  return a === b ? 0 : a > b ? 1 : -1
+}
+
+function toDateSortValue(value: any) {
+  return value instanceof Date ? value.getTime() : value
+}
+
+function toString(a: any) {
+  if (typeof a === 'number') {
+    if (isNaN(a) || a === Infinity || a === -Infinity) {
+      return ''
+    }
+    return String(a)
+  }
+  if (typeof a === 'string') {
+    return a
+  }
+  return ''
+}
+
+// Mixed sorting is slow, but very inclusive of many edge cases.
+// It handles numbers, mixed alphanumeric combinations, and even
+// null, undefined, and Infinity
+function compareAlphanumeric(aStr: string, bStr: string) {
+  let ai = 0
+  let bi = 0
+  const aLen = aStr.length
+  const bLen = bStr.length
+
+  while (ai < aLen && bi < bLen) {
+    const aIsNumeric = isDigit(aStr.charCodeAt(ai))
+    const bIsNumeric = isDigit(bStr.charCodeAt(bi))
+
+    const aEnd = findChunkEnd(aStr, ai, aIsNumeric)
+    const bEnd = findChunkEnd(bStr, bi, bIsNumeric)
+
+    // Both are string chunks
+    if (!aIsNumeric && !bIsNumeric) {
+      const stringComparison = compareStringChunks(
+        aStr,
+        ai,
+        aEnd,
+        bStr,
+        bi,
+        bEnd,
+      )
+      if (stringComparison) {
+        return stringComparison
+      }
+      ai = aEnd
+      bi = bEnd
+      continue
+    }
+
+    // One is a string chunk, one is a number chunk — the string sorts first
+    if (aIsNumeric !== bIsNumeric) {
+      return aIsNumeric ? 1 : -1
+    }
+
+    // Both are numeric chunks
+    const numericComparison = compareNumericChunks(
+      aStr,
+      ai,
+      aEnd,
+      bStr,
+      bi,
+      bEnd,
+    )
+    if (numericComparison) {
+      return numericComparison
+    }
+
+    ai = aEnd
+    bi = bEnd
+  }
+
+  // One side is exhausted — compare the counts of remaining non-empty chunks
+  return countRemainingChunks(aStr, ai) - countRemainingChunks(bStr, bi)
+}
+
+function isDigit(charCode: number) {
+  return charCode >= 48 && charCode <= 57
+}
+
+function findChunkEnd(str: string, start: number, isNumeric: boolean) {
+  let end = start + 1
+  while (end < str.length && isDigit(str.charCodeAt(end)) === isNumeric) {
+    end++
+  }
+  return end
+}
+
+function compareStringChunks(
+  aStr: string,
+  aStart: number,
+  aEnd: number,
+  bStr: string,
+  bStart: number,
+  bEnd: number,
+) {
+  const aLength = aEnd - aStart
+  const bLength = bEnd - bStart
+  const minLength = aLength < bLength ? aLength : bLength
+
+  for (let i = 0; i < minLength; i++) {
+    const aCode = aStr.charCodeAt(aStart + i)
+    const bCode = bStr.charCodeAt(bStart + i)
+
+    if (aCode > bCode) {
+      return 1
+    }
+    if (bCode > aCode) {
+      return -1
+    }
+  }
+
+  if (aLength > bLength) {
+    return 1
+  }
+  if (bLength > aLength) {
+    return -1
+  }
+  return 0
+}
+
+function compareNumericChunks(
+  aStr: string,
+  aStart: number,
+  aEnd: number,
+  bStr: string,
+  bStart: number,
+  bEnd: number,
+) {
+  let aSignificantStart = aStart
+  while (
+    aSignificantStart < aEnd &&
+    aStr.charCodeAt(aSignificantStart) === 48
+  ) {
+    aSignificantStart++
+  }
+
+  let bSignificantStart = bStart
+  while (
+    bSignificantStart < bEnd &&
+    bStr.charCodeAt(bSignificantStart) === 48
+  ) {
+    bSignificantStart++
+  }
+
+  const aSignificantLength = aEnd - aSignificantStart
+  const bSignificantLength = bEnd - bSignificantStart
+
+  if (aSignificantLength === 0 && bSignificantLength === 0) {
+    return 0
+  }
+
+  if (aSignificantLength <= 15 && bSignificantLength <= 15) {
+    const an = parseSmallInt(aStr, aSignificantStart, aEnd)
+    const bn = parseSmallInt(bStr, bSignificantStart, bEnd)
+
+    if (an > bn) {
+      return 1
+    }
+    if (bn > an) {
+      return -1
+    }
+    return 0
+  }
+
+  // Preserve parseInt precision-collapse behavior for unusually large chunks.
+  const an = parseInt(aStr.slice(aStart, aEnd), 10)
+  const bn = parseInt(bStr.slice(bStart, bEnd), 10)
+
+  if (an > bn) {
+    return 1
+  }
+  if (bn > an) {
+    return -1
+  }
+  return 0
+}
+
+function parseSmallInt(str: string, start: number, end: number) {
+  let result = 0
+  for (let i = start; i < end; i++) {
+    result = result * 10 + str.charCodeAt(i) - 48
+  }
+  return result
+}
+
+function countRemainingChunks(str: string, start: number) {
+  let count = 0
+  let index = start
+
+  while (index < str.length) {
+    count++
+    index = findChunkEnd(str, index, isDigit(str.charCodeAt(index)))
+  }
+
+  return count
+}
+
+// Exports
+
+/**
+ * The built-in sorting function registry.
+ *
+ * Registering this full object opts out of tree-shaking: every built-in
+ * sorting function ends up in your bundle. Prefer importing the `sortFn_*`
+ * functions you actually use and registering just those in the `sortFns`
+ * slot, or passing them directly to the `sortFn` column option.
+ *
+ * @deprecated Import individual `sortFn_*` functions instead for a smaller
+ * bundle. This export still works and is not going away in v9, but built-in
+ * name resolution (including `sortFn: 'auto'`) only finds functions you
+ * register yourself.
+ */
+export const sortFns = {
+  alphanumeric: sortFn_alphanumeric,
+  alphanumericCaseSensitive: sortFn_alphanumericCaseSensitive,
+  basic: sortFn_basic,
+  datetime: sortFn_datetime,
+  text: sortFn_text,
+  textCaseSensitive: sortFn_textCaseSensitive,
+}
+
+export type BuiltInSortFn = keyof typeof sortFns

package/src/features/stockFeatures.ts

@@ -1,4 +1,5 @@
 import { columnFacetingFeature } from './column-faceting/columnFacetingFeature'
+import { rowAggregationFeature } from './row-aggregation/rowAggregationFeature'
 import { columnFilteringFeature } from './column-filtering/columnFilteringFeature'
 import { columnGroupingFeature } from './column-grouping/columnGroupingFeature'
 import { columnOrderingFeature } from './column-ordering/columnOrderingFeature'
@@ -14,6 +15,7 @@ import { rowSelectionFeature } from './row-selection/rowSelectionFeature'
 import { rowSortingFeature } from './row-sorting/rowSortingFeature'
 
 export interface StockFeatures {
+  rowAggregationFeature: typeof rowAggregationFeature
   columnFacetingFeature: typeof columnFacetingFeature
   columnFilteringFeature: typeof columnFilteringFeature
   columnGroupingFeature: typeof columnGroupingFeature
@@ -36,6 +38,7 @@ export interface StockFeatures {
  * Use individual feature exports for tree-shaking, or this aggregate when a table should include every built-in feature.
  */
 export const stockFeatures: StockFeatures = {
+  rowAggregationFeature,
   columnFacetingFeature,
   columnFilteringFeature,
   columnGroupingFeature,

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,50 @@
-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,
+ *   filterFn_includesString,
+ *   rowSortingFeature,
+ *   sortFn_alphanumeric,
+ *   sortFn_text,
+ *   tableFeatures,
+ * } from '@tanstack/react-table'
+ * const features = tableFeatures({
+ *   columnFilteringFeature,
+ *   rowSortingFeature,
+ *   filteredRowModel: createFilteredRowModel(),
+ *   sortedRowModel: createSortedRowModel(),
+ *   filterFns: { includesString: filterFn_includesString, myCustomFilterFn },
+ *   sortFns: { alphanumeric: sortFn_alphanumeric, text: sortFn_text },
+ *   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'
@@ -57,20 +58,17 @@ export * from './core/table/constructTable'
 export * from './core/table/coreTablesFeature'
 export * from './core/table/coreTablesFeature.types'
 
-/**
- * RowModelFns
- */
-
-export * from './fns/aggregationFns'
-export * from './fns/filterFns'
-export * from './fns/sortFns'
-
 /**
  * Features
  */
 
 export * from './features/stockFeatures'
 
+// rowAggregationFeature
+export * from './features/row-aggregation/rowAggregationFeature'
+export * from './features/row-aggregation/rowAggregationFeature.types'
+export * from './features/row-aggregation/aggregationFns'
+
 // columnFacetingFeature
 export * from './features/column-faceting/columnFacetingFeature'
 export * from './features/column-faceting/columnFacetingFeature.types'
@@ -82,6 +80,7 @@ export * from './features/column-faceting/createFacetedUniqueValues'
 export * from './features/column-filtering/columnFilteringFeature'
 export * from './features/column-filtering/columnFilteringFeature.types'
 export * from './features/column-filtering/createFilteredRowModel'
+export * from './features/column-filtering/filterFns'
 
 // columnGroupingFeature
 export * from './features/column-grouping/columnGroupingFeature'
@@ -134,5 +133,6 @@ export * from './features/row-selection/rowSelectionFeature.types'
 export * from './features/row-sorting/rowSortingFeature'
 export * from './features/row-sorting/rowSortingFeature.types'
 export * from './features/row-sorting/createSortedRowModel'
+export * from './features/row-sorting/sortFns'
 
 // force

package/src/static-functions.ts

@@ -15,6 +15,7 @@ export * from './core/row-models/coreRowModelsFeature.utils'
 export * from './core/table/coreTablesFeature.utils'
 
 // Features
+export * from './features/row-aggregation/rowAggregationFeature.utils'
 export * from './features/column-faceting/columnFacetingFeature.utils'
 export * from './features/column-filtering/columnFilteringFeature.utils'
 export * from './features/column-grouping/columnGroupingFeature.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,15 +1,17 @@
 import type { Cell_ColumnGrouping } from '../features/column-grouping/columnGroupingFeature.types'
+import type { Cell_Aggregation } from '../features/row-aggregation/rowAggregationFeature.types'
 import type { CellData, RowData } from './type-utils'
 import type { ExtractFeatureMapTypes, TableFeatures } from './TableFeatures'
 import type { Cell_Cell } from '../core/cells/coreCellsFeature.types'
 
 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> {}
 
 export interface Cell_FeatureMap {
+  rowAggregationFeature: Cell_Aggregation
   columnGroupingFeature: Cell_ColumnGrouping
 }
 

package/src/types/Column.ts

@@ -1,4 +1,6 @@
+import type { Table_Internal } from './Table'
 import type { Column_RowSorting } from '../features/row-sorting/rowSortingFeature.types'
+import type { Column_Aggregation } from '../features/row-aggregation/rowAggregationFeature.types'
 import type { Column_ColumnFaceting } from '../features/column-faceting/columnFacetingFeature.types'
 import type { Column_ColumnFiltering } from '../features/column-filtering/columnFilteringFeature.types'
 import type { Column_ColumnGrouping } from '../features/column-grouping/columnGroupingFeature.types'
@@ -14,18 +16,19 @@ import type { ExtractFeatureMapTypes, TableFeatures } from './TableFeatures'
 import type { Column_Column } from '../core/columns/coreColumnsFeature.types'
 
 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,
 > {
+  rowAggregationFeature: Column_Aggregation<TFeatures, TData>
   columnFacetingFeature: Column_ColumnFaceting<TFeatures, TData>
   columnFilteringFeature: Column_ColumnFiltering<TFeatures, TData>
-  columnGroupingFeature: Column_ColumnGrouping<TFeatures, TData>
+  columnGroupingFeature: Column_ColumnGrouping
   columnOrderingFeature: Column_ColumnOrdering
   columnPinningFeature: Column_ColumnPinning
   columnResizingFeature: Column_ColumnResizing
@@ -42,10 +45,11 @@ export type Column<
 > = Column_Core<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>
 }