All Projects → P4sca1 → cron-schedule

P4sca1 / cron-schedule

Licence: MIT License
A zero-dependency cron parser and scheduler for Node.js, Deno and the browser.

Programming Languages

typescript
32286 projects
javascript
184084 projects - #8 most used programming language
shell
77523 projects

Projects that are alternatives of or similar to cron-schedule

croner
Trigger functions and/or evaluate cron expressions in JavaScript. No dependencies. Most features. All environments.
Stars: ✭ 169 (+503.57%)
Mutual labels:  cron, schedule, job, timer, deno
legacy-bottlerockets
Node.js high availability queue and scheduler for background job processing
Stars: ✭ 25 (-10.71%)
Mutual labels:  cron, schedule, job
schedule-rs
An in-process scheduler for periodic jobs. Schedule lets you run Rust functions on a cron-like schedule.
Stars: ✭ 93 (+232.14%)
Mutual labels:  cron, schedule, job
linda
Linda is a simple dispatcher library.
Stars: ✭ 12 (-57.14%)
Mutual labels:  cron, schedule, job
Forest
分布式任务调度平台,分布式,任务调度,schedule,scheduler
Stars: ✭ 231 (+725%)
Mutual labels:  cron, schedule, job
aws-tag-sched-ops
Retired, please see https://github.com/sqlxpert/lights-off-aws
Stars: ✭ 24 (-14.29%)
Mutual labels:  cron, schedule
chronoman
Utility class to simplify use of timers created by setTimeout
Stars: ✭ 15 (-46.43%)
Mutual labels:  timer, interval
AdvancedTimer
AdvancedTimer implementation for Xamarin.Forms This repo is no longer maintained. New repo available.
Stars: ✭ 40 (+42.86%)
Mutual labels:  timer, interval
sidecloq
Recurring / Periodic / Scheduled / Cron job extension for Sidekiq
Stars: ✭ 81 (+189.29%)
Mutual labels:  cron, schedule
cron-time
Javascript Cron Time Expressions
Stars: ✭ 58 (+107.14%)
Mutual labels:  cron, cron-expression
php-cron-expr
Ultra lightweight, Dependency free and Super Fast Cron Expression parser for PHP
Stars: ✭ 42 (+50%)
Mutual labels:  cron, cron-expression
job-plus
Job Plus项目是基于SpringBoot+Vue的轻量级定时任务管理系统
Stars: ✭ 17 (-39.29%)
Mutual labels:  cron, job
point-vue-cron
vue component: cron expression generator
Stars: ✭ 21 (-25%)
Mutual labels:  cron, cron-expression
watchman
📆 更夫(watchman)是一款可视化的定时任务配置 Web 工具,麻麻不用担心我漏掉任何更新啦!
Stars: ✭ 40 (+42.86%)
Mutual labels:  cron, schedule
delay-timer
Time-manager of delayed tasks. Like crontab, but synchronous asynchronous tasks are possible scheduling, and dynamic add/cancel/remove is supported.
Stars: ✭ 257 (+817.86%)
Mutual labels:  cron, schedule
gymbox-bot
Simplify the booking of a gymbox class.
Stars: ✭ 21 (-25%)
Mutual labels:  cron, schedule
scheduler
Task Scheduler for Laravel applications. UI from scratch
Stars: ✭ 18 (-35.71%)
Mutual labels:  cron, schedule
angular-cron-gen
A basic way to for users to graphically build a cron expression using Angular.
Stars: ✭ 36 (+28.57%)
Mutual labels:  cron, cron-expression
cron-validate
A cron-expression validator for TypeScript/JavaScript projects.
Stars: ✭ 40 (+42.86%)
Mutual labels:  cron, cron-expression
crontab
cron expression parser and executor for dotnet core.
Stars: ✭ 13 (-53.57%)
Mutual labels:  cron, cron-expression

cron-schedule CircleCI

A zero-dependency cron parser and scheduler for Node.js, Deno and the browser.

ts semantic-release code style: prettier

Features

  • Parse cron expressions.
  • Get next or previous schedules from a specific starting date.
  • Check if a date matches a cron expression.
  • Schedule a function call based on a cron expression.
  • Supports Node.js, Deno and the browser (IIFE or ESM, ES6 required)
  • Lightweight and tree-shakeable.

