@nest-native/jobs

[!NOTE] v0.x — early but stable. The producer, claimer, handler discovery, and the three Drizzle stores are implemented and tested at 100% coverage. SQLite, Postgres, and MySQL are supported.

The problem it solves

Most NestJS apps grow a first background job long before they need a queueing system: send a welcome email after signup, generate a report, retry a flaky webhook. The official NestJS answer is @nestjs/bullmq — which means operating Redis for what is often a handful of jobs a minute. And because Redis is a second system, the classic dual-write bug appears on day one: the signup commits but the process crashes before queue.add() — the email is never sent. Or queue.add() succeeds and the transaction rolls back — a welcome email for a user that does not exist.

@nest-native/jobs stores jobs in the same Drizzle database your app already has:

• Transactional enqueue — enqueue() inserts the job row inside your business transaction (via @nestjs-cls/transactional). The job exists if and only if your writes committed.
• Nest-native execution — declare a class with @JobHandler('email.welcome'), register it as a provider, and the claimer dispatches to it with full DI. Handlers are discovered at bootstrap; duplicate names throw at startup.
• Retries, delays, priorities, unique jobs — jittered exponential backoff (or RetryableError's explicit delayMs), PermanentError to fail fast, runAt/delayMs scheduling, priority ordering, and uniqueKey dedup among active jobs.
• DB-stored cron schedules — recurring enqueue driven by a job_schedules row: survives restarts, safe across instances (atomic claim), runtime-editable via JobSchedulesService. Missed occurrences are skipped (at most one catch-up).
• One runtime dependency — croner does the cron math; everything else (Nest, Drizzle, your driver) is a peer you already installed.

Install

npm install @nest-native/jobs
# plus your driver (peer dependencies):
npm install drizzle-orm @nestjs-cls/transactional better-sqlite3   # or pg / mysql2

Compatibility

| Peer | Supported range | Notes | | --- | --- | --- | | Node.js | >=22 (>=22.12 with NestJS 12 — see the note below the table) | engines is >=22; the 12 end of the NestJS range raises the floor, the 11 end does not | | @nestjs/common, @nestjs/core | ^11.0.0 \|\| ^12.0.0 | 12 is ESM-only; tested by a dedicated CI leg | | @nestjs-cls/transactional | ^3.0.0 | on NestJS 12 you need >=3.3.0 (with nestjs-cls >=6.3.0) — earlier minors declare @nestjs/core >= 10 < 12 | | drizzle-orm | ^0.44.0 \|\| ^0.45.0 | | | better-sqlite3 | ^11.0.0 \|\| ^12.0.0 \|\| ^13.0.0 | optional; 13 requires Node >=22 | | pg | ^8.0.0 | optional | | mysql2 | ^3.0.0 | optional |

The Node.js floor depends on which end of the NestJS range you are on. NestJS 11 runs on any Node.js >=22. NestJS 12 is ESM-only; a CommonJS app — the usual NestJS build, and this package itself — loads it through Node's require(esm), which is behind a flag before Node.js 22.12.0, so NestJS 12 needs Node.js >=22.12. engines stays >=22 because the 11 end does not need more; Node 22.0–22.11 satisfies it and still cannot load NestJS 12. CI's NestJS 12 leg runs on a current 22.x.

Entry points

| Import | Contents | | --- | --- | | @nest-native/jobs | core engine — JobsService (enqueue), JobsClaimer + runWorkerLoop, @JobHandler + JobsHandlerExplorer, RetryableError/PermanentError, the JobStore seam, JobsModule | | @nest-native/jobs/sqlite | better-sqlite3 (synchronous) store + the jobs table definition | | @nest-native/jobs/postgres | node-postgres (async) store + table definition | | @nest-native/jobs/mysql | mysql2 (async) store + table definition | | @nest-native/jobs/testing | drainJobs + RecordingJobHandler for hermetic tests |

Usage

// app.module.ts — wire CLS + the dialect store once
JobsModule.forRoot({
  drizzleInstanceToken: DRIZZLE,
  store: new SqliteJobStore(),
});

// user.service.ts — enqueue inside the business transaction
@Injectable()
export class UserService {
  constructor(
    @InjectTransaction() private readonly db: AppDatabase,
    private readonly jobs: JobsService<SqliteJobStore>,
  ) {}

  @Transactional()
  register(email: string) {
    this.db.insert(users).values({ email }).run();
    this.jobs.enqueue({
      name: 'email.welcome',
      payload: { email },
      uniqueKey: `welcome:${email}`, // dedup among active jobs
    });
    // both rows commit atomically; a throw rolls both back
  }
}

// welcome-email.handler.ts — executed by the claimer, with full DI
@JobHandler('email.welcome')
@Injectable()
export class WelcomeEmailHandler implements JobHandler {
  async handle(payload: Record<string, unknown>, ctx: JobContext) {
    await this.mailer.send(String(payload.email)); // throw RetryableError / PermanentError to steer retries
  }
}

// worker (same process or a dedicated one)
const controller = new AbortController();
void runWorkerLoop(app.get(JobsClaimer), { signal: controller.signal });

Delivery is at-least-once: a worker crash mid-job means the row is reclaimed after stuckTimeoutMs and run again. Make handlers idempotent or key their side effects on ctx.jobId.

The uniqueKey contract

uniqueKey means "unique among active jobs", identically on all three dialects: a full unique index on (name, unique_key), and terminal transitions (completed, failed) clear the key. Enqueueing a duplicate (name, uniqueKey) while one is pending/processing is a no-op that returns the existing row; once that job finishes, the key is free again. Jobs without a uniqueKey never collide.

Cron schedules (0.2+)

Recurring work driven by rows in your database — survives restarts, safe across instances (atomic claim), runtime-editable. Opt in by adding the jobSchedules table to your Drizzle schema and passing a schedule store:

JobsModule.forRoot({
  drizzleInstanceToken: DRIZZLE,
  store: new SqliteJobStore(),
  scheduleStore: new SqliteScheduleStore(), // opt-in: omit and nothing changes
});

schedules.upsert({
  name: 'nightly-report',      // unique identity (upsert key)
  jobName: 'report.build',     // the @JobHandler each occurrence runs
  cron: '0 3 * * *',           // croner syntax; timezone: IANA name, default UTC
  uniqueKey: 'nightly-report', // optional: no overlap pile-up while one runs
});

Firing is an atomic compare-and-swap plus the occurrence insert in one store transaction — exactly one instance wins each occurrence. Missed occurrences are skipped (at most one catch-up). An occurrence exhausting its retries never touches the schedule. Full details: the Cron Schedules docs page.

Honest comparison

| | BullMQ (@nestjs/bullmq) | pg-boss | @nest-native/jobs | | --- | --- | --- | --- | | Backing store | Redis (required) | Postgres only | the Drizzle DB you already run — SQLite, Postgres, or MySQL | | NestJS integration | official wrapper module | none (framework-agnostic) | native — module, DI, @JobHandler decorators | | Enqueue in your DB transaction | no (Redis is a second system) | yes (raw SQL in your tx) | yes — first-class, via @nestjs-cls/transactional | | Delivery | Redis push (blocking ops) | polling + LISTEN/NOTIFY | polling claimer | | Throughput | very high | high | right-sized — polling batches, fine for most apps' background work | | Repeatable / cron jobs | yes | yes | yes — DB-stored schedules (JobSchedulesService) | | Dashboards, rate limiting | yes | partial | no | | Runtime dependencies | Redis server + client | pg | one — croner (the rest are peers you already have) |

If you need tens of thousands of jobs per second, sandboxed processors, or a dashboard, use BullMQ — it is excellent at that. If you run Postgres without Nest, pg-boss is battle-tested. This library is for the large middle: NestJS + Drizzle apps that want reliable background jobs without operating another system.

Non-goals (v0.2)

• Dashboards / UI, rate limiting, concurrency groups.
• LISTEN/NOTIFY push — the claimer polls; pollIntervalMs is your latency knob.
• Redis-class throughput — this is a polling claimer over your relational DB, by design.

Part of the nest-native family. Not affiliated with the NestJS core team. MIT licensed.