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

package/src/core/rows/coreRowsFeature.utils.ts

@@ -1,10 +1,68 @@
-import { flattenBy } from '../../utils'
+import { flattenBy, hasOwn, makeObjectMap } from '../../utils'
 import { constructCell } from '../cells/constructCell'
 import type { Table_Internal } from '../../types/Table'
 import type { RowData } from '../../types/type-utils'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { Row } from '../../types/Row'
 import type { Cell } from '../../types/Cell'
+import type { Row_RowExpanding } from '../../features/row-expanding/rowExpandingFeature.types'
+
+/**
+ * Returns this row's zero-based position in the current pre-pagination row
+ * model. Rows outside that model return `-1`.
+ */
+export function row_getDisplayIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  const rows = row.table.getRowsInDisplayOrder()
+  const displayIndex = row._displayIndexCache
+
+  return rows[displayIndex] === row ? displayIndex : -1
+}
+
+/**
+ * Returns the rows in the current display order after assigning their
+ * zero-based display indexes.
+ *
+ * When expanded rows bypass pagination, expanded descendants are inserted into
+ * the returned order even though they are absent from the pre-pagination row
+ * model.
+ */
+export function table_getRowsInDisplayOrder<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const rows = table.getPrePaginatedRowModel().rows
+
+  if (table.options.paginateExpandedRows === false) {
+    const displayRows: Array<Row<TFeatures, TData>> = []
+
+    const handleRow = (row: Row<TFeatures, TData>) => {
+      row._displayIndexCache = displayRows.length
+      displayRows.push(row)
+
+      if (
+        row.subRows.length &&
+        (
+          row as Row<TFeatures, TData> & Partial<Row_RowExpanding>
+        ).getIsExpanded?.()
+      ) {
+        row.subRows.forEach(handleRow)
+      }
+    }
+
+    rows.forEach(handleRow)
+
+    return displayRows
+  }
+
+  for (let i = 0; i < rows.length; i++) {
+    rows[i]!._displayIndexCache = i
+  }
+
+  return rows
+}
 
 /**
  * Reads and caches this row's value for a column.
@@ -21,7 +79,7 @@ export function row_getValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(row: Row<TFeatures, TData>, columnId: string) {
-  if (row._valuesCache.hasOwnProperty(columnId)) {
+  if (hasOwn(row._valuesCache, columnId)) {
     return row._valuesCache[columnId]
   }
 
@@ -51,7 +109,7 @@ export function row_getUniqueValues<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(row: Row<TFeatures, TData>, columnId: string) {
-  if (row._uniqueValuesCache.hasOwnProperty(columnId)) {
+  if (hasOwn(row._uniqueValuesCache, columnId)) {
     return row._uniqueValuesCache[columnId]
   }
 
@@ -109,6 +167,24 @@ export function row_getLeafRows<
   return flattenBy(row.subRows, (d) => d.subRows)
 }
 
+/**
+ * Returns the deepest structural row depth in the core row model.
+ * Root rows are depth `0`, their direct sub-rows are depth `1`, and so on.
+ */
+export function table_getMaxSubRowDepth<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): number {
+  const rows = table.getCoreRowModel().flatRows
+  let maxDepth = 0
+
+  for (let i = 0; i < rows.length; i++) {
+    maxDepth = Math.max(maxDepth, rows[i]!.depth)
+  }
+
+  return maxDepth
+}
+
 /**
  * Looks up this row's direct parent, if it has one.
  *
@@ -169,11 +245,23 @@ export function row_getAllCells<
   TData extends RowData,
 >(row: Row<TFeatures, TData>): Array<Cell<TFeatures, TData, unknown>> {
   const columns = row.table.getAllLeafColumns()
+  // WeakMap so cells keyed by replaced column instances can be collected;
+  // rows are memoized on data only and outlive column generations
+  let cache = row._cellsCache
+  if (!cache) {
+    cache = row._cellsCache = new WeakMap()
+  }
   const cells: Array<Cell<TFeatures, TData, unknown>> = new Array(
     columns.length,
   )
   for (let i = 0; i < columns.length; i++) {
-    cells[i] = constructCell(columns[i]!, row, row.table)
+    const column = columns[i]!
+    let cell = cache.get(column)
+    if (!cell) {
+      cell = constructCell(column, row, row.table)
+      cache.set(column, cell)
+    }
+    cells[i] = cell
   }
   return cells
 }
@@ -192,7 +280,7 @@ export function row_getAllCellsByColumnId<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(row: Row<TFeatures, TData>) {
-  const result: Record<string, Cell<TFeatures, TData, unknown>> = {}
+  const result = makeObjectMap<Cell<TFeatures, TData, unknown>>()
   const cells = row.getAllCells()
   for (let i = 0; i < cells.length; i++) {
     const cell = cells[i]!

package/src/core/table/constructTable.ts

@@ -33,16 +33,38 @@ export function constructTable<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(tableOptions: TableOptions<TFeatures, TData>): Table<TFeatures, TData> {
-  const _reactivity = tableOptions.features.coreReativityFeature!
+  const _reactivity = tableOptions.features.coreReactivityFeature!
+
+  // Strip the non-feature slots: type-only meta slots, row model factories,
+  // and row model fn registries all live on the `features` option but are not
+  // table features themselves.
+  const {
+    aggregationFns,
+    columnMeta: _columnMeta,
+    coreRowModel,
+    expandedRowModel,
+    facetedMinMaxValues,
+    facetedRowModel,
+    facetedUniqueValues,
+    filterFns,
+    filterMeta: _filterMeta,
+    filteredRowModel,
+    groupedRowModel,
+    paginatedRowModel,
+    sortFns,
+    sortedRowModel,
+    tableMeta: _tableMeta,
+    ...features
+  } = tableOptions.features
 
   const table = {
     _reactivity,
-    _features: { ...coreFeatures, ...tableOptions.features },
+    _features: { ...coreFeatures, ...features },
     _rowModels: {},
-    _rowModelFns: {},
+    _rowModelFns: { aggregationFns, filterFns, sortFns },
     baseAtoms: {},
     atoms: {},
-  } as Table_Internal<TFeatures, TData>
+  } as unknown as Table_Internal<TFeatures, TData>
 
   const featuresList: Array<TableFeature> = Object.values(table._features)
 
@@ -144,12 +166,28 @@ export function constructTable<
     ),
   )
 
+  for (let i = 0; i < featuresList.length; i++) {
+    featuresList[i]!.initTableInstanceData?.(table)
+  }
+
   if (
     process.env.NODE_ENV === 'development' &&
     (tableOptions.debugAll || tableOptions.debugTable)
   ) {
     const features = Object.keys(table._features)
-    const rowModels = Object.keys(table.options.rowModels || {})
+    const rowModels = Object.entries({
+      coreRowModel,
+      filteredRowModel,
+      groupedRowModel,
+      sortedRowModel,
+      expandedRowModel,
+      paginatedRowModel,
+      facetedRowModel,
+      facetedMinMaxValues,
+      facetedUniqueValues,
+    })
+      .filter(([, factory]) => factory)
+      .map(([key]) => key)
     const states = Object.keys(table.initialState)
 
     console.log(
@@ -168,5 +206,5 @@ export function constructTable<
     featuresList[i]!.constructTableAPIs?.(table)
   }
 
-  return table
+  return table as unknown as Table<TFeatures, TData>
 }

package/src/core/table/coreTablesFeature.types.ts

@@ -3,15 +3,38 @@ import type { Atom, ReadonlyAtom, ReadonlyStore } from '@tanstack/store'
 import type { CoreFeatures } from '../coreFeatures'
 import type { RowModelFns } from '../../types/RowModelFns'
 import type { RowData, Updater } from '../../types/type-utils'
-import type { TableFeatures } from '../../types/TableFeatures'
-import type { CachedRowModels, CreateRowModels_All } from '../../types/RowModel'
+import type {
+  IsAny,
+  TableFeatures,
+  ValidateFeatureSlots,
+} from '../../types/TableFeatures'
+import type { CachedRowModels } from '../../types/RowModel'
 import type { TableOptions } from '../../types/TableOptions'
 import type { TableState, TableState_All } from '../../types/TableState'
 
+// @ts-expect-error Phantom type params: unused in this empty base declaration, but required with these exact names so user `declare module` augmentations merge correctly.
 export interface TableMeta<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> {}
+
+/**
+ * Resolves the type of `options.meta` for a feature set.
+ *
+ * When the features object declares a `tableMeta` type-only slot
+ * (`tableFeatures({ ..., tableMeta: {} as MyTableMeta })`), that type wins.
+ * Otherwise this falls back to the global declaration-merged `TableMeta`
+ * interface.
+ */
+export type ExtractTableMeta<
   TFeatures extends TableFeatures,
   TData extends RowData,
