unexpired

Simple API for keeping your expiring resources fresh!

usage

Set up an expiring resource by providing a fetch function.

  var unexpired = require('unexpired');
  
  var freshCertificate = unexpired(function fetch(cb){
    // fetch a fresh copy of whatever your resource you are after,
    // then pass the result and expiration to the callback
    cb(null, {
      certId: id,
      key: encryptionKey,
      expires: expiration //in milliseconds sense epoch
    });
  });

The generated function will lazily call your fetch function as necessary to provide fresh resources.

  freshCertificate(function(err, certificate){
     if (err) {
      throw new Error('something went wrong fetching my resource');
     }
     // do something with the resource - it is guaranteed fresh
     console.log('using cert:', certificate.certId );
  });

promises

Your fetch function may also allowed to return a promise instead of calling the supplied callback. unexpired will check for a then method on your return value, and use that. If you are using promises, you will likely want to use your promise library to "promisify" the generated function:

  var resource = Promise.promisify(unexpired(function() {
    return new Promise(resolve, reject) {
      // do some work to fulfill the promise
    }
  }));
  
  resource().then(/* ... */);

options

You can customize the behavior by passing an options object instead.

  unexpired({
    fetch: function(cb){/* your fetch function */},
    buffer: 200, // safety buffer in milliseconds,
    now: fn, // alternate method for determining current time
    expires: fn, // alternate method for extracting expiration from fetch result
    transform: fn,  // transform the fetch result before passing to callbacks
    copy: fn, // create a defensive copy for each callback,
    prefetch: '2 hours', // try to prefetch 2 hours early
    retry: '15 minutes' // retry prefetch every 15 minutes until expired
  });

Only fetch is required, everything else is optional.

• fetch: Function
  The fetch function. It must accept a node style callback (i.e. cb(err, result)). By default, the callback should be called with an object that has an expires property. The expires property should be an integer, representing the time the resource expires (in milliseconds since epoch).

• buffer: Number or String
  The safety buffer in milliseconds. Forcibly refresh resources a little earlier than necessary. This is useful for resources (like authentication tokens) that you want to use over the network. It mitigates problems arising from network latency and slightly off system clocks. Callbacks will never receive results that expire within buffer milliseconds. String values will be parsed using duration-parser. Defaults to 0.

• prefetch: Number or String
  Prefetch time in milliseconds. Proactively fetch a new resource even before it is expired. Any requests for the resource within buffer + prefetch ms of the expiration will trigger a fetch. Unlike buffer, this value does not prevent incoming requests from being fulfilled by an existing unexpired resource. Incoming requests will continue to be served by the unexpired resource until the newly fetched resource is available. This helps avoid latency on incoming requests by ensuring there is always an unexpired resource ready to go. String values will be parsed using duration-parser. Defaults to 0.

• retry: Number or String
  If a prefetch attempt fails, how long to wait before trying to prefetch again (in milliseconds). String values will be parsed using duration-parser. Defaults to 0.

• expires: Function or String
  Alternate method for extracting the expiration from the fetch result. It will be called with the fetch results, and must return a number representing the expiration (in milliseconds since epoch). By default, it just returns the expires property of the fetch result. Possible use would be parsing the notAfter result of an X509 certificate. If you provide a string, it will use that named property of the fetch result.

• transform: Function
  Transform the result before passing to callbacks.

• copy: Function
  Create a defensive copy of the result before passing to each callback.

• now: Function
  Alternate method of fetching the current time.