@types/eslint-plugin-jsdoc or bundle .d.ts

[snebjorn]

Motivation

With the new ESLint flat config we import plugins

import jsdoc from "eslint-plugin-jsdoc";

However that causes typescript in the VSCode to report an error due to missing type definitions.

Could not find a declaration file for module 'eslint-plugin-jsdoc'. 'myrepo/node_modules/eslint-plugin-jsdoc/dist/index.js' implicitly has an 'any' type.
Try npm i --save-dev @types/eslint-plugin-jsdoc if it exists or add a new declaration (.d.ts) file containing declare module 'eslint-plugin-jsdoc';

Current behavior

There are no types for eslint-plugin-jsdoc

Desired behavior

eslint-plugin-jsdoc should bundle the typescript types.

I'm not sure this is correct, but here's an example of the d.ts

import type { ESLint } from "eslint";

interface JSDoc extends ESLint.Plugin {
  configs: ESLint.Plugin["configs"] & {
    recommended: ESLint.ConfigData;
    ["recommended-error"]: ESLint.ConfigData;
    ["recommended-typescript"]: ESLint.ConfigData;
    ["recommended-typescript-error"]: ESLint.ConfigData;
    ["recommended-typescript-flavor"]: ESLint.ConfigData;
    ["recommended-typescript-flavor-error"]: ESLint.ConfigData;
  };
}

export default JSDoc;

Alternatives considered

A DefinitelyTyped package @types/eslint-plugin-jsdoc

[snebjorn]

#1139 added

eslint-plugin-jsdoc/package.json

Line 86 in e8b1475

"types": "./dist/index.d.ts",

but index.d.ts is missing from the distributed package

[paulshryock]

but index.d.ts is missing from the distributed package

That's because *.d.ts is explicitly ignored in .npmignore.

Looks like .npmignore should be updated to to not ignore index.d.ts.

[brettz9]

Yes, sorry, I inadvertently actually added that when merely considering adding it.

I'm afraid that with some projects rather conscious about package size, that the multiple generated files may become cumbersome for some.

We could submit this to DefinitelyTyped, as you say, using what we're already able to generate.

[snebjorn]

I don't understand why package size matters for a dev dependency - unless it's ridiculously large 😃

How big are the types? For comparison @typescript-eslint's types are 7 KB including .d.ts.map and 3.66 KB without. I'm not counting the AST types, as it doesn't seem relevant to using the package for linting.

Anyway, types bundled in the package is optimal but publishing a separate types package or via DefinitelyTyped also works 📦

[brettz9]

For our project, it's 76 KB / 49 KB (with and without map files).

I am also unclear on why it should matter (IDEs which rely on linting tools perhaps?), but it really apparently does given how much attention projects have given us to package size (#1141 being only the most recent). I'm not keen to garner complaints on this (especially when typing is not really so critical for ESLint config files, beyond suppressing complaints in IDEs) and then having to yank the new typing feature from those who do want it.

While there are some who consider it an anti-pattern to publish within the package due to semver noise, I personally prefer it myself (projects ideally shouldn't need to track transitive dependencies themselves), but feel it is unfortunately necessary at this point.

[what1s1ove]

Hey guys!

Since Eslint 9 is on the horizon, I think it's essential to pay more attention to this issue and start preparing for the changes 🙏

[brettz9]

I've submitted #1180 which should do the trick. It appears that it will be sufficient and feasible to only publish the index file types.

[what1s1ove]

I've submitted #1180 which should do the trick. It appears that it will be sufficient and feasible to only publish the index file types.

Thank you so much!