@tanstack/table-core 9.0.0-alpha.43 → 9.0.0-alpha.47

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

@@ -12,10 +12,30 @@ import type {
 
 // State Utils
 
+/**
+ * Returns the default sorting state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultSortingState()
+ * ```
+ */
 export function getDefaultSortingState(): SortingState {
   return []
 }
 
+/**
+ * Updates the table's sorting state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setSorting(table, (old) => old)
+ * ```
+ */
 export function table_setSorting<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -23,6 +43,17 @@ export function table_setSorting<
   table.options.onSortingChange?.(updater)
 }
 
+/**
+ * Resets the table's sorting state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetSorting(table)
+ * table_resetSorting(table, true)
+ * ```
+ */
 export function table_resetSorting<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -35,6 +66,16 @@ export function table_resetSorting<
 
 // Column Utils
 
+/**
+ * Infers sort fn for a column.
+ *
+ * The inference uses the column definition, table options, and sampled row values when needed.
+ *
+ * @example
+ * ```ts
+ * const value = column_getAutoSortFn(column)
+ * ```
+ */
 export function column_getAutoSortFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -49,8 +90,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
@@ -72,6 +113,16 @@ export function column_getAutoSortFn<
   return sortFn ?? sortFn_basic
 }
 
+/**
+ * Infers sort dir for a column.
+ *
+ * The inference uses the column definition, table options, and sampled row values when needed.
+ *
+ * @example
+ * ```ts
+ * const value = column_getAutoSortDir(column)
+ * ```
+ */
 export function column_getAutoSortDir<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -88,6 +139,16 @@ export function column_getAutoSortDir<
   return 'desc'
 }
 
+/**
+ * Returns sort fn for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getSortFn(column)
+ * ```
+ */
 export function column_getSortFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -103,6 +164,16 @@ export function column_getSortFn<
       : (sortFns?.[column.columnDef.sortFn as string] ?? sortFn_basic)
 }
 
+/**
+ * Toggles sorting for a column.
+ *
+ * The update is applied through the owning table state slice and respects the feature options for that column.
+ *
+ * @example
+ * ```ts
+ * column_toggleSorting(column)
+ * ```
+ */
 export function column_toggleSorting<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -206,6 +277,16 @@ export function column_toggleSorting<
   })
 }
 
+/**
+ * Returns first sort dir for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getFirstSortDir(column)
+ * ```
+ */
 export function column_getFirstSortDir<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -218,6 +299,16 @@ export function column_getFirstSortDir<
   return sortDescFirst ? 'desc' : 'asc'
 }
 
+/**
+ * Returns next sorting order for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getNextSortingOrder(column)
+ * ```
+ */
 export function column_getNextSortingOrder<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -240,6 +331,16 @@ export function column_getNextSortingOrder<
   return isSorted === 'desc' ? 'asc' : 'desc'
 }
 
+/**
+ * Returns whether a column can use sort.
+ *
+ * This combines column options, table options, and any required accessor or feature state for the capability.
+ *
+ * @example
+ * ```ts
+ * const value = column_getCanSort(column)
+ * ```
+ */
 export function column_getCanSort<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -252,6 +353,16 @@ export function column_getCanSort<
   )
 }
 
+/**
+ * Returns whether a column can use multi sort.
+ *
+ * This combines column options, table options, and any required accessor or feature state for the capability.
+ *
+ * @example
+ * ```ts
+ * const value = column_getCanMultiSort(column)
+ * ```
+ */
 export function column_getCanMultiSort<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -264,6 +375,16 @@ export function column_getCanMultiSort<
   )
 }
 
+/**
+ * Returns is sorted for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getIsSorted(column)
+ * ```
+ */
 export function column_getIsSorted<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -275,6 +396,16 @@ export function column_getIsSorted<
   return !columnSort ? false : columnSort.desc ? 'desc' : 'asc'
 }
 
+/**
+ * Returns sort index for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getSortIndex(column)
+ * ```
+ */
 export function column_getSortIndex<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -286,6 +417,16 @@ export function column_getSortIndex<
   )
 }
 
+/**
+ * Clear Sorting. for a column.
+ *
+ * This is the static implementation behind the matching column instance API.
+ *
+ * @example
+ * ```ts
+ * const value = column_clearSorting(column)
+ * ```
+ */
 export function column_clearSorting<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -297,6 +438,16 @@ export function column_clearSorting<
   )
 }
 
