orta / structured-types

Extract structured types from jsdoc and typescript files

About

structured-types is a collection of libraries using the Typescript Compiler API to generate "structured" type information from jsdoc and typescript files.

Motivation

• Extract full types for your libraries, not just string representations of the type.
• Plugin architecture, to extract custom types for frameworks such as react, vue, angular with the same package.

Roadmap

• JSDoc types
• Typescript types
• React plugin
• Typescript playground plugin
• component-controls integration
• Automatically generate README.md files (structured-md)
• Vue plugin
• Angular plugin

Getting started

1. Installation

$ npm install @structured-types/api --save-dev

2. Your API source file (sum.js):

/**
 * sum api function
 * @remarks
 * Unlike the summary, the remarks block may contain lengthy documentation content.
 * The remarks should not restate information from the summary, since the summary section
 * will always be displayed wherever the remarks section appears.  Other sections
 * (e.g. an `@example` block) will be shown after the remarks section.
 *
 * @param {number} a first parameter to add
 * @param {number} b second parameter to add
 * @returns {number} the sum of the two parameters
 *
 * @example
 *
 * ```js
 * import { sum } from './sum';
 *
 * expect(sum(1, 2)).toMatchObject({ a: 1, b: 2, result: 3});
 * ```
 */
export const sum = (a, b = 1) => ({ a, b, result: a + b });

3. Your documentation extraction

import { parseFiles } from '@structured-types/api';

const docs = parseFiles(['../src/sum.js']);

4. The result

{
  "sum": {
    "displayName": "sum",
    "kind": 11,
    "parameters": [
      {
        "kind": 2,
        "displayName": "a",
        "description": "first parameter to add"
      },
      {
        "kind": 2,
        "displayName": "b",
        "value": 1,
        "description": "second parameter to add"
      }
    ],
    "examples": [
      {
        "content": "```js\nimport { sum } from './sum';\n\nexpect(sum(1, 2)).toMatchObject({ a: 1, b: 2, result: 3});\n```"
      }
    ],
    "returns": {
      "description": "the sum of the two parameters",
      "kind": 2
    },
    "tags": [
      {
        "tag": "remarks",
        "content": "Unlike the summary, the remarks block may contain lengthy documentation content.\nThe remarks should not restate information from the summary, since the summary section\nwill always be displayed wherever the remarks section appears.  Other sections\n(e.g. an `@example` block) will be shown after the remarks section."
      }
    ],
    "description": "sum api function"
  }
}