@tanstack/table-core 9.0.0-beta.7 → 9.0.0-beta.70

package/dist/worker/initTableWorker.d.ts

@@ -0,0 +1,31 @@
+import { RowData } from "../types/type-utils.js";
+import { TableOptions } from "../types/TableOptions.js";
+import { TableFeatures } from "../types/TableFeatures.js";
+//#region src/worker/initTableWorker.d.ts
+type TableWorkerConfig<TFeatures extends TableFeatures, TData extends RowData> = Omit<TableOptions<TFeatures, TData>, 'data'>;
+/**
+ * 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 })
+ * ```
+ */
+declare function initTableWorker<TFeatures extends TableFeatures, TData extends RowData>(config: TableWorkerConfig<TFeatures, TData>): void;
+//#endregion
+export { TableWorkerConfig, initTableWorker };

package/dist/worker/initTableWorker.js

@@ -0,0 +1,99 @@
+import { makeObjectMap } from "../utils.js";
+import { constructTable } from "../core/table/constructTable.js";
+import { storeReactivityBindings } from "../store-reactivity-bindings.js";
+import { serializeRowModel } from "./serializeRowModel.js";
+
+//#region src/worker/initTableWorker.ts
+function capitalize(stage) {
+	return stage.charAt(0).toUpperCase() + stage.slice(1);
+}
+/** Flatten column-group defs to leaf defs (mirrors core's id resolution). */
+function flattenColumnDefs(defs) {
+	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 })
+* ```
+*/
+function initTableWorker(config) {
+	let table;
+	let dataVersion = 0;
+	let coreIndexById = makeObjectMap();
+	let aggregateColumnIds = [];
+	let lastSentModels = {};
+	self.onmessage = (event) => {
+		const message = event.data;
+		if (message.type === "data") {
+			dataVersion = message.dataVersion;
+			lastSentModels = {};
+			if (!table) {
+				table = constructTable({
+					...config,
+					features: {
+						coreReactivityFeature: storeReactivityBindings(),
+						...config.features
+					},
+					data: message.data
+				});
+				aggregateColumnIds = flattenColumnDefs(config.columns).filter((def) => def.aggregationFn != null || def.aggregatedCell != null).map((def) => def.id ?? (def.accessorKey === void 0 ? void 0 : String(def.accessorKey).replaceAll(".", "_"))).filter((id) => id != null);
+			} else table.setOptions((prev) => ({
+				...prev,
+				data: message.data
+			}));
+			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();
+		table._reactivity.batch(() => {
+			for (const [key, value] of Object.entries(message.state)) {
+				const baseAtom = table.baseAtoms[key];
+				if (baseAtom && value !== void 0) baseAtom.set(value);
+			}
+		});
+		const stages = {};
+		const transfer = [];
+		for (const stage of message.stages) {
+			if (!config.features[`${stage}RowModel`]) continue;
+			const model = table[`get${capitalize(stage)}RowModel`]();
+			if (lastSentModels[stage] === model) {
+				stages[stage] = { kind: "unchanged" };
+				continue;
+			}
+			lastSentModels[stage] = model;
+			stages[stage] = serializeRowModel(model, coreIndexById, aggregateColumnIds, transfer);
+		}
+		const response = {
+			type: "result",
+			requestId: message.requestId,
+			dataVersion,
+			stages,
+			computeMs: performance.now() - start
+		};
+		postMessage(response, { transfer });
+	};
+}
+
+//#endregion
+export { initTableWorker };

package/dist/worker/rebuildRowModel.d.ts

@@ -0,0 +1,11 @@
+import { TableWorkerStagePayload } from "./tableWorkerProtocol.js";
+import "../core/row-models/coreRowModelsFeature.types.js";
+import "../types/Table.js";
+import "../types/TableFeatures.js";
+//#region src/worker/rebuildRowModel.d.ts
+/** Payloads that carry data; `unchanged` never reaches the rebuilder. */
+type TableWorkerDataPayload = Exclude<TableWorkerStagePayload, {
+  kind: 'unchanged';
+}>;
+//#endregion
+export { TableWorkerDataPayload };

package/dist/worker/rebuildRowModel.js

@@ -0,0 +1,71 @@
+import { hasOwn } from "../utils.js";
+import { constructRow } from "../core/rows/constructRow.js";
+
+//#region src/worker/rebuildRowModel.ts
+function collectLeafRows(subRows, out) {
+	for (let i = 0; i < subRows.length; i++) {
+		const row = subRows[i];
+		if (row.groupingColumnId == null) out.push(row);
+		else collectLeafRows(row.subRows, out);
+	}
+}
+function rebuildRowModel(table, payload, resetDepths) {
+	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 = core.flatRows[indices[i]];
+			if (resetDepths) {
+				row.depth = 0;
+				row.parentId = void 0;
+			}
+			rows[i] = row;
+		}
+		return {
+			rows,
+			flatRows: rows,
+			rowsById: core.rowsById
+		};
+	}
+	const flatRows = [];
+	const rowsById = Object.create(core.rowsById);
+	const rebuildRows = (nodes, depth, parentId) => {
+		const rows = new Array(nodes.length);
+		for (let i = 0; i < nodes.length; i++) {
+			const node = nodes[i];
+			if (typeof node === "number") {
+				const row = 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 = [];
+			collectLeafRows(subRows, leafRows);
+			const row = constructRow(table, node.id, leafRows[0]?.original, node.index, depth, void 0, parentId);
+			const aggregates = node.aggregates;
+			Object.assign(row, {
+				groupingColumnId: node.groupingColumnId,
+				groupingValue: node.groupingValue,
+				subRows,
+				leafRows,
+				getValue: (columnId) => hasOwn(aggregates, columnId) ? aggregates[columnId] : void 0
+			});
+			flatRows.push(row);
+			rowsById[node.id] = row;
+			rows[i] = row;
+		}
+		return rows;
+	};
+	return {
+		rows: rebuildRows(payload.children, 0, void 0),
+		flatRows,
+		rowsById
+	};
+}
+
+//#endregion
+export { rebuildRowModel };

package/dist/worker/serializeRowModel.js

@@ -0,0 +1,51 @@
+//#region src/worker/serializeRowModel.ts
+function isCloneSafe(value) {
+	return typeof value !== "function" && typeof value !== "symbol";
+}
+function serializeRows(rows, coreIndexById, aggregateColumnIds) {
+	const nodes = new Array(rows.length);
+	for (let i = 0; i < rows.length; i++) {
+		const row = rows[i];
+		if (row.groupingColumnId == null) {
+			nodes[i] = coreIndexById[row.id];
+			continue;
+		}
+		const aggregates = {};
+		for (let c = 0; c < aggregateColumnIds.length; c++) {
+			const columnId = aggregateColumnIds[c];
+			const value = row.getValue(columnId);
+			if (value !== void 0 && isCloneSafe(value)) aggregates[columnId] = value;
+		}
+		if (!(row.groupingColumnId in aggregates)) {
+			const value = row.getValue(row.groupingColumnId);
+			if (value !== void 0 && 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;
+}
+function serializeRowModel(model, coreIndexById, aggregateColumnIds, transfer) {
+	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)
+	};
+}
+
+//#endregion
+export { serializeRowModel };

package/dist/worker/tableWorkerProtocol.d.ts

@@ -0,0 +1,88 @@
+import { RowData } from "../types/type-utils.js";
+//#region src/worker/tableWorkerProtocol.d.ts
+/**
+ * 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`.
+ */
+declare const tableWorkerPipeline: readonly ["filtered", "grouped", "sorted", "expanded"];
+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.
+ */
+declare const tableWorkerStageStateDeps: Record<TableWorkerStage, Array<string>>;
+/**
+ * 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.
+ */
+interface TableWorkerGroupNode {
+  id: string;
+  groupingColumnId: string;
+  groupingValue: unknown;
+  index: number;
+  aggregates: Record<string, unknown>;
+  children: Array<TableWorkerRowNode>;
+}
+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.
+ */
+type TableWorkerStagePayload = {
+  kind: 'flat';
+  indices: Uint32Array;
+} | {
+  kind: 'tree';
+  children: Array<TableWorkerRowNode>;
+} | {
+  kind: 'unchanged';
+};
+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>;
+};
+interface TableWorkerResult {
+  type: 'result';
+  requestId: number;
+  dataVersion: number;
+  stages: { [K in TableWorkerStage]?: TableWorkerStagePayload; };
+  computeMs: number;
+}
+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.
+ */
+interface TableState_WorkerRowModels {
+  workerRowModels: {
+    version: number;
+    isPending: boolean;
+    lastComputeMs?: number;
+    lastRoundTripMs?: number;
+  };
+}
+//#endregion
+export { TableState_WorkerRowModels, TableWorkerGroupNode, TableWorkerRequest, TableWorkerResponse, TableWorkerResult, TableWorkerRowNode, TableWorkerStage, TableWorkerStagePayload, tableWorkerPipeline, tableWorkerStageStateDeps };

