Cronbake - A Powerful and Flexible Cron Job Manager powered by Bun

Cronbake is a powerful and flexible cron job manager built with TypeScript powered by Bun. It provides an easy-to-use interface for scheduling and managing cron jobs with a wide range of options and features. Cronbake is designed to be lightweight, efficient, and highly configurable, making it suitable for a variety of use cases.

Features

Expressive Cron Expressions

Cronbake supports a wide range of cron expressions, including standard formats, ranges, steps, lists, and presets. You can use the following formats or presets:

Wildcards: * * * * * * (second minute hour day month day-of-week)
Ranges: 1-10 * * * * *
Steps: 1-10/2 * * * * * (can be used with wildcards and ranges)
Lists: 1,2,3 * * * * *
Presets:
- @every_second
- @every_minute
- @yearly or @annually
- @monthly
- @weekly
- @daily
- @hourly
Custom Presets: (as for now you can only use one presets at a time for each cron job in the format of @<preset>_<value> the support for multiple presets will be added in the future)
- @every_<number>_<unit> (where <unit> is one of seconds, minutes, hours, dayOfMonth, months, dayOfWeek)
- @at_<hour>:<minute> (where <hour> is a number between 0 and 23, and <minute> is a number between 0 and 59)
- @on_<day> (where <day> is one of sunday, monday, tuesday, wednesday, thursday, friday, saturday)
- @between_<hour>_<hour> (where <hour> is a number between 0 and 23)

This a simple graph to show how the cron expression works:

* * * * * * (second minute hour day month day-of-week)
| | | | | |
| | | | | +-- day of the week (0 - 6) (Sunday to Saturday)
| | | | +---- month (1 - 12)
| | | +------ day of the month (1 - 31)
| | +-------- hour (0 - 23)
| +---------- minute (0 - 59)
+------------ second (0 - 59)

Advanced Scheduling

Cronbake provides two scheduling modes for optimal performance:

Calculated Timeouts (default): More efficient scheduling using precise timeout calculations
Polling Interval: Traditional polling-based scheduling with configurable intervals

Additional scheduling controls:

Immediate/Delayed First Run: Run the first callback immediately (immediate: true) or after a delay (delay: '10s').
Overrun Protection: Skip new starts if a previous run is still executing (overrunProtection: true).

Cron Job Management

Cronbake provides a simple and intuitive interface for managing cron jobs. You can easily add, remove, start, stop, pause, resume, and destroy cron jobs using the Baker class.

Job Status and Control

Cronbake supports comprehensive job control with multiple status states:

running: Job is actively executing
stopped: Job is not executing
paused: Job is temporarily suspended
error: Job encountered an error

Real-time Status and Metrics

Cronbake allows you to get the current status, last execution time, next execution time, remaining time, execution history, and comprehensive metrics for each cron job. This information is useful for monitoring, debugging, and performance analysis.

Execution History and Metrics

Track detailed execution history and performance metrics including:

Total executions
Successful/failed execution counts
Average execution time
Execution history with timestamps and durations
Error tracking and reporting

Job Persistence (opt-in)

Opt in by setting persistence.enabled: true
Use await baker.ready() before interacting when autoRestore restores jobs for you
Select file- or Redis-backed providers depending on your environment

Callbacks and Error Handling

With Cronbake, you can execute custom functions when a cron job ticks (runs), completes, or encounters errors. Enhanced error handling provides detailed error information and custom error handlers.

Priority System

Jobs can be assigned priority levels for execution ordering and resource management.

Type-safe

Cronbake is built with TypeScript, ensuring type safety and better tooling support. This helps catch errors during development and provides better code navigation and auto-completion.

Async Support

Full support for asynchronous callbacks and Promise-based operations.

Installation

You can install Cronbake using your preferred package manager:

# With Bun
bun add cronbake

# With npm
npm install cronbake

# With yarn
yarn add cronbake

# With pnpm
pnpm add cronbake

Quick Start (stateless defaults)

To get started with Cronbake, create a new instance of the Baker class and add cron jobs using the add method:

import Baker from "cronbake";

// Create a new Baker instance
const baker = Baker.create();