-> {}
+> =
+  IsAny<TFeatures> extends true
+    ? TableMeta<TFeatures, TData>
+    : TFeatures extends { tableMeta: infer TMeta extends object }
+      ? TMeta
+      : TableMeta<TFeatures, TData>
 
 /**
  * A map of writable atoms, one per `TableState` slice. These are the internal
@@ -52,31 +75,29 @@ export type ExternalAtoms<TFeatures extends TableFeatures> = Partial<{
  * use optional chaining (`table.atoms.columnPinning?.get() ?? default`).
  */
 export type BaseAtoms_All = {
-  [K in keyof TableState_All]?: Atom<TableState_All[K]>
+  [K in keyof TableState_All]?: Atom<Exclude<TableState_All[K], undefined>>
 }
 export type Atoms_All = {
   [K in keyof TableState_All]?: ReadonlyAtom<TableState_All[K]>
 }
 export type ExternalAtoms_All = Partial<{
-  [K in keyof TableState_All]: Atom<TableState_All[K]>
+  [K in keyof TableState_All]: Atom<Exclude<TableState_All[K], undefined>>
 }>
 
 export interface TableOptions_Table<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * The feature modules registered on this table instance.
    *
    * Feature registration controls which state slices, options, and prototype
-   * APIs are available.
+   * APIs are available. This object also carries the table's row model
+   * factories (`sortedRowModel`, `filteredRowModel`, etc.), row model function
+   * registries (`sortFns`, `filterFns`, `aggregationFns`), and type-only meta
+   * slots (`tableMeta`, `columnMeta`).
    */
