limited-cache 1.1.1 → 2.1.0

package/src/__tests__/lowLevelFunctions.test.ts

@@ -0,0 +1,430 @@
+import { describe, beforeEach, expect, it, vitest } from 'vitest';
+import { defaultOptions } from '../core/defaultOptions';
+import {
+  isCacheMeta,
+  upgradeCacheMeta,
+  lowLevelInit,
+  lowLevelGetOne,
+  lowLevelGetAll,
+  lowLevelHas,
+  lowLevelSet,
+  lowLevelRemove,
+  lowLevelReset,
+} from '../core/lowLevelFunctions';
+import { LimitedCacheMeta } from '../types';
+
+describe('lowLevelFunctions', () => {
+  describe('isCacheMeta', () => {
+    it('accepts cacheMeta shapes', () => {
+      expect(
+        isCacheMeta({
+          limitedCacheMetaVersion: 123,
+          options: defaultOptions,
+          cache: {},
+          keyList: [],
+          keyInfo: {},
+          opsLeft: 100,
+        }),
+      ).toBe(true);
+    });
+    it('rejects invalid cacheMeta shapes', () => {
+      expect(
+        // @ts-expect-error Invalid cacheMeta shape
+        isCacheMeta({
+          cache: {},
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe('upgradeCacheMeta', () => {
+    it('warns and upgrades if given an older, incompatible cacheMeta', () => {
+      const consoleWarnSpy = vitest.spyOn(console, 'warn').mockReturnValueOnce();
+
+      const cacheMeta = lowLevelInit();
+      cacheMeta.limitedCacheMetaVersion = 1;
+      upgradeCacheMeta(cacheMeta);
+
+      expect(cacheMeta.limitedCacheMetaVersion).toEqual(2);
+
+      const consoleErrorCalls = consoleWarnSpy.mock.calls;
+      expect(consoleErrorCalls.length).toBe(1);
+    });
+
+    it('throws if given an invalid cacheMeta', () => {
+      expect(() => {
+        // @ts-expect-error Invalid cacheMeta shape
+        upgradeCacheMeta({
+          cache: {},
+        });
+      }).toThrowError();
+    });
+  });
+
+  describe('lowLevelInit', () => {
+    beforeEach(() => {
+      vitest.restoreAllMocks();
+    });
+
+    it('clones the default options', () => {
+      const myCacheMeta = lowLevelInit();
+
+      expect(myCacheMeta.options).toEqual(defaultOptions);
+      expect(myCacheMeta.options === defaultOptions).toBe(false);
+    });
+
+    it('clones provided options', () => {
+      const myOptions = {
+        maxCacheSize: 123,
+        maxCacheTime: 456,
+        warnIfItemPurgedBeforeTime: 999,
+        opLimit: 10,
+        scanLimit: 100,
+      };
+
+      const myCacheMeta = lowLevelInit(myOptions);
+
+      expect(myCacheMeta.options).toEqual(myOptions);
+      expect(myCacheMeta.options === myOptions).toBe(false);
+    });
+
+    it('merges provided options with defaults', () => {
+      const myOptions = {
+        maxCacheSize: 123,
+        maxCacheTime: 456,
+      };
+
+      const myCacheMeta = lowLevelInit(myOptions);
+
+      expect(myCacheMeta.options).toEqual({
+        maxCacheSize: 123,
+        maxCacheTime: 456,
+        warnIfItemPurgedBeforeTime: 5000,
+        opLimit: 200,
+        scanLimit: 50,
+      });
+    });
+
+    it('accepts an existing cacheMeta', () => {
+      const existingCacheMeta = lowLevelInit();
+      const myCacheMeta = lowLevelInit(existingCacheMeta);
+
+      expect(existingCacheMeta).toEqual(myCacheMeta);
+    });
+
+    it('warns and upgrades if given an older, incompatible cacheMeta', () => {
+      const consoleWarnSpy = vitest.spyOn(console, 'warn').mockReturnValueOnce();
+
+      const existingCacheMeta = lowLevelInit();
+      existingCacheMeta.limitedCacheMetaVersion = 1;
+      const myCacheMeta = lowLevelInit(existingCacheMeta);
+
+      expect(existingCacheMeta).toEqual(myCacheMeta);
+      expect(existingCacheMeta.limitedCacheMetaVersion).toEqual(2);
+
+      const consoleErrorCalls = consoleWarnSpy.mock.calls;
+      expect(consoleErrorCalls.length).toBe(1);
+    });
+  });
+
+  describe('lowLevelHas', () => {
+    let myCacheMeta: LimitedCacheMeta;
+    beforeEach(() => {
+      vitest.restoreAllMocks();
+      myCacheMeta = lowLevelInit({
+        maxCacheTime: 1000,
+      });
+    });
+
+    it('has a missing key', () => {
+      const result = lowLevelHas(myCacheMeta, 'abc');
+      expect(result).toBe(false);
+    });
+
+    it('has a present key', () => {
+      myCacheMeta.cache['abc'] = 123;
+      myCacheMeta.keyInfo['abc'] = [Date.now(), 0];
+
+      const result = lowLevelHas(myCacheMeta, 'abc');
+      expect(result).toBe(true);
+    });
+
+    it('has an expired key', () => {
+      myCacheMeta.cache['abc'] = 123;
+      myCacheMeta.keyInfo['abc'] = [1, 0];
+
+      const result = lowLevelHas(myCacheMeta, 'abc');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('lowLevelGetOne', () => {
+    let myCacheMeta: LimitedCacheMeta;
+    beforeEach(() => {
+      vitest.restoreAllMocks();
+      myCacheMeta = lowLevelInit({
+        maxCacheTime: 1000,
+      });
+    });
+
+    it('get a missing key', () => {
+      const result = lowLevelGetOne(myCacheMeta, 'abc');
+      expect(result).toBeUndefined();
+    });
+
+    it('get a present key', () => {
+      // Danger: Manually manipulating internals, because otherwise we can't test 'get' separately from 'set'
+      myCacheMeta.cache['abc'] = 123;
+      myCacheMeta.keyList = ['abc'];
+      myCacheMeta.keyInfo['abc'] = [Date.now(), 0];
+
+      const result = lowLevelGetOne(myCacheMeta, 'abc');
+      expect(result).toEqual(123);
+    });
+
+    it('get an expired key', () => {
+      // Danger: Manually manipulating internals, because otherwise we can't test 'get' separately from 'set'
+      myCacheMeta.cache['abc'] = 123;
+      myCacheMeta.keyList = ['abc'];
+      myCacheMeta.keyInfo['abc'] = [1, 0];
+
+      const result = lowLevelGetOne(myCacheMeta, 'abc');
+      expect(result).toEqual(undefined);
+    });
+  });
+
+  describe('lowLevelGetAll', () => {
+    let myCacheMeta: LimitedCacheMeta;
+    beforeEach(() => {
+      vitest.restoreAllMocks();
+      myCacheMeta = lowLevelInit({
+        maxCacheTime: 1000,
+      });
+    });
+
+    it('get all when empty', () => {
+      const result = lowLevelGetAll(myCacheMeta);
+      expect(result).toEqual({});
+    });
+
+    it('get all when not empty', () => {
+      // Danger: Manually manipulating internals, because otherwise we can't test 'get' separately from 'set'
+      myCacheMeta.cache['abc'] = 123;
+      myCacheMeta.cache['def'] = 456;
+      myCacheMeta.keyList = ['abc', 'def'];
+      myCacheMeta.keyInfo['abc'] = [Date.now(), 0];
+      myCacheMeta.keyInfo['def'] = [Date.now(), 0];
+
+      const result = lowLevelGetAll(myCacheMeta);
+      expect(result).toEqual({ abc: 123, def: 456 });
+    });
+
+    it('get all when all expired', () => {
+      // Danger: Manually manipulating internals, because otherwise we can't test 'get' separately from 'set'
+      myCacheMeta.cache['abc'] = 123;
+      myCacheMeta.cache['def'] = 456;
+      myCacheMeta.keyList = ['abc', 'def'];
+      myCacheMeta.keyInfo['abc'] = [1, 0];
+      myCacheMeta.keyInfo['def'] = [1, 0];
+
+      const result = lowLevelGetAll(myCacheMeta);
+      expect(result).toEqual({});
+    });
+
+    it('get all when some expired', () => {
+      // Danger: Manually manipulating internals, because otherwise we can't test 'get' separately from 'set'
+      myCacheMeta.cache['abc'] = 123;
+      myCacheMeta.cache['def'] = 456;
+      myCacheMeta.keyList = ['abc', 'def'];
+      myCacheMeta.keyInfo['abc'] = [1, 0];
+      myCacheMeta.keyInfo['def'] = [Date.now(), 0];
+
+      const result = lowLevelGetAll(myCacheMeta);
+      expect(result).toEqual({ def: 456 });
+    });
+  });
+
+  describe('lowLevelSet', () => {
+    let myCacheMeta: LimitedCacheMeta;
+    beforeEach(() => {
+      vitest.restoreAllMocks();
+      myCacheMeta = lowLevelInit({
+        maxCacheTime: 1000,
+      });
+    });
+
+    it('returns a mutated cacheMeta', () => {
+      const returnedCacheMeta = lowLevelSet(myCacheMeta, 'abc', 123);
+
+      expect(returnedCacheMeta).toStrictEqual(myCacheMeta);
+    });
+
+    it('set a new key', () => {
+      myCacheMeta = lowLevelSet(myCacheMeta, 'abc', 123);
+
+      expect(myCacheMeta.cache).toEqual({ abc: 123 });
+    });
+
+    it('set several new keys', () => {
+      myCacheMeta = lowLevelSet(myCacheMeta, 'abc', 123);
+      myCacheMeta = lowLevelSet(myCacheMeta, 'def', 456);
+
+      expect(myCacheMeta.cache).toEqual({ abc: 123, def: 456 });
+    });
+
+    it('overwrite a key', () => {
+      myCacheMeta = lowLevelSet(myCacheMeta, 'abc', 123);
+      myCacheMeta = lowLevelSet(myCacheMeta, 'abc', 456);
+
+      expect(myCacheMeta.cache).toEqual({ abc: 456 });
+    });
+
+    it('removes items to stay within the cache size', () => {
+      myCacheMeta = lowLevelInit({
+        maxCacheSize: 5,
+        maxCacheTime: 1000,
+        opLimit: Number.MAX_SAFE_INTEGER,
+        warnIfItemPurgedBeforeTime: 0,
+      });
+
+      // Set 5 items, then 5 more
+      for (let n = 1; n <= 5; n++) {
+        myCacheMeta = lowLevelSet(myCacheMeta, `n=${n}`, n);
+      }
+      expect(myCacheMeta.cache).toEqual({
+        'n=1': 1,
+        'n=2': 2,
+        'n=3': 3,
+        'n=4': 4,
+        'n=5': 5,
+      });
+
+      for (let n = 6; n <= 10; n++) {
+        myCacheMeta = lowLevelSet(myCacheMeta, `n=${n}`, n);
+      }
+
+      expect(myCacheMeta.cache).toEqual({
+        'n=1': undefined,
+        'n=2': undefined,
+        'n=3': undefined,
+        'n=4': undefined,
+        'n=5': undefined,
+        'n=6': 6,
+        'n=7': 7,
+        'n=8': 8,
+        'n=9': 9,
+        'n=10': 10,
+      });
+      // Double-check the keys, because jest can give false positives on the undefined ones above
+      expect(Object.keys(myCacheMeta.cache)).toEqual([
+        'n=1',
+        'n=2',
+        'n=3',
+        'n=4',
+        'n=5',
+        'n=6',
+        'n=7',
+        'n=8',
+        'n=9',
+        'n=10',
+      ]);
+
+      // And even though the cache hasn't been cleaned up yet, the keys should reflect the proper state
+      expect(lowLevelHas(myCacheMeta, 'n=1')).toEqual(false);
+      expect(lowLevelHas(myCacheMeta, 'n=5')).toEqual(false);
+      expect(lowLevelHas(myCacheMeta, 'n=8')).toEqual(true);
+      expect(lowLevelHas(myCacheMeta, 'n=10')).toEqual(true);
+    });
+
+    it('performs maintenance after many actions', () => {
+      myCacheMeta = lowLevelInit({
+        maxCacheSize: 10,
+        maxCacheTime: 1000,
+        opLimit: 1,
+      });
+
+      // Automaintenance should be done after 10 "set" actions (i.e., on the 11th)
+      for (let n = 1; n <= 10; n++) {
+        myCacheMeta = lowLevelSet(myCacheMeta, `n=${n}`, n);
+      }
+      for (let n = 2; n <= 9; n++) {
+        myCacheMeta = lowLevelRemove(myCacheMeta, `n=${n}`);
+      }
+      expect(myCacheMeta.cache).toEqual({
+        'n=1': 1,
+        'n=2': undefined,
+        'n=3': undefined,
+        'n=4': undefined,
+        'n=5': undefined,
+        'n=6': undefined,
+        'n=7': undefined,
+        'n=8': undefined,
+        'n=9': undefined,
+        'n=10': 10,
+      });
+      // Double-check the keys, because jest can give false positives on the undefined ones above
+      expect(Object.keys(myCacheMeta.cache)).toEqual([
+        'n=1',
+        'n=2',
+        'n=3',
+        'n=4',
+        'n=5',
+        'n=6',
+        'n=7',
+        'n=8',
+        'n=9',
+        'n=10',
+      ]);
+
+      myCacheMeta = lowLevelSet(myCacheMeta, 'n=11', 11);
+
+      // Now the internal data (including keys) should be trimmed
+      expect(myCacheMeta.cache).toEqual({ 'n=1': 1, 'n=10': 10, 'n=11': 11 });
+      expect(Object.keys(myCacheMeta.cache)).toEqual(['n=1', 'n=10', 'n=11']);
+    });
+  });
+
+  describe('lowLevelRemove', () => {
+    let myCacheMeta: LimitedCacheMeta;
+    beforeEach(() => {
+      vitest.restoreAllMocks();
+      myCacheMeta = lowLevelInit();
+      myCacheMeta = lowLevelSet(myCacheMeta, 'abc', 123);
+    });
+
+    it('removes an absent key', () => {
+      myCacheMeta = lowLevelRemove(myCacheMeta, 'ghi');
+
+      expect(myCacheMeta.cache).toEqual({ abc: 123 });
+    });
+
+    it('removes a present key', () => {
+      myCacheMeta = lowLevelRemove(myCacheMeta, 'abc');
+
+      expect(myCacheMeta.cache).toEqual({ abc: undefined });
+    });
+
+    it('removes a present key multiple times', () => {
+      myCacheMeta = lowLevelRemove(myCacheMeta, 'abc');
+      expect(myCacheMeta.cache).toEqual({ abc: undefined });
+
+      myCacheMeta = lowLevelRemove(myCacheMeta, 'abc');
+      expect(myCacheMeta.cache).toEqual({ abc: undefined });
+    });
+  });
+
+  describe('lowLevelReset', () => {
+    let myCacheMeta: LimitedCacheMeta;
+    beforeEach(() => {
+      vitest.restoreAllMocks();
+      myCacheMeta = lowLevelInit();
+      myCacheMeta = lowLevelSet(myCacheMeta, 'abc', 123);
+    });
+
+    it('does what it says', () => {
+      myCacheMeta = lowLevelReset(myCacheMeta);
+
+      expect(myCacheMeta.cache).toEqual({});
+    });
+  });
+});

package/src/__tests__/scenarios/keys.test.ts

@@ -0,0 +1,67 @@
+import { describe, beforeEach, expect, it } from 'vitest';
+import { limitedCacheUtil, LimitedCacheMeta } from '../../index';
+
+describe('key names', () => {
+  let myCacheMeta: LimitedCacheMeta;
+  beforeEach(() => {
+    myCacheMeta = limitedCacheUtil.init();
+  });
+
+  it('builtins: hasOwnProperty', () => {
+    expect(limitedCacheUtil.has(myCacheMeta, 'hasOwnProperty')).toEqual(false);
+    expect(limitedCacheUtil.get(myCacheMeta, 'hasOwnProperty')).toEqual(undefined);
+
+    limitedCacheUtil.set(myCacheMeta, 'hasOwnProperty', 123);
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'hasOwnProperty')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, 'hasOwnProperty')).toEqual(123);
+  });
+
+  it('builtins: constructor', () => {
+    expect(limitedCacheUtil.has(myCacheMeta, 'constructor')).toEqual(false);
+    expect(limitedCacheUtil.get(myCacheMeta, 'constructor')).toEqual(undefined);
+
+    limitedCacheUtil.set(myCacheMeta, 'constructor', 123);
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'constructor')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, 'constructor')).toEqual(123);
+  });
+
+  it('empty string', () => {
+    limitedCacheUtil.set(myCacheMeta, '', 123);
+
+    expect(limitedCacheUtil.has(myCacheMeta, '')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, '')).toEqual(123);
+  });
+
+  it('number', () => {
+    // @ts-expect-error description here
+    limitedCacheUtil.set(myCacheMeta, 123, 123);
+
+    // @ts-expect-error description here
+    expect(limitedCacheUtil.has(myCacheMeta, 123)).toEqual(true);
+    // @ts-expect-error description here
+    expect(limitedCacheUtil.get(myCacheMeta, 123)).toEqual(123);
+  });
+
+  it('special character: "-"', () => {
+    limitedCacheUtil.set(myCacheMeta, 'abc-123', 123);
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'abc-123')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, 'abc-123')).toEqual(123);
+  });
+
+  it('special character: "."', () => {
+    limitedCacheUtil.set(myCacheMeta, 'abc.123', 123);
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'abc.123')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, 'abc.123')).toEqual(123);
+  });
+
+  it('special character: " "', () => {
+    limitedCacheUtil.set(myCacheMeta, 'abc 123', 123);
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'abc 123')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, 'abc 123')).toEqual(123);
+  });
+});

