feat!: rename tryAcquire to acquireImmediately + add runImmediately method

Author: Julien-R44

docs/content/docs/api.md

@@ -43,23 +43,34 @@ Acquire the lock, run the callback, and release the lock.
 
 ```ts
 const lock = verrou.createLock('key')
-await lock.run({ retry: { timeout: '1000ms' } }, async () => {
+await lock.run(() => {
+  // do something
+})
+```
+
+### `runImmediately`
+
+Same as `run`, but try to acquire the lock immediately ( without retrying ). If the lock is already acquired, it will throws a `E_LOCK_ALREADY_ACQUIRED` error.
+
+```ts
+const lock = verrou.createLock('key')
+await lock.runImmediately(async () => {
   // do something
 })
 ```
 
 Accept an optional object with the same properties as `acquire`.
 
-### `tryAcquire`
+### `acquireImmediately`
 
-Try to acquire the lock immediately. If the lock is already acquired, it will throws a `E_LOCK_ALREADY_ACQUIRED` error.
+Try to acquire the lock immediately ( without retrying ). 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()
+  await lock.acquireImmediately()
 } catch (err) {
   if (err instanceof E_LOCK_ALREADY_ACQUIRED) {
 

packages/verrou/src/lock.ts

@@ -108,12 +108,12 @@ export class Lock {
   /**
    * Try to acquire the lock immediately or throw an error
    */
-  async tryAcquire() {
+  async acquireImmediately() {
     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
 
-    this.#config.logger.debug({ key: this.#key }, 'Lock acquired with tryAcquire()')
+    this.#config.logger.debug({ key: this.#key }, 'Lock acquired with acquireImmediately()')
   }
 
   /**
@@ -130,6 +130,19 @@ export class Lock {
     }
   }
 
+  /**
+   * Same as `run` but try to acquire the lock immediately
+   * Or throw an error if the lock is already acquired
+   */
+  async runImmediately<T>(callback: () => Promise<T>): Promise<T> {
+    try {
+      await this.acquireImmediately()
+      return await callback()
+    } finally {
+      await this.release()
+    }
+  }
+
   /**
    * Force release the lock
    */

packages/verrou/tests/lock.spec.ts

@@ -335,20 +335,20 @@ test.group('Lock', () => {
     assert.isAbove(elapsed, 500)
   })
 
-  test('tryAcquire works', async ({ assert }) => {
+  test('acquireImmediately 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()
+    await lock.acquireImmediately()
 
     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 }) => {
+  test('acquireImmediately throws timeout error when lock is not available', async ({ assert }) => {
     class FakeStore extends NullStore {
       async save(_key: string) {
         return false
@@ -358,6 +358,32 @@ test.group('Lock', () => {
     const lock = new Lock('foo', new FakeStore(), defaultOptions)
 
     // @ts-ignore
-    await assert.rejects(() => lock.tryAcquire(), E_LOCK_ALREADY_ACQUIRED.message)
+    await assert.rejects(() => lock.acquireImmediately(), E_LOCK_ALREADY_ACQUIRED.message)
+  })
+
+  test('runImmediately should acquire and release lock', async ({ assert }) => {
+    assert.plan(3)
+
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, defaultOptions)
+
+    assert.deepEqual(await lock.isLocked(), false)
+
+    await lock.runImmediately(async () => {
+      assert.deepEqual(await lock.isLocked(), true)
+    })
+
+    assert.deepEqual(await lock.isLocked(), false)
+  })
+
+  test('runImmediately throws if lock is not available', async ({ assert }) => {
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, defaultOptions)
+    const lock2 = new Lock('foo', store, defaultOptions)
+
+    await lock2.acquire()
+
+    // @ts-expect-error
+    await assert.rejects(() => lock.acquireImmediately(), E_LOCK_ALREADY_ACQUIRED.message)
   })
 })