@tanstack/table-core 9.0.0-beta.9 → 9.0.0

package/dist/utils.d.ts

@@ -1,8 +1,7 @@
 import { NoInfer, RowData, Updater } from "./types/type-utils.js";
 import { TableState, TableState_All } from "./types/TableState.js";
+import { Table } from "./types/Table.js";
 import { TableFeatures } from "./types/TableFeatures.js";
-import { Table, Table_Internal } from "./types/Table.js";
-
 //#region src/utils.d.ts
 /**
  * Applies a TanStack updater to a value.
@@ -16,12 +15,34 @@ declare function functionalUpdate<T>(updater: Updater<T>, input: T): T;
  * Plain objects and arrays are copied recursively so state updates can avoid mutating existing references.
  */
 declare function cloneState<T>(value: T): T;
+/**
+ * Copies prototype-instance own properties without carrying over lazy memo
+ * closures or the per-row cell cache, both of which are bound to the source
+ * instance (cached cells reference the source row).
+ */
+declare function copyInstancePropertiesWithoutMemos<TTarget extends Record<string, any>, TSource extends Record<string, any>>(target: TTarget, source: TSource): TTarget & TSource;
+/**
+ * Creates an object intended only for string-keyed dictionary lookups.
+ *
+ * The null prototype keeps user-controlled ids such as `__proto__` and
+ * `hasOwnProperty` as plain data keys.
+ */
+declare function makeObjectMap<TValue = unknown>(): Record<string, TValue>;
+/**
+ * Checks whether an object owns a key, including null-prototype dictionaries.
+ */
+declare function hasOwn(obj: object, key: PropertyKey): boolean;
 /**
  * Creates a table state updater for a single state slice.
  *
  * The updater writes through the table base atom for the slice and supports both value and functional updater forms.
  */
-declare function makeStateUpdater<TFeatures extends TableFeatures, K extends (string & {}) | keyof TableState_All | keyof TableState<TFeatures>>(key: K, instance: Table<TFeatures, any>): (updater: Updater<TableState<any>[K & keyof TableState<any>]>) => void;
+declare function makeStateUpdater<TFeatures extends TableFeatures, K extends (string & {}) | keyof TableState_All | keyof TableState<TFeatures>>(key: K, instance: {
+  readonly options: {
+    readonly atoms?: object | undefined;
+  };
+  readonly baseAtoms: object;
+}): (updater: Updater<TableState<any>[K & keyof TableState<any>]>) => void;
 type AnyFunction = (...args: any) => any;
 /**
  * Returns whether a value is a function.
@@ -46,35 +67,30 @@ interface MemoOptions<TDeps extends ReadonlyArray<any>, TDepArgs, TResult> {
  *
  * The memo recomputes only when its dependency tuple changes and can emit debug timing information.
  */
-declare const memo: <TDeps extends ReadonlyArray<any>, TDepArgs, TResult>({
-  fn,
-  memoDeps,
-  onAfterCompare,
-  onAfterUpdate,
-  onBeforeCompare,
-  onBeforeUpdate
-}: MemoOptions<TDeps, TDepArgs, TResult>) => ((depArgs?: TDepArgs) => TResult);
+declare const memo: <TDeps extends ReadonlyArray<any>, TDepArgs, TResult>({ fn, memoDeps, onAfterCompare, onAfterUpdate, onBeforeCompare, onBeforeUpdate }: MemoOptions<TDeps, TDepArgs, TResult>) => ((depArgs?: TDepArgs) => TResult);
+/**
+ * Wraps a callback so that its first invocation is skipped.
+ *
+ * Row-model `onAfterUpdate` hooks schedule auto-resets when their inputs
+ * change. The initial computation of a row model is not a change, so state
+ * resets must not fire for it — otherwise merely reading a row model on mount
+ * would wipe initial or controlled state.
+ */
+declare function skipFirstRun(fn: () => void): () => void;
 interface TableMemoOptions<TFeatures extends TableFeatures, TDeps extends ReadonlyArray<any>, TDepArgs, TResult> extends MemoOptions<TDeps, TDepArgs, TResult> {
   feature?: keyof TFeatures & string;
   fnName: string;
   objectId?: string;
   onAfterUpdate?: () => void;
-  table: Table_Internal<TFeatures, any>;
+  table: Table<TFeatures, any>;
 }
 /**
  * Creates a table-aware memoized function.
  *
  * This wraps `memo` with table debug options and feature metadata so row models and derived APIs can share consistent diagnostics.
  */
