docs: update docs with latest changes

Author: Julien-R44

README.md

@@ -14,6 +14,7 @@
 - 🛡️ Grace period and timeouts. Serve stale data when the store is dead or slow
 - 🤓 SWR-like caching strategy
 - 🗂️ Namespaces. Group your keys by categories.
+- 🏷️ Tagging. Easy invalidations.
 - 🛑 Cache stamped protection.
 - 🏷️ Named caches
 - 📖 Well documented + handy JSDoc annotations
@@ -89,15 +90,29 @@ See the [drivers documentation](https://bentocache.dev/docs/cache-drivers) for l
 
 If your factory is taking too long to execute, you can just return a little bit of stale data while keeping the factory running in the background. Next time the entry is requested, it will be already computed and served immediately.
 
+### Tagging
+
+Allows associating a cache entry with one or more tags to simplify invalidation. Instead of managing individual keys, entries can be grouped under multiple tags and invalidated in a single operation.
+
+```ts
+await bento.getOrSet({
+  key: 'foo',
+  factory: getFromDb(),
+  tags: ['tag-1', 'tag-2']
+});
+
+await bento.deleteByTags({ tags: ['tag-1'] });
+```
+
 ### Namespaces
 
-The ability to create logical groups for cache keys together, so you can invalidate everything at once later :
+Another way to group your keys is to use namespaces. This allows you to invalidate everything at once later :
 
 ```ts
 const users = bento.namespace('users')
 
-users.set('32', { name: 'foo' })
-users.set('33', { name: 'bar' })
+users.set({ key: '32', value: { name: 'foo' } })
+users.set({ key: '33', value: { name: 'bar' } })
 
 users.clear() 
 ```

docs/content/docs/adaptive_caching.md

@@ -31,7 +31,7 @@ const authToken = await bento.getOrSet({
   key: 'token',
   factory: async (options) => {
     const token = await fetchAccessToken();
-    options.setTtl(token.expiresIn);
+    options.setOptions({ ttl: token.expiresIn });
     return token;
   }
 });
@@ -53,9 +53,9 @@ const news = await namespace.getOrSet({
     const newsItem = await fetchNews(newsId);
 
     if (newsItem.hasBeenUpdatedRecently) {
-      options.setTtl('5m');
+      options.setOptions({ ttl: '5m' });
     } else {
-      options.setTtl('2d');
+      options.setOptions({ ttl: '2d' });
     }
 
     return newsItem;

docs/content/docs/db.json

@@ -41,6 +41,12 @@
     "contentPath": "./methods.md",
     "category": "Guides"
   },
+  {
+    "permalink": "tagging",
+    "title": "Tagging",
+    "contentPath": "./tags.md",
+    "category": "Guides"
+  },
   {
     "permalink": "namespaces",
     "title": "Namespaces",

docs/content/docs/introduction.md

@@ -14,6 +14,7 @@ Bentocache is a robust multi-tier caching library for Node.js applications
 - 🛡️ Grace period and timeouts. Serve stale data when the store is dead or slow
 - 🤓 SWR-like caching strategy
 - 🗂️ Namespaces. Group your keys by categories.
+- 🏷️ Tagging. Easy invalidations.
 - 🛑 Cache stamped protection.
 - 🏷️ Named caches
 - 📖 Well documented + handy JSDoc annotations
@@ -102,9 +103,23 @@ Only a Redis driver for the bus is currently available. We probably have drivers
 
 If your factory is taking too long to execute, you can just return a little bit of stale data while keeping the factory running in the background. Next time the entry is requested, it will be already computed and served immediately.
 
+### Tagging
+
+Allows associating a cache entry with one or more tags to simplify invalidation. Instead of managing individual keys, entries can be grouped under multiple tags and invalidated in a single operation.
+
+```ts
+await bento.getOrSet({
+  key: 'foo',
+  factory: getFromDb(),
+  tags: ['tag-1', 'tag-2']
+});
+
+await bento.deleteByTags({ tags: ['tag-1'] });
+```
+
 ### Namespaces
 
-The ability to create logical groups for cache keys together, so you can invalidate everything at once later :
+Another way to group your keys is to use namespaces. This allows you to invalidate everything at once later :
 
 ```ts
 const users = bento.namespace('users')
@@ -165,6 +180,8 @@ If you like this project, [please consider supporting it by sponsoring it](https
 
 ## Prior art and inspirations
 
+Bentocache was inspired by several other caching libraries and systems. Especially [FusionCache](https://github.com/ZiggyCreatures/FusionCache), which is probably the most advanced caching library I've ever seen, no matter the language. Huge kudos to the author for his amazing work.
+
 - https://github.com/ZiggyCreatures/FusionCache
 - https://laravel.com/docs/10.x/cache
 - https://github.com/TurnerSoftware/CacheTower

docs/content/docs/methods.md

@@ -83,25 +83,6 @@ const products = await bento.getOrSet({
 
 The `getOrSet` factory function accepts an `ctx` object as argument that can be used to do multiple things:
 
-### ctx.setTtl
-
-`setTtl` allows you to set the TTL of the key dynamically. This is useful when the TTL depends on the value itself.
-
-```ts
-const products = await bento.getOrSet({
-  key: 'token',
-  factory: async (ctx) => {
-    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. See [Adaptive Caching docs](./adaptive_caching.md) for more information.
-
 ### ctx.skip
 
 Returning `skip` in a factory will not cache the value, and `getOrSet` will returns `undefined` even if there is a stale item in cache.
@@ -143,6 +124,47 @@ cache.getOrSet({
 })
 ```
 
+### ctx.setOptions
+
+`setOptions` allows you to update the options of the cache entry. This is useful when you want to update the TTL, grace period, or tags and when it depends on the value itself.
+
+
+```ts
+const products = await bento.getOrSet({
+  key: 'token',
+  factory: async (ctx) => {
+    const token = await fetchAccessToken()
+
+    options.setOptions({
+      ttl: token.expiresIn,
+      tags: ['auth', 'token'],
+    })
+
+    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. See [Adaptive Caching docs](./adaptive_caching.md) for more information.
+
+### ctx.gracedEntry
+
+If a stale value is available in the cache, `ctx.gracedEntry` will contain it. This can be useful if you want to do something based on the stale value.
+
+```ts
+const products = await bento.getOrSet({
+  key: 'products',
+  factory: async (ctx) => {
+    if (ctx.gracedEntry?.value === 'bar') {
+      return 'foo'
+    }
+
+    return 'bar'
+  }
+})
+```
+
 ## getOrSetForever
 
 Same as `getOrSet`, but the value will never expire.
@@ -186,6 +208,32 @@ Delete a key from the cache.
 await bento.delete({ key: 'products' })
 ```
 
+## expire
+
+This method is slightly different from `delete`:
+
+When we delete a key, it is completely removed and forgotten. This means that even if we use grace periods, the value will no longer be available.
+
+`expire` works like `delete`, except that instead of completely removing the value, we just mark it as expired/stale but keep it for the [grace period](./grace_periods.md). For example:
+
+```ts
+// Set a value with a grace period of 6 minutes
+await cache.set({ 
+  key: 'hello',
+  value: 'world',
+  grace: '6m'
+})
+
+// Expire the value. It is kept in the cache but marked as STALE for 6 minutes
+await cache.expire({ key: 'hello' })
+
+// Here, a get with `grace: false` will return nothing, because we have a stale value
+const r1 = await cache.get({ key: 'hello', grace: false })
+
+// Here it will return the value, because it is still within the grace period
+const r2 = await cache.get({ key: 'hello' })
+```
+
 ## deleteMany
 
 Delete multiple keys from the cache.

docs/content/docs/options.md

@@ -132,6 +132,34 @@ const bento = new BentoCache({
 })
 ```
 
+### `l2CircuitBreakerDuration`
+
+Default: `undefined (disabled)`
+
+Levels: `global`, `store`, `operation`
+
+This option allows you to enable a simple circuit breaker system for the L2 Cache. If defined, the circuit breaker will open when a call to our distributed cache fails. It will stay open for `l2CircuitBreakerDuration` seconds. 
+
+If you're not familiar with the circuit breaker system, to summarize it very simply: if an operation on the L2 Cache fails and the circuit breaker option is activated, then all future operations on the L2 Cache will be rejected for `l2CircuitBreakerDuration` seconds, in order to avoid overloading the L2 Cache with operations that are likely to fail. 
+
+Once the `l2CircuitBreakerDuration` seconds have passed, the circuit breaker closes and operations on the L2 Cache can resume.
+
+### skipL2Write
+
+Default: `false`
+
+Levels: `operation`
+
+If `true`, the L2 Cache will not be called to write a value.
+
+### skipBusNotify
+
+Default: `false`
+
+Levels: `operation`
+
+If `true`, no notification will be sent to the bus after an operation.
+
 ### `serializer`
 
 Default: `JSON.stringify` and `JSON.parse`

docs/content/docs/tags.md

@@ -0,0 +1,137 @@
+---
+summary: Associate tags with your cache keys to easily invalidat a bunch of keys at once
+---
+
+# Tags
+
+:::warning
+Tags are available since v1.2.0 and still **experimental**. 
+
+We will **not** make breaking changes without a major version, but no guarantees are made about the stability of this feature yet.
+
+Please if you find any bugs, report them on Github issues.
+:::
+
+
+Tagging allows associating a cache entry with one or more tags to simplify invalidation. Instead of managing individual keys, entries can be grouped under multiple tags and invalidated in a single operation.
+
+## Usage
+
+```ts
+await bento.getOrSet({
+  key: 'foo',
+  factory: getFromDb(),
+  tags: ['tag-1', 'tag-2']
+});
+
+await bento.set({ key: 'foo', tags: ['tag-1'] });
+```
+
+To invalidate all entries linked to a tag:
+
+```ts
+await bento.deleteByTags({ tags: ['tag-1'] });
+```
+
+Now, imagine that the tags depend on the cached value itself. In that case, you can use [adaptive caching](./adaptive_caching.md) to update tags dynamically based on the computed value.
+
+```ts
+const product = await bento.getOrSet({
+  key: `product:${id}`,
+  factory: async (ctx) => {
+    const product = await fetchProduct(id);
+    ctx.setTags(product.tags);
+    return product;
+  }
+})
+```
+
+
+## How it works
+
+If you are interested in how Bentocache handles tags internally, read on.
+
+Generally, there are two ways to implement tagging in a cache system:
+
+- **Server-side tagging**: The cache backend (e.g., Redis, Memcached, databases) is responsible for managing tags and their associated entries. However, most distributed caches do not natively support tagging. When it's not supported, workarounds exist, but they are either inefficient or complex to implement.
+
+- **Client-side tagging**: The caching library manages tags internally. This is the approach used by Bentocache.
+
+Bentocache implements **client-side tagging**, making it fully backend-agnostic. Instead of relying on the cache backend to track and delete entries by tags, Bentocache tracks invalidation timestamps for each tag and filters out stale data dynamically.
+
+This means all Bentocache drivers automatically support tagging without any modification. If someone implements a custom driver, tagging will work out of the box, without requiring any additional logic.
+
+### Why avoid server-side tagging
+
+Among all the cache backends Bentocache supports, none provide a native tagging system without significant overhead. Of course, something could probably be hacked together on top of all drivers, but it would probably be inefficient and also pretty complex to implement, depending on the backend.
+
+For example:
+
+- In Redis, tagging could be hacked together using Redis sets, but this would require complex management and would not be efficient for large datasets.
+- In databases, a separate table mapping cache keys to tags could be used, but this would significantly increase query complexity and also reduce performance.
+
+By performance, I mean that to delete all keys associated with a tag, you’d typically need to run a query like:
+
+```sql
+DELETE * FROM cache WHERE "my-tag" IN tags;
+```
+
+This approach does not scale in a distributed cache with millions of entries, as scanning large datasets in real-time would be extremely slow and inefficient.
+
+### How Bentocache handles tags
+
+Instead of directly deleting entries with a given tag, Bentocache uses a more efficient approach.
+
+Core idea is pretty simple:
+- When a tag is invalidated, Bentocache stores an **invalidation timestamp** in the cache.
+- When fetching an entry, Bentocache checks whether it was cached before or after its associated tags were invalidated.
+
+Let's take a concrete example. Here we just cached an entry with the tags `tag-1` and `tag-2`:
+
+```ts
+await bento.getOrSet({
+  key: 'foo',
+  factory: getFromDb(),
+  tags: ['tag-1', 'tag-2']
+});
+```
+
+Internally, Bentocache stores something like:
+
+```ts
+foo = { value: 'bar', tags: ['tag-1', 'tag-2'], createdAt: 1700000 }
+```
+
+Note that we also store the creation date of the entry as `createdAt`.
+
+Now, we invalidate the `tag-1` tag:
+
+```ts
+await bento.deleteByTags({ tags: ['tag-1'] });
+```
+
+Instead of scanning and deleting every entry associated with `tag-1`, Bentocache simply stores the invalidation timestamp under a special cache key:
+
+```ts
+__bentocache:tags:tag-1 = { invalidatedAt: 1701234 }
+```
+
+So, we store the invalidation timestamp of the tag under the key `__bentocache:tags:tag-1`. This means that any cache entry associated with tag-1 created before `1700001234` is now considered stale.
+
+Now, when fetching an entry, Bentocache checks if it was created before the tag was invalidated. If it was, Bentocache considers the entry stale and ignores it.
+
+In fact, the implementation is a bit more complex than that, but that's the general idea. 
+
+## Limitations
+
+The main limitation of this system is that you should avoid using too many tags on a single entry. The more tags you use per entry, the more invalidation timestamps Bentocache needs to store and especially check when fetching an entry. This can increase lookup times and impact performance. 
+
+In fact, the same issue exists in other systems like Loki, OpenTelemetry, TimescaleDB etc.. where it's known as the "high cardinality" problem. To maintain optimal performance, it's recommended to **keep the number of tags per entry reasonable**.
+
+## Acknowledgements
+
+The concept of client-side tagging in Bentocache was **heavily inspired** by the huge work done by Jody Donetti on [FusionCache](https://github.com/ZiggyCreatures/FusionCache).
+
+Reading his detailed explanations and discussions on GitHub provided invaluable insights into the challenges and solutions in implementing an efficient tagging system.
+
+A **huge thanks** for sharing his expertise and paving the way for innovative caching strategies