Verrou Locking Library

Verrou is a locking library for Node.js designed to provide a consistent API across different storage backends. It allows you to manage distributed locks using various drivers such as Redis, Postgres, MySQL, Sqlite, or In-Memory.

A key advantage is the ability to switch drivers (e.g., using Redis in production and an In-Memory driver for fast, infrastructure-free testing) without changing your application logic.

// See Basic usage for a concrete example
```ts
import { Verrou } from '@verrou/core'
import { redisStore } from '@verrou/core/drivers/redis'
import { memoryStore } from '@verrou/core/drivers/memory'

const verrou = new Verrou({
  default: 'redis',
  stores: {
    redis: { driver: redisStore() },
    memory: { driver: memoryStore() }
  }
})

// Lock a resource and run a function
await verrou.createLock('my-resource').run(async () => {
  await doSomething()
}) // Lock is automatically released

By default, only the specific Lock instance that acquired a lock can release it. Attempting to release a lock from a different instance will throw an E_LOCK_NOT_OWNER error.

To release a lock from a different process (e.g., a worker process receiving a task from a queue), you must:

1. Serialize the lock in the original process using lock.serialize().
2. Restore the lock in the new process using verrou.restoreLock(serializedLock).

Alternatively, you can use lock.forceRelease() to release a lock regardless of who owns it.

// Process A: Serialize and send
const lock = verrou.createLock('my-resource', '2s')
await lock.acquire()
const serialized = lock.serialize()
// ... send 'serialized' to another process via queue/API ...

// Process B: Restore and release
import { verrou } from './verrou.js'
const restoredLock = verrou.restoreLock(serialized)
await restoredLock.release()

Verrou supports using relational databases as lock stores via adapters. It provides built-in support for Knex and Kysely. These drivers work by attempting to insert a row and relying on primary key constraints to detect existing locks.

Common Options for all Database drivers:

• tableName: The name of the table used to store locks (Default: verrou).
• autoCreateTable: Whether to automatically create the table if it doesn't exist (Default: true).

Custom Adapters: You can implement the DatabaseAdapter interface to support other database libraries.

// Knex Example
import knex from 'knex'
import { Verrou } from '@verrou/core'
import { knexStore } from '@verrou/core/drivers/knex'

const db = knex({ client: 'mysql2', connection: MYSQL_CREDENTIALS })
const verrou = new Verrou({
  default: 'sqlite',
  stores: {
    sqlite: { driver: knexStore({ connection: db }) },
  },
})

// Kysely Example
import { Kysely } from 'kysely'
import { Verrou } from '@verrou/core'
import { kyselyStore } from '@verrou/core/drivers/kysely'

const db = new Kysely<Database>({ dialect })
const verrou = new Verrou({
  default: 'kysely',
  stores: {
    kysely: { driver: kyselyStore({ connection: db }) },
  },
})

The DynamoDB driver allows you to store locks in an AWS DynamoDB table. The table will be automatically created if it does not exist.

Prerequisites: Install @aws-sdk/client-dynamodb.

// Verrou API
import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
import { dynamodbStore } from '@verrou/core/drivers/dynamodb'

const dynamoClient = new DynamoDBClient(/* ... */)
const verrou = new Verrou({
  default: 'dynamo',
  stores: {
    dynamo: {
      driver: dynamodbStore({
        connection: dynamoClient,
        table: { name: 'locks' },
      }),
    },
  },
})

// LockFactory API
import { Verrou, LockFactory } from '@verrou/core'
import { DynamoDBStore } from '@verrou/core/drivers/dynamodb'

const dynamoClient = new DynamoDBClient(/* ... */)
const store = new DynamoDBStore({
  connection: dynamoClient,
  table: {
    name: 'locks',
  },
})

const lockFactory = new LockFactory(store)

To extend Verrou with a custom cache driver, you must implement the LockStore interface from @verrou/core/types.

Once implemented, you must provide a factory function that follows the CreateDriverResult pattern. This factory is used by Verrou at runtime to instantiate your driver.

To use your new driver, register it in the stores object when initializing a new Verrou instance and set it as the default store.

import type { CreateDriverResult } from '@verrou/core/types'

// 1. Implement the LockStore interface
class MyDriver implements LockStore {
  async save(key: string, owner: string, ttl: number | undefined): Promise<boolean> { /* ... */ }
  async delete(key: string, owner: string): Promise<void> { /* ... */ }
  async exists(key: string): Promise<boolean> { /* ... */ }
  async extend(key: string, owner: string, duration: number): Promise<void> { /* ... */ }
}

// 2. Create the factory function
export function myStore(config: MyStoreOptions): CreateDriverResult<MyStoreOptions> {
  return { config, factory: () => new MyDriver(config) }
}

// 3. Register and use in Verrou
import { Verrou } from '@verrou/core'
import { myStore } from './my_store.js'

const verrou = new Verrou({
  default: 'myStore',
  stores: {
    myStore: myStore({ /* Your driver options */ })
  }
})