eslint-good-throws

ESLint plugin enforcing @throws documentation and handling in TypeScript projects. Think Swift's throws keyword, but for TypeScript via lint rules.

Why

TypeScript has no native way to enforce exception handling. Functions can throw anything, and callers are never warned. This plugin fills that gap with two rules that work together to ensure thrown exceptions are always documented and handled.

Rules

require-throws-tag

Functions containing a throw statement must have a @throws JSDoc tag.

// Bad
function parse(input: string) {
  if (!input) throw new Error("empty");
}

// Good
/** @throws {Error} if input is empty */
function parse(input: string) {
  if (!input) throw new Error("empty");
}

handle-throws

When calling a function annotated with @throws, you must either:

1. Wrap the call in a try/catch block, or
2. Annotate the calling function with @throws to propagate it up

Supports cross-file resolution via the TypeScript type checker.

/** @throws {Error} if input is empty */
declare function parse(input: string): any;

// Bad
function run() {
  parse("");
}

// Good — handle it
function run() {
  try {
    parse("");
  } catch (e) {
    console.error(e);
  }
}

// Good — propagate it
/** @throws {Error} from parse */
function run() {
  parse("");
}

Installation

npm install eslint-good-throws

Setup

In your eslint.config.js (flat config, ESLint 9+):

import throws from "eslint-good-throws";
import tsParser from "@typescript-eslint/parser";

export default [
  {
    files: ["**/*.ts"],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        projectService: true,
      },
    },
    plugins: { throws },
    rules: {
      "throws/require-throws-tag": "error",
      "throws/handle-throws": "error",
    },
  },
];

Requirements

• ESLint >= 9
• TypeScript >= 5
• @typescript-eslint/parser with projectService enabled (for cross-file support in handle-throws)

License

MIT