everytime

Good-enough natural language replacement for cron expressions in JavaScript. Write "every day at 3pm" instead of "0 15 * * *".

This library can be janky! It doesn't support logical expressions and has quirks. However, it is consistent in its behavior.

Installation

npm install everytime

Usage

const everytime = require('everytime');

// Generate dates from a natural language query
for (const date of everytime('each day at 3pm').take(5)) {
  console.log(date);
}

Examples

// Every day at noon
everytime('every day at noon')
// → 2025-01-01T12:00:00, 2025-01-02T12:00:00, ...

// Every hour after 3pm
everytime('every hour after 3pm')
// → 2025-01-01T15:00:00, 2025-01-01T16:00:00, ...

// Multiple schedules (semicolon-separated)
everytime('monday at 9am; monday at 5pm')
// → 2025-01-06T09:00:00, 2025-01-06T17:00:00, 2025-01-13T09:00:00, ...

// Every other day at 6pm
everytime('every other day at 6pm')
// → 2025-01-01T18:00:00, 2025-01-03T18:00:00, ...

// Specific date ranges
everytime('from 9am to 5pm on June 7th 2025 every 30 minutes', {
  startDate: '2025-06-01',
  endDate: '2025-06-30'
})
// → 2025-06-07T09:00:00, 2025-06-07T09:30:00, ..., 2025-06-07T17:00:00

// Weekends
everytime('each day on weekends at 6pm')
// → 2025-10-04T18:00:00, 2025-10-05T18:00:00, 2025-10-11T18:00:00

// Monthly schedules
everytime('on the 1st at 2pm')
// → 2025-01-01T14:00:00, 2025-02-01T14:00:00, ...

// Duration-based
everytime('every 3 hours and 30 minutes')
// → Every 3.5 hours starting from now

API

everytime(query, options?)

Generates recurring dates from a natural language query.

Parameters:

• query: Natural language expression describing when events should occur
  • Can include time expressions: "at 3pm", "at noon", "at midnight"
  • Can include intervals: "every day", "every hour", "every 30 minutes"
  • Can include day/date specifications: "monday", "weekends", "on the 1st"
  • Can include ranges: "from 9am to 5pm"
  • Can include absolute dates: "2025-02-10", "August 27th"
  • Can combine multiple schedules with semicolons: "monday at 9am; friday at 5pm"
• options:
  • timezone: Timezone name (e.g., 'America/Vancouver'). Defaults to local timezone.
  • startDate: Start generating dates from this point. Defaults to now.
  • endDate: Stop generating dates after this point, leave unset to never stop.

Returns: Generator yielding Date objects in chronological order.

Example:

const dates = everytime('every day at noon', {
  timezone: 'America/New_York',
  startDate: '2025-01-01',
  endDate: '2025-12-31'
});

for (const date of dates) {
  console.log(date);
}

Compromise

This library uses compromise (with compromise-dates) for natural language parsing and spacetime for date manipulation.

Limitations

This library has several limitations:

1. No logical expressions: Can't handle "every weekday except holidays" or "monday OR friday". Use semicolons for multiple schedules instead.

2. Compromise quirks: "every weekday" includes weekends due to how compromise parses the phrase. Test your expressions!

3. Consistent but not always intuitive: The same query will always produce the same results, but those results might not match your expectations.

UI Recommendation

When building a UI around this library, always show the next 5 to 10 generated dates for any expression the user enters. This makes it immediately clear what the schedule will be and allows users to iterate on their expression until it produces the desired results.

License

Licensed under the MIT License.

Made with ❤ by Lua (foxgirl.dev).