sx4im/chronos

Debugging non-deterministic race conditions and async timing bugs in distributed JavaScript applications is notoriously difficult. sx4im/chronos brings Deterministic Simulation Testing to Node.js and TypeScript, letting you catch, isolate, and replay complex async bugs bit for bit using a single integer seed.

Instead of running flaky tests against wall-clock time or live networks, Chronos controls execution order and timing using a virtual clock, a MinHeap event scheduler, and a seeded pseudo-random number generator powered by xoshiro256. Its ecosystem includes @sx4im/chronos-net for fault-injecting network chaos like latency spikes, dropped packets, and network partitions, alongside @sx4im/chronos-vitest to integrate directly into existing Vitest suites using helpers like simTest and expectInvariant. When an invariant fails during a simulation sweep, the framework automatically shrinks the failure trace into a minimal reproduction capsule so you can replay the exact bug locally on demand.

For engineers building stateful microservices, distributed consensus protocols, or complex async pipelines in TypeScript, Chronos turns unpredictable timing issues into reproducible unit tests.

Chronos is a strong and focused testing framework for TypeScript and Node.js projects. It helps developers find race conditions, timing bugs, and network failures by replacing clocks, random values, timers, and network behavior with controlled versions. When a test fails, the same seed can be used to replay that exact test path. This is a valuable idea for distributed systems, where rare failures are often hard to reproduce.

The repository is organized as a clean monorepo with separate packages for the core engine, network simulator, Vitest integration, command-line tools, and visual inspector. The README includes a useful quick start, working code examples, an architecture diagram, a package guide, and a clear security section. There are also larger examples for distributed counters and Raft. The MIT license, contribution guide, code of conduct, security policy, and public documentation site make the project welcoming to users and contributors.

The engineering setup also looks healthy. Chronos uses TypeScript, Vitest, ESLint, Prettier, and a locked pnpm version. Current GitHub Actions checks are passing. Recent work includes a detailed security review that improved path handling, output escaping, failure capsule validation, and protection against spreadsheet formula injection. This shows that the maintainer takes untrusted test files seriously.

The biggest opportunity is to define the limits of determinism more clearly. Claims such as “100% deterministic” and “bit-for-bit” are powerful, but users need to know the exact conditions under which they apply. The documentation should explain behavior across Node.js versions, operating systems, package versions, worker threads, native modules, file access, child processes, and real network calls. A compatibility table and a versioned failure capsule format would help users understand whether an old failure can still be replayed after upgrading Chronos.

It would also be helpful to publish measured performance results. Tests could compare Chronos with regular Vitest runs across different seed counts, node counts, and event volumes. Adding coverage reports, release notes, API stability rules, and automated package publishing checks would make adoption easier for larger teams.

Overall, Chronos solves a difficult testing problem with a clear design and excellent developer tools. The repository already feels more complete than many early testing frameworks. Stronger limits, compatibility rules, and performance evidence would make its impressive claims easier for developers to trust.