@jakguru/vueprint / @jakguru/vueprint/libs/milicron / MiliCron

Class: MiliCron

@jakguru/vueprint/libs/milicron.MiliCron

The cron service is a simple Cron Daemon designed to be run in-browser which supports a resolution of up to 10ms.

Remarks

Accessing the Cron Service

The Cron Service is both injectable and accessible from the global Vue instance:

<script lang="ts">
import { defineComponent, inject } from 'vue'
import type { CronService } from '@jakguru/vueprint'
export default defineComponent({
    setup() {
        const cron = inject<CronService>('cron')
        return {}
    }
    mounted() {
        const cron: CronService = this.config.globalProperties.$cron
    }
})
</script>

Using the Cron Service

Adding a cron job

You can use the CronService.$on and CronService.$once methods to add a callback which will be called when the appropriate cron expression is matched. For example:

cron.$on('* * * * *', () => {
  // this runs once per minute
})

cron.$once("1704067200", () => {
  // This is set to run at midnight on January 1st, 2024
  console.log('Happy New Year!');
});

cron.$once(DateTime.now().toUTC().plus({ seconds: 10 }).toUnixInteger().toString(), () => {
  // This is set to run 10 seconds from now
  console.log("10 seconds later");
});

Supported cron expressions

The cron service accepts an enhanced crontab format:

Crontab format

  *    *    *    *    *    *    *
  ┬    ┬    ┬    ┬    ┬    ┬    ┬
  │    │    │    │    │    │    |
  │    │    │    │    │    │    └ day of week (0 - 7, 1L - 7L) (0 or 7 is Sun)
  │    │    │    │    │    └───── month (1 - 12)
  │    │    │    │    └────────── day of month (1 - 31, L)
  │    │    │    └─────────────── hour (0 - 23)
  │    │    └──────────────────── minute (0 - 59)
  |    └───────────────────────── second (0 - 59, optional)
  └────────────────────────────── millisecond (0 - 999, optional)*

TIP

While the millisecond field accepts values of 0-999, the resolution of the cron daemon is limited to 10ms, meaning that the job may trigger up to 10ms before or 10ms after the expressions's defined time.

Additionally, the library also accepts mixed use of ranges and range increments (except for W).

Examples

• * * * * * * * - Every 10ms
• */2 * * * * * * - Every 10ms (due to the 10ms resolution)
• */100 * * * * * - Every 100ms
• 0 * * * * * * - Every second
• 0 0 * * * * * - Every minute

For more information on the crontab format, see crontab.guru or cronjob.xyz. Note that these don't accept the exact same syntax as this library, as they do not accept the millisecond or seconds fields.

Crontab aliases

• @yearly - Once a year, at midnight on the morning of January 1st
• @monthly - Once a month, at midnight on the morning of the first day of the month
• @weekly - Once a week, at midnight on Sunday morning
• @daily - Once a day, at midnight
• @hourly - Once an hour, at the beginning of the hour

Unix Timestamp (seconds)

A unix timestamp in seconds can be used to specify a single time to run the job. Important Note: It is highly recommended to use the $once method with unix timestamps instead of $on in order to clear the callback after the job has run.

Constructors

constructor

• new MiliCron(autostart?): MiliCron

Creates a new instance of the MiliCron class.

Parameters

Name	Type	Description
autostart?	boolean	Whether to automatically start the cron daemon upon instantiation.

Returns

MiliCron

• A new instance of the MiliCron class.

Defined in

src/libs/milicron.ts:173

Accessors

running

• get running(): boolean

Returns a boolean indicating whether the cron daemon is currently running.

Returns

boolean

• A boolean indicating whether the cron daemon is currently running.

Defined in

src/libs/milicron.ts:220

Methods

$clear

▸ $clear(event?): void

Removes all listeners for the specified event or all events if no event is specified.

Parameters

Name	Type	Description
event?	string	The name of the event to remove all listeners from.

Returns

void

See

EventEmitter.removeAllListeners

Defined in

src/libs/milicron.ts:265

---

$off

▸ $off(event, cb): void

Removes a previously registered callback function for the specified event.

Parameters

Name	Type	Description
event	string	The name of the event to remove the callback function from.
cb	EventCallback	The callback function to remove.

Returns

void

See

EventEmitter.off

Defined in

src/libs/milicron.ts:254

---

$on

▸ $on(event, cb): void

Registers a callback function to be executed every time the specified event is emitted.

Parameters

Name	Type	Description
event	string	The name of the event to listen for.
cb	EventCallback	The callback function to execute when the event is emitted.

Returns

void

See

EventEmitter.on

Defined in

src/libs/milicron.ts:230

---

$once

▸ $once(event, cb): void

Registers a callback function to be executed only once when the specified event is emitted.

Parameters

Name	Type	Description
event	string	The name of the event to listen for.
cb	EventCallback	The callback function to execute when the event is emitted.

Returns

void

See

EventEmitter.once

Defined in

src/libs/milicron.ts:242

---

crontabMatchesDateTime

▸ crontabMatchesDateTime(crontab, now): boolean

Determines whether the given crontab expression matches the given date and time.

Parameters

Name	Type	Description
crontab	string	The crontab expression to check.
now	DateTime	The date and time to check against the crontab expression.

Returns

boolean

• A boolean indicating whether the crontab expression matches the given date and time.

Defined in

src/libs/milicron.ts:279

---

getParsedCronExpression

▸ getParsedCronExpression(cronExpression, now?): any

Parses the given cron expression and returns either a DateTime object representing the next time the cron expression will match, or a CronTabObject containing the parsed cron expression.

Parameters

Name	Type	Description
cronExpression	string	The cron expression to parse.
now?	any	The current date and time to use as a reference when calculating the next match time. If not provided, the current date and time will be used.

Returns

any

• A DateTime object representing the next time the cron expression will match, or a CronTabObject containing the parsed cron expression.

Throws

• Throws an error if the cron expression is so invalid that it cannot be recognized, or if the now parameter is not a valid DateTime object.

Defined in

src/libs/milicron.ts:290

---

restart

▸ restart(): void

Stops the cron daemon if it is running and then starts it again.

Returns

void

Function

Defined in

src/libs/milicron.ts:210

---

start

▸ start(): void

Starts the cron daemon if it is not already running.

Returns

void

Function

Defined in

src/libs/milicron.ts:186

---

stop

▸ stop(): void

Stops the cron daemon if it is running.

Returns

void

Function

Defined in

src/libs/milicron.ts:198

---

crontabMatchesDateTime

▸ crontabMatchesDateTime(crontab, now): boolean

Check if the crontab expression matches the current time

Parameters

Name	Type	Description
crontab	string	A crontab expression, crontab alias or unix timestamp
now	DateTime	A DateTime object representing the current time

Returns

boolean

If the crontab expression matches the current time

Defined in

src/libs/milicron.ts:556

---

getParsedCronExpression

▸ getParsedCronExpression(cronExpression, now?): any

Parses the given cron expression and returns either a DateTime object representing the next time the cron expression will match, or a CronTabObject containing the parsed cron expression.

Parameters

Name	Type	Description
cronExpression	string	The cron expression to parse.
now?	any	The current date and time to use as a reference when calculating the next match time. If not provided, the current date and time will be used.

Returns

any

• A DateTime object representing the next time the cron expression will match, or a CronTabObject containing the parsed cron expression.

Throws

• Throws an error if the cron expression is so invalid that it cannot be recognized, or if the now parameter is not a valid DateTime object.

Defined in

src/libs/milicron.ts:589