-  readonly features: TFeatures
-  /**
-   * Row model factories used by features such as filtering, grouping, sorting,
-   * expansion, and pagination.
-   */
-  readonly rowModels?: CreateRowModels_All<TFeatures, TData>
+  readonly features: TFeatures & ValidateFeatureSlots<TFeatures>
   /**
    * Optionally, provide your own external writable atoms for individual state slices.
    * When an atom is provided for a given slice, it takes precedence over `options.state[key]`
@@ -116,8 +137,11 @@ export interface TableOptions_Table<
   ) => TableOptions<TFeatures, TData>
   /**
    * You can pass any object to `options.meta` and access it anywhere the `table` is available via `table.options.meta`.
+   *
+   * Declare its type per-table via the `tableMeta` type-only slot on the
+   * `features` option, or globally via declaration merging on `TableMeta`.
    */
-  readonly meta?: TableMeta<TFeatures, TData>
+  readonly meta?: ExtractTableMeta<TFeatures, TData>
   /**
    * Optionally provide externally managed values for individual state slices.
    *
@@ -129,8 +153,8 @@ export interface TableOptions_Table<
 }
 
 export interface Table_CoreProperties<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Table reactivity bindings for interacting with TanStack Store.
@@ -197,15 +221,16 @@ export interface Table_CoreProperties<
 }
 
 export interface Table_Table<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > extends Table_CoreProperties<TFeatures, TData> {
   /**
    * Resets the table's internal base atoms to `table.initialState`.
    *
    * Prefer feature-specific reset APIs, such as `resetPagination`, when a state
    * slice may be owned by an external atom or needs that feature's blank/default
-   * reset behavior.
+   * reset behavior. After resetting internal atoms, this also invokes feature
+   * reset hooks for mutable, transient table-instance data.
    */
   reset: () => void
   /**

package/src/core/table/coreTablesFeature.utils.ts

@@ -32,7 +32,7 @@ export function table_syncExternalStateToBaseAtoms<
       }
 
       const externalState = state[key as keyof typeof state]
-      if (externalState !== baseAtom.get()) {
+      if (externalState !== table._reactivity.untrack(() => baseAtom.get())) {
         baseAtom.set(() => externalState)
       }
     }
@@ -40,7 +40,8 @@ export function table_syncExternalStateToBaseAtoms<
 }
 
 /**
- * Resets all internal table base atoms to `table.initialState`.
+ * Resets all internal table base atoms to `table.initialState`, then clears
+ * transient instance data through registered feature reset hooks.
  *
  * This resets internally owned state slices in a single reactivity batch. Use
  * feature-specific reset APIs when a slice may be externally owned.
@@ -62,13 +63,20 @@ export function table_reset<
       ;(table.baseAtoms as any)[key].set(snap[key])
     }
   })
+
+  const features = Object.values(table._features)
+  for (let i = 0; i < features.length; i++) {
+    features[i]!.resetTableInstanceData?.(table)
+  }
 }
 
 /**
  * Merges new table options with the current resolved options.
  *
  * If `options.mergeOptions` is provided, it owns the merge behavior; otherwise
- * options are shallow-merged.
+ * options are shallow-merged. Static options that should never change after
+ * initialization are restored on a fresh object so framework merge helpers may
+ * return readonly getter/proxy objects.
  *
  * @example
  * ```ts
@@ -82,14 +90,52 @@ export function table_mergeOptions<
   table: Table_Internal<TFeatures, TData>,
   newOptions: TableOptions<TFeatures, TData>,
 ) {
-  if (table.options.mergeOptions) {
-    return table.options.mergeOptions(table.options, newOptions)
+  const { features, atoms, initialState } = table.options
+
+  // simple merge if no mergeOptions is provided - performant
+  if (!table.options.mergeOptions) {
+    return {
+      ...table.options,
+      ...newOptions,
+      features,
+      atoms,
+      initialState,
+    }
   }
 
-  return {
-    ...table.options,
-    ...newOptions,
+  // else use the mergeOptions function and preserve getters/setters
+  const mergedOptions = table.options.mergeOptions(
+    table.options as TableOptions<TFeatures, TData>,
+    newOptions,
+  )
+  const descriptors: PropertyDescriptorMap = {
+    ...Object.getOwnPropertyDescriptors(mergedOptions),
   }
+
+  return Object.defineProperties(
+    Object.create(Object.getPrototypeOf(mergedOptions)),
+    {
+      ...descriptors,
+      features: {
+        value: features,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      },
+      atoms: {
+        value: atoms,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      },
+      initialState: {
+        value: initialState,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      },
+    },
+  ) as TableOptions<TFeatures, TData>
 }
 
 /**
@@ -110,17 +156,11 @@ export function table_setOptions<
   table: Table_Internal<TFeatures, TData>,
   updater: Updater<TableOptions<TFeatures, TData>>,
 ): void {
-  const newOptions = functionalUpdate(updater, table.options)
-  // table static options that should never change after initialization
-  const { rowModels, features, atoms, initialState } = table.options
-  const mergedOptions = Object.assign(table_mergeOptions(table, newOptions), {
-    // Once the table instance is created those properties should never change after initialization,
-    // so we assign them back preserving the `table_mergeOptions` object reference
-    rowModels,
-    features,
-    atoms,
-    initialState,
-  })
+  const newOptions = functionalUpdate(
+    updater,
+    table.options as TableOptions<TFeatures, TData>,
+  )
+  const mergedOptions = table_mergeOptions(table, newOptions)
 
   if (table.optionsStore) {
     table.optionsStore.set(() => mergedOptions)

package/src/experimental-worker-plugin.ts

@@ -0,0 +1,22 @@
+/**
+ * Web Worker row models sub-entry (experimental POC).
+ *
+ * Offloads row model stages to a dedicated worker running a headless "shadow
+ * table" built with the same table-core row model pipeline. The main thread
+ * receives transferable index permutations and rebuilds its row models from
+ * them, stale-while-revalidate style.
+ *
+ * Main thread:
+ * - `createTableWorker` — one shared handle per table worker
+ * - `createWorkerRowModel` — turns any flat row model stage into a
+ *   worker-backed factory for the matching `features` slot
+ * - `workerRowModelsFeature` — registers the `workerRowModels` state slice
+ *
+ * Worker entry (user-authored file):
+ * - `initTableWorker` — runs the shadow table; computes only the stages whose
+ *   row model factories are registered in its config
+ */
+export * from './worker/tableWorkerProtocol'
+export * from './worker/initTableWorker'
+export * from './worker/createTableWorker'
+export * from './worker/createWorkerRowModel'

