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

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

@@ -1,4 +1,4 @@
-import { tableMemo } from '../../utils'
+import { copyInstancePropertiesWithoutMemos, tableMemo } from '../../utils'
 import { table_autoResetPageIndex } from '../row-pagination/rowPaginationFeature.utils'
 import { column_getCanSort, column_getSortFn } from './rowSortingFeature.utils'
 import type { Column_Internal } from '../../types/Column'
@@ -6,23 +6,27 @@ import type { TableFeatures } from '../../types/TableFeatures'
 import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
 import type { Table, Table_Internal } from '../../types/Table'
 import type { Row } from '../../types/Row'
-import type { SortFn, SortFns } from './rowSortingFeature.types'
+import type { SortFn } from './rowSortingFeature.types'
 import type { RowData } from '../../types/type-utils'
 
 /**
  * Creates a memoized sorted 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.
+ *
+ * Register the sorting functions you use with the `sortFns` slot on the
+ * `features` option:
+ * `tableFeatures({ rowSortingFeature, sortedRowModel: createSortedRowModel(), sortFns: { alphanumeric: sortFn_alphanumeric } })`.
+ * Importing individual `sortFn_*` functions keeps unused built-ins out of
+ * your bundle; sorting functions passed directly to the `sortFn` column
+ * option need no registration at all.
  */
 export function createSortedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
