[niranjan94]

Summary

Adds an optional workOptions map to withQueues() so a consumer can tune individual queues (concurrency, batch size, polling) instead of every queue sharing pg-boss defaults. Entries are keyed by queue name and forwarded to boss.work(name, options, handler). Queues omitted from the map keep the current behavior: a single worker fetching one job at a time.

createApp()
  .withQueues(registry, {
    workOptions: {
      concierge: { localConcurrency: 5 }, // 5 independent workers for this queue
    },
  })
  .buildConsumer();

Motivation

Today registerQueueWorkers calls boss.work(name, handler) with no options for every queue, so each queue runs a single serial worker (batchSize: 1). A reactive, high-volume queue whose handler is long-running (e.g. one that launches and polls an external task) can be head-of-line-blocked by a single slow or stuck job: everything behind it waits until that handler returns. Meanwhile low-traffic queues are fine as single workers.

localConcurrency (pg-boss spawns N independent workers per node for that queue) is exactly the right lever, but there was no seam to pass it. This adds one.

Changes

File	Change
src/queue/consumer.ts	registerQueueWorkers takes an optional workOptions map and forwards a queue's entry to the three-arg boss.work() overload; falls back to the two-arg overload when absent. Adds exported QueueWorkOptions type.
src/builder.ts	WithQueueOptions is now generic over the registry and gains a workOptions field (keys checked against queue names); withQueues() accepts it; buildConsumer() forwards it.
src/queue/__tests__/register-queue-workers.test.ts	New unit tests: creates each queue, uses the two-arg overload without options, forwards options via the three-arg overload when present, and still dispatches jobs to the handler.
src/queue/__tests__/consumer-builder.test.ts	Adds a builder-level test that withQueues(registry, { workOptions }) builds a consumer.

Backward compatibility

Additive and non-breaking. QueueRegistry, QueueJobHandler, and JobDataFor are untouched, so existing withQueues(registry) calls compile and behave exactly as before. The new WithQueueOptions type parameter defaults to QueueRegistry, so existing references to the type keep working.

Testing

• pnpm build:check (tsc --noEmit): clean
• pnpm test:unit: 273 passed (21 files)
• pnpm lint: clean (2 pre-existing warnings in tests/e2e/error-handling.test.ts, unrelated)

Follow-up

A minor release (e.g. 1.16.0) is needed to consume workOptions downstream. Left out of this PR to match the repo's convention of separate chore: bump version commits.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
telaio-docs	Ready	Preview, Comment	Jul 14, 2026 7:07am