Nestjs SchedulingSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: nestjs-scheduling
description: Implement distributed cron jobs with Redis-based locking and BullMQ offloading in NestJS. Use when adding @Cron scheduled tasks, preventing duplicate runs across pods, or delegating heavy work to queue workers.
metadata:
  triggers:
    files:
    - '**/*.service.ts'
    keywords:
    - "@Cron"
    - CronExpression
    - ScheduleModule
---
# Task Scheduling & Jobs

## **Priority: P1 (HIGH)**


## Workflow: Add Scheduled Task

1. **Register ScheduleModule** — Import `ScheduleModule.forRoot()` in AppModule.
2. **Create cron handler** — Decorate service method with `@Cron(CronExpression.*)`.
3. **Add distributed lock** — Apply Redis lock decorator to prevent multi-pod duplication.
4. **Offload heavy work** — Push job IDs to BullMQ; let workers process them.
5. **Wrap in try/catch** — Uncaught exceptions in cron handlers crash entire Node process.
6. **Verify** — Test with 2+ instances to confirm only one acquires lock.

## Problem & Solution

- **Problem**: `@Cron()` runs on **every** instance. In K8s with 3 pods, your "Daily Report" runs 3 times.
- **Solution**: **Distributed Locking** using Redis.
 - **Pattern**: Using decorator to wrap cron method.
 - **Logic**: `SET resource_name my_random_value NX PX 30000` (Redis Atomic Set).

## Cron Decorator Pattern

- **Implementation**:

 See [implementation examples](references/example.md)

- **Tools**: Use `nestjs-redlock` or custom Redis wrapper via `redlock` library.

## Cron-to-Queue Offload

See [implementation examples](references/example.md)

## Job Robustness

- **Isolation**: Never perform heavy processing inside Cron handler.
 - **Pattern**: Cron -> Push Job ID to Queue (BullMQ) -> Worker processes it.
 - **Why**: Cron schedulers can get blocked by Event Loop; Workers scalable.
- **Error Handling**: Wrap ALL cron logic in `try/catch`. Uncaught exceptions in Cron job can crash entire Node process.


## Anti-Patterns

- **No unguarded cron logic**: Always wrap in `try/catch`; uncaught exceptions crash entire Node process.
- **No direct cron processing**: Push to BullMQ queue; workers scalable, cron handlers not.
- **No bare @Cron in multi-pod**: Use distributed locking (redlock) to prevent duplicate concurrent runs.

## Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- crash

## Remediation anchors

- Remediation anchors: BullMQ, event loop, worker

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.