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

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

@@ -13,13 +13,14 @@ import type {
 // State Utils
 
 /**
- * Returns the default sorting state.
+ * Creates the default sorting state.
  *
- * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ * The feature default is an empty array, meaning no columns are sorted. Reset
+ * APIs use this value when `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultSortingState()
+ * const sorting = getDefaultSortingState()
  * ```
  */
 export function getDefaultSortingState(): SortingState {
@@ -27,13 +28,14 @@ export function getDefaultSortingState(): SortingState {
 }
 
 /**
- * Updates the table's sorting state slice.
+ * Routes a sorting updater through the table's sorting change handler.
  *
- * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ * The updater may be a next `SortingState` array or a function of the previous
+ * sorting state, matching the instance `table.setSorting` behavior.
  *
  * @example
  * ```ts
- * table_setSorting(table, (old) => old)
+ * table_setSorting(table, (old) => [...old, { id: 'age', desc: true }])
  * ```
  */
 export function table_setSorting<
@@ -44,9 +46,10 @@ export function table_setSorting<
 }
 
 /**
- * Resets the table's sorting state slice.
+ * Resets `sorting` to the configured initial state or feature default.
  *
- * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ * With no argument, the reset clones `table.initialState.sorting` when it
+ * exists. Passing `true` ignores initial state and resets to `[]`.
  *
  * @example
  * ```ts
@@ -67,13 +70,15 @@ export function table_resetSorting<
 // Column Utils
 
 /**
- * Infers sort fn for a column.
+ * Chooses a built-in sorting function from sampled filtered row values.
  *
- * The inference uses the column definition, table options, and sampled row values when needed.
+ * Date-like values use `datetime`, mixed text/numeric strings use
+ * `alphanumeric`, plain strings use `text`, and unknown values fall back to
+ * `basic`.
  *
  * @example
  * ```ts
- * const value = column_getAutoSortFn(column)
+ * const sortFn = column_getAutoSortFn(column)
  * ```
  */
 export function column_getAutoSortFn<
@@ -90,8 +95,8 @@ export function column_getAutoSortFn<
 
   let isString = false
 
-  for (const row of firstRows) {
-    const value = row.getValue(column.id)
+  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
@@ -114,13 +119,14 @@ export function column_getAutoSortFn<
 }
 
 /**
- * Infers sort dir for a column.
+ * Chooses the default first sort direction from the first filtered row value.
  *
- * The inference uses the column definition, table options, and sampled row values when needed.
+ * String columns start ascending so alphabetical order is natural; other value
+ * types start descending.
  *
  * @example
  * ```ts
- * const value = column_getAutoSortDir(column)
+ * const direction = column_getAutoSortDir(column)
  * ```
  */
 export function column_getAutoSortDir<
@@ -140,13 +146,15 @@ export function column_getAutoSortDir<
 }
 
 /**
- * Returns sort fn for a column.
+ * Resolves the sorting function configured for a column.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Function-valued `columnDef.sortFn` is returned directly, `'auto'` delegates
+ * to `column_getAutoSortFn`, and string values are looked up in the table's
+ * sorting function registry before falling back to `basic`.
  *
  * @example
  * ```ts
- * const value = column_getSortFn(column)
+ * const sortFn = column_getSortFn(column)
  * ```
  */
 export function column_getSortFn<
@@ -165,13 +173,15 @@ export function column_getSortFn<
 }
 
 /**
- * Toggles sorting for a column.
+ * Applies the next sorting state for this column.
  *
- * The update is applied through the owning table state slice and respects the feature options for that column.
+ * The toggle can add, replace, flip, or remove this column's sort entry. Multi
+ * sorting respects `enableMultiSort`, `maxMultiSortColCount`, and the `multi`
+ * argument.
  *
  * @example
  * ```ts
- * column_toggleSorting(column)
+ * column_toggleSorting(column, undefined, true)
  * ```
  */
 export function column_toggleSorting<
@@ -278,13 +288,14 @@ export function column_toggleSorting<
 }
 
 /**
- * Returns first sort dir for a column.
+ * Resolves the first direction used when this column begins sorting.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Column-level `sortDescFirst` wins, then table-level `sortDescFirst`, then the
+ * auto direction inferred from sampled values.
  *
  * @example
  * ```ts
- * const value = column_getFirstSortDir(column)
+ * const firstDirection = column_getFirstSortDir(column)
  * ```
  */
 export function column_getFirstSortDir<
