feat: add a tryAcquire method

Author: Julien-R44

docs/content/docs/api.md

@@ -50,6 +50,23 @@ await lock.run({ retry: { timeout: '1000ms' } }, async () => {
 
 Accept an optional object with the same properties as `acquire`.
 
+### `tryAcquire`
+
+Try to acquire the lock immediately. If the lock is already acquired, it will throws a `E_LOCK_ALREADY_ACQUIRED` error.
+
+```ts
+import { errors } from '@verrou/core'
+
+const lock = verrou.createLock('key')
+try {
+  await lock.tryAcquire()
+} catch (err) {
+  if (err instanceof E_LOCK_ALREADY_ACQUIRED) {
+
+  }
+}
+```
+
 ### `isLocked`
 
 Check if the lock is acquired.

packages/verrou/src/errors.ts

@@ -23,3 +23,11 @@ export const E_LOCK_STORAGE_ERROR = createError<[{ message: string }]>(
   'Lock storage error: %s',
   'E_LOCK_STORAGE_ERROR',
 )
+
+/**
+ * Thrown when the lock is already acquired by someone else
+ */
+export const E_LOCK_ALREADY_ACQUIRED = createError(
+  'Lock is already acquired',
+  'E_LOCK_ALREDY_ACQUIRED',
+)

packages/verrou/src/lock.ts

@@ -1,8 +1,8 @@
 import { setTimeout } from 'node:timers/promises'
 import { InvalidArgumentsException } from '@poppinss/utils'
 
-import { E_LOCK_TIMEOUT } from './errors.js'
 import { resolveDuration } from './helpers.js'
+import { E_LOCK_ALREADY_ACQUIRED, E_LOCK_TIMEOUT } from './errors.js'
 import type {
   Duration,
   LockAcquireOptions,
@@ -105,6 +105,15 @@ export class Lock {
     this.#config.logger.debug({ key: this.#key }, 'Lock acquired')
   }
 
+  /**
+   * Try to acquire the lock immediately or throw an error
+   */
+  async tryAcquire() {
+    const result = await this.#lockStore.save(this.#key, this.#owner, this.#ttl)
+    if (!result) throw new E_LOCK_ALREADY_ACQUIRED()
+    this.#expirationTime = this.#ttl ? Date.now() + this.#ttl : null
+  }
+
   /**
    * Acquire the lock, run the callback and release the lock automatically
    * after the callback is done.

packages/verrou/tests/lock.spec.ts

@@ -3,9 +3,9 @@ import { noopLogger } from 'typescript-log'
 import { setTimeout } from 'node:timers/promises'
 
 import { Lock } from '../src/lock.js'
-import { E_LOCK_TIMEOUT } from '../src/errors.js'
 import { MemoryStore } from '../src/drivers/memory.js'
 import { NullStore } from '../test_helpers/null_store.js'
+import { E_LOCK_ALREADY_ACQUIRED, E_LOCK_TIMEOUT } from '../src/errors.js'
 
 const defaultOptions = {
   retry: {
@@ -334,4 +334,30 @@ test.group('Lock', () => {
     const elapsed = Date.now() - start
     assert.isAbove(elapsed, 500)
   })
+
+  test('tryAcquire works', async ({ assert }) => {
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, defaultOptions, undefined, 1000)
+
+    assert.deepEqual(await lock.isLocked(), false)
+
+    await lock.tryAcquire()
+
+    assert.deepEqual(await lock.isLocked(), true)
+    assert.deepEqual(lock.getRemainingTime(), 1000)
+    assert.deepEqual(lock.isExpired(), false)
+  })
+
+  test('tryAcquires throws timeout error when lock is not available', async ({ assert }) => {
+    class FakeStore extends NullStore {
+      async save(_key: string) {
+        return false
+      }
+    }
+
+    const lock = new Lock('foo', new FakeStore(), defaultOptions)
+
+    // @ts-ignore
+    await assert.rejects(() => lock.tryAcquire(), E_LOCK_ALREADY_ACQUIRED.message)
+  })
 })