Installation and usage

Node.js (CommonJS)

Via npm:

$ npm install cron-schedule

Via yarn:

$ yarn add cron-schedule

We test our code against the following Node.js releases (12.18, 14.13, 16.12). Other versions of node.js may also work, but this is not tested.

Usage
import { parseCronExpression } from 'cron-schedule'
const cron = parseCronExpression('*/5 * * * *')
console.log(cron.getNextDate(new Date(2020, 10, 20, 18, 32)))
// 2020-11-20T17:35:00.000Z

Browser (IIFE)

<script src="https://unpkg.com/cron-schedule@:version"></script>

After the script has been loaded, you can use the global cronSchedule object to access the API.

Usage
<script>
  const cron = cronSchedule.parseCronExpression('*/5 * * * *')
  console.log(cron.getNextDate(new Date(2020, 10, 20, 18, 32)))
  // 2020-11-20T17:35:00.000Z
</script>

Requires ES6 (ES2015) browser support. Internet Explorer is not supported. If you need to support older browsers, get cron-schedule via npm or yarn and transpile it with your bundler.

Browser (ECMAScript module)

<script type="module">
  import { parseCronExpression } from 'https://cdn.skypack.dev/cron-schedule@:version'
  const cron = parseCronExpression('*/5 * * * *')
  console.log(cron.getNextDate(new Date(2020, 10, 20, 18, 32)))
  // 2020-11-20T17:35:00.000Z
</script>

Deno

import { parseCronExpression } from 'https://cdn.skypack.dev/cron-schedule@:version?dts'
// TypeScript types are automatically shipped with the X-TypeScript-Types http header.
const cron = parseCronExpression('*/5 * * * *')
console.log(cron.getNextDate(new Date(2020, 10, 20, 18, 32)))
// 2020-11-20T17:35:00.000Z

Note on CDN usage

The examples above use unpkg for IIFE and Skypack for ESM.

The urls contain :version placeholder. Replace :version with the desired version. Semver ranges are supported. To always use the latest 2.x version use ^2.0.0. See https://www.npmjs.com/package/cron-schedule for a list of available versions.

Work with cron expressions

// Import method to parse a cron expression. In the browser with IIFE: cronSchedule.parseCronExpression
import { parseCronExpression } from 'cron-schedule'

// Parse a cron expression to return a Cron instance.
const cron = parseCronExpression('*/5 * * * *')

// Get the next date starting from the given start date or now.
cron.getNextDate(startDate?: Date): Date

// Get the specified amount of future dates starting from the given start date or now.
cron.getNextDates(amount: number, startDate?: Date): Date[]

// Get an ES6 compatible iterator which iterates over the next dates starting from startDate or now.
// The iterator runs until the optional endDate is reached or forever.
// The advantage of an iterator is that you can get more further dates on demand by using iterator.next().
cron.getNextDatesIterator(startDate: Date = new Date(), endDate?: Date): Generator<Date, undefined, undefined>

// Get the previou date starting from the given start date or now.
cron.getPrevDate(startDate: Date = new Date()): Date

// Get the specified amount of previous dates starting from the given start date or now.
cron.getPrevDates(amount: number, startDate?: Date): Date[]

// Get an ES6 compatible iterator which iterates over the previous dates starting from startDate or now.
// The iterator runs until the optional endDate is reached or forever.
// The advantage of an iterator is that you can get more previous dates on demand by using iterator.next().
cron.getPrevDatesIterator(startDate: Date = new Date(), endDate?: Date): Generator<Date, undefined, undefined>

// Check whether there is a cron date at the given date.
cron.matchDate(date: Date): boolean

Schedule tasks based on cron expressions

You can schedule tasks to be executed based on a cron expression. cron-schedule comes with 2 different schedulers.

1. Timer based scheduler

The timer based cron scheduler creates one timer for every scheduled cron. When the node timeout limit of ~24 days would be exceeded, it uses multiple consecutive timeouts.

// Import the scheduler. In the browser with IIFE: cronSchedule.TimerBasedCronScheduler
import { TimerBasedCronScheduler as scheduler } from 'cron-schedule'