// Add a cron job that runs daily at midnight
const dailyJob = baker.add({
  name: "daily-job",
  cron: "0 0 0 * * *", // Runs daily at midnight
  callback: () => {
    console.log("Daily job executed!");
  },
});

// Runs every first 3 minutes for the first 3 hours of every day
const everyFirst3MinutesJob = baker.add({
  name: "every-first-3-minutes-job",
  cron: "0 0-3 1,2,3 * * *", // Runs every first 3 minutes for the first 3 hours of every day
  callback: () => {
    console.log("Every first 3 minutes job executed!");
  },
});

// using custom presets
const everyMinuteJob = baker.add({
  name: "every-minute-job",
  cron: "@every_minute",
  callback: () => {
    console.log("Every minute job executed!");
  },
});

// Start all cron jobs
baker.bakeAll();

// Process exits? No problem—cron definitions live only in memory by default.
// Enable persistence to keep jobs across restarts (see next section).

Persistence & Advanced Controls

When you need your job definitions to survive application restarts, opt into persistence explicitly:

import Baker from "cronbake";
import { FilePersistenceProvider } from "cronbake";

const baker = Baker.create({
  persistence: {
    enabled: true,
    strategy: "file",
    provider: new FilePersistenceProvider("./cronbake-state.json"),
    autoRestore: true,
  },
});

await baker.ready(); // wait for autoRestore before interacting with jobs

baker.add({
  name: "daily-job",
  cron: "@daily",
  persist: true, // default when persistence is enabled, but explicit for clarity
  callback: () => console.log("runs daily"),
});

// Jobs with persist: false stay ephemeral even when persistence is on
baker.add({
  name: "one-off",
  cron: "@hourly",
  persist: false,
  callback: () => console.log("won't be restored"),
});

Examples

This repo includes runnable TypeScript scripts under examples/. They are excluded from the published package (only dist/ ships), so you can use them freely as references:

examples/basic.ts – minimal stateless jobs with graceful shutdown
examples/persistence.ts – file-backed persistence plus await baker.ready() and mixed persist flags

Run them with your favorite TS runner, e.g. pnpm tsx examples/basic.ts.

Immediate/Delayed First Run and Overrun Protection

import Baker from "cronbake";

const baker = Baker.create();

baker.add({
  name: "fast-job",
  cron: "@every_10_seconds",
  immediate: true, // run the first time right away
  delay: "2s", // but wait 2 seconds before that first run
  overrunProtection: true, // skip overlaps if a previous run still executes
  callback: async () => {
    // Do work
  },
});

baker.bakeAll();

Advanced Configuration

You can configure the Baker with advanced options:

import Baker from "cronbake";

const baker = Baker.create({
  autoStart: false,
  enableMetrics: true,
  schedulerConfig: {
    useCalculatedTimeouts: true,
    pollingInterval: 1000,
    maxHistoryEntries: 100,
  },
  persistence: {
    enabled: true,
    filePath: "./cronbake-state.json",
    autoRestore: true,
  },
  onError: (error, jobName) => {
    console.error(`Job ${jobName} failed:`, error.message);
  },
});

Job Configuration Options

Jobs can be configured with various options:

const job = baker.add({
  name: "advanced-job",
  cron: "*/30 * * * * *",
  callback: async () => {
    // Your async job logic here
    await processData();
  },
  onTick: () => {
    console.log("Job started");
  },
  onComplete: () => {
    console.log("Job completed");
  },
  onError: (error) => {
    console.error("Job failed:", error.message);
  },
  priority: 5,
  maxHistory: 50,
  start: true,
  persist: true, // default true when persistence enabled; set false for ephemeral
});

Job Control and Monitoring

You can manage cron jobs using the various methods provided by the Baker class:

// Start, stop, pause, and resume jobs
baker.bake("job-name");
baker.stop("job-name");
baker.pause("job-name");
baker.resume("job-name");

// Bulk operations
baker.bakeAll();
baker.stopAll();
baker.pauseAll();
baker.resumeAll();

// Get job information
const status = baker.getStatus("job-name");
const isRunning = baker.isRunning("job-name");
const nextRun = baker.nextExecution("job-name");
const remaining = baker.remaining("job-name");

