API reference

Cron(expression, jobFunction)

Creates and immediately starts a cron job.

import { Cron } from '@robojs/cron'

const job = Cron('*/10 * * * * *', () => {
	console.log('Running...')
})

import { Cron } from '@robojs/cron'

const job = Cron('*/10 * * * * *', () => {
	console.log('Running...')
})

Parameters:

Returns: A CronJob instance.

When jobFunction is a string, the plugin resolves it as a file path and dynamically imports the module on each execution. The module must export a default function that receives the job ID as its argument.

// Function-based (not persistable)
Cron('*/5 * * * * *', () => console.log('tick'))

// File-based (persistable)
Cron('*/5 * * * * *', 'cron/task.js')

// Function-based (not persistable)
Cron('*/5 * * * * *', () => console.log('tick'))

// File-based (persistable)
Cron('*/5 * * * * *', 'cron/task.js')

An invalid cron expression throws an error at creation time.

Cron.get(id)

Retrieves a job instance by ID from the runtime state.

const job = Cron.get('my-job')

const job = Cron.get('my-job')

Parameters:

Returns: CronJob | null

This is a synchronous call. It reads from in-memory state, not from Flashcore. After a restart, jobs are available only after the plugin's startup restoration completes.

Cron.remove(id)

Removes a job from Flashcore persistence and in-memory state.

await Cron.remove('my-job')

await Cron.remove('my-job')

Parameters:

Returns: Promise<void>

This does not stop a running job. Call job.stop() first for a complete cleanup.

const job = Cron.get('my-job')
job?.stop()
await Cron.remove('my-job')

const job = Cron.get('my-job')
job?.stop()
await Cron.remove('my-job')

CronJob instance

The object returned by Cron() and Cron.get(). The CronJob class is not exported directly — you interact with instances through the factory function.

save(id?)

Persists a file-based job to Flashcore so it survives restarts.

const job = Cron('0 0 * * *', 'cron/daily.js')
const jobId = await job.save('daily-task')

const job = Cron('0 0 * * *', 'cron/daily.js')
const jobId = await job.save('daily-task')

Parameters:

Returns: Promise<string> — The job ID.

Function-based jobs are stored in runtime state only. They will not be written to Flashcore and will not survive restarts.

pause()

Temporarily halts the job. The job can be resumed later.

job.pause()

job.pause()

Returns: void

resume()

Resumes a paused job.

job.resume()

job.resume()

Returns: void

stop()

Permanently stops the job. A stopped job cannot be resumed — create a new one instead.

job.stop()

job.stop()

Returns: void

This does not remove persistence. If the job was saved, it will be restored on the next restart. Use Cron.remove(id) to also clear persistence.

nextRun()

Returns the next scheduled execution time.

const next = job.nextRun()
console.log('Next run:', next)

const next = job.nextRun()
console.log('Next run:', next)

Returns: Date | null — The next run time, or null if the job is stopped.

Patterns

A merged object of constant presets, day constants, and builder functions for cron expressions. See the full Patterns reference.

import { Cron, Patterns } from '@robojs/cron'

// Constant preset
Cron(Patterns.EVERY_HOUR, () => { /* ... */ })

// Builder function
Cron(Patterns.everyWeekdayAt('09:00'), () => { /* ... */ })

// Day constant with builder
Cron(Patterns.everyWeekOn(Patterns.FRIDAY, '17:00'), () => { /* ... */ })

import { Cron, Patterns } from '@robojs/cron'

// Constant preset
Cron(Patterns.EVERY_HOUR, () => { /* ... */ })

// Builder function
Cron(Patterns.everyWeekdayAt('09:00'), () => { /* ... */ })

// Day constant with builder
Cron(Patterns.everyWeekOn(Patterns.FRIDAY, '17:00'), () => { /* ... */ })

Constant presets

58 pre-built cron expression strings covering seconds, minutes, hours, daily times, weekly/monthly/yearly schedules, and business hours. See Patterns for the complete table.

Day constants

Builder functions

Aliases

Next Steps