@tanstack/table-core 9.0.0-beta.31 → 9.0.0-beta.33

package/src/worker/createWorkerRowModel.ts

@@ -0,0 +1,121 @@
+import { tableMemo } from '../utils'
+import { getTableWorkerBridge, syncTableWorker } from './createTableWorker'
+import { rebuildRowModel } from './rebuildRowModel'
+import { tableWorkerPipeline } from './tableWorkerProtocol'
+import type { RowModel } from '../core/row-models/coreRowModelsFeature.types'
+import type { Table, Table_Internal } from '../types/Table'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { RowData } from '../types/type-utils'
+import type { TableWorker } from './createTableWorker'
+import type { TableWorkerStage } from './tableWorkerProtocol'
+
+type AnyTable = Table_Internal<any, any>
+
+function capitalize(stage: string) {
+  return stage.charAt(0).toUpperCase() + stage.slice(1)
+}
+
+/**
+ * Turns any row model stage into a worker-backed one. The returned factory
+ * plugs into the standard feature slot for that stage, so it composes with
+ * the rest of the pipeline exactly like the sync factory it replaces.
+ *
+ * Register only the stages you want offloaded; each import is independent and
+ * tree-shakable. All stages on a table share one worker and one round trip
+ * per state change via the `tableWorker` handle. Until a result lands, the
+ * stage returns its pre-stage model (stale-while-revalidate).
+ *
+ * Offloaded stages must form a contiguous prefix of the pipeline
+ * (filtered -> grouped -> sorted -> expanded): a stage's worker result encodes
+ * everything upstream as computed in the worker, so any upstream stage
+ * registered on the main thread must be offloaded too. A dev warning fires on
+ * mismatches.
+ *
+ * @example
+ * ```ts
+ * const tableWorker = createTableWorker({ createWorker })
+ *
+ * const features = tableFeatures({
+ *   rowSortingFeature,
+ *   columnGroupingFeature,
+ *   workerRowModelsFeature,
+ *   filteredRowModel: createWorkerRowModel(tableWorker, 'filtered'),
+ *   groupedRowModel: createWorkerRowModel(tableWorker, 'grouped'),
+ *   sortedRowModel: createWorkerRowModel(tableWorker, 'sorted'),
+ * })
+ * ```
+ */
+export function createWorkerRowModel(
+  tableWorker: TableWorker,
+  stage: TableWorkerStage,
+) {
+  return <TFeatures extends TableFeatures, TData extends RowData>(
+    _table: Table<TFeatures, TData>,
+  ): (() => RowModel<TFeatures, TData>) => {
+    const table = _table as unknown as AnyTable
+    // Stages register per table as their factories initialize (first read).
+    // The first render may therefore fire one extra coalesced request while
+    // the stage set grows; single-flight makes it a cheap trailing request.
+    getTableWorkerBridge(tableWorker, table).stages.add(stage)
+    let warned = false
+
+    const warnOnce = (message: string) => {
+      if (process.env.NODE_ENV === 'development' && !warned) {
+        warned = true
+        console.warn(`[table-worker] ${message}`)
+      }
+    }
+
+    const memoized = tableMemo({
+      table,
+      fnName: `table.get${capitalize(stage)}RowModel`,
+      // The per-stage version bumps only when this stage's payload actually
+      // changed, so stages the worker reported as `unchanged` skip the O(n)
+      // rebuild entirely (the re-render itself rides the state slice bump).
+      memoDeps: () => [
+        table.getCoreRowModel(),
+        getTableWorkerBridge(tableWorker, table).stageVersions[stage],
+      ],
+      fn: () => {
+        const bridge = getTableWorkerBridge(tableWorker, table)
+        const payload = bridge.results[stage]
+        if (!payload) {
+          if (bridge.resultRequestId > 0) {
+            warnOnce(
+              `The worker returned no '${stage}' result. Make sure the ` +
+                `worker's initTableWorker() config registers a ` +
+                `${stage}RowModel factory.`,
+            )
+          }
+          return (table as any)[`getPre${capitalize(stage)}RowModel`]()
+        }
+        // Contiguous-prefix check: any upstream stage registered on this
+        // table must also have a worker result, or it is silently bypassed.
+        if (bridge.resultRequestId > 0) {
+          for (const upstream of tableWorkerPipeline) {
+            if (upstream === stage) break
+            if (
+              (table.options.features as Record<string, unknown>)[
+                `${upstream}RowModel`
+              ] &&
+              !bridge.results[upstream]
+            ) {
+              warnOnce(
+                `This table has a ${upstream}RowModel, but the worker result ` +
+                  `for '${stage}' was computed without an offloaded ` +
+                  `'${upstream}' stage, so it is bypassed. Offload it too ` +
+                  `with createWorkerRowModel(tableWorker, '${upstream}').`,
+              )
+            }
+          }
+        }
+        return rebuildRowModel(table, payload, stage !== 'filtered')
+      },
+    })
+
+    return () => {
+      syncTableWorker(tableWorker, table)
+      return memoized()
+    }
+  }
+}

