limited-cache 1.1.1 → 2.1.0

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

@@ -0,0 +1,150 @@
+import { describe, beforeEach, expect, it, vitest } from 'vitest';
+import { LimitedCacheObject, LimitedCacheObjectInstance } 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 = 25;
+const timeoutPromise = (): Promise<null> =>
+  new Promise((resolve) => setTimeout(resolve, CACHE_TIMEOUT + 2));
+
+describe('maxCacheTime scenarios', () => {
+  let myCache: LimitedCacheObjectInstance;
+  beforeEach(() => {
+    vitest.restoreAllMocks();
+    myCache = LimitedCacheObject({
+      maxCacheTime: CACHE_TIMEOUT,
+      maxCacheSize: Number.MAX_SAFE_INTEGER,
+      opLimit: Number.MAX_SAFE_INTEGER,
+    });
+  });
+
+  it("doesn't have keys for expired items", async () => {
+    myCache.abc = 123;
+    myCache.def = 456;
+    await timeoutPromise();
+    myCache.ghi = 789;
+
+    const { hasOwnProperty } = Object.prototype;
+    expect(hasOwnProperty.call(myCache, 'abc')).toEqual(false);
+    expect(hasOwnProperty.call(myCache, 'def')).toEqual(false);
+
+    expect(Object.keys(myCache)).toEqual(['ghi']);
+  });
+
+  it('removes expired items on get', async () => {
+    myCache.abc = 123;
+    myCache.def = 456;
+    await timeoutPromise();
+
+    expect(myCache.abc).toEqual(undefined);
+    expect(myCache.def).toEqual(undefined);
+    expect(Object.keys(myCache)).toEqual([]);
+  });
+
+  it('removes expired items on set', async () => {
+    myCache.abc = 123;
+    myCache.def = 456;
+    await timeoutPromise();
+    myCache.ghi = 789;
+
+    const { hasOwnProperty } = Object.prototype;
+    expect(hasOwnProperty.call(myCache, 'abc')).toEqual(false);
+    expect(hasOwnProperty.call(myCache, 'def')).toEqual(false);
+    expect(hasOwnProperty.call(myCache, 'ghi')).toEqual(true);
+    expect(myCache.abc).toEqual(undefined);
+    expect(myCache.def).toEqual(undefined);
+    expect(myCache.ghi).toEqual(789);
+    expect(Object.keys(myCache)).toEqual(['ghi']);
+  });
+
+  it('removes older items before newer ones', async () => {
+    myCache = LimitedCacheObject({
+      maxCacheTime: Number.MAX_SAFE_INTEGER,
+      maxCacheSize: 3,
+      opLimit: Number.MAX_SAFE_INTEGER,
+      warnIfItemPurgedBeforeTime: 0,
+    });
+
+    myCache.abc = 123;
+    await timeoutPromise();
+    myCache.def = 456;
+    await timeoutPromise();
+    myCache.ghi = 789;
+    await timeoutPromise();
+
+    // Now write over the 'oldest' key to reset its timestamp
+    myCache.abc = 123;
+
+    // Now, adding a new value (over maxCacheSize) should remove the actual oldest
+    myCache.newOne = 100;
+    expect(myCache.def).toEqual(undefined);
+    expect(Object.keys(myCache)).toEqual(['abc', 'ghi', 'newOne']);
+
+    // And then the next oldest, after that
+    myCache.newTwo = 200;
+    expect(myCache.ghi).toEqual(undefined);
+    expect(Object.keys(myCache)).toEqual(['abc', 'newOne', 'newTwo']);
+  });
+
+  it('removes expired items before old ones', async () => {
+    myCache = LimitedCacheObject({
+      maxCacheTime: CACHE_TIMEOUT * 2,
+      maxCacheSize: 5,
+      opLimit: Number.MAX_SAFE_INTEGER,
+    });
+
+    // This first set will expire after the second set gets added
+    myCache.abc = 123;
+    myCache.def = 456;
+    myCache.ghi = 789;
+    await timeoutPromise();
+    myCache.jkl = 321;
+    myCache.mno = 654;
+    myCache.abc = 1000;
+
+    // At this point nothing has been removed, since reusing 'abc' keeps us within maxCacheSize
+    expect(myCache.abc).toEqual(1000);
+    expect(myCache.def).toEqual(456);
+    expect(myCache.ghi).toEqual(789);
+
+    await timeoutPromise();
+
+    // Now, adding a new value (over maxCacheSize) should remove both of the remaining expired values
+    myCache.newOne = 100;
+    expect(myCache.def).toEqual(undefined);
+    expect(myCache.ghi).toEqual(undefined);
+    expect(Object.keys(myCache)).toEqual(['abc', 'jkl', 'mno', 'newOne']);
+
+    // And then the next can go in without having to remove anything
+    myCache.newTwo = 200;
+    expect(myCache.jkl).toEqual(321);
+    expect(myCache.mno).toEqual(654);
+    expect(myCache.abc).toEqual(1000);
+    expect(Object.keys(myCache)).toEqual(['abc', 'jkl', 'mno', 'newOne', 'newTwo']);
+  });
+
+  it('removes keys for already-removed items first', async () => {
+    myCache = LimitedCacheObject({
+      maxCacheTime: 0,
+      maxCacheSize: 5,
+      opLimit: Number.MAX_SAFE_INTEGER,
+      warnIfItemPurgedBeforeTime: 0,
+    });
+
+    // This first set will expire after the second set gets added
+    myCache.abc = 123;
+    myCache.def = 456;
+    myCache.ghi = 789;
+    myCache.jkl = 321;
+    myCache.mno = 654;
+    myCache.abc = 1000;
+
+    delete myCache.ghi;
+    delete myCache.jkl;
+
+    // Now, adding a new value (over maxCacheSize) should not remove anything else
+    myCache.newOne = 100;
+
+    expect(Object.keys(myCache)).toEqual(['abc', 'def', 'mno', 'newOne']);
+  });
+});

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

