Capítulo 47 de 54

Chapter 47: Core Table Types

Core Idea

The core exported types (Table, TableOptions, TableState, TableMeta, TableFeature, TableFeatures) are all generic over TFeatures (the object from tableFeatures()) and compose feature-contributed pieces via ExtractFeatureMapTypes — this is the mechanism that makes an unregistered feature's state/options/APIs simply not exist on the type, rather than exist as undefined.

Key Concepts

  • Table<TFeatures, TData>: the full table-instance type — core table functionality intersected with whatever Table_FeatureMap<TFeatures, TData> contributes for each registered feature. This is the type of the object useTable/createTable/constructTable returns (before the React adapter's own Table_Extended additions — see the React Adapter API chapter).
  • TableOptions<TFeatures, TData>: core options intersected with feature-contributed options (TableOptions_FeatureMap) and DebugOptions. Only options for registered features type-check.
  • TableState<TFeatures>: the full state shape, assembled purely from TableState_FeatureMap entries for registered features (no core-only base — every state slice comes from some feature).
  • TableMeta<TFeatures, TData> / ColumnMeta / FilterMeta: the interfaces behind the metaHelper phantom-slot mechanism (see Table and Column Meta Guide) — extend via declaration merging (v8-style) or per-table via tableFeatures({ tableMeta: metaHelper<T>() }) (v9-recommended).
  • TableFeature: the interface every built-in and custom feature object implements — the full lifecycle hook set (getInitialState, getDefaultTableOptions, getDefaultColumnDef, constructTableAPIs, assign*Prototype, init*InstanceData, resetTableInstanceData) covered in depth in the Custom Features Guide.
  • TableFeatures: the type of the object returned by tableFeatures({...}) — a map from feature keys to their TableFeature implementations (plus row-model-factory and function-registry slots), used as the TFeatures generic parameter everywhere else.
  • StockFeatures / CoreFeatures: StockFeatures is the interface describing every optional built-in feature (what stockFeatures the value satisfies — see Features Guide); CoreFeatures describes the always-included core (row/column/cell/header construction) with no opt-in features.
  • BaseAtoms / Atoms / ExternalAtoms: the TanStack Store-backed state layer's type surface — BaseAtoms<TFeatures> are the internal writable atoms, Atoms<TFeatures> the public readonly derived atoms (table.atoms), ExternalAtoms the shape accepted by the atoms table option for externally-owned slices (see Table State Guide).
  • Construction/config functions: constructTable(options) — the framework-agnostic table constructor every adapter's useTable/createTable wraps (needs an explicit coreReactivityFeature outside a framework adapter); tableOptions<TFeatures, TData>(options) — the type-preserving option-composition helper (Helpers Guide); tableFeatures({...}) — declares the feature set (Features Guide); getInitialTableState(features, initialState?) — resolves a table's starting state from registered features + overrides, the same resolution getInitialState hooks feed into.
  • Small option/utility types: OnChangeFn<T> — the shape of every on[State]Change callback ((updater: Updater<T>) => void); Updater<T> — either a raw new value or a function (old: T) => T, the shape every state setter accepts; DebugOptions<TFeatures> — the debugTable/debugHeaders/etc. flags mixed into TableOptions.

Key Takeaways

  1. TFeatures is the generic thread running through every core type — when a type error mentions a missing property, check whether the relevant feature is actually registered in tableFeatures() before assuming a bug.
  2. constructTable is the lowest-level entry point; every framework adapter's useTable/createTable/injectTable is a thin wrapper around it plus a coreReactivityFeature.
  3. OnChangeFn/Updater are the two small generic types worth memorizing — every single state setter in the library (built-in or custom feature) follows this same updater shape.

Connects To

  • Features Guide / Helpers Guide: tableFeatures, tableOptions, stockFeatures in practical use.
  • Table State (React) Guide: BaseAtoms/Atoms/ExternalAtoms in the context of reading/writing state.
  • Custom Features (React) Guide: the full TableFeature hook contract.