package/src/worker/initTableWorker.ts

@@ -0,0 +1,164 @@
+import { constructTable } from '../core/table/constructTable'
+import { storeReactivityBindings } from '../store-reactivity-bindings'
+import { makeObjectMap } from '../utils'
+import { serializeRowModel } from './serializeRowModel'
+import type { RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { TableOptions } from '../types/TableOptions'
+import type { Table_Internal } from '../types/Table'
+import type {
+  TableWorkerRequest,
+  TableWorkerResult,
+  TableWorkerStage,
+  TableWorkerStagePayload,
+} from './tableWorkerProtocol'
+
+export type TableWorkerConfig<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = Omit<TableOptions<TFeatures, TData>, 'data'>
+
+function capitalize(stage: string) {
+  return stage.charAt(0).toUpperCase() + stage.slice(1)
+}
+
+/** Flatten column-group defs to leaf defs (mirrors core's id resolution). */
+function flattenColumnDefs(defs: Array<any>): Array<any> {
+  return defs.flatMap((def) =>
+    def.columns ? flattenColumnDefs(def.columns) : [def],
+  )
+}
+
+/**
+ * Runs a headless "shadow table" inside a dedicated Web Worker.
+ *
+ * Call this from a user-authored worker entry file, passing the same columns
+ * and processing features used on the main thread. The shadow table runs the
+ * real table-core row model pipeline (real fns, real Row objects) off the
+ * main thread and posts back one payload per stage the main thread requested:
+ * a transferable index permutation for flat results, a serialized row tree
+ * (with eagerly computed aggregates) when grouping produces synthetic rows.
+ *
+ * Everything passed here must be thread-portable: `accessorKey` columns or
+ * accessors defined in a shared module, and fns from registries or shared
+ * modules (no closures over app state).
+ *
+ * @example
+ * ```ts
+ * // table.worker.ts
+ * import { initTableWorker } from '@tanstack/table-core/experimental-worker-plugin'
+ * import { columns, sharedFeatures } from './tableConfig'
+ *
+ * initTableWorker({ features: sharedFeatures, columns })
+ * ```
+ */
+export function initTableWorker<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(config: TableWorkerConfig<TFeatures, TData>): void {
+  let table: Table_Internal<TFeatures, TData> | undefined
+  let dataVersion = 0
+  let coreIndexById: Record<string, number> = makeObjectMap()
+  let aggregateColumnIds: Array<string> = []
+  // Last-sent model identity per stage: the memoized getters return stable
+  // objects when their inputs did not change, so identity equality is exactly
+  // "this stage's result is unchanged".
+  let lastSentModels: { [K in TableWorkerStage]?: unknown } = {}
+
+  self.onmessage = (event: MessageEvent<TableWorkerRequest<TData>>) => {
+    const message = event.data
+
+    if (message.type === 'data') {
+      dataVersion = message.dataVersion
+      lastSentModels = {}
+      if (!table) {
+        table = constructTable<TFeatures, TData>({
+          ...(config as TableOptions<TFeatures, TData>),
+          features: {
+            coreReactivityFeature: storeReactivityBindings(),
+            ...config.features,
+          },
+          data: message.data,
+        }) as unknown as Table_Internal<TFeatures, TData>
+        // Only columns with an explicit aggregation get eagerly aggregated
+        // per group. Sync tables aggregate lazily (visible cells only), so
+        // auto-aggregating every column would explode on high-cardinality
+        // grouping for values nothing renders. Read the RAW column defs:
+        // columnGroupingFeature injects default aggregatedCell/aggregationFn
+        // into every resolved columnDef, so the resolved defs can't tell
+        // explicit from default.
+        aggregateColumnIds = flattenColumnDefs(config.columns as Array<any>)
+          .filter(
+            (def) => def.aggregationFn != null || def.aggregatedCell != null,
+          )
+          .map(
+            (def) =>
+              def.id ??
+              (typeof def.accessorKey === 'string'
+                ? def.accessorKey.replaceAll('.', '_')
+                : undefined),
+          )
+          .filter((id): id is string => id != null)
+      } else {
+        table.setOptions((prev) => ({ ...prev, data: message.data }))
+      }
+      // Map row ids to data positions once per dataset; serialization uses it
+      // to express every stage result in terms of core row positions.
+      const coreFlatRows = table.getCoreRowModel().flatRows
+      coreIndexById = makeObjectMap()
+      for (let i = 0; i < coreFlatRows.length; i++) {
+        coreIndexById[coreFlatRows[i]!.id] = i
+      }
+      return
+    }
+
+    if (!table) return
+
+    const start = performance.now()
+
+    // Apply the serializable state slices to the shadow table's base atoms.
+    table._reactivity.batch(() => {
+      for (const [key, value] of Object.entries(message.state)) {
+        const baseAtom = (table!.baseAtoms as Record<string, any>)[key]
+        if (baseAtom && value !== undefined) {
+          baseAtom.set(value)
+        }
+      }
+    })
+
+    // Compute exactly the stages the main thread requested, skipping any this
+    // shadow table has no row model factory for (the main thread warns).
+    const stages: { [K in TableWorkerStage]?: TableWorkerStagePayload } = {}
+    const transfer: Array<Transferable> = []
+
+    for (const stage of message.stages) {
+      if (!(config.features as Record<string, unknown>)[`${stage}RowModel`]) {
+        continue
+      }
+      const model = (table as any)[`get${capitalize(stage)}RowModel`]()
+      // Memoized getters return the same object when inputs are unchanged;
+      // skip re-serializing (and the main thread skips rebuilding). Safe under
+      // single-flight: results are never dropped within a dataVersion.
+      if (lastSentModels[stage] === model) {
+        stages[stage] = { kind: 'unchanged' }
+        continue
+      }
+      lastSentModels[stage] = model
+      stages[stage] = serializeRowModel(
+        model,
+        coreIndexById,
+        aggregateColumnIds,
+        transfer,
+      )
+    }
+
+    const response: TableWorkerResult = {
+      type: 'result',
+      requestId: message.requestId,
+      dataVersion,
+      stages,
+      computeMs: performance.now() - start,
+    }
+    postMessage(response, { transfer })
+  }
+}

package/src/worker/rebuildRowModel.ts

@@ -0,0 +1,117 @@
+import { constructRow } from '../core/rows/constructRow'
+import { hasOwn } from '../utils'
+import type { RowModel } from '../core/row-models/coreRowModelsFeature.types'
+import type { Table_Internal } from '../types/Table'
+import type {
+  TableWorkerRowNode,
+  TableWorkerStagePayload,
+} from './tableWorkerProtocol'
+
+/** Payloads that carry data; `unchanged` never reaches the rebuilder. */
+export type TableWorkerDataPayload = Exclude<
+  TableWorkerStagePayload,
+  { kind: 'unchanged' }
+>
+
+type AnyTable = Table_Internal<any, any>
+
+// Main-thread side: payload + this table's core rows -> RowModel. Mirrors how
+// the sync row models treat rows: data rows are reused (with depth/parentId
+// rewritten, exactly like createGroupedRowModel does), synthetic group rows
+// are reconstructed via constructRow with their worker-computed aggregates
+// pre-seeded so no aggregation ever runs on the main thread.
+
+function collectLeafRows(subRows: Array<any>, out: Array<any>) {
+  for (let i = 0; i < subRows.length; i++) {
+    const row = subRows[i]
+    if (row.groupingColumnId == null) {
+      out.push(row)
+    } else {
+      collectLeafRows(row.subRows, out)
+    }
+  }
+}
+
+export function rebuildRowModel(
+  table: AnyTable,
+  payload: TableWorkerDataPayload,
+  /**
+   * Whether a flat payload should rewrite row depth/parentId. Mirrors core:
+   * the grouped model's passthrough resets them, the filtered model never
+   * touches them. Without this distinction a filtered rebuild could zero the
+   * depths a grouped/sorted tree rebuild just assigned to shared row objects.
+   */
+  resetDepths: boolean,
+): RowModel<any, any> {
+  const core = table.getCoreRowModel()
+
+  if (payload.kind === 'flat') {
+    const { indices } = payload
+    const rows = new Array(indices.length)
+    for (let i = 0; i < indices.length; i++) {
+      const row: any = core.flatRows[indices[i]!]!
+      if (resetDepths) {
+        row.depth = 0
+        row.parentId = undefined
+      }
+      rows[i] = row
+    }
+    return { rows, flatRows: rows, rowsById: core.rowsById }
+  }
+
+  const flatRows: Array<any> = []
+  // Data rows resolve through the prototype chain to the core map; only
+  // synthetic group rows are added on top.
+  const rowsById: Record<string, any> = Object.create(core.rowsById)
+
+  const rebuildRows = (
+    nodes: Array<TableWorkerRowNode>,
+    depth: number,
+    parentId: string | undefined,
+  ): Array<any> => {
+    const rows = new Array(nodes.length)
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i]!
+      if (typeof node === 'number') {
+        const row: any = core.flatRows[node]!
+        row.depth = depth
+        row.parentId = parentId
+        flatRows.push(row)
+        rows[i] = row
+        continue
+      }
+
+      const subRows = rebuildRows(node.children, depth + 1, node.id)
+      const leafRows: Array<any> = []
+      collectLeafRows(subRows, leafRows)
+
+      const row: any = constructRow(
+        table,
+        node.id,
+        leafRows[0]?.original,
+        node.index,
+        depth,
+        undefined,
+        parentId,
+      )
+      const aggregates = node.aggregates
+      Object.assign(row, {
+        groupingColumnId: node.groupingColumnId,
+        groupingValue: node.groupingValue,
+        subRows,
+        leafRows,
+        getValue: (columnId: string) =>
+          hasOwn(aggregates, columnId) ? aggregates[columnId] : undefined,
+      })
+
+      flatRows.push(row)
+      rowsById[node.id] = row
+      rows[i] = row
+    }
+    return rows
+  }
+
+  const rows = rebuildRows(payload.children, 0, undefined)
+
+  return { rows, flatRows, rowsById }
+}

