timers

timers is a minimal Node.js library for running a callback on a repeating interval described in plain, human-readable duration strings like '2s', '2.5m', or '2 hours'. It wraps the native setInterval/clearInterval behind an every(...).do(callback) API and returns a handle you can stop at any time.

The entire implementation is a single small file with no runtime dependencies, making it a lightweight alternative to pulling in a full cron-parsing library when all that’s needed is readable, repeated scheduling inside a running Node process.

What You Get

• An every(str) function that parses strings like '10ms', '2s', '2.5m', '2 hours', or '2days' into a millisecond interval
• A chainable .do(callback) method that starts a setInterval running the callback on that cadence
• A .stop() method on the returned instance to clear the interval from inside or outside the callback
• A call counter (count) on the returned instance tracking how many times the callback has fired

Common Use Cases

• Running a lightweight polling or heartbeat task on a human-readable interval without formatting milliseconds by hand
• Scheduling periodic cleanup or cache-refresh jobs inside a long-running Node process
• Stopping a repeating task safely in response to an error or an uncaught exception handler
• Prototyping simple repeated jobs where a full cron library would be overkill

Under The Hood

Architecture — The package is a single index.js file exporting one factory function, every(str), which constructs an Every instance that parses the duration string with a regex into a numeric time value and unit; calling .do(callback) on that instance starts a native setInterval wrapping the callback to increment a call counter, and .stop() clears that interval. Tech Stack — Plain Node.js with zero runtime dependencies, relying only on the built-in setInterval/clearInterval timers; its devDependencies (mocha, should, sinon, blanket, coveralls) are limited to its 2013-era test and coverage tooling. Code Quality — The implementation is under 60 lines and is covered by a small Mocha/should/sinon test suite (test.js) exercising string parsing, formatting variants, and start/stop behavior, but the project has had no commits since 2016 and uses very old dependency pins. API Design — The every('2s').do(fn) chain is minimal and readable with almost no boilerplate, though the duration-string grammar (units like s, m, h, d and their long forms) is not documented beyond the README’s short format table.