@@ -300,13 +311,14 @@ export function column_getFirstSortDir<
 }
 
 /**
- * Returns next sorting order for a column.
+ * Resolves the next sort order for this column's toggle cycle.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The cycle starts with the first sort direction, flips between `asc` and
+ * `desc`, and can return `false` when sorting removal is enabled.
  *
  * @example
  * ```ts
- * const value = column_getNextSortingOrder(column)
+ * const nextOrder = column_getNextSortingOrder(column)
  * ```
  */
 export function column_getNextSortingOrder<
@@ -332,13 +344,14 @@ export function column_getNextSortingOrder<
 }
 
 /**
- * Returns whether a column can use sort.
+ * Checks whether this accessor column can participate in sorting.
  *
- * This combines column options, table options, and any required accessor or feature state for the capability.
+ * The column must have an accessor and sorting must be enabled by both the
+ * column definition and table options.
  *
  * @example
  * ```ts
- * const value = column_getCanSort(column)
+ * const canSort = column_getCanSort(column)
  * ```
  */
 export function column_getCanSort<
@@ -354,13 +367,14 @@ export function column_getCanSort<
 }
 
 /**
- * Returns whether a column can use multi sort.
+ * Checks whether this column can be added to a multi-sort state.
  *
- * This combines column options, table options, and any required accessor or feature state for the capability.
+ * Column-level `enableMultiSort` wins over table-level `enableMultiSort`; if
+ * neither is set, accessor columns can multi-sort by default.
  *
  * @example
  * ```ts
- * const value = column_getCanMultiSort(column)
+ * const canMultiSort = column_getCanMultiSort(column)
  * ```
  */
 export function column_getCanMultiSort<
@@ -376,13 +390,14 @@ export function column_getCanMultiSort<
 }
 
 /**
- * Returns is sorted for a column.
+ * Reads this column's current sort direction.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The result is `false` when the column is not sorted, otherwise `'asc'` or
+ * `'desc'` based on the column's entry in `state.sorting`.
  *
  * @example
  * ```ts
- * const value = column_getIsSorted(column)
+ * const direction = column_getIsSorted(column)
  * ```
  */
 export function column_getIsSorted<
@@ -397,13 +412,13 @@ export function column_getIsSorted<
 }
 
 /**
- * Returns sort index for a column.
+ * Finds this column's position in the ordered `state.sorting` array.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The result is `-1` when the column is not sorted.
  *
  * @example
  * ```ts
- * const value = column_getSortIndex(column)
+ * const index = column_getSortIndex(column)
  * ```
  */
 export function column_getSortIndex<
@@ -418,13 +433,13 @@ export function column_getSortIndex<
 }
 
 /**
- * Clear Sorting. for a column.
+ * Removes this column from the sorting state.
  *
- * This is the static implementation behind the matching column instance API.
+ * Other sorted columns are preserved, including their relative order.
  *
  * @example
  * ```ts
- * const value = column_clearSorting(column)
+ * column_clearSorting(column)
  * ```
  */
 export function column_clearSorting<
@@ -439,13 +454,15 @@ export function column_clearSorting<
 }
 
 /**
- * Returns an event handler for toggling sorting handler.
+ * Creates a header event handler that toggles this column's sorting.
  *
- * The handler is intended for direct use in column header controls such as buttons or checkboxes.
+ * The handler ignores events when the column cannot sort, persists React-style
+ * synthetic events when present, and asks `options.isMultiSortEvent` whether
+ * the event should add to a multi-sort.
  *
  * @example
  * ```ts
- * const value = column_getToggleSortingHandler(column)
+ * const onClick = column_getToggleSortingHandler(column)
  * ```
  */
 export function column_getToggleSortingHandler<

package/src/fns/aggregationFns.ts

