Hey there! Would you take a quick second to ⭐️ star this repo?

cron-js-parser

📢Support for Unix scheduler coming soon

Contents

• Introduction
• Supported Schedulers
• JCON - Javascript Cron Object Notation
  • Overview
  • Mode Object
• Quartz Scheduler
  • Methods Overview
    • Parsers
    • Deparser
  • Example For Quartz
  • Cron Trigger Standards
• Support
• Important Links

Introduction

Cron expressions are powerful, but can be pretty confusing. The aim of this library is to standardize javascript logic for handling cron expressions.

✨ Introducing JCON - Javascript Cron Object Notation

Supported Schedulers

• Quartz Scheduler - Unix-based Java scheduler, referred to as Cron Trigger

JCON

Overview

ℹ️ More on mode objects can be found here

{
  seconds: <Mode Object>,
  minutes: <Mode Object>
  hours: <Mode Object>,
  daysOfMonth?: <Mode Object>,
  months: <Mode Object>,
  daysOfWeek?: <Mode Object>,
  years?: <Mode Object>
}

Mandatory Fields - seconds, minutes, hours, months Optional Fields - daysOfMonth, daysOfWeek, years

Mode Object

These constants define the allowed string literal values for the mode property in the respective types.

Types

1. Cycle

Represents an object with a fixed mode indicating a cycle.

type Cycle = {
  mode: typeof cycle;
};

---

2. At

Represents an object with a mode 'at' and an array of numeric values.

type At = {
  mode: typeof at;
  value: number[];
};

---

3. StartAtRepeatCycleEvery

Represents an object with a mode 'StartAtRepeatCycleEvery' and a StartAt object as its value.

type StartAtRepeatCycleEvery = {
  mode: typeof startAtRepeatCycleEvery;
  value: StartAt;
};

---

4. StartCycleInRange

Represents an object with a mode 'startCycleInRange' and an InRange object as its value.

type StartCycleInRange = {
  mode: typeof startCycleInRange;
  value: InRange;
};

Summary

Type	Property	Type	Description
cycle	mode	typeof cycle	Must be the literal string 'cycle'
At	mode	typeof at	Must be the literal string 'at'
At	value	number[]	An array of numbers specifying values
StartAtRepeatCycleEvery	mode	typeof startAtRepeatCycleEvery	Must be the literal string 'startAtRepeatCycleEvery'
StartAtRepeatCycleEvery	value	StartAt	An object containing startAt and every numbers
StartCycleInRange	mode	typeof startCycleInRange	Must be the literal string 'startCycleInRange'
StartCycleInRange	value	InRange	An object defining a range with from and to

Quartz Scheduler

Methods Overview

Parsers

parseCronExpression

export const parseCronExpression = (cronValues: QuartzCronObj): string

Description

Converts a structured QuartzCronObj back into a cron expression string.

Input

• cronValues (QuartzCronObj): An object representing the components of a cron expression.

Output

• Returns a string representing the cron expression generated from the input object.

parseHumanReadable

export const parseHumanReadable = (
  cronExpr: string,
  cronValues: QuartzCronObj,
  language: string
): string

Description

Generates a human-readable description of a cron expression in the specified language.

Inputs

• cronExpr (string): The cron expression string. If empty or falsy, the function will generate the expression from cronValues.
• cronValues (QuartzCronObj): An object representing the cron expression components.
• language (string): The locale/language code (e.g., 'en', 'fr', 'de') to format the description.

Output

• Returns a string containing a verbose, human-readable description of the cron schedule in the specified language.

Deparser

deparseCronExpression

Description

Converts a cron expression string into a structured QuartzCronObj representation.

Input

• cronExpr (string): A valid cron expression string in Quartz format.

Output

• Returns a QuartzCronObj — an object representing the parsed components of the cron expression.

Example for Quartz

Input

const { 
  parseCronExpression, parseHumanReadable, deparseCronExpression
} = require('./cron-js-parser.quartz');

let obj = {
  seconds: {
    mode: 'at',
    value: [1, 5, 10]
  },
  minutes: {
    mode: 'StartAtRepeatCycleEvery',
    value: {
      startAt: 1,
      every: 10
    }
  },
  hours: {
    mode:'startCycleInRange',
    value: {
      from: 2,
      to: 20
    }
  },
  daysOfMonth: {
    mode: 'cycle'
  },
  months: {
    mode: 'cycle'
  },
  years: {
    mode: 'at',
    value: [2020, 2022]
  },
  daysOfWeek: {
    mode: 'on',
    value: {
      isLastWeek: false,
      dayIndex: 6,
      weekIndex: 3
    } 
  }
};
const cron = parseCronExpression(obj); 
console.log(cron);
lang = 'fr' //French
console.log(parseHumanReadable(cron,{},lang))
const deparsed = deparseCronExpression(cron)
console.log(deparsed)
console.log(parseCronExpression(deparsed))

Output

1,5,10 1/10 2-20 ? * ? 2020,2022
1, 5, et 10 secondes après la minute, toutes les 10 minutes, à partir de 1 minutes après l'heure, de 02:00 à 20:59, tous les jours, uniquement en 2020 et 2022
{
  seconds: { mode: 'at', value: [ 1, 5, 10 ] },
  minutes: { mode: 'StartAtRepeatCycleEvery', value: { startAt: 1, every: 10 } },
  hours: { mode: 'startCycleInRange', value: { from: 2, to: 20 } },
  daysOfMonth: undefined,
  months: { mode: 'cycle' },
  years: { mode: 'at', value: [ 2020, 2022 ] }
}
1,5,10 1/10 2-20 ? * ? 2020,2022

Cron Trigger Standards

Days of Week

• 1 - SUN - Sunday
• 2 - MON - Monday
• 3 - TUE - Tuesday
• 4 - WED - Wednesday
• 5 - THU - Thursday
• 6 - FRI - Friday
• 7 - SAT - Saturday

Support

• Javascript
• Typescript
• Nodejs
• Browser

Important Links

• https://www.freeformatter.com/cron-expression-generator-quartz.html