API

The package is available by importing its named functions and classes:

import { getLinks, getNameWithDefault, parseFile } from 'typal'

Its primary use is in Documentary, and the API is therefore semi-private.

On This Page

• On This Page
• getNameWithDefault(name, defaultValue, type=, parentParam=): string
• parseFile(xml, namespace=, location=): { namespace: string, types: !Array<!Type>, imports: !Array<!Import> }
  • Root Namespace
• getLinks(allTypes, type, opts=): string

getNameWithDefault(
  name: string,
  defaultValue: ?(string|boolean|number),
  type=: string,
  parentParam=: string,
): string

Return a name of a property with its default value, and surrounded by square brackets if default is given. If type is boolean or number, the default value is not surrounded by "".

• name* string: The name of the param.
• defaultValue* ?(string | boolean | number): The default value, if exists. null does not mean the null default value, it means that there isn't one.
• type string (optional): The type of the param.
• parentParam string (optional): Name of the parent parameter.

The default values are only used for visual feedback as VSCode does not show that information anywhere, and GCC does not use it in compilation.

Constructors and interfaces don't have optional properties since Closure Compiler expects all declared options to be initialised in the constructor method, or specified with getters.

E.g., the following JSDoc includes the params generated with this method (with the addition of [] and annotations' tags):

/**
 * @param {*} requiredParam
 * @param {*} [optionalDefaultParam=false]
 * @param {*} [optionalDefaultParamString="test"]
 * @param {*} [optionalParam]
 *
 * @param {*} parentParam.requiredParam
 * @param {*} [parentParam.optionalDefaultParam=false]
 * @param {*} [parentParam.optionalDefaultParamString="test"]
 * @param {*} [parentParam.optionalParam]
 */

import { getNameWithDefault } from 'typal'

console.log(getNameWithDefault('arg', 'test', 'string'))
console.log(getNameWithDefault('hello', true, 'boolean', 'arg'))
console.log(getNameWithDefault('world', 27, 'number', 'arg'))

arg="test"
arg.hello=true
arg.world=27

parseFile(
  xml: string,
  namespace=: string,
  location=: string,
): { namespace: string, types: !Array<!Type>, imports: !Array<!Import> }

Parses the types.xml file. Looks for <type>, <constructor>, <interface> and <method> elements and extracts their properties, functions and arguments.

• xml* string: The content of the xml file.
• namespace string (optional): Namespace to ignore in types and properties.
• location string (optional): The path to the file. Used to resolve relative paths for examples.

Given the following types file:

<types>
  <import name="ServerResponse" from="http" />
  <type name="SetHeaders"
    type="(s: ServerResponse) => void"
    closure="function(http.ServerResponse)"
    desc="Function to set custom headers on response." />
  <type name="StaticConfig" desc="Options to setup `koa-static`.">
    <prop string name="root">
      Root directory string.
    </prop>
    <prop number name="maxage" default="0">
      Browser cache max-age in milliseconds.
    </prop>
    <prop boolean name="hidden" default="false">
      Allow transfer of hidden files.
    </prop>
  </type>
</types>

It can be parsed using the following call:

import read from '@wrote/read'
import { parseFile } from 'typal'

const getFile = async () => {
  const file = await read('test/fixture/types.xml')
  const res = parseFile(file)
  return res
}

The result will contain Types and Imports:

{ namespace: undefined,
  types: 
   [ Type {
       name: 'SetHeaders',
       type: '(s: ServerResponse) => void',
       closureType: 'function(http.ServerResponse)',
       description: 'Function to set custom headers on response.',
       noToc: false,
       spread: false,
       noExpand: false,
       link: null,
       properties: [],
       namespace: null,
       isConstructor: false,
       isInterface: false,
       isRecord: false,
       extends: null,
       args: null,
       examples: [],
       file: null },
     Type {
       name: 'StaticConfig',
       type: null,
       closureType: null,
       description: 'Options to setup `koa-static`.',
       noToc: false,
       spread: false,
       noExpand: false,
       link: null,
       properties: 
        [ Property {
            name: 'root',
            description: 'Root directory string.',
            _type: 'string',
            closureType: 'string',
            _closure: null,
            default: null,
            optional: false,
            aliases: [],
            noParams: false,
            parsed: { name: 'string' },
            args: null,
            _static: false,
            examples: [],
            templateNoReturn: false },
          Property {
            name: 'maxage',
            description: 'Browser cache max-age in milliseconds.',
            _type: 'number',
            closureType: 'number',
            _closure: null,
            default: 0,
            optional: true,
            aliases: [],
            noParams: false,
            parsed: { name: 'number' },
            args: null,
            _static: false,
            examples: [],
            templateNoReturn: false },
          Property {
            name: 'hidden',
            description: 'Allow transfer of hidden files.',
            _type: 'boolean',
            closureType: 'boolean',
            _closure: null,
            default: false,
            optional: true,
            aliases: [],
            noParams: false,
            parsed: { name: 'boolean' },
            args: null,
            _static: false,
            examples: [],
            templateNoReturn: false } ],
       namespace: null,
       isConstructor: false,
       isInterface: false,
       isRecord: false,
       extends: null,
       args: null,
       examples: [],
       file: null } ],
  imports: 
   [ Import {
       name: 'ServerResponse',
       type: 'import(\'http\').ServerResponse',
       closureType: 'import(\'http\').ServerResponse',
       description: '',
       noToc: true,
       spread: false,
       noExpand: false,
       link: null,
       properties: [],
       namespace: 'http',
       isConstructor: false,
       isInterface: false,
       isRecord: false,
       extends: null,
       args: null,
       examples: [],
       file: null,
       from: 'http' } ],
  embeds: [] }

Root Namespace

Passing the rootNamespace allows to ignore the given namespace in types and properties. This can be used for compiling documentation when only single namespace is used, and readers can assume where the types come from. However, this should only be used when printing to docs, but when compiling JSDoc, the full namespaces should be used to allow integration with externs.

Given the following types file which uses namespaces:

<types namespace="ns">
  <type name="HelloWorld" desc="The example type.">
  </type>
  <type type="ns.HelloWorld" name="GoodMorning"
    desc="Life is seeing sunlight every day." />
  </type>
  <type name="Conf" desc="The configuration object">
    <prop type="ns.HelloWorld" name="propName">
      The property description.
    </prop>
  </type>
</types>

It can be parsed so that the ns. prefix is ignored:

import read from '@wrote/read'
import { parseFile } from 'typal'

const getFile = async () => {
  const file = await read('example/root.xml')
  const res = parseFile(file, 'ns')
  return res
}

{ namespace: 'ns',
  types: 
   [ Type {
       name: 'HelloWorld',
       type: null,
       closureType: null,
       description: 'The example type.',
       noToc: false,
       spread: false,
       noExpand: false,
       link: null,
       properties: [],
       namespace: null,
       isConstructor: false,
       isInterface: false,
       isRecord: false,
       extends: null,
       args: null,
       examples: [],
       file: null },
     Type {
       name: 'GoodMorning',
       type: 'HelloWorld',
       closureType: 'ns.HelloWorld',
       description: 'Life is seeing sunlight every day.',
       noToc: false,
       spread: false,
       noExpand: false,
       link: null,
       properties: [],
       namespace: null,
       isConstructor: false,
       isInterface: false,
       isRecord: false,
       extends: null,
       args: null,
       examples: [],
       file: null },
     Type {
       name: 'Conf',
       type: null,
       closureType: null,
       description: 'The configuration object',
       noToc: false,
       spread: false,
       noExpand: false,
       link: null,
       properties: 
        [ Property {
            name: 'propName',
            description: 'The property description.',
            _type: 'HelloWorld',
            closureType: 'HelloWorld',
            _closure: null,
            default: null,
            optional: false,
            aliases: [],
            noParams: false,
            parsed: { name: 'HelloWorld' },
            args: null,
            _static: false,
            examples: [],
            templateNoReturn: false } ],
       namespace: null,
       isConstructor: false,
       isInterface: false,
       isRecord: false,
       extends: null,
       args: null,
       examples: [],
       file: null } ],
  imports: [],
  embeds: [] }

getLinks(
  allTypes: !Array<Type>,
  type: string|!_typedefsParser.Type,
  opts=: !LinkingOptions,
): string

Gets links for markdown. Iterates through the types to find referenced ones, and returns a string which contains a link to it.

• allTypes* !Array<Type>: All types that can be linked.
• type* (string | !_typedefsParser.Type): The type or parsed type that should be serialised.
• opts !LinkingOptions (optional): Options for linking.