docs: first step docs

Author: Julien-R44

docs/content/docs/introduction.md

@@ -1,184 +1,130 @@
 ---
-summary: Bentocache is a robust multi-tier caching library for Node.js applications
+summary: Verrou is a locking library for managing locks in a NodeJS application.
 ---
 
 # Introduction
 
-Bentocache is a robust multi-tier caching library for Node.js applications
+Verrou is a locking library for managing locks ( mutexes ) in a NodeJS application.
 
-- 🗄️ Multi-tier caching
-- 🔄 Synchronization of local cache via Bus
-- 🚀 Many drivers (Redis, Upstash, In-memory, Postgres, Sqlite and others)
-- 🛡️ Grace period and timeouts. Serve stale data when the store is dead or slow
-- 🔄 Early refresh. Refresh cached value before needing to serve it
-- 🗂️ Namespaces. Group your keys by categories.
-- 🛑 Cache stamped protection.
-- 🏷️ Named caches
-- 📖 Well documented + handy JSDoc annotations
-- 📊 Events. Useful for monitoring and metrics
-- 📝 Easy Prometheus integration and ready-to-use Grafana dashboard
-- 🧩 Easily extendable with your own driver
+- 🔒 Easy Usage
+- 🔄 Multiple drivers (Redis, Postgres, MySQL, Sqlite, In-Memory and others)
+- 🔑 Customizable Named Locks
+- 🌐 Consistent API Across All Drivers
+- 🧪 Easy testing by switching to an in-memory driver
+- 🔨 Easily extensible with your own drivers
 
