typescript-docs-verifier

Verifies that typescript examples in markdown files actually compile.

Why?

Ever copied a TypeScript code example from a README and found that it didn't even compile? This tool can help by verifying that all of your code examples compile correctly. And yes, the TypeScript code samples in this README are checked using this tool.

Inspired the by the tut documentation compilation tool for scala.

How it works

The selected markdown files are searched for TypeScript code blocks marked like this:

```typescript
// Some TypeScript code here
```

These code blocks are extracted and any imports from the current project are replaced with an import of the main or exports file (see below) from package.json (e.g. import { compileSnippets } from 'typescript-docs-verifier' would be replaced with import { compileSnippets } from './dist/index' for this project).

Each code snippet is compiled (but not run) and any compilation errors are reported. Code snippets must compile independently from any other code snippets in the file.

Ignoring code blocks

Individual code blocks can be ignored by preceding them with a <!-- ts-docs-verifier:ignore --> comment:

<!-- ts-docs-verifier:ignore -->
```typescript
// This block won't be compiled by typescript-docs-verifier
```

Script usage

node_modules/.bin/typescript-docs-verifier [--input-files <markdown-files-to-test>]

• --input-files is optional and defaults to README.md.
• Any compilation errors will be reported on the console.
• The exit code is 1 if there are any compilation errors and 0 otherwise.

Library usage

TypeScript

import { compileSnippets, SnippetCompilationResult } from 'typescript-docs-verifier'
import * as http from 'http'

const inputFiles = ['README', 'examples.md'] // defaults to 'README.md' if not provided
compileSnippets(inputFiles)
  .then((results: SnippetCompilationResult[]) => {
    results.forEach((result: SnippetCompilationResult) => {
      if (result.error) {
        console.log(`Error compiling example code block ${result.index} in file ${result.file}`)
        console.log(result.error.message)
        console.log('Original code:')
        console.log(result.snippet)
      }
    })
  })
  .catch((error) => {
    console.error('Error compiling TypeScript snippets', error)
  })

JavaScript

const { compileSnippets } = require('typescript-docs-verifier')

const inputFiles = ['README.md', 'examples.md'] // defaults to 'README.md' if not provided
compileSnippets(inputFiles)
  .then((results) => {
    results.forEach((result) => {
      if (result.error) {
        console.log(`Error compiling example code block ${result.index} in file ${result.file}`)
        console.log(result.error.message)
        console.log('Original code:')
        console.log(result.snippet)
      }
    })
  })
  .catch((error) => {
    console.error('Error compiling TypeScript snippets', error)
  })

exports resolution

The exports property of package.json is rather complex. Currently this library does not support SubPath exports and will always prefer the require conditional export to the import conditional export (since ESM support in TypeScript is still experimental at this time). Supported exports patterns at the current time are:

{
  exports: "./path/to/file.js"
}

{
  exports: {
    ".": "./path/to/file.js"
  }
}

{
  exports: {
    "require|node-addons|node|default": "./path/to/file.js"
  }
}

{
  exports: {
    "require|node-addons|node|default": {
      ".": "./path/to/file.js"
    }
  }
}

Development

Run the tests:

npm install
npm test

Contributing

See these notes for information for contributors.

License

typescript-docs-verifier is available to all via the Apache-2.0 license.

Copyright © 2017 BBC