10.0.2 β€’ Published 10 months ago

@sapphire/plugin-scheduled-tasks v10.0.2

Weekly downloads
-
License
MIT
Repository
github
Last release
10 months ago

Sapphire Logo

@sapphire/plugin-scheduled-tasks

Plugin for @sapphire/framework to add support for scheduled tasks.

GitHub codecov npm bundle size npm

Description

Many bots have features that need to run periodically, such as uploading analytics data, reminders for users, birthdays, scheduled giveaways, undoing moderation actions, and more. Several implemented solutions exist for this, but as with many time-based processing attempts, they are often flawed and unreliable. This plugin is our solution, enabling you to schedule tasks and save them in services like Redis and SQS with ease.

Features

  • Full TypeScript support
  • Includes ESM entrypoint

Installation

@sapphire/plugin-scheduled-tasks depends on the following packages. Be sure to install these along with this package!

In case you want to use bull as your provider:

In case you want to use sqs as your provider:

You can use the following command to install this package with bull, or replace npm install with your package manager of choice.

npm install @sapphire/plugin-scheduled-tasks @sapphire/framework bull

Usage

This registers the necessary options and methods in the Sapphire client to be able to use the schedule plugin.

// Main bot file
// Be sure to register the plugin before instantiating the client.
import { ScheduledTaskRedisStrategy } from '@sapphire/plugin-scheduled-tasks/register-redis';

// Or if you want to use sqs
import { ScheduledTaskSQSStrategy } from '@sapphire/plugin-scheduled-tasks/register-sqs';

Then, you can pass the imported Strategy into the configuration options in your SapphireClient extension class or initializer. This will either be located in your new SapphireClient constructor call, or super in your constructor method if you use an extension class.

const options = {
	...otherClientOptionsGoHere,
	tasks: {
		strategy: new ScheduledTaskRedisStrategy(),
		// or with sqs
		strategy: new ScheduledTaskSQSStrategy({
			/* you can add your SQS options here */
		})
	}
};

In order to use the scheduled tasks anywhere other than a piece (commands, arguments, preconditions, etc.), you must first import the container property of @sapphire/framework. For pieces, you can simply use this.container.tasks to access this plugin's methods.

This is a simple example that creates a task to be run in 2 seconds from a service.

import { container } from '@sapphire/framework';

export class MyAwesomeService {
	public createAwesomeTask() {
		container.tasks.create('name', { id: '123' }, 2000);
	}
}

Here is an example mute command, demonstrating the use of this.container.tasks from within a piece by omitting the explicit import.

// mute command

import { Command, CommandOptions, PieceContext } from '@sapphire/framework';
import type { Message } from 'discord.js';

export class MuteCommand extends Command {
	public constructor(context: PieceContext) {
		super(context, {
			description: 'Mute a user'
		});
	}

	public async run(message: Message) {
		// create a task to unmute the user in 1 minute
		this.container.tasks.create('unmute', { authorId: message.author.id }, 60000);
	}
}

Create a task handler

Scheduled tasks use their own store, like other types of pieces. You can create a directory alongside your commands directory named scheduled-tasks and place your tasks there, but they must inherit from ScheduledTask, like so.

Manual task example

Creating the Piece:
import type { PieceContext } from '@sapphire/framework';
import { ScheduledTask } from '@sapphire/plugin-scheduled-tasks';

export class ManualTask extends ScheduledTask {
	public constructor(context: PieceContext) {
		super(context);
	}

	public async run(payload: unknown) {
		this.container.logger.info('I ran!', payload);
	}
}

declare module '@sapphire/framework' {
	interface ScheduledTasks {
		manual: never;
	}
}
Using Manual Tasks
container.tasks.create('manual', payload, 5000);

Cron Task Example

Cron jobs are currently only supported by the Redis strategy.

Creating the Piece:
import type { PieceContext } from '@sapphire/framework';
import { ScheduledTask } from '@sapphire/plugin-scheduled-tasks';

export class CronTask extends ScheduledTask {
	public constructor(context: PieceContext) {
		super(context, {
			cron: '0 * * * *'
		});
	}

	public async run() {
		this.container.logger.info('I run every hour at *:00');
	}
}

declare module '@sapphire/framework' {
	interface ScheduledTasks {
		cron: never;
	}
}
Using Cron tasks

Cron & Interval tasks are loaded automatically.

Interval task example

