https://github.com/danielrbradley/cron-fns
Functions for working with CRON schedules
https://github.com/danielrbradley/cron-fns
cron date-time javascript-library npm-package typescript-library
Last synced: over 1 year ago
JSON representation
Functions for working with CRON schedules
- Host: GitHub
- URL: https://github.com/danielrbradley/cron-fns
- Owner: danielrbradley
- Created: 2020-11-06T17:08:40.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-11-26T22:49:02.000Z (over 5 years ago)
- Last Synced: 2025-03-23T20:37:11.017Z (over 1 year ago)
- Topics: cron, date-time, javascript-library, npm-package, typescript-library
- Language: TypeScript
- Homepage: https://www.danielbradley.net/cron-fns/
- Size: 695 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# cron-fns
A simple, zero dependency implementation of cron schedule functions. Runs in the browser, in Node.js, in Deno, anywhere with `setTimeout`.
[](https://www.npmjs.com/package/cron-fns)
[](https://github.com/danielrbradley/cron-fns/issues)
[](https://www.danielbradley.net/cron-fns/)
[](https://github.com/danielrbradley/cron-fns/actions?query=workflow%3ARelease)
## Quick Start
```bash
npm install cron-fns --save
# or with yarn
yarn add cron-fns
```
## Usage
### `CronDaemon`
Executes a callback on a given schedule.
_Note: This should be stopped if no longer in use in the application_
```ts
import { CronDaemon } from "cron-fns";
const daemon = new CronDaemon("0,30 9-17 * * MON", () => {
console.log("do some work");
});
// Check when it's going to run next
console.log(daemon.next());
// Stop the daemon
daemon.stop();
// Start it again
daemon.start();
// Check if it's running
console.log(daemon.state()); // "running"
```
### `nextCronOccurrence(schedule, from?) => Date | undefined`
Fetches the next date that matches the schedule, or undefined if no other time is available.
```ts
import { nextCronOccurrence } from "cron-fns";
nextCronOccurrence("0,30 9-17 * * MON", new Date("2020-01-01T00:00:00"));
// Returns 2020-01-06T09:00:00
// `from` defaults to the current date if not specified.
nextCronOccurrence("0,30 9-17 * * MON 1987");
// Returns undefined if no more possible dates
```
### `nextCronOccurrences(schedule, from?)`
Returns a generator which iterates through each sequential date in order from the specified start point. The generator will only stop iterating if there is no more possible dates.
```ts
import { nextCronOccurrences } from "cron-fns";
nextCronOccurrences("0,30 9-10 * * MON", new Date("2020-01-01T00:00:00"));
// Returns a generator with the sequence:
// 2020-01-06T09:00:00
// 2020-01-06T09:30:00
// 2020-01-06T10:00:00
// ...
```
### `Cron`
```ts
import { Cron } from "cron-fns";
const cron = new Cron("0,30 9-17 * * MON");
cron.next(); // Returns the next date from now
cron.next(new Date("2020-01-01T00:00:00")); // Returns 2020-01-06T09:00:00
```
## Cron syntax rules
```ts
// ┌───────────── minute (0 - 59)
// │ ┌───────────── hour (0 - 23)
// │ │ ┌───────────── day of the month (1 - 31)
// │ │ │ ┌───────────── month (1 - 12)
// │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
// │ │ │ │ │
// │ │ │ │ │
nextCronOccurrence("0,30 9-17 * * MON");
```
- Use a single space to separate fields.
- Enumerate multiple values for a field by separating by a comma (`,`).
- Specify a range of values with a hyphen (`-`).
- Ranges and enumeration cannot be mixed.
## Cron variations & notes
### Optional years
If you specify 6 fields then the last field is the year. If not specifed it doesn't limit by year.
### Optional seconds
If you specify 7 fields then the first field is the second. If not specified it chooses the zeroth second of each minute.
### Timezones
All times and dates are based on the system (or browser's) local timezone.