@structured-types/api

api to extract structured type information from typescript types and jsdoc comments

Usage no npm install needed!

<script type="module">
  import structuredTypesApi from 'https://cdn.skypack.dev/@structured-types/api';
</script>

README

Table of contents

Overview

Extract structured documentation from javascript and typescript files using a combination of typescript types and jsdoc comments.

Comparable libraries

jsdoc typedoc ts-json-schema-generator documentation.js react-docgen-typescript react-docgen

Motivation

The creation of structured-types comes from the need for a library that can be used to document as well as instrument typescript and javascript code. The currently existing libraries are mostly meant just for documenting code.

  • Extract fully structured types, that can be used to fully interact with the analyzed code - this can be used to automatically create tests, examples, etc.
  • Use typescript types if available and supplement the type information with any jsdoc comments.
  • Extract documentation down to the member-level - for example for an enum extract comments for the enum type, as well as for the individual enum member fields.
  • Swiss-army extensible architecture using resolution plugins, where the library can be used to analyze typescript files, as well as extract react, angular, and more framework-specific types.

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": {
    "name": "sum",
    "kind": 11,
    "parameters": [
      {
        "kind": 2,
        "name": "a",
        "description": "first parameter to add"
      },
      {
        "kind": 2,
        "name": "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"
  }
}

API

parseFiles

function

API to analyze the given files by also loading the local typescript options from tsconfig

defined in @structured-types/api/packages/api/src/index.ts

parameters

Name Type Description
files* string[] list of files to be processed
options* DocsOptions parsing options
programOptions ProgramOptions typescript ts.program and ts.compilerHost
returns PropTypes the parsed types

example

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

const props = parseFiles(['index.ts'], {
 collectHelpers: true,
 collectSourceInfo: true,
})

analyzeFiles

function

API to analyze the given files

defined in @structured-types/api/packages/api/src/index.ts

parameters

Name Type Description
files* string[] list of files to be processed
options* DocsOptions parsing options
programOptions* ProgramOptions typescript ts.program and ts.compilerHost
returns PropTypes the parsed types

example

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

const props = analyzeFiles(['index.ts'], {
 collectHelpers: true,
 collectSourceInfo: true,
 tsOptions: {
   allowJs: true,
 }
})

DocsOptions

type

defined in @structured-types/api/packages/api/src/ts-utils.ts

properties

Name Type Parent Default Description
tsOptions ts.CompilerOptions
internalTypes Record<string, PropKind> ParseOptions internal types - libs by default includes classes such as String , Function ...
extract string[] ParseOptions list of export names to be extracted. by default all exports are extracted
filter function (
prop*: PropType
) => boolean
ParseOptions filter properties function. By default filter out all props with ignore === true
isInternal function (
file*: SourceFile
node*: Node
) => boolean | undefined
ParseOptions callback function to determine if a node is an internal (typescript) symbol return undefined if you need to use the default isInternal processing
maxDepth number ParseOptions 6 max depth for extracting child props.
collectHelpers boolean ParseOptions whether to save "helper" props that are used by the main parsed props if set to false will result in a smaller result set
collectGenerics boolean ParseOptions true whether to collect generics parameters
collectParameters boolean ParseOptions true whether to collect function parameters
collectParametersUsage boolean ParseOptions whether to collect function parameters usage locations within the function body
collectProperties boolean ParseOptions true whether to collect object/type properties
collectInheritance boolean ParseOptions true whether to collect the inheritance properties
collectExtension boolean ParseOptions true whether to collect the plugin/extension name
collectDiagnostics boolean ParseOptions whether to collect errors/diagnostics
collectAliasName boolean ParseOptions true whether to collect alias names - for example: when imported default symbol from another file, this will be the import name
collectInternals boolean ParseOptions whether to collect internal (typescript) symbols
plugins ParsePlugin[] ParseOptions installed plugins can modify default options and install type resolvers
scope "exports" | "all" ParseOptions by default collects only the exported symbols
collectSourceInfo boolean | "body" ParseOptions whether to collect the file path and the source code location for the symbol declarations. If set to 'body', the source will refer to the function body instead of the variable declaration.
collectInnerLocations boolean ParseOptions whether to collect the source code location for inner symbol declarations if set to true, the data will be collected in the loc prop
moduleCallback function (
module*: Symbol
checker*: TypeChecker
) => void
ParseOptions callback with the parsed module. Can be used to retrieve additional information such as the imports of a file etc.

ParseOptions

interface

parsing options

defined in @structured-types/api/packages/api/src/ts-utils.ts

properties

