From 5ae0a1f2952001f97a0903c5537d1946e8a0a056 Mon Sep 17 00:00:00 2001
From: Kiko Beats <josefrancisco.verdu@gmail.com>
Date: Thu, 19 Aug 2021 14:19:57 +0200
Subject: [PATCH] feat: rename getKey into key

in order to be aligned with `@keyvhq/memomize` API.
---
 README.md                        | 40 ++++++++++++++++++++++++++------
 src/index.js                     |  2 +-
 src/util.js                      |  4 ++--
 test/util/{get-key.js => key.js} | 12 +++++-----
 4 files changed, 42 insertions(+), 16 deletions(-)
 rename test/util/{get-key.js => key.js} (84%)

diff --git a/README.md b/README.md
index 3a2db2e..9aacf8e 100644
--- a/README.md
+++ b/README.md
@@ -112,6 +112,32 @@ curl https://myserver.dev/user?force=true # BYPASS (skip cache copy)
 
 In that case, the `x-cache-status` will reflect a `'BYPASS'` value.
 
+Additionally, you can configure a stale ttl:
+
+```js
+const cacheableResponse = require('cacheable-response')
+
+const ssrCache = cacheableResponse({
+  get: ({ req, res }) => ({
+    data: doSomething(req),
+    ttl: 86400000, // 24 hours
+    staleTtl: 3600000 // 1h
+  }),
+  send: ({ data, res, req }) => res.send(data)
+})
+```
+
+The stale ttl maximizes your cache HITs, allowing you to serve a no fresh cache copy _while_ doing revalidation on the background. 
+
+```bash
+curl https://myserver.dev/user # MISS (first access)
+curl https://myserver.dev/user # HIT (served from cache)
+curl https://myserver.dev/user # STALE (23 hours later, background revalidation)
+curl https://myserver.dev/user?force=true # HIT (fresh cache copy for the next 24 hours)
+```
+
+The library provides enough good sensible defaults for most common scenarios and you can tune these values based on your use case.
+
 ## API
 
 ### cacheableResponse([options])
@@ -165,13 +191,6 @@ async function get ({ req, res }) {
 }
 ```
 
-##### getKey
-
-Type: `function`<br/>
-Default: `({ req }) => normalizeUrl(req.url)`
-
-It determinates how the cache key should be computed, receiving `req, res` as input.
-
 The method will received `({ req, res })` and it should be returns:
 
 - **data** `object`|`string`: The content to be saved on the cache.
@@ -182,6 +201,13 @@ Any other property can be specified and will passed to `.send`.
 
 In case you want to bypass the cache, preventing caching a value (e.g., when an error occurred), you should return `undefined` or `null`.
 
+##### key
+
+Type: `function`<br/>
+Default: `({ req }) => req.url)`
+
+It determinates how the cache key should be computed, receiving `req, res` as input.
+
 ##### send
 
 _Required_<br/>
diff --git a/src/index.js b/src/index.js
index 6a4543c..dd9adaa 100644
--- a/src/index.js
+++ b/src/index.js
@@ -14,7 +14,7 @@ const cacheableResponse = ({
   cache = new Keyv({ namespace: 'ssr' }),
   compress: enableCompression = false,
   get,
-  getKey = require('./util').getKey,
+  key: getKey = require('./util').key,
   send,
   staleTtl: rawStaleTtl = 3600000,
   ttl: rawTtl = 86400000,
diff --git a/src/util.js b/src/util.js
index 8f98875..005383d 100644
--- a/src/util.js
+++ b/src/util.js
@@ -12,7 +12,7 @@ const hasQueryParameter = (req, key) => {
   return Boolean(req.query ? req.query[key] : parse(req.url.split('?')[1])[key])
 }
 
-const getKey = ({ req }, { bypassQueryParameter }) => {
+const key = ({ req }, { bypassQueryParameter }) => {
   const urlObj = new URL(req.url, 'http://localhost:8080')
   const OMIT_KEYS = [bypassQueryParameter, /^utm_\w+/i]
   const omitKeys = Array.from(urlObj.searchParams.keys()).reduce((acc, key) => {
@@ -61,7 +61,7 @@ const setHeaders = ({
 }
 
 module.exports = {
-  getKey,
+  key,
   hasQueryParameter,
   isFunction,
   setHeaders,
diff --git a/test/util/get-key.js b/test/util/key.js
similarity index 84%
rename from test/util/get-key.js
rename to test/util/key.js
index c5adff7..bee1bdf 100644
--- a/test/util/get-key.js
+++ b/test/util/key.js
@@ -2,11 +2,11 @@
 
 const test = require('ava')
 
-const { getKey } = require('../../src/util')
+const { key } = require('../../src/util')
 
-test('default getKey dedupe requests', t => {
+test('default key dedupe requests', t => {
   t.is(
-    getKey(
+    key(
       {
         req: {
           url: '/kikobeats?foo=bar&force'
@@ -17,7 +17,7 @@ test('default getKey dedupe requests', t => {
     '/kikobeats?foo=bar'
   )
   t.is(
-    getKey(
+    key(
       {
         req: {
           url: '/kikobeats?foo=bar&force=true'
@@ -28,7 +28,7 @@ test('default getKey dedupe requests', t => {
     '/kikobeats?foo=bar'
   )
   t.is(
-    getKey(
+    key(
       {
         req: {
           url: '/kikobeats?foo=bar&bypass=true'
@@ -39,7 +39,7 @@ test('default getKey dedupe requests', t => {
     '/kikobeats?foo=bar'
   )
   t.is(
-    getKey(
+    key(
       {
         req: {
           url: '/kikobeats?foo=bar&bypass=true&utm_source=twitter'