@@ -1,11 +1,13 @@
-import { isNumberArray } from '../utils'
 import type { RowData } from '../types/type-utils'
 import type { TableFeatures } from '../types/TableFeatures'
 import type { Row } from '../types/Row'
 import type { AggregationFn } from '../features/column-grouping/columnGroupingFeature.types'
 
 /**
- * Aggregation function for summing up the values of a column.
+ * Sums numeric child-row values for a grouped column.
+ *
+ * Non-number values contribute `0`. Child rows are used so nested group totals
+ * can reuse already aggregated values.
  */
 export const aggregationFn_sum: AggregationFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -24,7 +26,10 @@ export const aggregationFn_sum: AggregationFn<any, any> = <
 }
 
 /**
- * Aggregation function for finding the minimum value of a column.
+ * Finds the minimum numeric child-row value for a grouped column.
+ *
+ * Nullish and non-number values are ignored. Returns `undefined` when no
+ * numeric value is found.
  */
 export const aggregationFn_min: AggregationFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -52,7 +57,10 @@ export const aggregationFn_min: AggregationFn<any, any> = <
 }
 
 /**
- * Aggregation function for finding the maximum value of a column.
+ * Finds the maximum numeric child-row value for a grouped column.
+ *
+ * Nullish and non-number values are ignored. Returns `undefined` when no
+ * numeric value is found.
  */
 export const aggregationFn_max: AggregationFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -79,7 +87,10 @@ export const aggregationFn_max: AggregationFn<any, any> = <
 }
 
 /**
- * Aggregation function for finding the extent (min and max) of a column.
+ * Finds the numeric extent for a grouped column.
+ *
+ * Returns `[min, max]`, where each entry is `undefined` when no numeric value is
+ * present.
  */
 export const aggregationFn_extent: AggregationFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -108,7 +119,10 @@ export const aggregationFn_extent: AggregationFn<any, any> = <
 }
 
 /**
- * Aggregation function for finding the mean (average) of a column.
+ * Averages numeric leaf-row values for a grouped column.
+ *
+ * Number-like values are coerced with unary `+`; nullish and non-numeric values
+ * are ignored.
  */
 export const aggregationFn_mean: AggregationFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -140,7 +154,10 @@ export const aggregationFn_mean: AggregationFn<any, any> = <
 }
 
 /**
- * Aggregation function for finding the median value of a column.
+ * Computes the median of numeric leaf-row values for a grouped column.
+ *
+ * All values must be numbers. If any value is non-numeric, or no leaf rows are
+ * present, the result is `undefined`.
  */
 export const aggregationFn_median: AggregationFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -153,21 +170,28 @@ export const aggregationFn_median: AggregationFn<any, any> = <
     return
   }
 
-  const values = leafRows.map((row) => row.getValue(columnId))
-  if (!isNumberArray(values)) {
-    return
+  const values: Array<number> = new Array(leafRows.length)
+  for (let i = 0; i < leafRows.length; i++) {
+    const v = leafRows[i]!.getValue(columnId)
+    if (typeof v !== 'number') return
+    values[i] = v
   }
+
   if (values.length === 1) {
     return values[0]
   }
 
   const mid = Math.floor(values.length / 2)
-  const nums = values.sort((a, b) => a - b)
-  return values.length % 2 !== 0 ? nums[mid] : (nums[mid - 1]! + nums[mid]!) / 2
+  values.sort((a, b) => a - b)
+  return values.length % 2 !== 0
+    ? values[mid]
+    : (values[mid - 1]! + values[mid]!) / 2
 }
 
 /**
- * Aggregation function for finding the unique values of a column.
+ * Collects unique leaf-row values for a grouped column.
+ *
+ * Values are compared with JavaScript `Set` semantics.
  */
 export const aggregationFn_unique: AggregationFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -176,11 +200,17 @@ export const aggregationFn_unique: AggregationFn<any, any> = <
   columnId: string,
   leafRows: Array<Row<any, any>>,
 ) => {
-  return Array.from(new Set(leafRows.map((d) => d.getValue(columnId))).values())
+  const set = new Set<unknown>()
+  for (let i = 0; i < leafRows.length; i++) {
+    set.add(leafRows[i]!.getValue(columnId))
+  }
+  return Array.from(set.values())
 }
 
 /**
- * Aggregation function for finding the count of unique values of a column.
+ * Counts unique leaf-row values for a grouped column.
+ *
+ * Values are compared with JavaScript `Set` semantics.
  */
 export const aggregationFn_uniqueCount: AggregationFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -189,11 +219,17 @@ export const aggregationFn_uniqueCount: AggregationFn<any, any> = <
   columnId: string,
   leafRows: Array<Row<any, any>>,
 ) => {
-  return new Set(leafRows.map((d) => d.getValue(columnId))).size
+  const set = new Set<unknown>()
+  for (let i = 0; i < leafRows.length; i++) {
+    set.add(leafRows[i]!.getValue(columnId))
+  }
+  return set.size
 }
 
 /**
- * Aggregation function for counting the number of rows in a column.
+ * Counts the number of leaf rows in the group.
+ *
+ * The column id is ignored because the result is based only on group size.
  */
 export const aggregationFn_count: AggregationFn<any, any> = <
   TFeatures extends TableFeatures,

