Croner: JavaScript Cron Scheduler

Common errors

• TypeError: Cron is not a constructor

  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.
  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`).

• Property 'nextRuns' does not exist on type 'Cron'.

  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.
  fix Upgrade to `croner@10.0.1` or later. Ensure your `tsconfig.json` targets a sufficiently modern JavaScript version and module system.

• Error: Invalid cron pattern: '<your-pattern>'

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

• Cron job did not fire at the expected time (or fired multiple times unexpectedly)

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

Warnings

• breaking 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`.
  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.
• breaking 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.
  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.
• gotcha The initial 10.0.0 release had TypeScript definition distribution issues, potentially leading to compilation errors. This was promptly fixed in 10.0.1.
  Fix: Immediately upgrade to `croner@10.0.1` or a later version if you are on 10.0.0 and encountering TypeScript-related issues.
• gotcha 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.
  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 });`
• gotcha 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.
  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.

Install

• npm install croner npm
• yarn add croner yarn
• pnpm add croner pnpm

Imports

• Cron
  wrong:

  const Cron = require('croner');

  correct:

  import { Cron } from 'croner';

  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.
• CronOptions

  import type { CronOptions } from 'croner';

  Use `import type` for type definitions to ensure they are stripped during transpilation, avoiding runtime errors in some environments.
• CronJob

  import type { CronJob } from 'croner';

  This type represents the instance returned when creating a new Cron job, providing methods like `nextRuns()` and `stop()`.

Quickstart

Demonstrates how to create recurring and one-time cron jobs, retrieve next execution times, and stop a running job.

import { Cron } from 'croner';

// Schedule a job to run every minute
const job = new Cron('* * * * *', () => {
  console.log(`Cron job executed at ${new Date().toISOString()}`);
});

// Schedule a job to run once on a specific date in the future
const oneTimeJob = new Cron(new Date(Date.now() + 1000 * 60 * 5), () => {
  console.log(`One-time job executed after 5 minutes at ${new Date().toISOString()}`);
  oneTimeJob.stop(); // Stop the job after it runs once
}, { timezone: 'Europe/Stockholm', name: 'One-Time Task' });

// Enumerate upcoming runs
console.log('Next 5 runs for the minute job:', job.nextRuns(5).map(d => d.toISOString()));

// Stop the minute job after 10 minutes for demonstration
setTimeout(() => {
  job.stop();
  console.log('Cron job stopped after 10 minutes.');
}, 1000 * 60 * 10);