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

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
+}

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

@@ -0,0 +1,401 @@
+import { hasOwn, makeObjectMap } from '../../utils'
+import type { Cell } from '../../types/Cell'
+import type { Column, Column_Internal } from '../../types/Column'
+import type { Row } from '../../types/Row'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { CellData, RowData } from '../../types/type-utils'
+import type {
+  AggregationFnDef,
+  AggregationFnDescriptor,
+  AggregationFnRef,
+  ColumnAggregationValue,
+  ResolvedAggregationFn,
+} from './aggregationFeature.types'
+
+interface AggregationCacheEntry {
+  aggregationFnOption: unknown
+  dependency: unknown
+  registry: unknown
+  value: unknown
+}
+
+interface ResolvedAggregationFnsCacheEntry<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  coreRowModel: unknown
+  option: unknown
+  registry: unknown
+  value: ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>
+}
+
+function isAggregationFnDef(value: unknown): value is AggregationFnDef {
+  return !!value && typeof value === 'object' && 'aggregate' in value
+}
+
+function isAggregationFnDescriptor(
+  value: unknown,
+): value is AggregationFnDescriptor<any, any> {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    'id' in value &&
+    'aggregationFn' in value
+  )
+}
+
+function warn(message: string) {
+  if (process.env.NODE_ENV === 'development') {
+    console.warn(message)
+  }
+}
+
+/**
+ * Flattens hierarchical row inputs to unique terminal leaves in encounter
+ * order. This is the normalization used by public aggregation-value calls.
+ */
+export function normalizeAggregationRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(rows: ReadonlyArray<Row<TFeatures, TData>>): Array<Row<TFeatures, TData>> {
+  const result: Array<Row<TFeatures, TData>> = []
+  const seen = new Set<string>()
+
+  const visit = (row: Row<TFeatures, TData>) => {
+    if (row.subRows.length) {
+      for (let i = 0; i < row.subRows.length; i++) {
+        visit(row.subRows[i]!)
+      }
+      return
+    }
+
+    if (!seen.has(row.id)) {
+      seen.add(row.id)
+      result.push(row)
+    }
+  }
+
+  for (let i = 0; i < rows.length; i++) {
+    visit(rows[i]!)
+  }
+
+  return result
+}
+
+function getAutoAggregationFnName(
+  value: unknown,
+): 'extent' | 'sum' | undefined {
+  if (typeof value === 'number') {
+    return 'sum'
+  }
+
+  if (value instanceof Date && !Number.isNaN(value.getTime())) {
+    return 'extent'
+  }
+
+  return undefined
+}
+
+/** Resolves the `sum` or `extent` definition inferred from the first core row. */
+export function column_getAutoAggregationFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  const value = column.table.getCoreRowModel().flatRows[0]?.getValue(column.id)
+
+  const name = getAutoAggregationFnName(value)
+  if (!name) return undefined
+
+  const aggregationFn = column.table._rowModelFns.aggregationFns?.[name]
+
+  if (!aggregationFn) {
+    warn(
+      `aggregationFn '${name}' (auto) for column '${column.id}' is not registered`,
+    )
+  }
+
+  return aggregationFn
+}
+
+function resolveAggregationFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  column: Column_Internal<TFeatures, TData, any>,
+  ref: AggregationFnRef<TFeatures, TData, any, any>,
+): AggregationFnDef<TFeatures, TData, any, any> | undefined {
+  if (isAggregationFnDef(ref)) return ref as any
+  if (ref === 'auto') return column_getAutoAggregationFn(column)
+
+  const aggregationFn =
+    column.table._rowModelFns.aggregationFns?.[ref as string]
+  if (!aggregationFn) {
+    warn(
+      `aggregationFn '${String(ref)}' for column '${column.id}' is not registered`,
+    )
+  }
+  return aggregationFn
+}
+
+/** Resolves and validates a column's scalar or multiple aggregation option. */
+export function column_getAggregationFns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+): ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>> {
+  const option = column.columnDef.aggregationFn
+  const registry = column.table._rowModelFns.aggregationFns
+  const coreRowModel = column.table.getCoreRowModel()
+  const previous = (column as any)._resolvedAggregationFnsCache as
+    | ResolvedAggregationFnsCacheEntry<TFeatures, TData>
+    | undefined
+
+  if (
+    previous &&
+    previous.option === option &&
+    previous.registry === registry &&
+    previous.coreRowModel === coreRowModel
+  ) {
+    return previous.value
+  }
+
+  const finish = (
+    value: ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>,
+  ) => {
+    ;(column as any)._resolvedAggregationFnsCache = {
+      coreRowModel,
+      option,
+      registry,
+      value,
+    } satisfies ResolvedAggregationFnsCacheEntry<TFeatures, TData>
+    return value
+  }
+
+  if (option == null) return finish([])
+
+  if (!Array.isArray(option)) {
+    return finish([
+      {
+        aggregationFn: resolveAggregationFn(column, option as any),
+        id: typeof option === 'string' ? option : undefined,
+      },
+    ])
+  }
+
+  const ids = makeObjectMap<number>()
+  for (let i = 0; i < option.length; i++) {
+    const item = option[i]
+    const id =
+      typeof item === 'string'
+        ? item
+        : isAggregationFnDescriptor(item)
+          ? item.id
+          : undefined
+    if (id !== undefined) ids[id] = (ids[id] ?? 0) + 1
+  }
+
+  const resolved: Array<ResolvedAggregationFn<TFeatures, TData>> = []
+
+  for (let i = 0; i < option.length; i++) {
+    const item = option[i]
+    const id =
+      typeof item === 'string'
+        ? item
+        : isAggregationFnDescriptor(item)
+          ? item.id
+          : undefined
+
+    if (id === undefined) {
+      warn(
+        `aggregationFn at index ${i} for column '${column.id}' needs a stable id`,
+      )
+      resolved.push({ aggregationFn: undefined, id: undefined })
+      continue
+    }
+
+    if (ids[id]! > 1) {
+      warn(`aggregationFn id '${id}' for column '${column.id}' is duplicated`)
+      resolved.push({ aggregationFn: undefined, id })
+      continue
+    }
+
+    const ref = isAggregationFnDescriptor(item) ? item.aggregationFn : item
+    resolved.push({
+      aggregationFn: resolveAggregationFn(column, ref),
+      id,
+    })
+  }
+
+  return finish(resolved)
+}
+
+function getChildResult(
+  childValue: unknown,
+  isMultiple: boolean,
+  id: string | undefined,
+) {
+  if (!isMultiple) return childValue
+  if (!id || !childValue || typeof childValue !== 'object') return undefined
+  return hasOwn(childValue, id)
+    ? (childValue as Record<string, unknown>)[id]
+    : undefined
+}
+
+/** Executes every configured aggregation for a column over normalized rows. */
+export function aggregateColumnValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(args: {
+  childRows?: ReadonlyArray<Row<TFeatures, TData>>
+  column: Column<TFeatures, TData, unknown>
+  groupingRow?: Row<TFeatures, TData>
+  rows: ReadonlyArray<Row<TFeatures, TData>>
+}): unknown {
+  const { childRows, column, groupingRow, rows } = args
+  const internalColumn = column as Column_Internal<TFeatures, TData, unknown>
+  const entries = column_getAggregationFns(internalColumn)
+  const isMultiple = Array.isArray(internalColumn.columnDef.aggregationFn)
+  const canMerge =
+    !!childRows?.length &&
+    childRows.every(
+      (row) =>
+        !!(row as any).groupingColumnId &&
+        (row as any).groupingColumnId !== column.id,
+    )
+
+  const execute = (entry: ResolvedAggregationFn<TFeatures, TData>) => {
+    const definition = entry.aggregationFn
+    if (!definition) return undefined
+
+    const context = {
+      column,
+      columnId: column.id,
+      getValue: (row: Row<TFeatures, TData>) => row.getValue(column.id),
+      ...(groupingRow ? { groupingRow } : {}),
+      rows,
+      table: column.table as any,
+    }
+
+    if (canMerge && definition.merge) {
+      return definition.merge({
+        ...context,
+        childResults: childRows.map((row) =>
+          getChildResult(row.getValue(column.id), isMultiple, entry.id),
+        ),
+        childRows: childRows,
+      })
+    }
+
+    return definition.aggregate(context)
+  }
+
+  if (!isMultiple) {
+    return entries[0] ? execute(entries[0]) : undefined
+  }
+
+  const result = makeObjectMap<unknown>()
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]!
+    if (entry.id !== undefined) {
+      result[entry.id] = execute(entry)
+    }
+  }
+  return result
+}
+
+/** Implements `column.getAggregationValue(rows?)` and its default-value cache. */
+export function column_getAggregationValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  rows?: ReadonlyArray<Row<TFeatures, TData>>,
+): ColumnAggregationValue<TFeatures> {
+  const providedResult = column.columnDef.getAggregationValue?.({
+    column: column as any,
+    rows,
+    table: column.table as any,
+  })
+
+  if (providedResult) return providedResult.value as any
+  if (column.table.options.manualAggregation) return undefined
+
+  if (rows !== undefined) {
+    return aggregateColumnValue({
+      column: column as any,
+      rows: normalizeAggregationRows(rows),
+    }) as any
+  }
+
+  const model = column.table.getPreGroupedRowModel()
+  const previous = (column as any)._aggregationValueCache as
+    | AggregationCacheEntry
+    | undefined
+  const registry = column.table._rowModelFns.aggregationFns
+  const aggregationFnOption = column.columnDef.aggregationFn
+
+  if (
+    previous &&
+    previous.dependency === model &&
+    previous.registry === registry &&
+    previous.aggregationFnOption === aggregationFnOption
+  ) {
+    return previous.value as any
+  }
+
+  const value = aggregateColumnValue({
+    column: column as any,
+    rows: normalizeAggregationRows(model.rows),
+  })
+  ;(column as any)._aggregationValueCache = {
+    aggregationFnOption,
+    dependency: model,
+    registry,
+    value,
+  } satisfies AggregationCacheEntry
+  return value as any
+}
+
+/** Implements `cell.getIsAggregated()` for synthetic grouped rows. */
+export function cell_getIsAggregated<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(cell: Cell<TFeatures, TData, TValue>) {
+  const groupingColumnId = (cell.row as any).groupingColumnId as
+    | string
+    | undefined
+  if (!groupingColumnId || groupingColumnId === cell.column.id) return false
+
+  const grouping = (cell.column.table as any).atoms.grouping?.get?.() as
+    | Array<string>
+    | undefined
+  if (grouping?.includes(cell.column.id)) return false
+
+  return column_getAggregationFns(cell.column as any).some(
+    (entry) => !!entry.aggregationFn,
+  )
+}
+
+/** Formats the default scalar or keyed aggregated-cell representation. */
+export function formatAggregatedCellValue(
+  value: unknown,
+  option: unknown,
+): string | null {
+  if (value == null) return null
+
+  if (Array.isArray(option) && typeof value === 'object') {
+    const entries = Object.keys(value)
+    return entries
+      .map(
+        (key) => `${key}: ${String((value as Record<string, unknown>)[key])}`,
+      )
+      .join(', ')
+  }
+
+  return String(value)
+}