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

package/skills/migrate-v8-to-v9/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: lifecycle
   library: '@tanstack/table-core'
-  library_version: '9.0.0-beta.47'
+  library_version: '9.0.0-beta.48'
 requires: ['core', 'table-features', 'typescript']
 sources:
   - 'TanStack/table:docs/framework/react/guide/migrating.md'
@@ -70,7 +70,8 @@ V8 bundled all stock features. V9 exposes an API only when its feature is presen
 | --------------------------- | ------------------------- |
 | Column faceting             | `columnFacetingFeature`   |
 | Column filtering            | `columnFilteringFeature`  |
-| Grouping and aggregation    | `columnGroupingFeature`   |
+| Aggregation                 | `aggregationFeature`      |
+| Grouping                    | `columnGroupingFeature`   |
 | Column ordering             | `columnOrderingFeature`   |
 | Column pinning              | `columnPinningFeature`    |
 | Interactive column resizing | `columnResizingFeature`   |
@@ -90,6 +91,7 @@ Honor feature prerequisites in the same `tableFeatures` call:
 - `columnResizingFeature` requires `columnSizingFeature`.
 - `globalFilteringFeature` requires `columnFilteringFeature`.
 - Every row-model or function-registry slot requires its associated feature.
+- `aggregationFns` requires `aggregationFeature`; grouped aggregation uses both `aggregationFeature` and `columnGroupingFeature`.
 - Put prerequisite feature properties before dependent slots so inference and diagnostics remain clear.
 
 ### 2. Move row models into feature slots and rename factories
@@ -120,6 +122,16 @@ Move registries from table options or factory arguments into these feature slots
 
 Register only the built-ins the table references by string name, importing each individually (`filterFn_includesString`, `sortFn_alphanumeric`, `aggregationFn_sum`, and so on) alongside any custom functions. The full registry objects (`filterFns`, `sortFns`, `aggregationFns` exports) still work but bundle every built-in. A slot's keys become the valid string names in column definitions, and `'auto'` resolves only registered functions.
 
+Aggregation is independent from grouping. Add `aggregationFeature` for
+`aggregationFn`, `aggregatedCell`, `column.getAggregationValue(rows?)`, and
+`cell.getIsAggregated`. A root total does not require grouping. Convert legacy
+custom callables `(columnId, leafRows, childRows) => result` to
+`constructAggregationFn({ aggregate: (context) => result, merge? })`
+definitions. Replace `column.getAggregationFn()` with
+`column.getAggregationFns()`; arrays in `aggregationFn` return keyed objects.
+Replace the old `AggregationFn` and `CreatedAggregationFn` types with
+`AggregationFnDef`.
+
 ### 3. Migrate state reads and whole-state observation
 
 `table.getState()` and the top-level `onStateChange` option are removed. Individual `on[Slice]Change` callbacks remain.
@@ -280,6 +292,7 @@ Do not confuse new capabilities with required breakages. After the table works,
 - [ ] Move all remaining `get*RowModel()` options or earlier-beta `rowModels` entries to `create*RowModel()` feature slots.
 - [ ] Register each dependent feature before its row-model slot.
 - [ ] Move `filterFns`, `sortingFns`/`sortFns`, and `aggregationFns` into feature slots, registering individually imported built-ins; pass no registries to factories.
+- [ ] Register `aggregationFeature` independently and migrate custom aggregation callables to context-based `AggregationFnDef` definitions.
 - [ ] Register `columnFilteringFeature` before global filtering and filter/facet dependencies.
 - [ ] Register `columnSizingFeature` before `columnResizingFeature`.
 - [ ] Replace `table.getState()` and top-level `onStateChange` according to the adapter state guide.

package/skills/pagination/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.47',
+    library_version: '9.0.0-beta.48',
   }
 requires: ['core', 'table-features', 'client-vs-server']
 sources:

package/skills/row-pinning/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.47',
+    library_version: '9.0.0-beta.48',
   }
 requires: ['core', 'table-features']
 sources:

package/skills/row-selection/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.47',
+    library_version: '9.0.0-beta.48',
   }
 requires: ['core', 'table-features']
 sources:

package/skills/sorting/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.47',
+    library_version: '9.0.0-beta.48',
   }
 requires: ['core', 'table-features', 'client-vs-server']
 sources:

package/skills/table-features/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: sub-skill
   library: '@tanstack/table-core'
-  library_version: '9.0.0-beta.47'
+  library_version: '9.0.0-beta.48'
 requires: ['core']
 sources:
   - 'TanStack/table:docs/guide/row-models.md'
@@ -22,6 +22,7 @@ This skill builds on `core`. Read it first for the headless model and stable inp
 
 ```ts
 import {
+  aggregationFeature,
   aggregationFn_sum,
   columnGroupingFeature,
   createFilteredRowModel,
@@ -37,6 +38,7 @@ export const features = tableFeatures({
   columnFilteringFeature,
   filteredRowModel: createFilteredRowModel(),
   filterFns: { includesString: filterFn_includesString },
+  aggregationFeature,
   columnGroupingFeature,
   aggregationFns: { sum: aggregationFn_sum },
   rowSortingFeature,
@@ -66,6 +68,7 @@ const features = tableFeatures({
   filterFns: { includesString: filterFn_includesString },
   rowSortingFeature,
   sortFns: { alphanumeric: sortFn_alphanumeric },
+  aggregationFeature,
   columnGroupingFeature,
   aggregationFns: { sum: aggregationFn_sum },
 })
@@ -73,7 +76,7 @@ const features = tableFeatures({
 
 `filterFns`, `sortFns`, and `aggregationFns` are feature slots, not table
 options. They respectively require `columnFilteringFeature`,
-`rowSortingFeature`, and `columnGroupingFeature`. Import individual built-ins
+`rowSortingFeature`, and `aggregationFeature`. Import individual built-ins
 (`filterFn_*`, `sortFn_*`, `aggregationFn_*`) and register them under their
 conventional keys; the full registry objects (`filterFns`, `sortFns`,
 `aggregationFns` exports) still work but bundle every built-in. A registered

package/skills/typescript/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: sub-skill
   library: '@tanstack/table-core'
-  library_version: '9.0.0-beta.47'
+  library_version: '9.0.0-beta.48'
 requires: ['core', 'table-features']
 sources:
   - 'TanStack/table:docs/guide/helpers.md'

package/src/core/row-models/coreRowModelsFeature.utils.ts

@@ -92,7 +92,7 @@ export function table_getPreGroupedRowModel<
 }
 
 /**
- * Resolves the row model after grouping has produced grouped and aggregated rows.
+ * Resolves the row model after grouping has produced grouped rows.
  *
  * When `manualGrouping` is enabled, or no grouped row-model factory was
  * registered, this returns the pre-grouped row model unchanged.

package/src/features/aggregation/aggregationFeature.ts

@@ -0,0 +1,59 @@
+import { assignPrototypeAPIs, makeObjectMap } from '../../utils'
+import {
+  cell_getIsAggregated,
+  column_getAggregationFns,
+  column_getAggregationValue,
+  column_getAutoAggregationFn,
+  formatAggregatedCellValue,
+} from './aggregationFeature.utils'
+import type { TableFeature } from '../../types/TableFeatures'
+
+/**
+ * Independent aggregation feature for grouped values and root/custom-row totals.
+ */
+export const aggregationFeature: TableFeature = {
+  getDefaultColumnDef: () => ({
+    aggregatedCell: ({ column, getValue }: any) =>
+      formatAggregatedCellValue(getValue(), column.columnDef.aggregationFn),
+    aggregationFn: 'auto',
+  }),
+
+  getDefaultTableOptions: () => ({
+    manualAggregation: false,
+  }),
+
+  assignCellPrototype: (prototype, table) => {
+    assignPrototypeAPIs('aggregationFeature', prototype, table, {
+      cell_getIsAggregated: {
+        fn: (cell) => cell_getIsAggregated(cell),
+      },
+    })
+  },
+
+  assignColumnPrototype: (prototype, table) => {
+    assignPrototypeAPIs('aggregationFeature', prototype, table, {
+      column_getAggregationFns: {
+        fn: (column) => column_getAggregationFns(column),
+      },
+      column_getAggregationValue: {
+        fn: (column, rows) => column_getAggregationValue(column, rows),
+      },
+      column_getAutoAggregationFn: {
+        fn: (column) => column_getAutoAggregationFn(column),
+        memoDeps: (column) => [
+          column.table.getCoreRowModel(),
+          column.table._rowModelFns.aggregationFns,
+        ],
+      },
+    })
+  },
+
+  initColumnInstanceData: (column) => {
+    ;(column as any)._aggregationValueCache = undefined
+    ;(column as any)._resolvedAggregationFnsCache = undefined
+  },
+
+  initRowInstanceData: (row) => {
+    ;(row as any)._aggregationValuesCache = makeObjectMap()
+  },
+}

package/src/features/aggregation/aggregationFeature.types.ts

@@ -0,0 +1,312 @@
+import type { BuiltInAggregationFn } from './aggregationFns'
+import type { Cell } from '../../types/Cell'
+import type { Column } from '../../types/Column'
+import type { ColumnDefTemplate } from '../../types/ColumnDef'
+import type { IsAny, TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+import type { Table } from '../../types/Table'
+import type { CellData, RowData } from '../../types/type-utils'
+
+/** Declaration-merging fallback for named aggregation definitions. */
+export interface AggregationFns {}
+
+/** Values and table objects available while one aggregation is evaluated. */
+export interface AggregationContext<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue = unknown,
+> {
+  /** The column whose values are being aggregated. */
+  column: Column<TFeatures, TData, TValue>
+  /** Convenience alias for `column.id`. */
+  columnId: string
+  /** Reads this column's value from one of `rows`. */
+  getValue: (row: Row<TFeatures, TData>) => TValue
+  /**
+   * The synthetic grouped row receiving this result. This property is omitted
+   * for root or caller-supplied-row aggregation. Its `depth` identifies the
+   * grouping level when grouped aggregation needs that distinction.
+   */
+  groupingRow?: Row<TFeatures, TData>
+  /**
+   * Terminal leaf rows included in this aggregation. The executor normalizes
+   * hierarchical and duplicate row inputs before invoking the definition.
+   */
+  rows: ReadonlyArray<Row<TFeatures, TData>>
+  /** The table that owns the column and rows. */
+  table: Table<TFeatures, TData>
+}
+
+/** Additional values available when merging nested grouped results. */
+export interface AggregationMergeContext<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue,
+  TResult,
+> extends AggregationContext<TFeatures, TData, TValue> {
+  /** Results produced for each immediate child group, in child-row order. */
+  childResults: ReadonlyArray<TResult>
+  /** Immediate child group rows corresponding to `childResults`. */
+  childRows: ReadonlyArray<Row<TFeatures, TData>>
+}
+
+/** A context-based aggregation definition and optional grouped-result merge. */
+export interface AggregationFnDef<
+  TFeatures extends TableFeatures = any,
+  TData extends RowData = any,
+  TValue = unknown,
+  TResult = unknown,
+> {
+  /** Computes a result directly from normalized terminal rows. */
+  aggregate: (context: AggregationContext<TFeatures, TData, TValue>) => TResult
+  /**
+   * Combines already-computed immediate child-group results. When omitted,
+   * nested grouping falls back to `aggregate` over the group's terminal rows.
+   */
+  merge?: (
+    context: AggregationMergeContext<TFeatures, TData, TValue, TResult>,
+  ) => TResult
+}
+
+/**
+ * Creates a typed context-based aggregation definition for a column or
+ * aggregation-function registry.
+ */
+export function constructAggregationFn<
+  TFeatures extends TableFeatures = any,
+  TData extends RowData = any,
+  TValue = unknown,
+  TResult = unknown,
+>(
+  definition: AggregationFnDef<TFeatures, TData, TValue, TResult>,
+): AggregationFnDef<TFeatures, TData, TValue, TResult> {
+  return definition
+}
+
+/** Aggregation-definition registry carried by a table feature set. */
+export interface RowModelFns_Aggregation<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> {
+  aggregationFns: Record<string, AggregationFnDef<TFeatures, TData, any, any>>
+}
+
+/** Named context-based aggregation definitions registered on a feature set. */
+export type CustomAggregationFns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = Record<string, AggregationFnDef<TFeatures, TData, any, any>>
+
+/** String names available from a feature set's aggregation registry. */
+export type ExtractAggregationFnKeys<TFeatures extends TableFeatures> =
+  IsAny<TFeatures> extends true
+    ? keyof AggregationFns | BuiltInAggregationFn
+    : TFeatures extends { aggregationFns: infer TAggregationFns extends object }
+      ? Extract<keyof TAggregationFns, string>
+      : keyof AggregationFns
+
+/** A registered name, automatic inference, or inline aggregation definition. */
+export type AggregationFnRef<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue = unknown,
+  TResult = unknown,
+> =
+  | 'auto'
+  | ExtractAggregationFnKeys<TFeatures>
+  | AggregationFnDef<TFeatures, TData, TValue, TResult>
+
+/** Gives an aggregation reference a stable key in a multiple result. */
+export interface AggregationFnDescriptor<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue = unknown,
+  TResult = unknown,
+> {
+  /** The named, automatic, or inline definition to execute. */
+  aggregationFn: AggregationFnRef<TFeatures, TData, TValue, TResult>
+  /** Stable key used in the object returned by a multiple aggregation. */
+  id: string
+}
+
+/** One named or explicitly keyed entry in a multiple aggregation option. */
+export type AggregationFnListItem<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue = unknown,
+> =
+  | 'auto'
+  | ExtractAggregationFnKeys<TFeatures>
+  | AggregationFnDescriptor<TFeatures, TData, TValue, any>
+
+/** A scalar aggregation reference or a list that produces a keyed object. */
+export type AggregationFnOption<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue = unknown,
+> =
+  | AggregationFnRef<TFeatures, TData, TValue, any>
+  | ReadonlyArray<AggregationFnListItem<TFeatures, TData, TValue>>
+
+/** Extracts the result type produced by an aggregation definition. */
+export type AggregationResultOf<TDefinition> =
+  TDefinition extends AggregationFnDef<any, any, any, infer TResult>
+    ? TResult
+    : unknown
+
+type RegisteredAggregationDefinition<
+  TFeatures extends TableFeatures,
+  TKey extends PropertyKey,
+> = TFeatures extends {
+  aggregationFns: infer TRegistry extends Record<PropertyKey, unknown>
+}
+  ? TKey extends keyof TRegistry
+    ? TRegistry[TKey]
+    : never
+  : never
+
+type AggregationResultOfRef<TRef, TFeatures extends TableFeatures> =
+  TRef extends AggregationFnDef<any, any, any, any>
+    ? AggregationResultOf<TRef>
+    : TRef extends 'auto'
+      ? RegisteredAggregationResult<TFeatures>
+      : TRef extends PropertyKey
+        ? AggregationResultOf<RegisteredAggregationDefinition<TFeatures, TRef>>
+        : unknown
+
+type AggregationEntryId<TEntry> = TEntry extends string
+  ? TEntry
+  : TEntry extends { id: infer TId extends string }
+    ? TId
+    : never
+
+type AggregationEntryDefinition<TEntry> = TEntry extends {
+  aggregationFn: infer TDefinition
+}
+  ? TDefinition
+  : TEntry
+
+/** Infers the scalar or keyed result produced by an aggregation option. */
+export type AggregationResult<TOption, TFeatures extends TableFeatures = any> =
+  TOption extends ReadonlyArray<infer TEntry>
+    ? {
+        [TKey in AggregationEntryId<TEntry>]: AggregationResultOfRef<
+          AggregationEntryDefinition<Extract<TEntry, TKey | { id: TKey }>>,
+          TFeatures
+        >
+      }
+    : AggregationResultOfRef<TOption, TFeatures>
+
+type RegisteredAggregationResult<TFeatures extends TableFeatures> =
+  TFeatures extends {
+    aggregationFns: infer TRegistry extends Record<string, unknown>
+  }
+    ? AggregationResultOf<TRegistry[keyof TRegistry]>
+    : unknown
+
+/** Default public result union when a column's precise option is not known. */
+export type ColumnAggregationValue<TFeatures extends TableFeatures> =
+  | RegisteredAggregationResult<TFeatures>
+  | Record<string, RegisteredAggregationResult<TFeatures> | undefined>
+  | undefined
+
+/** A validated aggregation entry returned by `column.getAggregationFns()`. */
+export interface ResolvedAggregationFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /** Resolved definition, or `undefined` when configuration is invalid. */
+  aggregationFn: AggregationFnDef<TFeatures, TData, any, any> | undefined
+  /** Key used for a multiple result; scalar inline definitions have no id. */
+  id: string | undefined
+}
+
+/** Column-definition options installed by `aggregationFeature`. */
+export interface ColumnDef_Aggregation<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  /** Renderer used for a grouped row's aggregated cell. */
+  aggregatedCell?: ColumnDefTemplate<
+    ReturnType<Cell<TFeatures, TData, TValue>['getContext']>
+  >
+  /**
+   * One aggregation reference for a scalar result, or an array for a keyed
+   * result object. Inline definitions in an array require an explicit `id`.
+   */
+  aggregationFn?: AggregationFnOption<TFeatures, TData, TValue>
+  /**
+   * Optionally supplies a precomputed aggregation value for this column.
+   * Return `{ value }` to handle the request, including `{ value: undefined }`;
+   * return `undefined` to use the local aggregation fallback.
+   */
+  getAggregationValue?: (
+    context: AggregationValueContext<TFeatures, TData, TValue>,
+  ) => AggregationValueResult | undefined
+}
+
+/** Column instance APIs installed by `aggregationFeature`. */
+export interface Column_Aggregation<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> {
+  /** Resolves the configured scalar or multiple aggregation definitions. */
+  getAggregationFns: () => ReadonlyArray<
+    ResolvedAggregationFn<TFeatures, TData>
+  >
+  /**
+   * Aggregates this column over the default pre-grouped row model, or over a
+   * caller-provided array of rows. Explicit rows are normalized to unique
+   * terminal leaves and are intentionally not cached.
+   */
+  getAggregationValue: <TResult = ColumnAggregationValue<TFeatures>>(
+    rows?: ReadonlyArray<Row<TFeatures, TData>>,
+  ) => TResult
+  /** Infers `sum` for a numeric first row and `extent` for a Date first row. */
+  getAutoAggregationFn: () =>
+    | AggregationFnDef<TFeatures, TData, any, any>
+    | undefined
+}
+
+/** Cell instance APIs installed by `aggregationFeature`. */
+export interface Cell_Aggregation {
+  /** Whether this cell displays an aggregate on a synthetic grouped row. */
+  getIsAggregated: () => boolean
+}
+
+/** Internal per-row cache used while grouped aggregates are evaluated. */
+export interface Row_Aggregation {
+  /** Cached aggregate results keyed by column id. */
+  _aggregationValuesCache: Record<string, unknown>
+}
+
+/** Values passed to a column-level aggregation-value provider. */
+export interface AggregationValueContext<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  /** The column whose value was requested. */
+  column: Column<TFeatures, TData, TValue>
+  /** Caller-provided rows, or `undefined` for the default row model. */
+  rows?: ReadonlyArray<Row<TFeatures, TData>>
+  /** The table that owns the column. */
+  table: Table<TFeatures, TData>
+}
+
+/** Marks an aggregation-value override as handled. */
+export interface AggregationValueResult<TResult = unknown> {
+  /** The supplied value. `undefined` is still a handled result. */
+  value: TResult
+}
+
+/** Table options installed by `aggregationFeature`. */
+export interface TableOptions_Aggregation {
+  /**
+   * Disables local `column.getAggregationValue()` calculation when a column
+   * override does not handle the request. Group values supplied by manually
+   * grouped rows remain the responsibility of the data owner.
+   */
+  manualAggregation?: boolean
+}