Neolithic Psychedelic Mushrooms
    Wondering what’s next for npm?Check out our public roadmap! »

    tsdocstandard

    16.2.2 • Public • Published

    TSDoc Standard

    Standard but also use TypeScript on JS files with jsdoc.

    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.

    Motivation

    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 ).

    Comparison with ts-standard

    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

    Why use JS+JSDoc over TS ?

    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.

    • Using JS makes the package.json 10x simpler ( https://github.com/Raynos/fake-kms/pull/1/files#diff-b9cfc7f2cdf78a7f4b91a753d10865a2 )
    • No build step during development
    • External contributors for my library can just write JS, largest pool of possible contributors ( same reason i dont author/publish coffeescript )
    • The published artifact to npm is the one I wrote and is not some "compiled JS" output. Aka no source maps.
    • In general there are far fewer files checked into git with JS+JSDoc for a library published to npm.

    Usage

    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"
      ]
    }

    Migration

    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.

    Install

    npm install -D typescript # dependency
    npm install -D tsdocstandard

    Status (Unstable)

    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

    Known issues

    There are limitations with the following rules

    How to ignore files

    Add a tsdocstandard key like documented for standard https://standardjs.com/#how-do-i-ignore-files

    How to use in text editor.

    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.

    Rules

    Importantly:

    • jsdoc
    • @eslint-typescript

    There's lots of rules. Plus standard as well.

    Usage

    Literally just like standard

    Install

    npm i tsdocstandard

    DownloadsWeekly Downloads

    6

    Version

    16.2.2

    License

    MIT

    Unpacked Size

    39.3 kB

    Total Files

    12

    Last publish

    Collaborators

    • avatar