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

package/src/features/row-sorting/createSortedRowModel.ts

@@ -1,4 +1,4 @@
-import { tableMemo } from '../../utils'
+import { copyInstancePropertiesWithoutMemos, tableMemo } from '../../utils'
 import { table_autoResetPageIndex } from '../row-pagination/rowPaginationFeature.utils'
 import { column_getCanSort, column_getSortFn } from './rowSortingFeature.utils'
 import type { Column_Internal } from '../../types/Column'
@@ -56,6 +56,10 @@ function _createSortedRowModel<
     return column ? column_getCanSort(column) : false
   })
 
+  if (!availableSorting.length) {
+    return preSortedRowModel
+  }
+
   const resolvedSorting: Array<{
     id: string
     desc?: boolean
@@ -132,32 +136,49 @@ function _createSortedRowModel<
     return rowA.index - rowB.index
   }
 
-  const sortData = (rows: Array<Row<TFeatures, TData>>) => {
+  const sortData = (
+    rows: Array<Row<TFeatures, TData>>,
+  ): {
+    rows: Array<Row<TFeatures, TData>>
+    changed: boolean
+  } => {
     const sortedData = rows.slice()
 
     sortedData.sort(compareRows)
+    let changed = false
 
     // If there are sub-rows, sort them. Clone only rows that need mutation
     // (i.e. have subRows) so we don't corrupt the source row model.
     for (let i = 0; i < sortedData.length; i++) {
       const row = sortedData[i]!
+      if (row !== rows[i]) {
+        changed = true
+      }
+
       if (row.subRows.length) {
-        // Preserve prototype chain so methods like getValue() remain accessible
-        const cloned = Object.create(Object.getPrototypeOf(row))
-        Object.assign(cloned, row)
-        cloned.subRows = sortData(row.subRows)
-        sortedData[i] = cloned
-        sortedFlatRows.push(cloned)
+        const sortedSubRows = sortData(row.subRows)
+
+        if (sortedSubRows.changed) {
+          // Preserve prototype chain so methods like getValue() remain accessible
+          const cloned = Object.create(Object.getPrototypeOf(row))
+          copyInstancePropertiesWithoutMemos(cloned, row)
+          cloned.subRows = sortedSubRows.rows
+          sortedData[i] = cloned
+          sortedFlatRows.push(cloned)
+          changed = true
+        } else {
+          sortedFlatRows.push(row)
+        }
       } else {
         sortedFlatRows.push(row)
       }
     }
 
-    return sortedData
+    return { rows: sortedData, changed }
   }
 
   return {
-    rows: sortData(preSortedRowModel.rows),
+    rows: sortData(preSortedRowModel.rows).rows,
     flatRows: sortedFlatRows,
     rowsById: preSortedRowModel.rowsById,
   }

package/src/features/row-sorting/rowSortingFeature.utils.ts

@@ -195,23 +195,15 @@ export function column_toggleSorting<
   desc?: boolean,
   multi?: boolean,
 ) {
-  // if (column.columns.length) {
-  //   column.columns.forEach((c, i) => {
-  //     if (c.id) {
-  //       table.toggleColumnSorting(c.id, undefined, multi || !!i)
-  //     }
-  //   })
-  //   return
-  // }
-
   // this needs to be outside of table.setSorting to be in sync with rerender
   const nextSortingOrder = column_getNextSortingOrder(column)
   const hasManualValue = typeof desc !== 'undefined'
 
   table_setSorting(column.table, (old) => {
     // Find any existing sorting for this column
-    const existingSorting = old.find((d) => d.id === column.id)
     const existingIndex = old.findIndex((d) => d.id === column.id)
+    const existingSorting =
+      existingIndex === -1 ? undefined : old[existingIndex]
 
     let newSorting: SortingState = []
 

package/src/utils.ts

@@ -50,6 +50,27 @@ export function cloneState<T>(value: T): T {
   return value
 }
 
+/**
+ * Copies prototype-instance own properties without carrying over lazy memo
+ * closures that were bound to the source instance.
+ */
+export function copyInstancePropertiesWithoutMemos<
+  TTarget extends Record<string, any>,
+  TSource extends Record<string, any>,
+>(target: TTarget, source: TSource): TTarget & TSource {
+  const keys = Object.keys(source)
+  const targetRecord = target as Record<string, any>
+
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]!
+    if (!key.startsWith('_memo_')) {
+      targetRecord[key] = source[key]
+    }
+  }
+
+  return target as TTarget & TSource
+}
+
 /**
  * Creates an object intended only for string-keyed dictionary lookups.
  *

package/src/worker/createTableWorker.ts

@@ -0,0 +1,357 @@
+import { table_autoResetPageIndex } from '../features/row-pagination/rowPaginationFeature.utils'
+import { table_autoResetExpanded } from '../features/row-expanding/rowExpandingFeature.utils'
+import {
+  tableWorkerPipeline,
+  tableWorkerStageStateDeps,
+} from './tableWorkerProtocol'
+import type { Table_Internal } from '../types/Table'
+import type { TableFeature } from '../types/TableFeatures'
+import type { TableWorkerDataPayload } from './rebuildRowModel'
+import type {
+  TableState_WorkerRowModels,
+  TableWorkerResponse,
+  TableWorkerStage,
+  TableWorkerStagePayload,
+} from './tableWorkerProtocol'
+
+// Importing anything from this module (e.g. `workerRowModelsFeature`)
+// registers the plugin key and its state slice with the core type maps, so
+// userland needs no `declare module` of its own. Apps that never use worker
+// row models never load this module and never see the types.
+declare module '../types/TableFeatures' {
+  interface Plugins {
+    workerRowModelsFeature: TableFeature
+  }
+}
+declare module '../types/TableState' {
+  interface TableState_FeatureMap {
+    workerRowModelsFeature: TableState_WorkerRowModels
+  }
+}
+
+export interface TableWorkerOptions {
+  /**
+   * Creates the dedicated worker that runs the shadow table. The worker entry
+   * must call `initTableWorker` with the same columns and processing config.
+   *
+   * The `new Worker(new URL(...))` expression must live in your code (not the
+   * library) so your bundler can statically discover and bundle the worker
+   * entry file.
+   *
+   * @example
+   * ```ts
+   * createWorker: () =>
+   *   new Worker(new URL('./table.worker.ts', import.meta.url), {
+   *     type: 'module',
+   *   })
+   * ```
+   */
+  createWorker: () => Worker
+}
+
+export interface TableWorkerBridge {
+  worker: Worker | null
+  /** The worker errored (load failure or uncaught throw); stop posting. */
+  failed: boolean
+  lastData: unknown
+  dataVersion: number
+  requestId: number
+  resultRequestId: number
+  /** A process request has been posted and its result has not arrived yet. */
+  inFlight: boolean
+  /** State changed since the last posted request; post when possible. */
+  needsProcess: boolean
+  sentAt: number
+  /** The stages registered on this table (grows as factories initialize). */
+  stages: Set<TableWorkerStage>
+  /** Snapshot of state refs + stage count captured at the last post. */
+  sentState: Record<string, unknown> | null
+  sentStageCount: number
+  /** Latest observed state refs, posted on the trailing edge if in flight. */
+  lastState: Record<string, unknown>
+  results: { [K in TableWorkerStage]?: TableWorkerDataPayload }
+  /** Bumped per stage only when that stage's payload actually changed. */
+  stageVersions: { [K in TableWorkerStage]?: number }
+}
+
+type AnyTable = Table_Internal<any, any>
+
+/**
+ * A handle shared by every worker-backed row model on a table. It owns the
+ * worker instance and the per-table request/result bookkeeping, so registering
+ * one stage or four costs exactly one worker and one round trip per change.
+ */
+export interface TableWorker {
+  _options: TableWorkerOptions
+  _bridges: WeakMap<object, TableWorkerBridge>
+  _liveBridges: Set<TableWorkerBridge>
+  /**
+   * Terminates every worker created through this handle and resets the
+   * bookkeeping. Safe to call at any time: the next row model read lazily
+   * recreates the worker and re-sends the data (self-healing). Note that
+   * nothing calls this automatically yet; React StrictMode double-mounts and
+   * HMR updates still leak a worker in development until the reactivity
+   * bindings grow a real `unmount` hook.
+   */
+  terminate: () => void
+}
+
+/**
+ * Registers the `workerRowModels` state slice
+ * (`{ version, isPending, lastComputeMs, lastRoundTripMs }`). Worker results
+ * land by bumping `version`, so re-renders flow through the exact same state
+ * mechanism as every other table state change.
+ */
+export const workerRowModelsFeature: TableFeature = {
+  getInitialState: (initialState: any) => ({
+    workerRowModels: { version: 0, isPending: false },
+    ...initialState,
+  }),
+}
+
+/**
+ * Creates the shared worker handle for a table's worker-backed row models.
+ * Pass it to `createWorkerRowModel()` once per stage you want offloaded.
+ */
+export function createTableWorker(options: TableWorkerOptions): TableWorker {
+  const liveBridges = new Set<TableWorkerBridge>()
+  return {
+    _options: options,
+    _bridges: new WeakMap(),
+    _liveBridges: liveBridges,
+    terminate: () => {
+      for (const bridge of liveBridges) {
+        bridge.worker?.terminate()
+        bridge.worker = null
+        bridge.failed = false
+        bridge.lastData = undefined
+        bridge.inFlight = false
+        bridge.needsProcess = true
+        bridge.sentState = null
+        bridge.sentStageCount = 0
+      }
+      liveBridges.clear()
+    },
+  }
+}
+
+export function getTableWorkerBridge(
+  tableWorker: TableWorker,
+  table: AnyTable,
+): TableWorkerBridge {
+  let bridge = tableWorker._bridges.get(table)
+  if (!bridge) {
+    bridge = {
+      worker: null,
+      failed: false,
+      lastData: undefined,
+      dataVersion: 0,
+      requestId: 0,
+      resultRequestId: 0,
+      inFlight: false,
+      needsProcess: true,
+      sentAt: 0,
+      stages: new Set(),
+      sentState: null,
+      sentStageCount: 0,
+      lastState: {},
+      results: {},
+      stageVersions: {},
+    }
+    tableWorker._bridges.set(table, bridge)
+  }
+  return bridge
+}
+
+/** Shallow reference comparison; atoms return stable refs when unchanged. */
+function statesEqual(
+  a: Record<string, unknown> | null,
+  b: Record<string, unknown>,
+): boolean {
+  if (a === null) return false
+  const aKeys = Object.keys(a)
+  const bKeys = Object.keys(b)
+  if (aKeys.length !== bKeys.length) return false
+  for (const key of bKeys) {
+    if (a[key] !== b[key]) return false
+  }
+  return true
+}
+
+function setWorkerRowModelsState(
+  table: AnyTable,
+  update: (prev: any) => Record<string, unknown>,
+) {
+  const stateAtom = (table.baseAtoms as Record<string, any>).workerRowModels
+  stateAtom?.set((prev: any) => update(prev ?? { version: 0 }))
+}
+
+function postProcess(table: AnyTable, bridge: TableWorkerBridge): void {
+  const stages = tableWorkerPipeline.filter((stage) => bridge.stages.has(stage))
+  bridge.needsProcess = false
+  bridge.sentState = bridge.lastState
+  bridge.sentStageCount = bridge.stages.size
+  bridge.inFlight = true
+  bridge.sentAt = performance.now()
+  const requestId = ++bridge.requestId
+  bridge.worker!.postMessage({
+    type: 'process',
+    requestId,
+    dataVersion: bridge.dataVersion,
+    stages,
+    state: bridge.lastState,
+  })
+  // postProcess can run during render (via sync); defer the pending write.
+  table._reactivity.schedule(() => {
+    if (bridge.requestId === requestId && bridge.resultRequestId < requestId) {
+      setWorkerRowModelsState(table, (prev) => ({ ...prev, isPending: true }))
+    }
+  })
+}
+
+function handleResult(
+  table: AnyTable,
+  bridge: TableWorkerBridge,
+  message: TableWorkerResponse,
+) {
+  if (message.requestId !== bridge.requestId) return
+  bridge.inFlight = false
+  bridge.resultRequestId = message.requestId
+
+  // A data change raced this request: the result is for the old dataset.
+  // Drop it and immediately re-process against the new data.
+  if (message.dataVersion !== bridge.dataVersion) {
+    postProcess(table, bridge)
+    return
+  }
+
+  // Merge stage payloads: `unchanged` keeps the previous result (and its
+  // rebuilt model, via the per-stage version), changed payloads replace it.
+  let anyChanged = false
+  let groupedChanged = false
+  for (const [stage, payload] of Object.entries(message.stages) as Array<
+    [TableWorkerStage, TableWorkerStagePayload]
+  >) {
+    if (payload.kind === 'unchanged') continue
+    bridge.results[stage] = payload
+    bridge.stageVersions[stage] = (bridge.stageVersions[stage] ?? 0) + 1
+    anyChanged = true
+    if (stage === 'grouped') groupedChanged = true
+  }
+
+  const roundTripMs = performance.now() - bridge.sentAt
+  setWorkerRowModelsState(table, (prev) => ({
+    version: (prev.version ?? 0) + 1,
+    isPending: false,
+    lastComputeMs: message.computeMs,
+    lastRoundTripMs: roundTripMs,
+  }))
+
+  // The async equivalent of the sync models' `onAfterUpdate` hooks. The
+  // worker's unchanged-detection is its memo identity, so `groupedChanged`
+  // mirrors exactly when the sync grouped model would have recomputed (and
+  // reset expansion).
+  if (anyChanged) {
+    table._reactivity.schedule(() =>
+      table._reactivity.untrack(() => {
+        if (groupedChanged) {
+          table_autoResetExpanded(table)
+        }
+        table_autoResetPageIndex(table)
+      }),
+    )
+  }
+
+  // Trailing edge: state changed while this request was in flight.
+  if (bridge.needsProcess) {
+    postProcess(table, bridge)
+  }
+}
+
+function handleError(
+  table: AnyTable,
+  bridge: TableWorkerBridge,
+  event: unknown,
+) {
+  if (bridge.failed) return
+  bridge.failed = true
+  bridge.inFlight = false
+  console.error(
+    '[table-worker] The table worker failed; worker row models will keep ' +
+      'their last results and stop updating. Check that the worker entry ' +
+      'loads and that its initTableWorker() config is thread-portable.',
+    event,
+  )
+  bridge.worker?.terminate()
+  bridge.worker = null
+  setWorkerRowModelsState(table, (prev) => ({ ...prev, isPending: false }))
+}
+
+function ensureWorker(
+  tableWorker: TableWorker,
+  table: AnyTable,
+  bridge: TableWorkerBridge,
+) {
+  if (bridge.worker) return
+  bridge.worker = tableWorker._options.createWorker()
+  tableWorker._liveBridges.add(bridge)
+  bridge.worker.onmessage = (event: MessageEvent<TableWorkerResponse>) => {
+    handleResult(table, bridge, event.data)
+  }
+  bridge.worker.onerror = (event) => handleError(table, bridge, event)
+  bridge.worker.onmessageerror = (event) => handleError(table, bridge, event)
+}
+
+/**
+ * Pull-based sync, called at the top of every worker-backed row model read
+ * (i.e. every render). Posts data on identity change and a single-flight
+ * process request on state change; both are cheap no-ops otherwise, and
+ * multiple stages sharing the handle dedupe onto one request.
+ */
+export function syncTableWorker(tableWorker: TableWorker, table: AnyTable) {
+  // SSR: no Worker global. Getters fall back to pre-stage models, so the
+  // server renders unprocessed rows and the client takes over after hydration.
+  if (typeof Worker === 'undefined') return
+
+  const bridge = getTableWorkerBridge(tableWorker, table)
+  if (bridge.failed) return
+  ensureWorker(tableWorker, table, bridge)
+
+  const data = table.options.data
+  if (data !== bridge.lastData) {
+    bridge.lastData = data
+    bridge.dataVersion++
+    bridge.worker!.postMessage({
+      type: 'data',
+      dataVersion: bridge.dataVersion,
+      data,
+    })
+    bridge.needsProcess = true
+  }
+
+  // Union of the registered stages' state deps, compared by reference (atoms
+  // return stable refs when a slice did not change).
+  const atoms = table.atoms as Record<string, any>
+  const state: Record<string, unknown> = {}
+  for (const stage of bridge.stages) {
+    for (const key of tableWorkerStageStateDeps[stage]) {
+      state[key] = atoms[key]?.get()
+    }
+  }
+  bridge.lastState = state
+
+  if (
+    !bridge.needsProcess &&
+    (!statesEqual(bridge.sentState, state) ||
+      bridge.stages.size !== bridge.sentStageCount)
+  ) {
+    bridge.needsProcess = true
+  }
+
+  // Single-flight: at most one request in the worker at a time. If one is in
+  // flight, the latest state is posted from the result handler (trailing
+  // edge), so rapid input coalesces instead of queueing doomed computes.
+  if (bridge.needsProcess && !bridge.inFlight) {
+    postProcess(table, bridge)
+  }
+}

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