@@ -0,0 +1,49 @@
+import { describe, beforeEach, expect, it } from 'vitest';
+import { limitedCacheUtil, LimitedCacheMeta } from '../../index';
+
+describe('value types', () => {
+  let myCacheMeta: LimitedCacheMeta;
+  beforeEach(() => {
+    myCacheMeta = limitedCacheUtil.init();
+  });
+
+  it('null', () => {
+    limitedCacheUtil.set(myCacheMeta, 'test', null);
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'test')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, 'test')).toEqual(null);
+  });
+
+  // Setting an explicit `undefined` treats the value as absent
+  it('undefined', () => {
+    limitedCacheUtil.set(myCacheMeta, 'test', undefined);
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'test')).toEqual(false);
+    expect(limitedCacheUtil.get(myCacheMeta, 'test')).toEqual(undefined);
+  });
+
+  it('object', () => {
+    limitedCacheUtil.set(myCacheMeta, 'test', { foo: 'bar' });
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'test')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, 'test')).toEqual({ foo: 'bar' });
+  });
+
+  it('array', () => {
+    limitedCacheUtil.set(myCacheMeta, 'test', [1, 2, 3]);
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'test')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, 'test')).toEqual([1, 2, 3]);
+  });
+
+  it('function', () => {
+    function testFunction(): null {
+      return null;
+    }
+
+    limitedCacheUtil.set(myCacheMeta, 'test', testFunction);
+
+    expect(limitedCacheUtil.has(myCacheMeta, 'test')).toEqual(true);
+    expect(limitedCacheUtil.get(myCacheMeta, 'test')).toEqual(testFunction);
+  });
+});

package/src/__tests__/typeChecks/LimitedCacheObjectTypes.test.ts

