@ap3x/cadence

A standalone durable scheduler: cron, interval, and one-shot jobs with exactly-once firing semantics and pluggable storage.

Part of AP3X — a TypeScript multi-agent framework.

Install

npm install @ap3x/cadence

What's inside

• Schedules — cron expressions, fixed intervals, and one-shot timers.
• Exactly-once slot advance — claiming a due occurrence and advancing its slot happen in one critical section, so a given occurrence is never fired twice by the running engine. A crash between the two releases the claim, and the occurrence fires again on restart — the design prefers re-firing over silently dropping a scheduled run.
• Durable across restarts — state reloads from the store; in-flight attempts abandoned by a crashed process are reclaimed and routed through the retry ladder.
• Overlap + misfire policies — choose what happens when an occurrence comes due while the previous attempt is still running (allow, queue, skip_if_running), and what to do with occurrences missed while the engine was down.
• Pluggable stores — in-memory and file-backed stores ship with the package, behind a store interface with a conformance suite.
• Injectable clock — no wall-clock reads in core, so schedules are testable deterministically.

Concurrency scope

The bundled stores hold their claim in process memory and rely on JavaScript's run-to-completion as the critical section. Run one engine process per store directory — multi-process exclusion is out of scope for the in-memory and file stores.

The Store interface is designed for it: a backend that can claim and advance in one transaction (a Postgres row lock, say) extends the same guarantee across processes. No such adapter ships here.

Depends on no other @ap3x package.

Documentation

See the AP3X repository for architecture notes, the full package map, and examples.

License

MIT