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

package/src/features/column-faceting/createFacetedUniqueValues.ts

@@ -1,5 +1,9 @@
 import { callMemoOrStaticFn, tableMemo } from '../../utils'
-import { column_getFacetedRowModel } from './columnFacetingFeature.utils'
+import { column_getCanGlobalFilter } from '../global-filtering/globalFilteringFeature.utils'
+import {
+  column_getFacetedRowModel,
+  table_getGlobalFacetedRowModel,
+} from './columnFacetingFeature.utils'
 import type { Row } from '../../types/Row'
 import type { Table, Table_Internal } from '../../types/Table'
 import type { TableFeatures } from '../../types/TableFeatures'
@@ -24,6 +28,15 @@ export function createFacetedUniqueValues<
       table,
       fnName: 'table.getFacetedUniqueValues',
       memoDeps: () => {
+        if (columnId === '__global__') {
+          return [
+            callMemoOrStaticFn(
+              table,
+              'getGlobalFacetedRowModel',
+              table_getGlobalFacetedRowModel,
+            ).flatRows,
+          ]
+        }
         const column = table.getColumn(columnId)
         if (!column) return [table.getPreFilteredRowModel().flatRows]
         return [
@@ -35,7 +48,7 @@ export function createFacetedUniqueValues<
           ).flatRows,
         ]
       },
-      fn: (flatRows) => _createFacetedUniqueValues(columnId, flatRows),
+      fn: (flatRows) => _createFacetedUniqueValues(table, columnId, flatRows),
     })
   }
 }
@@ -43,21 +56,39 @@ export function createFacetedUniqueValues<
 function _createFacetedUniqueValues<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
