@tanstack/table-core 9.0.0-beta.46 → 9.0.0-beta.48

package/src/features/aggregation/aggregationFns.ts

@@ -0,0 +1,336 @@
+import { constructAggregationFn } from './aggregationFeature.types'
+import type { AggregationContext } from './aggregationFeature.types'
+
+type RangeValue = Date | number
+
+function isNumber(value: unknown): value is number {
+  return typeof value === 'number'
+}
+
+function isValidDate(value: unknown): value is Date {
+  return value instanceof Date && !Number.isNaN(value.getTime())
+}
+
+function getRangeKind(value: unknown): 'date' | 'number' | undefined {
+  if (isNumber(value)) return 'number'
+  if (isValidDate(value)) return 'date'
+  return undefined
+}
+
+function compareRangeValues(left: RangeValue, right: RangeValue) {
+  const leftValue = left instanceof Date ? left.getTime() : left
+  const rightValue = right instanceof Date ? right.getTime() : right
+  return leftValue - rightValue
+}
+
+function collectRangeValues(context: AggregationContext<any, any, unknown>) {
+  const values: Array<RangeValue> = []
+  let kind: 'date' | 'number' | undefined
+
+  for (let i = 0; i < context.rows.length; i++) {
+    const value = context.getValue(context.rows[i]!)
+    const valueKind = getRangeKind(value)
+    if (!valueKind) continue
+    kind ??= valueKind
+    if (valueKind === kind) values.push(value as RangeValue)
+  }
+
+  return values
+}
+
+/**
+ * Sums numeric row values. Non-number values contribute zero. As in the
+ * previous API, `NaN` is a number and therefore propagates through the sum.
+ */
+export const aggregationFn_sum = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  number
+>({
+  aggregate: (context) => {
+    let sum = 0
+    for (let i = 0; i < context.rows.length; i++) {
+      const value = context.getValue(context.rows[i]!)
+      sum += typeof value === 'number' ? value : 0
+    }
+    return sum
+  },
+  merge: ({ childResults }) => {
+    let sum = 0
+    for (let i = 0; i < childResults.length; i++) {
+      const value = childResults[i]
+      if (isNumber(value)) sum += value
+    }
+    return sum
+  },
+})
+
+/**
+ * Finds the minimum numeric or Date value. Invalid value types are ignored;
+ * `NaN` preserves the legacy numeric seeding behavior.
+ */
+export const aggregationFn_min = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  RangeValue | undefined
+>({
+  aggregate: (context) => {
+    const values = collectRangeValues(context)
+    let result = values[0]
+    for (let i = 1; i < values.length; i++) {
+      if (compareRangeValues(values[i]!, result!) < 0) result = values[i]
+    }
+    return result
+  },
+  merge: ({ childResults }) => {
+    let result: RangeValue | undefined
+    let kind: 'date' | 'number' | undefined
+    for (let i = 0; i < childResults.length; i++) {
+      const value = childResults[i]
+      const valueKind = getRangeKind(value)
+      if (!valueKind) continue
+      kind ??= valueKind
+      if (kind !== valueKind) continue
+      if (result === undefined || compareRangeValues(value!, result) < 0) {
+        result = value
+      }
+    }
+    return result
+  },
+})
+
+/**
+ * Finds the maximum numeric or Date value. Invalid value types are ignored;
+ * `NaN` preserves the legacy numeric seeding behavior.
+ */
+export const aggregationFn_max = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  RangeValue | undefined
+>({
+  aggregate: (context) => {
+    const values = collectRangeValues(context)
+    let result = values[0]
+    for (let i = 1; i < values.length; i++) {
+      if (compareRangeValues(values[i]!, result!) > 0) result = values[i]
+    }
+    return result
+  },
+  merge: ({ childResults }) => {
+    let result: RangeValue | undefined
+    let kind: 'date' | 'number' | undefined
+    for (let i = 0; i < childResults.length; i++) {
+      const value = childResults[i]
+      const valueKind = getRangeKind(value)
+      if (!valueKind) continue
+      kind ??= valueKind
+      if (kind !== valueKind) continue
+      if (result === undefined || compareRangeValues(value!, result) > 0) {
+        result = value
+      }
+    }
+    return result
+  },
+})
+
+/**
+ * Finds the minimum and maximum numeric or Date values. Empty inputs return
+ * `[undefined, undefined]`, preserving the previous built-in result shape.
+ */
+export const aggregationFn_extent = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  [RangeValue | undefined, RangeValue | undefined]
+>({
+  aggregate: (context) => {
+    const values = collectRangeValues(context)
+    if (!values.length) return [undefined, undefined]
+    let min = values[0]!
+    let max = values[0]!
+    for (let i = 1; i < values.length; i++) {
+      const value = values[i]!
+      if (compareRangeValues(value, min) < 0) min = value
+      if (compareRangeValues(value, max) > 0) max = value
+    }
+    return [min, max]
+  },
+  merge: ({ childResults }) => {
+    let result: [RangeValue | undefined, RangeValue | undefined] = [
+      undefined,
+      undefined,
+    ]
+    let kind: 'date' | 'number' | undefined
+    for (let i = 0; i < childResults.length; i++) {
+      const extent = childResults[i]!
+      const valueKind = getRangeKind(extent[0])
+      if (!valueKind) continue
+      kind ??= valueKind
+      if (kind !== valueKind) continue
+      if (result[0] === undefined) {
+        result = [extent[0], extent[1]]
+      } else {
+        if (compareRangeValues(extent[0]!, result[0]) < 0) {
+          result[0] = extent[0]
+        }
+        if (compareRangeValues(extent[1]!, result[1]!) > 0) {
+          result[1] = extent[1]
+        }
+      }
+    }
+    return result
+  },
+})
+
+/**
+ * Averages number and number-like row values. Nullish and non-numeric values
+ * are ignored; other values retain the legacy unary-plus coercion behavior.
+ */
+export const aggregationFn_mean = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  number | undefined
+>({
+  aggregate: (context) => {
+    let count = 0
+    let sum = 0
+    for (let i = 0; i < context.rows.length; i++) {
+      const value = context.getValue(context.rows[i]!)
+      if (value == null) continue
+      const numberValue = typeof value === 'number' ? value : +value
+      if (!Number.isNaN(numberValue)) {
+        count++
+        sum += numberValue
+      }
+    }
+    return count ? sum / count : undefined
+  },
+})
+
+/**
+ * Computes the median when every row value is a number. Returns `undefined`
+ * for empty inputs or when any value is non-numeric.
+ */
+export const aggregationFn_median = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  number | undefined
+>({
+  aggregate: (context) => {
+    if (!context.rows.length) return undefined
+    const values = new Array<number>(context.rows.length)
+    for (let i = 0; i < context.rows.length; i++) {
+      const value = context.getValue(context.rows[i]!)
+      if (typeof value !== 'number') return undefined
+      values[i] = value
+    }
+    values.sort((a, b) => a - b)
+    const mid = Math.floor(values.length / 2)
+    return values.length % 2
+      ? values[mid]
+      : (values[mid - 1]! + values[mid]!) / 2
+  },
+})
+
+/** Collects distinct row values using JavaScript `Set` semantics. */
+export const aggregationFn_unique = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  Array<unknown>
+>({
+  aggregate: (context) => {
+    const values = new Set<unknown>()
+    for (let i = 0; i < context.rows.length; i++) {
+      values.add(context.getValue(context.rows[i]!))
+    }
+    return Array.from(values)
+  },
+})
+
+/** Counts distinct row values using JavaScript `Set` semantics. */
+export const aggregationFn_uniqueCount = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  number
+>({
+  aggregate: (context) => {
+    const values = new Set<unknown>()
+    for (let i = 0; i < context.rows.length; i++) {
+      values.add(context.getValue(context.rows[i]!))
+    }
+    return values.size
+  },
+})
+
+/** Counts rows, independently of the column's values. */
+export const aggregationFn_count = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  number
+>({
+  aggregate: ({ rows }) => rows.length,
+  merge: ({ childResults }) => {
+    let count = 0
+    for (let i = 0; i < childResults.length; i++) {
+      const value = childResults[i]
+      if (isNumber(value)) count += value
+    }
+    return count
+  },
+})
+
+/** Returns the first row's value, including a nullish value. */
+export const aggregationFn_first = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  unknown
+>({
+  aggregate: (context) =>
+    context.rows[0] ? context.getValue(context.rows[0]) : undefined,
+  merge: ({ childResults }) => childResults[0],
+})
+
+/** Returns the last row's value, including a nullish value. */
+export const aggregationFn_last = constructAggregationFn<
+  any,
+  any,
+  unknown,
+  unknown
+>({
+  aggregate: (context) => {
+    const row = context.rows[context.rows.length - 1]
+    return row ? context.getValue(row) : undefined
+  },
+  merge: ({ childResults }) => childResults[childResults.length - 1],
+})
+
+/**
+ * Full built-in registry. Register individual definitions for tree-shaking.
+ *
+ * @deprecated Import individual `aggregationFn_*` definitions instead for a
+ * smaller bundle. This registry remains available for compatibility.
+ */
+export const aggregationFns = {
+  sum: aggregationFn_sum,
+  min: aggregationFn_min,
+  max: aggregationFn_max,
+  extent: aggregationFn_extent,
+  mean: aggregationFn_mean,
+  median: aggregationFn_median,
+  unique: aggregationFn_unique,
+  uniqueCount: aggregationFn_uniqueCount,
+  count: aggregationFn_count,
+  first: aggregationFn_first,
+  last: aggregationFn_last,
+}
+
+export type BuiltInAggregationFn = keyof typeof aggregationFns

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

