typejuice

Documentation generator for TypeScript Declaration Files inspired by godoc.

This repo contains two packages:

• typejuice: the JavaScript API library
• vite-plugin-typejuice: the Vite plugin for it.

Hat tip to Guido D'Orsi for the name idea (vitepress, typejuice).

npm i typejuice --save

Introduction

TypeScript Declaration Files have become a common addition to libraries, even those written in standard JavaScript, as a means of enhancing autocomplete behaviour of the exposed APIs.

There's a lot of overlap between documentation and these declaration files. This project attempts to bridge the gap by providing godoc-like comment extraction from .d.ts files while also inferring on types and signatures so you don't have to maintain the same information in two different places. It's a radically stripped down, minimalist analogue to typedoc.

Examples

Instead of using tags like @param, just have one function parameter per line

<table> <tr> <td>

TypeScript Declaration File

declare class Client extends Dispatcher {
  // Extends: `undici.Dispatcher`
  // A basic HTTP/1.1 client, mapped on top a single TCP/TLS connection. Pipelining is disabled by default.
  // Requests are not guaranteed to be dispatched in order of invocation.
  constructor(
    // Should only include the **protocol, hostname, and port**.
    url: string | URL,
    options?: Client.Options
  );

</td> </tr> <tr> <td>

Generated Markdown

<img width="733" alt="constructor" src="https://user-images.githubusercontent.com/12291/144707016-21605a86-600b-47cc-b290-858e72a070fa.png"> </td> </tr> </table>

Multi-line comments on interface props

<table> <tr> <td>

TypeScript Declaration File

declare namespace Client {
  export interface Options {
    // The timeout after which a request will time out, in milliseconds. 
    // Monitors time between receiving body data. Use `0` to disable it entirely.
    // Defaults to 30e3 (number), 30s in milliseconds
    bodyTimeout?: number | null;

    // The amount of time the parser will wait to receive the complete HTTP 
    // headers (Node 14 and above only). 
    // Defaults to 30e3 (number), 30s in milliseconds
    headersTimeout?: number | null;

</td> </tr> <tr> <td>

Generated Markdown

<img width="733" alt="interface" src="https://user-images.githubusercontent.com/12291/144706946-e438dd9e-14cd-4826-a983-ae824803bdea.png"> </td> </tr> </table> <details> <summary>Supported Syntax</summary>

• Top-level function and class declarations
• Single-file namespace declarations
• Constructor declarations – Primitive types such as string, number, boolean
• Primitive values such as null and undefined
• Union Types

</details> <details> <summary>TODO</summary>

• Intersection Types
• Type Aliases
• Utility Types
• Element type arrays or generic array types (type[], Array<type>)

</details>

Basic Usage

import TypeJuice from 'typejuice'

const tj = new TypeJuice('./sample.d.ts')

console.log(tj.toMarkdown())

Vite integration

In vite.config.js:

import { dirname } from 'path'
import { fileURLToPath } from 'url'
import TypeJuice from 'vite-plugin-typejuice'

export default {
  plugins: [
    TypeJuice({
      // Defaults to process.cwd()
      typeRoot: resolve(dirname(fileURLToPath(import.meta.url)), 'types'),
      // Defaults to only 'md'
      extensions: ['md'],
    })
  ],
}

In your Markdown files:

<<< typejuice:client.d.ts

This will insert the autogenerated markdown for client.d.ts under typeRoot.

Meta

Sponsored by NearForm.

License

MIT