Schedulers

Execute functions at designated regular intervals.

A scheduler is a type of decorator that, when applied to a function, causes the function to be executed at regular intervals 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. The 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.

Creating a scheduler

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

Example:

Backend code

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

export class ExampleService extends SquidService {
  @scheduler(
    'sendEmailReminders',
    CronExpression.EVERY_MINUTE,
    true /* exclusive */
  )
  async sendEmailReminders(): Promise<void> {
    // TODO - add your business logic here
  }
}

The exclusive parameter

The @scheduler decorator takes three parameters: the name of the function to run, the interval, and the exclusivity. Take the following example:

Backend code

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

The third parameter of this @scheduler decorator is a boolean that defines whether the function should be marked as exclusive. If 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.

If set to false, then an instance of a scheduler will run regardless of whether or not 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 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:

service/index.ts

export * from './example-service';

To see the full SDK reference documentation for the scheduler decorator, click here.