feat: add isExpired and getRemainingTime methods

Author: Julien-R44

docs/content/docs/api.md

@@ -76,7 +76,7 @@ Check if the lock is expired.
 
 ```ts
 const lock = verrou.createLock('key', '10s')
-const isExpired = await lock.isExpired()
+const isExpired = lock.isExpired()
 ```
 
 ### `extend`
@@ -104,7 +104,7 @@ Get the remaining time before the lock expires.
 const lock = verrou.createLock('key', '10s')
 await lock.acquire()
 
-const remainingTime = await lock.getRemainingTime()
+const remainingTime = lock.getRemainingTime()
 ```
 
 ### `forceRelease`

packages/verrou/src/lock.ts

@@ -6,16 +6,26 @@ import { resolveDuration } from './helpers.js'
 import type { Duration, LockAcquireOptions, LockFactoryConfig, LockStore } from './types/main.js'
 
 export class Lock {
+  #key: string
   #owner: string
+  #lockStore: LockStore
+  #ttl: number | null = null
+  #config: LockFactoryConfig
+  #expirationTime: number | null = null
 
   constructor(
-    protected readonly key: string,
-    protected readonly lockStore: LockStore,
-    protected config: LockFactoryConfig,
+    key: string,
+    lockStore: LockStore,
+    config: LockFactoryConfig,
     owner?: string,
-    protected ttl?: number | null,
+    ttl?: number | null,
   ) {
+    this.#key = key
+    this.#config = config
+    this.#lockStore = lockStore
+    this.#expirationTime = null
     this.#owner = owner ?? this.#generateOwner()
+    this.#ttl = ttl ?? null
   }
 
   /**
@@ -36,26 +46,32 @@ export class Lock {
    * Acquire the lock
    */
   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
+      options?.retry?.attempts ?? this.#config.retry.attempts ?? Number.POSITIVE_INFINITY
 
     while (attemptsDone++ < attemptsMax) {
-      const result = await this.lockStore.save(this.key, this.#owner, this.ttl)
-      if (result) break
+      const now = Date.now()
+      const result = await this.#lockStore.save(this.#key, this.#owner, this.#ttl)
+      if (result) {
+        this.#expirationTime = this.#ttl ? now + this.#ttl : null
+        break
+      }
 
       if (attemptsDone === attemptsMax) throw new E_LOCK_TIMEOUT()
 
       const elapsed = Date.now() - start
-      if (this.config.retry.timeout && elapsed > this.config.retry.timeout) {
+      if (this.#config.retry.timeout && elapsed > this.#config.retry.timeout) {
         throw new E_LOCK_TIMEOUT()
       }
 
-      await setTimeout(this.config.retry.delay ?? 250)
+      await setTimeout(this.#config.retry.delay ?? 250)
     }
 
-    this.config.logger.debug({ key: this.key }, 'Lock acquired')
+    this.#config.logger.debug({ key: this.#key }, 'Lock acquired')
   }
 
   /**
@@ -76,37 +92,48 @@ export class Lock {
    * Force release the lock
    */
   async forceRelease() {
-    await this.lockStore.forceRelease(this.key)
+    await this.#lockStore.forceRelease(this.#key)
   }
 
   /**
    * Release the lock
    */
   async release() {
-    await this.lockStore.delete(this.key, this.#owner)
+    await this.#lockStore.delete(this.#key, this.#owner)
   }
 
   /**
    * Returns true if the lock is expired
    */
-  async isExpired() {
-    return false
+  isExpired() {
+    if (this.#expirationTime === null) return false
+    return this.#expirationTime < Date.now()
+  }
+
+  /**
+   * Get the remaining time before the lock expires
+   */
+  getRemainingTime() {
+    if (this.#expirationTime === null) return null
+    return this.#expirationTime - Date.now()
   }
 
   /**
    * Extends the lock TTL
    */
   async extend(ttl?: Duration) {
-    const resolvedTtl = ttl ? resolveDuration(ttl) : this.ttl
+    const resolvedTtl = ttl ? resolveDuration(ttl) : this.#ttl
     if (!resolvedTtl) throw new InvalidArgumentsException('Cannot extend a lock without TTL')
 
-    await this.lockStore.extend(this.key, this.#owner, resolvedTtl)
+    const now = Date.now()
+    await this.#lockStore.extend(this.#key, this.#owner, resolvedTtl)
+    this.#expirationTime = now + resolvedTtl
   }
 
   /**
    * Returns true if the lock is currently locked
    */
   async isLocked() {
-    return await this.lockStore.exists(this.key)
+    return await this.#lockStore.exists(this.#key)
   }
 }

packages/verrou/tests/lock.spec.ts

@@ -1,5 +1,6 @@
 import { test } from '@japa/runner'
 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'
@@ -156,4 +157,117 @@ test.group('Lock', () => {
     const lock = new Lock('foo', new FakeStore(), { retry: {}, logger: noopLogger() }, 'bar', 1000)
     await lock.extend('2s')
   })
+
+  test('isExpired is false when lock has no expiration time', async ({ assert }) => {
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, { retry: {}, logger: noopLogger() })
+
+    assert.deepEqual(lock.isExpired(), false)
+
+    await lock.acquire()
+
+    assert.deepEqual(lock.isExpired(), false)
+  })
+
+  test('isExpired is true when lock has expired', async ({ assert }) => {
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, { retry: {}, logger: noopLogger() }, undefined, 100)
+
+    assert.deepEqual(lock.isExpired(), false)
+
+    await lock.acquire()
+
+    assert.deepEqual(lock.isExpired(), false)
+    await setTimeout(200)
+    assert.deepEqual(lock.isExpired(), true)
+  })
+
+  test('isExpired is extended when extending the lock', async ({ assert }) => {
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, { retry: {}, logger: noopLogger() }, undefined, 100)
+
+    assert.deepEqual(lock.isExpired(), false)
+
+    await lock.acquire()
+
+    assert.deepEqual(lock.isExpired(), false)
+    await lock.extend(200)
+    await setTimeout(100)
+    assert.deepEqual(lock.isExpired(), false)
+    await setTimeout(200)
+    assert.deepEqual(lock.isExpired(), true)
+  })
+
+  test('getRemainingTime returns null when lock has no expiration time', async ({ assert }) => {
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, { retry: {}, logger: noopLogger() })
+
+    assert.deepEqual(lock.getRemainingTime(), null)
+
+    await lock.acquire()
+
+    assert.deepEqual(lock.getRemainingTime(), null)
+  })
+
+  test('getRemainingTime returns remaining time when lock has expiration time', async ({
+    assert,
+  }) => {
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, { retry: {}, logger: noopLogger() }, undefined, 100)
+
+    assert.deepEqual(lock.getRemainingTime(), null)
+
+    await lock.acquire()
+
+    assert.closeTo(lock.getRemainingTime()!, 100, 10)
+    await setTimeout(200)
+    assert.closeTo(lock.getRemainingTime()!, -100, 10)
+  })
+
+  test('getRemainingTime is extended when extending the lock', async ({ assert }) => {
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, { retry: {}, logger: noopLogger() }, undefined, 100)
+
+    assert.deepEqual(lock.getRemainingTime(), null)
+
+    await lock.acquire()
+
+    assert.closeTo(lock.getRemainingTime()!, 100, 10)
+    await lock.extend(200)
+    assert.closeTo(lock.getRemainingTime()!, 200, 10)
+  })
+
+  test('getRemainingTime doesnt get extended when extend fails', async ({ assert }) => {
+    class FakeStore extends NullStore {
+      async extend() {
+        throw new Error('foo')
+      }
+    }
+
+    const store = new FakeStore()
+    const lock = new Lock('foo', store, { retry: {}, logger: noopLogger() }, undefined, 100)
+
+    assert.deepEqual(lock.getRemainingTime(), null)
+
+    await lock.acquire()
+
+    assert.closeTo(lock.getRemainingTime()!, 100, 10)
+    await assert.rejects(() => lock.extend(200))
+    assert.closeTo(lock.getRemainingTime()!, 100, 10)
+  })
+
+  test('expiration time is null when lock is not acquired', async ({ assert }) => {
+    const store = new MemoryStore()
+    const lock = new Lock('foo', store, { retry: { attempts: 1 }, logger: noopLogger() })
+    const lock2 = new Lock('foo', store, { retry: {}, logger: noopLogger() }, undefined, 1000)
+
+    assert.deepEqual(lock.getRemainingTime(), null)
+
+    await lock2.acquire()
+    assert.closeTo(lock2.getRemainingTime()!, 1000, 10)
+
+    await lock.acquire().catch(() => {})
+    assert.deepEqual(lock.getRemainingTime(), null)
+    assert.closeTo(lock2.getRemainingTime()!, 1000, 200)
+  })
 })