+/**
+ * Returns an event handler for toggling sorting handler.
+ *
+ * The handler is intended for direct use in column header controls such as buttons or checkboxes.
+ *
+ * @example
+ * ```ts
+ * const value = column_getToggleSortingHandler(column)
+ * ```
+ */
 export function column_getToggleSortingHandler<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/features/stockFeatures.ts

@@ -30,6 +30,11 @@ export interface StockFeatures {
   rowSortingFeature: typeof rowSortingFeature
 }
 
+/**
+ * The complete set of stock optional table features.
+ *
+ * Use individual feature exports for tree-shaking, or this aggregate when a table should include every built-in feature.
+ */
 export const stockFeatures: StockFeatures = {
   columnFacetingFeature,
   columnFilteringFeature,

package/src/flex-render.ts

@@ -3,6 +3,11 @@ import type { Header } from './types/Header'
 import type { TableFeatures } from './types/TableFeatures'
 import type { CellData, RowData } from './types/type-utils'
 
+/**
+ * Renders a static value or render function with the provided props.
+ *
+ * Framework adapters use this helper to support column definitions that contain either plain values or template functions.
+ */
 export function flexRender<TProps extends object>(
   comp: unknown,
   props: TProps,
@@ -33,6 +38,11 @@ export type FlexRenderProps<
       header?: never
     }
 
+/**
+ * Renders a static value or render function with the provided props.
+ *
+ * Framework adapters use this helper to support column definitions that contain either plain values or template functions.
+ */
 export function FlexRender<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/fns/aggregationFns.ts

@@ -1,4 +1,3 @@
-import { isNumberArray } from '../utils'
 import type { RowData } from '../types/type-utils'
 import type { TableFeatures } from '../types/TableFeatures'
 import type { Row } from '../types/Row'
@@ -153,17 +152,22 @@ 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
 }
 
 /**
@@ -176,7 +180,11 @@ 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())
 }
 
 /**
@@ -189,7 +197,11 @@ 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
 }
 
 /**
@@ -205,6 +217,11 @@ export const aggregationFn_count: AggregationFn<any, any> = <
   return leafRows.length
 }
 
+/**
+ * The built-in aggregation function registry.
+ *
+ * Pass this object to grouped row model creation or extend it with custom aggregation functions for grouped columns.
+ */
 export const aggregationFns = {
   sum: aggregationFn_sum,
   min: aggregationFn_min,

package/src/fns/filterFns.ts

@@ -355,6 +355,11 @@ filterFn_arrIncludesSome.autoRemove = (val: any) =>
 
 // Export
 
+/**
+ * The built-in filter function registry.
+ *
+ * Pass this object to filtered row model creation or extend it with custom filter functions.
+ */
 export const filterFns = {
   arrIncludes: filterFn_arrIncludes,
   arrIncludesAll: filterFn_arrIncludesAll,

package/src/fns/sortFns.ts

@@ -3,8 +3,19 @@ import type { TableFeatures } from '../types/TableFeatures'
 import type { Row } from '../types/Row'
 import type { SortFn } from '../features/row-sorting/rowSortingFeature.types'
 
+/**
+ * Regular expression used to split mixed text and numeric chunks.
+ *
+ * The alphanumeric sort functions use these chunks for natural sorting of
+ * strings like `item2` before `item10`.
+ */
 export const reSplitAlphaNumeric = /([0-9]+)/gm
 
+/**
+ * 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: SortFn<any, any> = <
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -19,6 +30,11 @@ export const sortFn_alphanumeric: SortFn<any, any> = <
   )
 }
 
+/**
+ * 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: SortFn<any, any> = <
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -35,6 +51,11 @@ export const sortFn_alphanumericCaseSensitive: SortFn<any, any> = <
 
 // The text filter 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: SortFn<any, any> = <
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -51,6 +72,11 @@ export const sortFn_text: SortFn<any, any> = <
 
 // The text filter 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: SortFn<any, any> = <
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -65,6 +91,11 @@ export const sortFn_textCaseSensitive: SortFn<any, any> = <
   )
 }
 
+/**
+ * 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: SortFn<any, any> = <
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -82,6 +113,11 @@ export const sortFn_datetime: SortFn<any, any> = <
   return a > b ? 1 : a < b ? -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: SortFn<any, any> = <
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -121,10 +157,14 @@ function compareAlphanumeric(aStr: string, bStr: string) {
   const a = aStr.split(reSplitAlphaNumeric).filter(Boolean)
   const b = bStr.split(reSplitAlphaNumeric).filter(Boolean)
 
-  // While
-  while (a.length && b.length) {
-    const aa = a.shift()!
-    const bb = b.shift()!
+  let ai = 0
+  let bi = 0
+  const aLen = a.length
+  const bLen = b.length
+
+  while (ai < aLen && bi < bLen) {
+    const aa = a[ai++]!
+    const bb = b[bi++]!
 
     const an = parseInt(aa, 10)
     const bn = parseInt(bb, 10)
@@ -156,11 +196,16 @@ function compareAlphanumeric(aStr: string, bStr: string) {
     }
   }
 
-  return a.length - b.length
+  return aLen - ai - (bLen - bi)
 }
 
 // Exports
 
+/**
+ * The built-in sorting function registry.
+ *
+ * Pass this object to sorted row model creation or extend it with custom sorting functions.
+ */
 export const sortFns = {
   alphanumeric: sortFn_alphanumeric,
   alphanumericCaseSensitive: sortFn_alphanumericCaseSensitive,

package/src/helpers/tableOptions.ts

@@ -2,6 +2,11 @@ import type { RowData } from '../types/type-utils'
 import type { TableFeatures } from '../types/TableFeatures'
 import type { TableOptions } from '../types/TableOptions'
 
+/**
+ * Returns table options while preserving generic inference.
+ *
+ * This helper is useful when composing reusable table options outside of a framework adapter call.
+ */
 export function tableOptions<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
@@ -13,6 +18,9 @@ export function tableOptions<
   _features: TFeatures
 }
 
+/**
+ * Returns table options while preserving generic inference when `data` is supplied later.
+ */
 export function tableOptions<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
@@ -24,6 +32,9 @@ export function tableOptions<
   _features: TFeatures
 }
 
+/**
+ * Returns table options while preserving generic inference when both `data` and `columns` are supplied later.
+ */
 export function tableOptions<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
@@ -35,11 +46,17 @@ export function tableOptions<
   _features: TFeatures
 }
 