package/src/fns/filterFns.ts

@@ -6,7 +6,9 @@ import type { FilterFn } from '../features/column-filtering/columnFilteringFeatu
 // Basic filters
 
 /**
- * Filter function for checking if a value is exactly equal to a given value. (JS === comparison)
+ * Keeps rows whose column value is strictly equal to the filter value.
+ *
+ * Uses JavaScript `===` comparison and auto-removes empty filter values.
  */
 export const filterFn_equals: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -22,7 +24,10 @@ export const filterFn_equals: FilterFn<any, any> = <
 filterFn_equals.autoRemove = (val: any) => testFalsy(val)
 
 /**
- * Filter function for checking if a value is weakly equal to a given value. (JS == comparison)
+ * Keeps rows whose column value is loosely equal to the filter value.
+ *
+ * Uses JavaScript `==` comparison and auto-removes empty filter values. This is
+ * useful for matching string input against numeric row values.
  */
 export const filterFn_weakEquals: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -40,7 +45,9 @@ filterFn_weakEquals.autoRemove = (val: any) => testFalsy(val)
 // String filters
 
 /**
- * Filter function for checking if a string includes a given substring. (Case-sensitive)
+ * Keeps rows whose stringified column value includes the filter text.
+ *
+ * Matching is case-sensitive and empty filter values are auto-removed.
  */
 export const filterFn_includesStringSensitive: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -58,7 +65,10 @@ export const filterFn_includesStringSensitive: FilterFn<any, any> = <
 filterFn_includesStringSensitive.autoRemove = (val: any) => testFalsy(val)
 
 /**
- * Filter function for checking if a string includes a given substring. (Non-case-sensitive)
+ * Keeps rows whose stringified column value includes the filter text.
+ *
+ * Both values are lowercased before comparison, and empty filter values are
+ * auto-removed.
  */
 export const filterFn_includesString: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -80,7 +90,10 @@ export const filterFn_includesString: FilterFn<any, any> = <
 filterFn_includesString.autoRemove = (val: any) => testFalsy(val)
 
 /**
- * Filter function for checking if a string is exactly equal to a given string. (Non-case-sensitive)
+ * Keeps rows whose stringified column value equals the filter text.
+ *
+ * Both values are lowercased before comparison, and empty filter values are
+ * auto-removed.
  */
 export const filterFn_equalsString: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -99,7 +112,9 @@ export const filterFn_equalsString: FilterFn<any, any> = <
 filterFn_equalsString.autoRemove = (val: any) => testFalsy(val)
 
 /**
- * Filter function for checking if a string is exactly equal to a given string. (Case-sensitive)
+ * Keeps rows whose stringified column value exactly equals the filter text.
+ *
+ * Matching is case-sensitive and empty filter values are auto-removed.
  */
 export const filterFn_equalsStringSensitive: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -117,7 +132,10 @@ filterFn_equalsStringSensitive.autoRemove = (val: any) => testFalsy(val)
 // Number filters
 
 /**
- * Filter function for checking if a number is greater than a given number.
+ * Keeps rows whose value is greater than the filter value.
+ *
+ * Numeric values are compared numerically when both sides can be coerced to
+ * numbers; otherwise normalized strings are compared.
  */
 export const filterFn_greaterThan: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -144,7 +162,9 @@ export const filterFn_greaterThan: FilterFn<any, any> = <
 filterFn_greaterThan.resolveFilterValue = (val: any) => testFalsy(val)
 
 /**
- * Filter function for checking if a number is greater than or equal to a given number.
+ * Keeps rows whose value is greater than or equal to the filter value.
+ *
+ * Delegates to the built-in greater-than and equality comparisons.
  */
 export const filterFn_greaterThanOrEqualTo: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -163,7 +183,9 @@ export const filterFn_greaterThanOrEqualTo: FilterFn<any, any> = <
 filterFn_greaterThanOrEqualTo.resolveFilterValue = (val: any) => testFalsy(val)
 
 /**
- * Filter function for checking if a number is less than a given number.
+ * Keeps rows whose value is less than the filter value.
+ *
+ * This is implemented as the inverse of greater-than-or-equal comparison.
  */
 export const filterFn_lessThan: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -179,7 +201,9 @@ export const filterFn_lessThan: FilterFn<any, any> = <
 filterFn_lessThan.resolveFilterValue = (val: any) => testFalsy(val)
 
 /**
- * Filter function for checking if a number is less than or equal to a given number.
+ * Keeps rows whose value is less than or equal to the filter value.
+ *
+ * This is implemented as the inverse of greater-than comparison.
  */
 export const filterFn_lessThanOrEqualTo: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -197,7 +221,9 @@ filterFn_lessThanOrEqualTo.resolveFilterValue = (val: any) => testFalsy(val)
 // Range filters
 
 /**
- * Filter function for checking if a number or a string is between two given values.
+ * Keeps rows whose value falls between an exclusive min/max pair.
+ *
+ * Blank range endpoints are treated as open-ended.
  */
 const filterFn_between: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -218,7 +244,9 @@ const filterFn_between: FilterFn<any, any> = <
 filterFn_between.autoRemove = (val: any) => !val
 
 /**
- * Filter function for checking if a number or a string is between two given values or equal to them.
+ * Keeps rows whose value falls between an inclusive min/max pair.
+ *
+ * Blank range endpoints are treated as open-ended.
  */
 const filterFn_betweenInclusive: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -239,7 +267,10 @@ const filterFn_betweenInclusive: FilterFn<any, any> = <
 filterFn_betweenInclusive.autoRemove = (val: any) => !val
 
 /**
- * Filter function for checking if a number is within a given range.
+ * Keeps rows whose numeric value is inside an inclusive `[min, max]` range.
+ *
+ * Filter values are normalized so blank endpoints become open-ended and
+ * reversed endpoints are swapped.
  */
 export const filterFn_inNumberRange: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -282,7 +313,7 @@ filterFn_inNumberRange.autoRemove = (val: any) =>
 // Array filters
 
 /**
- * Filter function for checking if an array has a given value.
+ * Keeps rows whose scalar column value equals at least one filter value.
  */
 export const filterFn_arrHas: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -296,7 +327,7 @@ export const filterFn_arrHas: FilterFn<any, any> = <
 }
 
 /**
- * Filter function for checking if an array includes a given value.
+ * Keeps rows whose array or string column value includes at least one filter value.
  */
 export const filterFn_arrIncludes: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -316,7 +347,7 @@ export const filterFn_arrIncludes: FilterFn<any, any> = <
 filterFn_arrIncludes.autoRemove = (val: any) => testFalsy(val) || !val?.length
 
 /**
- * Filter function for checking if an array includes all of the given values.
+ * Keeps rows whose array column value includes every filter value.
  */
 export const filterFn_arrIncludesAll: FilterFn<any, any> = <
   TFeatures extends TableFeatures,