->(columnId: string, flatRows: Array<Row<TFeatures, TData>>): Map<any, number> {
+>(
+  table: Table_Internal<TFeatures, TData>,
+  columnId: string,
+  flatRows: Array<Row<TFeatures, TData>>,
+): Map<any, number> {
+  // The global context aggregates unique values across every column that
+  // participates in global filtering
+  const columnIds =
+    columnId === '__global__'
+      ? table
+          .getAllLeafColumns()
+          .filter((column) => column_getCanGlobalFilter(column))
+          .map((column) => column.id)
+      : [columnId]
+
   const facetedUniqueValues = new Map<any, number>()
 
   for (let i = 0; i < flatRows.length; i++) {
-    const values = flatRows[i]!.getUniqueValues(columnId)
+    for (let c = 0; c < columnIds.length; c++) {
+      // the declared return type is Array, but rows return undefined for
+      // columns without an accessor (e.g. display columns)
+      const values = flatRows[i]!.getUniqueValues(columnIds[c]!) as
+        | Array<unknown>
+        | undefined
+      if (!values) continue
 
-    for (let j = 0; j < values.length; j++) {
-      const value = values[j]
-      if (facetedUniqueValues.has(value)) {
+      for (let j = 0; j < values.length; j++) {
+        const value = values[j]
+        const previousValue = facetedUniqueValues.get(value)
         facetedUniqueValues.set(
           value,
-          (facetedUniqueValues.get(value) ?? 0) + 1,
+          previousValue === undefined ? 1 : previousValue + 1,
         )
-      } else {
-        facetedUniqueValues.set(value, 1)
       }
     }
   }

package/src/features/column-filtering/columnFilteringFeature.ts

@@ -1,6 +1,7 @@
 import {
   assignPrototypeAPIs,
   assignTableAPIs,
+  makeObjectMap,
   makeStateUpdater,
 } from '../../utils'
 import {
@@ -69,8 +70,8 @@ export const columnFilteringFeature: TableFeature = {
   },
 
   initRowInstanceData: (row) => {
-    ;(row as any).columnFilters = {}
-    ;(row as any).columnFiltersMeta = {}
+    ;(row as any).columnFilters = makeObjectMap()
+    ;(row as any).columnFiltersMeta = makeObjectMap()
   },
 
   constructTableAPIs: (table) => {

package/src/features/column-filtering/columnFilteringFeature.types.ts

@@ -1,18 +1,33 @@
-import type { Table } from '../../types/Table'
-import type { BuiltInFilterFn } from '../../fns/filterFns'
+import type { BuiltInFilterFn } from './filterFns'
 import type {
   CellData,
   OnChangeFn,
   RowData,
+  TransformDataValueFn,
   Updater,
 } from '../../types/type-utils'
-import type { TableFeatures } from '../../types/TableFeatures'
+import type { IsAny, TableFeatures } from '../../types/TableFeatures'
 import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
 import type { Row } from '../../types/Row'
 import type { Column } from '../../types/Column'
 
 export interface FilterMeta {}
 
+/**
+ * Resolves the type of the filter meta attached to rows for a feature set.
+ *
+ * When the features object declares a `filterMeta` type-only slot
+ * (`tableFeatures({ ..., filterMeta: {} as MyFilterMeta })`), that type wins.
+ * Otherwise this falls back to the global declaration-merged `FilterMeta`
+ * interface.
+ */
+export type ExtractFilterMeta<TFeatures extends TableFeatures> =
+  IsAny<TFeatures> extends true
+    ? FilterMeta
+    : TFeatures extends { filterMeta: infer TFilterMeta extends object }
+      ? TFilterMeta
+      : FilterMeta
+
 export interface FilterFns {}
 
 export interface TableState_ColumnFiltering {
@@ -27,8 +42,8 @@ export interface ColumnFilter {
 }
 
 export interface ResolvedColumnFilter<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   filterFn: FilterFn<TFeatures, TData>
   id: string
@@ -36,24 +51,83 @@ export interface ResolvedColumnFilter<
 }
 
 export interface RowModelFns_ColumnFiltering<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
-  filterFns: Record<keyof FilterFns, FilterFn<TFeatures, RowData>>
+  filterFns: Record<string, FilterFn<TFeatures, TData>>
 }
 
 export interface FilterFn<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   (
     row: Row<TFeatures, TData>,
     columnId: string,
     filterValue: any,
-    addMeta?: (meta: FilterMeta) => void,
+    addMeta?: (meta: ExtractFilterMeta<TFeatures>) => void,
   ): boolean
+  /**
+   * Removes the filter from `state.columnFilters` when the filter value fails
+   * this test (e.g. empty strings for text filters).
+   */
   autoRemove?: ColumnFilterAutoRemoveTestFn<TFeatures, TData>
+  /**
+   * Normalizes the filter value before filtering runs.
+   *
+   * The table applies this once per filter (not per row) and passes the
+   * resolved value to the filter function as `filterValue`.
+   */
   resolveFilterValue?: TransformFilterValueFn<TFeatures, TData>
+  /**
+   * Normalizes each row's value before it is compared against the filter
+   * value. Only honored by filter functions built with `constructFilterFn`
+   * (including all built-in filter functions).
+   */
+  resolveDataValue?: TransformDataValueFn
+}
+
+/**
+ * The definition object accepted by `constructFilterFn`.
+ *
+ * `filter` is a value-level comparator: it receives the row's (resolved) data
+ * value and the (resolved) filter value instead of the whole row, so
+ * normalization concerns stay in `resolveDataValue`/`resolveFilterValue`.
+ */
+export interface FilterFnDef<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> {
+  filter: (
+    dataValue: any,
+    filterValue: any,
+    row: Row<TFeatures, TData>,
+    columnId: string,
+    addMeta?: (meta: ExtractFilterMeta<TFeatures>) => void,
+  ) => boolean
+  autoRemove?: (filterValue: any) => boolean
+  resolveFilterValue?: (filterValue: any) => any
+  resolveDataValue?: TransformDataValueFn
+}
+
+/**
+ * The shape returned by `constructFilterFn`: a `FilterFn` with its definition
+ * attached, so variants can be built by spreading it into another
+ * `constructFilterFn` call.
+ *
+ * The call signature is generic so a created filter function can be used with
+ * any table's rows, regardless of the feature set it was defined against.
+ */
+export interface CreatedFilterFn<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> extends FilterFnDef<TFeatures, TData> {
+  <TRowFeatures extends TableFeatures, TRowData extends RowData>(
+    row: Row<TRowFeatures, TRowData>,
+    columnId: string,
+    filterValue: any,
+    addMeta?: (meta: ExtractFilterMeta<TRowFeatures>) => void,
+  ): boolean
 }
 
 export type TransformFilterValueFn<
@@ -71,16 +145,33 @@ export type ColumnFilterAutoRemoveTestFn<
 export type CustomFilterFns<
   TFeatures extends TableFeatures,
   TData extends RowData,
-> = Record<string, FilterFn<TFeatures, RowData>>
+> = Record<string, FilterFn<TFeatures, TData>>
+
+/**
+ * Resolves the valid string names for `columnDef.filterFn` and
+ * `options.globalFilterFn` for a feature set.
+ *
+ * When the features object declares a `filterFns` registry
+ * (`tableFeatures({ ..., filterFns })`), its keys are the only valid names; a
+ * name is only assignable if a filter function is actually registered for it.
+ * Otherwise this falls back to the global declaration-merged `FilterFns`
+ * interface.
+ */
+export type ExtractFilterFnKeys<TFeatures extends TableFeatures> =
+  IsAny<TFeatures> extends true
+    ? keyof FilterFns | BuiltInFilterFn
+    : TFeatures extends { filterFns: infer TFilterFns extends object }
+      ? Extract<keyof TFilterFns, string>
+      : keyof FilterFns
 
 export type FilterFnOption<
   TFeatures extends TableFeatures,
   TData extends RowData,
-> = 'auto' | BuiltInFilterFn | keyof FilterFns | FilterFn<TFeatures, RowData>
+> = 'auto' | ExtractFilterFnKeys<TFeatures> | FilterFn<TFeatures, TData>
 
 export interface ColumnDef_ColumnFiltering<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Enables this column to participate in column-specific filtering.
@@ -96,8 +187,8 @@ export interface ColumnDef_ColumnFiltering<
 }
 
 export interface Column_ColumnFiltering<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Returns an automatically calculated filter function for the column based off of the columns first known value.
@@ -133,8 +224,8 @@ export interface Column_ColumnFiltering<
 }
 
 export interface Row_ColumnFiltering<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out _TData extends RowData,
 > {
   /**
    * The column filters map for the row. This object tracks whether a row is passing/failing specific filters by their column ID.
@@ -143,12 +234,12 @@ export interface Row_ColumnFiltering<
   /**
    * The column filters meta map for the row. This object tracks any filter meta for a row as optionally provided during the filtering process.
    */
-  columnFiltersMeta: Record<string, FilterMeta>
+  columnFiltersMeta: Record<string, ExtractFilterMeta<TFeatures>>
 }
 
 export interface TableOptions_ColumnFiltering<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out _TFeatures extends TableFeatures,
+  in out _TData extends RowData,
 > {
   /**
    * Enables column-specific filtering for all columns that also allow it.
@@ -196,8 +287,8 @@ export interface Table_ColumnFiltering {
 }
 
 export interface Table_RowModels_Filtered<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Resolves the row model after column and global filters have been applied.
@@ -209,24 +300,9 @@ export interface Table_RowModels_Filtered<
   getPreFilteredRowModel: () => RowModel<TFeatures, TData>
 }
 
-export interface CreateRowModel_Filtered<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> {
-  /**
-   * If provided, this factory is called once per table and should return a
-   * function that calculates the filtered row model.
-   * - For server-side filtering, this function is unnecessary and can be ignored since the server should already return the filtered row model.
-   * - For client-side filtering, pass the exported `createFilteredRowModel()` or implement your own factory.
-   */
-  filteredRowModel?: (
-    table: Table<TFeatures, TData>,
-  ) => () => RowModel<TFeatures, TData>
-}
-
 export interface CachedRowModel_Filtered<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   filteredRowModel: () => RowModel<TFeatures, TData>
 }

package/src/features/column-filtering/columnFilteringFeature.utils.ts

@@ -27,8 +27,12 @@ export function getDefaultColumnFiltersState(): ColumnFiltersState {
  * Chooses a built-in filter function from the column's first core row value.
  *
  * Strings use `includesString`, numbers use `inNumberRange`, booleans and
- * objects use `equals`, arrays use `arrIncludes`, and unknown values fall back
- * to `weakEquals`.
+ * objects use `equals`, dates use `inDateRange`, arrays use `arrIncludes`,
+ * and unknown values fall back to `weakEquals`.
+ *
+ * The chosen filter function is looked up in the table's `filterFns`
+ * registry. When it is not registered there, this returns `undefined` and
+ * warns in development instead of substituting a different filter function.
  *
  * @example
  * ```ts
@@ -40,34 +44,40 @@ export function column_getAutoFilterFn<
   TData extends RowData,
   TValue extends CellData = CellData,
 >(column: Column_Internal<TFeatures, TData, TValue>) {
-  const filterFns: Record<string, FilterFn<TFeatures, RowData>> | undefined =
+  const filterFns: Record<string, FilterFn<TFeatures, TData>> | undefined =
     column.table._rowModelFns.filterFns
 
   const firstRow = column.table.getCoreRowModel().flatRows[0]
 
   const value = firstRow ? firstRow.getValue(column.id) : undefined
 
-  if (typeof value === 'string') {
-    return filterFns?.includesString
-  }
+  let filterFnName: string
 
-  if (typeof value === 'number') {
-    return filterFns?.inNumberRange
+  if (typeof value === 'string') {
+    filterFnName = 'includesString'
+  } else if (typeof value === 'number') {
+    filterFnName = 'inNumberRange'
+  } else if (typeof value === 'boolean') {
+    filterFnName = 'equals'
+  } else if (Array.isArray(value)) {
+    filterFnName = 'arrIncludes'
+  } else if (Object.prototype.toString.call(value) === '[object Date]') {
+    filterFnName = 'inDateRange'
+  } else if (value !== null && typeof value === 'object') {
+    filterFnName = 'equals'
+  } else {
+    filterFnName = 'weakEquals'
   }
 
-  if (typeof value === 'boolean') {
-    return filterFns?.equals
-  }
+  const filterFn = filterFns?.[filterFnName]
 
-  if (value !== null && typeof value === 'object') {
-    return filterFns?.equals
-  }
-
-  if (Array.isArray(value)) {
-    return filterFns?.arrIncludes
+  if (process.env.NODE_ENV === 'development' && !filterFn) {
+    console.warn(
+      `filterFn '${filterFnName}' (auto) for column '${column.id}' is not registered`,
+    )
   }
 
-  return filterFns?.weakEquals
+  return filterFn
 }
 
 /**
@@ -90,7 +100,7 @@ export function column_getFilterFn<
   column: Column_Internal<TFeatures, TData, TValue>,
 ): FilterFn<TFeatures, TData> | undefined {
   let filterFn = null
-  const filterFns: Record<string, FilterFn<TFeatures, RowData>> | undefined =
+  const filterFns: Record<string, FilterFn<TFeatures, TData>> | undefined =
     column.table._rowModelFns.filterFns
   filterFn = isFunction(column.columnDef.filterFn)
     ? column.columnDef.filterFn
@@ -98,13 +108,17 @@ export function column_getFilterFn<
       ? column_getAutoFilterFn(column)
       : filterFns?.[column.columnDef.filterFn as string]
 
-  if (process.env.NODE_ENV === 'development' && !filterFn) {
+  if (
+    process.env.NODE_ENV === 'development' &&
+    !filterFn &&
+    column.columnDef.filterFn !== 'auto' // the auto picker warns on its own
+  ) {
     console.warn(
-      `Could not find a valid 'column.filterFn' for column with the ID: ${column.id}.`,
+      `filterFn '${String(column.columnDef.filterFn)}' for column '${column.id}' is not registered`,
     )
   }
 
-  return filterFn as FilterFn<TFeatures, TData> | undefined
+  return filterFn ?? undefined
 }
 
 /**
@@ -323,7 +337,7 @@ export function shouldAutoRemoveFilter<
 ) {
   return (
     (filterFn && filterFn.autoRemove
-      ? filterFn.autoRemove(value, column as Column_Internal<TFeatures, TData>)
+      ? filterFn.autoRemove(value, column as any)
       : false) ||
     typeof value === 'undefined' ||
     (typeof value === 'string' && !value)

package/src/features/column-filtering/createFilteredRowModel.ts

@@ -1,4 +1,4 @@
-import { tableMemo } from '../../utils'
+import { makeObjectMap, tableMemo } from '../../utils'
 import { table_getColumn } from '../../core/columns/coreColumnsFeature.utils'
 import {
   column_getCanGlobalFilter,
@@ -13,8 +13,6 @@ 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 {
-  FilterFn,
-  FilterFns,
   ResolvedColumnFilter,
   Row_ColumnFiltering,
 } from './columnFilteringFeature.types'
@@ -23,16 +21,20 @@ import type {
  * Creates a memoized filtered 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 filter functions you use with the `filterFns` slot on the
+ * `features` option:
+ * `tableFeatures({ columnFilteringFeature, filteredRowModel: createFilteredRowModel(), filterFns: { includesString: filterFn_includesString } })`.
+ * Importing individual `filterFn_*` functions keeps unused built-ins out of
+ * your bundle; filter functions passed directly to the `filterFn` column
+ * option need no registration at all.
  */
 export function createFilteredRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
->(
-  filterFns: Record<keyof FilterFns, FilterFn<TFeatures, RowData>>,
-): (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.filterFns) table._rowModelFns.filterFns = filterFns
     return tableMemo({
       feature: 'columnFilteringFeature',
       table,
@@ -62,8 +64,8 @@ function _createFilteredRowModel<
     >
     for (let i = 0; i < flatRows.length; i++) {
       const row = flatRows[i]!
-      row.columnFilters = {}
-      row.columnFiltersMeta = {}
+      row.columnFilters = makeObjectMap()
+      row.columnFiltersMeta = makeObjectMap()
     }
     return rowModel
   }
@@ -80,7 +82,13 @@ function _createFilteredRowModel<
       return
     }
 
-    const filterFn = column_getFilterFn(column)!
+    const filterFn = column_getFilterFn(column)
+
+    // A dev warning has already fired in column_getFilterFn; ignore the
+    // filter instead of crashing when its filter fn is not registered.
+    if (!filterFn) {
+      return
+    }
 
     resolvedColumnFilters.push({
       id: columnFilter.id,
@@ -117,7 +125,8 @@ function _createFilteredRowModel<
   >
   for (let i = 0; i < flatRows.length; i++) {
     const row = flatRows[i]!
-    row.columnFilters = {}
+    row.columnFilters = makeObjectMap()
+    row.columnFiltersMeta = makeObjectMap()
 
     if (resolvedColumnFilters.length) {
       for (let j = 0; j < resolvedColumnFilters.length; j++) {
@@ -130,9 +139,10 @@ function _createFilteredRowModel<
           id,
           currentColumnFilter.resolvedValue,
           (filterMeta) => {
-            !row.columnFiltersMeta
-              ? (row.columnFiltersMeta = {})
-              : (row.columnFiltersMeta[id] = filterMeta)
+            if (!row.columnFiltersMeta) {
+              row.columnFiltersMeta = makeObjectMap()
+            }
+            row.columnFiltersMeta[id] = filterMeta
           },
         )
       }
@@ -149,9 +159,10 @@ function _createFilteredRowModel<
             id,
             currentGlobalFilter.resolvedValue,
             (filterMeta) => {
-              !row.columnFiltersMeta
-                ? (row.columnFiltersMeta = {})
-                : (row.columnFiltersMeta[id] = filterMeta)
+              if (!row.columnFiltersMeta) {
+                row.columnFiltersMeta = makeObjectMap()
+              }
+              row.columnFiltersMeta[id] = filterMeta
             },
           )
         ) {