@@ -0,0 +1,70 @@
+import { describe, it } from 'vitest';
+
+import { LimitedCacheObject } from '../../index';
+
+/**
+ * This is not a source file or test file.
+ * Instead, it ensures that the typeChecks are correct.
+ */
+
+let value;
+
+const defaultCache = LimitedCacheObject();
+
+defaultCache.number = 1;
+defaultCache.string = 'hello';
+defaultCache.array = [];
+value = defaultCache.number as number;
+value = defaultCache.string as string;
+value = defaultCache.array as Array<undefined>;
+
+const numberCache = LimitedCacheObject<number>();
+
+numberCache.number = 1;
+value = numberCache.number as number;
+
+// @ts-expect-error Invalid type
+numberCache.string = 'hello';
+// @ts-expect-error Invalid type
+numberCache.array = [];
+
+// @ts-expect-error Invalid type
+value = numberCache.string as string;
+// @ts-expect-error Invalid type
+value = numberCache.array as Array<undefined>;
+
+const primitiveCache = LimitedCacheObject<boolean | number | string>();
+
+primitiveCache.number = 1;
+primitiveCache.string = 'hello';
+value = primitiveCache.number as number;
+value = primitiveCache.string as string;
+
+// @ts-expect-error Invalid type
+primitiveCache.array = [];
+
+// @ts-expect-error Invalid type
+value = primitiveCache.array as Array<undefined>;
+
+const arrayCache = LimitedCacheObject<Array<undefined>>();
+
+arrayCache.array = [];
+value = arrayCache.array as Array<undefined>;
+
+// @ts-expect-error Invalid type
+arrayCache.number = 1;
+// @ts-expect-error Invalid type
+arrayCache.string = 'hello';
+
+// @ts-expect-error Invalid type
+value = arrayCache.number as number;
+// @ts-expect-error Invalid type
+value = arrayCache.string as string;
+
+// Fake test, to make Vitest happy
+describe('fake typeCheck test', () => {
+  it('does nothing', () => null);
+});
+
+// Fake export, to make the linter happy
+export { value };

package/src/__tests__/typeChecks/LimitedCacheTypes.test.ts

@@ -0,0 +1,70 @@
+import { describe, it } from 'vitest';
+
+import { LimitedCache } from '../../index';
+
+/**
+ * This is not a source file or test file.
+ * Instead, it ensures that the typeChecks are correct.
+ */
+
+let value;
+
+const defaultCache = LimitedCache();
+
+defaultCache.set('number', 1);
+defaultCache.set('string', 'hello');
+defaultCache.set('array', []);
+value = defaultCache.get('number') as number;
+value = defaultCache.get('string') as string;
+value = defaultCache.get('array') as Array<undefined>;
+
+const numberCache = LimitedCache<number>();
+
+numberCache.set('number', 1);
+value = numberCache.get('number') as number;
+
+// @ts-expect-error Invalid type
+numberCache.set('string', 'hello');
+// @ts-expect-error Invalid type
+numberCache.set('array', []);
+
+// @ts-expect-error Invalid type
+value = numberCache.get('string') as string;
+// @ts-expect-error Invalid type
+value = numberCache.get('array') as Array<undefined>;
+
+const primitiveCache = LimitedCache<boolean | number | string>();
+
+primitiveCache.set('number', 1);
+primitiveCache.set('string', 'hello');
+value = primitiveCache.get('number') as number;
+value = primitiveCache.get('string') as string;
+
+// @ts-expect-error Invalid type
+primitiveCache.set('array', []);
+
+// @ts-expect-error Invalid type
+value = primitiveCache.get('array') as Array<undefined>;
+
+const arrayCache = LimitedCache<Array<undefined>>();
+
+arrayCache.set('array', []);
+value = arrayCache.get('array') as Array<undefined>;
+
+// @ts-expect-error Invalid type
+arrayCache.set('number', 1);
+// @ts-expect-error Invalid type
+arrayCache.set('string', 'hello');
+
+// @ts-expect-error Invalid type
+value = arrayCache.get('number') as number;
+// @ts-expect-error Invalid type
+value = arrayCache.get('string') as string;
+
+// Fake test, to make Vitest happy
+describe('fake typeCheck test', () => {
+  it('does nothing', () => null);
+});
+
+// Fake export, to make the linter happy
+export { value };

package/src/__tests__/typeChecks/lowLevelFunctionsTypes.test.ts

