limited-cache 2.2.0 → 2.3.1

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

@@ -1,10 +1,12 @@
-import { describe, beforeEach, expect, it, vitest } from 'vitest';
-import { LimitedCacheObject, LimitedCacheObjectInstance } from '../../index.js';
+// biome-ignore-all lint/performance/noDelete: Delete is explicitly used to unset items for these tests
+
+import { beforeEach, describe, expect, it, vitest } from 'vitest';
+import { LimitedCacheObject, type LimitedCacheObjectInstance } from '../../index.js';
 
 // 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> =>
+const timeoutPromise = (): Promise<void> =>
   new Promise((resolve) => setTimeout(resolve, CACHE_TIMEOUT + 2));
 
 describe('maxCacheTime scenarios', () => {
@@ -19,41 +21,39 @@ describe('maxCacheTime scenarios', () => {
   });
 
   it("doesn't have keys for expired items", async () => {
-    myCache.abc = 123;
-    myCache.def = 456;
+    myCache['abc'] = 123;
+    myCache['def'] = 456;
     await timeoutPromise();
-    myCache.ghi = 789;
+    myCache['ghi'] = 789;
 
-    const { hasOwnProperty } = Object.prototype;
-    expect(hasOwnProperty.call(myCache, 'abc')).toEqual(false);
-    expect(hasOwnProperty.call(myCache, 'def')).toEqual(false);
+    expect(Object.hasOwn(myCache, 'abc')).toEqual(false);
+    expect(Object.hasOwn(myCache, 'def')).toEqual(false);
 
     expect(Object.keys(myCache)).toEqual(['ghi']);
   });
 
   it('removes expired items on get', async () => {
-    myCache.abc = 123;
-    myCache.def = 456;
+    myCache['abc'] = 123;
+    myCache['def'] = 456;
     await timeoutPromise();
 
-    expect(myCache.abc).toEqual(undefined);
-    expect(myCache.def).toEqual(undefined);
+    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;
+    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);
+    myCache['ghi'] = 789;
+
+    expect(Object.hasOwn(myCache, 'abc')).toEqual(false);
+    expect(Object.hasOwn(myCache, 'def')).toEqual(false);
+    expect(Object.hasOwn(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']);
   });
 
@@ -65,24 +65,24 @@ describe('maxCacheTime scenarios', () => {
       warnIfItemPurgedBeforeTime: 0,
     });
 
-    myCache.abc = 123;
+    myCache['abc'] = 123;
     await timeoutPromise();
-    myCache.def = 456;
+    myCache['def'] = 456;
     await timeoutPromise();
-    myCache.ghi = 789;
+    myCache['ghi'] = 789;
     await timeoutPromise();
 
     // Now write over the 'oldest' key to reset its timestamp
-    myCache.abc = 123;
+    myCache['abc'] = 123;
 
     // Now, adding a new value (over maxCacheSize) should remove the actual oldest
-    myCache.newOne = 100;
-    expect(myCache.def).toEqual(undefined);
+    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);
+    myCache['newTwo'] = 200;
+    expect(myCache['ghi']).toEqual(undefined);
     expect(Object.keys(myCache)).toEqual(['abc', 'newOne', 'newTwo']);
   });
 
@@ -94,36 +94,36 @@ describe('maxCacheTime scenarios', () => {
     });
 
     // This first set will expire after the second set gets added
-    myCache.abc = 123;
-    myCache.def = 456;
-    myCache.ghi = 789;
+    myCache['abc'] = 123;
+    myCache['def'] = 456;
+    myCache['ghi'] = 789;
     await timeoutPromise();
