feat: add EXPIRED cache state

Author: Kikobeats

README.md

@@ -16,6 +16,16 @@ Instead of serving a real time™ – and costly – response, we can say it is
 
 That will save CPU cycles, saving them for things that really matters.
 
+## Caching states
+
+| Value    | Description                                                                                                       |
+|----------|-------------------------------------------------------------------------------------------------------------------|
+| `MISS`   | The resource was looked into the cache but did not find it, so a new copy is generated and placed into the cache. |
+| `HIT`    | The resources was found into the cache, being generated by a previous access.                                     |
+| `EXPIRED`| The resouce was found but it is expired, being necessary regerate it.                                             |
+| `BYPASS` | The cache is forced to be bypassed, regenerating the resource.                                                    |
+| `STALE`  | The resource is expired but it's served while a new cache copy is generated in background.                        |
+
 ## Install
 
 ```bash
@@ -298,8 +308,7 @@ x-cache-expired-at: 1h 59m 60s
 cf-cache-status: HIT
 ```
 
-Note how in this second request `x-cache-status` is still
-`MISS`.
+Note how in this second request `x-cache-status` is still a `MISS`.
 
 That's because CloudFlare way for caching the content includes caching the response headers.
 

src/index.js

@@ -79,14 +79,15 @@ const cacheableResponse = ({
     })
 
     setHeaders({
-      etag,
-      res,
       createdAt,
+      etag,
+      forceExpiration,
+      hasValue,
       isHit,
       isStale,
-      ttl,
+      res,
       staleTtl,
-      forceExpiration
+      ttl
     })
 
     if (!forceExpiration && !isModified) {

src/util.js

@@ -32,13 +32,22 @@ const createKey = bypassQueryParameter => ({ req }) => {
 
 const toSeconds = ms => Math.floor(ms / 1000)
 
-const getStatus = ({ isHit, isStale, forceExpiration }) =>
-  isHit ? (isStale ? 'STALE' : 'HIT') : forceExpiration ? 'BYPASS' : 'MISS'
+const getStatus = ({ hasValue, isHit, isStale, forceExpiration }) =>
+  isHit
+    ? isStale
+        ? 'STALE'
+        : 'HIT'
+    : forceExpiration
+      ? 'BYPASS'
+      : hasValue
+        ? 'EXPIRED'
+        : 'MISS'
 
 const setHeaders = ({
   createdAt,
   etag,
   forceExpiration,
+  hasValue,
   isHit,
   isStale,
   res,
@@ -60,7 +69,7 @@ const setHeaders = ({
   res.setHeader('Cache-Control', cacheControl)
   res.setHeader(
     'X-Cache-Status',
-    getStatus({ isHit, isStale, forceExpiration })
+    getStatus({ hasValue, isHit, isStale, forceExpiration })
   )
   res.setHeader('ETag', etag)
 }

test/status.js

@@ -41,7 +41,7 @@ test('MISS for undefined data value', async t => {
   t.is((await got(`${url}/kikobeats`)).headers['x-cache-status'], 'MISS')
 })
 
-test('MISS after cache expiration', async t => {
+test('EXPIRED after cache expiration', async t => {
   const url = await createServer(
     cacheableResponse({
       staleTtl: false,
@@ -62,7 +62,7 @@ test('MISS after cache expiration', async t => {
   const doRequest = () => got(`${url}/kikobeats`)
 
   t.is((await doRequest()).headers['x-cache-status'], 'MISS')
-  t.is((await doRequest()).headers['x-cache-status'], 'MISS')
+  t.is((await doRequest()).headers['x-cache-status'], 'EXPIRED')
 })
 
 test('BYPASS for forcing refresh', async t => {