# cron-builder-ts

> simple API for building cron expressions

Latest version **1.0.5** (published 2020-09-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install cron-builder-ts
pnpm add cron-builder-ts
yarn add cron-builder-ts
bun add cron-builder-ts
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2020-09-04 |
| First published | 2020-05-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 278.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Evgeniy Efimov. Origianl author is Tyler Waneka |
| Maintainers | x_jenka_x |

## Links

- npm: https://www.npmjs.com/package/cron-builder-ts
- Repository: https://github.com/evgeniyefimov/cron-builder-ts
- Homepage: https://github.com/evgeniyefimov/cron-builder-ts#readme
- Issues: https://github.com/evgeniyefimov/cron-builder-ts/issues
- npm.io page: https://npm.io/package/cron-builder-ts

## Dependencies (1)

- [cron-converter](https://npm.io/package/cron-converter.md) 1.0.0

## Recent versions

- 1.0.5 (latest) — 2020-09-04
- 1.0.4 — 2020-09-04
- 1.0.3 — 2020-09-04
- 1.0.2 — 2020-05-15
- 1.0.1 — 2020-05-14

## README

### Forked from https://github.com/sourceclear/cron-builder

# cron-builder
The software utility *cron* is a time-based scheduler in Unix-like computer operating systems. A user may use cron to schedule jobs (commands or scripts) to run periodically at fixed times, dates, or intervals. A cron statement is composed of 5 fields separated by white space. The `*` character translates to "every", ie: "every minute" or "every day of the week".

cron-builder will manage the state of a cron expression, allowing a user to manipulate it through a simple API. It is decoupled from the DOM and doesn't have an opinion about where it's being called from. cron-builder considers [this article](https://en.wikipedia.org/wiki/Cron) its source of truth.

### Install
cron-builder is available on npm and bower:
```
npm i cron-builder-ts --save
```

After installing, just require the package as you normally would:
```
import { CronBuilder } from 'cron-builder-ts';
```



### API
To instantiate the cron builder:

```JavaScript
// (default expression is set to "* * * * *")
var cronExp = new CronBuilder();

// optionally, pass in a cron expression to override the default:
var myCronExp = new CronBuilder('5 12 * * 1-5')
```

To return the cron expression at any given time:
```JavaScript
cronExp.build();
// '* * * * *'

// add optional flags to customize build result
cronExp.build(options);
```


API includes basic getters and setters:
```JavaScript
cronExp.get('minute');
// '*'
cronExp.set('minute', '5,35');
// '5,35'
cronExp.get('minute');
// '5,35'
cronExp.build();
// '5,35 * * * *'
```

Or if you'd prefer to add or remove values one at a time, use `addValue` and `removeValue`. These methods build or take away from what is currently set:
```JavaScript
cronExp.addValue('hour', '2');
cronExp.addValue('monthOfTheYear', '4');
cronExp.addValue('monthOfTheYear', '10');
cronExp.build();
// '5,35 2 * 4,10 *'

cronExp.removeValue('minute', '5');
cronExp.build();
// '35 2 * 4,10 *'
```

If you prefer to work with the expression object directly, use `getAll` and `setAll`:
```JavaScript
var exp = cronExp.getAll();
// {minute: ['35'], hour: ['2'], dayOfTheMonth: ['*'], monthOfTheYear: ['4','10'], ...}
exp.dayOfTheMonth = ['7','14','21','28'];
cronExp.setAll(exp);
cronExp.build();
// '35 2 7,14,21,28 4,10 *'
```

### Build options

#### outputWeekdayNames and outputMonthNames
Default: false
```js
const myCronExp = new CronBuilder('*/5 9-17/2 * 1-3 1-5')
cronExp.build({ outputWeekdayNames: true, outputMonthNames: true });
// Result: '*/5 *(10-16)/2 * JAN-MAR MON-FRI'
```

#### outputHashes
Default: false
```js
const myCronExp = new CronBuilder('*/5 9-17/2 * 1-3 1-5')
cronExp.build({ outputHashes: true });
// Result: 'H/5 H(10-16)/2 H 1-3 1-5'
```

##### Notes:
- cron-builder does not currently support using `/` syntax to indicate values that are repeated. Instead of using `*/15`, use the verbose form `0,15,30,45`.
- cron-builder requires using numeric representations of days of the week and months of the year. So instead of using `Feb,Mar,Apr` just use `2,3,4`.

### Contribute
Easy!
```
npm install
npm test
```
Pull requests and issues appreciated!

### TODO
- more validation for things like adding values that are already included in a range, better range validations...
- sorting of values for a given measure of time

### License

The MIT License (MIT)

---
_Source: https://npm.io/package/cron-builder-ts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._