@tanstack/table-core 9.0.0-beta.45 → 9.0.0-beta.47

package/src/fns/sortFns.ts

@@ -1,3 +1,7 @@
+import type {
+  CreatedSortFn,
+  SortFnDef,
+} from '../features/row-sorting/rowSortingFeature.types'
 import type { RowData } from '../types/type-utils'
 import type { TableFeatures } from '../types/TableFeatures'
 import type { Row } from '../types/Row'
@@ -11,122 +15,127 @@ import type { Row } from '../types/Row'
 export const reSplitAlphaNumeric = /([0-9]+)/gm
 
 /**
- * Sorts rows with the built-in alphanumeric strategy.
+ * Builds a `SortFn` from a value-level comparator plus an optional
+ * `resolveDataValue` normalizer.
  *
- * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ * 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 const sortFn_alphanumeric = <
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  rowA: Row<TFeatures, TData>,
-  rowB: Row<TFeatures, TData>,
-  columnId: string,
-) => {
-  return compareAlphanumeric(
-    toString(rowA.getValue(columnId)).toLowerCase(),
-    toString(rowB.getValue(columnId)).toLowerCase(),
+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 = <
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  rowA: Row<TFeatures, TData>,
-  rowB: Row<TFeatures, TData>,
-  columnId: string,
-) => {
-  return compareAlphanumeric(
-    toString(rowA.getValue(columnId)),
-    toString(rowB.getValue(columnId)),
-  )
-}
+export const sortFn_alphanumericCaseSensitive = constructSortFn({
+  resolveDataValue: (dataValue) => toString(dataValue),
+  sort: (dataValueA, dataValueB) => compareAlphanumeric(dataValueA, dataValueB),
+})
 
-// The text filter is more basic (less numeric support)
+// 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 = <
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  rowA: Row<TFeatures, TData>,
-  rowB: Row<TFeatures, TData>,
-  columnId: string,
-) => {
-  return compareBasic(
-    toString(rowA.getValue(columnId)).toLowerCase(),
-    toString(rowB.getValue(columnId)).toLowerCase(),
-  )
-}
+export const sortFn_text = constructSortFn({
+  resolveDataValue: (dataValue) => toString(dataValue).toLowerCase(),
+  sort: (dataValueA, dataValueB) => compareBasic(dataValueA, dataValueB),
+})
 
-// The text filter is more basic (less numeric support)
+// 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 = <
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  rowA: Row<TFeatures, TData>,
-  rowB: Row<TFeatures, TData>,
-  columnId: string,
-) => {
-  return compareBasic(
-    toString(rowA.getValue(columnId)),
-    toString(rowB.getValue(columnId)),
-  )
-}
+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 = <
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  rowA: Row<TFeatures, TData>,
-  rowB: Row<TFeatures, TData>,
-  columnId: string,
-) => {
-  const a = toDateSortValue(rowA.getValue(columnId))
-  const b = toDateSortValue(rowB.getValue(columnId))
-
+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()).
-  return a > b ? 1 : a < b ? -1 : 0
-}
+  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 = <
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  rowA: Row<TFeatures, TData>,
-  rowB: Row<TFeatures, TData>,
-  columnId: string,
-) => {
-  return compareBasic(rowA.getValue(columnId), rowB.getValue(columnId))
-}
+export const sortFn_basic = constructSortFn({
+  sort: (dataValueA, dataValueB) => compareBasic(dataValueA, dataValueB),
+})
 
 // Utils
 
@@ -338,7 +347,15 @@ function countRemainingChunks(str: string, start: number) {
 /**
  * The built-in sorting function registry.
  *
- * Pass this object to sorted row model creation or extend it with custom sorting functions.
+ * 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,

package/src/helpers/tableFeatures.ts

@@ -24,9 +24,10 @@ import type {
  *   columnFilteringFeature,
  *   createFilteredRowModel,
  *   createSortedRowModel,
- *   filterFns,
+ *   filterFn_includesString,
  *   rowSortingFeature,
- *   sortFns,
+ *   sortFn_alphanumeric,
+ *   sortFn_text,
  *   tableFeatures,
  * } from '@tanstack/react-table'
  * const features = tableFeatures({
@@ -34,8 +35,8 @@ import type {
  *   rowSortingFeature,
  *   filteredRowModel: createFilteredRowModel(),
  *   sortedRowModel: createSortedRowModel(),
- *   filterFns: { ...filterFns, myCustomFilterFn },
- *   sortFns,
+ *   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' },
  * });

package/src/types/TableFeatures.ts

@@ -184,9 +184,11 @@ export interface TableFeatures
    * Registry of aggregation functions available to this table by name.
    *
    * Keys registered here become the valid string values for `aggregationFn` on
-   * column definitions, with full inference. Spread the exported
-   * `aggregationFns` to register the built-in aggregation functions:
-   * `aggregationFns: { ...aggregationFns, myCustomAggregationFn }`.
+   * column definitions, with full inference. Import the built-in aggregation
+   * functions you use individually and register them by their conventional
+   * names: `aggregationFns: { sum: aggregationFn_sum, myCustomAggregationFn }`.
+   * Spreading the exported `aggregationFns` registry also works, but puts
+   * every built-in aggregation function in your bundle.
    */
   aggregationFns?: Record<string, AggregationFn<any, any>>
   /**
@@ -243,8 +245,11 @@ export interface TableFeatures
    *
    * Keys registered here become the valid string values for `filterFn` on
    * column definitions and the `globalFilterFn` option, with full inference.
-   * Spread the exported `filterFns` to register the built-in filter functions:
-   * `filterFns: { ...filterFns, myCustomFilterFn }`.
+   * Import the built-in filter functions you use individually and register
+   * them by their conventional names:
+   * `filterFns: { includesString: filterFn_includesString, myCustomFilterFn }`.
+   * Spreading the exported `filterFns` registry also works, but puts every
+   * built-in filter function in your bundle.
    */
   filterFns?: Record<string, FilterFn<any, any>>
   /**
@@ -281,8 +286,11 @@ export interface TableFeatures
    * Registry of sorting functions available to this table by name.
    *
    * Keys registered here become the valid string values for `sortFn` on column
-   * definitions, with full inference. Spread the exported `sortFns` to register
-   * the built-in sorting functions: `sortFns: { ...sortFns, myCustomSortFn }`.
+   * definitions, with full inference. Import the built-in sorting functions
+   * you use individually and register them by their conventional names:
+   * `sortFns: { alphanumeric: sortFn_alphanumeric, myCustomSortFn }`. Spreading
+   * the exported `sortFns` registry also works, but puts every built-in
+   * sorting function in your bundle.
    */
   sortFns?: Record<string, SortFn<any, any>>
   /**

package/src/types/type-utils.ts

@@ -6,6 +6,14 @@ export type RowData = Record<string, any> | Array<any>
 
 export type CellData = unknown
 
+/**
+ * Normalizes a row's value before a filter or sort comparator sees it.
+ *
+ * Attach as `resolveDataValue` on filter/sort functions built with
+ * `constructFilterFn`/`constructSortFn` (e.g. to lowercase or strip diacritics).
+ */
+export type TransformDataValueFn = (dataValue: any) => any
+
 export type PartialKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
 
 export type RequiredKeys<T, K extends keyof T> = Omit<T, K> &