package/dist/worker/tableWorkerProtocol.js

@@ -0,0 +1,26 @@
+//#region src/worker/tableWorkerProtocol.ts
+/**
+* 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`.
+*/
+const tableWorkerPipeline = [
+	"filtered",
+	"grouped",
+	"sorted",
+	"expanded"
+];
+/**
+* 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.
+*/
+const tableWorkerStageStateDeps = {
+	filtered: ["columnFilters", "globalFilter"],
+	grouped: ["grouping"],
+	sorted: ["sorting"],
+	expanded: ["expanded"]
+};
+
+//#endregion
+export { tableWorkerPipeline, tableWorkerStageStateDeps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/table-core",
-  "version": "9.0.0-beta.7",
+  "version": "9.0.0-beta.70",
   "description": "Headless UI for building powerful tables & datagrids for TS/JS.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -27,39 +27,22 @@
     "tanstack-intent"
   ],
   "type": "module",
-  "types": "./dist/index.d.cts",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./flex-render": {
-      "import": "./dist/flex-render.js",
-      "require": "./dist/flex-render.cjs"
-    },
-    "./reactivity": {
-      "import": "./dist/reactivity.js",
-      "require": "./dist/reactivity.cjs"
-    },
-    "./static-functions": {
-      "import": "./dist/static-functions.js",
-      "require": "./dist/static-functions.cjs"
-    },
-    "./store-reactivity-bindings": {
-      "import": "./dist/store-reactivity-bindings.js",
-      "require": "./dist/store-reactivity-bindings.cjs"
-    },
+    ".": "./dist/index.js",
+    "./experimental-worker-plugin": "./dist/experimental-worker-plugin.js",
+    "./flex-render": "./dist/flex-render.js",
+    "./reactivity": "./dist/reactivity.js",
+    "./static-functions": "./dist/static-functions.js",
+    "./store-reactivity-bindings": "./dist/store-reactivity-bindings.js",
     "./package.json": "./package.json"
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=16"
+    "node": ">=20"
   },
   "files": [
-    "dist/",
-    "src",
+    "dist",
     "skills"
   ],
   "dependencies": {
@@ -69,10 +52,11 @@
     "clean": "rimraf ./build && rimraf ./dist",
     "lint:fix": "eslint ./src --fix",
     "test:eslint": "eslint ./src",
+    "test:coverage": "vitest run --coverage",
     "test:lib": "vitest",
     "test:lib:dev": "pnpm test:lib --watch",
     "test:types": "tsc && tsc -p tests/tsconfig.declaration-emit.json",
     "test:build": "publint --strict",
-    "build": "tsdown"
+    "build": "tsdown && node ../../scripts/rewrite-table-core-dts.mjs"
   }
 }

