{"id":13672850,"url":"https://github.com/Airfooox/cron-validate","last_synced_at":"2025-04-28T04:30:28.869Z","repository":{"id":37485385,"uuid":"254733680","full_name":"Airfooox/cron-validate","owner":"Airfooox","description":"A cron-expression validator for TypeScript/JavaScript projects.","archived":false,"fork":false,"pushed_at":"2025-03-13T18:59:41.000Z","size":1416,"stargazers_count":74,"open_issues_count":5,"forks_count":13,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-13T19:40:29.931Z","etag":null,"topics":["cron","cron-expression","validation","validation-library","validator"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Airfooox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-10T20:50:20.000Z","updated_at":"2025-03-13T18:59:42.000Z","dependencies_parsed_at":"2023-02-19T10:45:22.156Z","dependency_job_id":"1bffa5e8-ffe9-446e-b994-df4615f12965","html_url":"https://github.com/Airfooox/cron-validate","commit_stats":{"total_commits":299,"total_committers":8,"mean_commits":37.375,"dds":0.5518394648829432,"last_synced_commit":"b95aae1f3a44ad89dbfc7d1a7fca63f3b697aa14"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Airfooox%2Fcron-validate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Airfooox%2Fcron-validate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Airfooox%2Fcron-validate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Airfooox%2Fcron-validate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Airfooox","download_url":"https://codeload.github.com/Airfooox/cron-validate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251251752,"owners_count":21559654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cron","cron-expression","validation","validation-library","validator"],"created_at":"2024-08-02T09:01:52.034Z","updated_at":"2025-04-28T04:30:28.858Z","avatar_url":"https://github.com/Airfooox.png","language":"TypeScript","readme":"# cron-validate\n\n[![typescript](https://camo.githubusercontent.com/56e4a1d9c38168bd7b1520246d6ee084ab9abbbb/68747470733a2f2f62616467656e2e6e65742f62616467652f69636f6e2f547970655363726970743f69636f6e3d74797065736372697074266c6162656c266c6162656c436f6c6f723d626c756526636f6c6f723d353535353535)](https://www.typescriptlang.org/)\n[![dependencies Status](https://img.shields.io/npm/v/cron-validate)](https://www.npmjs.com/package/cron-validate)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n![npm](https://img.shields.io/npm/dw/cron-validate)\n[![dependencies Status](https://david-dm.org/airfooox/cron-validate/status.svg)](https://david-dm.org/airfooox/cron-validate)\n\nCron-validate is a cron-expression validator written in TypeScript.\nThe validation options are customizable and cron fields like seconds and years are supported.\n\n## Installation\n\nPackage is available on npm:\n\n`npm install -S cron-validate`\n\n## Usage\n\n### Basic usage\n\n```typescript\nimport cron from 'cron-validate'\n\nconst cronResult = cron('* * * * *')\nif (cronResult.isValid()) {\n  // !cronResult.isError()\n  // valid code\n} else {\n  // error code\n}\n```\n\n### Result system\n\nThe `cron` function returns a Result-type, which is either `Valid\u003cT, E\u003e` or `Err\u003cT, E\u003e`.\n\nFor checking the returned result, just use `result.isValid()` or `result.isError()`\n\nBoth result types contain values:\n\n```typescript\nimport cron from 'cron-validate'\n\nconst cronResult = cron('* * * * *')\nif (cronResult.isValid()) {\n  const validValue = cronResult.getValue()\n\n  // The valid value is a object containing all cron fields\n  console.log(validValue)\n  // In this case, it would be:\n  // { seconds: undefined, minutes: '*', hours: '*', daysOfMonth: '*', months: '*', daysOfWeek: '*', years: undefiend }\n} else {\n  const errorValue = cronResult.getError()\n\n  // The error value contains an array of strings, which represent the cron validation errors.\n  console.log(errorValue) // string[] of error messages\n}\n```\n\nMake sure to test the result type beforehand, because `getValue()` only works on `Valid` and `getError()` only works on `Err`. If you don't check, it will throw an error.\n\nFor further information, you can check out https://github.com/gDelgado14/neverthrow, because I used and modified his code for this package.\n(Therefor not every documented function on his package is available on this package.)\n\n## Options / Configuration\n\nTo configure the validator, cron-validate uses a preset system. There are already defined presets (default, npm-node-cron or aws), but you can also define your own preset to use for your system. You can also use the override property to set certain option on single cron validates.\n\n### Presets\n\nThe following presets are already defined by cron-validate:\n\n- default (see: http://crontab.org/)\n- npm-node-cron (see: https://github.com/kelektiv/node-cron)\n- aws-cloud-watch (see: https://docs.aws.amazon.com/de_de/AmazonCloudWatch/latest/events/ScheduledEvents.html)\n- npm-cron-schedule (see: https://github.com/P4sca1/cron-schedule)\n\nTo select a preset for your validation, you can simply do this:\n\n```typescript\ncron('* * * * *', {\n  preset: 'npm-cron-schedule',\n})\n```\n\n#### Defining and using your own preset\n\nTo define your own preset, use this:\n\n```typescript\nregisterOptionPreset('YOUR-PRESET-ID', {\n  presetId: 'YOUR-PRESET-ID',\n  useSeconds: false,\n  useYears: false,\n  useAliases: false, // optional, default to false\n  useBlankDay: false,\n  allowOnlyOneBlankDayField: false,\n  allowStepping: true, // optional, defaults to true\n  mustHaveBlankDayField: false, // optional, default to false\n  useLastDayOfMonth: false, // optional, default to false\n  useLastDayOfWeek: false, // optional, default to false\n  useNearestWeekday: false, // optional, default to false\n  useNthWeekdayOfMonth: false, // optional, default to false\n  seconds: {\n    minValue: 0,\n    maxValue: 59,\n    lowerLimit: 0, // optional, default to minValue\n    upperLimit: 59, // optional, default to maxValue\n  },\n  minutes: {\n    minValue: 0,\n    maxValue: 59,\n    lowerLimit: 0, // optional, default to minValue\n    upperLimit: 59, // optional, default to maxValue\n  },\n  hours: {\n    minValue: 0,\n    maxValue: 23,\n    lowerLimit: 0, // optional, default to minValue\n    upperLimit: 23, // optional, default to maxValue\n  },\n  daysOfMonth: {\n    minValue: 1,\n    maxValue: 31,\n    lowerLimit: 1, // optional, default to minValue\n    upperLimit: 31, // optional, default to maxValue\n  },\n  months: {\n    minValue: 0,\n    maxValue: 12,\n    lowerLimit: 0, // optional, default to minValue\n    upperLimit: 12, // optional, default to maxValue\n  },\n  daysOfWeek: {\n    minValue: 1,\n    maxValue: 7,\n    lowerLimit: 1, // optional, default to minValue\n    upperLimit: 7, // optional, default to maxValue\n  },\n  years: {\n    minValue: 1970,\n    maxValue: 2099,\n    lowerLimit: 1970, // optional, default to minValue\n    upperLimit: 2099, // optional, default to maxValue\n  },\n})\n```\n\nThe preset properties explained:\n\n- `presetId: string`\n  - same id as in first function parameter\n- `useSeconds: boolean`\n  - enables seconds field in cron expression\n- `useYears: boolean`\n  - enables years field in cron expression\n- `useAliases: boolean`\n  - enables aliases for month and daysOfWeek fields (ignores limits for month and daysOfWeek, so be aware of that)\n- `useBlankDay: boolean`\n  - enables blank day notation '?' in daysOfMonth and daysOfWeek field\n- `allowOnlyOneBlankDayField: boolean`\n  - requires a day field to not be blank (so not both day fields can be blank)\n- `allowStepping: boolean`\n  - optional, will default to true\n  - when set to false, disallows the use of the '/' operation for valid expressions\n- `mustHaveBlankDayField: boolean`\n  - requires a day field to be blank (so not both day fields are specified)\n  - when mixed with `allowOnlyOneBlankDayField`, it means that there will always be either day or day of week as `?`\n- `useLastDayOfMonth: boolean`\n  - enables the 'L' character to specify the last day of the month.\n  - accept negative offset after the 'L' for nth last day of the month.\n  - e.g.: `L-2` would me the 2nd to last day of the month.\n- `useLastDayOfWeek: boolean`\n  - enables the 'L' character to specify the last occurrence of a weekday in a month.\n  - e.g.: `5L` would mean the last friday of the month.\n- `useNearestWeekday: boolean`\n  - enables the 'W' character to specify the use of the closest weekday.\n  - e.g.: `15W` would mean the weekday (mon-fri) closest to the 15th when the 15th is on sat-sun.\n- `useNthWeekdayOfMonth: boolean`\n  - enables the '#' character to specify the Nth weekday of the month.\n  - e.g.: `6#3` would mean the 3rd friday of the month (assuming 6 = friday).\n\n* in cron fields (like seconds, minutes etc.):\n  - `minValue: number`\n    - minimum value of your cron interpreter (like npm-node-cron only supports 0-6 for weekdays)\n    - can't be set as override\n  - `maxValue: number`\n    - minimum value of your cron interpreter (like npm-node-cron only supports 0-6 for weekdays)\n    - can't be set as override\n  - `lowerLimit?: number`\n    - lower limit for validation\n    - equal or greater than minValue\n    - if not set, default to minValue\n  - `upperLimit?: number`\n    - upper limit for validation\n    - equal or lower than maxValue\n    - if not set, defaults to maxValue\n\n### Override preset options\n\nIf you want to override a option for single cron validations, you can use the `override` property:\n\n```typescript\nconsole.log(cron('* * * * * *', {\n  preset: 'default', // second field not supported in default preset\n  override: {\n    useSeconds: true // override preset option\n  }\n}))\n\nconsole.log(cron('* 10-20 * * * *', {\n  preset: 'default',\n  override: {\n    minutes: {\n      lowerLimit: 10, // override preset option\n      upperLimit: 20 // override preset option\n    }\n  }\n}))\n```\n\n## Examples\n\n```typescript\nimport cron from 'cron-validate'\n\nconsole.log(cron('* * * * *').isValid()) // true\n\nconsole.log(cron('* * * * *').isError()) // false\n\nconsole.log(cron('* 2,3,4 * * *').isValid()) // true\n\nconsole.log(cron('0 */2 */5 * *').isValid()) // true\n\nconsole.log(cron('* * * * * *', { override: { useSeconds: true } }).isValid()) // true\n\nconsole.log(cron('* * * * * *', { override: { useYears: true } }).isValid()) // true\n\nconsole.log(\n  cron('30 * * * * *', {\n    override: {\n      useSeconds: true,\n      seconds: {\n        lowerLimit: 20,\n        upperLimit: 40,\n      },\n    },\n  }).isValid()\n) // true\n\nconsole.log(\n  cron('* 3 * * *', {\n    override: {\n      hours: {\n        lowerLimit: 0,\n        upperLimit: 2,\n      },\n    },\n  }).isValid()\n) // false\n\nconsole.log(\n  cron('* * ? * *', {\n    override: {\n      useBlankDay: true,\n    },\n  }).isValid()\n) // true\n\nconsole.log(\n  cron('* * ? * ?', {\n    override: {\n      useBlankDay: true,\n      allowOnlyOneBlankDayField: true,\n    },\n  }).isValid()\n) // false\n```\n\n## (Planned) Features\n\n- [x] Basic cron validation.\n- [x] Error messenges with information about invalid cron expression.\n- [x] Seconds field support.\n- [x] Years field support.\n- [x] Option presets (classic cron, node-cron, etc.)\n- [x] Blank '?' daysOfMonth/daysOfWeek support\n- [x] Last day of month.\n- [x] Last specific weekday of month. (e.g. last Tuesday)\n- [x] Closest weekday to a specific day of the month.\n- [x] Nth specific weekday of month. (e.g. 2nd Tuesday)\n- [x] Cron alias support.\n\n\u003chr /\u003e\n\n### Contributors\n\n \u003cul\u003e\n    \u003cli\u003e\n        \u003ca href=\"https://github.com/Airfooox\"\u003eAirfooox\u003c/a\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n        \u003ca href=\"https://github.com/GuillaumeRochat\"\u003eGuillaumeRochat\u003c/a\u003e\n    \u003c/li\u003e\n \u003c/ul\u003e\n\n\u003chr /\u003e\n\n### Used by:\n \u003cul\u003e\n    \u003cli\u003e\n        \u003ca href=\"https://github.com/breejs/bree\"\u003eBree - Job Scheduler For NodeJS\u003c/a\u003e\n    \u003c/li\u003e\n \u003c/ul\u003e\n\n\u003chr /\u003e\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAirfooox%2Fcron-validate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAirfooox%2Fcron-validate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAirfooox%2Fcron-validate/lists"}