Skip to content

Commit

Permalink
docs: fix LockFactory instructions
Browse files Browse the repository at this point in the history
Fix #7
  • Loading branch information
Julien-R44 committed Apr 27, 2024
1 parent 4c3ca28 commit fbb5e60
Show file tree
Hide file tree
Showing 4 changed files with 67 additions and 62 deletions.
14 changes: 8 additions & 6 deletions docs/content/docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,6 @@ const [executed, result] = await lock.run(() => {
})
```


### `runImmediately`

Same as `run`, but try to acquire the lock immediately ( without retrying ).
Expand Down Expand Up @@ -157,7 +156,9 @@ await lock.forceRelease()
Create a lock.

```ts
const lockFactory = new LockFactory(redisStore())
import { RedisStore } from '@verrou/core/drivers/redis'

const lockFactory = new LockFactory(new RedisStore())
const lock1 = lockFactory.createLock('key')
const lock2 = lockFactory.createLock('key', '5m')
const lock3 = lockFactory.createLock('key', 30_000)
Expand All @@ -170,14 +171,16 @@ First argument is the lock key. Second argument is optional and is the lock expi
Restore a lock. Useful when sharing a lock between multiple processes. See [Sharing a lock between multiple processes](./usage.md#sharing-a-lock-between-multiple-processes) for more details.

```ts
const lockFactory = new LockFactory(redisStore())
import { RedisStore } from '@verrou/core/drivers/redis'

const lockFactory = new LockFactory(new RedisStore())
const lock1 = lockFactory.createLock('key', 'owner')
const lock2 = lockFactory.restoreLock(lock1.serialize())
```

## Verrou API

Verrou API is a wrapper around the LockFactory API.
Verrou API is a wrapper around the LockFactory API.

```ts
const verrou = new Verrou({
Expand All @@ -191,7 +194,7 @@ const verrou = new Verrou({
})
```

Every method available on the `LockFactory` class is available on the `Verrou` class, and will be called on the default store.
Every method available on the `LockFactory` class is available on the `Verrou` class, and will be called on the default store.

If you need to use a different store, you can use the `use` method.

Expand All @@ -210,4 +213,3 @@ As explained above, the `use` method allows you to use a different store than th
```ts
verrou.use('myMemoryStore').createLock('key')
```

33 changes: 17 additions & 16 deletions docs/content/docs/digging_deeper/logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,25 +10,25 @@ Your logger must comply with the following interface:

```ts
export interface Logger {
trace(msg: string | LogObject): void;
trace(obj: LogObject, msg: string): void;
trace(msg: string | LogObject): void
trace(obj: LogObject, msg: string): void

debug(msg: string | LogObject): void;
debug(obj: LogObject, msg: string): void;
debug(msg: string | LogObject): void
debug(obj: LogObject, msg: string): void

info(msg: string | LogObject): void;
info(obj: LogObject, msg: string): void;
info(msg: string | LogObject): void
info(obj: LogObject, msg: string): void

warn(msg: string): void;
warn(obj: LogObject, msg: string): void;
warn(msg: string): void
warn(obj: LogObject, msg: string): void

error(msg: string): void;
error(obj: ErrorObject, msg: string): void;
error(msg: string): void
error(obj: ErrorObject, msg: string): void

fatal(msg: string): void;
fatal(obj: ErrorObject, msg: string): void;
fatal(msg: string): void
fatal(obj: ErrorObject, msg: string): void

child(childObj: LogObject): Logger;
child(childObj: LogObject): Logger
}
```

Expand All @@ -41,7 +41,7 @@ import { pino } from 'pino'

const logger = pino({
level: 'trace',
transport: { target: 'pino-pretty' }
transport: { target: 'pino-pretty' },
})

const verrou = new Verrou({
Expand All @@ -57,11 +57,12 @@ If using the `LockFactory` API, you can also do the same :
```ts
import { pino } from 'pino'
import { LockFactory } from '@verrou/core'
import { MemoryStore } from '@verrou/core/drivers/memory'

const logger = pino({
level: 'trace',
transport: { target: 'pino-pretty' }
transport: { target: 'pino-pretty' },
})

const lockFactory = new LockFactory(memoryStore(), { logger })
const lockFactory = new LockFactory(new MemoryStore(), { logger })
```
70 changes: 36 additions & 34 deletions docs/content/docs/drivers.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Verrou supports multiple drivers to store the locks. No matter which driver you
You will need to install `ioredis` to use this driver.

The Redis driver can be used with many different providers:

- Upstash
- Vercel KV
- DragonFly
Expand All @@ -31,19 +32,19 @@ const verrou = new Verrou({
default: 'redis',
drivers: {
redis: {
driver: redisStore({ connection: redis })
driver: redisStore({ connection: redis }),
},
}
},
})
```

```ts
// title: LockFactory API
import { Verrou, LockFactory } from '@verrou/core'
import { redisStore } from '@verrou/core/drivers/redis'
import { RedisStore } from '@verrou/core/drivers/redis'

const redis = new Redis({ host: 'localhost', port: 6379 })
const store = redisStore({ connection: redis })
const store = new RedisStore({ connection: redis })

const lockFactory = new LockFactory(store)
```
Expand All @@ -52,17 +53,17 @@ const lockFactory = new LockFactory(store)

### Options

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

### Implementation details

Note that the Redis store does **not** use the redlock algorithm. It uses a simple `setnx` as described in the [Redis documentation](https://redis.io/commands/set/). We may introduce a redlock strategy in the future.

## Memory

The memory store is a simple in-memory store, so don't use it in a multi-server environment.
The memory store is a simple in-memory store, so don't use it in a multi-server environment.

Use [async-mutex](https://www.npmjs.com/package/async-mutex) under the hood.

Expand All @@ -77,16 +78,16 @@ const verrou = new Verrou({
default: 'memory',
drivers: {
memory: { driver: memoryStore() },
}
},
})
```

```ts
// title: LockFactory API
import { Verrou, LockFactory } from '@verrou/core'
import { memoryStore } from '@verrou/core/drivers/memory'
import { MemoryStore } from '@verrou/core/drivers/memory'

const store = memoryStore()
const store = new MemoryStore()
const lockFactory = new LockFactory(store)
```

Expand All @@ -113,40 +114,40 @@ const verrou = new Verrou({
connection: dynamoClient,
// Name of the table where the locks will be stored
table: { name: 'locks' },
})
}
}
}),
},
},
})
```

```ts
// title: LockFactory API
import { Verrou, LockFactory } from '@verrou/core'
import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
import { dynamodbStore } from '@verrou/core/drivers/dynamodb'
import { DynamoDBStore } from '@verrou/core/drivers/dynamodb'

