Adopting JSDoc with varying levels of strictness.

[Raynos]

When using JSDoc together with typescript you can enforce varying levels of strictness as part of your tests, test suite & CI setup.

When we talk about strictness what we mean is "How many times does the type any show up in your codebase", aka if your project is 50% strict, that means its 50% statically typed & 50% "any" typed.

0% strictness (IDE only)

To use JSDoc with no strictness you can add a very simple jsconfig.json

{
  "compilerOptions": {
    "target": "es2018",
    "lib": ["es2018", "dom"],
    "noEmit": true,
    "module": "commonjs",
    "moduleResolution": "node",
    "resolveJsonModule": true
  },
  "exclude": ["node_modules"],
  "include": [
    "src/**/*.js",
    "src/**/*.d.ts"
  ]
}

And then leave you existing scripts in package.json as normal, for example

{
  "scripts": {
    "test": "node test/index.js"
  }
}

25% strictness

To increase the strictness of JSDoc in a codebase you can add strict: false to your jsconfig.json

{
  "compilerOptions": {
    ...
    "strict": false,
  }
}

Then you can enforce tsc in your package.json so that it fails the test suite like you would use a linter ( eslint or standard )

{
  "scripts": {
    "tsc": "tsc -p jsconfig.json --maxNodeModuleJsDepth 0",
    "test": "npm run tsc && node test/index.js"
  }
}

50% strictness

The next step for having strict static typed javascript with JSDoc is to turn strict: true in the jsconfig.json.

Nothing else really changes

90% strictness

Out of the box tsc is suprisingly lenient when it comes to type checking JavaScript, you want to use eslint

There's a seperate discussion about eslint + jsdoc but here i will use tsdocstandard as an example

{
  "scripts": {
    "tsc": "tsc -p jsconfig.json --maxNodeModuleJsDepth 0",
    "test": "npm run tsc && tsdocstandard && node test/index.js"
  }
}

100% strictness

The best way to get 100% type safety in a JavaScript + JSDoc project is to use the type-coverage command, you can add this to your package.json

{
  "scripts": {
    "tsc": "tsc -p jsconfig.json --maxNodeModuleJsDepth 0",
    "test": "npm run tsc && tsdocstandard && node test/index.js && npm run type-coverage",
    "type-coverage": "type-coverage -p jsconfig.json --ignore-catch --strict --at-least 100"
  }
}

By asking type-coverage you will know you are 100% strict, aka 0% any

[Rizary]

@Raynos is that < on the test part (last snipped) a typo? Do you have minimal example project that implements 100% strict?

[Raynos]

@Rizary that was a typo I meant , and must have hit SHIFT.

[Raynos]

As for example project see https://github.com/Raynos/lean.js/blob/master/package.json or any other project referenced from tsdocstandard ( https://github.com/Raynos/tsdocstandard#status-unstable ).

[voxpelli]

I added a post where we can select examples + started out with some of mines: #11

Can you add some of yours @Raynos? Maybe it helps you @Rizary?

[Raynos]

Added my examples there.

[voxpelli]

I myself often play around with modifiers on top of "strict": true, like decreasing the strictness by disabling these:

    "noImplicitAny": false,
    "strictNullChecks": false,

Then reactivating them as I move towards an ever stricter setup and then combining it with https://github.com/voxpelli/eslint-config-jsdoc-ts and since @Raynos suggested type-coverage I now also use it when I want the very highest level of strictness