Implement TypeScript types via JSDoc comments.

Author: jaydenseric

.eslintrc.json

@@ -1,3 +1,8 @@
 {
-  "extends": ["env"]
+  "extends": ["env"],
+  "settings": {
+    "jsdoc": {
+      "mode": "typescript"
+    }
+  }
 }

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "typescript.disableAutomaticTypeAcquisition": true,
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

CliError.mjs

@@ -1,15 +1,18 @@
+// @ts-check
+
 /**
  * A CLI error. Useful for anticipated CLI errors (such as invalid CLI
  * arguments) that don’t need to be displayed with a stack trace, vs unexpected
  * internal errors.
- * @kind class
- * @name CliError
- * @param {string} message Error message.
- * @ignore
  */
 export default class CliError extends Error {
-  constructor(...args) {
-    super(...args);
+  /** @param {string} message Error message. */
+  constructor(message) {
+    if (typeof message !== "string")
+      throw new TypeError("Argument 1 `message` must be a string.");
+
+    super(message);
+
     this.name = this.constructor.name;
   }
 }

CliError.test.mjs

@@ -0,0 +1,28 @@
+// @ts-check
+
+import { strictEqual, throws } from "assert";
+import CliError from "./CliError.mjs";
+
+/**
+ * Adds `CliError` tests.
+ * @param {import("test-director").default} tests Test director.
+ */
+export default (tests) => {
+  tests.add("`CliError` with argument 1 `message` not a string.", () => {
+    throws(() => {
+      new CliError(
+        // @ts-expect-error Testing invalid.
+        true
+      );
+    }, new TypeError("Argument 1 `message` must be a string."));
+  });
+
+  tests.add("`CliError` with arguments valid.", () => {
+    const message = "Message.";
+    const error = new CliError(message);
+
+    strictEqual(error instanceof Error, true);
+    strictEqual(error.name, "CliError");
+    strictEqual(error.message, message);
+  });
+};

analyseCoverage.mjs

@@ -1,20 +1,17 @@
+// @ts-check
+
 import fs from "fs";
 import { join } from "path";
 import { fileURLToPath } from "url";
 import v8Coverage from "@bcoe/v8-coverage";
 import sourceRange from "./sourceRange.mjs";
 
 /**
- * Analyzes [Node.js generated V8 JavaScript code coverage data](https://nodejs.org/api/cli.html#cli_node_v8_coverage_dir)
+ * Analyzes
+ * [Node.js generated V8 JavaScript code coverage data](https://nodejs.org/api/cli.html#cli_node_v8_coverage_dir)
  * in a directory; useful for reporting.
- * @kind function
- * @name analyseCoverage
  * @param {string} coverageDirPath Code coverage data directory path.
  * @returns {Promise<CoverageAnalysis>} Resolves the coverage analysis.
- * @example <caption>How to import.</caption>
- * ```js
- * import analyseCoverage from "coverage-node/analyseCoverage.mjs";
- * ```
  */
 export default async function analyseCoverage(coverageDirPath) {
   if (typeof coverageDirPath !== "string")
@@ -29,6 +26,7 @@ export default async function analyseCoverage(coverageDirPath) {
         fs.promises
           .readFile(join(coverageDirPath, fileName), "utf8")
           .then((coverageFileJson) => {
+            /** @type {import("@bcoe/v8-coverage").ProcessCov} */
             const { result } = JSON.parse(coverageFileJson);
             return {
               // For performance, filtering happens as early as possible.
@@ -53,18 +51,11 @@ export default async function analyseCoverage(coverageDirPath) {
     await Promise.all(filteredProcessCoverages)
   );
 
-  // The analysis will only include info useful for reporting.
+  /** @type {CoverageAnalysis} */
   const analysis = {
-    // Total number of files.
     filesCount: 0,
-
-    // Fully covered file paths.
     covered: [],
-
-    // File paths and ignored ranges.
     ignored: [],
-
-    // File paths and uncovered ranges.
     uncovered: [],
   };
 
@@ -83,17 +74,17 @@ export default async function analyseCoverage(coverageDirPath) {
       const uncovered = [];
 
       for (const range of uncoveredRanges) {
-        const { ignore, ...rangeDetails } = sourceRange(
+        const sourceCodeRange = sourceRange(
           source,
           range.startOffset,
           // The coverage data end offset is the first character after the
-          // range. For reporting to a user, it’s better to show the range
-          // as only the included characters.
+          // range. For reporting to a user, it’s better to show the range as
+          // only the included characters.
           range.endOffset - 1
         );
 
-        if (ignore) ignored.push(rangeDetails);
-        else uncovered.push(rangeDetails);
+        if (sourceCodeRange.ignore) ignored.push(sourceCodeRange);
+        else uncovered.push(sourceCodeRange);
       }
 
       if (ignored.length) analysis.ignored.push({ path, ranges: ignored });
@@ -104,3 +95,21 @@ export default async function analyseCoverage(coverageDirPath) {
 
   return analysis;
 }
+
+/**
+ * [Node.js generated V8 JavaScript code coverage data](https://nodejs.org/api/cli.html#cli_node_v8_coverage_dir)
+ * analysis; useful for reporting.
+ * @typedef {object} CoverageAnalysis
+ * @prop {number} filesCount Number of files analyzed.
+ * @prop {Array<string>} covered Covered file absolute paths.
+ * @prop {Array<SourceCodeRanges>} ignored Ignored source code ranges.
+ * @prop {Array<SourceCodeRanges>} uncovered Uncovered source code ranges.
+ */
+
+/**
+ * A source code file with ranges of interest.
+ * @typedef {object} SourceCodeRanges
+ * @prop {string} path File absolute path.
+ * @prop {Array<import("./sourceRange.mjs").SourceCodeRange>} ranges Ranges of
+ *   interest.
+ */

analyseCoverage.test.mjs

@@ -1,3 +1,5 @@
+// @ts-check
+
 import { deepStrictEqual, rejects } from "assert";
 import { spawn } from "child_process";
 import fs from "fs";
@@ -6,12 +8,19 @@ import disposableDirectory from "disposable-directory";
 import analyseCoverage from "./analyseCoverage.mjs";
 import childProcessPromise from "./childProcessPromise.mjs";
 
+/**
+ * Adds `reportCliError` tests.
+ * @param {import("test-director").default} tests Test director.
+ */
 export default (tests) => {
   tests.add(
     "`reportCliError` with first argument `coverageDirPath` not a string.",
     async () => {
       await rejects(
-        analyseCoverage(true),
+        analyseCoverage(
+          // @ts-expect-error Testing invalid.
+          true
+        ),
         new TypeError("First argument `coverageDirPath` must be a string.")
       );
     }
@@ -177,6 +186,7 @@ export default (tests) => {
             path: filePath,
             ranges: [
               {
+                ignore: false,
                 start: {
                   offset: 0,
                   line: 1,
@@ -189,6 +199,7 @@ export default (tests) => {
                 },
               },
               {
+                ignore: false,
                 start: {
                   offset: 17,
                   line: 1,

changelog.md

@@ -10,14 +10,19 @@
 - Removed `./package` from the package `exports` field; the full `package.json` filename must be used in a `require` path.
 - Removed the package main index module; deep imports must be used.
 - Shortened public module deep import paths, removing the `/public/`.
+- Implemented TypeScript types via JSDoc comments.
 
 ### Patch
 
 - Simplified package scripts.
+- Check TypeScript types via a new package `types` script.
+- Fixed various type related issues.
 - Also run GitHub Actions CI with Node.js v17, and drop v15.
 - Configured Prettier option `singleQuote` to the default, `false`.
 - Reorganized the test file structure.
 - Renamed imports in the test index module.
+- Added `CliError` class tests.
+- Runtime type check `CLiError` constructor arguments.
 - Readme tweaks.
 
 ## 5.0.1

childProcessPromise.mjs

@@ -1,12 +1,15 @@
+// @ts-check
+
 import { ChildProcess } from "child_process";
 
 /**
  * Promisifies a Node.js child process.
- * @kind function
- * @name childProcessPromise
  * @param {ChildProcess} childProcess Node.js child process.
- * @returns {Promise<{exitCode: number, signal: string}>} Resolves the exit code if the child exited on its own, or the signal by which the child process was terminated.
- * @ignore
+ * @returns {Promise<{
+ *   exitCode: number | null,
+ *   signal: NodeJS.Signals | null
+ * }>} Resolves the exit code if the child exited on its own, or the signal by
+ *   which the child process was terminated.
  */
 export default async function childProcessPromise(childProcess) {
   if (!(childProcess instanceof ChildProcess))

childProcessPromise.test.mjs

@@ -1,12 +1,21 @@
+// @ts-check
+
 import { rejects } from "assert";
 import childProcessPromise from "./childProcessPromise.mjs";
 
+/**
+ * Adds `childProcessPromise` tests.
+ * @param {import("test-director").default} tests Test director.
+ */
 export default (tests) => {
   tests.add(
     "`childProcessPromise` with first argument `childProcess` not a `ChildProcess` instance.",
     async () => {
       await rejects(
-        childProcessPromise(true),
+        childProcessPromise(
+          // @ts-expect-error Testing invalid.
+          true
+        ),
         new TypeError(
           "First argument `childProcess` must be a `ChildProcess` instance."
         )

coverage-node.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @ts-check
 
 import { spawn } from "child_process";
 import disposableDirectory from "disposable-directory";
@@ -15,10 +16,7 @@ import reportCoverage from "./reportCoverage.mjs";
  * Powers the `coverage-node` CLI. Runs Node.js with the given arguments and
  * coverage enabled. An analysis of the coverage is reported to the console, and
  * if coverage isn’t complete the process exits with code `1`.
- * @kind function
- * @name coverageNode
  * @returns {Promise<void>} Resolves when all work is complete.
- * @ignore
  */
 async function coverageNode() {
   try {
@@ -43,7 +41,7 @@ async function coverageNode() {
           const analysis = await analyseCoverage(tempDirPath);
           reportCoverage(analysis);
           if (analysis.uncovered.length) process.exitCode = 1;
-        } else process.exitCode = exitCode;
+        } else if (exitCode !== null) process.exitCode = exitCode;
       });
       // coverage ignore next line
     } else {
@@ -57,7 +55,7 @@ async function coverageNode() {
             `Skipped code coverage as Node.js is ${process.version}, v${minNodeVersion.major}.${minNodeVersion.minor}.${minNodeVersion.patch}+ is supported.`
           )}\n`
         );
-      else process.exitCode = exitCode;
+      else if (exitCode !== null) process.exitCode = exitCode;
     }
   } catch (error) {
     reportCliError(