package/src/__tests__/scenarios/maxCacheSize.test.ts

@@ -0,0 +1,126 @@
+import { describe, beforeEach, expect, it, vitest } from 'vitest';
+import { LimitedCache, LimitedCacheInstance } from '../../index';
+
+// To avoid race conditions or timing issues, since some expect() checks can take 10+ ms when busy,
+// we use a long cache timeout even for 'immediate' expiration, and use delays slightly longer than that
+const CACHE_TIMEOUT = 20;
+const timeoutPromise = (): Promise<null> =>
+  new Promise((resolve) => setTimeout(resolve, CACHE_TIMEOUT + 2));
+
+describe('maxCacheSize scenarios', () => {
+  let myCache: LimitedCacheInstance;
+  beforeEach(() => {
+    vitest.restoreAllMocks();
+    myCache = LimitedCache({
+      maxCacheSize: 20,
+      maxCacheTime: Number.MAX_SAFE_INTEGER,
+      opLimit: Number.MAX_SAFE_INTEGER,
+      warnIfItemPurgedBeforeTime: 0,
+    });
+  });
+
+  it('removes items to stay within the cache size, with unique keys', () => {
+    // Populate items into new keys: there should remain 20 items
+    for (let n = 1; n <= 1000; n++) {
+      myCache.set(`n=${n}`, n);
+
+      const allKeys = Object.keys(myCache.getAll());
+      expect(allKeys.length).toEqual(Math.min(20, n));
+    }
+  });
+
+  it('removes items to stay within the cache size, with overlapping keys', () => {
+    // Populate 20 items
+    for (let n = 1; n <= 20; n++) {
+      myCache.set(`n=${n}`, n);
+    }
+
+    // Populate items into progressive larger sets of keys: there should remain 20 items
+    for (let n = 1; n <= 10; n++) {
+      myCache.set(`n=${n}`, n);
+
+      const allKeys = Object.keys(myCache.getAll());
+      expect(allKeys.length).toEqual(20);
+    }
+    for (let n = 1; n <= 100; n++) {
+      myCache.set(`n=${n}`, n);
+
+      const allKeys = Object.keys(myCache.getAll());
+      expect(allKeys.length).toEqual(20);
+    }
+    for (let n = 1; n <= 1000; n++) {
+      myCache.set(`n=${n}`, n);
+
+      const allKeys = Object.keys(myCache.getAll());
+      expect(allKeys.length).toEqual(20);
+    }
+  });
+
+  it('removes items to stay within the cache size, with randomized keys', () => {
+    // Populate 20 items
+    for (let n = 1; n <= 20; n++) {
+      myCache.set(`n=${n}`, n);
+    }
+
+    // Now keep populating random values into a limited set of keys: there should remain 20 items
+    for (let i = 0; i < 1000; i++) {
+      // Keys will span 1 to 100
+      const n = Math.floor(Math.random() * 100) + 1;
+      myCache.set(`n=${n}`, i);
+
+      const allKeys = Object.keys(myCache.getAll());
+      expect(allKeys.length).toEqual(20);
+    }
+  });
+
+  it('removes expired items aggressively', async () => {
+    myCache = LimitedCache({
+      maxCacheSize: 5,
+      maxCacheTime: CACHE_TIMEOUT,
+      opLimit: Number.MAX_SAFE_INTEGER,
+    });
+
+    // Fill the cache
+    for (let n = 1; n <= 5; n++) {
+      myCache.set(`n=${n}`, n);
+    }
+    expect(Object.keys(myCache.getAll())).toEqual(['n=1', 'n=2', 'n=3', 'n=4', 'n=5']);
+
+    await timeoutPromise();
+
+    // Fill with different values
+    for (let n = 6; n <= 10; n++) {
+      myCache.set(`n=${n}`, n);
+    }
+    expect(Object.keys(myCache.getAll())).toEqual(['n=6', 'n=7', 'n=8', 'n=9', 'n=10']);
+  });
+
+  it('warns if a freshly-added item is pushed out too quickly', async () => {
+    myCache = LimitedCache({
+      maxCacheSize: 5,
+      maxCacheTime: 1000,
+      opLimit: Number.MAX_SAFE_INTEGER,
+      warnIfItemPurgedBeforeTime: 1000,
+    });
+
+    const consoleWarnSpy = vitest.spyOn(console, 'warn').mockReturnValueOnce();
+
+    for (let n = 1; n <= 5; n++) {
+      myCache.set(`n=${n}`, n);
+    }
+    // This pushes out the still-fresh `n=1`
+    myCache.set('abc', 123);
+
+    expect(Object.keys(myCache.getAll())).toEqual(['n=2', 'n=3', 'n=4', 'n=5', 'abc']);
+
+    // And we should have seen a warning about the force-removed key
+    const consoleWarnCalls = consoleWarnSpy.mock.calls;
+    expect(consoleWarnCalls.length).toBe(1);
+    const [warningString, warningObject] = consoleWarnCalls[0];
+    expect(warningString).toBe(
+      'Purged an item from cache while it was still fresh: you may want to increase maxCacheSize',
+    );
+    expect(typeof warningObject).toBe('object');
+    expect(warningObject.key).toBe('n=1');
+  });
+});