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

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

@@ -172,7 +172,9 @@ export interface TableOptions_RowSorting {
    */
   maxMultiSortColCount?: number
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.sorting` changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table.
+   * Called with an updater when sorting state changes. Pair this with
+   * `state.sorting` when using external state; external atoms can own the slice
+   * without this callback.
    */
   onSortingChange?: OnChangeFn<SortingState>
   /**
@@ -190,7 +192,7 @@ export interface Table_RowSorting<
    */
   resetSorting: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.sorting` state.
+   * Sets sorting state using a value or updater.
    */
   setSorting: (updater: Updater<SortingState>) => void
 }
@@ -214,7 +216,9 @@ export interface CreateRowModel_Sorted<
   TData extends RowData,
 > {
   /**
-   * This function is used to retrieve the sorted row model. If using server-side sorting, this function is not required. To use client-side sorting, pass the exported `getSortedRowModel()` from your adapter to your table or implement your own.
+   * 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>,

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,
@@ -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

@@ -205,6 +205,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/reactivity.ts

@@ -1,3 +1,2 @@
 export * from './core/reactivity/coreReactivityFeature.types'
-export * from './core/reactivity/constructReactivityBindings'
 export * from './core/reactivity/coreReactivityFeature.utils'

package/src/store-reactivity-bindings.ts

@@ -0,0 +1,35 @@
+import { batch, createAtom } from '@tanstack/store'
+import type { TableReactivityBindings } from './core/reactivity/coreReactivityFeature.types'
+
+/**
+ * TanStack Store–based reactivity for vanilla / non-framework use of `constructTable`,
+ * with `createOptionsStore: true` so `table.optionsStore` is available for subscriptions.
+ *
+ * @example
+ * ```ts
+ * import { constructTable, tableFeatures } from '@tanstack/table-core'
+ * import { storeReactivityBindings } from '@tanstack/table-core/store-reactivity-bindings'
+ *
+ * const table = constructTable({
+ *   _features: tableFeatures({ coreReativityFeature: storeReactivityBindings() }),
+ *   // ...
+ * })
+ * ```
+ */
+export function storeReactivityBindings(): TableReactivityBindings {
+  return {
+    createOptionsStore: true,
+    batch,
+    untrack: (fn) => fn(),
+    createReadonlyAtom: (fn, options) => {
+      return createAtom(() => fn(), {
+        compare: options?.compare,
+      })
+    },
+    createWritableAtom: (value, options) => {
+      return createAtom(value, {
+        compare: options?.compare,
+      })
+    },
+  }
+}

package/src/types/Table.ts

@@ -1,4 +1,4 @@
-import type { ReadonlyAtom, ReadonlyStore } from '@tanstack/store'
+import type { ReadonlyStore } from '@tanstack/store'
 import type { Table_ColumnFaceting } from '../features/column-faceting/columnFacetingFeature.types'
 import type { Table_ColumnResizing } from '../features/column-resizing/columnResizingFeature.types'
 import type { Table_ColumnFiltering } from '../features/column-filtering/columnFilteringFeature.types'

package/src/utils.ts

@@ -3,12 +3,22 @@ import type { NoInfer, RowData, Updater } from './types/type-utils'
 import type { TableFeatures } from './types/TableFeatures'
 import type { TableState, TableState_All } from './types/TableState'
 
+/**
+ * Applies a TanStack updater to a value.
+ *
+ * If the updater is a function it is called with the previous value; otherwise the updater value is returned directly.
+ */
 export function functionalUpdate<T>(updater: Updater<T>, input: T): T {
   return typeof updater === 'function'
     ? (updater as (i: T) => T)(input)
     : updater
 }
 
+/**
+ * Clones table state values while preserving non-plain objects.
+ *
+ * Plain objects and arrays are copied recursively so state updates can avoid mutating existing references.
+ */
 export function cloneState<T>(value: T): T {
   if (Array.isArray(value)) {
     return value.map(cloneState) as T
@@ -33,8 +43,16 @@ export function cloneState<T>(value: T): T {
   return value
 }
 
+/**
+ * A no-operation function used as a safe default callback.
+ */
 export function noop() {}
 
+/**
+ * Creates a table state updater for a single state slice.
+ *
+ * The updater writes through the table base atom for the slice and supports both value and functional updater forms.
+ */
 export function makeStateUpdater<
   TFeatures extends TableFeatures,
   K extends (string & {}) | keyof TableState_All | keyof TableState<TFeatures>,
@@ -48,14 +66,25 @@ export function makeStateUpdater<
 
 type AnyFunction = (...args: any) => any
 
+/**
+ * Returns whether a value is a function.
+ */
 export function isFunction<T extends AnyFunction>(d: any): d is T {
   return d instanceof Function
 }
 
+/**
+ * Returns whether a value is an array containing only numbers.
+ */
 export function isNumberArray(d: any): d is Array<number> {
   return Array.isArray(d) && d.every((val) => typeof val === 'number')
 }
 
+/**
+ * Flattens a tree of nodes by recursively reading child nodes.
+ *
+ * The original nodes are preserved in depth-first order.
+ */
 export function flattenBy<TNode>(
   arr: Array<TNode>,
   getChildren: (item: TNode) => Array<TNode>,
@@ -77,6 +106,12 @@ export function flattenBy<TNode>(
   return flat
 }
 
+/**
+ * Symbol used to attach internal memo metadata to wrapped functions.
+ *
+ * This is exported so diagnostics can recognize memoized functions without
+ * depending on a string property name.
+ */
 export const $internalMemoFnMeta = Symbol('memoFnMeta')
 export type MemoFnMeta = { originalArgsLength?: number }
 
@@ -103,6 +138,11 @@ interface MemoOptions<TDeps extends ReadonlyArray<any>, TDepArgs, TResult> {
   onBeforeUpdate?: () => void
 }
 
+/**
+ * Creates a dependency-tracked memoized function for table internals.
+ *
+ * The memo recomputes only when its dependency tuple changes and can emit debug timing information.
+ */
 export const memo = <TDeps extends ReadonlyArray<any>, TDepArgs, TResult>({
   fn,
   memoDeps,
@@ -164,6 +204,11 @@ const pad = (str: number | string, num: number) => {
   return str
 }
 
+/**
+ * Creates a table-aware memoized function.
+ *
+ * This wraps `memo` with table debug options and feature metadata so row models and derived APIs can share consistent diagnostics.
+ */
 export function tableMemo<
   TFeatures extends TableFeatures,
   TDeps extends ReadonlyArray<any>,