-    myCache.jkl = 321;
-    myCache.mno = 654;
-    myCache.abc = 1000;
+    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);
+    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);
+    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);
+    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 () => {
+  it('removes keys for already-removed items first', () => {
     myCache = LimitedCacheObject({
       maxCacheTime: 0,
       maxCacheSize: 5,
@@ -132,18 +132,18 @@ describe('maxCacheTime scenarios', () => {
     });
 
     // 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;
+    myCache['abc'] = 123;
+    myCache['def'] = 456;
+    myCache['ghi'] = 789;
+    myCache['jkl'] = 321;
+    myCache['mno'] = 654;
+    myCache['abc'] = 1000;
 
-    delete myCache.ghi;
-    delete myCache.jkl;
+    delete myCache['ghi'];
+    delete myCache['jkl'];
 
     // Now, adding a new value (over maxCacheSize) should not remove anything else
-    myCache.newOne = 100;
+    myCache['newOne'] = 100;
 
     expect(Object.keys(myCache)).toEqual(['abc', 'def', 'mno', 'newOne']);
   });

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

@@ -1,5 +1,5 @@
-import { describe, beforeEach, expect, it } from 'vitest';
-import { limitedCacheUtil, LimitedCacheMeta } from '../../index.js';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { type LimitedCacheMeta, limitedCacheUtil } from '../../index.js';
 
 describe('value types', () => {
   let myCacheMeta: LimitedCacheMeta;

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

@@ -7,21 +7,21 @@ import { LimitedCacheObject } from '../../index.js';
  * Instead, it ensures that the typeChecks are correct.
  */
 
-let value;
+let value: unknown;
 
 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>;
+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;
+numberCache['number'] = 1;
+value = numberCache['number'];
 
 // @ts-expect-error Invalid type
 numberCache.string = 'hello';
@@ -35,10 +35,10 @@ 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;
+primitiveCache['number'] = 1;
+primitiveCache['string'] = 'hello';
+value = primitiveCache['number'];
+value = primitiveCache['string'];
 
 // @ts-expect-error Invalid type
 primitiveCache.array = [];
@@ -48,8 +48,8 @@ value = primitiveCache.array as Array<undefined>;
 
 const arrayCache = LimitedCacheObject<Array<undefined>>();
 
-arrayCache.array = [];
-value = arrayCache.array as Array<undefined>;
+arrayCache['array'] = [];
+value = arrayCache['array'];
 
 // @ts-expect-error Invalid type
 arrayCache.number = 1;

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

@@ -7,7 +7,7 @@ import { LimitedCache } from '../../index.js';
  * Instead, it ensures that the typeChecks are correct.
  */
 
-let value;
+let value: unknown;
 
 const defaultCache = LimitedCache();
 

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

@@ -1,13 +1,13 @@
 import { describe, it } from 'vitest';
 
-import { lowLevelInit, lowLevelGetOne, lowLevelSet } from '../../index.js';
+import { lowLevelGetOne, lowLevelInit, lowLevelSet } from '../../index.js';
 
 /**
  * This is not a source file or test file.
  * Instead, it ensures that the typeChecks are correct.
  */
 
-let value;
+let value: unknown;
 
 const defaultCacheMeta = lowLevelInit();
 

package/src/core/LimitedCache.ts

@@ -1,29 +1,28 @@
+import type {
+  DefaultItemType,
+  LimitedCacheInstance,
+  LimitedCacheMeta,
+  LimitedCacheOptions,
+  LimitedCacheOptionsReadonly,
+} from '../types.js';
 import {
-  lowLevelInit,
-  lowLevelGetOne,
+  lowLevelDoMaintenance,
   lowLevelGetAll,
+  lowLevelGetOne,
   lowLevelHas,
-  lowLevelSet,
+  lowLevelInit,
   lowLevelRemove,
   lowLevelReset,
+  lowLevelSet,
   lowLevelSetOptions,
-  lowLevelDoMaintenance,
 } from './lowLevelFunctions.js';
-import {
-  LimitedCacheOptions,
-  LimitedCacheOptionsReadonly,
-  LimitedCacheInstance,
-  LimitedCacheMeta,
-  DefaultItemType,
-} from '../types.js';
 
 // Most public functions just call a low-level function directly, passing the cacheMeta.
 // Doing this via a helper function makes the typeChecks easier, and minifies better.
-const bindFunctionToCacheMeta = <ItemType>(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  fn: (cacheMeta: LimitedCacheMeta<ItemType>, ...otherArgs: any) => any,
+const bindFunctionToCacheMeta = <ItemType, OtherArgs extends unknown[], ReturnValue>(
+  fn: (cacheMeta: LimitedCacheMeta<ItemType>, ...otherArgs: OtherArgs) => ReturnValue,
   cacheMeta: LimitedCacheMeta<ItemType>,
-) => fn.bind(null, cacheMeta);
+): ((...otherArgs: OtherArgs) => ReturnValue) => fn.bind(null, cacheMeta);
 
 const LimitedCache = <ItemType = DefaultItemType>(
   options?: LimitedCacheOptions,
@@ -31,9 +30,9 @@ const LimitedCache = <ItemType = DefaultItemType>(
   const cacheMeta = lowLevelInit<ItemType>(options);
 
   return {
-    get: bindFunctionToCacheMeta<ItemType>(lowLevelGetOne, cacheMeta),
-    getAll: bindFunctionToCacheMeta<ItemType>(lowLevelGetAll, cacheMeta),
-    has: bindFunctionToCacheMeta<ItemType>(lowLevelHas, cacheMeta),
+    get: bindFunctionToCacheMeta(lowLevelGetOne, cacheMeta),
+    getAll: bindFunctionToCacheMeta(lowLevelGetAll, cacheMeta),
+    has: bindFunctionToCacheMeta(lowLevelHas, cacheMeta),
     set: (cacheKey, item): ItemType => {
       lowLevelSet(cacheMeta, cacheKey, item);
       return item;
@@ -42,11 +41,11 @@ const LimitedCache = <ItemType = DefaultItemType>(
       lowLevelRemove(cacheMeta, cacheKey);
       return true;
     },
-    reset: bindFunctionToCacheMeta<ItemType>(lowLevelReset, cacheMeta),
+    reset: bindFunctionToCacheMeta(lowLevelReset, cacheMeta),
     getCacheMeta: (): LimitedCacheMeta<ItemType> => cacheMeta,
     getOptions: (): LimitedCacheOptionsReadonly => cacheMeta.options,
-    setOptions: bindFunctionToCacheMeta<ItemType>(lowLevelSetOptions, cacheMeta),
-    doMaintenance: bindFunctionToCacheMeta<ItemType>(lowLevelDoMaintenance, cacheMeta),
+    setOptions: bindFunctionToCacheMeta(lowLevelSetOptions, cacheMeta),
+    doMaintenance: bindFunctionToCacheMeta(lowLevelDoMaintenance, cacheMeta),
   };
 };
 

package/src/core/LimitedCacheObject.ts

@@ -1,36 +1,36 @@
-import { hasOwnProperty } from './builtIns.js';
+import type {
+  DefaultItemType,
+  LimitedCacheMeta,
+  LimitedCacheObjectInstance,
+  LimitedCacheOptions,
+} from '../types.js';
 import {
-  lowLevelInit,
-  lowLevelGetOne,
   lowLevelGetAll,
+  lowLevelGetOne,
   lowLevelHas,
-  lowLevelSet,
+  lowLevelInit,
   lowLevelRemove,
+  lowLevelSet,
 } from './lowLevelFunctions.js';
-import {
-  LimitedCacheOptions,
-  LimitedCacheObjectInstance,
-  LimitedCacheMeta,
-  DefaultItemType,
-} from '../types.js';
 
-// The `any` here doesn't escape out anywhere: it's overridden by the constructor below
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const proxyHandler: ProxyHandler<LimitedCacheObjectInstance<any>> = {
+const proxyHandler: ProxyHandler<LimitedCacheMeta> = {
   get: (cacheMeta: LimitedCacheMeta, cacheKey: string) => {
     if (cacheKey === 'hasOwnProperty') {
-      return hasOwnProperty;
+      return Object.prototype.hasOwnProperty;
     }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
     return lowLevelGetOne(cacheMeta, cacheKey);
   },
   getOwnPropertyDescriptor: (cacheMeta: LimitedCacheMeta, cacheKey: string) => {
     const hasResult = lowLevelHas(cacheMeta, cacheKey);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     const getResult = lowLevelGetOne(cacheMeta, cacheKey);
 
     if (hasResult) {
       return {
         configurable: true,
         enumerable: hasResult,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         value: getResult,
         writable: true,
       };
@@ -38,8 +38,7 @@ const proxyHandler: ProxyHandler<LimitedCacheObjectInstance<any>> = {
     return;
   },
   has: lowLevelHas,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  set: (cacheMeta: LimitedCacheMeta, cacheKey: string, item: any): any => {
+  set: <T>(cacheMeta: LimitedCacheMeta, cacheKey: string, item: T): T => {
     lowLevelSet(cacheMeta, cacheKey, item);
     return item;
   },
@@ -50,6 +49,16 @@ const proxyHandler: ProxyHandler<LimitedCacheObjectInstance<any>> = {
   ownKeys: (cacheMeta: LimitedCacheMeta) => Object.keys(lowLevelGetAll(cacheMeta)),
 };
 
+/**
+ * TypeScript's Proxy type models the runtime target, but LimitedCacheObject intentionally returns
+ * a facade with a different surface from the internal cache metadata target.
+ */
+const internal_createLimitedCacheObjectProxy = <ItemType = DefaultItemType>(
+  cacheMeta: LimitedCacheMeta<ItemType>,
+): LimitedCacheObjectInstance<ItemType> => {
+  return new Proxy(cacheMeta, proxyHandler) as unknown as LimitedCacheObjectInstance<ItemType>;
+};
+
 /**
  * So that we can retrieve the cacheMeta for a LimitedCacheObject, without polluting its properties, each proxy
  * is associated back to its internal cacheMeta here.
@@ -59,15 +68,17 @@ const cacheMetasForProxies = new WeakMap();
 const LimitedCacheObject = <ItemType = DefaultItemType>(
   options?: LimitedCacheOptions,
 ): LimitedCacheObjectInstance<ItemType> => {
-  const cacheMeta = lowLevelInit(options);
-  const limitedCacheObject = new Proxy(cacheMeta, proxyHandler);
+  const cacheMeta = lowLevelInit<ItemType>(options);
+  const limitedCacheObject = internal_createLimitedCacheObjectProxy(cacheMeta);
 
   cacheMetasForProxies.set(limitedCacheObject, cacheMeta);
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
   return limitedCacheObject;
 };
 
 const getCacheMetaFromObject = (instance: LimitedCacheObjectInstance): LimitedCacheMeta => {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
   return cacheMetasForProxies.get(instance);
 };
 
-export { LimitedCacheObject, getCacheMetaFromObject };
+export { getCacheMetaFromObject, LimitedCacheObject };

package/src/core/defaultOptions.ts

@@ -1,7 +1,8 @@
-import { LimitedCacheOptionsReadonly } from '../types.js';
+import type { LimitedCacheOptionsReadonly } from '../types.js';
 
-const CURRENT_META_VERSION = 2;
-const MAXIMUM_CACHE_TIME = 365 * 86400 * 1000;
+const CURRENT_META_VERSION = 2 as const;
+// Default = 1 year
+const MAXIMUM_CACHE_TIME: number = 365 * 86400 * 1000;
 
 const defaultOptions: LimitedCacheOptionsReadonly = {
   // Public
@@ -14,4 +15,4 @@ const defaultOptions: LimitedCacheOptionsReadonly = {
   scanLimit: 50,
 };
 
-export { CURRENT_META_VERSION, MAXIMUM_CACHE_TIME, defaultOptions };
+export { CURRENT_META_VERSION, defaultOptions, MAXIMUM_CACHE_TIME };

package/src/core/limitedCacheUtil.ts

@@ -1,16 +1,28 @@
 import {
-  lowLevelGetOne,
+  lowLevelDoMaintenance,
   lowLevelGetAll,
+  lowLevelGetOne,
   lowLevelHas,
   lowLevelInit,
-  lowLevelDoMaintenance,
   lowLevelRemove,
   lowLevelReset,
   lowLevelSet,
   lowLevelSetOptions,
 } from './lowLevelFunctions.js';
 
-const limitedCacheUtil = {
+type LimitedCacheUtil = {
+  init: typeof lowLevelInit;
+  get: typeof lowLevelGetOne;
+  getAll: typeof lowLevelGetAll;
+  has: typeof lowLevelHas;
+  set: typeof lowLevelSet;
+  remove: typeof lowLevelRemove;
+  reset: typeof lowLevelReset;
+  doMaintenance: typeof lowLevelDoMaintenance;
+  setOptions: typeof lowLevelSetOptions;
+};
+
+const limitedCacheUtil: LimitedCacheUtil = {
   init: lowLevelInit,
   get: lowLevelGetOne,
   getAll: lowLevelGetAll,