️⏰ Schedules

Hey there 👋! This guide is here to give you a fast understanding of how nyx's schedule system works, so you can use it right away. For in-depth details, see the respective guides of each schedule related object.

📚 Description

Schedules are objects that are ticked some time in the future, and can be used as a feature complete way of scheduling events in your bot, apart from Node's setInterval() API.

In essence, a Schedule object contains its ticking logic and its interval of when it wishes to be executed, which can be in cron format, in an amount of ms (number), or as a Date. When a schedule is added via the ScheduleManager, the ScheduleExecutionScheduler creates a new ScheduleJobAdapter for it, which will start ticking the schedule using the ScheduleExecutor.

danger

It's important to note that the ScheduleExecutionScheduler is implementation-specific. For example, @framework's implementation uses the cron npm package to create the job.

To add a layer of abstraction, the ScheduleExecutionScheduler's interface doesn't return any specific job type, but rather a ScheduleJobAdapter, which has methods like resume, pause, etc.

ScheduleJobAdapters do not tick schedules by themselves. They're meant to be a wrapper around an object that actually does so, like a cron job, a setInterval() interval, to be able to interact with them without actually knowing the actual implementation, or what's "inside". However because of their nature, they're also implementation-specific.

The schedule system is made up of several objects that work together to track the execution of schedule objects, all coordinated by a ScheduleManager.

Specifically, the schedule related objects are:

• ScheduleManager: The entry point for the schedule system, holding all the schedule-related objects and methods that use all of these objects. All objects below are contained here.
• ScheduleExecutionScheduler: Tracks the execution of schedules and stores the ScheduleJobAdapters.
• ScheduleRepository: Stores all the currently registered schedules.
• ScheduleExecutor: Executes schedules, checking its ScheduleMiddlewareList and passing any errors to its ErrorHandler.
• EventBus: An 📣 Event Bus that emits schedule related events.

🔢 Schedule tick sequence

tip

• A dashed step means it's executed asynchronously, so the next one is inmediately executed.
• You can hover over steps with (?) to see extra details.

💫 ErrorHandler

️🛡️ MiddlewareList

⚡ ScheduleExecutor

🧩 ScheduleJobAdapter

⏰ ScheduleExecutionScheduler

🚌 ScheduleRepository

💼 ScheduleManager

👤 You

Add a new schedule

Add schedule to repository

Track schedule

Instantiate new job adapter for this schedule

Return new job adapter

Wait for scheduled time

Execute schedule

If there are middlewares registered

Check middleware list

Check all registered middlewares

Workflow ends if denied

Return allowed or denied

Tick schedule

Workflow ends if it errored

Pass thrown errors, if any

Emits ScheduleEventEnum.ScheduleTick

Finish execution

React Flow

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

✨ Quick examples

Creating a StatusSchedule

1. Extend AbstractSchedule, implementing tick() and interval.
2. Register it to a bot's ScheduleManager.

class StatusSchedule extends AbstractSchedule {
  // Cron format (every half hour). Can also be a Date or number.
  protected readonly interval = '*/30 * * * *';

  public async tick(meta: ScheduleTickMeta) {
    const bot = meta.getBot();
    const { client } = bot;

    const guildsAmount = client.guilds.cache.size;
    client.user.setActivity(`${guildsAmount} servers`, { type: ActivityType.Watching });
  }
}

const schedule = new StatusSchedule();
await bot.getScheduleManager().addSchedule(schedule);

Pausing a Schedule

1. Get the job that ticks the schedule. Either:

• From the ScheduleExecutionScheduler via ScheduleExecutionScheduler#getJobForSchedule().
• From the Schedule, via Schedule#getJob(), passing the bot.
• From the ScheduleManager when adding the schedule.

2. Pause the job via ScheduleJobAdapter#pause().

// One of:
const job = bot.getScheduleManager().getScheduler().getJobForSchedule(schedule);
const job = schedule.getJob(bot);
const job = await bot.getScheduleManager().addSchedule(schedule);

// Then:
await job.pause();