feat: support Duration values and lock.acquire options

Author: Julien-R44

packages/verrou/src/errors.ts

@@ -1,15 +1,24 @@
 import { createError } from '@poppinss/utils'
 
+/**
+ * Thrown when the lock is not acquired in the allotted time
+ */
 export const E_LOCK_TIMEOUT = createError(
   `Lock was not acquired in the allotted time`,
   'E_LOCK_TIMEOUT',
 )
 
+/**
+ * Thrown when user tries to update/release/extend a lock that is not acquired by them
+ */
 export const E_LOCK_NOT_OWNED = createError(
   'Looks like you are trying to update a lock that is not acquired by you',
   'E_LOCK_NOT_OWNED',
 )
 
+/**
+ * Thrown when the underlying store throws an error while saving/deleting/reading a lock
+ */
 export const E_LOCK_STORAGE_ERROR = createError<[{ message: string }]>(
   'Lock storage error: %s',
   'E_LOCK_STORAGE_ERROR',

packages/verrou/src/helpers.ts

@@ -3,18 +3,18 @@ import string from '@poppinss/utils/string'
 import type { Duration } from './types/main.js'
 
 /**
- * Resolve a TTL value to a number in milliseconds
+ * Resolve a Duration to a number in milliseconds
  */
-export function resolveDuration(ttl?: Duration, defaultTtl: Duration = 30_000) {
-  if (typeof ttl === 'number') return ttl
-  if (ttl === null) return undefined
+export function resolveDuration(duration?: Duration, defaultValue: Duration = 30_000) {
+  if (typeof duration === 'number') return duration
+  if (duration === null) return undefined
 
-  if (ttl === undefined) {
-    if (typeof defaultTtl === 'number') return defaultTtl
-    if (typeof defaultTtl === 'string') return string.milliseconds.parse(defaultTtl)
+  if (duration === undefined) {
+    if (typeof defaultValue === 'number') return defaultValue
+    if (typeof defaultValue === 'string') return string.milliseconds.parse(defaultValue)
 
     return undefined
   }
 
-  return string.milliseconds.parse(ttl)
+  return string.milliseconds.parse(duration)
 }

packages/verrou/src/lock.ts

@@ -6,7 +6,7 @@ import { resolveDuration } from './helpers.js'
 import type {
   Duration,
   LockAcquireOptions,
-  LockFactoryConfig,
+  ResolvedLockConfig,
   LockStore,
   SerializedLock,
 } from './types/main.js'
@@ -16,13 +16,13 @@ export class Lock {
   #owner: string
   #lockStore: LockStore
   #ttl: number | null = null
-  #config: LockFactoryConfig
+  #config: ResolvedLockConfig
   #expirationTime: number | null = null
 
   constructor(
     key: string,
     lockStore: LockStore,
-    config: LockFactoryConfig,
+    config: ResolvedLockConfig,
     owner?: string,
     ttl?: number | null,
     expirationTime?: number | null,
@@ -64,14 +64,15 @@ export class Lock {
   /**
    * Acquire the lock
    */
-  async acquire(options?: LockAcquireOptions) {
+  async acquire(options: LockAcquireOptions = {}) {
     this.#expirationTime = null
 
     let attemptsDone = 0
-    const start = Date.now()
-    const attemptsMax =
-      options?.retry?.attempts ?? this.#config.retry.attempts ?? Number.POSITIVE_INFINITY
+    const attemptsMax = options.retry?.attempts ?? this.#config.retry.attempts
+    const delay = resolveDuration(options.retry?.delay, this.#config.retry.delay)
+    const timeout = resolveDuration(options.retry?.timeout, this.#config.retry.timeout)
 
+    const start = Date.now()
     while (attemptsDone++ < attemptsMax) {
       const now = Date.now()
       const result = await this.#lockStore.save(this.#key, this.#owner, this.#ttl)
@@ -83,11 +84,9 @@ export class Lock {
       if (attemptsDone === attemptsMax) throw new E_LOCK_TIMEOUT()
 
       const elapsed = Date.now() - start
-      if (this.#config.retry.timeout && elapsed > this.#config.retry.timeout) {
-        throw new E_LOCK_TIMEOUT()
-      }
+      if (timeout && elapsed > timeout) throw new E_LOCK_TIMEOUT()
 
-      await setTimeout(this.#config.retry.delay ?? 250)
+      await setTimeout(delay)
     }
 
     this.#config.logger.debug({ key: this.#key }, 'Lock acquired')

packages/verrou/src/lock_factory.ts

@@ -4,38 +4,52 @@ import { Lock } from './lock.js'
 import { resolveDuration } from './helpers.js'
 import type {
   Duration,
-  LockFactoryConfig,
+  ResolvedLockConfig,
   LockFactoryOptions,
   LockStore,
   SerializedLock,
 } from './types/main.js'
 
 export class LockFactory {
   /**
-   * Default TTL for locks. 30 seconds.
+   * Default configuration values
    */
-  static #kDefaultTtl = 30_000
+  static #kDefaults = {
+    ttl: 30_000,
+    retry: {
+      attempts: Number.POSITIVE_INFINITY,
+      delay: 250,
+      timeout: undefined,
+    },
+  }
+
+  /**
+   * The store used to persist locks
+   */
+  #store: LockStore
 
   /**
    * Resolved LockFactory configuration
    */
-  #config: LockFactoryConfig
+  #config: ResolvedLockConfig
 
-  constructor(
-    protected readonly store: LockStore,
-    options: LockFactoryOptions = {},
-  ) {
+  constructor(store: LockStore, options: LockFactoryOptions = {}) {
+    this.#store = store
     this.#config = {
-      retry: { attempts: null, delay: 250, ...options.retry },
+      retry: {
+        attempts: options.retry?.attempts ?? LockFactory.#kDefaults.retry.attempts,
+        delay: resolveDuration(options.retry?.delay, null) ?? LockFactory.#kDefaults.retry.delay,
+        timeout: resolveDuration(options.retry?.timeout, null),
+      },
       logger: (options.logger ?? noopLogger()).child({ pkg: 'verrou' }),
     }
   }
 
   /**
    * Create a new lock
    */
-  createLock(name: string, ttl: Duration = LockFactory.#kDefaultTtl) {
-    return new Lock(name, this.store, this.#config, undefined, resolveDuration(ttl))
+  createLock(name: string, ttl: Duration = LockFactory.#kDefaults.ttl) {
+    return new Lock(name, this.#store, this.#config, undefined, resolveDuration(ttl))
   }
 
   /**
@@ -44,13 +58,13 @@ export class LockFactory {
    * that acquired it.
    */
   restoreLock(lock: SerializedLock) {
-    return new Lock(lock.key, this.store, this.#config, lock.owner, lock.ttl, lock.expirationTime)
+    return new Lock(lock.key, this.#store, this.#config, lock.owner, lock.ttl, lock.expirationTime)
   }
 
   /**
    * Disconnect the store ( if applicable )
    */
   disconnect() {
-    return this.store.disconnect()
+    return this.#store.disconnect()
   }
 }

packages/verrou/src/types/main.ts

@@ -11,11 +11,11 @@ export * from './drivers.js'
  * - Null to indicate no expiration
  */
 export type Duration = number | string | null
+export type StoreFactory = { driver: { factory: () => LockStore } }
 
-export type StoreFactory = {
-  driver: { factory: () => LockStore }
-}
-
+/**
+ * Shape of a lock serialized through the `Lock.serialize` method
+ */
 export interface SerializedLock {
   key: string
   owner: string
@@ -26,36 +26,51 @@ export interface SerializedLock {
 export interface RetryConfig {
   /**
    * The number of times to retry the operation before giving up.
-   * Null means retry indefinitely
    *
-   * @default null
+   * @default Number.POSITIVE_INFINITY
    */
-  attempts?: number | null
+  attempts?: number
 
   /**
    * The delay between retries
    *
    * @default 250ms
    */
-  delay?: number
+  delay?: Duration
 
   /**
    * The maximum amount of time before giving up to acquire the lock
+   * If not specified, the operation will retry indefinitely
+   *
+   * @default undefined ( no timeout )
    */
-  timeout?: number
+  timeout?: Duration
 }
 
+/**
+ * Options passed to the Lock.acquire method
+ */
 export interface LockAcquireOptions {
   retry?: RetryConfig
 }
 
+/**
+ * Options passed to the LockFactory constructor
+ */
 export interface LockFactoryOptions {
   retry?: RetryConfig
   logger?: Logger
 }
 
-export interface LockFactoryConfig {
-  retry: RetryConfig
+/**
+ * Resolved configuration values
+ */
+export interface ResolvedLockConfig {
+  retry: {
+    attempts: number
+    delay: number
+    timeout?: number
+  }
   logger: Logger
 }
 

packages/verrou/test_helpers/null_store.ts

@@ -1,5 +1,9 @@
 import type { LockStore } from '../src/types/main.js'
 
+/**
+ * A null store that does nothing
+ * Useful for testing and extending/overriding
+ */
 export class NullStore implements LockStore {
   async save(_key: string): Promise<boolean> {
     return true