@recordset/adonis7-scheduler

Task scheduler provider for AdonisJS 7. Run recurring tasks using cron expressions with optional file-based locking for multi-instance deployments.

Built on top of node-schedule and cron-time-generator.

Features

• Cron-based task scheduling with human-readable helpers
• File-based locking to prevent overlapping task execution
• Auto-discovery of task files from a configurable directory
• AdonisJS 7 IoC container integration (dependency injection in tasks)
• make:task scaffolding command
• Graceful shutdown support

Installation

npm install @recordset/adonis7-scheduler
node ace configure @recordset/adonis7-scheduler

The configure command will:

• Register the provider and commands in adonisrc.ts
• Create config/scheduler.ts

Usage

Creating a Task

node ace make:task cleanup_expired

This generates app/tasks/cleanup_expired_task.ts:

import { BaseTask, CronTimeV2 } from "@recordset/adonis7-scheduler/task";

export default class CleanupExpiredTask extends BaseTask {
  static get schedule() {
    return CronTimeV2.everyMinute();
  }

  static get useLock() {
    return false;
  }

  async handle() {
    // Task logic here
  }
}

Running the Scheduler

node ace scheduler:run

The scheduler auto-discovers all task files in the configured tasksPath directory.

Schedule Helpers

CronTimeV2 extends cron-time-generator with sub-minute intervals:

Method	Cron Expression
everySecond()	* * * * * *
everyFiveSeconds()	*/5 * * * * *
everyTenSeconds()	*/10 * * * * *
everyThirtySeconds()	*/30 * * * * *
everyMinute()	* * * * *
everyFiveMinutes()	*/5 * * * *
everyThirtyMinutes()	*/30 * * * *

You can also use any valid cron expression string directly:

static get schedule() {
  return '0 9 * * 1-5' // Weekdays at 9:00 AM
}

All methods from cron-time-generator are also available: everyHour(), everyDay(), everyWeek(), etc.

File Locking

Enable useLock to prevent a task from running concurrently across multiple instances:

export default class HeavyTask extends BaseTask {
  static get schedule() {
    return CronTimeV2.everyFiveMinutes();
  }

  static get useLock() {
    return true;
  }

  async handle() {
    console.log(this.duration()); // e.g. "1.2s"
  }
}

Lock files are stored in tmp/adonis7-scheduler/locks/.

Dependency Injection

Tasks are resolved through the AdonisJS container, so you can use constructor injection:

import { inject } from "@adonisjs/core";
import { BaseTask, CronTimeV2 } from "@recordset/adonis7-scheduler/task";
import UserService from "#services/user_service";

@inject()
export default class NotifyUsersTask extends BaseTask {
  static get schedule() {
    return CronTimeV2.everyHour();
  }

  constructor(private userService: UserService) {
    super();
  }

  async handle() {
    await this.userService.notifyInactiveUsers();
  }
}

Configuration

// config/scheduler.ts
import { defineConfig } from "@recordset/adonis7-scheduler/types";

export default defineConfig({
  tasksPath: "app/tasks",
});

Option	Type	Default	Description
tasksPath	string	'app/tasks'	Directory where task files are located

Ace Commands

Command	Description
make:task <name>	Generate a new task class
scheduler:run	Start the scheduler (stays alive)

License

MIT