cachette 3.0.1 → 4.0.1

package/test/RedisCache_test.ts

@@ -0,0 +1,303 @@
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+
+import { RedisCache, SIZE_THRESHOLD_WARNING_BYTES } from '../src/lib/RedisCache';
+
+
+describe('RedisCache', () => {
+
+  describe('constructor', () => {
+    it('will not crash the application given an invalid Redis URL', async () => {
+      let cache = new RedisCache('redis://localhost:9999');
+      await cache.getValue('test');
+      await cache.setValue('test', 'value');
+      cache = new RedisCache('rediss://localhost:9999');
+      await cache.getValue('test');
+      await cache.setValue('test', 'value');
+    });
+
+    it('will raise an error if given a Redis URL without protocol', async () => {
+      expect(
+        () => new RedisCache('rer17kq3qdwc5wmy.4gzf3f.ng.0001.use1.cache.amazonaws.com'),
+      ).to.throw();
+    });
+
+    it('will raise an error if given a Redis URL with an invalid protocol', async () => {
+      expect(
+        () => new RedisCache('potato://rer17kq3qdwc5wmy.4gzf3f.ng.0001.use1.cache.amazonaws.com'),
+      ).to.throw();
+    });
+  });
+
+  describe('value serialization', () => {
+
+    it('can serialize the null value', () => {
+      let value = RedisCache.serializeValue(null);
+      expect(value).to.equal(RedisCache.NULL_VALUE);
+      value = RedisCache.deserializeValue(value);
+      expect(value).to.equal(null);
+    });
+
+    it('can serialize the true value', () => {
+      let value = RedisCache.serializeValue(true);
+      expect(value).to.equal(RedisCache.TRUE_VALUE);
+      value = RedisCache.deserializeValue(value);
+      expect(value).to.equal(true);
+    });
+
+    it('can serialize an object', () => {
+      const obj = {
+        level1: {
+          level2: {
+            level3: true,
+          },
+        },
+      };
+      let value = RedisCache.serializeValue(obj);
+      expect(value.startsWith(RedisCache.JSON_PREFIX)).to.be.true;
+      value = RedisCache.deserializeValue(value);
+      expect(value).to.deep.equal(obj);
+    });
+  
+    it('can serialize an object with a nested map', () => {
+      const mapStructure: Map<string, {
+        checksum: number;
+        originCommentId?: string;
+      }> = new Map();
+      mapStructure.set('key1', { checksum: 1, originCommentId: 'c1' });
+      mapStructure.set('key2', { checksum: 2, originCommentId: 'c2' });
+      const obj = {
+        level1: {
+          level2: {
+            level3: {
+              l3Map: mapStructure,
+              l3Bool: true,
+            },
+            l2Map: mapStructure,
+          },
+          l1Map: mapStructure,
+        },
+      };
+      let value = RedisCache.serializeValue(obj);
+      expect(value.startsWith(RedisCache.JSON_PREFIX)).to.be.true;
+      value = RedisCache.deserializeValue(value);
+      expect(value).to.deep.equal(obj);
+    });
+  
+    it('can serialize an object with a nested set', () => {
+      const setStructure: Set<string> = new Set();
+      setStructure.add('key1');
+      setStructure.add('key2');
+      const obj = {
+        level1: {
+          level2: {
+            level3: {
+              l3Set: setStructure,
+              l3Bool: false,
+            },
+            l2Set: setStructure,
+          },
+          l1Set: setStructure,
+        },
+      };
+      let value = RedisCache.serializeValue(obj);
+      expect(value.startsWith(RedisCache.JSON_PREFIX)).to.be.true;
+      value = RedisCache.deserializeValue(value);
+      expect(value).to.deep.equal(obj);
+    });
+
+    it('can serialize the false value', () => {
+      let value = RedisCache.serializeValue(false);
+      expect(value).to.equal(RedisCache.FALSE_VALUE);
+      value = RedisCache.deserializeValue(value);
+      expect(value).to.equal(false);
+    });
+
+    it('will leave a string untouched', () => {
+      let value = RedisCache.serializeValue('string');
+      expect(value).to.equal('string');
+      value = RedisCache.deserializeValue('string');
+      expect(value).to.equal('string');
+    });
+
+    it('will convert null to undefined when deserializing', () => {
+      const value = RedisCache.deserializeValue(null);
+      expect(value).to.equal(undefined);
+    });
+
+  });
+
+  describe('setValue', async () => {
+    it('can set values', async function (): Promise<void> {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+
+      const cache = new RedisCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+
+      // Just to be sure that the cache is really empty...
+      await cache.clear();
+
+      const wasSet = await cache.setValue('key', 'value');
+      expect(wasSet).to.be.true;
+      expect(await cache.itemCount()).to.equal(1);
+      const value = await cache.getValue('key');
+      expect(value).to.equal('value');
+      expect(await cache.itemCount()).to.equal(1);
+    });
+
+    it('can set/get numbers', async function (): Promise<void> {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+
+      const cache = new RedisCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+      await cache.clear();
+
+      await cache.setValue('numZero', 0);
+      expect(await cache.getValue('numZero')).to.equal(0);
+
+      await cache.setValue('numFloat', 123.456);
+      expect(await cache.getValue('numFloat')).to.equal(123.456);
+
+      await cache.setValue('numNegative', -99);
+      expect(await cache.getValue('numNegative')).to.equal(-99);
+
+      await cache.setValue('numMax', Number.MAX_SAFE_INTEGER);
+      expect(await cache.getValue('numMax')).to.equal(Number.MAX_SAFE_INTEGER);
+
+      await cache.setValue('numInfinity', Infinity);
+      expect(await cache.getValue('numInfinity')).to.equal(Infinity);
+
+      await cache.setValue('numBarf', 0.1 + 0.2); // 0.30000000000000004, IEEE754
+      expect(await cache.getValue('numBarf')).to.equal(0.1 + 0.2);
+    });
+
+    it('can set values with a TTL', async function (): Promise<void> {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+
+      const cache = new RedisCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+
+      // Just to be sure that the cache is really empty...
+      await cache.clear();
+
+      const wasSet = await cache.setValue('key', 'value', 30000);
+      expect(wasSet).to.be.true;
+
+      const value = await cache.getValue('key');
+      expect(value).to.equal('value');
+
+      expect(await cache.itemCount()).to.equal(1);
+
+      const ttl = await cache.getTtl('key');
+      expect(ttl).to.exist;
+      expect(ttl).to.be.above(0);
+      expect(ttl).to.not.be.above(30000000);
+    });
+
+    it('can set a boolean value', async function (): Promise<void> {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+
+      const cache = new RedisCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+
+      // Just to be sure that the cache is really empty...
+      await cache.clear();
+
+      let wasSet = await cache.setValue('key', true);
+      expect(wasSet).to.be.true;
+      let value = await cache.getValue('key');
+      expect(value).to.be.true;
+
+      wasSet = await cache.setValue('key', false);
+      expect(wasSet).to.be.true;
+      value = await cache.getValue('key');
+      expect(value).to.be.false;
+
+      expect(await cache.itemCount()).to.equal(1);
+    });
+
+    it('emits a warning when setting a large-enough value', async function () {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+
+      const cache = new RedisCache(process.env.TEST_REDIS_URL as string);
+      const warnSpy = sinon.spy();
+      cache.on('warn', warnSpy);
+      await cache.isReady();
+
+      const key = `emits-warning-on-large-value-${Math.random()}`;
+      await cache.setValue(key, 'a'.repeat(SIZE_THRESHOLD_WARNING_BYTES));
+
+      const warningsAfterSetLargeKey = warnSpy.getCalls().map(c => c.firstArg).filter(msg => msg.includes('Writing large value to Redis!'));
+      expect(warningsAfterSetLargeKey.length).to.equal(1);
+    });
+
+    it('does NOT emit a warning when setting a small-enough value', async function () {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+
+      const cache = new RedisCache(process.env.TEST_REDIS_URL as string);
+      const warnSpy = sinon.spy();
+      cache.on('warn', warnSpy);
+      await cache.isReady();
+
+      const key = `doesnt-emit-warning-on-small-value-${Math.random()}`;
+      await cache.setValue(key, 'a'.repeat(SIZE_THRESHOLD_WARNING_BYTES - 1));
+
+      const warningsAfterSetLargeKey = warnSpy.getCalls().map(c => c.firstArg).filter(msg => msg.includes('Writing large value to Redis!'));
+      expect(warningsAfterSetLargeKey.length).to.equal(0);
+    });
+  });
+
+  describe('itemCount', async () => {
+
+    it('can count the items in the redis cache.', async function (): Promise<void> {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+
+      const cache = new RedisCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+
+      // Just to be sure that the cache is really empty...
+      await cache.clear();
+
+      await cache.setValue('test1', 'value1');
+      await cache.setValue('test2', 'value2');
+      await cache.setValue('test3', 'value3');
+      expect(await cache.itemCount()).to.equal(3);
+      await cache.clear();
+      expect(await cache.itemCount()).to.equal(0);
+    });
+  });
+
+  describe('waitForReplication', () => {
+    it('wait for replication', async function (): Promise<void> {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+
+      const cache = new RedisCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+
+      await cache.clear();
+
+      await cache.setValue('test1', 'value1');
+      
+      const replicationAcknowledged = await cache.waitForReplication(0, 50);
+
+      // No replicas so we expect 0. This test basically confirms that waitForReplication doesn't crash. 🤷‍♂️
+      expect(replicationAcknowledged).to.equal(0);
+    });
+  });
+});

package/test/WriteThroughCache_test.ts

@@ -0,0 +1,306 @@
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+
+import { WriteThroughCache, LocalCache } from '../src/';
+
+function makeFakeWriteThroughCache(): WriteThroughCache {
+  const cache = new WriteThroughCache('redis://localhost:9999');
+  cache['redisCacheForWriting'] = new LocalCache();
+  cache['redisCacheForWriting'].getTtl = async () => 1;
+  cache['redisCacheForReading'] = cache['redisCacheForWriting'];
+  return cache;
+}
+
+
+describe('WriteThroughCache', () => {
+
+  it('will fallback to using a local cache is no connection to redis is made', async () => {
+
+    const cache = new WriteThroughCache('redis://localhost:9999');
+
+    // We know the connection was not made, but we should still be able to use the local cache.
+    await cache.setValue('key', 'value');
+    const value = await cache.getValue('key');
+    expect(value).to.equal('value');
+
+  });
+
+  describe('setValue', () => {
+
+    it('will write the value in both caches', async () => {
+
+      const cache = makeFakeWriteThroughCache();
+
+      const response = await cache.setValue('key', 'value');
+      expect(response).to.be.true;
+
+      let value = await cache.getValue('key');
+      expect(value).to.equal('value');
+
+      value = await cache['localCache'].getValue('key');
+      expect(value).to.equal('value');
+
+      value = await cache['redisCacheForReading'].getValue('key');
+      expect(value).to.equal('value');
+
+    });
+
+  });
+
+  describe('getValue', () => {
+
+    it('will populate the local cache with right ttl when fetching from redis', async function (): Promise<void> {
+
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+      const cache = new WriteThroughCache(process.env.TEST_REDIS_URL as string);
+      const spy = sinon.spy(cache['localCache'], 'setValue');
+
+      // await for Redis connection to be up
+      await cache.isReady();
+
+      await cache['redisCacheForWriting'].setValue('key', 'value', 100);
+
+      let value = await cache.getValue('key');
+      expect(value).to.equal('value');
+      sinon.assert.calledWith(spy, 'key', 'value', sinon.match(ttl => ttl > 99.9 && ttl <= 100));
+
+      value = await cache['localCache'].getValue('key');
+      expect(value).to.equal('value');
+
+    });
+
+    it('will get directly from the local cache if available', async () => {
+
+      const cache = makeFakeWriteThroughCache();
+
+      await cache['localCache'].setValue('key', 'value');
+
+      let value = await cache.getValue('key');
+      expect(value).to.equal('value');
+
+      value = await cache['redisCacheForReading'].getValue('key');
+      expect(value).not.to.exist;
+
+    });
+
+    it('will populate the local cache for a null value', async () => {
+
+      const cache = makeFakeWriteThroughCache();
+
+      await cache['redisCacheForWriting'].setValue('key', null);
+
+      let value = await cache.getValue('key');
+      expect(value).to.equal(null);
+
+      value = await cache['localCache'].getValue('key');
+      expect(value).to.equal(null);
+
+    });
+
+    it('will populate the local cache for an empty string', async () => {
+
+      const cache = makeFakeWriteThroughCache();
+
+      await cache['redisCacheForWriting'].setValue('key', '');
+
+      let value = await cache.getValue('key');
+      expect(value).to.equal('');
+
+      value = await cache['localCache'].getValue('key');
+      expect(value).to.equal('');
+
+    });
+
+    it('returns nothing if value in cache has expired', async function (): Promise<void> {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+      const cache = new WriteThroughCache(process.env.TEST_REDIS_URL as string);
+      await cache.setValue('fakeKey', 'fakeValue', 0.1);
+      // sleep 100 ms
+      await new Promise(resolve => setTimeout(resolve, 150));
+      const fakeValue = await cache.getValue('fakeKey');
+      expect(fakeValue).to.be.undefined;
+    });
+
+  });
+
+  describe('delValue', () => {
+
+    it('will delete values from both caches', async () => {
+
+      const cache = makeFakeWriteThroughCache();
+
+      await cache.setValue('key', 'value');
+
+      let value = await cache.getValue('key');
+      expect(value).to.equal('value');
+
+      value = await cache['localCache'].getValue('key');
+      expect(value).to.equal('value');
+
+      await cache.delValue('key');
+
+      value = await cache.getValue('key');
+      expect(value).not.to.exist;
+
+      value = await cache['localCache'].getValue('key');
+      expect(value).not.to.exist;
+
+    });
+
+  });
+
+  describe('clear', () => {
+
+    it('clears from both caches', async () => {
+      const cache = makeFakeWriteThroughCache();
+
+      const base = [...Array(10).keys()];
+      await Promise.all(base.map(i => cache.setValue(`key${i}`, i)));
+      expect(await cache.itemCount()).to.equal(20);
+
+      let values = await Promise.all(base.map(i => cache.getValue(`key${i}`)));
+      expect(values.sort()).to.eql(base);
+
+      await cache.clear();
+      expect(await cache.itemCount()).to.equal(0);
+
+      values = await Promise.all(base.map(i => cache.getValue(`key${i}`)));
+      values.forEach(value => expect(value).to.be.undefined);
+    });
+
+  });
+
+  describe('metrics', () => {
+    let sinonClock: sinon.SinonFakeTimers;
+
+    beforeEach(async () => {
+      sinonClock = sinon.useFakeTimers({
+        now: 0,
+        toFake: ['setInterval'],
+      });
+    });
+
+    afterEach(() => {
+      delete process.env.CACHETTE_METRICS_PERIOD_MINUTES;
+      sinonClock.restore();
+    })
+
+    it('stores metrics if env. var is set', async function () {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+      process.env.CACHETTE_METRICS_PERIOD_MINUTES = '1';
+      const cache = new WriteThroughCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+      expect(cache['metrics'].enabled).to.be.true;
+      const key = `key-metrics-${Math.random()}`;
+
+      // Getting bogus value to test doubleMisses
+      await cache.getValue(`non-existing-value-${Math.random()}`);
+      expect(cache['metrics'].localHits).to.equal(0);
+      expect(cache['metrics'].redisHits).to.equal(0);
+      expect(cache['metrics'].doubleMisses).to.equal(1);
+
+      // Setting in *Local* + *Redis* caches to test localHits
+      await cache.setValue(key, 'val');
+      await cache.getValue(key);
+      expect(cache['metrics'].localHits).to.equal(1);
+      expect(cache['metrics'].redisHits).to.equal(0);
+      expect(cache['metrics'].doubleMisses).to.equal(1);
+
+      // Evicting from private *Local* cache to test redisHits
+      await cache['localCache'].delValue(key);
+      await cache.getValue(key);
+      expect(cache['metrics'].localHits).to.equal(1);
+      expect(cache['metrics'].redisHits).to.equal(1);
+      expect(cache['metrics'].doubleMisses).to.equal(1);
+    });
+
+    it('does not store metrics by default', async function () {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+      // *Not* setting process.env.CACHETTE_METRICS_PERIOD_MINUTES
+      const cache = new WriteThroughCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+      const key = `key-metrics-${Math.random()}`;
+
+      // Causing activity that would have caused { localHits, redisHits, doubleMisses }
+      await cache.getValue(`non-existing-value-${Math.random()}`);
+      await cache.setValue(key, 'val');
+      await cache.getValue(key);
+      await cache['localCache'].delValue(key);
+      await cache.getValue(key);
+      expect(cache['metrics'].enabled).to.be.false;
+      expect(cache['metrics'].localHits).to.equal(0);
+      expect(cache['metrics'].redisHits).to.equal(0);
+      expect(cache['metrics'].doubleMisses).to.equal(0);
+    });
+
+    it('does not store metrics if env. var is invalid', async function () {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+      process.env.CACHETTE_METRICS_PERIOD_MINUTES = 'foo'; // invalid: not a positive integer
+      const cache = new WriteThroughCache(process.env.TEST_REDIS_URL as string);
+      await cache.isReady();
+      const key = `key-metrics-${Math.random()}`;
+
+      // Causing activity that would have caused { localHits, redisHits, doubleMisses }
+      await cache.getValue(`non-existing-value-${Math.random()}`);
+      await cache.setValue(key, 'val');
+      await cache.getValue(key);
+      await cache['localCache'].delValue(key);
+      await cache.getValue(key);
+      expect(cache['metrics'].enabled).to.be.false;
+      expect(cache['metrics'].localHits).to.equal(0);
+      expect(cache['metrics'].redisHits).to.equal(0);
+      expect(cache['metrics'].doubleMisses).to.equal(0);
+    });
+
+    it('emits metrics periodically', async function () {
+      if (!process.env.TEST_REDIS_URL) {
+        this.skip();
+      }
+
+      process.env.CACHETTE_METRICS_PERIOD_MINUTES = '1';
+      const cache = new WriteThroughCache(process.env.TEST_REDIS_URL as string);
+      const infoSpy = sinon.spy();
+      cache.on('info', infoSpy);
+      await cache.isReady();
+
+      // Causing 1 localHit, 1 redisHit, 1 doubleMiss
+      const key = `key-metrics-${Math.random()}`;
+      await cache.getValue(`non-existing-value-${Math.random()}`);
+      await cache.setValue(key, 'val');
+      await cache.getValue(key);
+      await cache['localCache'].delValue(key);
+      await cache.getValue(key);
+
+      // Testing we emitted at requested period
+      const metricsReports0 = infoSpy.getCalls().map(c => c.firstArg).filter(msg => msg.includes('metrics'));
+      expect(metricsReports0.length).to.equal(0);
+
+      sinonClock.tick(59999); // t = 1min minus a millisecond
+      const metricsReports59s = infoSpy.getCalls().map(c => c.firstArg).filter(msg => msg.includes('metrics'));
+      expect(metricsReports59s.length).to.equal(0);
+
+      sinonClock.tick(2); // t = 1min plus a millisecond
+      const metricsReports61s = infoSpy.getCalls().map(c => c.firstArg).filter(msg => msg.includes('metrics'));
+      expect(metricsReports61s.length).to.equal(1);
+      expect(metricsReports61s[0]).to.equal('WriteThroughCache metrics during last 1 min - Total: 3, Local hits: 1 (33%), Redis hits: 1 (33%), Double misses: 1 (33%).')
+
+      // Causing no activity for a minute and testing we emit again
+      sinonClock.tick(60000); // t = 2min plus a millisecond
+      const metricsReports121s = infoSpy.getCalls().map(c => c.firstArg).filter(msg => msg.includes('metrics'));
+      expect(metricsReports121s.length).to.equal(2);
+      expect(metricsReports121s[1]).to.equal('WriteThroughCache metrics during last 1 min - Total: 0, Local hits: 0 (0%), Redis hits: 0 (0%), Double misses: 0 (0%).')
+    });
+
+  });
+
+});

package/test/mocharc-ci.js

@@ -0,0 +1,12 @@
+'use strict';
+
+// https://mochajs.org/#configuring-mocha-nodejs
+// https://mochajs.org/#configuration-format
+// eslint-disable-next-line no-undef
+module.exports = {
+  require: ['source-map-support/register'],
+  recursive: true,
+  exit: true,
+  timeout: 60000,
+  'no-colors': true,
+};

package/test/mocharc.js

@@ -0,0 +1,10 @@
+'use strict';
+
+// https://mochajs.org/#configuring-mocha-nodejs
+// https://mochajs.org/#configuration-format
+// eslint-disable-next-line no-undef
+module.exports = {
+  require: ['source-map-support/register'],
+  recursive: true,
+  exit: true,
+};

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "declaration": true,
+    "experimentalDecorators": true,
+    "incremental": true,
+    "lib": ["ES2023"],
+    "listFiles": false,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "noUnusedLocals": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "sourceMap": true,
+    "strictNullChecks": true,
+    "target": "ES2022"
+  },
+  "include": [
+    "src/**/*",
+    "test/**/*"
+  ]
+}