\n\n# Typal\n\n[](https://www.npmjs.com/package/typal)\n\n ![\"Pipeline](\"https://gitlab.com/artdeco/typal/badges/master/pipeline.svg\")
\n\n
\n\n`typal` Keeps Types In XML files And Converts Them To (1) JavaScript JSDoc, (2) Closure Externs and (3) Markdown Documentation. It is the alternative to TypeScript definitions and utilises the power of JSDoc for excellent developer experience, documentation readability and compiler annotation. It also makes integration between _Google Closure Compiler_ and _VSCode_ easy, using the JSDoc notations that are understood by both at the same time.\n\nThe package's main use is as the CLI tool to generate typedefs, but it also has an API for parsing types and properties with regular expressions.\n\n```sh\nyarn add -D typal\nnpm i typal --save-dev\n```\n\n\n\n## Table Of Contents\n\n- [Table Of Contents](#table-of-contents)\n- [Purpose](#purpose)\n- [CLI](#cli)\n * [*Standard*](#standard)\n * [*Closure*](#closure)\n * [*Externs*](#externs)\n * [_Typal_ Arguments](#typal-arguments)\n * [Missing Types Warnings](#missing-types-warnings)\n * [Keeping Types In Separate File](#keeping-types-in-separate-file)\n * [User Snippet](#user-snippet)\n * [Migration](#migration)\n- [Schema](#schema)\n- [Markdown Documentation](#markdown-documentation)\n * [`Type`](#type-type)\n * [`Example`](#type-example)\n- [Copyright & License](#copyright--license)\n\n\n\n## Purpose\n\nThe main purpose of this package is to generate _JSDoc_ annotations that are understood both by _VSCode_, and compatible with _Google Closure Compiler_ via its externs system. The project deliberately deviates from _TypeScript_ and is meant for _JavaScript_ development, and it proves that typing can be achieved perfectly well with _JSDoc_. It's idea is to store files in an XML file, and then embed them in JS and README files and externs.\n\nThe solutions provided by _Typal_ are:\n\n1. Manage types from an external XML location.\n1. Compile types into JSDoc compatible both with _GCC_ and _VSCode_.\n1. Compile types as externs for _GCC_ and use in other packages.\n1. Place types' descriptions as formatted tables in markdown (used in [_Documentary_](https://github.com/artdecocode/documentary)).\n1. Improve the DevX by increasing the visibility of functions' APIs.\n\nTo tune in, start with the _Wiki Page_:\n\n🥇🥈🥉[Naïve, JSDoc And Closure Use Cases For Typedefs](https://github.com/artdecocode/typal/wiki/3-Use-Cases)\n\n\n\n## CLI\n\n_Typal_ is the command-line utility that is used to manage _JSDoc_ types in JavaScript source files. The typedefs are now sourced from the `types.xml` file and embedded on demand. There are 3 modes to embedding types:\n\n1. *Standard*, no flags required: places only _VSCode_ compatible code. Can be used when no Closure-compilation will be performed on packages. Does not utilise namespaces. Expands the parameters of complex types for better visibility.\n \n\n![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/0.svg\")
\n![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/1.svg\")
\n![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/2.svg\")
\n\n
\n
\n1. *Closure* with `-c` flag: suppresses standard typedefs' annotations so that Closure Compiler does not show warnings. Introduces namespaces for internal as well as external APIs to make types' sources more visible.\n Show Standard JSDoc
\n| \n\n ```js\n /**\n * @param {Conf} conf The configuration object.\n * @param {string} conf.source The source of where to read the data.\n * @param {boolean} [conf.closeOnFinish=true] Closes the stream when done. Default `true`.\n * @param {TransformOptions} options\n */\n const prog = (conf, options) => {}\n \n /* typal example/cli/types.xml */\n /**\n * @typedef {import('stream').TransformOptions} TransformOptions\n * @typedef {Object} Conf The configuration object.\n * @prop {string} source The source of where to read the data.\n * @prop {boolean} [closeOnFinish=true] Closes the stream when done. Default `true`.\n */\n ```\n |
\n
\n
\n1. *Externs* with `-e` flag: generates types only understood by the _Google Closure Compiler_, primarily in the `externs.js` file. These types do not have any meaning for the coding process and are only used in compilation either as types for programs, or externs for libraries.\n Show Closure JSDoc
\n| \n\n ```js\n /**\n * @param {_typal.Conf} conf The configuration object.\n * @param {string} conf.source The source of where to read the data.\n * @param {boolean} [conf.closeOnFinish=true] Closes the stream when done. Default `true`.\n * @param {stream.TransformOptions} options\n */\n const prog = (conf, options) => {}\n \n /* typal example/cli/types.xml */\n /**\n * @suppress {nonStandardJsDocs}\n * @typedef {_typal.Conf} Conf The configuration object.\n */\n /**\n * @suppress {nonStandardJsDocs}\n * @typedef {Object} _typal.Conf The configuration object.\n * @prop {string} source The source of where to read the data.\n * @prop {boolean} [closeOnFinish=true] Closes the stream when done. Default `true`.\n */\n /**\n * @suppress {nonStandardJsDocs}\n * @typedef {import('stream').TransformOptions} stream.TransformOptions\n */\n ```\n |
\n
\n
\n\n\n\n### _Typal_ Arguments\n\n```sh\n$ typal source [--closure|externs] [-o output] [-vh]\n```\n\nThe following arguments are supported by this software.\n\nShow Externs JSDoc
\n| \n\n ```js\n /* typal example/cli/types.xml */\n /** @const */\n var _typal = {}\n /**\n * The configuration object.\n * @typedef {{ source: string, closeOnFinish: (boolean|undefined) }}\n */\n _typal.Conf\n ```\n |
![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/3.svg\")
\n| Argument | \nShort | \nDescription | \n
|---|---|---|
| source | \n\n | The path to the source file or directory with files to embed types into. Can specify multiple values, e.g., typal types/index.js types/vendor.js. | \n
| --output | \n-o | \nThe destination where to save output.\n If not passed, the file will be overwritten.\n If - is passed, prints to stdout. | \n
| --closure | \n-c | \nWhether to generate types in Closure mode. | \n
| --useNamespace | \n-u | \nGenerate JSDoc for functions using namespaces. | \n
| --externs | \n-e | \nWhether to generate externs for GCC. | \n
| --types | \n-t | \nComma-separated location of files to read types from. | \n
| --template | \n-T | \nScans the input file for @type comment in functions' JSDoc, and inserts the annotations from types' files. | \n
| --migrate | \n-m | \nExtracts types from JavaScript source code and saves them\n into the types.xml file specified in the output option. | \n
| --help | \n-h | \nPrint the help information and exit. | \n
| --version | \n-v | \nShow the version's number and exit. | \n
![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/4.svg\")
\n![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/5.svg\")
\n![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/6.svg\")
\n| Using Migrate Command |
|---|
| \n\n```js\n/**\n * @typedef {import('koa-multer').StorageEngine} StorageEngine\n * @typedef {import('http').IncomingMessage} IncomingMessage\n * @typedef {import('koa-multer').File} File\n */\n\n/**\n * @typedef {Object} Example An example type.\n * @typedef {Object} SessionConfig Description of Session Config.\n * @prop {string} key The cookie key.\n * @prop {number|'session'} [maxAge=86400000] maxAge in ms. Default is 1 day.\n * @prop {boolean} [overwrite] Can overwrite or not. Default `true`.\n * @prop {boolean} [httpOnly] httpOnly or not or not. Default `true`.\n * @prop {boolean} [signed=false] Signed or not. Default `false`.\n * @prop {boolean} [rolling] Force a session identifier cookie to be set.\n * @prop {boolean} [renew] Renew session when session is nearly expired.\n */\n```\n |
\nFor example, the types above can be extracted into the types file using the typal src/index.js -m [-o types/index.xml] command.\n |
| \n\n```xml\n |
![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/7.svg\")
\n![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/8.svg\")
\n| Name | \nType & Description | \n
|---|---|
| type | \n?Type | \n
| \n The type itself, possibly nullable.\n | \n|
| union | \n!(Type | string) | \n
| \n The union of types.\n | \n|
| record | \n{ t: Type, r } | \n
| \n The record with a type.\n | \n|
| application | \nObject<string, Type> | \n
| \n The application with a type.\n | \n|
| function | \n(this: Type, arg0: string, arg1: !Type) => Type | \n
| \n The function with arguments and return type.\n | \n|
| variable-args | \n(...args: Type[]) => ? | \n
\n Functions with ... for variable argument types.\n | \n |
| vscode-function | \n(type: Type) => Type | \n
| \n Linking in the VSCode (TypeScript) functions is also supported when properties are written as functions. \n type* Type: The type.\n | \n
![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/9.svg\")
\n\n \n ![\"Art](\"https://gitlab.com/uploads/-/system/group/avatar/7454762/artdeco.png\"\n) \n \n | \n © Art Deco™ 2020 | \n\n ![\"AGPL-3.0\"](\"https://artdeco.gitlab.io/assets/licenses/agpl-3.0.svg\") \n | \n
|---|
![\"section](\"https://artdeco.gitlab.io/typal/section-breaks/-1.svg\")
\n