Merge pull request #19180 from BendingBender/lru-cache

[lru-cache] upgrade to 4.1, improve typings, enable strict null checks and linting

types/lru-cache/index.d.ts

@@ -1,14 +1,23 @@
-// Type definitions for lru-cache v4.0
+// Type definitions for lru-cache 4.1
 // Project: https://github.com/isaacs/node-lru-cache
 // Definitions by: Bart van der Schoor <https://github.com/Bartvds>
+//                 BendingBender <https://github.com/BendingBender>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.3
 
+export = LRU;
 
-declare function LRU<T>(opts: LRU.Options<T>): LRU.Cache<T>;
-declare function LRU<T>(max: number): LRU.Cache<T>;
+declare const LRU: LRU;
+
+interface LRU {
+    <K, V>(opts?: LRU.Options<K, V>): LRU.Cache<K, V>;
+    <K, V>(max: number): LRU.Cache<K, V>;
+    new <K, V>(opts?: LRU.Options<K, V>): LRU.Cache<K, V>;
+    new <K, V>(max: number): LRU.Cache<K, V>;
+}
 
 declare namespace LRU {
-    interface Options<T> {
+    interface Options<K = any, V = any> {
         /**
          * The maximum size of the cache, checked by applying the length
          * function to all values in the cache. Not setting this is kind of silly,
@@ -29,9 +38,9 @@ declare namespace LRU {
          * something like `function(n, key){return n.length}`. The default
          * is `function(){return 1}`, which is fine if you want to store
          * `max` like-sized things. The item is passed as the first argument,
-         * and the key is passed as the second argumnet.
+         * and the key is passed as the second argument.
          */
-        length?: (value: T) => number;
+        length?(value: V): number;
 
         /**
          * Function that is called on items when they are dropped from the cache.
@@ -41,7 +50,7 @@ declare namespace LRU {
          * so if you want to immediately put it back in, you'll have to do that in
          * a `nextTick` or `setTimeout` callback or it won't do anything.
          */
-        dispose?: (key: any, value: T) => void;
+        dispose?(key: K, value: V): void;
 
         /**
          * By default, if you set a `maxAge`, it'll only actually pull stale items
@@ -52,42 +61,81 @@ declare namespace LRU {
          * as if it had already been deleted.
          */
         stale?: boolean;
+
+        /**
+         * By default, if you set a `dispose()` method, then it'll be called whenever
+         * a `set()` operation overwrites an existing key. If you set this option,
+         * `dispose()` will only be called when a key falls out of the cache,
+         * not when it is overwritten.
+         */
+        noDisposeOnSet?: boolean;
     }
 
-    interface Cache<T> {
+    interface Cache<K, V> {
         /**
-         * Will update the "recently used"-ness of the key. They do what you think.
-         * `maxAge` is optional and overrides the cache `maxAge` option if provided.
+         * Return total length of objects in cache taking into account `length` options function.
          */
-        set(key: any, value: T, maxAge?: number): void;
+        readonly length: number;
+
+        /**
+         * Return total quantity of objects currently in cache. Note,
+         * that `stale` (see options) items are returned as part of this item count.
+         */
+        readonly itemCount: number;
+
+        /**
+         * Same as Options.allowStale.
+         */
+        allowStale: boolean;
+
+        /**
+         * Same as Options.length.
+         */
+        lengthCalculator(value: V): number;
+
+        /**
+         * Same as Options.max. Resizes the cache when the `max` changes.
+         */
+        max: number;
+
+        /**
+         * Same as Options.maxAge. Resizes the cache when the `maxAge` changes.
+         */
+        maxAge: number;
 
         /**
          * Will update the "recently used"-ness of the key. They do what you think.
          * `maxAge` is optional and overrides the cache `maxAge` option if provided.
-         * 
+         */
+        set(key: K, value: V, maxAge?: number): boolean;
+
+        /**
+         * Will update the "recently used"-ness of the key. They do what you think.
+         * `maxAge` is optional and overrides the cache `maxAge` option if provided.
+         *
          * If the key is not found, will return `undefined`.
          */
-        get(key: any): T;
+        get(key: K): V | undefined;
 
         /**
          * Returns the key value (or `undefined` if not found) without updating
          * the "recently used"-ness of the key.
-         * 
+         *
          * (If you find yourself using this a lot, you might be using the wrong
          * sort of data structure, but there are some use cases where it's handy.)
          */
-        peek(key: any): T;
+        peek(key: K): V | undefined;
 
         /**
          * Check if a key is in the cache, without updating the recent-ness
          * or deleting it for being stale.
          */
-        has(key: any): boolean
+        has(key: K): boolean;
 
         /**
          * Deletes a key out of the cache.
          */
-        del(key: any): void;
+        del(key: K): void;
 
         /**
          * Clear the cache entirely, throwing away all values.
@@ -103,48 +151,41 @@ declare namespace LRU {
          * Just like `Array.prototype.forEach`. Iterates over all the keys in the cache,
          * in order of recent-ness. (Ie, more recently used items are iterated over first.)
          */
-        forEach(iter: (value: T, key: any, cache: Cache<T>) => void, thisp?: any): void;
+        forEach<T = this>(callbackFn: (this: T, value: V, key: K, cache: this) => void, thisArg?: T): void;
 
         /**
          * The same as `cache.forEach(...)` but items are iterated over in reverse order.
          * (ie, less recently used items are iterated over first.)
          */
-        rforEach(iter: (value: T, key: any, cache: Cache<T>) => void, thisp?: any): void;
-
-        /**
-         * Return total quantity of objects currently in cache. Note,
-         * that `stale` (see options) items are returned as part of this item count.
-         */
-        itemCount: number;
-
-        /**
-         * Return total length of objects in cache taking into account `length` options function.
-         */
-        length: number;
+        rforEach<T = this>(callbackFn: (this: T, value: V, key: K, cache: this) => void, thisArg?: T): void;
 
         /**
          * Return an array of the keys in the cache.
          */
-        keys(): any[];
+        keys(): K[];
 
         /**
          * Return an array of the values in the cache.
          */
-        values(): T[];
+        values(): V[];
 
         /**
          * Return an array of the cache entries ready for serialization and usage with `destinationCache.load(arr)`.
          */
-        dump(): T[];
+        dump(): Array<LRUEntry<K, V>>;
 
         /**
          * Loads another cache entries array, obtained with `sourceCache.dump()`,
          * into the cache. The destination cache is reset before loading new entries
-         * 
+         *
          * @param cacheEntries Obtained from `sourceCache.dump()`
          */
-        load(cacheEntries: T[]): void;
+        load(cacheEntries: ReadonlyArray<LRUEntry<K, V>>): void;
+    }
+
+    interface LRUEntry<K, V> {
+        k: K;
+        v: V;
+        e: number;
     }
 }
-
-export = LRU;

types/lru-cache/lru-cache-tests.ts

@@ -1,55 +1,111 @@
+import LRU = require('lru-cache');
 
-import lru = require('lru-cache');
-
-var x: any;
-var num: number;
-var bool: boolean;
-var key: string;
-var strArr: string[];
+const num = 1;
 
 interface Foo {
 	foo(): void;
 }
 
-var foo: Foo;
-var fooArr: Foo[];
-
-var opts: lru.Options<any>;
-opts = {
-	max: num,
-	maxAge: num,
-	stale: bool
+const foo = {
+    foo() {}
 };
-var cache: lru.Cache<Foo> = lru<Foo>({
+
+const cache = LRU<string, Foo>();
+cache; // $ExpectType Cache<string, Foo>
+LRU<string, Foo>({ // $ExpectType Cache<string, Foo>
 	max: num,
 	maxAge: num,
-	length: (value: Foo) => {
-		return num
+	length(value) {
+        value; // $ExpectType Foo
+        return num;
 	},
-	dispose: (key: string, value: Foo) => {
-
+	dispose(key, value) {
+        key; // $ExpectType string
+        value; // $ExpectType Foo
 	},
-	stale: bool
+	stale: false,
+    noDisposeOnSet: false,
 });
+LRU<string, Foo>(num); // $ExpectType Cache<string, Foo>
+new LRU<string, Foo>(); // $ExpectType Cache<string, Foo>
+new LRU<string, Foo>({ // $ExpectType Cache<string, Foo>
+    max: num,
+    maxAge: num,
+    length: (value) => {
+        return num;
+    },
+    dispose: (key, value) => {},
+    stale: false,
+    noDisposeOnSet: false,
+});
+new LRU<string, Foo>(num); // $ExpectType Cache<string, Foo>
 
-cache = lru<Foo>(num);
+cache.length; // $ExpectType number
+cache.length = 1; // $ExpectError
+
+cache.itemCount; // $ExpectType number
+cache.itemCount = 1; // $ExpectError
+
+cache.allowStale; // $ExpectType boolean
+cache.allowStale = true;
+
+cache.lengthCalculator; // $ExpectType (value: Foo) => number
+cache.lengthCalculator = () => 1;
+
+cache.max; // $ExpectType number
+cache.max = 1;
+
+cache.maxAge; // $ExpectType number
+cache.maxAge = 1;
+
+cache.set('foo', foo); // $ExpectType boolean
+cache.set(1, foo); // $ExpectError
+cache.set('foo', 1); // $ExpectError
+
+cache.get('foo'); // $ExpectType Foo | undefined
+cache.get(1); // $ExpectError
+
+cache.peek('foo'); // $ExpectType Foo | undefined
+cache.peek(1); // $ExpectError
+
+cache.has('foo'); // $ExpectType boolean
+cache.has(1); // $ExpectError
+
+cache.del('foo');
+cache.del(1); // $ExpectError
 
-cache.set(key, foo);
-foo = cache.get(key);
-foo = cache.peek(key);
-bool = cache.has(key);
-cache.del(key);
 cache.reset();
+cache.prune();
 
-cache.forEach((value: Foo, key: string, cache: lru.Cache<Foo>) => {
-
+cache.forEach(function(value, key, cache) {
+    value; // $ExpectType Foo
+    key; // $ExpectType string
+    cache; // $ExpectType Cache<string, Foo>
+    this; // $ExpectType Cache<string, Foo>
 });
-cache.forEach((value: Foo, key: string, cache: lru.Cache<Foo>) => {
+cache.forEach(function(value, key, cache) {
+    value; // $ExpectType Foo
+    key; // $ExpectType string
+    cache; // $ExpectType Cache<string, Foo>
+    this; // $ExpectType { foo(): void; }
+}, foo);
 
-}, x);
-cache.forEach((value, key, cache) => {
-	foo = cache.peek(key);
+cache.rforEach(function(value, key, cache) {
+    value; // $ExpectType Foo
+    key; // $ExpectType string
+    cache; // $ExpectType Cache<string, Foo>
+    this; // $ExpectType Cache<string, Foo>
 });
+cache.rforEach(function(value, key, cache) {
+    value; // $ExpectType Foo
+    key; // $ExpectType string
+    cache; // $ExpectType Cache<string, Foo>
+    this; // $ExpectType { foo(): void; }
+}, foo);
 
-strArr = cache.keys();
-fooArr  = cache.values();
+cache.keys(); // $ExpectType string[]
+cache.values(); // $ExpectType Foo[]
+
+const dump = cache.dump();
+dump; // $ExpectType LRUEntry<string, Foo>[]
+cache.load(dump);

types/lru-cache/tsconfig.json

@@ -6,7 +6,7 @@
         ],
         "noImplicitAny": true,
         "noImplicitThis": true,
-        "strictNullChecks": false,
+        "strictNullChecks": true,
         "baseUrl": "../",
         "typeRoots": [
             "../"
@@ -19,4 +19,4 @@
         "index.d.ts",
         "lru-cache-tests.ts"
     ]
-}
+}

types/lru-cache/tslint.json

@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }