Job lifecycle

States

isRunning() returning true means a job is scheduled. It doesn’t mean its callback is executing right now, and between ticks nothing is.

A job also stays running after its callback fails, because a failed run doesn’t affect the schedule. To find out whether a job is healthy, check its metrics.

Control methods

Calling a method in a state where it doesn’t apply does nothing and doesn’t throw.

On a Baker, the same methods take the job’s name, except that start() is called bake(). Each one also has a version for all jobs: bakeAll(), stopAll(), pauseAll(), resumeAll() and destroyAll().

destroy() is the only one that fires onComplete. On a Baker it also removes the job, so the name is free to use again. baker.remove(name) does exactly the same thing.

Callbacks already in progress

stop() and pause() cancel future runs but don’t interrupt a run in progress. That callback finishes normally and its result is still recorded. There is no built-in way to wait for it, so see shutting down if you need that.

Ticks during a pause

resume() works out the next tick from the current time. Anything that came due while the job was paused is dropped, not caught up.

Starting jobs

There are three ways to start a job on a Baker.

// 1. Start it yourself, whenever you're ready
baker.add({ name: "a", cron: "@hourly", callback });
baker.bake("a"); // or baker.bakeAll()

// 2. Start one job as soon as it's added
baker.add({ name: "b", cron: "@hourly", start: true, callback });

// 3. Start every job as soon as it's added
const auto = Baker.create({ autoStart: true });
await auto.ready();
auto.add({ name: "c", cron: "@hourly", callback });
auto.add({ name: "d", cron: "@hourly", start: false, callback }); // opts out

In 0.4.0, autoStart only starts the jobs that exist when the baker finishes initialising, so you need to start any added later. New jobs start automatically from the next release.

Running on start

By default a job waits for its first scheduled tick, which could be a month away for @monthly. immediate: true also runs it once as soon as it starts, and delay holds that first run back.

baker.add({
  name: "warm-cache",
  cron: "@hourly",
  immediate: true,
  delay: "10s",
  callback: warmCache,
});

delay is a number of milliseconds, or a string with a unit of ms, s, m, h or d, such as "500ms" or "2m". A string with no unit counts as milliseconds. Negative numbers, decimals in strings and other units throw when the job is created.

• delay has no effect without immediate: true.
• Nothing runs until the delay is over, even if a normal tick comes due in the meantime.
• The first run happens on every start(), including restarting a stopped or paused job. resume() doesn’t trigger it.

Reading the schedule

Two of these are easy to misread:

• nextExecution() returns the current time for a stopped or paused job, so check isRunning() first.
• lastExecution() returns the most recent time the schedule matched if the job has never run. To know whether it has really run, look at getHistory().

Names that don’t exist

Baker doesn’t throw for an unknown job name. Control methods do nothing, getStatus() returns "stopped", isRunning() returns false, remaining() returns 0, and the date methods return the current time. A typo looks like a stopped job, so use getJobNames() if you need to tell them apart.

Priority Next release

priority is a number that sets the order bakeAll() starts jobs in, highest first. It defaults to 0, and ties start in the order they were added.

baker.add({ name: "first", cron: "@hourly", priority: 10, callback });
baker.add({ name: "second", cron: "@hourly", priority: 5, callback });
baker.bakeAll();

That’s all priority does. It doesn’t reserve resources or let one job interrupt another, and it has no effect on two jobs that fall due at the same moment. In 0.4.0, jobs start in the order they were added regardless of priority.