Creating the Piece:
import type { PieceContext } from '@sapphire/framework';
import { ScheduledTask } from '@sapphire/plugin-scheduled-tasks';

export class IntervalTask extends ScheduledTask {
	public constructor(context: PieceContext) {
		super(context, {
			interval: 60 * 1000 // 60 seconds
		});
	}

	public async run() {
		this.container.logger.info('I run every minute');
	}
}

declare module '@sapphire/framework' {
	interface ScheduledTasks {
		interval: never;
	}
}
Using Interval tasks

Cron & Interval tasks are loaded automatically.

Buy us some doughnuts

Sapphire Community is and always will be open source, even if we don't get donations. That being said, we know there are amazing people who may still want to donate just to show their appreciation. Thank you very much in advance!

We accept donations through Open Collective, Ko-fi, Paypal, Patreon and GitHub Sponsorships. You can use the buttons below to donate through your method of choice.

Donate WithAddress
Open CollectiveClick Here
Ko-fiClick Here
PatreonClick Here
PayPalClick Here

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

10.0.2

10 months ago

10.0.2-next.d512e6d

10 months ago

10.0.2-next.b4f1701

10 months ago

10.0.2-next.5395ccc

10 months ago

10.0.3-next.a0edebf

10 months ago

10.0.3-next.0782cfd

10 months ago

10.0.3-next.c75b7c2

10 months ago

10.0.2-next.d9dd30c

10 months ago

10.0.2-next.b2086e1

10 months ago

10.0.2-next.80d26ac

10 months ago

10.0.3-next.e0e4d74

10 months ago

10.0.3-next.21d90cf

10 months ago

10.0.2-next.6b9d139

10 months ago

10.0.2-next.dd4b95f

10 months ago

10.0.2-next.12ccd3c

10 months ago

10.0.2-next.6a148bb

10 months ago

10.0.2-next.518ac87

10 months ago

10.0.2-next.5aa5898

10 months ago

10.0.2-next.ccf3dc1

10 months ago

10.0.2-next.d2c9aaa

10 months ago

10.0.2-next.9e3ae6f

10 months ago

10.0.2-next.8128717

10 months ago

10.0.2-next.a1d7d5e

10 months ago

10.0.2-next.22ae85d

11 months ago

10.0.2-next.352f2cd

11 months ago

10.0.2-next.fa73a83

11 months ago

10.0.2-next.5ea63b2

11 months ago

10.0.2-next.f177359

11 months ago

10.0.2-next.51af5e9

11 months ago

10.0.2-next.96ac961

11 months ago

10.0.2-next.8de2057

11 months ago

10.0.2-next.f8b2f60

11 months ago

10.0.2-next.1c40781

11 months ago

10.0.2-next.f61b06f

11 months ago

10.0.2-next.e6fdc84

11 months ago

10.0.2-next.f730be1

11 months ago

10.0.2-next.9b36bae

11 months ago

10.0.2-next.821ff70

12 months ago

10.0.2-next.30e71f4

12 months ago

10.0.2-next.56b0ad1

12 months ago

10.0.2-next.fb8af18

12 months ago

10.0.2-next.8b575e9

12 months ago

10.0.2-next.7ba75bc

12 months ago

10.0.2-next.18d56e9

12 months ago

10.0.2-next.e37f2d0

12 months ago

10.0.2-next.e30dbc1

12 months ago

10.0.2-next.c2464a5

12 months ago

10.0.2-next.73cea33

12 months ago

10.0.1

2 years ago

10.0.0

2 years ago

9.1.0

2 years ago

9.0.1

2 years ago

9.0.0

2 years ago

8.1.0

2 years ago

7.1.2

2 years ago

7.1.1

2 years ago

8.0.0

2 years ago

7.0.0

2 years ago

7.1.0

2 years ago

6.0.1

2 years ago

5.0.1

3 years ago

6.0.0

3 years ago

4.0.1

3 years ago

5.0.0

3 years ago

4.0.0

3 years ago

2.3.4

3 years ago

2.3.5

3 years ago

3.0.0

3 years ago

2.3.2

3 years ago

2.3.1

3 years ago

2.3.3

3 years ago

1.2.0

4 years ago

1.2.1

4 years ago

2.2.0

4 years ago

2.0.0

4 years ago

1.1.1

4 years ago

2.3.0

3 years ago

2.1.0

4 years ago

1.1.0

4 years ago

1.0.1

4 years ago

1.0.0

4 years ago