package/src/features/column-faceting/columnFacetingFeature.types.ts

@@ -1,11 +1,10 @@
-import type { Table } from '../../types/Table'
 import type { RowData } from '../../types/type-utils'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
 
 export interface Column_ColumnFaceting<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Computes min/max numeric facet values for this column.
@@ -25,74 +24,44 @@ export interface Column_ColumnFaceting<
 }
 
 export interface Table_RowModels_Faceted<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Computes min/max numeric facet values for the active faceting context.
    *
-   * Requires a `facetedMinMaxValues` row-model factory in `rowModels`.
+   * Requires a `facetedMinMaxValues` row-model factory on the `features` option.
    */
   getFacetedMinMaxValues: () => undefined | [number, number]
   /**
    * Computes the row model used to derive facet values.
    *
-   * Requires a `facetedRowModel` row-model factory in `rowModels`.
+   * Requires a `facetedRowModel` row-model factory on the `features` option.
    */
   getFacetedRowModel: () => RowModel<TFeatures, TData>
   /**
    * Computes unique facet values and occurrence counts.
    *
-   * Requires a `facetedUniqueValues` row-model factory in `rowModels`.
+   * Requires a `facetedUniqueValues` row-model factory on the `features` option.
    */
   getFacetedUniqueValues: () => Map<any, number>
 }
 
