jsdoctypeparser

What is jsdoctypeparser?

The jsdoctypeparser npm package is a tool for parsing and manipulating JSDoc type expressions. It allows developers to parse JSDoc type strings into an abstract syntax tree (AST) and then manipulate or analyze these types programmatically.

What are jsdoctypeparser's main functionalities?

Parsing JSDoc Type Strings

This feature allows you to parse a JSDoc type string into an abstract syntax tree (AST). The code sample demonstrates how to parse the type string 'Array.<string>' and output the resulting AST.

const { parse } = require('jsdoctypeparser');
const typeString = 'Array.<string>';
const ast = parse(typeString);
console.log(JSON.stringify(ast, null, 2));

Stringifying AST Back to JSDoc Type String

This feature allows you to convert an AST back into a JSDoc type string. The code sample shows how to parse a type string into an AST and then convert it back to a string.

const { parse, stringify } = require('jsdoctypeparser');
const typeString = 'Array.<string>';
const ast = parse(typeString);
const newTypeString = stringify(ast);
console.log(newTypeString);

Handling Complex Type Expressions

This feature demonstrates the ability to handle complex JSDoc type expressions. The code sample parses a complex type string representing an object with properties of different types.

const { parse } = require('jsdoctypeparser');
const complexTypeString = '{a: number, b: string|boolean}';
const ast = parse(complexTypeString);
console.log(JSON.stringify(ast, null, 2));

Other packages similar to jsdoctypeparser

doctrine

Doctrine is a popular library for parsing JSDoc comments, including type expressions. It provides a more comprehensive solution for parsing entire JSDoc comments, not just type strings. Compared to jsdoctypeparser, Doctrine offers broader functionality but may be more complex to use if you only need to parse type expressions.

comment-parser

Comment-parser is a library for parsing JavaScript comments, including JSDoc comments. It focuses on extracting and parsing comments from source code, including type annotations. While it provides similar functionality for parsing JSDoc types, it is more focused on the overall comment structure rather than just type expressions.

README

Jsdoc strict type parser

This module is Jsdoc type expression parser.

This parser provide:

• Parse strict
• Build DOM
• Convert a type name to a link by using toHtml()

This parser can parse:

• JsDoc type expressions
  • foo.bar, String[]
• Closure Compiler type expressions
  • Array.<string>, function(this: Objext, arg1, arg2): ret
• Nested type expressions
  • Array.<Array.<string>>, function(function(Function))

Parsing

var Parser = require('jsdoctypeparser').Parser;
var parser = new Parser();
var result = parser.parse('Array.<string|number, ?Object=>|string|undefined');

The result is:

{
  optional: true,
  types: [
    {
      parameterTypeUnions: [
        {
          types: [
            { name: 'string' },
            { name: 'number' }
          ]
        },
        {
          nullable: true
          optional: true
          types: [
            { name: 'Object' }
          ]
        }
      ]
    }, {
      { name: 'string' }
    }
  ]
}

DOM Specification

Type name

TypeName = {
  name: string
};

Type Union

TypeUnion = {
  optional: boolean,
  nullable: boolean,
  variable: boolean,
  nonNullable: boolean,
  all: boolean,
  unknown: boolean,
  types: Array.<TypeName|GenericType|FunctionType|RecordType>
};

Generic type

GenericType = {
  genericTypeName: string,
  parameterTypeUnions: Array.<TypeUnion>
};

Function type

FunctionType = {
  parameterTypeUnions: Array.<TypeUnion>,
  returnTypeUnion: TypeUnion|null,
  isConstructor: boolean,
  contextTypeUnion: TypeUnion|null
};

Record type

RecordType = {
  entries: Array.<RecordEntry>
};

RecordEntry = {
  name: string,
  typeUnion: TypeUnion
};

Publishing

var Parser = require('jsdoctypeparser).Parser;
var parser = new Parser();
var result = parser.parse('Array.<MyClass>=');

• result.toString() ⇒ 'Array.<MyClass>|undefined'

• result.toHtml() ⇒ 'Array.&lt;<a href="MyClass.html">MyClass</a>&gt;|undefined'

Customize type name URI

You can change a file URL by set TypeBulder.TypeName.getUrlByTypeName(typeName).

var Builder = require('jsdoctypeparser').Builder;
Bulder.TypeName.getUrlByTypeName = function(typeName) {
  // do something.
  return typeName;
}; 

License

This script licensed under the MIT. See: http://orgachem.mit-license.org