Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/galvez/typejuice
Documentation generator for TypeScript Declaration Files inspired by godoc.
https://github.com/galvez/typejuice
Last synced: 10 days ago
JSON representation
Documentation generator for TypeScript Declaration Files inspired by godoc.
- Host: GitHub
- URL: https://github.com/galvez/typejuice
- Owner: galvez
- Created: 2021-12-24T04:19:47.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2021-12-24T19:52:58.000Z (almost 3 years ago)
- Last Synced: 2024-09-19T13:19:40.041Z (about 2 months ago)
- Language: JavaScript
- Homepage:
- Size: 41 KB
- Stars: 269
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# typejuice
Documentation generator for TypeScript Declaration Files inspired by [godoc](https://go.dev/blog/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](https://github.com/gdorsi) for the name idea (vite**press**, type**juice**)_.
```bash
npm i typejuice --save
```
## Introduction
[TypeScript Declaration Files](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html) 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](https://typedoc.org/guides/doccomments/).
### Examples
**Instead of using tags like @param, just have one function parameter per line**
*TypeScript Declaration File*
```ts
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*
**Multi-line comments on interface props**
*TypeScript Declaration File*
```ts
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*
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`)
## Basic Usage
```js
import TypeJuice from 'typejuice'
const tj = new TypeJuice('./sample.d.ts')
console.log(tj.toMarkdown())
```
## Vite integration
In **vite.config.js**:
```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](http://nearform.com/).
# License
MIT