TTL

README.md

@@ -68,7 +68,11 @@ Returns `true` if the response can be stored in a cache. If it's `false` then yo
 
 Returns `true` if the response is stale (i.e. not fresh).
 
-It generally means the response can't be used any more without revalidation with the server. However, there are exceptions, e.g. a client can explicitly allow stale responses. A fresh response still may not be used if other conditions—such as `Vary`—are not satisfied.
+It generally means the response can't be used any more without revalidation with the server. However, there are exceptions, e.g. a client can explicitly allow stale responses.
+
+### `timeToLive()`
+
+Returns number of *milliseconds* until the response becomes stale. After that time (when `timeToLive() <= 0`) the response won't be usable without revalidation.
 
 # Yo, FRESH
 

index.js

@@ -212,6 +212,10 @@ CachePolicy.prototype = {
         return 0;
     },
 
+    timeToLive() {
+        return Math.max(0, this.maxAge() - this.age())*1000;
+    },
+
     stale() {
         return this.maxAge() <= this.age();
     },

test/responsetest.js

@@ -61,11 +61,14 @@ describe('Response headers', function() {
         }});
         assert(cache.storable());
 
+        assert.equal(50*1000, cache.timeToLive());
         assert(!cache.stale());
         now += 48*1000;
+        assert.equal(2*1000, cache.timeToLive());
         assert(!cache.stale());
         now += 5*1000;
         assert(cache.stale());
+        assert.equal(0, cache.timeToLive());
     });
 
     it('Age can make stale', function() {