{"id":10688,"library":"croner","title":"Croner: JavaScript Cron Scheduler","description":"Croner is a zero-dependency JavaScript library designed for scheduling and executing functions based on cron expressions across all JavaScript environments, including Node.js (v18.0+) and modern browsers. The current stable version is 10.0.1, with a consistent release cadence for bug fixes and minor enhancements, as indicated by recent development builds. A major differentiator is its full compliance with OCPS 1.4, offering advanced scheduling capabilities like an optional seventh field for year specification and robust handling of complex cron patterns. Version 10 introduced features such as the `match()` method for pattern validation, `dayOffset` for relative scheduling, and improved DST fall-back behavior. It stands out for its isomorphic design and comprehensive feature set without external dependencies, providing a reliable and lightweight solution for various task scheduling needs.","status":"active","version":"10.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/hexagon/croner","tags":["javascript","cron","front-end","backend","parser","croner","schedule","scheduler","timer","typescript"],"install":[{"cmd":"npm install croner","lang":"bash","label":"npm"},{"cmd":"yarn add croner","lang":"bash","label":"yarn"},{"cmd":"pnpm add croner","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Croner is primarily designed for ESM. While `require` might work in some CJS contexts, direct ESM import is recommended and necessary for Node.js >=18.","wrong":"const Cron = require('croner');","symbol":"Cron","correct":"import { Cron } from 'croner';"},{"note":"Use `import type` for type definitions to ensure they are stripped during transpilation, avoiding runtime errors in some environments.","symbol":"CronOptions","correct":"import type { CronOptions } from 'croner';"},{"note":"This type represents the instance returned when creating a new Cron job, providing methods like `nextRuns()` and `stop()`.","symbol":"CronJob","correct":"import type { CronJob } from 'croner';"}],"quickstart":{"code":"import { Cron } from 'croner';\n\n// Schedule a job to run every minute\nconst job = new Cron('* * * * *', () => {\n  console.log(`Cron job executed at ${new Date().toISOString()}`);\n});\n\n// Schedule a job to run once on a specific date in the future\nconst oneTimeJob = new Cron(new Date(Date.now() + 1000 * 60 * 5), () => {\n  console.log(`One-time job executed after 5 minutes at ${new Date().toISOString()}`);\n  oneTimeJob.stop(); // Stop the job after it runs once\n}, { timezone: 'Europe/Stockholm', name: 'One-Time Task' });\n\n// Enumerate upcoming runs\nconsole.log('Next 5 runs for the minute job:', job.nextRuns(5).map(d => d.toISOString()));\n\n// Stop the minute job after 10 minutes for demonstration\nsetTimeout(() => {\n  job.stop();\n  console.log('Cron job stopped after 10 minutes.');\n}, 1000 * 60 * 10);","lang":"typescript","description":"Demonstrates how to create recurring and one-time cron jobs, retrieve next execution times, and stop a running job."},"warnings":[{"fix":"Review your cron patterns and configuration options against the Croner v10 documentation. Consider enabling `sloppyRanges` if you rely on more permissive parsing from older versions.","message":"Version 10.0.0 introduced significant changes, including full OCPS 1.4 compliance with optional seventh field for years, `dayOffset`, and the new `match()` method. Existing cron patterns or configurations relying on previous parsing rules might need review, particularly if they implicitly relied on behaviors now covered by stricter OCPS compliance or `sloppyRanges`.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Consult the Croner documentation regarding DST overlap behavior and test your cron patterns thoroughly around known DST transition dates, especially for mission-critical jobs.","message":"Daylight Saving Time (DST) fall-back scheduling behavior changed in 10.0.2-dev.0 (and subsequent stable releases). Specific-time patterns (e.g., `0 30 2 * * *`) now run once at the first occurrence during the overlap, while high-frequency patterns (e.g., `* * * * * *`) continue executing through the overlap period without gaps. This might alter expected execution times during DST transitions.","severity":"breaking","affected_versions":">=10.0.2-dev.0"},{"fix":"Immediately upgrade to `croner@10.0.1` or a later version if you are on 10.0.0 and encountering TypeScript-related issues.","message":"The initial 10.0.0 release had TypeScript definition distribution issues, potentially leading to compilation errors. This was promptly fixed in 10.0.1.","severity":"gotcha","affected_versions":"10.0.0"},{"fix":"For one-time jobs, set `allowPast: true` in the Cron options if there's a possibility of the scheduled time having just passed at creation: `new Cron(date, callback, { allowPast: true });`","message":"For 'once' jobs, the `allowPast` option is critical. If a job is created at or near its scheduled time and that time has already passed according to system clock, it might not fire. The `allowPast` option (introduced in 10.0.2-dev.1) addresses this by allowing such jobs to fire immediately.","severity":"gotcha","affected_versions":"<10.0.2-dev.1"},{"fix":"Ensure that any errors thrown within the `catch` callback itself are properly handled to prevent the job from unexpectedly stopping. Upgrade to the latest version to benefit from fixes in this area.","message":"Cron jobs configured with the `protect` option might stop entirely if an error thrown within the `catch` callback is not handled. This behavior was addressed in 10.0.0-dev.8.","severity":"gotcha","affected_versions":"<10.0.0-dev.8"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use ESM named import: `import { Cron } from 'croner';`. Ensure your project is configured for ESM if targeting modern Node.js environments (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to import Croner using CommonJS `require()` syntax in an environment configured for ESM, or incorrectly using a default import when it's a named export.","error":"TypeError: Cron is not a constructor"},{"fix":"Upgrade to `croner@10.0.1` or later. Ensure your `tsconfig.json` targets a sufficiently modern JavaScript version and module system.","cause":"This TypeScript error can occur if you are on `croner@10.0.0` due to a distribution issue with its type definitions, or if your TypeScript configuration is out of date.","error":"Property 'nextRuns' does not exist on type 'Cron'."},{"fix":"Verify your cron pattern against OCPS 1.4 specifications. Pay attention to valid ranges, characters, and field counts (up to 7 fields including year). If you need more permissive parsing for legacy patterns, consider adding `{ sloppyRanges: true }` to your Cron options.","cause":"The provided cron expression is malformed, uses non-standard syntax not supported by OCPS 1.4, or conflicts with stricter parsing introduced in v10 (e.g., for 'L' or 'W' modifiers).","error":"Error: Invalid cron pattern: '<your-pattern>'"},{"fix":"Specify the `timezone` option explicitly (e.g., `{ timezone: 'America/New_York' }`). Review DST behavior changes in v10.0.2-dev.0. For 'once' jobs, ensure `allowPast: true` is set if the job might be initialized after its nominal start time.","cause":"Common causes include incorrect timezone configuration, misunderstanding DST transition behavior (especially for fall-back), or issues with 'once' jobs created too close to their scheduled time.","error":"Cron job did not fire at the expected time (or fired multiple times unexpectedly)"}],"ecosystem":"npm"}