Rationale
Every production system grows a job queue (Oban in Elixir, BullMQ in Node). The TS actor ecosystem has none that is cluster-native. actor-ts already has the building blocks: persistence for durability, sharding for distribution, retry/backoff patterns, priority mailboxes — actor-ts/jobs composes them into a batteries-included module with zero new runtime dependencies.
Scope
- Durable job definitions with at-least-once workers: retries with backoff, priorities, uniqueness keys (dedup), scheduled + cron jobs.
- Persistence via PersistentActor/DurableState on any configured journal; distribution via ClusterSharding; failed-beyond-max-attempts jobs go to the dead-letter queue (see the DLQ issue) instead of vanishing.
JobQueueOptions per the AGENTS.md options family (JobQueueOptionsType/Builder/Validator; explicit > HOCON actor-ts.jobs.* > defaults); Prometheus metrics (enqueued/succeeded/failed/retried, queue depth, latency).- Subpath export
"./jobs".
import { JobQueue } from 'actor-ts/jobs';
const jobs = JobQueue.start(system, { journal: 'default' });
jobs.define('send-invoice',
async ({ orderId }: { orderId: string }) => { /* … */ },
{ retries: { maxRetries: 5, backoff: 'exponential' },
priority: 3,
unique: job => job.orderId });
await jobs.enqueue('send-invoice', { orderId: 'o-1' });
jobs.cron('cleanup', '0 3 * * *', {}); // survives restartsDocumentation
Own docs chapter (quickstart, concepts, config reference — EN + DE) + runnable example; JSDoc; CHANGELOG. (Docs DoD per CONTRIBUTING.)
Acceptance
- Jobs survive node restart and shard rebalance (MultiNodeSpec); uniqueness prevents duplicates under concurrent enqueue; cron fires after restart; retry/backoff under ManualScheduler.
Non-goals
Admin UI (DevTools suite later); exactly-once execution (documented as at-least-once + idempotent handlers).
Relates
Depends on #168 (Grain Reminders) for durable cron timers — sensible to land first. #222/DLQ issue. Improvement program M5.
Rationale
Every production system grows a job queue (Oban in Elixir, BullMQ in Node). The TS actor ecosystem has none that is cluster-native. actor-ts already has the building blocks: persistence for durability, sharding for distribution, retry/backoff patterns, priority mailboxes —
actor-ts/jobscomposes them into a batteries-included module with zero new runtime dependencies.Scope
JobQueueOptionsper the AGENTS.md options family (JobQueueOptionsType/Builder/Validator; explicit > HOCONactor-ts.jobs.*> defaults); Prometheus metrics (enqueued/succeeded/failed/retried, queue depth, latency)."./jobs".Documentation
Own docs chapter (quickstart, concepts, config reference — EN + DE) + runnable example; JSDoc; CHANGELOG. (Docs DoD per CONTRIBUTING.)
Acceptance
Non-goals
Admin UI (DevTools suite later); exactly-once execution (documented as at-least-once + idempotent handlers).
Relates
Depends on #168 (Grain Reminders) for durable cron timers — sensible to land first. #222/DLQ issue. Improvement program M5.