// Create a timeout, which fill fire the task on the next cron date.
// An optional errorHandler can be provided, which is called when the task throws an error or returns a promise that gets rejected.
// Returns a handle which can be used to clear the timeout using clearTimeoutOrInterval.
scheduler.setTimeout(cron: Cron, task: () => unknown, opts?: { errorHandler?: (err: Error) => unknown }): ITimerHandle

// Create an interval, which will fire the given task on every future cron date.
// This uses consecutive calls to scheduler.setTimeout under the hood.
// An optional errorHandler can be provided, which is called when the task throws an error or returns a promise that gets rejected.
// The task remains scheduled when an error occurs.
// Returns a handle which can be used to clear the timeout using clearTimeoutOrInterval.
scheduler.setInterval(cron: Cron, task: () => unknown, opts?: { errorHandler?: (err: Error) => unknown }): ITimerHandle

// Clear a timeout or interval, making sure that the task will no longer execute.
scheduler.clearTimeoutOrInterval(handle: ITimerHandle): void

Pros:

  • A task is scheduled exactly to the second of the next cron date.

Cons:

  • There is one timer per task, which could lead to lower performance compared to the interval based scheduler if you have many scheduled tasks.

2. Interval based scheduler

The interval based scheduler checks for due task in a fixed interval. So there is only one interval for all tasks assigned to a scheduler. You can have multiple instances of an interval based scheduler.

// Import the scheduler. In the browser with IIFE: cronSchedule.IntervalBasedCronScheduler
import { IntervalBasedCronScheduler } from 'cron-schedule'

// Instantiate a new instance of the scheduler with the given interval. In this example, the scheduler would check every 60 seconds.
const scheduler = new IntervalBasedCronScheduler(60 * 1000)

// Register a new task that will be executed on every future cron date, or only on the next cron date if isOneTimeTask is true.
// An optional errorHandler can be provided, which is called when the task throws an error or returns a promise that gets rejected.
// The task remains scheduled when an error occurs (if not a one time task). Tasks are at max executed only once per interval.
// Returns an id to be used with unregisterTask.
scheduler.registerTask(cron: Cron, task: () => unknown, opts?: { isOneTimeTask?: boolean, errorHandler?: (err: Error) => unknown }): number

// Unregister a task causing it to no longer be executed.
scheduler.unregisterTask(id: number): void

// You can stop the scheduler, which clears the interval.
scheduler.stop()

// You can start the scheduler after stopping it again. A newly created scheduler is started by default.
// Tasks that were due while the scheduler was stopped will be executed on the next interval tick (but only a single time).
scheduler.start()

Pros:

  • Only one interval for all tasks, which is quite performant.

Cons:

  • Tasks are not executed exactly on the cron date.
  • Tasks can only be executed once per interval.

For most people, the timer based scheduler should be a good option. When you have problems with long timeouts / intervals being skipped, or have performance problems because of many scheduled tasks, you should consider the interval based scheduler.

Cron expression format

cron_schedule uses the linux cron syntax as described here with the addition that you can optionally specify seconds by prepending the minute field with another field.

┌───────────── second (0 - 59, optional)
│ ┌───────────── minute (0 - 59)
│ │ ┌───────────── hour (0 - 23)
│ │ │ ┌───────────── day of month (1 - 31)
│ │ │ │ ┌───────────── month (1 - 12)
│ │ │ │ │ ┌───────────── weekday (0 - 7)
* * * * * *

All linux cron features are supported, including

  • lists
  • ranges
  • ranges in lists
  • step values
  • month names (jan,feb,... - case insensitive)
  • weekday names (mon,tue,... - case insensitive)
  • time nicknames (@yearly, @annually, @monthly, @weekly, @daily, @hourly - case insensitive)

For simple timing tasks like every x seconds, you should consider using setInterval which is more suitable for simple timing tasks, as it does not have the calculation overhead.

Cron validation

Looking for a way to validate cron expressions in your backend (node.js) or in the browser with support for multiple presets? Check out cron-validate!

Use the npm-cron-schedule preset to validate that cron expressions are supported by cron-schedule.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].