[utils] add types

Author: ljharb

.eslintrc

@@ -209,10 +209,10 @@
                     "exports": "always-multiline",
                     "functions": "never"
                 }],
-                "prefer-destructuring": "warn",
+                "prefer-destructuring": "off",
                 "prefer-object-spread": "off",
                 "prefer-rest-params": "off",
-                "prefer-spread": "warn",
+                "prefer-spread": "off",
                 "prefer-template": "off",
             }
         },

utils/.attw.json

@@ -0,0 +1,5 @@
+{
+  "ignoreRules": [
+    "cjs-only-exports-default"
+  ]
+}

utils/.npmignore

@@ -0,0 +1 @@
+.attw.json

utils/CHANGELOG.md

@@ -8,6 +8,9 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 ### Fixed
 - `parse`: also delete `parserOptions.EXPERIMENTAL_useProjectService` ([#2963], thanks [@JoshuaKGoldberg])
 
+### Changed
+- add types (thanks [@ljharb])
+
 ## v2.8.0 - 2023-04-14
 
 ### New

utils/ModuleCache.d.ts

@@ -0,0 +1,22 @@
+import type { ESLintSettings } from "./types";
+
+export type CacheKey = unknown;
+export type CacheObject = {
+    result: unknown;
+    lastSeen: ReturnType<typeof process.hrtime>;
+};
+
+declare class ModuleCache {
+    map: Map<CacheKey, CacheObject>;
+
+    constructor(map?: Map<CacheKey, CacheObject>);
+
+    get<T>(cacheKey: CacheKey, settings: ESLintSettings): T | undefined;
+
+    set<T>(cacheKey: CacheKey, result: T): T;
+
+    static getSettings(settings: ESLintSettings): { lifetime: number } & Omit<ESLintSettings['import/cache'], 'lifetime'>;
+}
+export default ModuleCache;
+
+export type { ModuleCache }

utils/ModuleCache.js

@@ -4,26 +4,26 @@ exports.__esModule = true;
 
 const log = require('debug')('eslint-module-utils:ModuleCache');
 
+/** @type {import('./ModuleCache').ModuleCache} */
 class ModuleCache {
+  /** @param {typeof import('./ModuleCache').ModuleCache.prototype.map} map */
   constructor(map) {
-    this.map = map || new Map();
+    this.map = map || /** @type {{typeof import('./ModuleCache').ModuleCache.prototype.map} */ new Map();
   }
 
-  /**
-   * returns value for returning inline
-   * @param {[type]} cacheKey [description]
-   * @param {[type]} result   [description]
-   */
+  /** @type {typeof import('./ModuleCache').ModuleCache.prototype.set} */
   set(cacheKey, result) {
     this.map.set(cacheKey, { result, lastSeen: process.hrtime() });
     log('setting entry for', cacheKey);
     return result;
   }
 
+  /** @type {typeof import('./ModuleCache').ModuleCache.prototype.get} */
   get(cacheKey, settings) {
     if (this.map.has(cacheKey)) {
       const f = this.map.get(cacheKey);
       // check freshness
+      // @ts-expect-error TS can't narrow properly from `has` and `get`
       if (process.hrtime(f.lastSeen)[0] < settings.lifetime) { return f.result; }
     } else {
       log('cache miss for', cacheKey);
@@ -32,19 +32,21 @@ class ModuleCache {
     return undefined;
   }
 
-}
-
-ModuleCache.getSettings = function (settings) {
-  const cacheSettings = Object.assign({
-    lifetime: 30,  // seconds
-  }, settings['import/cache']);
+  /** @type {typeof import('./ModuleCache').ModuleCache.getSettings} */
+  static getSettings(settings) {
+    /** @type {ReturnType<typeof ModuleCache.getSettings>} */
+    const cacheSettings = Object.assign({
+      lifetime: 30,  // seconds
+    }, settings['import/cache']);
+
+    // parse infinity
+    // @ts-expect-error the lack of type overlap is because we're abusing `cacheSettings` as a temporary object
+    if (cacheSettings.lifetime === '∞' || cacheSettings.lifetime === 'Infinity') {
+      cacheSettings.lifetime = Infinity;
+    }
 
-  // parse infinity
-  if (cacheSettings.lifetime === '∞' || cacheSettings.lifetime === 'Infinity') {
-    cacheSettings.lifetime = Infinity;
+    return cacheSettings;
   }
-
-  return cacheSettings;
-};
+}
 
 exports.default = ModuleCache;

utils/declaredScope.d.ts

@@ -0,0 +1,8 @@
+import { Rule, Scope } from 'eslint';
+
+declare function declaredScope(
+    context: Rule.RuleContext,
+    name: string
+): Scope.Scope['type'] | undefined;
+
+export default declaredScope;

utils/declaredScope.js

@@ -2,9 +2,10 @@
 
 exports.__esModule = true;
 
+/** @type {import('./declaredScope').default} */
 exports.default = function declaredScope(context, name) {
   const references = context.getScope().references;
   const reference = references.find((x) => x.identifier.name === name);
-  if (!reference) { return undefined; }
+  if (!reference || !reference.resolved) { return undefined; }
   return reference.resolved.scope.type;
 };

utils/hash.d.ts

@@ -0,0 +1,14 @@
+import type { Hash } from 'crypto';
+
+declare function hashArray(value: Array<unknown>, hash?: Hash): Hash;
+
+declare function hashObject<T extends object>(value: T, hash?: Hash): Hash;
+
+declare function hashify(
+    value: Array<unknown> | object | unknown,
+    hash?: Hash,
+): Hash;
+
+export default hashify;
+
+export { hashArray, hashObject };

utils/hash.js

@@ -11,6 +11,7 @@ const createHash = require('crypto').createHash;
 
 const stringify = JSON.stringify;
 
+/** @type {import('./hash').default} */
 function hashify(value, hash) {
   if (!hash) { hash = createHash('sha256'); }
 
@@ -26,6 +27,7 @@ function hashify(value, hash) {
 }
 exports.default = hashify;
 
+/** @type {import('./hash').hashArray} */
 function hashArray(array, hash) {
   if (!hash) { hash = createHash('sha256'); }
 
@@ -41,13 +43,15 @@ function hashArray(array, hash) {
 hashify.array = hashArray;
 exports.hashArray = hashArray;
 
-function hashObject(object, hash) {
-  if (!hash) { hash = createHash('sha256'); }
+/** @type {import('./hash').hashObject} */
+function hashObject(object, optionalHash) {
+  const hash = optionalHash || createHash('sha256');
 
   hash.update('{');
   Object.keys(object).sort().forEach((key) => {
     hash.update(stringify(key));
     hash.update(':');
+    // @ts-expect-error the key is guaranteed to exist on the object here
     hashify(object[key], hash);
     hash.update(',');
   });