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

package/skills/aggregation/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: aggregation
+description: >
+  Aggregate TanStack Table columns independently of grouping, including grand totals, caller-selected row totals, multiple keyed aggregations, custom context-based definitions, grouped merges, manual values, and worker constraints.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.49',
+  }
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/guide/aggregation.md'
+  - 'TanStack/table:docs/framework/react/guide/aggregation.md'
+  - 'TanStack/table:packages/table-core/src/features/aggregation'
+  - 'TanStack/table:examples/react/aggregation'
+  - 'TanStack/table:examples/react/grouped-aggregation'
+---
+
+This skill builds on `core` and `table-features`. Aggregation is independent
+from grouping: use it alone for totals, or combine it with the `grouping` skill
+for synthetic grouped rows.
+
+## Setup
+
+<!-- skill-snippet:check -->
+
+```ts
+import {
+  aggregationFeature,
+  aggregationFn_mean,
+  aggregationFn_sum,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  aggregationFeature,
+  aggregationFns: {
+    mean: aggregationFn_mean,
+    sum: aggregationFn_sum,
+  },
+})
+```
+
+## Core Patterns
+
+### Grand total and selected row scopes
+
+```ts
+const grandTotal = salaryColumn.getAggregationValue()
+const filteredTotal = salaryColumn.getAggregationValue(
+  table.getFilteredRowModel().rows,
+)
+```
+
+The default uses the pre-grouped row model. Explicit rows can come from any row
+model or caller-selected subset. Hierarchical inputs are normalized to unique
+terminal rows. Default calls are cached; explicit-row calls intentionally are
+not because array identity and contents are caller-owned.
+
+### Multiple aggregations
+
+```ts
+columnHelper.accessor('salary', {
+  aggregationFn: ['mean', { id: 'range', aggregationFn: 'extent' }],
+})
+
+const value = salaryColumn.getAggregationValue<{
+  mean: number
+  range: [number, number]
+}>()
+```
+
+A scalar option returns a scalar. An array returns a keyed object. Named
+functions use their registry name; descriptors provide a stable `id`, which is
+required for inline definitions in an array.
+
+### Custom definitions
+
+```ts
+const weightedMean = constructAggregationFn({
+  aggregate: ({ rows, getValue }) => {
+    const total = rows.reduce((sum, row) => sum + Number(getValue(row)), 0)
+    return rows.length ? total / rows.length : undefined
+  },
+})
+```
+
+The context provides `rows`, `getValue`, `column`, `columnId`, `table`, and an
+optional `groupingRow`. Add `merge({ childResults, childRows, ...context })`
+when nested groups can efficiently combine child results; otherwise the engine
+re-runs `aggregate` over normalized terminal rows.
+
+### Manual or remote values
+
+Set a column definition's `getAggregationValue(context)` to return `{ value }`
+for requests handled by a server or another execution environment. Returning
+`undefined` falls back to the local definition. `manualAggregation: true`
+disables that local fallback.
+
+## Common Mistakes
+
+### [HIGH] Adding grouping for a grand total
+
+Wrong: registering `columnGroupingFeature` solely to total a column.
+
+Correct: register `aggregationFeature` and call
+`column.getAggregationValue()`. Grouping is only required for grouped rows.
+
+### [HIGH] Passing a scope label and rows
+
+There is no scope option. Call `getAggregationValue()` for the default or pass
+the exact rows from the desired row model.
+
+### [HIGH] Reusing the legacy callable signature
+
+Wrong: `(columnId, leafRows, childRows) => result`.
+
+Correct: `constructAggregationFn({ aggregate: ({ rows, getValue }) => result })`.
+
+### [MEDIUM] Assuming arbitrary totals run in the worker
+
+The experimental worker computes grouped row-model aggregates. Public
+`getAggregationValue(rows?)` totals execute on the main thread, and custom
+grouped results sent by the worker must be structured-cloneable.
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/features/aggregation/` and the
+Aggregation Guide. Use `Column_Aggregation`, `AggregationFnDef`,
+`AggregationContext`, and `AggregationResult` for the typed public surface.

package/skills/api-not-found/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.49'
 requires: ['core', 'table-features']
 sources:
   - 'TanStack/table:packages/table-core/src/index.ts'

package/skills/client-vs-server/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.49'
 requires: ['core', 'table-features']
 sources:
   - 'TanStack/table:docs/guide/row-models.md'

package/skills/column-faceting/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.49',
   }
 requires: ['core', 'table-features', 'column-filtering']
 sources:

package/skills/column-filtering/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.49',
   }
 requires: ['core', 'table-features', 'client-vs-server']
 sources:

package/skills/column-ordering/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.49',
   }
 requires: ['core', 'table-features']
 sources:

package/skills/column-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.49',
   }
 requires: ['core', 'table-features', 'column-sizing']
 sources:

package/skills/column-resizing/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.49',
   }
 requires: ['core', 'table-features', 'column-sizing']
 sources:

package/skills/column-sizing/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.49',
   }
 requires: ['core', 'table-features']
 sources:

package/skills/column-visibility/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.49',
   }
 requires: ['core', 'table-features']
 sources:

package/skills/core/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: core
   library: '@tanstack/table-core'
-  library_version: '9.0.0-beta.47'
+  library_version: '9.0.0-beta.49'
 sources:
   - 'TanStack/table:docs/overview.md'
   - 'TanStack/table:docs/guide/tables.md'

package/skills/custom-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.49'
 requires: ['core', 'table-features', 'typescript']
 sources:
   - 'TanStack/table:docs/framework/react/guide/custom-features.md'

package/skills/expanding/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.49',
   }
 requires: ['core', 'table-features', 'client-vs-server']
 sources:

package/skills/global-filtering/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.49',
   }
 requires: ['core', 'table-features', 'client-vs-server', 'column-filtering']
 sources:

package/skills/grouping/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: grouping
 description: >
-  Group and aggregate rows with columnGroupingFeature, groupedRowModel, aggregationFns, groupedColumnMode, and manualGrouping. Load for grouped, placeholder, or aggregated cells and grouping interactions with expansion or pagination.
+  Group rows with columnGroupingFeature, groupedRowModel, groupedColumnMode, and manualGrouping. Load for grouped or placeholder cells and grouping interactions with expansion or pagination.
 metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.47',
+    library_version: '9.0.0-beta.49',
   }
 requires: ['core', 'table-features', 'client-vs-server']
 sources:
@@ -15,13 +15,12 @@ sources:
   - 'TanStack/table:examples/react/grouping'
 ---
 
-This skill builds on `core`, `table-features`, and `client-vs-server`. Grouping creates row structure and aggregate values; the renderer chooses grouped-cell UI.
+This skill builds on `core`, `table-features`, and `client-vs-server`. Grouping creates row structure and the renderer chooses grouped-cell UI. Load the separate `aggregation` skill when grouped rows should also calculate values.
 
 ## Setup
 
 ```ts
 import {
-  aggregationFn_sum,
   columnGroupingFeature,
   createGroupedRowModel,
   tableFeatures,
@@ -30,26 +29,18 @@ import {
 export const features = tableFeatures({
   columnGroupingFeature,
   groupedRowModel: createGroupedRowModel(),
-  aggregationFns: { sum: aggregationFn_sum },
 })
 ```
 
-Import individual `aggregationFn_*` built-ins and register only those your
-columns reference by string name or that `aggregationFn: 'auto'` should
-resolve (numbers resolve to `sum`, dates to `extent`). The full
-`aggregationFns` registry object still works but bundles every built-in.
-
 ## Core Patterns
 
 ```ts
 const options = { groupedColumnMode: 'reorder' as const }
 const mode = cell.getIsGrouped()
   ? 'grouped'
-  : cell.getIsAggregated()
-    ? 'aggregated'
-    : cell.getIsPlaceholder()
-      ? 'placeholder'
-      : 'value'
+  : cell.getIsPlaceholder()
+    ? 'placeholder'
+    : 'value'
 ```
 
 Render these cell modes deliberately.
@@ -62,7 +53,7 @@ Wrong: `tableFeatures({ groupedRowModel: createGroupedRowModel() })`
 
 Correct: `tableFeatures({ columnGroupingFeature, groupedRowModel: createGroupedRowModel() })`
 
-The grouped slot and aggregation registry require `columnGroupingFeature`.
+The grouped row-model slot requires `columnGroupingFeature`.
 
 Source: `packages/table-core/src/types/TableFeatures.ts#FeatureSlotPrereqs`
 
@@ -95,10 +86,13 @@ Wrong: `render(cell.getValue())`
 
 Correct: `render(cell.getIsPlaceholder() ? null : cell.getValue())`
 
-Placeholder and aggregated cells do not represent ordinary leaf values.
+Placeholder cells do not represent ordinary leaf values. Group rows should
+only render their grouped cell when aggregation is not enabled.
 
 Source: `examples/react/grouping/src/main.tsx`
 
 ## API Discovery
 
-Inspect `node_modules/@tanstack/table-core/src/features/column-grouping/` and `src/fns/aggregationFns.ts`.
+Inspect `node_modules/@tanstack/table-core/src/features/column-grouping/` for
+grouping. Load the `aggregation` skill when totals, multiple aggregations,
+grouped aggregate values, or custom definitions are part of the task.

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.49'
 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.49',
   }
 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.49',
   }
 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.49',
   }
 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.49',
   }
 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.49'
 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.49'
 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()
+  },
+}