-declare function tableMemo<TFeatures extends TableFeatures, TDeps extends ReadonlyArray<any>, TDepArgs, TResult>({
-  feature,
-  fnName,
-  objectId,
-  onAfterUpdate,
-  table,
-  ...memoOptions
-}: TableMemoOptions<TFeatures, TDeps, TDepArgs, TResult>): (depArgs?: TDepArgs | undefined) => TResult;
-interface API<TDeps extends ReadonlyArray<any>, TDepArgs> {
+declare function tableMemo<TFeatures extends TableFeatures, TDeps extends ReadonlyArray<any>, TDepArgs, TResult>({ feature, fnName, objectId, onAfterUpdate, table, ...memoOptions }: TableMemoOptions<TFeatures, TDeps, TDepArgs, TResult>): (depArgs?: TDepArgs | undefined) => TResult;
+interface API<_TDeps extends ReadonlyArray<any>, _TDepArgs> {
   fn: (...args: any) => any;
   memoDeps?: (depArgs?: any) => [...any] | undefined;
 }
@@ -91,8 +107,8 @@ declare function getFunctionNameInfo(staticFnName: string, splitBy?: '_' | '.'):
  * Assigns Table API methods directly to the table instance.
  * Unlike row/cell/column/header, the table is a singleton so methods are assigned directly.
  */
-declare function assignTableAPIs<TFeatures extends TableFeatures, TData extends RowData, TDeps extends ReadonlyArray<any>, TDepArgs>(feature: keyof TFeatures & string, table: Table_Internal<TFeatures, TData>, apis: APIObject<TDeps, NoInfer<TDepArgs>>): void;
-interface PrototypeAPI<TDeps extends ReadonlyArray<any>, TDepArgs> {
+declare function assignTableAPIs<TFeatures extends TableFeatures, TData extends RowData, TDeps extends ReadonlyArray<any>, TDepArgs>(feature: keyof TFeatures & string, table: Table<TFeatures, TData>, apis: APIObject<TDeps, NoInfer<TDepArgs>>): void;
+interface PrototypeAPI<_TDeps extends ReadonlyArray<any>, _TDepArgs> {
   fn: (self: any, ...args: any) => any;
   memoDeps?: (self: any, depArgs?: any) => [...any] | undefined;
 }
@@ -104,11 +120,10 @@ type PrototypeAPIObject<TDeps extends ReadonlyArray<any>, TDepArgs> = Record<str
  * For memoized methods, the memo state is lazily created and stored on each instance.
  * This provides the best of both worlds: shared method code + per-instance caching.
  */
-declare function assignPrototypeAPIs<TFeatures extends TableFeatures, TData extends RowData, TDeps extends ReadonlyArray<any>, TDepArgs>(feature: keyof TFeatures & string, prototype: Record<string, any>, table: Table_Internal<TFeatures, TData>, apis: PrototypeAPIObject<TDeps, NoInfer<TDepArgs>>): void;
+declare function assignPrototypeAPIs<TFeatures extends TableFeatures, TData extends RowData, TDeps extends ReadonlyArray<any>, TDepArgs>(feature: keyof TFeatures & string, prototype: Record<string, any>, table: Table<TFeatures, TData>, apis: PrototypeAPIObject<TDeps, NoInfer<TDepArgs>>): void;
 /**
- * Looks to run the memoized function with the builder pattern on the object if it exists, otherwise fallback to the static method passed in.
+ * Looks to run the memoized function with the builder pattern on the object if it exists, otherwise fall back to the static method passed in.
  */
 declare function callMemoOrStaticFn<TObject extends Record<string, any>, TArgs extends Array<any>, TReturn>(obj: TObject, fnKey: string, staticFn: (obj: TObject, ...args: TArgs) => TReturn, ...args: TArgs): TReturn;
 //#endregion
-export { API, APIObject, PrototypeAPI, PrototypeAPIObject, assignPrototypeAPIs, assignTableAPIs, callMemoOrStaticFn, cloneState, flattenBy, functionalUpdate, getFunctionNameInfo, isFunction, makeStateUpdater, memo, tableMemo };
-//# sourceMappingURL=utils.d.ts.map
+export { API, APIObject, PrototypeAPI, PrototypeAPIObject, assignPrototypeAPIs, assignTableAPIs, callMemoOrStaticFn, cloneState, copyInstancePropertiesWithoutMemos, flattenBy, functionalUpdate, getFunctionNameInfo, hasOwn, isFunction, makeObjectMap, makeStateUpdater, memo, skipFirstRun, tableMemo };

package/dist/utils.js

@@ -17,25 +17,58 @@ function cloneState(value) {
 	if (value && typeof value === "object") {
 		const proto = Object.getPrototypeOf(value);
 		if (proto !== Object.prototype && proto !== null) return value;
-		const copy = {};
+		const copy = proto === null ? makeObjectMap() : {};
 		const keys = Object.keys(value);
 		for (let i = 0; i < keys.length; i++) {
 			const key = keys[i];
-			copy[key] = cloneState(value[key]);
+			Object.defineProperty(copy, key, {
+				configurable: true,
+				enumerable: true,
+				value: cloneState(value[key]),
+				writable: true
+			});
 		}
 		return copy;
 	}
 	return value;
 }
 /**
+* Copies prototype-instance own properties without carrying over lazy memo
+* closures or the per-row cell cache, both of which are bound to the source
+* instance (cached cells reference the source row).
+*/
+function copyInstancePropertiesWithoutMemos(target, source) {
+	const keys = Object.keys(source);
+	const targetRecord = target;
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i];
+		if (!key.startsWith("_memo_") && key !== "_cellsCache") targetRecord[key] = source[key];
+	}
+	return target;
+}
+/**
+* Creates an object intended only for string-keyed dictionary lookups.
+*
+* The null prototype keeps user-controlled ids such as `__proto__` and
+* `hasOwnProperty` as plain data keys.
+*/
+function makeObjectMap() {
+	return Object.create(null);
+}
+/**
+* Checks whether an object owns a key, including null-prototype dictionaries.
+*/
+function hasOwn(obj, key) {
+	return Object.prototype.hasOwnProperty.call(obj, key);
+}
+/**
 * Creates a table state updater for a single state slice.
 *
 * The updater writes through the table base atom for the slice and supports both value and functional updater forms.
 */
 function makeStateUpdater(key, instance) {
 	return (updater) => {
-		var _atoms;
-		(((_atoms = instance.options.atoms) === null || _atoms === void 0 ? void 0 : _atoms[key]) ?? instance.baseAtoms[key]).set((old) => functionalUpdate(updater, old));
+		(instance.options.atoms?.[key] ?? instance.baseAtoms[key]).set((old) => functionalUpdate(updater, old));
 	};
 }
 /**
@@ -70,25 +103,43 @@ const memo = ({ fn, memoDeps, onAfterCompare, onAfterUpdate, onBeforeCompare, on
 	let deps = [];
 	let result;
 	const memoizedFn = (depArgs) => {
-		onBeforeCompare === null || onBeforeCompare === void 0 || onBeforeCompare();
-		const newDeps = memoDeps === null || memoDeps === void 0 ? void 0 : memoDeps(depArgs);
-		let depsChanged = !newDeps || newDeps.length !== (deps === null || deps === void 0 ? void 0 : deps.length);
+		onBeforeCompare?.();
+		const newDeps = memoDeps?.(depArgs);
+		let depsChanged = !newDeps || newDeps.length !== deps?.length;
 		if (!depsChanged && newDeps) {
 			for (let i = 0; i < newDeps.length; i++) if (newDeps[i] !== deps[i]) {
 				depsChanged = true;
 				break;
 			}
 		}
-		onAfterCompare === null || onAfterCompare === void 0 || onAfterCompare(depsChanged);
+		onAfterCompare?.(depsChanged);
 		if (!depsChanged) return result;
 		deps = newDeps;
-		onBeforeUpdate === null || onBeforeUpdate === void 0 || onBeforeUpdate();
+		onBeforeUpdate?.();
 		result = fn(...newDeps ?? []);
-		onAfterUpdate === null || onAfterUpdate === void 0 || onAfterUpdate(result);
+		onAfterUpdate?.(result);
 		return result;
 	};
 	return memoizedFn;
 };
+/**
+* Wraps a callback so that its first invocation is skipped.
+*
+* Row-model `onAfterUpdate` hooks schedule auto-resets when their inputs
+* change. The initial computation of a row model is not a change, so state
+* resets must not fire for it — otherwise merely reading a row model on mount
+* would wipe initial or controlled state.
+*/
+function skipFirstRun(fn) {
+	let hasRun = false;
+	return () => {
+		if (!hasRun) {
+			hasRun = true;
+			return;
+		}
+		fn();
+	};
+}
 const pad = (str, num) => {
 	str = String(str);
 	while (str.length < num) str = " " + str;
@@ -100,21 +151,18 @@ const pad = (str, num) => {
 * This wraps `memo` with table debug options and feature metadata so row models and derived APIs can share consistent diagnostics.
 */
 function tableMemo({ feature, fnName, objectId, onAfterUpdate, table, ...memoOptions }) {
-	let beforeCompareTime;
-	let afterCompareTime;
 	let startCalcTime;
 	let endCalcTime;
 	let runCount = 0;
 	let debug;
-	let debugCache;
 	if (process.env.NODE_ENV === "development") {
-		const { debugCache: _debugCache, debugAll } = table.options;
-		debugCache = _debugCache;
+		const { debugAll } = table.options;
 		const { parentName } = getFunctionNameInfo(fnName, ".");
-		debug = debugAll || table.options[`debug${(parentName != "table" ? parentName + "s" : parentName).replace(parentName, parentName.charAt(0).toUpperCase() + parentName.slice(1))}`] || (feature ? table.options[`debug${feature.charAt(0).toUpperCase() + feature.slice(1)}`] : false);
+		const debugByParent = table.options[`debug${(parentName != "table" ? parentName + "s" : parentName).replace(parentName, parentName.charAt(0).toUpperCase() + parentName.slice(1))}`];
+		const debugByFeature = feature ? table.options[`debug${feature.charAt(0).toUpperCase() + feature.slice(1)}`] : false;
+		debug = debugAll || debugByParent || debugByFeature;
 	}
 	function logTime(time, depsChanged) {
-		var _memoOptions$memoDeps;
 		const runType = runCount === 0 ? "(1st run)" : depsChanged ? "(rerun #" + runCount + ")" : "(cache)";
 		runCount++;
 		console.groupCollapsed(`%c⏱ ${pad(`${time.toFixed(1)} ms`, 12)} %c${runType}%c ${fnName}%c ${objectId ? `(${fnName.split(".")[0]}Id: ${objectId})` : ""}`, `font-size: .6rem; font-weight: bold; ${depsChanged ? `color: hsl(
@@ -122,7 +170,7 @@ function tableMemo({ feature, fnName, objectId, onAfterUpdate, table, ...memoOpt
 		console.info({
 			feature,
 			state: table.store.state,
-			deps: (_memoOptions$memoDeps = memoOptions.memoDeps) === null || _memoOptions$memoDeps === void 0 ? void 0 : _memoOptions$memoDeps.toString()
+			deps: memoOptions.memoDeps?.toString()
 		});
 		console.trace();
 		console.groupEnd();
@@ -133,16 +181,8 @@ function tableMemo({ feature, fnName, objectId, onAfterUpdate, table, ...memoOpt
 		schedule(() => untrack(() => onAfterUpdate()));
 	};
 	const debugOptions = process.env.NODE_ENV === "development" ? {
-		onBeforeCompare: () => {
-			if (debugCache) beforeCompareTime = performance.now();
-		},
-		onAfterCompare: (depsChanged) => {
-			if (debugCache) {
-				afterCompareTime = performance.now();
-				const compareTime = Math.round((afterCompareTime - beforeCompareTime) * 100) / 100;
-				if (!depsChanged) logTime(compareTime, depsChanged);
-			}
-		},
+		onBeforeCompare: () => {},
+		onAfterCompare: (depsChanged) => {},
 		onBeforeUpdate: () => {
 			if (debug) startCalcTime = performance.now();
 		},
@@ -220,13 +260,11 @@ function assignPrototypeAPIs(feature, prototype, table, apis) {
 	}
 }
 /**
-* Looks to run the memoized function with the builder pattern on the object if it exists, otherwise fallback to the static method passed in.
+* Looks to run the memoized function with the builder pattern on the object if it exists, otherwise fall back to the static method passed in.
 */
 function callMemoOrStaticFn(obj, fnKey, staticFn, ...args) {
-	var _obj$fnKey;
-	return ((_obj$fnKey = obj[fnKey]) === null || _obj$fnKey === void 0 ? void 0 : _obj$fnKey.call(obj, ...args)) ?? staticFn(obj, ...args);
+	return obj[fnKey]?.(...args) ?? staticFn(obj, ...args);
 }
 
 //#endregion
-export { assignPrototypeAPIs, assignTableAPIs, callMemoOrStaticFn, cloneState, flattenBy, functionalUpdate, getFunctionNameInfo, isFunction, makeStateUpdater, memo, tableMemo };
-//# sourceMappingURL=utils.js.map
+export { assignPrototypeAPIs, assignTableAPIs, callMemoOrStaticFn, cloneState, copyInstancePropertiesWithoutMemos, flattenBy, functionalUpdate, getFunctionNameInfo, hasOwn, isFunction, makeObjectMap, makeStateUpdater, memo, skipFirstRun, tableMemo };

package/dist/worker/createTableWorker.d.ts

@@ -0,0 +1,102 @@
+import { TableState_WorkerRowModels, TableWorkerStage } from "./tableWorkerProtocol.js";
+import { Table } from "../types/Table.js";
+import { TableFeature } from "../types/TableFeatures.js";
+import { TableWorkerDataPayload } from "./rebuildRowModel.js";
+//#region src/worker/createTableWorker.d.ts
+declare module '../types/TableFeatures' {
+  interface Plugins {
+    workerRowModelsFeature: TableFeature;
+  }
+}
+declare module '../types/TableState' {
+  interface TableState_FeatureMap {
+    workerRowModelsFeature: TableState_WorkerRowModels;
+  }
+}
+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;
+}
+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; };
+  /** The first applied result is not a change; auto-resets skip it. */
+  hasAppliedResults: boolean;
+}
+type AnyTable = Table<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.
+ */
+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.
+ */
+declare const workerRowModelsFeature: TableFeature;
+/**
+ * Creates the shared worker handle for a table's worker-backed row models.
+ * Pass it to `createWorkerRowModel()` once per stage you want offloaded.
+ */
+declare function createTableWorker(options: TableWorkerOptions): TableWorker;
+declare function getTableWorkerBridge(tableWorker: TableWorker, table: AnyTable): TableWorkerBridge;
+/**
+ * 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.
+ */
+declare function syncTableWorker(tableWorker: TableWorker, table: AnyTable): void;
+//#endregion
+export { TableWorker, TableWorkerBridge, TableWorkerOptions, createTableWorker, getTableWorkerBridge, syncTableWorker, workerRowModelsFeature };

package/dist/worker/createTableWorker.js

@@ -0,0 +1,188 @@
+import { table_autoResetExpanded } from "../features/row-expanding/rowExpandingFeature.utils.js";
+import { table_autoResetPageIndex } from "../features/row-pagination/rowPaginationFeature.utils.js";
+import { tableWorkerPipeline, tableWorkerStageStateDeps } from "./tableWorkerProtocol.js";
+
+//#region src/worker/createTableWorker.ts
+/**
+* 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.
+*/
+const workerRowModelsFeature = { getInitialState: (initialState) => ({
+	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.
+*/
+function createTableWorker(options) {
+	const liveBridges = /* @__PURE__ */ new Set();
+	return {
+		_options: options,
+		_bridges: /* @__PURE__ */ new WeakMap(),
+		_liveBridges: liveBridges,
+		terminate: () => {
+			for (const bridge of liveBridges) {
+				bridge.worker?.terminate();
+				bridge.worker = null;
+				bridge.failed = false;
+				bridge.lastData = void 0;
+				bridge.inFlight = false;
+				bridge.needsProcess = true;
+				bridge.sentState = null;
+				bridge.sentStageCount = 0;
+			}
+			liveBridges.clear();
+		}
+	};
+}
+function getTableWorkerBridge(tableWorker, table) {
+	let bridge = tableWorker._bridges.get(table);
+	if (!bridge) {
+		bridge = {
+			worker: null,
+			failed: false,
+			lastData: void 0,
+			dataVersion: 0,
+			requestId: 0,
+			resultRequestId: 0,
+			inFlight: false,
+			needsProcess: true,
+			sentAt: 0,
+			stages: /* @__PURE__ */ new Set(),
+			sentState: null,
+			sentStageCount: 0,
+			lastState: {},
+			results: {},
+			stageVersions: {},
+			hasAppliedResults: false
+		};
+		tableWorker._bridges.set(table, bridge);
+	}
+	return bridge;
+}
+/** Shallow reference comparison; atoms return stable refs when unchanged. */
+function statesEqual(a, b) {
+	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, update) {
+	table.baseAtoms.workerRowModels?.set((prev) => update(prev ?? { version: 0 }));
+}
+function postProcess(table, bridge) {
+	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
+	});
+	table._reactivity.schedule(() => {
+		if (bridge.requestId === requestId && bridge.resultRequestId < requestId) setWorkerRowModelsState(table, (prev) => ({
+			...prev,
+			isPending: true
+		}));
+	});
+}
+function handleResult(table, bridge, message) {
+	if (message.requestId !== bridge.requestId) return;
+	bridge.inFlight = false;
+	bridge.resultRequestId = message.requestId;
+	if (message.dataVersion !== bridge.dataVersion) {
+		postProcess(table, bridge);
+		return;
+	}
+	let anyChanged = false;
+	let groupedChanged = false;
+	for (const [stage, payload] of Object.entries(message.stages)) {
+		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
+	}));
+	const isFirstAppliedResult = !bridge.hasAppliedResults;
+	bridge.hasAppliedResults = true;
+	if (anyChanged && !isFirstAppliedResult) table._reactivity.schedule(() => table._reactivity.untrack(() => {
+		if (groupedChanged) table_autoResetExpanded(table);
+		table_autoResetPageIndex(table);
+	}));
+	if (bridge.needsProcess) postProcess(table, bridge);
+}
+function handleError(table, bridge, event) {
+	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, table, bridge) {
+	if (bridge.worker) return;
+	bridge.worker = tableWorker._options.createWorker();
+	tableWorker._liveBridges.add(bridge);
+	bridge.worker.onmessage = (event) => {
+		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.
+*/
+function syncTableWorker(tableWorker, table) {
+	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;
+	}
+	const atoms = table.atoms;
+	const state = {};
+	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;
+	if (bridge.needsProcess && !bridge.inFlight) postProcess(table, bridge);
+}
+
+//#endregion
+export { createTableWorker, getTableWorkerBridge, syncTableWorker, workerRowModelsFeature };

package/dist/worker/createWorkerRowModel.d.ts

@@ -0,0 +1,40 @@
+import { RowData } from "../types/type-utils.js";
+import { TableWorkerStage } from "./tableWorkerProtocol.js";
+import { RowModel } from "../core/row-models/coreRowModelsFeature.types.js";
+import { Table } from "../types/Table.js";
+import { TableFeatures } from "../types/TableFeatures.js";
+import { TableWorker } from "./createTableWorker.js";
+//#region src/worker/createWorkerRowModel.d.ts
+/**
+ * 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'),
+ * })
+ * ```
+ */
+declare function createWorkerRowModel(tableWorker: TableWorker, stage: TableWorkerStage): <TFeatures extends TableFeatures, TData extends RowData>(_table: Table<TFeatures, TData>) => (() => RowModel<TFeatures, TData>);
+//#endregion
+export { createWorkerRowModel };