@tanstack/table-core 9.0.0-beta.5 → 9.0.0-beta.51

package/src/features/row-aggregation/rowAggregationFeature.utils.ts

@@ -0,0 +1,430 @@
+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 {
+  AggregationContext,
+  AggregationFnDef,
+  AggregationFnDescriptor,
+  AggregationFnRef,
+  AggregationValueOptions,
+  ColumnAggregationValue,
+  ResolvedAggregationFn,
+} from './rowAggregationFeature.types'
+
+interface AggregationCacheEntry {
+  aggregationFnOption: unknown
+  dependency: unknown
+  maxDepth: number
+  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)
+  }
+}
+
+function resolveMaxAggregationDepth(maxDepth: number | undefined) {
+  return maxDepth === undefined || Number.isNaN(maxDepth)
+    ? 0
+    : Math.max(0, Math.floor(maxDepth))
+}
+
+/**
+ * Selects unique rows at a maximum relative depth in encounter order.
+ * Branches that end before the requested depth contribute their deepest row.
+ */
+export function normalizeAggregationRows<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rows: ReadonlyArray<Row<TFeatures, TData>>,
+  maxDepth = 0,
+): Array<Row<TFeatures, TData>> {
+  const result: Array<Row<TFeatures, TData>> = []
+  const seen = new Set<string>()
+  const normalizedMaxDepth = resolveMaxAggregationDepth(maxDepth)
+
+  const visit = (row: Row<TFeatures, TData>, depth: number) => {
+    if (row.subRows.length && depth < normalizedMaxDepth) {
+      for (let i = 0; i < row.subRows.length; i++) {
+        visit(row.subRows[i]!, depth + 1)
+      }
+      return
+    }
+
+    if (!seen.has(row.id)) {
+      seen.add(row.id)
+      result.push(row)
+    }
+  }
+
+  for (let i = 0; i < rows.length; i++) {
+    visit(rows[i]!, 0)
+  }
+
+  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 getSubRowResult(
+  subRowValue: unknown,
+  isMultiple: boolean,
+  id: string | undefined,
+) {
+  if (!isMultiple) return subRowValue
+  if (!id || !subRowValue || typeof subRowValue !== 'object') return undefined
+  return hasOwn(subRowValue, id)
+    ? (subRowValue as Record<string, unknown>)[id]
+    : undefined
+}
+
+/** Executes every configured aggregation over a depth-selected row frontier. */
+export function aggregateColumnValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(args: {
+  maxDepth?: number
+  subRows?: ReadonlyArray<Row<TFeatures, TData>>
+  column: Column<TFeatures, TData, unknown>
+  groupingRow?: Row<TFeatures, TData>
+  rows: ReadonlyArray<Row<TFeatures, TData>>
+}): unknown {
+  const { subRows, column, groupingRow, rows } = args
+  const internalColumn = column as Column_Internal<TFeatures, TData, unknown>
+  const maxDepth = resolveMaxAggregationDepth(
+    args.maxDepth ?? internalColumn.columnDef.maxAggregationDepth,
+  )
+  const aggregationRows = normalizeAggregationRows(rows, maxDepth)
+  const entries = column_getAggregationFns(internalColumn)
+  const isMultiple = Array.isArray(internalColumn.columnDef.aggregationFn)
+  const canMerge =
+    !!subRows?.length &&
+    subRows.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: AggregationContext<TFeatures, TData, unknown> = {
+      ...(subRows ? { subRows } : {}),
+      column,
+      columnId: column.id,
+      getValue: (row: Row<TFeatures, TData>) => row.getValue(column.id),
+      ...(groupingRow ? { groupingRow } : {}),
+      maxDepth,
+      rows: aggregationRows,
+      table: column.table as any,
+    }
+
+    if (canMerge && definition.merge) {
+      return definition.merge({
+        ...context,
+        subRowResults: subRows.map((row) =>
+          getSubRowResult(row.getValue(column.id), isMultiple, entry.id),
+        ),
+        subRows,
+      })
+    }
+
+    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(options?)` and its default cache. */
+export function column_getAggregationValue<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  options?: AggregationValueOptions<TFeatures, TData>,
+): ColumnAggregationValue<TFeatures> {
+  const rows = options?.rows
+  const resolvedMaxDepth = resolveMaxAggregationDepth(
+    options?.maxDepth ?? column.columnDef.maxAggregationDepth,
+  )
+  const providedResult = column.columnDef.getAggregationValue?.({
+    column: column as any,
+    maxDepth: resolvedMaxDepth,
+    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,
+      maxDepth: resolvedMaxDepth,
+      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.maxDepth === resolvedMaxDepth &&
+    previous.registry === registry &&
+    previous.aggregationFnOption === aggregationFnOption
+  ) {
+    return previous.value as any
+  }
+
+  const value = aggregateColumnValue({
+    column: column as any,
+    maxDepth: resolvedMaxDepth,
+    rows: model.rows,
+  })
+  ;(column as any)._aggregationValueCache = {
+    aggregationFnOption,
+    dependency: model,
+    maxDepth: resolvedMaxDepth,
+    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)
+}

package/src/features/row-expanding/rowExpandingFeature.types.ts

@@ -1,4 +1,3 @@
-import type { Table } from '../../types/Table'
 import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
@@ -35,8 +34,8 @@ export interface Row_RowExpanding {
 }
 
 export interface TableOptions_RowExpanding<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Enables automatic expanded-state resets when page-altering table state changes.
@@ -71,8 +70,8 @@ export interface TableOptions_RowExpanding<
 }
 
 export interface Table_RowExpanding<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out _TFeatures extends TableFeatures,
+  in out _TData extends RowData,
 > {
   autoResetExpanded: () => void
   /**
@@ -112,8 +111,8 @@ export interface Table_RowExpanding<
 }
 
 export interface Table_RowModels_Expanded<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Resolves the row model after expanded rows have been flattened into view.
@@ -125,23 +124,9 @@ export interface Table_RowModels_Expanded<
   getPreExpandedRowModel: () => RowModel<TFeatures, TData>
 }
 
-export interface CreateRowModel_Expanded<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> {
-  /**
-   * Factory used to retrieve the expanded row model. If this function is not
-   * provided, the table will not expand rows. To use client-side expansion,
-   * pass `createExpandedRowModel()` or implement your own factory.
-   */
-  expandedRowModel?: (
-    table: Table<TFeatures, TData>,
-  ) => () => RowModel<TFeatures, TData>
-}
-
 export interface CachedRowModel_Expanded<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   expandedRowModel: () => RowModel<TFeatures, TData>
 }

package/src/features/row-expanding/rowExpandingFeature.utils.ts

@@ -1,4 +1,4 @@
-import { cloneState } from '../../utils'
+import { cloneState, hasOwn, makeObjectMap } from '../../utils'
 import type { RowData, Updater } from '../../types/type-utils'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { Table_Internal } from '../../types/Table'
@@ -20,7 +20,7 @@ import type {
  * ```
  */
 export function getDefaultExpandedState(): ExpandedState {
-  return {}
+  return makeObjectMap()
 }
 
 /**
@@ -85,7 +85,7 @@ export function table_toggleAllRowsExpanded<
   if (expanded ?? !table_getIsAllRowsExpanded(table)) {
     table_setExpanded(table, true)
   } else {
-    table_setExpanded(table, {})
+    table_setExpanded(table, makeObjectMap())
   }
 }
 
@@ -105,9 +105,17 @@ export function table_resetExpanded<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  const initialExpanded = table.initialState.expanded
   table_setExpanded(
     table,
-    defaultState ? {} : cloneState(table.initialState.expanded ?? {}),
+    defaultState
+      ? makeObjectMap()
+      : initialExpanded === true
+        ? true
+        : Object.assign(
+            makeObjectMap<boolean | undefined>(),
+            cloneState(initialExpanded ?? {}),
+          ),
   )
 }
 
@@ -252,29 +260,34 @@ export function row_toggleExpanded<
   TData extends RowData,
 >(row: Row<TFeatures, TData>, expanded?: boolean) {
   table_setExpanded(row.table, (old) => {
-    const exists = old === true ? true : !!old[row.id]
+    const exists = old === true ? true : isExpandedRowId(old, row.id)
 
-    let oldExpanded: ExpandedStateList = {}
+    let oldExpanded: ExpandedStateList = makeObjectMap()
 
     if (old === true) {
       Object.keys(row.table.getRowModel().rowsById).forEach((rowId) => {
         oldExpanded[rowId] = true
       })
     } else {
-      oldExpanded = old
+      oldExpanded = Object.assign(makeObjectMap<boolean | undefined>(), old)
     }
 
     expanded = expanded ?? !exists
 
     if (!exists && expanded) {
-      return {
-        ...oldExpanded,
-        [row.id]: true,
-      }
+      oldExpanded[row.id] = true
+      return oldExpanded
     }
 
     if (exists && !expanded) {
-      const { [row.id]: _, ...rest } = oldExpanded
+      const rest: ExpandedStateList = makeObjectMap()
+      const rowIds = Object.keys(oldExpanded)
+      for (let i = 0; i < rowIds.length; i++) {
+        const rowId = rowIds[i]!
+        if (rowId !== row.id && oldExpanded[rowId]) {
+          rest[rowId] = true
+        }
+      }
       return rest
     }
 
@@ -301,7 +314,19 @@ export function row_getIsExpanded<
 
   return !!(
     row.table.options.getIsRowExpanded?.(row) ??
-    (expanded === true || expanded[row.id])
+    (expanded === true || isExpandedRowId(expanded, row.id))
+  )
+}
+
+function isExpandedRowId(
+  expanded: ExpandedState | undefined,
+  rowId: string,
+): boolean {
+  return !!(
+    expanded &&
+    expanded !== true &&
+    hasOwn(expanded, rowId) &&
+    expanded[rowId]
   )
 }
 

package/src/features/row-pagination/createPaginatedRowModel.ts

@@ -25,7 +25,7 @@ export function createPaginatedRowModel<
       memoDeps: () => [
         table.getPrePaginatedRowModel(),
         table.atoms.pagination?.get(),
-        table.options.paginateExpandedRows
+        !table.options.paginateExpandedRows
           ? table.atoms.expanded?.get()
           : undefined,
       ],

package/src/features/row-pagination/rowPaginationFeature.types.ts

@@ -1,5 +1,4 @@
 import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
-import type { Table } from '../../types/Table'
 import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
 import type { TableFeatures } from '../../types/TableFeatures'
 
@@ -42,8 +41,8 @@ export interface PaginationDefaultOptions {
 }
 
 export interface Table_RowPagination<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out _TFeatures extends TableFeatures,
+  in out _TData extends RowData,
 > {
   _autoResetPageIndex: () => void
   /**
@@ -117,8 +116,8 @@ export interface Table_RowPagination<
 }
 
 export interface Table_RowModels_Paginated<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Resolves the row model after pagination has sliced the current page.
@@ -130,23 +129,9 @@ export interface Table_RowModels_Paginated<
   getPrePaginatedRowModel: () => RowModel<TFeatures, TData>
 }
 
-export interface CreateRowModel_Paginated<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> {
-  /**
-   * Factory used to retrieve the paginated row model. If using server-side
-   * pagination, this is not required. To use client-side pagination, pass
-   * `createPaginatedRowModel()` or implement your own factory.
-   */
-  paginatedRowModel?: (
-    table: Table<TFeatures, TData>,
-  ) => () => RowModel<TFeatures, TData>
-}
-
 export interface CachedRowModel_Paginated<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   paginatedRowModel: () => RowModel<TFeatures, TData>
 }

package/src/features/row-pagination/rowPaginationFeature.utils.ts

@@ -46,7 +46,7 @@ export function table_autoResetPageIndex<
     table.options.autoResetPageIndex ??
     !table.options.manualPagination
   ) {
-    table_resetPageIndex(table)
+    table_resetPageIndex(table, true)
   }
 }
 

package/src/features/row-pinning/rowPinningFeature.types.ts

@@ -14,8 +14,8 @@ export interface TableState_RowPinning {
 }
 
 export interface TableOptions_RowPinning<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Allows rows to be pinned to top or bottom regions.
@@ -63,8 +63,8 @@ export interface Row_RowPinning {
 }
 
 export interface Table_RowPinning<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Gets rows pinned to the bottom region.