@@ -335,7 +366,7 @@ filterFn_arrIncludesAll.autoRemove = (val: any) =>
   testFalsy(val) || !val?.length
 
 /**
- * Filter function for checking if an array includes any of the given values.
+ * Keeps rows whose array column value includes at least one filter value.
  */
 export const filterFn_arrIncludesSome: FilterFn<any, any> = <
   TFeatures extends TableFeatures,

package/src/helpers/columnHelper.ts

@@ -78,16 +78,21 @@ export type ColumnHelper<
 }
 
 /**
- * A helper utility for creating column definitions with slightly better type inference for each individual column.
- * The `TValue` generic is inferred based on the accessor key or function provided.
- * **Note:** From a JavaScript perspective, the functions in these helpers do not do anything. They are only used to help TypeScript infer the correct types for the column definitions.
+ * Creates helper functions for authoring column definitions with stronger value
+ * inference.
+ *
+ * `accessor` infers `TValue` from an accessor key or accessor function,
+ * `display` creates non-data columns, `group` creates parent columns, and
+ * `columns` preserves tuple-level value types for arrays. At runtime these
+ * helpers only return column definition objects.
+ *
  * @example
  * ```tsx
  * const helper = createColumnHelper<typeof _features, Person>() // _features is the result of `tableFeatures({})` helper
  * const columns = [
  *  helper.display({ id: 'actions', header: 'Actions' }),
  *  helper.accessor('firstName', {}),
- *  helper.accessor((row) => row.lastName, {}
+ *  helper.accessor((row) => row.lastName, { id: 'lastName' }),
  * ]
  * ```
  */