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

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