This standard
configuration understands that you want to use
typescript on .js
files using jsdoc
/ tsdoc
syntax.
The eslint
configuration knows all about jsdoc
& typescript
to give you improved type safety on .js
files with jsdoc
annotations.
This tsdocstandard
is here to help you convert a standard
JavaScript project into a JavaScript + jsdoc + typescript project.
To use tsdocstandard
you do need some dependencies, namely
npm install -D typescript
and a ./tsconfig.json
file.
Here is an example tsconfig.json
Once you run tsdocstandard
expect to get 100 warnings about
missing jsdoc annotations. That's the point, it will help you
convert your JavaScript to typed JavaScript with jsdoc comments.
Once you fix all the missing annotations expect almost 100%
type-coverage
; ( You can measure it with the
type-coverage
library ).
There's also a ts-standard linter.
However, that is meant to lint *.ts
typescript files. This project tsdocstandard
is to lint *.js
files used with tsc --checkJs
I found JS+JSDoc a better fit for open source libraries published to npm. TS is probably fine for a closed source app or server.
To use tsdocstandard
you want to replace standard
with tsdocstandard
and also install typescript
npm install tsdocstandard typescript -D
tsc && tsdocstandard
Since tsdocstandard
relies on typescript in jsdoc you want to
make sure your codebase "type checks" with tsc
before running
the linter with tsdocstandard
otherwise some lint rules will
fail due to a typescript type checking error.
To use typescript you need a tsconfig.json
; for example you can use
{
"compilerOptions": {
"types": ["node"],
"lib": ["es2018"],
"noEmit": true,
"module": "commonjs",
"allowJs": true,
"checkJs": true,
"noFallthroughCasesInSwitch": true,
"noImplicitReturns": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"strict": true,
"baseUrl": "./",
"paths": {
"*" : ["./types/*"]
}
},
"include": [
"types/**/*.d.ts",
"*.js",
"test/**/*.js"
]
}
If you want to migrate a larger codebase one file at it's
recommended you install both standard
& tsdocstandard
.
Then use the tsdocstandard
& standard
keys in package.json
{
"tsdocstandard": {
"ignore": [
"old-code.js"
]
},
"standard": {
"ignore": [
"new-code.js"
]
}
}
Basically run both linters and ignore the files that have and have not been migrated.
npm install -D typescript # dependency
npm install -D tsdocstandard
Currently tsdocstandard
is used in multiple repositories. I've
applied it to existing TS code as well as added to a vanilla JS
code.
I need to use this ruleset on a larger set of javascript files before I will be happy with it.
Any and all feedback is useful in issues or PRs
There are limitations with the following rules
no-unsafe-assignment
( https://github.com/typescript-eslint/typescript-eslint/issues/1943 )no-invalid-void-type
( https://github.com/typescript-eslint/typescript-eslint/pull/1960 )Add a tsdocstandard
key like documented for standard
https://standardjs.com/#how-do-i-ignore-files
I have standard
vscode installed. You can configure it on a
per project basis whether to use standard
; semistandard
or
standardx
. However if you edit the JSON file you can enter
an arbitrary string like tsdocstandard
.
As long as you install tsdocstandard
globally and edit the
VS code extension configuration to use the tsdocstandard
engine
which requires editing JSON as the UI only has three items in
the dropdown.
Importantly:
jsdoc
@eslint-typescript
There's lots of rules. Plus standard
as well.
Literally just like standard