-## Why Bentocache ? 
-
-There are already caching libraries for Node: [`keyv`](https://keyv.org/), [`cache-manager`](https://github.com/node-cache-manager/node-cache-manager#readme), or [`unstorage`](https://unstorage.unjs.io/). However, I think that we could rather consider these libraries as bridges that allow different stores to be used via a unified API, rather than true caching solutions as such.
-
-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.
-
-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.
-
-## Quick presentation
-
-Bentocache is a caching solution aimed at combining performance and flexibility. If you are looking for a caching system that can transition from basic use to advanced multi-level configuration, you are in the right place. Here's what you need to know :
-
-### One-level
-
-The one-level mode is a standard caching method. Choose from a variety of drivers such as **Redis**, **In-Memory**, **Filesystem**, **DynamoDB**, and more, and you're ready to go. 
-
-In addition to this, you benefit from many features that allow you to efficiently manage your cache, such as **cache stampede protection**, **grace periods**, **timeouts**, **namespaces**, etc.
-
-### Two-levels
-For those looking to go further, you can use the two-levels caching system. Here's basically how it works:
-
-- **L1: Local Cache**: First level cache. Data is stored in memory with an LRU algorithm for quick access
-- **L2: Distributed Cache**: If the data is not in the in-memory cache, it is searched in the distributed cache (Redis, for example)
-- **Synchronization via Bus**: In a multi-instance context, you can synchronize different local in-memory caches of your instances via a Bus like Redis or RabbitMQ. This method maintains cache integrity across multiple instances
-
-Here is a simplified diagram of the flow :
-
-![Bentocache Diagram flow](content/docs/bentocache_flow.webp)
-
-All of this is managed invisibly for you via Bentocache. The only thing to do is to set up a bus in your infrastructure. But if you need multi-level cache, you're probably already using Redis rather than your database as a distributed cache. So you can leverage it to synchronize your local caches
+---
 
-The major benefit of multi-tier caching is that it allows for responses between 2,000x and 5,000x faster. While Redis is fast, accessing RAM is REALLY MUCH faster.
 
-In fact, it's a quite common pattern : to quote an example, it's [what Stackoverflow does](https://nickcraver.com/blog/2019/08/06/stack-overflow-how-we-do-app-caching/#layers-of-cache-at-stack-overflow). 
+:::codegroup
 
+```ts
+// title: Basic example
+import { Verrou } from 'verrou'
+import { redisStore } from 'verrou/drivers/redis'
+import { memoryStore } from 'verrou/drivers/memory'
+
+const verrou = new Verrou({
+  default: 'redis',
+  drivers: {
+    redis: { driver: redisStore() },
+    memory: { driver: memoryStore() }
+  }
+})
 
-To give some perspective, here's a simple benchmark that shows the difference between a simple distributed cache ( using Redis ) vs a multi-tier cache ( using Redis + In-memory cache ) :
+await verrou.createLock('my-resource').run(async () => {
+  await doSomething()
+}) // Lock is automatically released
+```
 
 ```ts
-// title: Benchmarked code
-benchmark
-  .add('BentoCache', async () => await bento.get('key'))
-  .add('ioredis', async () => await ioredis.get('key'))
+// title: Manual lock
+import { Verrou, E_LOCK_TIMEOUT } from 'verrou'
+
+const lock = verrou.createLock('my-resource')
+try {
+  await lock.acquire()
+  await doSomething()
+} catch (error) {
+  if (error instanceof E_LOCK_TIMEOUT) {
+    // handle timeout
+  }
+} finally {
+  await lock.release()
+}
 ```
 
-![Redis vs Multi-tier caching](content/docs/redis_vs_mtier.webp)
-
-So a pretty huge difference.
-
-
-## Features
-
-Below is a list of the main features of BentoCache. If you want to know more, you can read each associated documentation page.
-
-### Multi layer caching
-
-Multi-layer caching allows you to combine the speed of in-memory caching with the persistence of a distributed cache. Best of both worlds.
-
-### Lot of drivers
-
-Many drivers available to suit all situations: Redis, Upstash, Database (MySQL, SQLite, PostgreSQL), DynamoDB, Filesystem, In-memory (LRU Cache), Vercel KV...
+```ts
+// title: using keyword
+import { Verrou } from 'verrou'
 
-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)
+const lock = verrou.createLock('my-resource')
 
-<!-- :::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.
-::: -->
+function myFunction() {
+  await using handle = await lock.acquire()
 
+  await doSomething()
+} // Lock is automatically released here thanks to the using keyword
+```
 
-### Resiliency
+:::
 
-- [Grace period](./grace_periods.md): Keep your application running smoothly with the ability to temporarily use expired cache entries when your database is down, or when a factory is failing.
+## Why Verrou ? 
 
-- [Cache stamped prevention](./stampede_protection.md): Ensuring that only one factory is executed at the same time.
+Main advantage of Verrou is that it provides a consistent API across all drivers. This means that you can switch from one driver to another without having to change your code. It also means you can switch to an in-memory in your test environment, making tests faster and easier to setup (no infrastructure or anything fancy to setup).
 
-- [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.
+Having a consistent API also means that you don't have to learn a new API when switching from one driver to another. Today, in the node ecosystem, we have different npm packages to manage locks, but they all have differents APIs and behaviors.
 
-### Timeouts 
+But having a consistent API doesn't mean having a less powerful API. Verrou provides every features you would expect from a locking library, and even more.
 
-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.
+## Why I would need a locking library ?
 
-### Namespaces
+Well, locks is a very common pattern in software development. It is used to prevent multiple processes or concurrent code from accessing a shared resource at the same time. It probably sounds a bit abstract, so let's take a concrete example.
 
-The ability to create logical groups for cache keys together, so you can invalidate everything at once later :
+Let's say you are writing code for a banking system. You have a function that transfer money from one account to another. We gonna implement it very naively, and then we will see what can go wrong.
 
 ```ts
-const users = bento.namespace('users')
+router.get('/transfer', () => {
+  const fromAccount = getAccountFromDb(request.input('from'))
+  const toAccount = getAccountFromDb(request.input('to'))
 
-users.set('32', { name: 'foo' })
-users.set('33', { name: 'bar' })
-
-users.clear() 
-```
+  fromAccount.balance -= request.input('amount')
+  toAccount.balance += request.input('amount')
 
-### Events
-
-Events are emitted by Bentocache throughout its execution, allowing you to collect metrics and monitor your cache.
-
-```ts
-bento.on('cache:hit', () => {})
-bento.on('cache:miss', () => {})
-// ...
-```
-
-See the [events documentation](./digging_deeper/events.md) for more information.
-
-### Friendly TTLs
-
-All TTLs can be passed in a human-readable string format. We use [lukeed/ms](https://github.com/lukeed/ms) under the hood. (this is optional, and you can pass a `number` in milliseconds if you prefer)
-
-```ts
-bento.getOrSet('foo', () => getFromDb(), {
-  ttl: '2.5h',
-  gracePeriod: { enabled: true, duration: '6h' }
+  await fromAccount.save()
+  await toAccount.save()
 })
 ```
 
-### Early refresh
+Okay cool. It works when we are trying it locally. But imagine something. What if two users are calling the same endpoint at the same time ? What will happen ?
 
-When you cached item will expire soon, you can refresh it in advance, in the background. This way, next time the entry is requested, it will already be computed and thus returned to the user super quickly.
+1. User A's request reads the balance of Account X.
+2. Concurrently, User B's request also reads the balance of Account X.
+3. User A's request deducts the transfer amount from Account X and saves it.
+4. Almost simultaneously, User B's request does the same, but it was unaware of the change made by User A's request because it read the old balance.
 
-```ts
-bento.getOrSet('foo', () => getFromDb(), {
-  earlyExpiration: 0.8
-})
-```
-
-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.
-- Start a background refresh by calling the factory.
-- Next time the entry is requested, it will be already computed, and can be returned immediately.
-
-### Logging
+As a result, Account X's balance end up totally incorrect. This is a classic example of what we call race condition. 
 
-You can pass a logger to Bentocache, and it will log everything that happens. Can be useful for debugging or monitoring.
+They are multiple ways to solve this problem. A simple one would be to use a lock. By adding a lock, we are preventing concurrent requests from accessing the same piece of code at the same time :
 
 ```ts
-import { pino } from 'pino'
-
-const bento = new BentoCache({
-  logger: pino()
+router.get('/transfer', () => {
+  // Other requests will wait just here until the lock is released
+  await verrou.createLock('transfer').run(async () => {
+    const fromAccount = getAccountFromDb(request.input('from'))
+    const toAccount = getAccountFromDb(request.input('to'))
+
+    fromAccount.balance -= request.input('amount')
+    toAccount.balance += request.input('amount')
+
+    await fromAccount.save()
+    await toAccount.save()
+  }) // Lock is automatically released after the callback is executed
 })
 ```
 
-See the [logging documentation](./digging_deeper/logging.md) for more information.
+Now, if two users are calling the same endpoint at the same time, the second one will have to wait for the first one to finish before being able to execute the code. This way, we are sure that the balance will be correct.
 
 ## Sponsor
 
 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
-- https://laravel.com/docs/10.x/cache
-- https://github.com/TurnerSoftware/CacheTower
-- https://github.com/dotnetcore/EasyCaching
-- https://symfony.com/doc/current/components/cache.html