+/**
+ * Returns a fully specified table options object without changing its runtime value.
+ */
 export function tableOptions<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
 >(options: TableOptions<TFeatures, TData>): TableOptions<TFeatures, TData>
 
+/**
+ * Returns table options while preserving generic inference when `_features` is supplied by a wrapper.
+ */
 export function tableOptions<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
@@ -47,6 +64,9 @@ export function tableOptions<
   options: Omit<TableOptions<TFeatures, TData>, '_features'>,
 ): Omit<TableOptions<TFeatures, TData>, '_features'>
 
+/**
+ * Returns table options while preserving generic inference when `data` and `_features` are supplied by a wrapper.
+ */
 export function tableOptions<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
@@ -54,6 +74,9 @@ export function tableOptions<
   options: Omit<TableOptions<TFeatures, TData>, 'data' | '_features'>,
 ): Omit<TableOptions<TFeatures, TData>, 'data' | '_features'>
 
+/**
+ * Returns table options while preserving generic inference when `columns` and `_features` are supplied by a wrapper.
+ */
 export function tableOptions<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
@@ -61,6 +84,9 @@ export function tableOptions<
   options: Omit<TableOptions<TFeatures, TData>, 'columns' | '_features'>,
 ): Omit<TableOptions<TFeatures, TData>, 'columns' | '_features'>
 
+/**
+ * Returns table options while preserving generic inference when `data`, `columns`, and `_features` are supplied by a wrapper.
+ */
 export function tableOptions<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
@@ -71,6 +97,12 @@ export function tableOptions<
   >,
 ): Omit<TableOptions<TFeatures, TData>, 'data' | 'columns' | '_features'>
 
+/**
+ * Runtime implementation for `tableOptions`.
+ *
+ * The helper returns the same object it receives; all value comes from the
+ * overloads preserving table option inference at compile time.
+ */
 export function tableOptions(options: unknown) {
   return options
 }

package/src/store-reactivity-bindings.ts

@@ -20,6 +20,7 @@ export function storeReactivityBindings(): TableReactivityBindings {
   return {
     createOptionsStore: true,
     batch,
+    schedule: (fn) => queueMicrotask(fn),
     untrack: (fn) => fn(),
     createReadonlyAtom: (fn, options) => {
       return createAtom(() => fn(), {