Skip to content

Documentation generator for TypeScript Declaration Files inspired by godoc.

Notifications You must be signed in to change notification settings

galvez/typejuice

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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

Generated Markdown

constructor

Multi-line comments on interface props

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;

Generated Markdown

interface
Supported Syntax
  • 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
TODO
  • Intersection Types
  • Type Aliases
  • Utility Types
  • Element type arrays or generic array types (type[], Array<type>)

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

About

Documentation generator for TypeScript Declaration Files inspired by godoc.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published