Start using jsdoc as a type checking system

[Raruto]

Abstract

Visual Studio Code (and many other IDEs) includes built-in JavaScript IntelliSense: debugging, formatting, code navigation, auto-imports, refactorings, etc.

To make these features really usable (to everyone), it is necessary to include into the project at least one of the following files and then start documenting the code with the most basic type checking system available: JSDoc

• jsconfig.json
• tsconfig.json

Below, some recommended reading to get started on the subject:

• Types without typescript
• Javascript programming (vscode docs)
• Typescript programming (vscode docs)

---

JS Projects Utilizing TypeScript

The type system in TypeScript has different levels of strictness when working with a codebase:

• A type-system based only on inference with JavaScript code
• Incremental typing in JavaScript via JSDoc
• Using // @ts-check in a JavaScript file
• TypeScript code
• TypeScript with strict enabled

Each step represents a move towards a safer type-system, but not every project needs that level of verification.

TypeScript with JavaScript

This is when you use an editor which uses TypeScript to provide tooling like auto-complete, jump to symbol and refactoring tools like rename.
The homepage has a list of editors which have TypeScript plugins.

Providing Type Hints in JS via JSDoc

In a .js file, types can often be inferred. When types can't be inferred, they can be specified using JSDoc syntax.

JSDoc annotations come before a declaration will be used to set the type of that declaration. For example:

/** @type {number} */
var x;
x = 0; // OK
x = false; // OK?!

You can find the full list of supported JSDoc patterns in JSDoc Supported Types.

@ts-check

The last line of the previous code sample would raise an error in TypeScript, but it doesn't by default in a JS project.
To enable errors in your JavaScript files add: // @ts-check to the first line in your .js files to have TypeScript raise it as an error.

// @ts-check
// @errors: 2322
/** @type {number} */
var x;
x = 0; // OK
x = false; // Not OK

If you have a lot of JavaScript files you want to add errors to then you can switch to using a jsconfig.json.
You can skip checking some files by adding a // @ts-nocheck comment to files.

TypeScript may offer you errors which you disagree with, in those cases you can ignore errors on specific lines by adding // @ts-ignore or // @ts-expect-error on the preceding line.

// @ts-check
/** @type {number} */
var x;
x = 0; // OK
// @ts-expect-error
x = false; // Not OK

To learn more about how JavaScript is interpreted by TypeScript read How TS Type Checks JS

---

Creating .d.ts Files from .js files

With TypeScript 3.7, TypeScript added support for generating .d.ts files from JavaScript using JSDoc syntax.

This set up means you can own the editor experience of TypeScript-powered editors without porting your project to TypeScript, or having to maintain .d.ts files in your codebase.

TypeScript supports most JSDoc tags, you can find the reference here.

Setting up your Project to emit .d.ts files

To add creation of .d.ts files in your project, you will need to do up-to four steps:

• Add TypeScript to your dev dependencies
• Add a tsconfig.json to configure TypeScript
• Run the TypeScript compiler to generate the corresponding d.ts files for JS files
• (optional) Edit your package.json to reference the types

Adding TypeScript

You can learn how to do this in our installation page.

TSConfig

The TSConfig is a jsonc file which configures both your compiler flags, and declare where to find files.
In this case, you will want a file like the following:

{

  // Change this to match your project
  "include": ["src/**/*"],

  "compilerOptions": {

    // Tells TypeScript to read JS files, as
    // normally they are ignored as source files
    "allowJs": true,

    // Generate d.ts files
    "declaration": true,

    // This compiler run should
    // only output d.ts files
    "emitDeclarationOnly": true,

    // Types should go into this directory.
    // Removing this would place the .d.ts files
    // next to the .js files
    "outDir": "dist",

    // go to js file when using IDE functions like
    // "Go to Definition" in VSCode
    "declarationMap": true

  }

}

You can learn more about the options in the tsconfig reference.

An alternative to using a TSConfig file is the CLI, this is the same behavior as a CLI command.

npx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types

Run the compiler

