Page:
worker HowTo
Pages
Home
ai Overview
ai gemini Overview
api HowTo
api Overview
api client HowTo
api client Overview
api server HowTo
api server Overview
api server express HowTo
app HowTo
app Overview
auth HowTo
auth Overview
auth basic HowTo
auth basic Overview
auth firebase HowTo
auth firebase Overview
auth oidc Overview
auth pocketbase HowTo
auth pocketbase Overview
auth supabase HowTo
auth supabase Overview
backend HowTo
backend Overview
backend firestore Overview
backend migrations Overview
backend postgres Overview
backend restapi Overview
backend restapi recipes Overview
backend sqlite HowTo
backend sqlite Overview
cache Overview
cache redis Overview
cloudwrapper HowTo
cloudwrapper Overview
cloudwrapper firebase HowTo
cloudwrapper firebase Overview
cloudwrapper supabase HowTo
cloudwrapper supabase Overview
code Overview
code github Overview
core HowTo
core Overview
core cli HowTo
core cli Overview
gateway upstream express HowTo
gateway upstream express Overview
i18n HowTo
i18n Overview
i18n en HowTo
i18n en Overview
i18n fr HowTo
i18n fr Overview
log HowTo
log Overview
messaging HowTo
messaging Overview
messaging firebase HowTo
messaging firebase Overview
queue HowTo
queue Overview
queue amqp HowTo
queue amqp Overview
queue aws HowTo
queue aws Overview
queue gcp HowTo
queue gcp Overview
storage HowTo
storage Overview
storage firebase HowTo
storage firebase Overview
storage local Overview
storage s3 HowTo
storage s3 Overview
storage supabase HowTo
storage supabase Overview
studio Overview
testing Overview
types HowTo
types Overview
ui Overview
ui form react Overview
ui list HowTo
ui list Overview
ui list react HowTo
ui list react Overview
worker HowTo
worker Overview
No results
1
worker HowTo
GitHub Action edited this page 2026-04-21 15:41:04 +00:00
How To: Using @quatrain/worker
This guide covers common use cases for building background processors and daemons using @quatrain/worker.
Table of Contents
- Setting up a basic Worker
- Executing external CLI commands
- Reporting progress to a backend API
- Using FileSystem Helpers
1. Setting up a basic Worker
The standard pattern for setting up a worker is to define a handler function, and then pass it to Worker.handler() along with configuration options.
import { Worker, HandlerParameters } from '@quatrain/worker'
import { SqsAdapter } from '@quatrain/queue-aws' // Or AmqpQueueAdapter
// 1. Define your processing logic
const messageHandler = async (payload: any) => {
Worker.info('Received a new job to process:', payload.jobId)
// Simulate processing
await new Promise(resolve => setTimeout(resolve, 2000))
Worker.info('Job successfully completed!')
return true // Return true to acknowledge and delete the message from the queue
}
// 2. Configure the worker
const config: HandlerParameters = {
mode: 'queue', // Can be 'queue', 'cli', or 'test'
topic: 'MyTaskQueue',
queueAdapter: new SqsAdapter({
config: {
accesskey: process.env.AWS_KEY,
secret: process.env.AWS_SECRET,
region: 'eu-central-1',
accountid: '1234567890'
}
}),
concurrency: 1 // Process one message at a time
}
// 3. Start the worker loop
Worker.handler(messageHandler, config)
2. Executing external CLI commands
Workers often need to run external binaries (e.g., ffmpeg, imagemagick, or python scripts). The Worker.execPromise method wraps Node.js spawn and pipes the output directly to the Quatrain logger.
import { Worker } from '@quatrain/worker'
async function transcodeVideo(inputPath: string, outputPath: string) {
try {
Worker.info(`Starting transcoding for ${inputPath}`)
// Command, Arguments, Working Directory
await Worker.execPromise(
'ffmpeg',
['-i', inputPath, '-vcodec', 'libx264', outputPath],
'/tmp/worker-dir'
)
Worker.info('Transcoding completed successfully')
} catch (error) {
Worker.error('Transcoding failed!', error.message)
throw error
}
}
3. Reporting progress to a backend API
If you have a central API tracking job progress, you can define an endpoint. The worker will push updates formatted seamlessly.
import { Worker } from '@quatrain/worker'
// Configure the reporting endpoint once
Worker.endpoint = 'https://api.myproject.com/internal/webhooks/worker-events'
async function processData(jobId: string) {
// Fire and forget progress updates
Worker.pushEvent('job.started', { jobId, progress: 0 })
// ... do some work ...
// Or wait for the update to be acknowledged using the async version
await Worker.pushEventAsync('job.completed', {
jobId,
progress: 100,
result: 'Success'
})
}
4. Using FileSystem Helpers
Avoid using standard Node.js fs directly when writing workers; instead, use the unified FileSystem wrapper provided.
import { FileSystem } from '@quatrain/worker'
// Synchronous and asynchronous helpers for common disk operations
const tempDir = FileSystem.createTempDir('my-worker')
console.log(`Created workspace at: ${tempDir}`)
// Check if a path exists
if (FileSystem.exists(tempDir)) {
// Delete a folder and all its contents recursively
FileSystem.remove(tempDir)
}
Core Documentation
Foundations
Storage, Data & Cache
- backend
- backend-firestore
- backend-postgres
- backend-sqlite
- backend-migrations
- storage
- storage-firebase
- storage-s3
- storage-supabase
- storage-local
- cache
- cache-redis
Queue & Messaging
Auth & Cloud
- auth
- auth-firebase
- auth-supabase
- auth-oidc
- auth-pocketbase
- cloudwrapper
- cloudwrapper-firebase
- cloudwrapper-supabase