Renamed

README.md

@@ -12,7 +12,7 @@ const secondsFresh = cache.maxAge();
 const secondsOld = cache.age();
 
 // Current state
-const currentState = cache.isFresh();
+const outOfDate = cache.stale();
 ```
 
 Cacheability of response depends on how it was requested, so both request and response are required. Both are objects with `headers` property that is an object with lowercased header names as keys, e.g.
@@ -39,6 +39,12 @@ const options = {
 
 If `options.shared` is true (default), then response is evaluated from perspective of a shared cache (i.e. `private` is not cacheable and `s-maxage` is respected). If `options.shared` is false, then response is evaluated from perspective of a single-user cache (i.e. `private` is cacheable and `s-maxage` is ignored).
 
+### `stale()`
+
+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. client can explicitly allow stale responses. A fresh response still may not be used if other conditions—such as `Vary`—are not satisfied.
+
 ## Implemented
 
 * `Expires` with check for bad clocks

index.js

@@ -170,8 +170,8 @@ CachePolicy.prototype = {
         return 0;
     },
 
-    isFresh() {
-        return this.maxAge() > this.age();
+    stale() {
+        return this.maxAge() <= this.age();
     },
 };
 

test/requesttest.js

@@ -9,31 +9,31 @@ const cacheableResponse = {headers:{'cache-control': 'max-age=111'}};
 describe('Request properties', function() {
     it('No store kills cache', function() {
         const cache = new CachePolicy({method:'GET',headers:{'cache-control':'no-store'}}, publicCacheableResponse);
-        assert(!cache.isFresh());
+        assert(cache.stale());
         assert(!cache.storable());
     });
 
     it('POST not cacheable by default', function() {
         const cache = new CachePolicy({method:'POST',headers:{}}, {headers:{'cache-control': 'public'}});
-        assert(!cache.isFresh());
+        assert(cache.stale());
         assert(!cache.storable());
     });
 
     it('POST cacheable explicitly', function() {
         const cache = new CachePolicy({method:'POST',headers:{}}, publicCacheableResponse);
-        assert(cache.isFresh());
+        assert(!cache.stale());
         assert(cache.storable());
     });
 
     it('Public cacheable auth is OK', function() {
         const cache = new CachePolicy({method:'GET',headers:{'authorization': 'test'}}, publicCacheableResponse);
-        assert(cache.isFresh());
+        assert(!cache.stale());
         assert(cache.storable());
     });
 
     it('Auth prevents caching by default', function() {
         const cache = new CachePolicy({method:'GET',headers:{'authorization': 'test'}}, cacheableResponse);
-        assert(!cache.isFresh());
+        assert(cache.stale());
         assert(!cache.storable());
     });
 });

test/responsetest.js

@@ -8,12 +8,12 @@ const req = {method:'GET', headers:{}};
 describe('Response headers', function() {
     it('simple miss', function() {
         const cache = new CachePolicy(req, {headers:{}});
-        assert(!cache.isFresh());
+        assert(cache.stale());
     });
 
     it('simple hit', function() {
         const cache = new CachePolicy(req, {headers:{'cache-control': 'public, max-age=999999'}});
-        assert(cache.isFresh());
+        assert(!cache.stale());
         assert.equal(cache.maxAge(), 999999);
     });
 
@@ -22,7 +22,7 @@ describe('Response headers', function() {
             'date': new Date().toGMTString(),
             'expires': new Date(Date.now() + 2000).toGMTString(),
         }});
-        assert(cache.isFresh());
+        assert(!cache.stale());
         assert.equal(2, cache.maxAge());
     });
 
@@ -31,7 +31,7 @@ describe('Response headers', function() {
             'cache-control': 'public',
             'expires': new Date(Date.now()+3600*1000).toGMTString(),
         }});
-        assert(cache.isFresh());
+        assert(!cache.stale());
         assert(cache.maxAge() > 3595);
         assert(cache.maxAge() < 3605);
     });
@@ -41,7 +41,7 @@ describe('Response headers', function() {
             'date': new Date().toGMTString(),
             'last-modified': 'Mon, 07 Mar 2016 11:52:56 GMT',
         }});
-        assert(cache.isFresh());
+        assert(!cache.stale());
         assert(cache.maxAge() > 100);
     });
 
@@ -50,14 +50,14 @@ describe('Response headers', function() {
             'pragma': 'no-cache',
             'last-modified': 'Mon, 07 Mar 2016 11:52:56 GMT',
         }});
-        assert(!cache.isFresh());
+        assert(cache.stale());
     });
 
     it('no-store', function() {
         const cache = new CachePolicy(req, {headers:{
             'cache-control': 'no-store, public, max-age=1',
         }});
-        assert(!cache.isFresh());
+        assert(cache.stale());
         assert.equal(0, cache.maxAge());
     });
 
@@ -66,11 +66,11 @@ describe('Response headers', function() {
             'cache-control': 'private, max-age=1234',
         };
         const proxyCache = new CachePolicy(req, {headers:privateHeader});
-        assert(!proxyCache.isFresh());
+        assert(proxyCache.stale());
         assert.equal(0, proxyCache.maxAge());
 
         const uaCache = new CachePolicy(req, {headers:privateHeader}, {shared:false});
-        assert(uaCache.isFresh());
+        assert(!uaCache.stale());
         assert.equal(1234, uaCache.maxAge());
     });
 
@@ -80,11 +80,11 @@ describe('Response headers', function() {
             'cache-control': 'max-age=99',
         };
         const proxyCache = new CachePolicy(req, {headers:cookieHeader}, {shared:true});
-        assert(!proxyCache.isFresh());
+        assert(proxyCache.stale());
         assert.equal(0, proxyCache.maxAge());
 
         const uaCache = new CachePolicy(req, {headers:cookieHeader}, {shared:false});
-        assert(uaCache.isFresh());
+        assert(!uaCache.stale());
         assert.equal(99, uaCache.maxAge());
     });
 
@@ -94,7 +94,7 @@ describe('Response headers', function() {
             'cache-control': 'max-age=5, public',
         };
         const proxyCache = new CachePolicy(req, {headers:cookieHeader}, {shared:true});
-        assert(proxyCache.isFresh());
+        assert(!proxyCache.stale());
         assert.equal(5, proxyCache.maxAge());
     });
 
@@ -102,7 +102,7 @@ describe('Response headers', function() {
         const cache = new CachePolicy(req, {headers:{
             'cache-control': 'public, max-age=0',
         }});
-        assert(!cache.isFresh());
+        assert(cache.stale());
         assert.equal(0, cache.maxAge());
     });
 
@@ -112,7 +112,7 @@ describe('Response headers', function() {
             headers:{
                 'cache-control': 'public, max-age=1000',
             }});
-        assert(!cache.isFresh());
+        assert(cache.stale());
         assert.equal(0, cache.maxAge());
     });
 
@@ -122,7 +122,7 @@ describe('Response headers', function() {
             headers:{
                 'last-modified': 'Mon, 07 Mar 2016 11:52:56 GMT',
             }});
-        assert(cache.isFresh());
+        assert(!cache.stale());
     });
 
     it('uncacheable 303', function() {
@@ -131,7 +131,7 @@ describe('Response headers', function() {
             headers:{
                 'last-modified': 'Mon, 07 Mar 2016 11:52:56 GMT',
             }});
-        assert(!cache.isFresh());
+        assert(cache.stale());
         assert.equal(0, cache.maxAge());
     });
 
@@ -141,7 +141,7 @@ describe('Response headers', function() {
             headers:{
                 'cache-control': 'max-age=1000',
             }});
-        assert(cache.isFresh());
+        assert(!cache.stale());
     });
 
     it('uncacheable 412', function() {
@@ -150,7 +150,7 @@ describe('Response headers', function() {
             headers:{
                 'cache-control': 'public, max-age=1000',
             }});
-        assert(!cache.isFresh());
+        assert(cache.stale());
         assert.equal(0, cache.maxAge());
     });
 
@@ -159,7 +159,7 @@ describe('Response headers', function() {
             'cache-control': 'public, max-age=9999',
             'expires': 'Sat, 07 May 2016 15:35:18 GMT',
         }});
-        assert(cache.isFresh());
+        assert(!cache.stale());
         assert.equal(9999, cache.maxAge());
     });
 
@@ -169,11 +169,11 @@ describe('Response headers', function() {
             'expires': 'Sat, 07 May 2016 15:35:18 GMT',
         };
         const proxyCache = new CachePolicy(req, {headers:sMaxAgeHeaders});
-        assert(proxyCache.isFresh());
+        assert(!proxyCache.stale());
         assert.equal(9999, proxyCache.maxAge());
 
         const uaCache = new CachePolicy(req, {headers:sMaxAgeHeaders}, {shared:false});
-        assert(!uaCache.isFresh());
+        assert(uaCache.stale());
         assert.equal(0, uaCache.maxAge());
     });
 
@@ -182,7 +182,7 @@ describe('Response headers', function() {
             'cache-control': 'public, max-age=333',
             'expires': new Date(Date.now()+3600*1000).toGMTString(),
         }});
-        assert(cache.isFresh());
+        assert(!cache.stale());
         assert.equal(333, cache.maxAge());
     });
 });