Awesome
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
andundefined
- Union Types
- 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