Offloading Heavy Computations to Web Workers
When an application needs to parse multi-megabyte CSV/JSON files, aggregate tens of thousands of records, generate reports, or process images on the client, running that logic on the Main Thread blocks the UI and causes animation and input stutter.
In @pravosleva/reactive-engine v3.0.1, integrating Web Workers builds cleanly on top of engine.resource() and AbstractService:
- Promise wrapper over
postMessage: The service encapsulates theWorkerinstance and correlates each message with a uniquerequestId, turning asynchronous worker messaging into a standardPromisecompatible withengine.resource(). - Automatic cancellation of stale runs (
AbortSignal): If the user updates filter parameters before the worker finishes the previous job,resourceautomatically triggersabort(), rejecting the outdated promise and ignoring late worker replies. - Zero-copy buffer transfers (
Transferable): LargeArrayBufferpayloads can be transferred across threads without memory cloning.
Practical Example: Background Parsing & Aggregation
1. Worker Script (analytics.worker.ts)
typescript
export interface WorkerRequest {
requestId: number
rows: number[]
threshold: number
}
export interface WorkerSuccessResponse {
requestId: number
ok: true
result: {
matchedCount: number
average: number
}
}
export interface WorkerErrorResponse {
requestId: number
ok: false
error: string
}
export type WorkerResponse = WorkerSuccessResponse | WorkerErrorResponse
self.onmessage = (event: MessageEvent<WorkerRequest>) => {
const { requestId, rows, threshold } = event.data
try {
// Simulate a CPU-intensive pass over a large dataset in a background thread
let sum = 0
let matchedCount = 0
for (let i = 0; i < rows.length; i += 1) {
const val = rows[i]
if (val >= threshold) {
sum += val
matchedCount += 1
}
}
const average = matchedCount > 0 ? sum / matchedCount : 0
const response: WorkerSuccessResponse = {
requestId,
ok: true,
result: { matchedCount, average },
}
self.postMessage(response)
} catch (err: unknown) {
const response: WorkerErrorResponse = {
requestId,
ok: false,
error: err instanceof Error ? err.message : 'Unknown worker error',
}
self.postMessage(response)
}
}2. Reactive Service Wrapper (WorkerAnalyticsService.ts)
typescript
import { AbstractService } from '@pravosleva/reactive-engine'
import type { WorkerRequest, WorkerResponse } from './analytics.worker.js'
interface PendingTask {
resolve: (value: { matchedCount: number; average: number }) => void
reject: (reason: unknown) => void
}
export class WorkerAnalyticsService extends AbstractService {
// Reactive input parameters for background computation
public dataset = this.engine.signal<number[]>([], 'worker:dataset')
public threshold = this.engine.signal<number>(50, 'worker:threshold')
private worker: Worker | null = null
private nextRequestId = 1
private pendingTasks = new Map<number, PendingTask>()
// Combine input signals into a single dependency source for the resource
private computeInput = this.engine.computed(
() => ({
rows: this.dataset.value,
threshold: this.threshold.value,
}),
'worker:computeInput'
)
private getOrCreateWorker(): Worker {
if (this.worker) return this.worker
// Standard bundler syntax (Vite / Webpack 5) for instantiating a module Web Worker
const worker = new Worker(new URL('./analytics.worker.ts', import.meta.url), {
type: 'module',
})
worker.onmessage = (event: MessageEvent<WorkerResponse>) => {
const msg = event.data
const task = this.pendingTasks.get(msg.requestId)
if (!task) return
this.pendingTasks.delete(msg.requestId)
if (msg.ok) {
task.resolve(msg.result)
} else {
task.reject(new Error(msg.error))
}
}
worker.onerror = (event: ErrorEvent) => {
const err = new Error(event.message || 'Critical Web Worker thread error')
for (const task of this.pendingTasks.values()) {
task.reject(err)
}
this.pendingTasks.clear()
}
this.worker = worker
return worker
}
/**
* Dispatches a job to the Web Worker and binds its lifecycle to an AbortSignal.
*/
private runInWorker(
rows: number[],
threshold: number,
signal: AbortSignal
): Promise<{ matchedCount: number; average: number }> {
if (signal.aborted) {
return Promise.reject(new DOMException('Aborted before worker postMessage', 'AbortError'))
}
const worker = this.getOrCreateWorker()
const requestId = this.nextRequestId++
return new Promise((resolve, reject) => {
const onAbort = () => {
this.pendingTasks.delete(requestId)
reject(new DOMException('Worker calculation aborted', 'AbortError'))
}
signal.addEventListener('abort', onAbort, { once: true })
this.pendingTasks.set(requestId, {
resolve: (res) => {
signal.removeEventListener('abort', onAbort)
resolve(res)
},
reject: (err) => {
signal.removeEventListener('abort', onAbort)
reject(err)
},
})
const payload: WorkerRequest = { requestId, rows, threshold }
worker.postMessage(payload)
})
}
// Automatically re-runs computation when dataset or threshold changes
// and cancels any in-flight job on new updates
public summaryResource = this.engine.resource(
async ({ rows, threshold }, abortSignal) => {
if (rows.length === 0) {
return { matchedCount: 0, average: 0 }
}
return this.runInWorker(rows, threshold, abortSignal)
},
this.computeInput,
'worker:summaryResource'
)
// Cleanly terminate the worker thread when disposing the module or engine
public dispose() {
this.summaryResource.abort()
for (const task of this.pendingTasks.values()) {
task.reject(new DOMException('Worker disposed', 'AbortError'))
}
this.pendingTasks.clear()
if (this.worker) {
this.worker.terminate()
this.worker = null
}
}
}3. Usage in Vanilla JS or UI Layer
typescript
import { ReactiveEngine } from '@pravosleva/reactive-engine'
import { WorkerAnalyticsService } from './WorkerAnalyticsService.js'
const engine = new ReactiveEngine()
const analytics = engine.inject(WorkerAnalyticsService)
// Observe background computation status
engine.effect(() => {
const { loading, data, error } = analytics.summaryResource.value
if (loading) {
console.log('Computing inside Web Worker (Main Thread remains responsive)...')
return
}
if (error) {
console.error('Computation error:', error.message)
return
}
if (data) {
console.log(`Matched items: ${data.matchedCount}, average: ${data.average.toFixed(2)}`)
}
})
// Generate 500,000 numbers and trigger background aggregation
analytics.dataset.value = Array.from({ length: 500_000 }, () => Math.random() * 100)
// Changing the threshold immediately cancels the in-flight calculation via AbortSignal
// and starts a fresh run with the updated threshold
analytics.threshold.value = 75Production Best Practices
- Combine with
withDebouncefor UI sliders: If a user drags a range slider to updatethreshold, wraprunInWorkerwithwithDebounce(..., { delay: 150 })so the worker is not flooded with dozens of cancelled array passes per second. - Use
Transferable(Float64Array/ArrayBuffer) for massive datasets: Standardworker.postMessage(rows)clones arrays via the Structured Clone algorithm. For millions of numbers, store data in aFloat64Arrayand transfer buffer ownership without copying memory:worker.postMessage(payload, [rows.buffer]). - Always call
worker.terminate()insidedispose(): Browsers do not automatically shut down aWorkerthread when a service is garbage-collected. Always invokeworker.terminate()when destroying the engine instance or leaving the page.