croner 10.x

Complete instructions

Verified against croner@10.0.1 on 2026-09-07. 4 of 4 examples executed.

croner

Scope and version

This skill targets Croner 10.x, specifically the documented 10.0.1 line. It is a library, not a separate runner or CLI: import Cron and use it from your program. Documented runtime targets include Node.js >=18, Deno >=2, Bun >=1, and browsers.

Import correctly

Use the named export and instantiate it with new:

import { Cron } from "croner";

CommonJS uses:

const { Cron } = require("croner");

Do not use import Cron from "croner"; the default export was removed in v9. Do not omit new.

Constructing jobs

The constructor accepts a cron pattern, a JavaScript Date, or an ISO 8601 string as its first argument. A Date or ISO string creates a one-shot job. The second argument is optional options, and the third is an optional callback:

const job = new Cron("* * * * * *", { maxRuns: 1 }, () => {
  // called by the schedule
});

A callback can instead be supplied as the second argument:

const job = new Cron("*/5 * * * * *", () => {
  // every fifth second
});

Jobs schedule immediately unless { paused: true } is supplied. Use paused: true when constructing a job for inspection or when you intend to start it explicitly.

Calculation and enumeration

These methods calculate dates without waiting for timers:

• nextRun(startFromDate?) returns a Date.
• nextRuns(count, startFromDate?) returns scheduled Date[].
• previousRuns(count, referenceDate?) returns scheduled Date[].
• previousRun() returns the previous scheduled date.
• msToNext(startFromDate?) returns milliseconds until the next execution.
• currentRun() returns the current run information exposed by the job.

import { Cron } from "croner";
import assert from "node:assert/strict";

const job = new Cron("0 0 0 * * 7", { paused: true });
const from = new Date("2025-01-01T00:00:00Z");
const runs = job.nextRuns(2, from);

assert.equal(runs.length, 2);
assert.ok(runs[0] instanceof Date);
assert.ok(runs[1] > runs[0]);
assert.ok(job.nextRun(from) instanceof Date);
assert.ok(job.msToNext(from) >= 0);
assert.equal(job.previousRuns(1, from).length, 1);

Matching dates

match(date) checks whether a Date or date string satisfies the pattern. This was added in 10.0.0.

import { Cron } from "croner";
import assert from "node:assert/strict";

const monday = new Cron("0 0 0 * * MON", { paused: true });
assert.equal(monday.match("2024-01-01T00:00:00"), true);
assert.equal(monday.match("2024-01-02T00:00:00"), false);
assert.equal(monday.match(new Date("2024-01-01T00:00:00")), true);

One-shot dates and time zones

An ISO local time can be interpreted in a specified IANA time zone:

const job = new Cron("2024-01-23T00:00:00", {
  timezone: "Asia/Kolkata",
  paused: true,
});

The timezone option supports names such as Europe/Stockholm. getOnce() returns the original one-shot value as a Date, represented in the runtime’s date format; compare its timestamp or ISO representation rather than comparing it with the original string.

import { Cron } from "croner";
import assert from "node:assert/strict";

const job = new Cron("2030-01-23T00:00:00", {
  timezone: "Asia/Kolkata",
  paused: true,
});

assert.ok(job.getOnce() instanceof Date);
assert.equal(job.getOnce()?.toISOString(), "2030-01-22T18:30:00.000Z");
assert.ok(job.nextRun() instanceof Date);

Triggering and controlling a job

The control methods are trigger(), pause(), resume(), and stop(). Status methods include isRunning(), isStopped(), and isBusy().

stop() is permanent: a stopped job cannot be resumed. It also removes a named job from the exported scheduledJobs array. The documented import examples show Cron; do not assume the named-jobs array is available from the same documented import shape without checking the installed package.

import { Cron } from "croner";
import assert from "node:assert/strict";

let calls = 0;
const job = new Cron("* * * * * *", { paused: true }, () => {
  calls += 1;
});

assert.equal(job.isRunning(), false);
assert.equal(job.isStopped(), false);
assert.equal(job.isBusy(), false);
assert.equal(job.getPattern(), "* * * * * *");
assert.equal(job.getOnce(), null);

job.trigger();
assert.equal(calls, 1);
job.pause();
job.resume();
job.stop();
assert.equal(job.isStopped(), true);

The callback-based scheduling API requires the host runtime to remain alive for timer execution. unref is documented for Node.js and Deno, not browsers.

10.x syntax and options

10.x adds an optional seventh year field, W for nearest weekday, and + for explicit day-of-month AND day-of-week logic. Examples include:

new Cron("0 12 * * * * 2025", { paused: true });
new Cron("0 12 15W * *", { paused: true });
new Cron("0 12 15 * +FRI", { paused: true });

? is now a wildcard alias for *; it no longer has the older behavior of replacing fields with current-time values.

Use domAndDow rather than deprecated legacyMode: domAndDow: false is OR logic (the default), while domAndDow: true is AND logic.

Strict stepping is now the default. Forms such as */10, 0-59/10, and 30-50/10 are valid; legacy forms /10, 0/10, and 30/30 require { sloppyRanges: true }.

Other documented 10.x options include dayOffset, mode, and alternativeWeekdays. mode can be "auto", "5-part", "6-part", "7-part", "5-or-6-parts", or "6-or-7-parts".

Migration traps

Code copied from older majors commonly uses names that no longer exist:

• next() became nextRun().
• enumerate() became nextRuns().
• current() became currentRun().
• previous() became previousRun().
• running() became isRunning().
• busy() became isBusy().

Also account for the v9 removal of the default export and optional new.

Not covered

This skill does not cover undocumented exports such as the exact shape or import path of scheduledJobs, callback argument/context details, browser bundler configuration, or behavior requiring a long-lived timer run. It also does not cover package-specific CLI or runner usage because the research documents none.