->(
-  sortFns: Record<keyof SortFns, SortFn<TFeatures, TData>>,
-): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
+>(): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
   return (_table) => {
     const table = _table as unknown as Table_Internal<TFeatures, TData>
-    if (!table._rowModelFns.sortFns) table._rowModelFns.sortFns = sortFns
     return tableMemo({
       feature: 'rowSortingFeature',
       table,
@@ -51,106 +55,134 @@ function _createSortedRowModel<
   const sortedFlatRows: Array<Row<TFeatures, TData>> = []
 
   // Filter out sortings that correspond to non existing columns
-  const availableSorting = sorting.filter((sort) =>
-    column_getCanSort(
-      table.getColumn(sort.id) as Column_Internal<TFeatures, TData>,
-    ),
-  )
-
-  const columnInfoById: Record<
-    string,
-    {
-      sortUndefined?: false | -1 | 1 | 'first' | 'last'
-      invertSorting?: boolean
-      sortFn: SortFn<TFeatures, TData>
-    }
-  > = {}
+  const availableSorting = sorting.filter((sort) => {
+    const column = table.getColumn(sort.id)
+    return column ? column_getCanSort(column) : false
+  })
+
+  if (!availableSorting.length) {
+    return preSortedRowModel
+  }
 
-  availableSorting.forEach((sortEntry) => {
+  const resolvedSorting: Array<{
+    id: string
+    desc?: boolean
+    sortUndefined?: false | -1 | 1 | 'first' | 'last'
+    invertSorting?: boolean
+    sortFn: SortFn<TFeatures, TData>
+  }> = []
+
+  for (let i = 0; i < availableSorting.length; i++) {
+    const sortEntry = availableSorting[i]!
     const column: Column_Internal<TFeatures, TData> | undefined =
       table.getColumn(sortEntry.id)
-    if (!column) return
+    if (!column) {
+      continue
+    }
 
-    columnInfoById[sortEntry.id] = {
+    resolvedSorting.push({
+      id: sortEntry.id,
+      desc: sortEntry.desc,
       sortUndefined: column.columnDef.sortUndefined,
       invertSorting: column.columnDef.invertSorting,
       sortFn: column_getSortFn(column),
-    }
-  })
+    })
+  }
 
-  const sortData = (rows: Array<Row<TFeatures, TData>>) => {
-    const sortedData = rows.slice()
+  const compareRows = (
+    rowA: Row<TFeatures, TData>,
+    rowB: Row<TFeatures, TData>,
+  ) => {
+    for (let i = 0; i < resolvedSorting.length; i++) {
+      const sortEntry = resolvedSorting[i]!
+      const sortUndefined = sortEntry.sortUndefined
+      const isDesc = sortEntry.desc
+
+      let sortInt = 0
+
+      // All sorting ints should always return in ascending order
+      if (sortUndefined) {
+        const aValue = rowA.getValue(sortEntry.id)
+        const bValue = rowB.getValue(sortEntry.id)
 
-    sortedData.sort((rowA, rowB) => {
-      for (let i = 0; i < availableSorting.length; i++) {
-        const sortEntry = availableSorting[i]!
-        const columnInfo = columnInfoById[sortEntry.id]!
-        const sortUndefined = columnInfo.sortUndefined
-        const isDesc = sortEntry.desc
-
-        let sortInt = 0
-
-        // All sorting ints should always return in ascending order
-        if (sortUndefined) {
-          const aValue = rowA.getValue(sortEntry.id)
-          const bValue = rowB.getValue(sortEntry.id)
-
-          const aUndefined = aValue === undefined
-          const bUndefined = bValue === undefined
-
-          if (aUndefined || bUndefined) {
-            if (sortUndefined === 'first') return aUndefined ? -1 : 1
-            if (sortUndefined === 'last') return aUndefined ? 1 : -1
-            sortInt =
-              aUndefined && bUndefined
-                ? 0
-                : aUndefined
-                  ? sortUndefined
-                  : -sortUndefined
-          }
+        const aUndefined = aValue === undefined
+        const bUndefined = bValue === undefined
+
+        if (aUndefined && bUndefined) {
+          continue
         }
 
-        if (sortInt === 0) {
-          sortInt = columnInfo.sortFn(rowA, rowB, sortEntry.id)
+        if (aUndefined || bUndefined) {
+          if (sortUndefined === 'first') return aUndefined ? -1 : 1
+          if (sortUndefined === 'last') return aUndefined ? 1 : -1
+          sortInt = aUndefined ? sortUndefined : -sortUndefined
         }
+      }
 
-        // If sorting is non-zero, take care of desc and inversion
-        if (sortInt !== 0) {
-          if (isDesc) {
-            sortInt *= -1
-          }
+      if (sortInt === 0) {
+        sortInt = sortEntry.sortFn(rowA, rowB, sortEntry.id)
+      }
 
-          if (columnInfo.invertSorting) {
-            sortInt *= -1
-          }
+      // If sorting is non-zero, take care of desc and inversion
+      if (sortInt !== 0) {
+        if (isDesc) {
+          sortInt *= -1
+        }
 
-          return sortInt
+        if (sortEntry.invertSorting) {
+          sortInt *= -1
         }
+
+        return sortInt
       }
-      return rowA.index - rowB.index
-    })
+    }
+
+    return rowA.index - rowB.index
+  }
+
+  const sortData = (
+    rows: Array<Row<TFeatures, TData>>,
+  ): {
+    rows: Array<Row<TFeatures, TData>>
+    changed: boolean
+  } => {
+    const sortedData = rows.slice()
+
+    sortedData.sort(compareRows)
+    let changed = false
 
     // If there are sub-rows, sort them. Clone only rows that need mutation
     // (i.e. have subRows) so we don't corrupt the source row model.
     for (let i = 0; i < sortedData.length; i++) {
       const row = sortedData[i]!
+      if (row !== rows[i]) {
+        changed = true
+      }
+
       if (row.subRows.length) {
-        // Preserve prototype chain so methods like getValue() remain accessible
-        const cloned = Object.create(Object.getPrototypeOf(row))
-        Object.assign(cloned, row)
-        cloned.subRows = sortData(row.subRows)
-        sortedData[i] = cloned
-        sortedFlatRows.push(cloned)
+        const sortedSubRows = sortData(row.subRows)
+
+        if (sortedSubRows.changed) {
+          // Preserve prototype chain so methods like getValue() remain accessible
+          const cloned = Object.create(Object.getPrototypeOf(row))
+          copyInstancePropertiesWithoutMemos(cloned, row)
+          cloned.subRows = sortedSubRows.rows
+          sortedData[i] = cloned
+          sortedFlatRows.push(cloned)
+          changed = true
+        } else {
+          sortedFlatRows.push(row)
+        }
       } else {
         sortedFlatRows.push(row)
       }
     }
 
-    return sortedData
+    return { rows: sortedData, changed }
   }
 
   return {
-    rows: sortData(preSortedRowModel.rows),
+    rows: sortData(preSortedRowModel.rows).rows,
     flatRows: sortedFlatRows,
     rowsById: preSortedRowModel.rowsById,
   }

package/src/features/row-sorting/rowSortingFeature.types.ts

@@ -1,8 +1,12 @@
 import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
-import type { Table } from '../../types/Table'
-import type { BuiltInSortFn } from '../../fns/sortFns'
-import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
-import type { TableFeatures } from '../../types/TableFeatures'
+import type { BuiltInSortFn } from './sortFns'
+import type {
+  OnChangeFn,
+  RowData,
+  TransformDataValueFn,
+  Updater,
+} from '../../types/type-utils'
+import type { IsAny, TableFeatures } from '../../types/TableFeatures'
 import type { Row } from '../../types/Row'
 
 export type SortDirection = 'asc' | 'desc'
@@ -19,23 +23,70 @@ export interface TableState_RowSorting {
 }
 
 export interface RowModelFns_RowSorting<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
-  sortFns: Record<keyof SortFns, SortFn<TFeatures, TData>>
+  sortFns: Record<string, SortFn<TFeatures, TData>>
 }
 
 export interface SortFns {}
 
 export interface SortFn<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   (
     rowA: Row<TFeatures, TData>,
     rowB: Row<TFeatures, TData>,
     columnId: string,
   ): number
+  /**
+   * Normalizes each row's value before the two sides are compared. Only
+   * honored by sorting functions built with `constructSortFn` (including all
+   * built-in sorting functions).
+   */
+  resolveDataValue?: TransformDataValueFn
+}
+
+/**
+ * The definition object accepted by `constructSortFn`.
+ *
+ * `sort` is a value-level comparator: it receives both rows' (resolved) data
+ * values instead of the whole rows, so normalization concerns stay in
+ * `resolveDataValue`.
+ */
+export interface SortFnDef<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> {
+  sort: (
+    dataValueA: any,
+    dataValueB: any,
+    rowA: Row<TFeatures, TData>,
+    rowB: Row<TFeatures, TData>,
+    columnId: string,
+  ) => number
+  resolveDataValue?: TransformDataValueFn
+}
+
+/**
+ * The shape returned by `constructSortFn`: a `SortFn` with its definition
+ * attached, so variants can be built by spreading it into another
+ * `constructSortFn` call.
+ *
+ * The call signature is generic so a created sorting function can be used
+ * with any table's rows, regardless of the feature set it was defined
+ * against.
+ */
+export interface CreatedSortFn<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> extends SortFnDef<TFeatures, TData> {
+  <TRowFeatures extends TableFeatures, TRowData extends RowData>(
+    rowA: Row<TRowFeatures, TRowData>,
+    rowB: Row<TRowFeatures, TRowData>,
+    columnId: string,
+  ): number
 }
 
 export type CustomSortFns<
@@ -43,14 +94,30 @@ export type CustomSortFns<
   TData extends RowData,
 > = Record<string, SortFn<TFeatures, TData>>
 
+/**
+ * Resolves the valid string names for `columnDef.sortFn` for a feature set.
+ *
+ * When the features object declares a `sortFns` registry
+ * (`tableFeatures({ ..., sortFns })`), its keys are the only valid names; a
+ * name is only assignable if a sorting function is actually registered for it.
+ * Otherwise this falls back to the global declaration-merged `SortFns`
+ * interface.
+ */
+export type ExtractSortFnKeys<TFeatures extends TableFeatures> =
+  IsAny<TFeatures> extends true
+    ? keyof SortFns | BuiltInSortFn
+    : TFeatures extends { sortFns: infer TSortFns extends object }
+      ? Extract<keyof TSortFns, string>
+      : keyof SortFns
+
 export type SortFnOption<
   TFeatures extends TableFeatures,
   TData extends RowData,
-> = 'auto' | keyof SortFns | BuiltInSortFn | SortFn<TFeatures, TData>
+> = 'auto' | ExtractSortFnKeys<TFeatures> | SortFn<TFeatures, TData>
 
 export interface ColumnDef_RowSorting<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Enables/Disables multi-sorting for this column.
@@ -87,8 +154,8 @@ export interface ColumnDef_RowSorting<
 }
 
 export interface Column_RowSorting<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Removes this column from the table's sorting state
@@ -184,8 +251,8 @@ export interface TableOptions_RowSorting {
 }
 
 export interface Table_RowSorting<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out _TFeatures extends TableFeatures,
+  in out _TData extends RowData,
 > {
   /**
    * Resets `sorting` to `initialState.sorting`.
@@ -200,8 +267,8 @@ export interface Table_RowSorting<
 }
 
 export interface Table_RowModels_Sorted<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Reads the row model immediately before sorting.
@@ -213,23 +280,9 @@ export interface Table_RowModels_Sorted<
   getSortedRowModel: () => RowModel<TFeatures, TData>
 }
 
-export interface CreateRowModel_Sorted<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> {
-  /**
-   * Factory used to retrieve the sorted row model. If using server-side
-   * sorting, this is not required. To use client-side sorting, pass the
-   * exported `createSortedRowModel()` or implement your own factory.
-   */
-  sortedRowModel?: (
-    table: Table<TFeatures, TData>,
-  ) => () => RowModel<TFeatures, TData>
-}
-
 export interface CachedRowModel_Sorted<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   sortedRowModel: () => RowModel<TFeatures, TData>
 }

package/src/features/row-sorting/rowSortingFeature.utils.ts

@@ -1,5 +1,5 @@
-import { reSplitAlphaNumeric, sortFn_basic } from '../../fns/sortFns'
 import { cloneState, isFunction } from '../../utils'
+import { reSplitAlphaNumeric, sortFn_basic } from './sortFns'
 import type { CellData, RowData, Updater } from '../../types/type-utils'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { Table_Internal } from '../../types/Table'
@@ -89,33 +89,55 @@ export function column_getAutoSortFn<
   const sortFns: Record<string, SortFn<TFeatures, TData>> | undefined =
     column.table._rowModelFns.sortFns
 
-  let sortFn: SortFn<TFeatures, TData> | undefined
-
   const firstRows = column.table.getFilteredRowModel().flatRows.slice(0, 10)
 
+  let sortFnName: string | undefined
   let isString = false
 
   for (let i = 0; i < firstRows.length; i++) {
     const value = firstRows[i]!.getValue(column.id)
 
     if (Object.prototype.toString.call(value) === '[object Date]') {
-      sortFn = sortFns?.datetime
+      sortFnName = 'datetime'
+      break
     }
 
     if (typeof value === 'string') {
       isString = true
 
       if (value.split(reSplitAlphaNumeric).length > 1) {
-        sortFn = sortFns?.alphanumeric
+        sortFnName = 'alphanumeric'
+        break
       }
     }
   }
 
-  if (isString) {
-    sortFn = sortFns?.text
+  if (!sortFnName && isString) {
+    sortFnName = 'text'
   }
 
-  return sortFn ?? sortFn_basic
+  if (sortFnName) {
+    let sortFn = sortFns?.[sortFnName]
+
+    if (!sortFn) {
+      if (process.env.NODE_ENV === 'development') {
+        console.warn(
+          `sortFn '${sortFnName}' (auto) for column '${column.id}' is not registered`,
+        )
+      }
+
+      // String columns degrade to a registered text sort before basic
+      if (sortFnName === 'alphanumeric') {
+        sortFn = sortFns?.text
+      }
+    }
+
+    if (sortFn) {
+      return sortFn
+    }
+  }
+
+  return sortFn_basic
 }
 
 /**
@@ -165,11 +187,23 @@ export function column_getSortFn<
   const sortFns: Record<string, SortFn<TFeatures, TData>> | undefined =
     column.table._rowModelFns.sortFns
 
-  return isFunction(column.columnDef.sortFn)
-    ? column.columnDef.sortFn
-    : column.columnDef.sortFn === 'auto'
-      ? column_getAutoSortFn(column)
-      : (sortFns?.[column.columnDef.sortFn as string] ?? sortFn_basic)
+  if (isFunction(column.columnDef.sortFn)) {
+    return column.columnDef.sortFn
+  }
+
+  if (column.columnDef.sortFn === 'auto') {
+    return column_getAutoSortFn(column)
+  }
+
+  const sortFn = sortFns?.[column.columnDef.sortFn as string]
+
+  if (process.env.NODE_ENV === 'development' && !sortFn) {
+    console.warn(
+      `sortFn '${String(column.columnDef.sortFn)}' for column '${column.id}' is not registered`,
+    )
+  }
+
+  return sortFn ?? sortFn_basic
 }
 
 /**
@@ -193,23 +227,15 @@ export function column_toggleSorting<
   desc?: boolean,
   multi?: boolean,
 ) {
-  // if (column.columns.length) {
-  //   column.columns.forEach((c, i) => {
-  //     if (c.id) {
-  //       table.toggleColumnSorting(c.id, undefined, multi || !!i)
-  //     }
-  //   })
-  //   return
-  // }
-
   // this needs to be outside of table.setSorting to be in sync with rerender
   const nextSortingOrder = column_getNextSortingOrder(column)
   const hasManualValue = typeof desc !== 'undefined'
 
   table_setSorting(column.table, (old) => {
     // Find any existing sorting for this column
-    const existingSorting = old.find((d) => d.id === column.id)
     const existingIndex = old.findIndex((d) => d.id === column.id)
+    const existingSorting =
+      existingIndex === -1 ? undefined : old[existingIndex]
 
     let newSorting: SortingState = []