@@ -0,0 +1,70 @@
+import { describe, it } from 'vitest';
+
+import { lowLevelInit, lowLevelGetOne, lowLevelSet } from '../../index';
+
+/**
+ * This is not a source file or test file.
+ * Instead, it ensures that the typeChecks are correct.
+ */
+
+let value;
+
+const defaultCacheMeta = lowLevelInit();
+
+lowLevelSet(defaultCacheMeta, 'number', 1);
+lowLevelSet(defaultCacheMeta, 'string', 'hello');
+lowLevelSet(defaultCacheMeta, 'array', []);
+value = lowLevelGetOne(defaultCacheMeta, 'number') as number;
+value = lowLevelGetOne(defaultCacheMeta, 'string') as string;
+value = lowLevelGetOne(defaultCacheMeta, 'array') as Array<undefined>;
+
+const numberCacheMeta = lowLevelInit<number>();
+
+lowLevelSet(numberCacheMeta, 'number', 1);
+value = lowLevelGetOne(numberCacheMeta, 'number') as number;
+
+// @ts-expect-error Invalid type
+lowLevelSet(numberCacheMeta, 'string', 'hello');
+// @ts-expect-error Invalid type
+lowLevelSet(numberCacheMeta, 'array', []);
+
+// @ts-expect-error Invalid type
+value = lowLevelGetOne(numberCacheMeta, 'string') as string;
+// @ts-expect-error Invalid type
+value = lowLevelGetOne(numberCacheMeta, 'array') as Array<undefined>;
+
+const primitiveCacheMeta = lowLevelInit<boolean | number | string>();
+
+lowLevelSet(primitiveCacheMeta, 'number', 1);
+lowLevelSet(primitiveCacheMeta, 'string', 'hello');
+value = lowLevelGetOne(primitiveCacheMeta, 'number') as number;
+value = lowLevelGetOne(primitiveCacheMeta, 'string') as string;
+
+// @ts-expect-error Invalid type
+lowLevelSet(primitiveCacheMeta, 'array', []);
+
+// @ts-expect-error Invalid type
+value = lowLevelGetOne(primitiveCacheMeta, 'array') as Array<undefined>;
+
+const arrayCacheMeta = lowLevelInit<Array<undefined>>();
+
+lowLevelSet(arrayCacheMeta, 'array', []);
+value = lowLevelGetOne(arrayCacheMeta, 'array') as Array<undefined>;
+
+// @ts-expect-error Invalid type
+lowLevelSet(arrayCacheMeta, 'number', 1);
+// @ts-expect-error Invalid type
+lowLevelSet(arrayCacheMeta, 'string', 'hello');
+
+// @ts-expect-error Invalid type
+value = lowLevelGetOne(arrayCacheMeta, 'number') as number;
+// @ts-expect-error Invalid type
+value = lowLevelGetOne(arrayCacheMeta, 'string') as string;
+
+// Fake test, to make Vitest happy
+describe('fake typeCheck test', () => {
+  it('does nothing', () => null);
+});
+
+// Fake export, to make the linter happy
+export { value };

package/src/core/LimitedCache.ts

@@ -50,4 +50,4 @@ const LimitedCache = <ItemType = DefaultItemType>(
   };
 };
 
-export default LimitedCache;
+export { LimitedCache };

package/src/core/LimitedCacheObject.ts

