# ts-code-api

> [![version](https://img.shields.io/npm/v/ts-code-api.svg)](https://www.npmjs.com/package/ts-code-api) ![license](https://img.shields.io/npm/l/ts-code-api.svg)

Latest version **0.4.2** (published 2020-07-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install ts-code-api
pnpm add ts-code-api
yarn add ts-code-api
bun add ts-code-api
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.2 |
| Published | 2020-07-12 |
| First published | 2019-09-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 63.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Maintainers | malcolmkee |
| Keywords | typescript, docs generation |

## Links

- npm: https://www.npmjs.com/package/ts-code-api
- Repository: https://github.com/malcolm-kee/ts-code-api
- Homepage: https://github.com/malcolm-kee/ts-code-api#readme
- Issues: https://github.com/malcolm-kee/ts-code-api/issues
- npm.io page: https://npm.io/package/ts-code-api

## Dependencies (1)

- [micromatch](https://npm.io/package/micromatch.md) ^4.0.2

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.4.2 (latest) — 2020-07-12
- 0.4.1 — 2020-07-12
- 0.4.0 — 2019-10-21
- 0.3.0 — 2019-09-22
- 0.2.1 — 2019-09-20
- 0.2.0 — 2019-09-20
- 0.1.2 — 2019-09-19
- 0.1.1 — 2019-09-05
- 0.1.0 — 2019-09-05

## README

# ts-code-api

[![version](https://img.shields.io/npm/v/ts-code-api.svg)](https://www.npmjs.com/package/ts-code-api) ![license](https://img.shields.io/npm/l/ts-code-api.svg)

Extract function and constants definitions with JSDocs comments from typescript code to a JavaScript object. You can then use this object generate documentations with your favorite template engine.

> If you want to output markdown, generate HTML then use converter library (e.g. [turndown](https://github.com/domchristie/turndown)) to convert them to markdown files.

## Installation

```bash
npm i -D ts-code-api
```

## Usage

Assuming that you have following typescript code `helper.ts` in `src` folder:

```ts
// @overview: Helper functions for mathematics calculations.
const add = (a: number, b: number) => a + b;

/**
 * Sum up a set of numbers
 * @param numbers numbers which you want to sum up
 * @returns sum of the numbers
 */
export const sum = (a: number, ...numbers: number[]) => numbers.reduce(add, a);

/**
 * Some magic number
 */
export const MAGIC_NUMBER: number = 89757;
```

Using this library:

```js
// your NodeJS script
const { tsDoc } = require('ts-code-api');

const output = tsDoc({
  files: ['src/helper.ts'],
});

console.log(output);
```

The output will be:

```json
[
  {
    "fileName": "helper",
    "fileComment": "Helper functions for mathematics calculations.",
    "items": [
      {
        "isFunction": true,
        "name": "sum",
        "typeString": "(a: number, ...numbers: number[]) => number",
        "comments": ["Sum up a set of numbers"],
        "params": [
          {
            "name": "a",
            "type": "number"
          },
          {
            "name": "numbers",
            "description": "numbers which you want to sum up",
            "type": "number[]"
          }
        ],
        "returns": {
          "type": "number",
          "description": "sum of the numbers"
        },
        "jsDocTags": [
          {
            "name": "param",
            "text": "numbers numbers which you want to sum up"
          },
          {
            "name": "returns",
            "text": "sum of the numbers"
          }
        ]
      },
      {
        "isFunction": false,
        "name": "MAGIC_NUMBER",
        "typeString": "number",
        "comments": ["Some magic number"],
        "jsDocTags": []
      }
    ]
  }
]
```

## Options

`tsDoc` accepts an options object as parameter. The options are:

- files (`string[]`, required): relative paths to files which you want to extract the typescript definitions. Note that you only need to provide the entries files; imported modules will automatically included.
- excludes (`string[]`, optional): pattern to exclude specific files. Example: `**/*.tsx`
- showPrivate (`boolean`, optional): make members tagged with `@private` to be exported. Default to `false`.
- warnIfParamMissingJsDoc (`boolean`, optional): warn if function parameter could not find is associated jsdoc comment. Default to `true`.

## Supported Features

Currently this library only supports function and constants. Many Typescript constructs (e.g. `type` and `interface`) are not supported intentionally because your JavaScript library documentation should not requires Typescript knowledge. `class` definition is currently not supported as I do not have use case of that; I seldom code in OOP.

- [x] function
- [x] constants
- [ ] class

## File Overview

> Warning: This is not a standard Typescript feature because there is no official way to provide file overview in current Typescript version as far as I know, so I invented my own convention. If you know the official supported syntaax to provide file overview in Typescript, raise an issue.

You can provide a short file overview for by adding `// @overview: <your description>` magic comment at _first line_ of the code.

## Comparisons with other libraries

[typedoc](https://typedoc.org/) is handy if you want a standardized format of Typescript documentation, but it doesn't allows you to easily extract the metadata and use your own rendering logic. I personally find the documentation structure confusing.

[api-extractor](https://api-extractor.com/) seems like allow you to do what this library does too, but it has higher learning curve.

---
_Source: https://npm.io/package/ts-code-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._