package/src/worker/serializeRowModel.ts

@@ -0,0 +1,80 @@
+import type { RowModel } from '../core/row-models/coreRowModelsFeature.types'
+import type {
+  TableWorkerRowNode,
+  TableWorkerStagePayload,
+} from './tableWorkerProtocol'
+
+// Worker-side: RowModel -> transferable payload. Stage-agnostic; the payload
+// kind is chosen from the model's shape (synthetic rows present or not).
+
+function isCloneSafe(value: unknown): boolean {
+  return typeof value !== 'function' && typeof value !== 'symbol'
+}
+
+function serializeRows(
+  rows: Array<any>,
+  coreIndexById: Record<string, number>,
+  aggregateColumnIds: Array<string>,
+): Array<TableWorkerRowNode> {
+  const nodes = new Array<TableWorkerRowNode>(rows.length)
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i]
+    if (row.groupingColumnId == null) {
+      // Data row: its position in `options.data` is all the main thread needs.
+      nodes[i] = coreIndexById[row.id]!
+      continue
+    }
+    // Synthetic group row: compute aggregates eagerly (the expensive per-group
+    // work we want off the main thread), but only for columns with an explicit
+    // aggregation; sync tables aggregate lazily, so eagerly auto-aggregating
+    // every column would explode on high-cardinality grouping.
+    const aggregates: Record<string, unknown> = {}
+    for (let c = 0; c < aggregateColumnIds.length; c++) {
+      const columnId = aggregateColumnIds[c]!
+      const value = row.getValue(columnId)
+      if (value !== undefined && isCloneSafe(value)) {
+        aggregates[columnId] = value
+      }
+    }
+    // The group's own column always serializes its display value (the first
+    // leaf's value) so grouped cells render.
+    if (!(row.groupingColumnId in aggregates)) {
+      const value = row.getValue(row.groupingColumnId)
+      if (value !== undefined && isCloneSafe(value)) {
+        aggregates[row.groupingColumnId] = value
+      }
+    }
+    nodes[i] = {
+      id: row.id,
+      groupingColumnId: row.groupingColumnId,
+      groupingValue: row.groupingValue,
+      index: row.index,
+      aggregates,
+      children: serializeRows(row.subRows, coreIndexById, aggregateColumnIds),
+    }
+  }
+  return nodes
+}
+
+export function serializeRowModel(
+  model: RowModel<any, any>,
+  coreIndexById: Record<string, number>,
+  aggregateColumnIds: Array<string>,
+  transfer: Array<Transferable>,
+): TableWorkerStagePayload {
+  // Flat fast path: no synthetic rows anywhere (flatRows === rows for flat
+  // data). A Uint32Array permutation transfers at zero-copy cost.
+  if (model.flatRows.length === model.rows.length) {
+    const indices = new Uint32Array(model.rows.length)
+    for (let i = 0; i < indices.length; i++) {
+      indices[i] = coreIndexById[model.rows[i]!.id]!
+    }
+    transfer.push(indices.buffer)
+    return { kind: 'flat', indices }
+  }
+
+  return {
+    kind: 'tree',
+    children: serializeRows(model.rows, coreIndexById, aggregateColumnIds),
+  }
+}

