node package manager

zeit

Injectable clock and promise scheduler, plus stub versions for easy testing, using native JS or Moment.js Date APIs

zeit

A node.js clock and scheduler, intended to take place of the global V8 object for manipulation of time and task scheduling which would be handled with calls to set/clearTimeout and set/clearInterval. Zeit ships with a set of controllable Stub clocks which can be used for the manipulation of time and scheduling in tests.

Writing testable code which involves the concept of time can be hard work, since you need to interact with the global "system" object in order to:

  1. Create Date object instances.
  2. Schedule callbacks to be executed at some point in the future.

In order to ensure that this behaviour is acceptably deterministic (and hence testable), we need to be able to control both of these events. The Zeit library provides objects to abstract away the global-ness of these operations, which can be used in node.js application code to provide a more managed method.

For test code you can use the bundled Stub implementations to effectively control the time in your tests, which removes the need for non-deterministic methods for asserting order and expected bevahiour, many of which rely on timeouts.

Zeit currently supports both the native JavaScript Date API and the (IMHO) superior Moment.js API.

  1. Schedule a single execution of a callback for 10 seconds in the future.
new zeit.Scheduler(new zeit.DateClock())
    .execute(function () {
        return 'some happy value';
    })
    .after(10000)
    .start();
  1. Schedule a single execution of a callback at 10 seconds in the future.
new zeit.Scheduler(new zeit.DateClock())
    .execute(function () {
        return 'some happy value';
    })
    .at(new zeit.DateClock().timeIn(10000))
    .start();
  1. Schedule a Q promise to execute 5 times at 30 second intervals, starting immediately.
new zeit.Scheduler(new zeit.MomentClock())
    .execute(function () {
        return q.resolve('some happy path resolving promise');
    })
    .exactly(5)
    .atFixedIntervalOf(moment.duration(30000))
    .start();
  1. Schedule repeatedly to trigger a callback at 1 minute breaks (wait for completion) while executed less than 1000 times and no error is thrown by the callback. Starts immediately.
new zeit.Scheduler(new zeit.DateClock())
    .execute(function () {
        return 'some happy value';
    })
    .andRepeatAfter(60000)
    .whilst(function(scheduleItemDetails) {
        return scheduleItemDetails.invocationCount < 1000;
    })
    .until(function(errresult) {
        return err;
    })
    .start();

Via npm, simply run: npm install zeit

Zeit requires that the same supported Date API is used consistently throughout calling code - use the wrong type and you'll get an explicit error:

  • Native Date implementation - Dates are represented as native Date objects, and durations are passed/returned as an integer number of milliseconds.
  • Moment.js implementation - Dates are represented as Moment objects and durations are passed/returned as Duration objects.

Abstracts the creation of date objects (using now), and wraps the native set/clearTimeout & set/clearInterval methods. Also provides some utility methods below, which are required by the Scheduler implementation:

In the format relative to the implementation (see above).

Returns the current date incremented by the passed duration.

In the format relative to the implementation (see above).

In the format relative to the implementation (see above).

If you want to provide your own implementation of clock (using another Date library), you'll just need to implement these methods and then mixin an instance of TimeoutsAndIntervals.

Extends the Real Clock API and provides a means to control the current time by setting it directly, or implicitly/explicitly ticking by a set duration. API as above, with the following methods:

If no values passed, the following defaults are used:

  • currentDate: Start of universal time (01-01-1970)
  • tickSize: 1 second
  • implicitTickFlag: false

Sets the current date if passed, and then returns the current date in the relative format. If implicit ticking is activated, the time will be incremented automatically by the set ticksize.

Return a Hash of currently scheduled timeout durations by their timeout id.

Return a Hash of currently scheduled interval durations by their timeout id.

Triggers all of the currently stored timeouts and intervals. After completion, reschedules intervals at the specified duration and discards timeouts.

Same as now(), but with no ticking.

If passed, sets the current ticksize.

Increments the current date by the duration in milliseconds, or the current ticksize if not passed. Then returns the new current date.

If passed, sets the current implicit tick flag.

Wraps the native scheduling of repeating and non-repeating callbacks or Promises/A compliant promises, but also provides the API to provide pre and post predicates to prevent execution or rescheduling or to control the number of executions. Configuration of the schedules follows the Builder pattern. The scheduler doesn't make a distinction between repeating and one-off events, rather the usage of the API determines this behaviour.

Schedulers are Event Emitters which emit the following lifecycle events for each schedule, with the latest schedule details as the message:

  • start
  • finish
  • error Note that callbacks/promises which throw exceptions (or rejected promises) emit Start & Error (no Finish event), and that throwing an exception does not cancel repeat scheduling (to stop rescheduling on an error, use the until() predicate when configuring the schedule).

Initiates the Builder pattern for configuring the schedule item. The passed function can be either a standard callback or return a Promises/A compliant promise object. Some of the examples below and the internal Zeit implementation use the Q library.

Returns details of the schedule, including the configuration and stats such as the invocation count and last run time.

Cancels the schedule and returns the latest details for that schedule, if any.

Cancels all schedules and returns a Hash of the schedules cancelled.

Provides the methods to configure the schedule. Calling start() actually schedules the execution. Follows the Builder pattern, so most methods return this.

Sets the name of the schedule.

Sets the initial delay before the first execution (like setTimeout).

Sets the time of the first execution (like setTimeout).

Sets the repeat at a fixed rate, regardless of how long the execution takes.

Sets the repeat at a fixed interval after execution has completed (like a tail call to setTimeout).

Sets the maximum number of executions, which may be adjusted by pre and post predicates.

Syntactic-sugar for exactly(1).

Sets a pre-execution predicate, which will cancel all rescheduling once it returns false.

Sets a post-execution predicate, which will cancel all rescheduling once it returns true. The last execution error and result are passed to this predicate, so asserting on these values is possible.