cron-js-parser
Version:
Cron expression parser to human readable format from Expression as well as Individual values
237 lines (207 loc) • 7.21 kB
Markdown
> Hey there! Would you take a quick second to ⭐️ star this [repo](https://github.com/adagioNeo/cron-js-parser)?
<img align="left" src="https://user-images.githubusercontent.com/759811/210273710-b13913e2-0a71-4d9d-94da-1fe538b8a73e.gif" width="120"/>
<br/>
<br/>
# [cron-js-parser](https://www.npmjs.com/package/cron-js-parser)
> 📢Support for <u>_Unix_</u> scheduler coming soon
## Contents
- [Introduction](#introduction)
- [Supported Schedulers](#supported-schedulers)
- [_JCON_ - Javascript Cron Object Notation](#jcon)
- [Overview](#overview)
- [Mode Object](#mode-object)
- [Quartz Scheduler](#quartz-scheduler)
- [Methods Overview](#methods-overview)
- [Parsers](#parsers)
- [Deparser](#deparser)
- [Example For Quartz](#example-for-quartz)
- [Cron Trigger Standards](#cron-trigger-standards)
- [Support](#support)
- [Important Links](#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 <u>**JCON**</u> - [*Javascript Cron Object Notation*](#jcon)
## Supported Schedulers
- [Quartz Scheduler](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html) - Unix-based Java scheduler, referred to as Cron Trigger
## JCON
### Overview
> ℹ️ More on mode objects can be found [here](#mode-object)
```
{
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** </br>
> 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](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html)
### Methods Overview
#### Parsers
##### <u>parseCronExpression</u>
```
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.
##### <u>parseHumanReadable</u>
```
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
##### <u>deparseCronExpression</u>
###### 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](https://github.com/adagioNeo/cron-js-parser/tree/v1.1/test/index.js)
#### 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