Test-friendly timer function replacements.
All problems in computer science can be solved by another level of indirection
TIMER-SHIM is a simple wrapper around standard timer functions adding the ability to mock / stub / test timing functions with ease.
If you have trouble getting mocha and sinon fake timers to behave, or you have trouble
testing code that depends on
setInterval you will find this simple
comes in quite handy.
Additionally, TIMER-SHIM also provides a few niceties over standard timer functions, including:
- Call with timeout number before the function (or vice versa - doesn't matter.)
- Shorter and simpler aliases without any magic or prototype infection.
- Protect against NaN and non-function values to save you debugging time.
And best of all:
wind()so you can test your timing functionality directly in a sane way.
At its core, the shim simply delegates calls to
setInterval internally but
by calling those function via TIMER-SHIM you can more easily test your time-dependent
There is a little caveat though, as I try not to pollute your global namespace in that you
must update all your
setInterval to use TIMER-SHIM's provided functions
instead to be able to use the time simulation functions.
Internally a node-linkedlist is used to track scheduled tasks with very basic adaptive cleanup. From a set of benchmarks I have ran, using TIMER-SHIM vs setTimeout adds no more than 100ms overhead for 100,000 tasks on a decent MBA. This overhead will be completly togglable in the future so you can have shims for tests and zero overhead for production.
$ npm install timer-shim --save
var timer = require'timer-shim'count = 0handle = null;timertimeout50 console.log'hello!'; ;handle = timerinterval100console.logcount++;if count === 10 timerclearhandle;;
example/test.js for an example on how to write code / test the
Internal class for handling timers. Instances exports the same API as the module itself. You can create multiple instances of this class if you need to
wind() only a certain set of functions while leaving other set of functions still
Clears the timeout handle given. Only works with TIMER-SHIM's provided handles. Does not works with handles returned from native
Clears all registered timeout handles. Effectively cancels all scheduled timeout and intervals. Useful for reseting the timer in tests.
Schedules a function to run after the specified timeout. Returns a TIMER-SHIM handle.
Schedules a function to run repeatedly every set interval. Returns a TIMER-SHIM handle.
Pauses all timing functions that has not yet run and all functions that may be scheduled in the future.
Resumes all scheduled function as though the time hasn't flickered.
timer.wind( time )
Only works when paused. Winds the internal clock by the specified
time (in ms) running
anything that is scheduled to be run in that amount of time.
resume()-ing after this
point will execute any scheduled functions as though
time has passed (i.e. shorter
timeout, shorter first invocation of interval function)
unref() if inside node.js environment. Effectively prevents all timers set so
far to keep the process alive if they are the only thing waiting to run inside the event
loop. Useful for cleaning up after timer tests.
ref() if inside node.js environment. Reverses the effect of
timer.interval can be called in either of the following ways:
timertimeout100 ; // both workstimertimeout 100;timerinterval100 ; // also workstimerinterval 100;
All timers are
ref()-ed by default. See node.js timers doc for more information
unref(). For convenience
timer-shim provides a top-level
unref() on all timers.
$ make lib/timer-shim.js
- Ability to infect global setTimeout/setInterval and route it to call the shim functions instead.
- Ability to un-shim the the shims and send calls directly to setTimeout/setInterval virtually removing any perf and mem impact (i.e. in production.)
- Performance optimizations.
- nextTick support?
Just open a GitHub issue or ping me @chakrit on Twitter.