package/src/worker/tableWorkerProtocol.ts

@@ -0,0 +1,105 @@
+import type { RowData } from '../types/type-utils'
+
+/**
+ * Row model stages that can be offloaded to the worker, in pipeline order.
+ * Everything else in this module is derived from this list; adding a stage
+ * means adding an entry here and to `tableWorkerStageStateDeps`.
+ */
+export const tableWorkerPipeline = [
+  'filtered',
+  'grouped',
+  'sorted',
+  'expanded',
+] as const
+
+export type TableWorkerStage = (typeof tableWorkerPipeline)[number]
+
+/**
+ * The state slices each stage's computation depends on. The main thread sends
+ * the union of deps for its registered stages; a change to any of them
+ * triggers one worker round trip.
+ */
+export const tableWorkerStageStateDeps: Record<
+  TableWorkerStage,
+  Array<string>
+> = {
+  filtered: ['columnFilters', 'globalFilter'],
+  grouped: ['grouping'],
+  sorted: ['sorting'],
+  expanded: ['expanded'],
+}
+
+/**
+ * A serialized synthetic (group) row. Leaf rows serialize as their position in
+ * `options.data`; group rows carry what `constructRow` + the grouped row model
+ * need to rebuild them, plus eagerly computed aggregate values so no
+ * aggregation runs on the main thread.
+ */
+export interface TableWorkerGroupNode {
+  id: string
+  groupingColumnId: string
+  groupingValue: unknown
+  index: number
+  aggregates: Record<string, unknown>
+  children: Array<TableWorkerRowNode>
+}
+
+export type TableWorkerRowNode = number | TableWorkerGroupNode
+
+/**
+ * A stage result. Flat models (every row is a data row) travel as a
+ * transferable index permutation; models containing synthetic rows (grouping)
+ * travel as a tree. The kind is chosen from the model's actual shape at
+ * runtime, not from the stage name: a sorted model is flat without grouping
+ * and a tree with it.
+ *
+ * `unchanged` means the stage's model is identical to the last one sent for
+ * this dataset (its memoized inputs did not change); the main thread keeps
+ * its previous result and skips the rebuild entirely.
+ */
+export type TableWorkerStagePayload =
+  | { kind: 'flat'; indices: Uint32Array }
+  | { kind: 'tree'; children: Array<TableWorkerRowNode> }
+  | { kind: 'unchanged' }
+
+export type TableWorkerRequest<TData extends RowData = any> =
+  | {
+      type: 'data'
+      dataVersion: number
+      data: Array<TData>
+    }
+  | {
+      type: 'process'
+      requestId: number
+      dataVersion: number
+      /** The stages the main thread has worker-backed row models for. */
+      stages: Array<TableWorkerStage>
+      /** Serializable state slices (union of the stages' deps). */
+      state: Record<string, unknown>
+    }
+
+export interface TableWorkerResult {
+  type: 'result'
+  requestId: number
+  dataVersion: number
+  stages: { [K in TableWorkerStage]?: TableWorkerStagePayload }
+  computeMs: number
+}
+
+export type TableWorkerResponse = TableWorkerResult
+
+/**
+ * The state slice added by `workerRowModelsFeature`. `version` bumps when a
+ * worker result lands (driving re-renders through the normal state path);
+ * `isPending` is true while a request is in flight. The timing fields expose
+ * the last result's worker compute time and full round trip for devtools and
+ * debugging.
+ */
+export interface TableState_WorkerRowModels {
+  workerRowModels: {
+    version: number
+    isPending: boolean
+    lastComputeMs?: number
+    lastRoundTripMs?: number
+  }
+}