You can learn how to do this in our installation page.
You want to make sure these files are included in your package if you have the files in your project's .gitignore.

Editing the package.json

TypeScript replicates the node resolution for modules in a package.json, with an additional step for finding .d.ts files.
Roughly, the resolution will first check the optional types field, then the "main" field, and finally will try index.d.ts in the root.

Package.json	Location of default .d.ts
No "types" field	checks "main", then index.d.ts
"types": "main.d.ts"	main.d.ts
"types": "./dist/main.js"	./dist/main.d.ts

If absent, then "main" is used

Package.json	Location of default .d.ts
No "main" field	index.d.ts
"main":"index.js"	index.d.ts
"main":"./dist/index.js"	./dist/index.d.ts

Tips

If you'd like to write tests for your .d.ts files, try tsd.

---

A Real world example: Open Layers v7.2.2

• openlayers/config/tsconfig-build.json

{
  "compilerOptions": {

    /* Basic Options */

    "target": "es2017",                     /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'. */
    "module": "es2020",                     /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */
    // "lib": [],                           /* Specify library files to be included in the compilation. */
    "allowJs": true,                        /* Allow javascript files to be compiled. */
    // "checkJs": true,                     /* Report errors in .js files. */
    // "jsx": "preserve",                   /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
    // "declaration": true,                 /* Generates corresponding '.d.ts' file. */
    // "declarationMap": true,              /* Generates a sourcemap for each corresponding '.d.ts' file. */
    "sourceMap": true,                      /* Generates corresponding '.map' file. */
    // "outFile": "./",                     /* Concatenate and emit output to single file. */
    "outDir": "../build/ol",                /* Redirect output structure to the directory. */
    // "rootDir": "./",                     /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
    // "composite": true,                   /* Enable project compilation */
    // "removeComments": true,              /* Do not emit comments to output. */
    // "noEmit": true,                      /* Do not emit outputs. */
    "importHelpers": false,                 /* Import emit helpers from 'tslib'. */
    // "downlevelIteration": true,          /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
    // "isolatedModules": true,             /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */

    /* Strict Type-Checking Options */

    "strict": false,                        /* Enable all strict type-checking options. */
    // "noImplicitAny": true,               /* Raise error on expressions and declarations with an implied 'any' type. */
    "strictNullChecks": true,               /* Enable strict null checks. */
    // "strictFunctionTypes": true,         /* Enable strict checking of function types. */
    // "strictBindCallApply": true,         /* Enable strict 'bind', 'call', and 'apply' methods on functions. */
    // "strictPropertyInitialization": true,/* Enable strict checking of property initialization in classes. */
    // "noImplicitThis": true,              /* Raise error on 'this' expressions with an implied 'any' type. */
    // "alwaysStrict": true,                /* Parse in strict mode and emit "use strict" for each source file. */

    /* Additional Checks */

    // "noUnusedLocals": true,              /* Report errors on unused locals. */
    // "noUnusedParameters": true,          /* Report errors on unused parameters. */
    // "noImplicitReturns": true,           /* Report error when not all code paths in function return a value. */
    // "noFallthroughCasesInSwitch": true,  /* Report errors for fallthrough cases in switch statement. */

    /* Module Resolution Options */

    "moduleResolution": "node",             /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
    // "baseUrl": "./",                     /* Base directory to resolve non-absolute module names. */
    // "paths": {},                         /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
    // "rootDirs": [],                      /* List of root folders whose combined content represents the structure of the project at runtime. */
    // "typeRoots": [],                     /* List of folders to include type definitions from. */
    // "types": [],                         /* Type declaration files to be included in compilation. */
    // "allowSyntheticDefaultImports": true,/* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
    "esModuleInterop": false,               /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
    // "preserveSymlinks": true,            /* Do not resolve the real path of symlinks. */

    /* Source Map Options */

    // "sourceRoot": "",                    /* Specify the location where debugger should locate TypeScript files instead of source locations. */
    // "mapRoot": "",                       /* Specify the location where debugger should locate map files instead of generated locations. */
    // "inlineSourceMap": true,             /* Emit a single file with source maps instead of having a separate file. */
    "inlineSources": false,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */
    "skipLibCheck": true
    /* Experimental Options */
    // "experimentalDecorators": true,      /* Enables experimental support for ES7 decorators. */
    // "emitDecoratorMetadata": true,       /* Enables experimental support for emitting type metadata for decorators. */
  },

  "include": [
    "../build/ol/**/*.js"
  ],

  "exclude": []
}