Name Type Default Description
internalTypes Record<string, PropKind> internal types - libs by default includes classes such as String , Function ...
extract string[] list of export names to be extracted. by default all exports are extracted
filter function (
prop*: PropType
) => boolean
filter properties function. By default filter out all props with ignore === true
isInternal function (
file*: SourceFile
node*: Node
) => boolean | undefined
callback function to determine if a node is an internal (typescript) symbol return undefined if you need to use the default isInternal processing
maxDepth number 6 max depth for extracting child props.
collectHelpers boolean whether to save "helper" props that are used by the main parsed props if set to false will result in a smaller result set
collectGenerics boolean true whether to collect generics parameters
collectParameters boolean true whether to collect function parameters
collectParametersUsage boolean whether to collect function parameters usage locations within the function body
collectProperties boolean true whether to collect object/type properties
collectInheritance boolean true whether to collect the inheritance properties
collectExtension boolean true whether to collect the plugin/extension name
collectDiagnostics boolean whether to collect errors/diagnostics
collectAliasName boolean true whether to collect alias names - for example: when imported default symbol from another file, this will be the import name
collectInternals boolean whether to collect internal (typescript) symbols
plugins ParsePlugin[] installed plugins can modify default options and install type resolvers
scope "exports" | "all" by default collects only the exported symbols
collectSourceInfo boolean | "body" whether to collect the file path and the source code location for the symbol declarations. If set to 'body', the source will refer to the function body instead of the variable declaration.
collectInnerLocations boolean whether to collect the source code location for inner symbol declarations if set to true, the data will be collected in the loc prop
moduleCallback function (
module*: Symbol
checker*: TypeChecker
) => void
callback with the parsed module. Can be used to retrieve additional information such as the imports of a file etc.

ProgramOptions

type

defined in @structured-types/api/packages/api/src/ts-utils.ts

properties

Name Type Description
host ts.CompilerHost
program ts.Program
hostCallback function (
host*: CompilerHost
) => void
callback with the created host, gives an opportunity to change some properties of the host.

PropTypes

type

Top-level prop type, with added optional __helpers and __diagnostics fields.

defined in @structured-types/api/packages/api/src/types.ts

properties

Name Type Description
anonymous [string]: PropType
__helpers Record<string, PropType> Utility symbols such as parent types are stored here. Only available if option collectHelpers is set to true.
__diagnostics PropDiagnostic[] Typescript program diagnostics / errors. Only available if option collectDiagnostics is set to true.

PropType

interface

Base prop type interface

defined in @structured-types/api/packages/api/src/types.ts

properties

Name Type Description
kind PropKind generic properties
name string name of the property
alias string alias - when the assigned property is being imported as an aliased name
parent PropParent Parent of a property field
loc SourceLocation source location of the symbol and source file position will be available when collectSourceInfo option is set to true
optional boolean by default, properties are required
readonly boolean readonly property
abstract boolean abstract property
async boolean async function
visibility "private" | "protected" | "public" property visibility
static boolean true, of the class property is static
type string type name of the property or lookup into __helpers list of symbols
extension string used plugin name ie 'react'...
description string jsdoc description
fires string[] jsdoc fires events list
see string[] jsdoc see links list
examples JSDocExample[] jsdoc examples list
tags JSDocPropTag[] jsdoc generic tags, not covered by other props
summary string jsdoc summary
deprecated string | true jsdoc deprecated tag
ignore boolean jsdoc ignore tag, to be excluded from documentations
usage type[] if collectParametersUsage option is set, this will collect parameters usage in function body

PropKind

enum

The property type or kind

defined in @structured-types/api/packages/api/src/types.ts

properties

Name Type Value
String* number 1
Number* number 2
Boolean* number 3
Union* number 4
Enum* number 5
Tuple* number 6
Rest* number 7
Undefined* number 8
Unknown* number 9
Null* number 10
Function* number 11
Void* number 12
Class* number 13
Interface* number 14
Type* number 15
Array* number 16
Any* number 17
Index* number 20
Constructor* number 21
Getter* number 22
Setter* number 23
BigInt* number 24
Component* number 25
Object* number 26
Namespace* number 27
RegEx* number 28

ParsePlugin

type

Plugin type - provides the plugin name and the type resolver

defined in @structured-types/api/packages/api/src/ts-utils.ts

properties

Name Type Parent Default Description
tsOptions ts.CompilerOptions DocsOptions
internalTypes Record<string, PropKind> ParseOptions internal types - libs by default includes classes such as String , Function ...
extract string[] ParseOptions list of export names to be extracted. by default all exports are extracted
filter function (
prop*: PropType
) => boolean
ParseOptions filter properties function. By default filter out all props with ignore === true
maxDepth number ParseOptions 6 max depth for extracting child props.
collectHelpers boolean ParseOptions whether to save "helper" props that are used by the main parsed props if set to false will result in a smaller result set
collectGenerics boolean ParseOptions true whether to collect generics parameters
collectParameters boolean ParseOptions true whether to collect function parameters
collectParametersUsage boolean ParseOptions whether to collect function parameters usage locations within the function body
collectProperties boolean ParseOptions true whether to collect object/type properties
collectInheritance boolean ParseOptions true whether to collect the inheritance properties
collectExtension boolean ParseOptions true whether to collect the plugin/extension name
collectDiagnostics boolean ParseOptions whether to collect errors/diagnostics
collectAliasName boolean ParseOptions true whether to collect alias names - for example: when imported default symbol from another file, this will be the import name
collectInternals boolean ParseOptions whether to collect internal (typescript) symbols
plugins ParsePlugin[] ParseOptions installed plugins can modify default options and install type resolvers
scope "exports" | "all" ParseOptions by default collects only the exported symbols
collectSourceInfo boolean | "body" ParseOptions whether to collect the file path and the source code location for the symbol declarations. If set to 'body', the source will refer to the function body instead of the variable declaration.
collectInnerLocations boolean ParseOptions whether to collect the source code location for inner symbol declarations if set to true, the data will be collected in the loc prop
moduleCallback function (
module*: Symbol
checker*: TypeChecker
) => void
ParseOptions callback with the parsed module. Can be used to retrieve additional information such as the imports of a file etc.
typesResolve* function (
props*
symbolType*: Type
declaration: ts.Declaration
parser*: ISymbolParser
expression: ts.Expression
) => ResolverReturnType | undefined
type resolving custom function ie from a react component will return the props type if the plugin does not recognize the type, should return undefined
pluginName string plugin name

