doc: update doc accordingly

Author: Julien-R44

docs/content/docs/api.md

@@ -14,18 +14,38 @@ Acquire the lock. If the lock is already acquired, it will wait until it is rele
 
 ```ts
 const lock = verrou.createLock('key', '10s')
-await lock.acquire()
-await lock.acquire({ retry: { timeout: 1000 } })
-await lock.acquire({ retry: { timeout: '1s' } })
+const acquired = await lock.acquire()
+const acquired = await lock.acquire({ retry: { timeout: 1000 } })
+const acquired = await lock.acquire({ retry: { timeout: '1s' } })
+
+if (acquired) {
+  await criticalSection()
+}
 ```
 
 Accept an optional object with the following properties:
 
 - `retry`: An object with the following properties:
-  - `timeout`: The maximum time to wait for the lock to be acquired. If the timeout is reached, an `E_LOCK_TIMEOUT` error will be thrown. Defaults to `Infinity`.
+  - `timeout`: The maximum time to wait for the lock to be acquired. Defaults to `Infinity`.
   - `delay`: The delay in miliseconds between each retry. Defaults to `250`
   - `attempts`: The maximum number of attempts to acquire the lock.
 
+`acquire` will return a boolean indicating if the lock was acquired or not
+
+### `acquireImmediately`
+
+Try to acquire the lock immediately ( without retrying ). If the lock is already acquired, it will return `false` immediately.
+
+```ts
+import { errors } from '@verrou/core'
+
+const lock = verrou.createLock('key')
+const acquired = await lock.acquireImmediately()
+if (acquired) {
+  await criticalSection()
+}
+```
+
 ### `release`
 
 Release the lock. Note that only the lock owner can release the lock.
@@ -39,45 +59,31 @@ await lock.release()
 
 ### `run`
 
-Acquire the lock, run the callback, and release the lock.
+Acquire the lock, run the callback, and release the lock. The method will return a tuple with the first value being a boolean indicating if the lock was acquired or not, and the second value being the result of the callback.
 
 ```ts
 const lock = verrou.createLock('key')
-await lock.run(() => {
+const [executed, result] = await lock.run(() => {
   // do something
+  return 'result'
 })
 ```
 
+
 ### `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.
+Same as `run`, but try to acquire the lock immediately ( without retrying ).
 
 ```ts
 const lock = verrou.createLock('key')
-await lock.runImmediately(async () => {
+const [executed, result] = await lock.runImmediately(async () => {
   // do something
+  return 'result'
 })
 ```
 
 Accept an optional object with the same properties as `acquire`.
 
-### `acquireImmediately`
-
-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.acquireImmediately()
-} catch (err) {
-  if (err instanceof E_LOCK_ALREADY_ACQUIRED) {
-
-  }
-}
-```
-
 ### `isLocked`
 
 Check if the lock is acquired.

docs/content/docs/introduction.md

@@ -36,16 +36,13 @@ const verrou = new Verrou({
 
 ```ts
 // title: Manual lock
-import { Verrou, E_LOCK_TIMEOUT } from '@verrou/core'
+import { Verrou } from '@verrou/core'
 
 const lock = verrou.createLock('my-resource')
+const acquired = await lock.acquire()
+
 try {
-  await lock.acquire()
   await doSomething()
-} catch (error) {
-  if (error instanceof E_LOCK_TIMEOUT) {
-    // handle timeout
-  }
 } finally {
   await lock.release()
 }

docs/content/docs/usage.md

@@ -38,13 +38,13 @@ import { verrou } from './verrou.js'
 const lock = verrou.createLock('my-resource', null)
 
 // We gonna wait for the lock to be acquired
-await lock.acquire()
-
-// Do your critical code here
-doSomething()
+if (await lock.acquire()) {  
+  // Do your critical code here
+  doSomething()
 
-// Once you are done, release the lock.
-await lock.release()
+  // Once you are done, release the lock.
+  await lock.release()
+}
 ```
 
 But we are still missing error handling. What if my `doSomething` method throws an error? The lock will never be released. To prevent this, always make sure to wrap your code with a try/catch/finaly block.
@@ -53,10 +53,10 @@ But we are still missing error handling. What if my `doSomething` method throws
 import { verrou } from './verrou.js'
 
 const lock = verrou.createLock('my-resource', null)
+const acquired = await lock.acquire()
+if (!acquired) return 'Lock not acquired'
 
 try {
-  await lock.acquire()
-
   // Do your critical code here
   doSomething()
 } catch (error) {
@@ -115,29 +115,27 @@ await lock.acquire({
 
 In general, you will either use the `retry.attempts` or `retry.timeout` options.
 
-### Handling errors
+### Handling lock acquisition failure
 
-If ever you can't acquire a lock, an error will be thrown. You can catch it and handle it like this : 
+If ever you can't acquire a lock, `acquire` and `acquireImmediately` will return `false`. You can check if the lock was acquired by checking this value.
 
 ```ts
 import { errors } from '@verrou/core'
 
-try {
-  await lock.acquire()
-} catch (error) {
-  if (error instanceof errors.E_LOCK_TIMEOUT) {
-    // Handle the error
-  }
+const acquired = await lock.acquire()
+if (!acquired) {
+  return 'Lock not acquired'
 }
+```
 
-await lock.run(async () => {
-  // Do your critical code here
-  doSomething()
-}).catch(error => {
-  if (error instanceof errors.E_LOCK_TIMEOUT) {
-    // Handle the error
-  }
+`run` and `runImmediately` methods will return a tuple with the first value being a boolean indicating if the lock was acquired or not.
+
+```ts
+const [acquired, result] = await lock.run(async () => {
+  return doSomething()
 })
+
+if (!acquired) return 'Lock not acquired'
 ```
 
 ### Sharing a lock between multiple processes