@tanstack/table-core 9.0.0-beta.52 → 9.0.0-beta.53

package/src/worker/createTableWorker.ts

@@ -1,357 +0,0 @@
-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

@@ -1,121 +0,0 @@
-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

@@ -1,164 +0,0 @@
-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,
-        })
-        // 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:
-        // rowAggregationFeature 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 })
-  }
-}