Schedulers

Execute functions at a defined time intervals.

A scheduler is a type of decorator that, when applied to a function, causes the function to be executed at a regular interval based on UTC time. The scheduling is typically specified using a cron expression in UTC.

The function itself can perform any action, such as querying a database, sending an email, calling an API, and more.

The @scheduler decorator takes a cron expression as a parameter. A cron expression is a string that defines when the function should run, based on Coordinated Universal Time (UTC). It's important to convert the desired times to UTC when defining the expression. The cron expression is defined as follows:

* * * * * *
| | | | | |
| | | | | day of week
| | | | months
| | | day of month
| | hours
| minutes
seconds (optional)

There are also predefined cron intervals that can be accessed using the CronExpression enum in the Backend SDK.

Creating a scheduler

To create a scheduler, use the @scheduler decorator on a function within a class that extends the base SquidService class:

Backend code

import { CronExpression, SquidService, scheduler } from '@squidcloud/backend';

export class ExampleService extends SquidService {
  @scheduler('sendEmailReminders', CronExpression.EVERY_MINUTE)
  async sendEmailReminders(): Promise<void> {
    // TODO - implement email functionality
  }
}

The exclusive parameter

The @scheduler decorator takes three parameters: the name of the function to run, the interval, and whether the function should be exclusive. The exclusive parameter is a boolean. If it is set to true, only one instance of the scheduler will run at a time. If a new instance is scheduled to run while another instance is still running, then the new instance will be skipped.

For example, if you have a scheduler that runs every minute, and the previous instance of the scheduler is still running after a minute has passed, then the new instance does not run. The default value of exclusive is true.

Backend code

@scheduler('sendEmailReminders', CronExpression.EVERY_MINUTE, true)

If set to false, then an instance of a scheduler will run regardless of whether the previous instance has completed. This means more than one instance might run at a time.

Disabling a scheduler

Schedulers can be disabled and enabled. A disabled scheduler will not run until it is re-enabled. A disabled scheduler maintains its disabled state across redeploys, but all schedulers will be enabled on a deploy that occurs after an undeploy.

Backend code

await this.squid.schedulers.disable('schedulerId');

// Re-enable the scheduler at a later time
await this.squid.schedulers.enable('schedulerId');

You can also see all schedulers with the list method. This returns all the schedulers with its current state (enabled/disabled).

Backend code

await this.squid.schedulers.list();

Exporting the service

To allow Squid to discover the scheduler and the rest of the functions in the same service, make sure the service is exported in the service/index.ts file:

export * from './example-service';