eslint-plugin-neverthrow-must-use

An ESLint plugin enforcing proper handling of neverthrow Result values.

You are forced to consume the result in one of the following three ways:

• Calling .match
• Calling .unwrapOr
• Calling ._unsafeUnwrap

📦 Installation

Install the plugin and required dependencies:

npm install neverthrow
npm install --save-dev eslint-plugin-neverthrow-must-use eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript

⚙️ Configuration

1️⃣ Create eslint.config.mjs

import neverthrowMustUse from "eslint-plugin-neverthrow-must-use"; // Import plugin
import tsPlugin from "@typescript-eslint/eslint-plugin"; // Import TypeScript plugin
import tsParser from "@typescript-eslint/parser"; // Import TypeScript parser

export default [
	{
		files: ["src/**/*.ts", "src/**/*.tsx"], // Apply to TypeScript files
		languageOptions: {
			parser: tsParser, // Set TypeScript parser
			parserOptions: {
				ecmaVersion: "latest",
				sourceType: "module",
				project: "./tsconfig.json", // Ensure ESLint reads tsconfig
				tsconfigRootDir: process.cwd(),
			},
		},
		plugins: {
			"@typescript-eslint": tsPlugin, // Enable TypeScript ESLint rules
			"neverthrow-must-use": neverthrowMustUse, // Register the plugin
		},
		rules: {
			"@typescript-eslint/no-unused-vars": "error", // Example TypeScript rule
			"neverthrow-must-use/must-use-result": "error", // Enforce `neverthrow` rule
		},
	},
];

2️⃣ Create tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}

❌ Incorrect Usage:

import { ok, err, Result } from "neverthrow";

function divide(a: number, b: number): Result<number, Error> {
  return b === 0 ? err(new Error("Cannot divide by zero")) : ok(a / b);
}

function main() {
  const result = divide(10, 2);
  result.map((value) => {
    console.log(value); // ❌ ESLint will throw an error
  });
}

✅ Correct Usage:

import { ok, err, Result } from "neverthrow";

function divide(a: number, b: number): Result<number, Error> {
  return b === 0 ? err(new Error("Cannot divide by zero")) : ok(a / b);
}

function main() {
  const result = divide(10, 2);
  result.match({
    ok: (value) => console.log(value),
    err: (error) => console.error(error),
  }); // ✅ Proper handling
}

🛠 Troubleshooting

1️⃣ Ensure ESLint is detecting the plugin

Run:

npx eslint --debug

You should see output showing that neverthrow-must-use is loaded.

2️⃣ If ESLint isn't enforcing the rule

Check that the plugin is installed:

npm ls eslint-plugin-neverthrow-must-use

If missing, reinstall it:

npm install --save-dev eslint-plugin-neverthrow-must-use

3️⃣ Ensure ESLint can find tsconfig.json

Run:

npx eslint --ext .ts,.tsx src

If you see an error like:

Cannot read file 'tsconfig.json': ENOENT: no such file or directory

Make sure tsconfig.json exists in your project.

📜 License

This project is licensed under the MIT License.

💡 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue.

📢 Acknowledgments

Inspired by functional programming best practices and the neverthrow library.