s-m-r-t
Open the s-m-r-t source on GitHub Switch to dark color scheme
← All packages
Agents & runtime v0.57.40

@happyvertical/smrt-jobs

Persistent background work, schedules, retries, runners, queue controls, and operational visibility.

Source ↗

What it gives you

Persistent background work, schedules, retries, runners, queue controls, and operational visibility.

  1. 01An opt-in allowlist for the methods a job row may call
  2. 02A per-tenant ceiling on in-flight jobs
  3. 03Retry counts clamped rather than trusted
  4. 04Automatic retention for terminal jobs and job events

Build a job before you enqueue it

The fluent builder composes delay(), priority(), retries(), queue(), and timeout() before enqueue(); bg() is the short form for background work. Delivery is at least once. timeoutBehavior chooses fail, warn, or kill, so idempotency belongs in the job method.

Schedules use local wall-clock time

ScheduleRunner fires forward once: cron matching uses local time, is not timezone-aware, and does not backfill missed runs. Worker liveness uses a process-global live set, an off-loop ticker, and lease recovery. ForgeDeliveryCollection and ForgeProjectionRuntime provide durable projections and dead-letter replay.

Say which methods a job may call

A persisted job row names an object type and a method, so the runner must know which methods are reachable. Mark a method with the backgroundEligible decorator. For non-decorator code, call markBackgroundEligible. These operations add an allowlist to the class. A class that marks nothing keeps the default behavior. After one method is marked, the runner refuses every method outside the list.

One tenant cannot drain the queue

Enqueueing counts the non-terminal jobs for a tenant and refuses another job above the limit. The default limit is ten thousand, and each call or job builder can change it. A value of zero disables the check. Jobs without a tenant do not count against the limit. Requested retry counts are clamped to the supported maximum. Thus, a misconfigured caller cannot pin a worker on a poison job.

Terminal outcomes commit with their event

Completion, permanent failure, timeout, stale-worker recovery, and cancel update the job row and append its versioned event in one transaction. If either write fails, neither commits. listTerminalOutcomes on the event collection requires an explicit tenant, reads newest first, and returns only the safe terminal shape without arguments, results, or raw errors.

Retention starts after the runner is stable

TaskRunner schedules its first retention sweep one interval after start, never at startup. The default policy keeps completed or canceled jobs for seven days. It keeps failed jobs and events for thirty days. Dry-run cleanup is available before a deletion policy changes.

Continue from the contract

Related stories and guides

Features See the application outcomes that packages provide. All guides Find a task procedure that uses this part of the framework.