npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

cron-validate

v1.4.5

Published

cron-validate is a cron-expression validator written in TypeScript.

Downloads

1,749,005

Readme

cron-validate

typescript dependencies Status semantic-release styled with prettier npm dependencies Status

Cron-validate is a cron-expression validator written in TypeScript. The validation options are customizable and cron fields like seconds and years are supported.

Installation

Pacakge is available on npm:

npm install -S cron-validate

Usage

Basic usage

import cron from 'cron-validate'

const cronResult = cron('* * * * *')
if (cronResult.isValid()) {
  // !cronResult.isError()
  // valid code
} else {
  // error code
}

Result system

The cron function returns a Result-type, which is either Valid<T, E> or Err<T, E>.

For checking the returned result, just use result.isValid() or result.isError()

Both result types contain values:

import cron from 'cron-validate'

const cronResult = cron('* * * * *')
if (cronResult.isValid()) {
  const validValue = cronResult.getValue()

  // The valid value is a object containing all cron fields
  console.log(validValue)
  // In this case, it would be:
  // { seconds: undefined, minutes: '*', hours: '*', daysOfMonth: '*', months: '*', daysOfWeek: '*', years: undefiend }
} else {
  const errorValue = cronResult.getError()

  // The error value contains an array of strings, which represent the cron validation errors.
  console.log(errorValue) // string[] of error messages
}

Make 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.

For further information, you can check out https://github.com/gDelgado14/neverthrow, because I used and modified his code for this package. (Therefor not every documented function on his package is available on this package.)

Options / Configuration

To 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.

Presets