@@ -21,7 +21,6 @@ const proxyHandler: ProxyHandler<LimitedCacheObjectInstance<any>> = {
     if (cacheKey === 'hasOwnProperty') {
       return hasOwnProperty;
     }
-
     return lowLevelGetOne(cacheMeta, cacheKey);
   },
   getOwnPropertyDescriptor: (cacheMeta: LimitedCacheMeta, cacheKey: string) => {
@@ -51,11 +50,24 @@ const proxyHandler: ProxyHandler<LimitedCacheObjectInstance<any>> = {
   ownKeys: (cacheMeta: LimitedCacheMeta) => Object.keys(lowLevelGetAll(cacheMeta)),
 };
 
+/**
+ * So that we can retrieve the cacheMeta for a LimitedCacheObject, without polluting its properties, each proxy
+ * is associated back to its internal cacheMeta here.
+ */
+const cacheMetasForProxies = new WeakMap();
+
 const LimitedCacheObject = <ItemType = DefaultItemType>(
   options?: LimitedCacheOptions,
 ): LimitedCacheObjectInstance<ItemType> => {
   const cacheMeta = lowLevelInit(options);
-  return new Proxy(cacheMeta, proxyHandler);
+  const limitedCacheObject = new Proxy(cacheMeta, proxyHandler);
+
+  cacheMetasForProxies.set(limitedCacheObject, cacheMeta);
+  return limitedCacheObject;
+};
+
+const getCacheMetaFromObject = (instance: LimitedCacheObjectInstance): LimitedCacheMeta => {
+  return cacheMetasForProxies.get(instance);
 };
 
-export default LimitedCacheObject;
+export { LimitedCacheObject, getCacheMetaFromObject };

package/src/core/defaultOptions.ts

@@ -14,5 +14,4 @@ const defaultOptions: LimitedCacheOptionsReadonly = {
   scanLimit: 50,
 };
 
-export default defaultOptions;
-export { CURRENT_META_VERSION, MAXIMUM_CACHE_TIME };
+export { CURRENT_META_VERSION, MAXIMUM_CACHE_TIME, defaultOptions };

package/src/core/limitedCacheUtil.ts

@@ -22,4 +22,4 @@ const limitedCacheUtil = {
   setOptions: lowLevelSetOptions,
 };
 
-export default limitedCacheUtil;
+export { limitedCacheUtil };

package/src/core/lowLevelFunctions.ts

@@ -1,5 +1,5 @@
 import { objectAssign, objectCreate, dateNow, hasOwnProperty } from './builtIns';
-import defaultOptions, { CURRENT_META_VERSION, MAXIMUM_CACHE_TIME } from './defaultOptions';
+import { CURRENT_META_VERSION, MAXIMUM_CACHE_TIME, defaultOptions } from './defaultOptions';
 import {
   LimitedCacheOptions,
   LimitedCacheOptionsReadonly,
@@ -115,9 +115,9 @@ const lowLevelDoMaintenance = <ItemType = DefaultItemType>(
       return acc;
     },
     [
-      {} as typeof cacheMeta['cache'],
-      [] as typeof cacheMeta['keyList'],
-      objectCreate(null) as typeof cacheMeta['keyInfo'],
+      {} as (typeof cacheMeta)['cache'],
+      [] as (typeof cacheMeta)['keyList'],
+      objectCreate(null) as (typeof cacheMeta)['keyInfo'],
     ],
   );
 
@@ -169,7 +169,7 @@ const _removeItemsToMakeRoom = (cacheMeta: LimitedCacheMeta, now: number): void
     const maxIndexToCheck = Math.min(keyList.length, scanLimit);
     while (indexToCheck < maxIndexToCheck) {
       const cacheKeyForIndex = keyList[indexToCheck];
-      let expireTimeForIndex = _getExpireTime(cacheMeta, cacheKeyForIndex);
+      const expireTimeForIndex = _getExpireTime(cacheMeta, cacheKeyForIndex);
 
       // We only consider it if it's eligible for expiration: otherwise it can't be a better option
       // than the default head-of-queue
@@ -196,7 +196,7 @@ const _removeItemsToMakeRoom = (cacheMeta: LimitedCacheMeta, now: number): void
     oldestExpireTime > now
   ) {
     const oldestItemKey = keyList[oldestItemIndex];
-    const [oldestItemSetTime, oldestItemExpireTime] = keyInfo[oldestItemKey]!;
+    const [oldestItemSetTime, oldestItemExpireTime] = keyInfo[oldestItemKey] as [number, number];
 
     if (now - oldestItemSetTime < warnIfItemPurgedBeforeTime) {
       console.warn(

package/src/index.ts

@@ -1,15 +1,7 @@
-export { default as defaultOptions } from './core/defaultOptions';
 export * from './core/defaultOptions';
-
-export { default as LimitedCache } from './core/LimitedCache';
 export * from './core/LimitedCache';
-
-export { default as LimitedCacheObject } from './core/LimitedCacheObject';
 export * from './core/LimitedCacheObject';
-
-export { default as limitedCacheUtil } from './core/limitedCacheUtil';
 export * from './core/limitedCacheUtil';
 
 export * from './core/lowLevelFunctions';
-
 export * from './types';