Cron

The @talosjs/cron component runs background tasks on top of Bun’s native Bun.cron. You extend the abstract Cron class, declare a schedule with a readable string like "every 1 hours", and implement a handler() that runs on that schedule. Behind the scenes the schedule is converted to a crontab expression, so there is no external scheduler to operate.

What it does

Schedules read like English. You write "every 5 minutes" or "in 30 seconds" and the component converts that to crontab syntax for you. Each job is a class with three abstract methods (getTime(), getTimeZone(), and handler()). getTimeZone() is part of the contract, but the current Cron base class does not pass a timezone into Bun.cron; schedules therefore run in the server’s local time. You drive a job with start(), stop(), and isActive(), and you register it with @decorator.cron() so the container can resolve it.

How it works

A cron job is a class that extends Cron and implements its three abstract methods. When you call start(), the schedule from getTime() is converted to a crontab expression and registered with Bun.cron, which invokes your handler() on every tick.

Method	Purpose
`getTime()`	Return the schedule as a `CronTimeType` string, e.g. `"every 1 hours"`.
`getTimeZone()`	Return an IANA timezone string or `null`. The current base class does not use it when starting `Bun.cron`.
`handler()`	The async work to run on each scheduled tick.
`start()`	Convert the schedule and register the job. No-op if already active. Throws `CronException` on failure.
`stop()`	Stop the job and release the underlying timer.
`isActive()`	Whether the job is currently scheduled.

The schedule string has the shape "<prefix> <number> <unit>":

Part	Values
Prefix	`every` (recurring) or `in` (delay converted into the next matching crontab time)
Number	Any positive integer
Unit	`seconds`, `minutes`, `hours`, `days`, `months`, `years`

So "every 5 minutes" runs repeatedly every five minutes. The in prefix is converted into a concrete crontab expression for the computed future date and time; because Bun.cron is recurring, it is not a true one-shot timer. An invalid format or a non-positive number throws CronException.

Decorator and usage

`@decorator.cron()`

Registers a cron class with the container. It accepts an optional scope (defaults to singleton). Decorate any class that extends Cron.

import type { TimeZoneType } from "@talosjs/country";
import { Cron, decorator, type CronTimeType } from "@talosjs/cron";

@decorator.cron()
export class CleanupCron extends Cron {
  public getTime(): CronTimeType {
    return "every 1 hours";
  }

  public getTimeZone(): TimeZoneType | null {
    return null; // server's local timezone
  }

  public async handler(): Promise<void> {
    await this.removeExpiredRecords();
  }

  private async removeExpiredRecords(): Promise<void> {
    // cleanup logic
  }
}

Resolve and control the job from the container:

import { container } from "@talosjs/container";

const cleanup = container.get(CleanupCron);

await cleanup.start();
cleanup.isActive(); // true

await cleanup.stop();
cleanup.isActive(); // false

getTimeZone() is still part of the interface, but the current base class does not apply it when starting the job:

import type { TimeZoneType } from "@talosjs/country";
import { Cron, decorator, type CronTimeType } from "@talosjs/cron";

@decorator.cron()
export class DailyReportCron extends Cron {
  public getTime(): CronTimeType {
    return "every 1 days";
  }

  public getTimeZone(): TimeZoneType | null {
    return "Europe/Paris";
  }

  public async handler(): Promise<void> {
    await this.generateDailyReport();
  }

  private async generateDailyReport(): Promise<void> {
    // report logic
  }
}

Use the in prefix only when you want the helper to compute the next matching calendar time from a delay:

public getTime(): CronTimeType {
  return "in 30 seconds";
}

Exceptions

The component throws CronException when a schedule is malformed or a job fails to start. It carries a machine-readable key, a human-readable message, and a data object.

Key	When
`INVALID_FORMAT`	The schedule string is not in `"<prefix> <number> <unit>"` form.
`INVALID_VALUE`	The number in the schedule is not a positive integer.
`START_FAILED`	The underlying scheduler rejected the converted crontab expression when starting.

import { CronException } from "@talosjs/cron";

try {
  await job.start();
} catch (error) {
  if (error instanceof CronException) {
    logger.error(`Cron error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

Running jobs reliably

Catch errors inside handler(). A throw there should not take down the scheduler, so wrap risky work and log what fails. Make handlers idempotent, since a run may overlap or repeat and the work has to stay safe to execute more than once. Match the interval to the work too: a long task on "every 1 minutes" can pile up if it can’t finish before the next tick. For time-sensitive jobs like reports and billing, remember that the current base class runs on the server’s local time even if getTimeZone() returns a value. Inject caches, databases, and loggers from the container rather than constructing them inside the handler. Use every for recurring work; in is only a scheduling convenience for computing a future crontab expression, not a true one-shot timer. And stop jobs you no longer need: stop() releases the timer, and isActive() tells you whether a job is still running.

CLI command

Scaffold a cron class and its test file with the generator. It writes the class under modules/<module>/src/crons/<Name>Cron.ts, registers it in the module’s cronJobs array, and installs @talosjs/cron if it is missing.

# Interactive: prompts for the name
talos cron:create

# Provide the name
talos cron:create --name=Cleanup

# Target a module and overwrite
talos cron:create --name=Cleanup --module=auth --override

Option	Description	Default
`--name`	Cron class name. The `Cron` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated class is a ready-to-fill stub with the schedule, timezone, and handler in place:

import type { TimeZoneType } from "@talosjs/country";
import type { CronTimeType } from "@talosjs/cron";
import { Cron, decorator } from "@talosjs/cron";

@decorator.cron()
export class CleanupCron extends Cron {
  public getTime(): CronTimeType {
    // Examples: "every 5 minutes", "every 1 hours", "every 30 seconds"
    return "every 1 hours";
  }

  public getTimeZone(): TimeZoneType | null {
    // Return null to use server timezone, or specify a timezone like "Europe/Paris"
    return null;
  }

  public async handler(): Promise<void> {
    // Implement your cron handler logic here
    // console.log("CleanupCron handler executed");
  }
}

See cron:create for the full command reference.

Use with Claude and Codex

The generator ships a matching cron:create skill. It runs the scaffold and then guides your AI agent through completing the job: setting the schedule in getTime(), choosing a timezone, and implementing handler() with real logic. Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a cron job that runs every night at midnight to clean up expired sessions.

talos agent:skills:create

Then ask Codex the same way; it maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a cron job that runs every night at midnight to clean up expired sessions.

For example, the prompt above maps to cron:create --name=CleanExpiredSessions, then sets the schedule and implements the handler() to remove expired sessions.

Getting Started

AI

Framework

Command Line

What it does

How it works

Decorator and usage

`@decorator.cron()`

Exceptions

Running jobs reliably

CLI command

Use with Claude and Codex

​What it does

​How it works

​Decorator and usage

​@decorator.cron()

​Exceptions

​Running jobs reliably

​CLI command

​Use with Claude and Codex

What it does

How it works

Decorator and usage

`@decorator.cron()`

Exceptions

Running jobs reliably

CLI command

Use with Claude and Codex