@@ -1,8 +1,9 @@
-import type { BuiltInFilterFn } from '../../fns/filterFns'
+import type { BuiltInFilterFn } from './filterFns'
 import type {
   CellData,
   OnChangeFn,
   RowData,
+  TransformDataValueFn,
   Updater,
 } from '../../types/type-utils'
 import type { IsAny, TableFeatures } from '../../types/TableFeatures'
@@ -66,8 +67,67 @@ export interface FilterFn<
     filterValue: any,
     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<

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
@@ -47,27 +51,33 @@ export function column_getAutoFilterFn<
 
   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 (Array.isArray(value)) {
-    return filterFns?.arrIncludes
-  }
-
-  if (value !== null && typeof value === 'object') {
-    return filterFns?.equals
+  if (process.env.NODE_ENV === 'development' && !filterFn) {
+    console.warn(
+      `filterFn '${filterFnName}' (auto) for column '${column.id}' is not registered`,
+    )
   }
 
-  return filterFns?.weakEquals
+  return filterFn
 }
 
 /**
@@ -98,9 +108,13 @@ 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`,
     )
   }
 

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

@@ -22,8 +22,12 @@ import type {
  *
  * The factory reads the relevant table state atoms and options, then returns a row model function used by the table row-model pipeline.
  *
- * Register filter functions with the `filterFns` slot on the `features` option:
- * `tableFeatures({ columnFilteringFeature, filteredRowModel: createFilteredRowModel(), filterFns })`.
+ * 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,
@@ -78,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,