package/skills/aggregation/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: aggregation
+description: >
+  Aggregate TanStack Table columns independently of grouping, including grand totals, caller-selected row totals, multiple keyed aggregations, custom context-based definitions, grouped merges, manual values, and worker constraints.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.70',
+  }
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/guide/aggregation.md'
+  - 'TanStack/table:docs/framework/react/guide/aggregation.md'
+  - 'TanStack/table:packages/table-core/src/features/row-aggregation'
+  - 'TanStack/table:examples/react/aggregation'
+  - 'TanStack/table:examples/react/grouped-aggregation'
+---
+
+This skill builds on `core` and `table-features`. Aggregation is independent
+from grouping: use it alone for totals, or combine it with the `grouping` skill
+for synthetic grouped rows.
+
+## Setup
+
+<!-- skill-snippet:check -->
+
+```ts
+import {
+  rowAggregationFeature,
+  aggregationFn_mean,
+  aggregationFn_sum,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  rowAggregationFeature,
+  aggregationFns: {
+    mean: aggregationFn_mean,
+    sum: aggregationFn_sum,
+  },
+})
+```
+
+## Core Patterns
+
+### Grand total and selected row scopes
+
+```ts
+const grandTotal = salaryColumn.getAggregationValue()
+const filteredTotal = salaryColumn.getAggregationValue({
+  rows: table.getFilteredRowModel().rows,
+})
+const childTotal = salaryColumn.getAggregationValue({
+  rows: table.getCoreRowModel().rows,
+  maxDepth: 1,
+})
+```
+
+The default uses the pre-grouped row model. Explicit rows can come from any row
+model or caller-selected subset. `maxAggregationDepth` defaults to `0`, which
+selects the supplied roots; `1` selects direct sub-rows, and `Infinity` selects
+terminal rows. Branches that end early contribute their deepest available row.
+Default calls are cached; explicit-row calls intentionally are not because array
+identity and contents are caller-owned. `table.getMaxSubRowDepth()` returns the
+deepest structural depth in the core row model.
+
+### Multiple aggregations
+
+```ts
+columnHelper.accessor('salary', {
+  aggregationFn: ['mean', { id: 'range', aggregationFn: 'extent' }],
+})
+
+const value = salaryColumn.getAggregationValue<{
+  mean: number
+  range: [number, number]
+}>()
+```
+
+A scalar option returns a scalar. An array returns a keyed object. Named
+functions use their registry name; descriptors provide a stable `id`, which is
+required for inline definitions in an array.
+
+### Custom definitions
+
+```ts
+const weightedMean = constructAggregationFn({
+  aggregate: ({ rows, getValue }) => {
+    const total = rows.reduce((sum, row) => sum + Number(getValue(row)), 0)
+    return rows.length ? total / rows.length : undefined
+  },
+})
+```
+
+The context provides depth-selected `rows`, `maxDepth`, `getValue`, `column`,
+`columnId`, `table`, and optional grouped-only `groupingRow` and `subRows`.
+Every aggregation configured on a column receives the same row frontier. Add
+`merge({ subRowResults, subRows, ...context })` when nested groups can more
+efficiently combine already-computed sub-row results; otherwise the engine calls
+`aggregate` with both row sets. `subRowResults[i]` corresponds to `subRows[i]`.
+
+### Manual or remote values
+
+Set a column definition's `getAggregationValue(context)` to return `{ value }`
+for requests handled by a server or another execution environment. Returning
+`undefined` falls back to the local definition. `manualAggregation: true`
+disables that local fallback.
+
+## Common Mistakes
+
+### [HIGH] Adding grouping for a grand total
+
+Wrong: registering `columnGroupingFeature` solely to total a column.
+
+Correct: register `rowAggregationFeature` and call
+`column.getAggregationValue()`. Grouping is only required for grouped rows.
+
+### [HIGH] Passing a scope label and rows
+
+There is no scope option. Call `getAggregationValue()` for the cached default,
+or pass a single options object containing rows from the desired row model and
+`maxDepth` when the desired frontier is below those rows.
+
+### [HIGH] Reusing the legacy callable signature
+
+Wrong: `(columnId, leafRows, childRows) => result`.
+
+Correct: `constructAggregationFn({ aggregate: ({ rows, subRows, getValue }) => result })`.
+
+### [MEDIUM] Assuming arbitrary totals run in the worker
+
+The experimental worker computes grouped row-model aggregates. Public
+`getAggregationValue(options?)` totals execute on the main thread, and custom
+grouped results sent by the worker must be structured-cloneable.
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/dist/features/row-aggregation/` and the
+Aggregation Guide. Use `Column_RowAggregation`, `AggregationFnDef`,
+`AggregationContext`, and `AggregationResult` for the typed public surface.