-export interface CreateRowModel_Faceted<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-> {
-  /**
-   * Factory used to retrieve faceted min/max values. If using server-side
-   * faceting, this is not required. To use client-side faceting, pass
-   * `createFacetedMinMaxValues()` or implement your own factory.
-   */
-  facetedMinMaxValues?: (
-    table: Table<TFeatures, TData>,
-    columnId: string,
-  ) => () => [number, number] | undefined
-  /**
-   * Factory used to retrieve the faceted row model. If using server-side
-   * faceting, this is not required. To use client-side faceting, pass
-   * `createFacetedRowModel()` or implement your own factory.
-   */
-  facetedRowModel?: (
-    table: Table<TFeatures, TData>,
-    columnId: string,
-  ) => () => RowModel<TFeatures, TData>
-  /**
-   * Factory used to retrieve faceted unique values. If using server-side
-   * faceting, this is not required. To use client-side faceting, pass
-   * `createFacetedUniqueValues()` or implement your own factory.
-   */
-  facetedUniqueValues?: (
-    table: Table<TFeatures, TData>,
-    columnId: string,
-  ) => () => Map<any, number>
-}
-
 export interface CachedRowModel_Faceted<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
-  facetedRowModel?: (columnId: string) => () => RowModel<TFeatures, TData>
-  facetedMinMaxValues?: (columnId: string) => [number, number]
-  facetedUniqueValues?: (columnId: string) => Map<any, number>
+  facetedRowModels?: Record<string, () => RowModel<TFeatures, TData>>
+  facetedMinMaxValues?: Record<string, () => undefined | [number, number]>
+  facetedUniqueValues?: Record<string, () => Map<any, number>>
+  globalFacetedRowModel?: () => RowModel<TFeatures, TData>
+  globalFacetedMinMaxValues?: () => undefined | [number, number]
+  globalFacetedUniqueValues?: () => Map<any, number>
 }
 
 export interface Table_ColumnFaceting<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
 > {
   /**
    * Returns the min and max values for the global filter.