# nestjs-schedule

> nestjs distributed timer schedule lib

Latest version **0.1.8** (published 2024-05-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install nestjs-schedule
pnpm add nestjs-schedule
yarn add nestjs-schedule
bun add nestjs-schedule
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.8 |
| Published | 2024-05-24 |
| First published | 2021-05-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 59.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | yanqic |
| Maintainers | yanqic |
| Keywords | nestjs, schedule, distributed, cluster |

## Links

- npm: https://www.npmjs.com/package/nestjs-schedule
- Repository: https://github.com/yanqic/nest-schedule
- Homepage: https://github.com/yanqic/nest-schedule#readme
- Issues: https://github.com:yanqic/nest-schedule/issues
- npm.io page: https://npm.io/package/nestjs-schedule

## Dependencies (2)

- [node-schedule](https://npm.io/package/node-schedule.md) ^2.0.0
- [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.1.13

## Recent versions

- 0.1.8 (latest) — 2024-05-24
- 0.1.7 — 2023-03-13
- 0.1.6 — 2022-04-29
- 0.1.5 — 2022-04-28
- 0.1.4 — 2022-04-26
- 0.1.2 — 2022-04-25
- 0.1.1 — 2022-04-25
- 0.1.0 — 2022-04-25
- 0.0.6 — 2022-01-06
- 0.0.5 — 2022-01-06
- 0.0.4 — 2022-01-06
- 0.0.3 — 2021-08-17
- 0.0.2 — 2021-05-31
- 0.0.1 — 2021-05-31

## README

<p align="center">
  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo_text.svg" width="320" alt="Nest Logo" /></a>
</p>

# Nestjs Schedule

<p align="center">
    <a href="https://www.npmjs.com/~nestjs-schedule" target="_blank"><img src="https://img.shields.io/npm/v/nestjs-schedule.svg" alt="NPM Version"/></a>
    <a href="https://www.npmjs.com/~nestjs-schedule" target="_blank"><img src="https://img.shields.io/npm/l/nestjs-schedule.svg" alt="Package License"/></a>
    <a href="https://www.npmjs.com/~nestjs-schedule" target="_blank"><img src="https://img.shields.io/npm/dm/nestjs-schedule.svg" alt="NPM Downloads"/></a>
</p>

## Description

Distributed Schedule module for [Nest.js](https://github.com/nestjs/nest) based on the node-schedule package.

## Installation

```bash
$ npm i --save nestjs-schedule
```

## Usage

```typescript
import { Module } from '@nestjs/common';
import { ScheduleModule } from 'nestjs-schedule';

@Module({
    imports: [ScheduleModule.forRoot({
        // Optional: Import external dependent modules if you need
        imports: [MyLockerModule]
        // Optional: Inject your global custom lock
        useClass: MyScheduleLocker
    })],
})
export class AppModule {}
```

```typescript
import { Injectable, Logger } from '@nestjs/common';
import { Cron, Timeout, Interval } from 'nestjs-schedule';

@Injectable()
export class TasksService {
    private readonly logger = new Logger(TasksService.name);

    @Cron('45 * * * * *')
    handleCron() {
        this.logger.debug('Called when the current second is 45');
    }

    @Interval(5000)
    handleInterval() {
        this.logger.debug('Called every 5 seconds');
    }

    @Timeout(5000)
    handleTimeout() {
        this.logger.debug('Called after 5 seconds');
    }
}
```

### Dynamic Schedule Job

```typescript
import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { InjectSchedule, Schedule } from 'nestjs-schedule';

@Injectable()
export class TasksService implements OnModuleInit {
    private readonly logger = new Logger(TasksService.name);

    constructor(@InjectSchedule() private readonly schedule: Schedule) {}

    execute() {
        this.logger.debug('execute dynamic job');
    }

    onModuleInit() {
        this.schedule.createIntervalJob(this.execute.bind(this), 3000, {
            name: 'test_job',
        });
        this.schedule.deleteIntervalJob('test_job');
    }
}
```

### Distributed Support

1. Implements Locker interface

```typescript
import { Locker } from 'nestjs-schedule';
import { Injectable } from '@nestjs/common';

@Injectable()
export class ScheduleLocker implements Locker {

    release(jobName: string): any {}

    async tryLock(jobName: string): Promise<boolean> {
        // use redis lock or other methods
        return true;
    }
}
```

2. Use your locker

```typescript
import { Injectable, Logger } from '@nestjs/common';
import { Cron, UseLocker } from '@nestjs-schedule';
import { ScheduleLocker } from './schedule-locker';

@Injectable()
export class TasksService {
    private readonly logger = new Logger(TasksService.name);

    @Cron('45 * * * * *')
    // remove it if you want to use the lock which injected forRoot
    @UseLocker(ScheduleLocker)
    handleCron() {
        this.logger.debug('Called when the current second is 45');
    }
}
```

## API

### class ScheduleModule

#### static forRoot\(\): DynamicModule

Import schedule module.

### class Schedule

#### createTimeoutJob\(methodRef: Function, timeout: number, options?: TimeoutOptions\)

Dynamic create a timeout job.

| field     | type         | required | description          |
| --------- | ------------ | -------- | -------------------- |
| methodRef | Function     | true     | job method           |
| timeout   | number       | true     | milliseconds         |
| options   |              | false    | see decorators       |
| locker    | Locker/false | false    | custom lock instance |

> If the locker is configured as false, the default lock will be ignored
#### createIntervalJob\(methodRef: Function, timeout: number, options?: IntervalOptions\)

Dynamic create a interval job.

| field     | type         | required | description          |
| --------- | ------------ | -------- | -------------------- |
| methodRef | Function     | true     | job method           |
| interval  | number       | true     | milliseconds         |
| options   |              | false    | see decorators       |
| locker    | Locker/false | false    | custom lock instance |

#### createCronJob\(rule: string | number | Date | CronObject | CronObjLiteral, methodRef, options?: CronOptions\)

Dynamic create a cron job.

| field     | type                                         | required | description          |
| --------- | -------------------------------------------- | -------- | -------------------- |
| rule      | Date string number CronObject CronObjLiteral | true     | the cron rule        |
| methodRef | Function                                     | true     | job method           |
| options   |                                              | false    | see decorators       |
| locker    | Locker/false                                 | false    | custom lock instance |

#### deleteTimeoutJob\(name: string\)

Delete a timeout job

#### deleteIntervalJob\(name: string\)

Delete a interval job

#### deleteCronJob\(name: string\)

Delete a cron job

#### getTimeoutJobs\(\): TimeoutJobOptions[]

Get all timeout jobs

#### getIntervalJobs\(\): IntervalJobOptions[]

Get all interval jobs

#### getCronJobs\(\): CronJobOptions[]

Get all cron jobs

## Decorators

### Cron(rule: string | number | Date | CronObject | CronObjLiteral, options?: CronOptions): MethodDecorator

Schedule a cron job.

| field           | type                                         | required | description                                  |
| --------------- | -------------------------------------------- | -------- | -------------------------------------------- |
| rule            | Date string number CronObject CronObjLiteral | true     | The cron rule                                |
| rule.dayOfWeek  | number                                       | true     | Timezone                                     |
| options.name    | string                                       | false    | The unique job key.**Distributed lock need it**                           |
| options.retries | number                                       | false    | the max retry count, default is -1 not retry |
| options.retry   | number                                       | false    | the retry interval, default is 5000          |

[CronObject CronObjLiteral](https://github.com/yanqic/nest-schedule/blob/main/lib/interfaces/cron-options.interface.ts)

### Interval(timeout: number): MethodDecorator

### Interval(name: string, timeout: number): MethodDecorator

### Interval(name: string, timeout: number, options?: IntervalOptions): MethodDecorator

Schedule a interval job.

| field             | type    | required | description                                  |
| ----------------- | ------- | -------- | -------------------------------------------- |
| timeout           | number  | true     | milliseconds                                 |
| options.retries   | number  | false    | the max retry count, default is -1 not retry |
| options.retry     | number  | false    | the retry interval, default is 5000          |
| options.immediate | boolean | false    | executing job immediately                    |

### Timeout(timeout: number): MethodDecorator

### Timeout(name: string, timeout: number): MethodDecorator

### Timeout(name: string, timeout: number, options?: TimeoutOptions): MethodDecorator

Schedule a timeout job.

| field             | type    | required | description                                  |
| ----------------- | ------- | -------- | -------------------------------------------- |
| timeout           | number  | true     | milliseconds                                 |
| options.retries   | number  | false    | the max retry count, default is -1 not retry |
| options.retry     | number  | false    | the retry interval, default is 5000          |
| options.immediate | boolean | false    | executing job immediately                    |

### InjectSchedule(): PropertyDecorator

Inject Schedule instance

### UseLocker(locker: Locker | Function): MethodDecorator

Set a distributed locker for job.

## Stay in touch

-   Author - [yanqic](https://github.com/yanqic)

## License

NestCloud is [MIT licensed](LICENSE).

---
_Source: https://npm.io/package/nestjs-schedule · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._