• openlayers/package.json

"scripts": {

 ...

  "generate-types": "tsc --project config/tsconfig-build.json --declaration --declarationMap --emitDeclarationOnly --outdir build/ol",
  "typecheck": "tsc --pretty",
  "apidoc-debug": "shx rm -rf build/apidoc && node --inspect-brk=9229 ./node_modules/jsdoc/jsdoc.js -R config/jsdoc/api/index.md -c config/jsdoc/api/conf.json -P package.json -d build/apidoc",
  "apidoc": "shx rm -rf build/apidoc && jsdoc -R config/jsdoc/api/index.md -c config/jsdoc/api/conf.json -P package.json -d build/apidoc"

 ...

}

• openlayers/tsconfig.json

{

  "compilerOptions": {

    /* Basic Options */

    "target": "ES2017",                       /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'. */
    "module": "commonjs",                     /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */
    "lib": ["es2017", "dom", "webworker"],    /* Specify library files to be included in the compilation. */
    "allowJs": true,                          /* Allow javascript files to be compiled. */
    "checkJs": true,                          /* Report errors in .js files. */
    "skipLibCheck": true,
    // "jsx": "preserve",                     /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
    // "declaration": true,                   /* Generates corresponding '.d.ts' file. */
    // "sourceMap": true,                     /* Generates corresponding '.map' file. */
    // "outFile": "./",                       /* Concatenate and emit output to single file. */
    // "outDir": "./",                        /* Redirect output structure to the directory. */
    // "rootDir": "./",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
    // "removeComments": true,                /* Do not emit comments to output. */
    "noEmit": true,                           /* Do not emit outputs. */
    // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
    // "downlevelIteration": true,            /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
    // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */

    /* Strict Type-Checking Options */

    "strict": false,                          /* Enable all strict type-checking options. */
    // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
    // "strictNullChecks": true,              /* Enable strict null checks. */
    // "strictFunctionTypes": true,           /* Enable strict checking of function types. */
    // "strictPropertyInitialization": true,  /* Enable strict checking of property initialization in classes. */
    // "noImplicitThis": true,                /* Raise error on 'this' expressions with an implied 'any' type. */
    // "alwaysStrict": true,                  /* Parse in strict mode and emit "use strict" for each source file. */

    /* Additional Checks */

    // "noUnusedLocals": true,                /* Report errors on unused locals. */
    // "noUnusedParameters": true,            /* Report errors on unused parameters. */
    // "noImplicitReturns": true,             /* Report error when not all code paths in function return a value. */
    // "noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */

    /* Module Resolution Options */

    // "moduleResolution": "node",            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
    // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */
    // "paths": {},                           /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
    // "rootDirs": [],                        /* List of root folders whose combined content represents the structure of the project at runtime. */
    // "typeRoots": [],                       /* List of folders to include type definitions from. */
    // "types": ["node"],                        /* Type declaration files to be included in compilation. */
    // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
    "esModuleInterop": true                   /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
    // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */

    /* Source Map Options */

    // "sourceRoot": "./",                    /* Specify the location where debugger should locate TypeScript files instead of source locations. */
    // "mapRoot": "./",                       /* Specify the location where debugger should locate map files instead of generated locations. */
    // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
    // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */

    /* Experimental Options */

    // "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
    // "emitDecoratorMetadata": true,         /* Enables experimental support for emitting type metadata for decorators. */

  },

  "include": [
    "types/**/*.ts",
    "src/ol/**/*.js"
  ]

}

• unpkg.com/[email protected]/