// Get metrics and history
const metrics = baker.getMetrics("job-name");
const history = baker.getHistory("job-name");

// Job management
const jobNames = baker.getJobNames();
const allJobs = baker.getAllJobs();

Persistence Operations

Save and restore job state:

await baker.ready(); // Wait for autoRestore to finish before inspecting jobs

// Save current state
await baker.saveState();

// Restore from saved state
await baker.restoreState();

Using a Custom Logger

You can provide a custom logger that implements the Logger interface to log messages from Cronbake:

import { Baker, Logger } from 'cronbake';

// Using a logging library like logtape
import { getLogger } from '@logtape/logtape';

const logger = getLogger(['myapp', 'cron']);

export const baker = Baker.create({
  logger
});

// Or create a custom logger
const customLogger: Logger = {
  info: (msg, ...args) => console.log(`[INFO] ${msg}`, ...args),
  warn: (msg, ...args) => console.warn(`[WARN] ${msg}`, ...args),
  error: (msg, ...args) => console.error(`[ERROR] ${msg}`, ...args),
  debug: (msg, ...args) => console.debug(`[DEBUG] ${msg}`, ...args),
};

export const bakerWithCustomLogger = Baker.create({
  logger: customLogger
});

You can also override the logger per job:

const baker = Baker.create({ logger: defaultLogger });

baker.add({
  name: 'special-job',
  cron: '@daily',
  logger: specialLogger, // This job uses a different logger
  callback: () => console.log('Hello!'),
});

Persistence Providers (File and Redis)

Cronbake uses pluggable providers for persistence. A file provider is included by default. A Redis provider is available; you inject your Redis client.

import {
  Baker,
  FilePersistenceProvider,
  RedisPersistenceProvider,
} from "cronbake";

// File-based
const bakerFile = Baker.create({
  persistence: {
    enabled: true,
    strategy: "file",
    provider: new FilePersistenceProvider("./cronbake-state.json"),
    autoRestore: true,
  },
});

// Redis-based (provide your own client implementing get/set)
const redisProvider = new RedisPersistenceProvider({
  client: redisClient,
  key: "cronbake:state",
});
const bakerRedis = Baker.create({
  persistence: {
    enabled: true,
    strategy: "redis",
    provider: redisProvider,
    autoRestore: true,
  },
});

Baker Methods

Method	Description
`add(options: CronOptions<T>)`	Adds a new cron job to the baker.
`remove(name: string)`	Removes a cron job from the baker.
`bake(name: string)`	Starts a cron job.
`stop(name: string)`	Stops a cron job.
`pause(name: string)`	Pauses a cron job.
`resume(name: string)`	Resumes a paused cron job.
`destroy(name: string)`	Destroys a cron job.
`getStatus(name: string)`	Returns the status of a cron job.
`isRunning(name: string)`	Checks if a cron job is running.
`lastExecution(name: string)`	Returns the last execution time of a cron job.
`nextExecution(name: string)`	Returns the next execution time of a cron job.
`remaining(name: string)`	Returns the remaining time until the next execution of a cron job.
`time(name: string)`	Returns the remaining time until the next execution.
`getHistory(name: string)`	Returns the execution history of a cron job.
`getMetrics(name: string)`	Returns the metrics of a cron job.
`getJobNames()`	Returns all cron job names.
`getAllJobs()`	Returns all cron jobs with their status.
`bakeAll()`	Starts all cron jobs.
`stopAll()`	Stops all cron jobs.
`pauseAll()`	Pauses all cron jobs.
`resumeAll()`	Resumes all cron jobs.
`destroyAll()`	Destroys all cron jobs.
`saveState()`	Saves the current state of all jobs to persistence storage.
`restoreState()`	Restores jobs from persistence storage.
`resetAllMetrics()`	Resets metrics for all jobs.
`static create(options: IBakerOptions)`	Creates a new instance of `Baker`.

Advanced Usage

Cronbake also provides a Cron class that you can use directly to create and manage individual cron jobs. This can be useful if you need more granular control over cron job instances.

import { Cron } from "cronbake";