PropDiagnostic

type

diagnostics row data

defined in @structured-types/api/packages/api/src/types.ts

properties

Name Type Description
category* error category
message* string error text message
row number source code line of the error
column number source code column of the error
fileName string source file name

PropParent

interface

Parent of a property field

defined in @structured-types/api/packages/api/src/types.ts

properties

Name Type Description
name* string the parent type name
loc SourceLocation optional source location. will be available when collectSourceInfo option is set to true

SourceLocation

interface

defined in @structured-types/api/packages/api/src/types.ts

properties

Name Type Description
filePath string name of the file where the symbol is defined only if different from the default file path
loc
SourcePositions
start*: SourcePosition
end*: SourcePosition
source code location for the symbol declaration

JSDocExample

interface

JSDoc example item

defined in @structured-types/api/packages/api/src/types.ts

properties

Name Type Description
caption string example caption/title
content string example source/content

JSDocPropTag

interface

JSDoc generic tag item

defined in @structured-types/api/packages/api/src/types.ts

properties

Name Type Description
tag* string tag name
content string optional tag content

SourcePosition

interface

defined in @structured-types/api/packages/api/src/types.ts

properties

Name Type Description
line* number source line of the symbol
col* number source column of the symbol

ResolverReturnType

type

defined in @structured-types/api/packages/api/src/ts-utils.ts

properties

Name Type Parent Default Description
type* ts.Type | undefined
initializer ts.Node
declaration ts.Node
prop PropType
pluginName string
isInternal function (
file*: SourceFile
node*: Node
) => boolean | undefined
ParseOptions callback function to determine if a node is an internal (typescript) symbol return undefined if you need to use the default isInternal processing
tsOptions ts.CompilerOptions DocsOptions
internalTypes Record<string, PropKind> ParseOptions internal types - libs by default includes classes such as String , Function ...
extract string[] ParseOptions list of export names to be extracted. by default all exports are extracted
filter function (
prop*: PropType
) => boolean
ParseOptions filter properties function. By default filter out all props with ignore === true
maxDepth number ParseOptions 6 max depth for extracting child props.
collectHelpers boolean ParseOptions whether to save "helper" props that are used by the main parsed props if set to false will result in a smaller result set
collectGenerics boolean ParseOptions true whether to collect generics parameters
collectParameters boolean ParseOptions true whether to collect function parameters
collectParametersUsage boolean ParseOptions whether to collect function parameters usage locations within the function body
collectProperties boolean ParseOptions true whether to collect object/type properties
collectInheritance boolean ParseOptions true whether to collect the inheritance properties
collectExtension boolean ParseOptions true whether to collect the plugin/extension name
collectDiagnostics boolean ParseOptions whether to collect errors/diagnostics
collectAliasName boolean ParseOptions true whether to collect alias names - for example: when imported default symbol from another file, this will be the import name
collectInternals boolean ParseOptions whether to collect internal (typescript) symbols
plugins ParsePlugin[] ParseOptions installed plugins can modify default options and install type resolvers
scope "exports" | "all" ParseOptions by default collects only the exported symbols
collectSourceInfo boolean | "body" ParseOptions whether to collect the file path and the source code location for the symbol declarations. If set to 'body', the source will refer to the function body instead of the variable declaration.
collectInnerLocations boolean ParseOptions whether to collect the source code location for inner symbol declarations if set to true, the data will be collected in the loc prop
moduleCallback function (
module*: Symbol
checker*: TypeChecker
) => void
ParseOptions callback with the parsed module. Can be used to retrieve additional information such as the imports of a file etc.

ISymbolParser

interface

defined in @structured-types/api/packages/api/src/ts-utils.ts

properties

Name Type
checker* TypeChecker
options* ParseOptions
parseProperties* function (
properties*
[number]: T
options*: ParseOptions
types: PropType[]
) => PropType[]
updateSymbolName* function (
prop*: PropType
node: ts.Declaration
) => PropType
parseType* function (
prop*: PropType
options*: ParseOptions
node: ts.Node
) => PropType
parseTypeValueComments* function (
prop*: PropType
options*: ParseOptions
declaration: ts.Node
initializer: ts.Node
) => PropType | null
parseSymbol* function (
symbol*: Symbol
options*: ParseOptions
) => PropType | undefined