docs: update for new version

Author: RomainLanz

.github/workflows/checks.yml

@@ -12,7 +12,7 @@ jobs:
     - name: Setup Node.js
       uses: actions/setup-node@v4
       with:
-        node-version: 21
+        node-version:
 
     - name: Install pnpm
       run: |

docs/content/docs/adaptive_caching.md

@@ -9,10 +9,14 @@ Adaptive caching is a method to dynamically change the cache options based on th
 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' })
+const authToken = await bento.getOrSet({
+  key: 'token',
+  factory: 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:
@@ -23,10 +27,13 @@ In this example, we are fetching an authentication token that will expire after
 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;
+const authToken = await bento.getOrSet({
+  key: 'token',
+  factory: async (options) => {
+    const token = await fetchAccessToken();
+    options.setTtl(token.expiresIn);
+    return token;
+  }
 });
 ```
 
@@ -40,15 +47,18 @@ 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);
+const news = await namespace.getOrSet({
+  key: newsId,
+  factory: async (options) => {
+    const newsItem = await fetchNews(newsId);
 
-  if (newsItem.hasBeenUpdatedRecently) {
-    options.setTtl('5m');
-  } else {
-    options.setTtl('2d');
-  }
+    if (newsItem.hasBeenUpdatedRecently) {
+      options.setTtl('5m');
+    } else {
+      options.setTtl('2d');
+    }
 
-  return newsItem;
+    return newsItem;
+  }
 });
 ```

docs/content/docs/cache_drivers.md

@@ -50,9 +50,9 @@ const bento = new BentoCache({
 })
 ```
 
-| Option | Description | Default |
-| --- | --- | --- |
-| `connection` | The connection options to use to connect to Redis or an instance of `ioredis` | N/A |
+| Option       | Description                                                                   | Default |
+|--------------|-------------------------------------------------------------------------------|---------|
+| `connection` | The connection options to use to connect to Redis or an instance of `ioredis` | N/A     |
 
 ## Filesystem
 
@@ -74,10 +74,10 @@ const bento = new BentoCache({
 })
 ```
 
-| Option | Description | Default |
-| --- | --- | --- |
-| `directory` | The directory where the cache files will be stored. | N/A |
-| `pruneInterval` | The interval in milliseconds to prune expired entries. false to disable. | false |
+| Option          | Description                                                              | Default |
+|-----------------|--------------------------------------------------------------------------|---------|
+| `directory`     | The directory where the cache files will be stored.                      | N/A     |
+| `pruneInterval` | The interval in milliseconds to prune expired entries. false to disable. | false   |
 
 ### Prune Interval
 
@@ -105,11 +105,11 @@ const bento = new BentoCache({
 })
 ```
 
-| Option | Description | Default |
-| --- | --- | --- |
-| `maxSize` | The maximum size of the cache **in bytes**. | N/A |
-| `maxItems` | The maximum number of entries that the cache can contain. Note that fewer items may be stored if you are also using `maxSize` and the cache is full. | N/A |
-| `maxEntrySize` | The maximum size of a single entry in bytes. | N/A |
+| Option         | Description                                                                                                                                          | Default |
+|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| `maxSize`      | The maximum size of the cache **in bytes**.                                                                                                          | N/A     |
+| `maxItems`     | The maximum number of entries that the cache can contain. Note that fewer items may be stored if you are also using `maxSize` and the cache is full. | N/A     |
+| `maxEntrySize` | The maximum size of a single entry in bytes.                                                                                                         | N/A     |
 
 ## DynamoDB
 
@@ -143,16 +143,16 @@ You will also need to create a DynamoDB table with a string partition key named
 
 **Make sure to also enable [Time To Live (TTL)](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) on the table, on the `ttl` attribute. This will allow DynamoDB to automatically delete expired items.**
 
-| Option | Description | Default |
-| --- | --- | --- |
-| `table.name` | The name of the table that will be used to store the cache. | `cache` |
-| `credentials` | The credentials to use to connect to DynamoDB. | N/A |
-| `endpoint` | The endpoint to use to connect to DynamoDB. | N/A |
-| `region` | The region to use to connect to DynamoDB. | N/A |
+| Option        | Description                                                 | Default |
+|---------------|-------------------------------------------------------------|---------|
+| `table.name`  | The name of the table that will be used to store the cache. | `cache` |
+| `credentials` | The credentials to use to connect to DynamoDB.              | N/A     |
+| `endpoint`    | The endpoint to use to connect to DynamoDB.                 | N/A     |
+| `region`      | The region to use to connect to DynamoDB.                   | N/A     |
 
 
 :::warning
-Be careful with the `.clear()` function of the DynamoDB driver. We do not recommend using it. Dynamo does not offer a "native" `clear`, so we are forced to make several API calls to: retrieve the keys and delete them, 25 by 25 (max per `BatchWriteItemCommand`).
+You should be careful with the `.clear()` function of the DynamoDB driver. We do not recommend using it. Dynamo does not offer a "native" `clear`, so we are forced to make several API calls to: retrieve the keys and delete them, 25 by 25 (max per `BatchWriteItemCommand`).
 
 So using this function can be costly, both in terms of execution time and API request cost. And also pose rate-limiting problems. Use at your own risk.
 :::
@@ -163,18 +163,18 @@ We offer several drivers to use a database as a cache. The database store should
 
 :::note
 
-Note that you can easily create your own adapter by implementing the `DatabaseAdapter` interface if you are using another library not supported by Bentocache. See the [documentation](/docs/custom-cache-driver) for more details.
+Note that you can easily create your own adapter by implementing the `DatabaseAdapter` interface if you are using another library not supported by Bentocache. See the [documentation](./extend/custom_cache_driver.md) for more details.
 
 :::
 
 All SQL drivers accept the following options:
 
-| Option | Description | Default |
-| --- | --- | --- |
-| `tableName` | The name of the table that will be used to store the cache. | `bentocache` |
-| `autoCreateTable` | If the cache table should be automatically created if it does not exist. | `true` |
-| `connection` | An instance of `knex` or `Kysely` based on the driver. | N/A |
-| `pruneInterval` | The [Duration](./options.md#ttl-formats) in milliseconds to prune expired entries. | false |
+| Option            | Description                                                                        | Default      |
+|-------------------|------------------------------------------------------------------------------------|--------------|
+| `tableName`       | The name of the table that will be used to store the cache.                        | `bentocache` |
+| `autoCreateTable` | If the cache table should be automatically created if it does not exist.           | `true`       |
+| `connection`      | An instance of `knex` or `Kysely` based on the driver.                             | N/A          |
+| `pruneInterval`   | The [Duration](./options.md#ttl-formats) in milliseconds to prune expired entries. | false        |
 
 ### Knex
 
@@ -226,7 +226,7 @@ const bento = new BentoCache({
 
 ### Orchid ORM
 
-You must provide a Orchid ORM instance to use the Orchid driver. Feel free to check the [Orchid ORM documentation](https://orchid-orm.netlify.app/) for more details about the configuration. Orchid support the following databases : PostgreSQL.
+You must provide an Orchid ORM instance to use the Orchid driver. Feel free to check the [Orchid ORM documentation](https://orchid-orm.netlify.app/) for more details about the configuration. Orchid support the following databases : PostgreSQL.
 
 You will need to install `orchid-orm` to use this driver.
 

docs/content/docs/extend/custom_cache_driver.md

@@ -65,9 +65,9 @@ Similarly, the `L1CacheDriver` interface is the same, except that it is not asyn
 
 So this should be quite easy to implement. Feel free to take a lot at [the existing drivers](https://github.com/Julien-R44/bentocache/tree/main/packages/bentocache/src/drivers) implementations for inspiration. 
 
-Also note that your driver will receive two additional parameters in the constructor : `ttl` and `prefix`. These parameters are common to every drivers and their purpose is explained in the [options](../options.md) page.
+Also note that your driver will receive two additional parameters in the constructor : `ttl` and `prefix`. These parameters are common to every driver and their purpose is explained in the [options](../options.md) page.
 
-Once you defined you driver, you can create a factory function that will be used by Bentocache to create instances of your driver at runtime. The factory function must be something like this:
+Once you defined your driver, you can create a factory function that will be used by Bentocache to create instances of your driver at runtime. The factory function must be something like this:
 
 ```ts
 import type { CreateDriverResult } from 'bentocache/types'

docs/content/docs/grace_periods.md

@@ -14,7 +14,7 @@ Then, when the cache entry is requested again but not found, you will have to fe
 
 But what if your source of truth is down? Wouldn't it be nice to be able to serve stale data for a little while, until your source of truth is back up?
 
-This is what grace periods are for. Basically, you can specify a grace period when you set a cache entry. This grace period will be the duration during which an entry will still be considered as servable, even if it is stale, if anything goes wrong.
+This is what grace periods are for. This grace period will be the duration during which an entry will still be available, even if it is stale.
 
 ## How to use grace periods
 
@@ -23,26 +23,45 @@ Grace periods can be configured at global, driver and operations levels. See the
 Let's imagine you have a simple controller that fetches a user from the database, and caches it for 10 minutes:
 
 ```ts
-bento.getOrSet('users:1', () => User.find(1), { ttl: '10m' })
+bento.getOrSet({
+  key: 'users:1',
+  factory: () => User.find(1),
+  ttl: '10m',
+})
 ```
 
 Now, let's say your cache is empty. Someone request the user with id 1, but, the database is down, for any reasons. Without grace periods, this request will just fail and **will display an error to the user**.
 
 Now what if we add a grace period ?
 
 ```ts
-bento.getOrSet('users:1', () => User.find(1), {
+bento.getOrSet({
+  key: 'users:1',
+  factory: () => User.find(1),
   ttl: '10m',
-  gracePeriod: { enabled: true, duration: '6h', fallbackDuration: '5m' }
+  grace: '6h',
 })
 ```
 
 - First time this code is executed, user will be fetched from database, stored in cache for **10 minutes** with a grace period of **6 hours**.
 - **11 minutes later**, someone request the same user. The cache entry is logically expired, but the grace period is still valid.
-- So, we try to call the factory again to refresh the cache entry. But oops, **the database is down** ( or factory is failling for any other reasons ). 
+- So, we try to call the factory again to refresh the cache entry. But oops, **the database is down** ( or factory is failing for any other reasons ). 
 - Since we are still in the grace period of 6h, we will serve the stale data from the cache.
-- We also reconsider the stale cache entry as valid for 5m ( the `fallbackDuration` property ). In other words, subsequent requests for the same user will serve the same stale data for 5 minutes. This prevents overwhelming the database with multiple calls while it's down or overloaded. 
 
 As a result, instead of displaying an error page to the user, we are serving data that's a little out of date. Depending on your use case, this can result in a much better user experience.
 
-So, grace period is a practical solution that can help you maintain a positive user experience even during unforeseen downtimes or heavy loads on your data source. By understanding how to configure this feature, you can make your application more resilient and user-friendly.
+## Backoff strategy
+
+If the factory is failing, you can also use a backoff strategy to retry the factory only after a certain amount of time. This is useful to avoid hammering your database or API when it's down.
+
+```ts
+bento.getOrSet({
+  key: 'users:1',
+  factory: () => User.find(1),
+  ttl: '10m',
+  grace: '6h',
+  graceBackoff: '5m',
+})
+```
+
+In this example, if the factory fails, we will wait 5 minutes before trying again.

docs/content/docs/introduction.md

@@ -26,7 +26,7 @@ There are already caching libraries for Node: [`keyv`](https://keyv.org/), [`cac
 
 Not to knock them, on the contrary, they have their use cases and cool. Some are even "marketed" as such and are still very handy for simple caching system.
 
-Bentocache, on the other hand, is a **full-featured caching library**. We indeed have this notion of unified access to differents drivers, but in addition to that, we have a ton of features that will allow you to do robust caching.
+Bentocache, on the other hand, is a **full-featured caching library**. We indeed have this notion of unified access to different drivers, but in addition to that, we have a ton of features that will allow you to do robust caching.
 
 With that in mind, then I believe there is no serious alternative to Bentocache in the JavaScript ecosystem. Which is regrettable, because all other languages have powerful solutions. This is why Bentocache was created.
 
@@ -84,7 +84,7 @@ Multi-layer caching allows you to combine the speed of in-memory caching with th
 
 Many drivers available to suit all situations: Redis, Upstash, Database (MySQL, SQLite, PostgreSQL), DynamoDB, Filesystem, In-memory (LRU Cache), Vercel KV...
 
-See the [drivers documentation](./cache_drivers.md) for list of available drivers. Also very easy to extend the library and [add your own driver](tbd)
+See the [drivers documentation](./cache_drivers.md) for list of available drivers. Also, very easy to extend the library and [add your own driver](./extend/custom_cache_driver.md)
 
 <!-- :::warning
 Only a Redis driver for the bus is currently available. We probably have drivers for other backends like Zookeeper, Kafka, RabbitMQ... Let us know with an issue if you are interested in this.
@@ -97,7 +97,7 @@ Only a Redis driver for the bus is currently available. We probably have drivers
 
 - [Cache stamped prevention](./stampede_protection.md): Ensuring that only one factory is executed at the same time.
 
-- [Retry queue](./multi_tier.md#retry-queue-strategy) : When a application fails to publish something to the bus, it is added to a queue and retried later.
+- [Retry queue](./multi_tier.md#retry-queue-strategy) : When an application fails to publish something to the bus, it is added to a queue and retried later.
 
 ### Timeouts 
 
@@ -110,8 +110,8 @@ The ability to create logical groups for cache keys together, so you can invalid
 ```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() 
 ```
@@ -135,14 +135,14 @@ All TTLs can be passed in a human-readable string format. We use [lukeed/ms](htt
 ```ts
 bento.getOrSet({
   key: 'foo',
-  ttl: '2.5h',
   factory: () => getFromDb(),
+  ttl: '2.5h',
 })
 ```
 
 In this case, when only 20% or less of the TTL remains and the entry is requested : 
 
-- It will returns the cached value to the user.
+- It will return the cached value to the user.
 - Start a background refresh by calling the factory.
 - Next time the entry is requested, it will be already computed, and can be returned immediately.
 
@@ -164,9 +164,6 @@ See the [logging documentation](./digging_deeper/logging.md) for more informatio
 
 If you like this project, [please consider supporting it by sponsoring it](https://github.com/sponsors/Julien-R44/). It will help a lot to maintain and improve it. Thanks a lot !
 
-
-
-
 ## Prior art and inspirations
 
 - https://github.com/ZiggyCreatures/FusionCache