// Create a new Cron instance
const job = Cron.create({
  name: "custom-job",
  cron: "1-10/2 1,2,3 * * * *", // Runs every 2 seconds in the first 3 minutes of every hour
  callback: () => {
    console.log("Custom job executed!");
  },
  onTick: () => {
    console.log("Job ticked!");
  },
  onComplete: () => {
    console.log("Job completed!");
  },
  onError: (error) => {
    console.error("Job failed:", error.message);
  },
  priority: 10,
  immediate: false,
  overrunProtection: true,
});

// Start the cron job
job.start();
// Pause the cron job
job.pause();
// Resume the cron job
job.resume();
// Stop the cron job
job.stop();
// Get the job status
const status = job.getStatus();
// Get the next execution time
const nextExecution = job.nextExecution();
// Get metrics and history
const metrics = job.getMetrics();
const history = job.getHistory();
// Metrics include skippedExecutions when overrun protection skips overlaps

Cronbake also provides utility functions for parsing cron expressions, getting the next or previous execution times, and validating cron expressions.

import { Cron } from "cronbake";

// Parse a cron expression
const cronExpression = "0 0 0 * * *";
const cronTime = Cron.parse(cronExpression);
// Get the next execution time for a cron expression
const nextExecution = Cron.getNext(cronExpression);
// Get the previous execution time for a cron expression
const previousExecution = Cron.getPrevious(cronExpression);
// Check if a string is a valid cron expression
const isValid = Cron.isValid(cronExpression); // true

Cron Methods

Method	Description
`start()`	Starts the cron job.
`stop()`	Stops the cron job.
`pause()`	Pauses the cron job.
`resume()`	Resumes the cron job.
`getStatus()`	Returns the current status of the cron job.
`isRunning()`	Checks if the cron job is running.
`nextExecution()`	Returns the date of the next execution of the cron job.
`getHistory()`	Returns the execution history of the cron job.
`getMetrics()`	Returns the metrics of the cron job.
`resetMetrics()`	Resets the metrics and history of the cron job.
`static create(options: CronOptions<T>)`	Creates a new cron job with the specified options.
`static parse(cron: CronExpressionType<T>)`	Parses the specified cron expression and returns a `CronTime` object.
`static getNext(cron: CronExpressionType<T>)`	Gets the next execution time for the specified cron expression.
`static getPrevious(cron: CronExpressionType<T>)`	Gets the previous execution time for the specified cron expression.
`static isValid(cron: CronExpressionType<T>)`	Checks if the specified string is a valid cron expression.

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.

License

Cronbake is released under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.changeset		.changeset
.github/workflows		.github/workflows
examples		examples
lib		lib
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
bun.lockb		bun.lockb
index.ts		index.ts
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Cronbake - A Powerful and Flexible Cron Job Manager powered by Bun

Features

Expressive Cron Expressions

Advanced Scheduling

Cron Job Management

Job Status and Control

Real-time Status and Metrics

Execution History and Metrics

Job Persistence (opt-in)

Callbacks and Error Handling

Priority System

Type-safe

Async Support

Installation

Quick Start (stateless defaults)

Persistence & Advanced Controls

Examples

Immediate/Delayed First Run and Overrun Protection

Advanced Configuration

Job Configuration Options

Job Control and Monitoring

Persistence Operations

Using a Custom Logger

Persistence Providers (File and Redis)

Baker Methods

Advanced Usage

Cron Methods

Contributing

License

About

Uh oh!

Releases 8

Uh oh!

Contributors 4

Languages

License

chaqchase/cronbake

Folders and files

Latest commit

History

Repository files navigation

Cronbake - A Powerful and Flexible Cron Job Manager powered by Bun

Features

Expressive Cron Expressions

Advanced Scheduling

Cron Job Management

Job Status and Control

Real-time Status and Metrics

Execution History and Metrics

Job Persistence (opt-in)

Callbacks and Error Handling

Priority System

Type-safe

Async Support

Installation

Quick Start (stateless defaults)

Persistence & Advanced Controls

Examples

Immediate/Delayed First Run and Overrun Protection

Advanced Configuration

Job Configuration Options

Job Control and Monitoring

Persistence Operations

Using a Custom Logger

Persistence Providers (File and Redis)

Baker Methods

Advanced Usage

Cron Methods

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Uh oh!

Contributors 4

Languages