cachette 4.0.22 → 4.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cachette",
-  "version": "4.0.22",
+  "version": "4.0.24",
   "engines": {
     "node": ">=20",
     "npm": ">=10"

package/test/RedisCache_test.ts

@@ -300,4 +300,110 @@ describe('RedisCache', () => {
       expect(replicationAcknowledged).to.equal(0);
     });
   });
+
+  describe('lock', () => {
+    let cache: RedisCache;
+
+    beforeEach(async function () {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+      cache = new RedisCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+      await cache.clear();
+    });
+
+    afterEach(async function () {
+      if (cache) {
+        await cache.quit();
+      }
+    });
+
+    it('returns a Lock object with value property and unlock method', async () => {
+      const lock = await cache.lock('test-resource', 10000);
+
+      expect(lock).to.have.property('value');
+      expect(lock.value).to.be.a('string');
+      expect(lock.value!.length).to.be.greaterThan(0);
+
+      expect(lock).to.have.property('unlock');
+      expect(lock.unlock).to.be.a('function');
+
+      await cache.unlock(lock);
+    });
+
+    it('releases lock via the returned Lock object unlock method', async () => {
+      const resource = `test-resource-${Math.random()}`;
+
+      const lock = await cache.lock(resource, 10000);
+      expect(await cache.hasLock(resource)).to.be.true;
+
+      await lock.unlock();
+      expect(await cache.hasLock(resource)).to.be.false;
+    });
+
+    it('releases lock via cache.unlock()', async () => {
+      const resource = `test-resource-${Math.random()}`;
+
+      const lock = await cache.lock(resource, 10000);
+      expect(await cache.hasLock(resource)).to.be.true;
+
+      await cache.unlock(lock);
+      expect(await cache.hasLock(resource)).to.be.false;
+    });
+
+    it('with retry = true, waits for lock to become available', async () => {
+      const resource = `test-resource-${Math.random()}`;
+
+      // Acquire first lock with short TTL — intentionally let it expire
+      void (await cache.lock(resource, 100));
+
+      // Second lock should wait and succeed after first expires
+      const startTime = Date.now();
+      const secondLock = await cache.lock(resource, 10000, true);
+      const elapsed = Date.now() - startTime;
+
+      expect(elapsed).to.be.greaterThanOrEqual(50); // waited for first lock to expire
+      expect(secondLock).to.have.property('value');
+      expect(secondLock.value).to.be.a('string');
+
+      await cache.unlock(secondLock);
+    });
+
+    it('with retry = false, throws immediately if lock is held', async () => {
+      const resource = `test-resource-${Math.random()}`;
+
+      const firstLock = await cache.lock(resource, 10000);
+      expect(await cache.hasLock(resource)).to.be.true;
+
+      let error: Error | undefined;
+      try {
+        await cache.lock(resource, 10000, false);
+      } catch (err) {
+        error = err as Error;
+      }
+
+      expect(error).to.exist;
+      expect(error!.message).to.include('lock');
+
+      await cache.unlock(firstLock);
+    });
+
+    it('only releases its own lock (fencing token safety)', async () => {
+      const resource = `test-resource-${Math.random()}`;
+
+      // Acquire a lock, then let it expire
+      void (await cache.lock(resource, 50, false));
+      await new Promise((resolve) => setTimeout(resolve, 60));
+
+      // Acquire a new lock on the same resource (different owner)
+      const secondLock = await cache.lock(resource, 10000, false);
+      expect(await cache.hasLock(resource)).to.be.true;
+
+      // The second lock should still be held — unlocking the first (expired) lock
+      // should not have affected it. Verify the second lock can be unlocked normally.
+      await cache.unlock(secondLock);
+      expect(await cache.hasLock(resource)).to.be.false;
+    });
+  });
 });