feat: add adaptive caching

Close #8

Author: Julien-R44

docs/content/docs/adaptive_caching.md

@@ -0,0 +1,54 @@
+---
+summary: Dynamically change the cache strategy based on the data being cached.
+---
+
+# Adaptive Caching
+
+Adaptive caching is a method to dynamically change the cache options based on the data being cached. This approach is particularly useful when caching options depend on the value itself.
+
+For example, authentication tokens are a perfect example of this use case. Consider the following scenario:
+
+```ts
+const authToken = await bento.getOrSet('token', async () => {
+  const token = await fetchAccessToken()
+  return token
+}, { ttl: '10m' })
+```
+
+In this example, we are fetching an authentication token that will expire after some time. The problem is, we have no idea when the token will expire until we fetch it. So, we decide to cache the token for 10 minutes, but this approach has multiple issues:
+
+- First, if the token expires before 10 minutes, we will still use the expired token.
+- Second, if the token expires after 10 minutes, we will fetch a new token even if the old one is still valid.
+
+This is where adaptive caching comes in. Instead of setting a fixed TTL, we can set it dynamically based on the token's expiration time:
+
+```ts
+const authToken = await bento.getOrSet('token', async (options) => {
+  const token = await fetchAccessToken();
+  options.setTtl(token.expiresIn);
+  return token;
+});
+```
+
+And that's it! Now, the token will be removed from the cache when it expires, and a new one will be fetched.
+
+There are other use cases for adaptive caching. For example, consider managing a news feed with BentoCache. You may want to cache the freshest articles for a short period of time and the older articles for a much longer period. 
+
+Because the freshest articles are more likely to change: they may have typos, require updates, etc., whereas the older articles are less likely to change and may not have been updated for years.
+
+Let's see how we can achieve this with BentoCache:
+
+```ts
+const namespace = bento.namespace('news');
+const news = await namespace.getOrSet(newsId, async (options) => {
+  const newsItem = await fetchNews(newsId);
+
+  if (newsItem.hasBeenUpdatedRecently) {
+    options.setTtl('5m');
+  } else {
+    options.setTtl('2d');
+  }
+
+  return newsItem;
+});
+```

docs/content/docs/db.json

@@ -71,6 +71,12 @@
     "contentPath": "./stampede_protection.md",
     "category": "Guides"
   },