const dynamoClient = new DynamoDBClient(/* ... */)
const store = dynamodbStore({
const store = new DynamoDBStore({
connection: dynamoClient,
// Name of the table where the locks will be stored
table: {
name: 'locks'
name: 'locks',
},
})

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.

### Options

| Option | Description | Default |
| --- | --- | --- |
| 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 |
| `connection` | An instance of `DynamoDBClient` | N/A |

## Databases

Expand All @@ -160,10 +161,10 @@ Note that you can easily create your own adapter by implementing the `DatabaseAd

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` |
| 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` |

### Knex

Expand All @@ -182,19 +183,20 @@ const db = knex({ client: 'mysql2', connection: MYSQL_CREDENTIALS })
const verrou = new Verrou({
default: 'sqlite',
stores: {
sqlite: { driver: knexStore({ connection: db }) }
}
sqlite: { driver: knexStore({ connection: db }) },
},
})
```

```ts
// title: LockFactory API
import knex from 'knex'
import { Verrou, LockFactory } from '@verrou/core'
import { knexStore } from '@verrou/core/drivers/knex'
import { KnexAdapter } from '@verrou/core/drivers/knex'
import { DatabaseStore } from '@verrou/core/drivers/database'

const db = knex({ client: 'mysql2', connection: MYSQL_CREDENTIALS })
const store = knexStore({ dialect: 'sqlite', connection: db })
const store = new DatabaseStore(new KnexAdapter(db))
const lockFactory = new LockFactory(store)
```

Expand All @@ -204,7 +206,6 @@ const lockFactory = new LockFactory(store)

You must provide a Kysely instance to use the Kysely driver. Feel free to check the [Kysely documentation](https://kysely.dev/) for more details about the configuration. Kysely support the following databases : SQLite, MySQL, PostgreSQL and MSSQL.


:::codegroup

```ts
Expand All @@ -218,19 +219,20 @@ const db = new Kysely<Database>({ dialect })
const verrou = new Verrou({
default: 'kysely',
stores: {
kysely: { driver: kyselyStore({ connection: db }) }
}
kysely: { driver: kyselyStore({ connection: db }) },
},
})
```

```ts
// title: LockFactory API
import { Kysely } from 'kysely'
import { Verrou, LockFactory } from '@verrou/core'
import { kyselyStore } from '@verrou/core/drivers/kysely'
import { KyselyAdapter } from '@verrou/core/drivers/kysely'
import { DatabaseStore } from '@verrou/core/drivers/database'

const db = new Kysely<Database>({ dialect })
const store = kyselyStore({ connection: db })
const store = new DatabaseStore(new KyselyAdapter(db))
const lockFactory = new LockFactory(store)
```

Expand Down
12 changes: 6 additions & 6 deletions docs/content/docs/quick_setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ You can install Verrou via your favorite package manager.
Verrou is an ESM-only package. You will also need Node.js 18 or higher.
:::


:::codegroup

```sh
// title: npm
npm i @verrou/core
Expand All @@ -26,8 +26,8 @@ pnpm add @verrou/core
// title: yarn
yarn add @verrou/core
```
:::

:::

## Setup

Expand All @@ -46,8 +46,8 @@ const verrou = new Verrou({
default: 'redis',
stores: {
redis: { driver: redisStore() },
memory: { driver: memoryStore() }
}
memory: { driver: memoryStore() },
},
})
```

Expand All @@ -61,9 +61,9 @@ Alternatively, if having to keep a global variable is a hassle for you, you can

```ts
import { LockFactory } from '@verrou/core'
import { redisStore } from '@verrou/core/drivers/redis'
import { RedisStore } from '@verrou/core/drivers/redis'

const lockFactory = new LockFactory(redisStore())
const lockFactory = new LockFactory(new RedisStore())
await lockFactory.createLock('foo').run(async () => {
// do something
})
Expand Down

0 comments on commit fbb5e60

Please sign in to comment.