@typedefs/parser
Version:
The Parser For JSDoc Types.
185 lines (148 loc) • 9.89 kB
Markdown
# @typedefs/parser
[](https://npmjs.org/package/@typedefs/parser)
`@typedefs/parser` is The Parser For _JSDoc_ Types Written Using Google Closure Compiler Annotations (no _TypeScript_ support). Although most of the typing rules are the same, the main difference is for functions and arrays:
- ✅ `function(string, number=): void`
- ⛔️ `(arg: string, optional?: number) => void` The arrow function notation is not supported. Cannot write `?` for optional arguments, need to use `=`.
- ✅ `!Array<string>`
- ⛔️ `string[]` The double array bracket notation will not work.
- ✅ `{ record: (string|undefined) }`
- ⛔️ `{ record?: string }` Optional properties cannot be denoted with a question mark.
```sh
yarn add @typedefs/parser
```
## Table Of Contents
- [Table Of Contents](#table-of-contents)
- [API](#api)
- [`parse(type: string): !Type`](#parsetype-string-type)
* [`Type`](#type-type)
* [`FunctionType`](#type-functiontype)
- [Copyright](#copyright)
<p align="center"><a href="#table-of-contents">
<img src="/.documentary/section-breaks/0.svg?sanitize=true">
</a></p>
## API
The package is available by importing its default function:
```js
import parse from '@typedefs/parser'
```
<p align="center"><a href="#table-of-contents">
<img src="/.documentary/section-breaks/1.svg?sanitize=true">
</a></p>
## <code><ins>parse</ins>(</code><sub><br/> `type: string,`<br/></sub><code>): <i>!Type</i></code>
Parses a [Google Closure Compiler](https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System) type recursively.
__<a name="type-type">`Type`</a>__: The representation of a type.
| Name | Type | Description |
| ----------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| nullable | <em>boolean</em> | Whether the type is nullable. This is defined by writing `?` before the type name to state nullability and `!` otherwise. The parser does not infer nullability from types being primitive and `Function/function`. |
| name | <em>string</em> | The name of the type. |
| union | <em>!Array<<a href="#type-type" title="The representation of a type.">!Type</a>></em> | If the type is defined as a union, e.g., `(string\|number)`, contains the united types. Must include parenthesis. |
| record | <em>!Object<string, <a href="#type-type" title="The representation of a type.">Type</a>></em> | If the type is a record, contains its representation. If a property of the record does not have a type, it will be set to null. |
| application | <em>!Array<<a href="#type-type" title="The representation of a type.">!Type</a>></em> | The application of the type, e.g., the inner type of `Object<Application>`. |
| function | <em><a href="#type-functiontype" title="The meta information about the function.">!FunctionType</a></em> | The function info with args and return if the type is a function. |
| optional | <em>boolean</em> | If the type is returned as an optional argument of a function (`function(string=)`), this will be set to true. |
__<a name="type-functiontype">`FunctionType`</a>__: The meta information about the function.
| Name | Type | Description |
| ------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| __args*__ | <em>!Array<<a href="#type-type" title="The representation of a type.">!Type</a>></em> | The arguments of the function. |
| __return*__ | <em><a href="#type-type" title="The representation of a type.">?Type</a></em> | The return type of the function. When the value is set to `null`, it means the function does not have a return. If the return was actually `null`, it would be specified as `return: { name: 'null' }`. |
| this | <em><a href="#type-type" title="The representation of a type.">!Type</a></em> | The type of the `this` argument specified as `function(this: Type)`. |
| new | <em><a href="#type-type" title="The representation of a type.">!Type</a></em> | The type of the `new` argument specified as `function(new: Type)`. |
| variableArgs | <em><a href="#type-type" title="The representation of a type.">!Type</a></em> | The type of the variable arguments, e.g., `function(...Type)`. |
```js
import parser from '@typedefs/parser'
logHeading('Applications')
log(parser('!Object<string, Promise<Array<!Type>>>'))
logHeading('Unions (parenthesis are required)')
log(parser('(string | number | !Promise<?(string | symbol)>)'))
logHeading('Records')
log(parser(`{
a: string, b: ?number, c,
d: !Promise<Array<{e: number}>>,
f: { g: boolean }
}`))
logHeading('Functions')
log(parser(`function(
this: Type,
string,
function(),
function(): *=
): function(): null`))
// special case when name is nullable empty string ''
log(parser(`function(): ?`))
```
```js
Applications:
------------
{ nullable: false,
name: 'Object',
application:
[ { name: 'string' },
{ name: 'Promise',
application:
[ { name: 'Array',
application: [ { nullable: false, name: 'Type' } ] } ] } ] }
Unions (parenthesis are required):
---------------------------------
{ union:
[ { name: 'string' },
{ name: 'number' },
{ nullable: false,
name: 'Promise',
application:
[ { union: [ { name: 'string' }, { name: 'symbol' } ],
nullable: true } ] } ] }
Records:
-------
{ record:
{ a: { name: 'string' },
b: { nullable: true, name: 'number' },
c: null,
d:
{ nullable: false,
name: 'Promise',
application:
[ { name: 'Array',
application: [ { record: { e: { name: 'number' } } } ] } ] },
f: { record: { g: { name: 'boolean' } } } } }
Functions:
---------
{ name: 'function',
function:
{ return:
{ name: 'function',
function: { return: { name: 'null' }, args: [] } },
args:
[ { name: 'string' },
{ name: 'function', function: { return: null, args: [] } },
{ name: 'function',
function: { return: { name: 'any' }, args: [] },
optional: true } ],
this: { name: 'Type' } } }
{ name: 'function',
function: { return: { nullable: true, name: '' }, args: [] } }
```
<p align="center"><a href="#table-of-contents">
<img src="/.documentary/section-breaks/2.svg?sanitize=true">
</a></p>
## Copyright
<table>
<tr>
<th>
<a href="https://artd.eco">
<img width="100" src="https://raw.githubusercontent.com/wrote/wrote/master/images/artdeco.png"
alt="Art Deco">
</a>
</th>
<th>© <a href="https://artd.eco">Art Deco</a> 2019</th>
<th>
<a href="https://www.technation.sucks" title="Tech Nation Visa">
<img width="100" src="https://raw.githubusercontent.com/idiocc/cookies/master/wiki/arch4.jpg"
alt="Tech Nation Visa">
</a>
</th>
<th><a href="https://www.technation.sucks">Tech Nation Visa Sucks</a></th>
</tr>
</table>
<p align="center"><a href="#table-of-contents">
<img src="/.documentary/section-breaks/-1.svg?sanitize=true">
</a></p>