+  {
+    "permalink": "adaptive-caching",
+    "title": "Adaptive caching",
+    "contentPath": "./adaptive_caching.md",
+    "category": "Guides"
+  },
   {
     "permalink": "events",
     "title": "Events",

docs/content/docs/methods.md

@@ -89,6 +89,18 @@ const products = await bento.getOrSet('products', () => fetchProducts(), {
 })
 ```
 
+The `getOrSet` factory function accepts an `options` object as argument that can be used to dynamically set some cache options. This can be particulary useful when caching options depends on the value itself.
+
+```ts
+const products = await bento.getOrSet('token', (options) => {
+  const token = await fetchAccessToken()
+  options.setTtl(token.expiresIn)
+  return token
+})
+```
+
+Auth tokens are a perfect example of this use case. The cached token should expire when the token itself expires. And we know the expiration time only after fetching the token.
+
 ### getOrSetForever
 
 Same as `getOrSet`, but the value will never expire.

packages/bentocache/package.json

@@ -85,6 +85,7 @@
     "better-sqlite3": "^9.4.5",
     "cache-manager": "^5.5.0",
     "cache-manager-ioredis-yet": "^1.2.2",
+    "dayjs": "^1.11.10",
     "defu": "^6.1.4",
     "emittery": "^1.0.3",
     "ioredis": "^5.3.2",

packages/bentocache/src/bento_cache.ts

@@ -14,6 +14,7 @@ import type {
   BentoCachePlugin,
   HasOptions,
   ClearOptions,
+  GetSetFactory,
 } from './types/main.js'
 
 export class BentoCache<KnownCaches extends Record<string, BentoStore>> implements CacheProvider {
@@ -156,15 +157,15 @@ export class BentoCache<KnownCaches extends Record<string, BentoStore>> implemen
    * Retrieve an item from the cache if it exists, otherwise store the value
    * provided by the factory and return it
    */
-  async getOrSet<T>(key: string, factory: Factory<T>, options?: GetOrSetOptions): Promise<T> {
+  async getOrSet<T>(key: string, factory: GetSetFactory<T>, options?: GetOrSetOptions): Promise<T> {
     return this.use().getOrSet(key, factory, options)
   }
 
   /**
    * Retrieve an item from the cache if it exists, otherwise store the value
    * provided by the factory forever and return it
    */
-  getOrSetForever<T>(key: string, cb: Factory<T>, opts?: GetOrSetOptions): Promise<T> {
+  getOrSetForever<T>(key: string, cb: GetSetFactory<T>, opts?: GetOrSetOptions): Promise<T> {
     return this.use().getOrSetForever(key, cb, opts)
   }
 

packages/bentocache/src/cache/cache.ts

@@ -12,6 +12,7 @@ import type {
   SetOptions,
   HasOptions,
   ClearOptions,
+  GetSetFactory,
 } from '../types/main.js'
 
 export class Cache implements CacheProvider {
@@ -105,7 +106,7 @@ export class Cache implements CacheProvider {
    * Retrieve an item from the cache if it exists, otherwise store the value
    * provided by the factory and return it
    */
-  async getOrSet<T>(key: string, factory: Factory<T>, options?: GetOrSetOptions): Promise<T> {
+  async getOrSet<T>(key: string, factory: GetSetFactory<T>, options?: GetOrSetOptions): Promise<T> {
     const cacheOptions = this.#stack.defaultOptions.cloneWith(options)
     return this.#getSetHandler.handle(key, factory, cacheOptions)
   }
@@ -116,7 +117,7 @@ export class Cache implements CacheProvider {
    */
   async getOrSetForever<T>(
     key: string,
-    factory: Factory<T>,
+    factory: GetSetFactory<T>,
     options?: GetOrSetOptions,
   ): Promise<T> {
     const cacheOptions = this.#stack.defaultOptions.cloneWith({ ttl: null, ...options })

packages/bentocache/src/cache/cache_entry/cache_entry_options.ts

@@ -1,7 +1,7 @@
 import hexoid from 'hexoid'
 
 import { resolveTtl } from '../../helpers.js'
-import type { RawCommonOptions } from '../../types/main.js'
+import type { Duration, RawCommonOptions } from '../../types/main.js'
 
 // @ts-expect-error wrongly typed
 const toId = hexoid(12)
@@ -165,6 +165,19 @@ export class CacheEntryOptions {
     return this.#options.suppressL2Errors
   }
 
+  /**
+   * Set a new logical TTL
+   */
+  setLogicalTtl(ttl: Duration) {
+    this.#options.ttl = ttl
+
+    this.logicalTtl = this.#resolveLogicalTtl()
+    this.physicalTtl = this.#resolvePhysicalTtl()
+    this.earlyExpireTtl = this.#resolveEarlyExpireTtl()
+
+    return this
+  }
+
   /**
    * Compute the logical TTL timestamp from now
    */

packages/bentocache/src/cache/factory_runner.ts

@@ -4,8 +4,8 @@ import type { MutexInterface } from 'async-mutex'
 import type { Locks } from './locks.js'
 import * as exceptions from '../errors.js'
 import { events } from '../events/index.js'
-import type { Factory } from '../types/helpers.js'
 import type { CacheStack } from './stack/cache_stack.js'
+import type { GetSetFactory } from '../types/helpers.js'
 import type { CacheStackWriter } from './stack/cache_stack_writer.js'
 import type { CacheEntryOptions } from './cache_entry/cache_entry_options.js'
 
@@ -48,7 +48,7 @@ export class FactoryRunner {
 
   async run(
     key: string,
-    factory: Factory,
+    factory: GetSetFactory,
     hasFallback: boolean,
     options: CacheEntryOptions,
     lockReleaser: MutexInterface.Releaser,
@@ -59,7 +59,9 @@ export class FactoryRunner {
         ? exceptions.E_FACTORY_HARD_TIMEOUT
         : exceptions.E_FACTORY_SOFT_TIMEOUT
 
-    const promisifiedFactory = async () => await factory()
+    const promisifiedFactory = async () => {
+      return await factory({ setTtl: (ttl) => options.setLogicalTtl(ttl) })
+    }
 
     const factoryPromise = promisifiedFactory()
 

packages/bentocache/src/types/helpers.ts

@@ -17,6 +17,19 @@ export type MaybePromise<T> = T | Promise<T>
  */
 export type Factory<T = any> = T | (() => T) | Promise<T> | (() => Promise<T>)
 
+export type GetSetFactoryOptions = {
+  /**
+   * Set dynamically the TTL
+   * See Adaptive caching documentation for more information
+   */
+  setTtl: (ttl: Duration) => void
+}
+
+/**
+ * GetOrSet Factory
+ */
+export type GetSetFactory<T = any> = (options: GetSetFactoryOptions) => T | Promise<T>
+
 /**
  * Logger interface
  */

packages/bentocache/src/types/provider.ts

@@ -1,4 +1,4 @@
-import type { Factory } from './helpers.js'
+import type { Factory, GetSetFactory } from './helpers.js'
 import type {
   ClearOptions,
   DeleteOptions,
@@ -44,12 +44,16 @@ export interface CacheProvider {
   /**
    * Get or set a value in the cache
    */
-  getOrSet<T>(key: string, factory: Factory<T>, options?: Factory<T> | GetOrSetOptions): Promise<T>
+  getOrSet<T>(
+    key: string,
+    factory: GetSetFactory<T>,
+    options?: GetSetFactory<T> | GetOrSetOptions,
+  ): Promise<T>
 
   /**
    * Get or set a value in the cache forever
    */
-  getOrSetForever<T>(key: string, cb: Factory<T>, opts?: GetOrSetOptions): Promise<T>
+  getOrSetForever<T>(key: string, cb: GetSetFactory<T>, opts?: GetOrSetOptions): Promise<T>
 
   /**
    * Returns a new instance of the driver namespaced

packages/bentocache/tests/cache/cache_entry_options.spec.ts

@@ -149,4 +149,14 @@ test.group('Cache Entry Options', () => {
       hard: string.milliseconds.parse('4m'),
     })
   })
+
+  test('setTtl should re-compute physical ttl and early expiration', ({ assert }) => {
+    const options = new CacheEntryOptions({ ttl: '10m', earlyExpiration: 0.5 })
+
+    options.setLogicalTtl(string.milliseconds.parse('5m'))
+
+    assert.equal(options.logicalTtl, string.milliseconds.parse('5m'))
+    assert.equal(options.physicalTtl, string.milliseconds.parse('5m'))
+    assert.equal(options.earlyExpireTtl, string.milliseconds.parse('2.5m'))
+  })
 })

packages/bentocache/tests/cache/one_tier_local.spec.ts

@@ -1,3 +1,4 @@
+import dayjs from 'dayjs'
 import { test } from '@japa/runner'
 import { setTimeout } from 'node:timers/promises'
 
@@ -594,4 +595,23 @@ test.group('One tier tests', () => {
     assert.deepEqual(result1.value, 'value')
     assert.equal(result2.status, 'rejected')
   })
+
+  test('adaptive caching', async ({ assert }) => {
+    const { cache, local, stack } = new CacheFactory().withMemoryL1().merge({ ttl: '10m' }).create()
+
+    await cache.getOrSet(
+      'key1',
+      (options) => {
+        options.setTtl('2d')
+        return { foo: 'bar' }
+      },
+      { ttl: '4m' },
+    )
+
+    const res = local.get('key1', stack.defaultOptions)!
+    const logicalExpiration = res.getLogicalExpiration()
+
+    const inTwoDays = dayjs().add(2, 'day')
+    assert.isTrue(dayjs(logicalExpiration).isSame(inTwoDays, 'day'))
+  })
 })