4.3 KiB

Raw Blame History

Schedule Later

schedule-later is a static class that provides methods for managing date-time based tasks, such as starting timeouts and intervals at a specific time of day. Under-the-hood, it uses setTimeout and setInterval.

Install

npm install schedule-later

yarn add schedule-later

Import

import Scheduler from 'schedule-later'

Key Concepts

TimeOfDay

A TimeOfDay object is used to represent a specific time of day. It is an object containing the hour, minute, and seconds.

export interface TimeOfDay {
  hour: number
  minute?: number
  seconds?: number
}

TimeUntil

A TimeUntil object is used to represent a specific time until a certain event. It can represent time until a certain date, milliseconds from now, or a specific time of day.

export type TimeUntil = {
  timeOfDay?: TimeOfDay
  date?: Date
  ms?: number
}

Usage

The Scheduler class provides two main static methods: startTimeout and startInterval.

startTimeout

The startTimeout method starts a timeout that calls a given function after a specific delay. The delay is calculated based on the TimeUntil object passed to it. The method returns a StopFunction (see below).

public static startTimeout(
  timerFunc: Function,
  start: TimeUntil
): StopFunction;

startInterval

The startInterval method starts an interval that calls a given function repeatedly with a fixed time delay between each call. Like startTimeout, the initial delay is calculated based on a TimeUntil object. The method returns a StopFunction (see below).

public static startInterval(
  intervalFunc: Function,
  intervalMS: number,
  start?: TimeUntil
): StopFunction;

Stop Functions

Both the startTimeout and startInterval methods return a StopFunction. This function can be called to cancel a timeout or interval.

When called with no arguments, the StopFunction stops the timeout or interval immediately. If called with a TimeUntil argument, it schedules a stop at the specified time.

Here is the type definition of a StopFunction:

type StopFunction = (stopTime?: TimeUntil) => StopCancelFunction | null

Stop Cancel Functions

The StopFunction returns a StopCancelFunction when called. This function can be called to cancel a scheduled stop.

type StopCancelFunction = (stopRunning: boolean = false) => void

In the StopCancelFunction, if the stopRunning parameter is true, it stops the timeout or interval immediately. If stopRunning is false, it cancels the scheduled stop.

Examples

Start a timeout that says "Hello, world!" after 10 seconds, then stop it after 5 seconds.

const sayHello = () => console.log('Hello, world!')

// Start a timeout that says "Hello, world!" after 10 seconds, and stop it after 5 seconds.
let stopTimeout = Scheduler.startTimeout(sayHello, { ms: 10000 })
stopTimeout({ ms: 5000 })

Using startTimeout with a specific time of day

const goodMorning = () => console.log('Good morning!')
let stopTimeout = Scheduler.startTimeout(goodMorning, {
  timeOfDay: { hour: 7, minute: 0 },
})

// Later, if you want to cancel the morning greeting
stopTimeout()

In this example, the goodMorning function will be called at 7:00 AM. If you want to cancel the morning greeting (for example, the user chose to sleep in), you can call the stopTimeout function.

Using startInterval with a specific interval, basically a regular setInterval

const sayHello = () => console.log('Hello, world!')
let stopInterval = Scheduler.startInterval(sayHello, 1000)

// Later, if you want to stop the interval
stopInterval()

Using startInterval with a specific time of day
```
const sayHello = () => console.log('Hello, world!')
let stopInterval = Scheduler.startInterval(sayHello, 1000, {
  timeOfDay: { hour: 7, minute: 0 },
})

// Later, if you want to stop the interval
stopInterval()
```
In this example, the sayHello function will be called every 1000 milliseconds starting at 7:00 AM. If you want to cancel the morning greeting (for example, the user chose to sleep in), you can call the stopInterval function.

4.3 KiB Raw Blame History