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

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

Changelog

[1.1] - 2025-04-20

[!CAUTION] Breaking changes

Added

• Deparser (Quartz Scheduler supported)
• JSCON - JavaScript Cron Object Notation

  Changed

• Parser input format (Check latest README.md)
• Explicit support for Quartz Scheduler (Upcoming support for Unix Scheduler)

  Fixed

• Removed unnecessary mandate for runOnWeekDay

  [1.0.18] - 2024-07-16

  Fixed

• Upgraded Construe version to 2.50.0

[1.0.17] - 2022-06-11

Added

• Parser - Initial release with parseCronExpression