{"id":13013,"library":"cron-schedule","title":"Cron Schedule Parser and Scheduler","description":"cron-schedule is a robust, zero-dependency library designed for parsing cron expressions and scheduling tasks across Node.js, Deno, and browser environments. The current stable version is 6.0.0. The project maintains an active release cadence, frequently publishing patch and minor versions to address bugs and introduce features, with major versions typically aligning with Node.js End-of-Life cycles to ensure compatibility with modern runtime environments. Key differentiators include its complete lack of external dependencies, support for a wide range of JavaScript runtimes, a lightweight footprint, and full tree-shakeability. It provides comprehensive functionalities for parsing cron strings, calculating next or previous scheduled dates, generating date iterators, and directly scheduling function calls based on cron patterns. The library also offers full TypeScript support and is published on JSR, making it a versatile choice for various JavaScript/TypeScript projects.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/P4sca1/cron-schedule","tags":["javascript","cron","schedule","typescript","job parser","interval","iterator","deno"],"install":[{"cmd":"npm install cron-schedule","lang":"bash","label":"npm"},{"cmd":"yarn add cron-schedule","lang":"bash","label":"yarn"},{"cmd":"pnpm add cron-schedule","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only since v4.0.0. This is the primary function for parsing cron strings.","wrong":"const { parseCronExpression } = require('cron-schedule');","symbol":"parseCronExpression","correct":"import { parseCronExpression } from 'cron-schedule';"},{"note":"Used for scheduling functions. Note the specific subpath 'cron-schedule/schedulers'. For environments without conditional exports, use 'cron-schedule/dist/schedulers' for v4.0.0+.","wrong":"import { createCronScheduler } from 'cron-schedule';","symbol":"createCronScheduler","correct":"import { createCronScheduler } from 'cron-schedule/schedulers';"},{"note":"TypeScript type for the object returned by parseCronExpression. Essential for type-safe usage.","symbol":"CronExpression","correct":"import type { CronExpression } from 'cron-schedule';"}],"quickstart":{"code":"import { parseCronExpression, createCronScheduler } from 'cron-schedule';\n\n// 1. Parsing a cron expression and calculating future dates\nconst cronExpressionString = '0 0 * * MON-FRI'; // At 00:00 on every weekday (Monday through Friday)\nconst cron = parseCronExpression(cronExpressionString);\n\nconst startDate = new Date('2026-04-21T00:00:00.000Z'); // A Monday for demonstration\nconsole.log(`Starting date: ${startDate.toISOString()}`);\n\nconst nextDate = cron.getNextDate(startDate);\nconsole.log(`Next scheduled date: ${nextDate.toISOString()}`);\n\nconst nextFiveDates = cron.getNextDates(5, startDate);\nconsole.log('Next five scheduled dates:');\nnextFiveDates.forEach((date, index) => {\n  console.log(`  ${index + 1}: ${date.toISOString()}`);\n});\n\n// 2. Setting up a basic scheduler (note: this only sets it up, it won't run in a short-lived script)\n// In a real application, this would run indefinitely in a Node.js process.\nconst dailyJob = createCronScheduler('0 0 * * *', () => {\n  console.log(`Daily job executed at ${new Date().toISOString()}`);\n});\nconsole.log('\\nScheduler for \"0 0 * * *\" created (runs daily at midnight). It will execute in a long-running process.');\n// To prevent the quickstart from hanging, we'll stop it immediately for demo purposes.\ndailyJob.stop();\nconsole.log('Scheduler stopped immediately for quickstart demonstration.');\n","lang":"typescript","description":"Demonstrates parsing a cron expression to calculate next occurrences and how to set up a basic, albeit short-lived, cron job scheduler."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20, 22, or 24.","message":"Support for Node.js 18 (which reached End of Life) has been dropped.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Upgrade your Node.js environment to version 16 or higher (20+ for v6).","message":"Support for Node.js 14 was dropped due to its End of Life and missing ESM module support.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If experiencing import issues with schedulers, change your import statement from `import { createCronScheduler } from 'cron-schedule/schedulers'` to `import { createCronScheduler } from 'cron-schedule/dist/schedulers'`.","message":"For environments that do not support conditional exports, the import path for schedulers was changed.","severity":"breaking","affected_versions":">=4.0.0-next.2"},{"fix":"Do not install or use `cron-schedule@5.0.0`. Instead, use `cron-schedule@5.0.1` or any subsequent version.","message":"Version 5.0.0 was not published to npm due to a build error.","severity":"gotcha","affected_versions":"=5.0.0"},{"fix":"Ensure you are using ECMAScript module imports (`import ... from 'package'`) rather than CommonJS `require()` syntax.","message":"The library transitioned to an ESM-only build in version 4.0.0.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update to `cron-schedule@5.0.4` or a newer version.","cause":"A bug in the cron parser for the `@monthly` macro.","error":"Incorrect date returned when using the @monthly cron macro."},{"fix":"Update to `cron-schedule@5.0.3` or a newer version for correct Sunday range starting, and `cron-schedule@4.0.0` or newer for general Sunday range parsing fixes.","cause":"Bugs in handling Sunday in weekday ranges, particularly when Sunday starts a range.","error":"Weekday ranges including Sunday (e.g., '0-7' or 'SUN-SAT') are parsed incorrectly."},{"fix":"Update to `cron-schedule@5.0.1` or a newer version.","cause":"An edge case bug in the `getPrevDate` calculation logic.","error":"cron.getPrevDate() returns a wrong result for months with fewer than 31 days."},{"fix":"Update to `cron-schedule@5.0.2` or a newer version which includes improved whitespace handling.","cause":"The parser was not sufficiently resilient to handle arbitrary extra whitespaces within cron expressions.","error":"Cron expression parsing fails or produces incorrect results with extra whitespace characters."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}