Pre-requisites

The @verful/scheduler package requires @adonisjs/core >= 5.9.0

Setup

Install the package from the npm registry as follows.

npm i @verful/scheduler
# or
yarn add @verful/scheduler

Next, configure the package by running the following ace command.

node ace configure @verful/scheduler

Defining Scheduled Tasks

You may define all of your scheduled tasks in the start/tasks.ts preloaded file. To get started, let's take a look at an example. In this example, we will schedule a closure to be called every day at midnight. Within the closure we will execute a database query to clear a table:

import Scheduler from '@ioc:Verful/Scheduler'
import Database from '@ioc:Adonis/Lucid/Database'

Scheduler.call(async () => {
  Database.from('recent_users').delete()
}).daily()

Scheduling Ace Commands

In addition to scheduling closures, you may also schedule Ace commands and system commands. For example, you may use the command method to schedule an Ace command using the commands name.

import Scheduler from '@ioc:Verful/Scheduler'

Scheduler.command('queue:flush').everyFiveMinutes()

Scheduling Shell Commands

The exec method may be used to issue a command to the operating system:

import Scheduler from '@ioc:Verful/Scheduler'

Scheduler.exec('node script.js').daily()

Schedule Frequency Options

We've already seen a few examples of how you may configure a task to run at specified intervals. However, there are many more task schedule frequencies that you may assign to a task:

These methods may be combined with additional constraints to create even more finely tuned schedules that only run on certain days of the week. For example, you may schedule a command to run weekly on Monday:

import Scheduler from '@ioc:Verful/Scheduler'

// Run once per week on Monday at 1 PM...
Scheduler.call(() => {
    // ...
}).weekly().mondays().at('13:00')

// Run hourly from 8 AM to 5 PM on weekdays...
Scheduler.command('foo')
         .weekdays()
         .hourly()
         .between('8:00', '17:00')

A list of additional schedule constraints may be found below:

Day Constraints

The days method may be used to limit the execution of a task to specific days of the week. For example, you may schedule a command to run hourly on Sundays and Wednesdays:

import Scheduler from '@ioc:Verful/Scheduler'

Scheduler.command('emails:send')
         .hourly()
         .days([0, 3])

Between Time Constraints

The between method may be used to limit the execution of a task based on the time of day:

import Scheduler from '@ioc:Verful/Scheduler'

Scheduler.command('emails:send')
         .hourly()
         .between('7:00', '22:00')

Similarly, the unlessBetween method can be used to exclude the execution of a task for a period of time:

import Scheduler from '@ioc:Verful/Scheduler'

Scheduler.command('emails:send')
         .hourly()
         .unlessBetween('23:00', '4:00')

Truth Test Constraints

The when method may be used to limit the execution of a task based on the result of a given truth test. In other words, if the given closure returns true, the task will execute as long as no other constraining conditions prevent the task from running:

import Scheduler from '@ioc:Verful/Scheduler'

Scheduler.command('emails:send')
         .daily()
         .when(() => true);

The skip method may be seen as the inverse of when. If the skip method returns true, the scheduled task will not be executed:

import Scheduler from '@ioc:Verful/Scheduler'

Scheduler.command('emails:send')
         .daily()
         .skip(() => true);

When using chained when methods, the scheduled command will only execute if all when conditions return true.

Environment Constraints

The environments method may be used to execute tasks only on the given environments (as defined by the NODE_ENV environment variable):

import Scheduler from '@ioc:Verful/Scheduler'

Scheduler.command('emails:send')
         .daily()
         .environments(['staging', 'production']);

Running the Scheduler

Run the scheduler:work ace command, it doesn't need to be put into a cron job, as the scheduler will process the jobs as the time passes