Skip to content

Commit

Permalink
fix(docs): a couple of things (#8)
Browse files Browse the repository at this point in the history
* fix a couple of things

- fix Verrou options (rename `drivers` to `stores`)
- fix url of `implementing DatabaseAdapter` on Driver page
- reformat tables
- small typos left and right

* remove extra space
  • Loading branch information
TiBianMod authored May 26, 2024
1 parent 542f6ab commit 258963c
Show file tree
Hide file tree
Showing 5 changed files with 17 additions and 17 deletions.
2 changes: 1 addition & 1 deletion docs/content/docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Accept an optional object with the following properties:

- `retry`: An object with the following properties:
- `timeout`: The maximum time to wait for the lock to be acquired. Defaults to `Infinity`.
- `delay`: The delay in miliseconds between each retry. Defaults to `250`
- `delay`: The delay in milliseconds between each retry. Defaults to `250`
- `attempts`: The maximum number of attempts to acquire the lock.

`acquire` will return a boolean indicating if the lock was acquired or not
Expand Down
14 changes: 7 additions & 7 deletions docs/content/docs/drivers.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ import { redisStore } from '@verrou/core/drivers/redis'
const redis = new Redis({ host: 'localhost', port: 6379 })
const verrou = new Verrou({
default: 'redis',
drivers: {
stores: {
redis: {
driver: redisStore({ connection: redis }),
},
Expand All @@ -54,7 +54,7 @@ const lockFactory = new LockFactory(store)
### Options

| Option | Description | Default |
| ------------ | ------------------------ | ------- |
|--------------|--------------------------|---------|
| `connection` | An instance of `ioredis` | N/A |

### Implementation details
Expand All @@ -76,7 +76,7 @@ import { memoryStore } from '@verrou/core/drivers/memory'

const verrou = new Verrou({
default: 'memory',
drivers: {
stores: {
memory: { driver: memoryStore() },
},
})
Expand Down Expand Up @@ -140,12 +140,12 @@ const lockFactory = new LockFactory(store)

:::

The DynamoDB table will be automatically created if it does not exists. Otherwise, you can create it manually and specify the name of the table in the options.
The DynamoDB table will be automatically created if it does not exist. Otherwise, you can create it manually and specify the name of the table in the options.

### Options

| Option | Description | Default |
| ------------ | ----------------------------------------------------------- | ------- |
|--------------|-------------------------------------------------------------|---------|
| `table.name` | The name of the table that will be used to store the cache. | `cache` |
| `connection` | An instance of `DynamoDBClient` | N/A |

Expand All @@ -155,14 +155,14 @@ We offer several drivers to use a database as the locks store. The database stor

:::note

Note that you can easily create your own adapter by implementing the `DatabaseAdapter` interface if you are using another library not supported by Verrou. See the [documentation](/docs/advanced/custom-adapters) 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 Verrou. See the [documentation](/docs/custom-lock-store#create-an-adapter-for-the-databasestore) for more details.

:::

All Database drivers accept the following common options:

| Option | Description | Default |
| ----------------- | ------------------------------------------------------------------ | -------- |
|-------------------|--------------------------------------------------------------------|----------|
| `tableName` | The name of the table that will be used to store the locks. | `verrou` |
| `autoCreateTable` | If the table should be automatically created if it does not exist. | `true` |

Expand Down
2 changes: 1 addition & 1 deletion docs/content/docs/extend/custom_lock_store.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ interface LockStore {

Feel free to take a look at [the existing drivers](https://github.com/Julien-R44/verrou/tree/develop/src/drivers) implementations for inspiration.

Once you defined you driver, you can create a factory function that will be used by Verrou 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 Verrou to create instances of your driver at runtime. The factory function must be something like this:

```ts
import type { CreateDriverResult } from '@verrou/core/types'
Expand Down
8 changes: 4 additions & 4 deletions docs/content/docs/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ import { memoryStore } from '@verrou/core/drivers/memory'

const verrou = new Verrou({
default: 'redis',
drivers: {
stores: {
redis: { driver: redisStore() },
memory: { driver: memoryStore() }
}
Expand Down Expand Up @@ -62,7 +62,7 @@ await lock.run(async () => {

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).

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.
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 different APIs and behaviors.

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.

Expand All @@ -73,7 +73,7 @@ Well, locks is a very common pattern in software development. It is used to prev
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
router.get('/transfer', () => {
router.get('/transfer', async () => {
const fromAccount = getAccountFromDb(request.input('from'))
const toAccount = getAccountFromDb(request.input('to'))

Expand Down Expand Up @@ -108,7 +108,7 @@ As a result, we lost 100$ somewhere. And that's not good. This is what we also c
They are multiple ways to solve this problem. But let's use a lock here. By adding a lock, we are preventing concurrent requests from accessing the same piece of code at the same time :

```ts
router.get('/transfer', () => {
router.get('/transfer', async () => {
// Other requests will wait just here until the lock is released
await verrou.createLock('transfer').run(async () => {
const fromAccount = getAccountFromDb(request.input('from'))
Expand Down
8 changes: 4 additions & 4 deletions docs/content/docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import { verrou } from './verrou.js'
const lock = verrou.createLock('my-resource', '1s')
```

The first argument is the resource/key to lock. This is an arbitrary string that will be used to identify the lock. The second argument is the duration of the lock. It can be a number of milliseconds, a string like `1s` or `1m` ( see [lukeed/ms documentation](https://github.com/lukeed/ms), or even `null` if you want to create a lock that never expires.
The first argument is the resource/key to lock. This is an arbitrary string that will be used to identify the lock. The second argument is the duration of the lock. It can be a number of milliseconds, a string like `1s` or `1m` (see [lukeed/ms documentation](https://github.com/lukeed/ms)), or even `null` if you want to create a lock that never expires.

Note that the duration you are passing is the duration of the lease. This means that the lock will be automatically released after this duration. This is safe to always pass a duration, even if you are releasing the lock manually afterwards ( see below ). Having a duration will prevent the lock from being stuck forever if the process crashes before releasing it ( We call this a **Deadlock** ).

Expand Down Expand Up @@ -47,7 +47,7 @@ if (await lock.acquire()) {
}
```

But we are still missing error handling. What if my `doSomething` method throws an error? The lock will never be released. To prevent this, always make sure to wrap your code with a try/catch/finaly block.
But we are still missing error handling. What if my `doSomething` method throws an error? The lock will never be released. To prevent this, always make sure to wrap your code with a try/catch/finally block.

```ts
import { verrou } from './verrou.js'
Expand Down Expand Up @@ -177,12 +177,12 @@ import { verrou } from './verrou.js'

myQueue.on('process-payment', async ({ paymentId, lock }) => {
// First we **restore** the lock with the lock owner
const lock = verrou.restoreLock(lock)
const restoredLock = verrou.restoreLock(lock)

processPayment(paymentId)

// Then we can release it
await lock.release()
await restoredLock.release()
})
```

Expand Down

0 comments on commit 258963c

Please sign in to comment.