The following presets are already defined by cron-validate:

  • default (see: http://crontab.org/)
  • npm-node-cron (see: https://github.com/kelektiv/node-cron)
  • aws-cloud-watch (see: https://docs.aws.amazon.com/de_de/AmazonCloudWatch/latest/events/ScheduledEvents.html)
  • npm-cron-schedule (see: https://github.com/P4sca1/cron-schedule)

To select a preset for your validation, you can simply do this:

cron('* * * * *', {
  preset: 'npm-cron-schedule',
})

Defining and using your own preset

To define your own preset, use this:

registerOptionPreset('YOUR-PRESET-ID', {
  presetId: 'YOUR-PRESET-ID',
  useSeconds: false,
  useYears: false,
  useAliases: false, // optional, default to false
  useBlankDay: false,
  allowOnlyOneBlankDayField: false,
  mustHaveBlankDayField: false, // optional, default to false
  useLastDayOfMonth: false, // optional, default to false
  useLastDayOfWeek: false, // optional, default to false
  useNearestWeekday: false, // optional, default to false
  useNthWeekdayOfMonth: false, // optional, default to false
  seconds: {
    minValue: 0,
    maxValue: 59,
    lowerLimit: 0, // optional, default to minValue
    upperLimit: 59, // optional, default to maxValue
  },
  minutes: {
    minValue: 0,
    maxValue: 59,
    lowerLimit: 0, // optional, default to minValue
    upperLimit: 59, // optional, default to maxValue
  },
  hours: {
    minValue: 0,
    maxValue: 23,
    lowerLimit: 0, // optional, default to minValue
    upperLimit: 23, // optional, default to maxValue
  },
  daysOfMonth: {
    minValue: 1,
    maxValue: 31,
    lowerLimit: 1, // optional, default to minValue
    upperLimit: 31, // optional, default to maxValue
  },
  months: {
    minValue: 0,
    maxValue: 12,
    lowerLimit: 0, // optional, default to minValue
    upperLimit: 12, // optional, default to maxValue
  },
  daysOfWeek: {
    minValue: 1,
    maxValue: 7,
    lowerLimit: 1, // optional, default to minValue
    upperLimit: 7, // optional, default to maxValue
  },
  years: {
    minValue: 1970,
    maxValue: 2099,
    lowerLimit: 1970, // optional, default to minValue
    upperLimit: 2099, // optional, default to maxValue
  },
})

The preset properties explained:

  • presetId: string
    • same id as in first function parameter
  • useSeconds: boolean
    • enables seconds field in cron expression
  • useYears: boolean
    • enables years field in cron expression
  • useAliases: boolean
    • enables aliases for month and daysOfWeek fields (ignores limits for month and daysOfWeek, so be aware of that)
  • useBlankDay: boolean
    • enables blank day notation '?' in daysOfMonth and daysOfWeek field
  • allowOnlyOneBlankDayField: boolean
    • requires a day field to not be blank (so not both day fields can be blank)
  • mustHaveBlankDayField: boolean
    • requires a day field to be blank (so not both day fields are specified)
    • when mixed with allowOnlyOneBlankDayField, it means that there will always be either day or day of week as ?
  • useLastDayOfMonth: boolean
    • enables the 'L' character to specify the last day of the month.
    • accept negative offset after the 'L' for nth last day of the month.
    • e.g.: L-2 would me the 2nd to last day of the month.
  • useLastDayOfWeek: boolean
    • enables the 'L' character to specify the last occurrence of a weekday in a month.
    • e.g.: 5L would mean the last friday of the month.
  • useNearestWeekday: boolean
    • enables the 'W' character to specify the use of the closest weekday.
    • e.g.: 15W would mean the weekday (mon-fri) closest to the 15th when the 15th is on sat-sun.
  • useNthWeekdayOfMonth: boolean
    • enables the '#' character to specify the Nth weekday of the month.
    • e.g.: 6#3 would mean the 3rd friday of the month (assuming 6 = friday).
  • in cron fields (like seconds, minutes etc.):
    • minValue: number
      • minimum value of your cron interpreter (like npm-node-cron only supports 0-6 for weekdays)
      • can't be set as override
    • maxValue: number
      • minimum value of your cron interpreter (like npm-node-cron only supports 0-6 for weekdays)
      • can't be set as override
    • lowerLimit?: number
      • lower limit for validation
      • equal or greater than minValue
      • if not set, default to minValue
    • upperLimit?: number
      • upper limit for validation
      • equal or lower than maxValue
      • if not set, defaults to maxValue

Override preset options

If you want to override a option for single cron validations, you can use the override property:

console.log(cron('* * * * * *', {
  preset: 'default' // second field not supported in default preset
  override: {
    useSeconds: true // override preset option
  }
}))

console.log(cron('* 10-20 * * * *', {
  preset: 'default'
  override: {
    minutes: {
      lowerLimit: 10, // override preset option
      upperLimit: 20 // override preset option
    }
  }
}))

Examples

import cron from 'cron-validate'

console.log(cron('* * * * *').isValid()) // true

console.log(cron('* * * * *').isError()) // false

console.log(cron('* 2,3,4 * * *').isValid()) // true

console.log(cron('0 */2 */5 * *').isValid()) // true

console.log(cron('* * * * * *', { override: { useSeconds: true } }).isValid()) // true

console.log(cron('* * * * * *', { override: { useYears: true } }).isValid()) // true

console.log(
  cron('30 * * * * *', {
    override: {
      useSeconds: true,
      seconds: {
        lowerLimit: 20,
        upperLimit: 40,
      },
    },
  }).isValid()
) // true

console.log(
  cron('* 3 * * *', {
    override: {
      hours: {
        lowerLimit: 0,
        upperLimit: 2,
      },
    },
  }).isValid()
) // false

console.log(
  cron('* * ? * *', {
    override: {
      useBlankDay: true,
    },
  }).isValid()
) // true

console.log(
  cron('* * ? * ?', {
    override: {
      useBlankDay: true,
      allowOnlyOneBlankDayField: true,
    },
  }).isValid()
) // false

(Planned) Features

  • [x] Basic cron validation.
  • [x] Error messenges with information about invalid cron expression.
  • [x] Seconds field support.
  • [x] Years field support.
  • [x] Option presets (classic cron, node-cron, etc.)
  • [x] Blank '?' daysOfMonth/daysOfWeek support
  • [x] Last day of month.
  • [x] Last specific weekday of month. (e.g. last Tuesday)
  • [x] Closest weekday to a specific day of the month.
  • [x] Nth specific weekday of month. (e.g. 2nd Tuesday)
  • [x] Cron alias support.

Contributors

Used by: