iii-cron

The iii-cron worker schedules a registered function to run on a recurring cron expression. It exposes no callable functions — its entire surface is one trigger type, cron, bound via iii.registerTrigger({ type: 'cron', function_id, config }). On every firing the engine builds an event payload, optionally evaluates a condition function, acquires a distributed lock through the configured adapter, and invokes the target function. Each firing reports scheduled_time vs. actual_time so drift and reentrancy are observable from inside the handler.

The schedule grammar is the seven-field cron dialect — second minute hour day-of-month month day-of-week [year] — where the year is optional and defaults to *. Both six- and seven-field forms work; the leading field is always seconds, so 0 */5 * * * * fires every 5 minutes at second 0, not every 5 seconds.

Two adapters govern once-only execution: kv (default) takes a process-local lock and is single-instance only — on a multi-instance fleet every engine fires the same job (tunables lock_ttl_ms, lock_index); redis takes a distributed lock and is required for once-only firing across a fleet (tunable redis_url).

When to Use

• A function should run periodically without standing up a separate scheduler process or a system crontab entry.
• You need once-only firing across a fleet — nightly cleanup, hourly reports, batch maintenance — paired with the redis adapter.
• A scheduled job should be conditionally skipped (holiday calendar, feature flag, weekend pause) via condition_function_id without threading the check through the handler.

Boundaries