{"id":19475503,"url":"https://github.com/artdecocode/typal","last_synced_at":"2026-05-05T14:31:36.435Z","repository":{"id":135405736,"uuid":"150161499","full_name":"artdecocode/typal","owner":"artdecocode","description":"Keeps JSDoc types in XML files and converts them to JavaScript, Markdown and Closure Externs.","archived":false,"fork":false,"pushed_at":"2020-02-03T04:23:47.000Z","size":2497,"stargazers_count":4,"open_issues_count":23,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-18T14:32:08.623Z","etag":null,"topics":["closure-compiler","documentation","externs","gcc","google-closure-compiler","jsdoc","markdown","types"],"latest_commit_sha":null,"homepage":"https://typedef.page","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artdecocode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-24T20:04:26.000Z","updated_at":"2020-02-22T19:58:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"b59b99a9-0959-484f-9734-0caab8861521","html_url":"https://github.com/artdecocode/typal","commit_stats":null,"previous_names":[],"tags_count":81,"template":false,"template_full_name":null,"purl":"pkg:github/artdecocode/typal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artdecocode%2Ftypal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artdecocode%2Ftypal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artdecocode%2Ftypal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artdecocode%2Ftypal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artdecocode","download_url":"https://codeload.github.com/artdecocode/typal/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artdecocode%2Ftypal/sbom","scorecard":{"id":208916,"data":{"date":"2025-08-11","repo":{"name":"github.com/artdecocode/typal","commit":"610f03d2145dde34a0b489a77e6ab73492129577"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3,"checks":[{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: GNU Affero General Public License v3.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T00:21:24.110Z","repository_id":135405736,"created_at":"2025-08-17T00:21:24.110Z","updated_at":"2025-08-17T00:21:24.110Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32653468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["closure-compiler","documentation","externs","gcc","google-closure-compiler","jsdoc","markdown","types"],"created_at":"2024-11-10T19:33:16.291Z","updated_at":"2026-05-05T14:31:36.418Z","avatar_url":"https://github.com/artdecocode.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Typal\n\n[![npm version](https://badge.fury.io/js/typal.svg)](https://www.npmjs.com/package/typal)\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\n```\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/0.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\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](#copyright)\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/1.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\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\u003ckbd\u003e🥇🥈🥉[Naïve, JSDoc And Closure Use Cases For Typedefs](../../wiki/3-use-cases)\u003c/kbd\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/2.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\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. \u003ca name=\"standard\"\u003e*Standard*\u003c/a\u003e, 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    \u003cdetails\u003e\n    \u003csummary\u003eShow Standard JSDoc\u003c/summary\u003e\n    \u003ctable\u003e\u003ctr/\u003e\u003ctr\u003e\u003ctd\u003e\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) =\u003e {}\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    \u003c/tr\u003e\u003c/td\u003e\u003c/table\u003e\n    \u003c/details\u003e\n1. \u003ca name=\"closure\"\u003e*Closure*\u003c/a\u003e 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    \u003cdetails\u003e\n    \u003csummary\u003eShow Closure JSDoc\u003c/summary\u003e\n    \u003ctable\u003e\u003ctr/\u003e\u003ctr\u003e\u003ctd\u003e\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) =\u003e {}\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    \u003c/tr\u003e\u003c/td\u003e\u003c/table\u003e\n    \u003c/details\u003e\n1. \u003ca name=\"externs\"\u003e*Externs*\u003c/a\u003e 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    \u003cdetails\u003e\n    \u003csummary\u003eShow Externs JSDoc\u003c/summary\u003e\n    \u003ctable\u003e\u003ctr/\u003e\u003ctr\u003e\u003ctd\u003e\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    \u003c/tr\u003e\u003c/td\u003e\u003c/table\u003e\n    \u003c/details\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/3.svg?sanitize=true\" width=\"25\"\u003e\n\u003c/a\u003e\u003c/p\u003e\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\n\u003ctable\u003e\n \u003cthead\u003e\n  \u003ctr\u003e\n   \u003cth\u003eArgument\u003c/th\u003e \n   \u003cth\u003eShort\u003c/th\u003e\n   \u003cth\u003eDescription\u003c/th\u003e\n  \u003c/tr\u003e\n \u003c/thead\u003e\n  \u003ctr\u003e\n   \u003ctd\u003esource\u003c/td\u003e\n   \u003ctd\u003e\u003c/td\u003e\n   \u003ctd\u003eThe path to the source file or directory with files to embed types into. Can specify multiple values, e.g., \u003ccode\u003etypal types/index.js types/vendor.js\u003c/code\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--output\u003c/td\u003e\n   \u003ctd\u003e-o\u003c/td\u003e\n   \u003ctd\u003eThe destination where to save output.\n    If not passed, the file will be overwritten.\n    If \u003ccode\u003e-\u003c/code\u003e is passed, prints to stdout.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--closure\u003c/td\u003e\n   \u003ctd\u003e-c\u003c/td\u003e\n   \u003ctd\u003eWhether to generate types in \u003cem\u003eClosure\u003c/em\u003e mode.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--useNamespace\u003c/td\u003e\n   \u003ctd\u003e-u\u003c/td\u003e\n   \u003ctd\u003eGenerate JSDoc for functions using namespaces.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--externs\u003c/td\u003e\n   \u003ctd\u003e-e\u003c/td\u003e\n   \u003ctd\u003eWhether to generate externs for \u003cem\u003eGCC\u003c/em\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--types\u003c/td\u003e\n   \u003ctd\u003e-t\u003c/td\u003e\n   \u003ctd\u003eComma-separated location of files to read types from.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--template\u003c/td\u003e\n   \u003ctd\u003e-T\u003c/td\u003e\n   \u003ctd\u003eScans the input file for \u003ccode\u003e@type\u003c/code\u003e comment in functions' JSDoc, and inserts the annotations from types' files.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--migrate\u003c/td\u003e\n   \u003ctd\u003e-m\u003c/td\u003e\n   \u003ctd\u003eExtracts types from JavaScript source code and saves them\n    into the types.xml file specified in the output option.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--help\u003c/td\u003e\n   \u003ctd\u003e-h\u003c/td\u003e\n   \u003ctd\u003ePrint the help information and exit.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--version\u003c/td\u003e\n   \u003ctd\u003e-v\u003c/td\u003e\n   \u003ctd\u003eShow the version's number and exit.\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n_Typal_ will look for its marker in the source files, and insert all types definitions below it. There **must** be a single new line after the marker, even at the bottom of the file. It is possible to override the arguments, or pass them via the marker itself. When these are specified, there is no need to supply them via the CLI.\n\n```js\nfunction sourceCode() {}\n\n/* typal types/index.xml [closure|externs] [skipNsDecl] [noSuppress] [ignore:_ns.Type,Type] */\n_ // remember new line!\n```\n\n- \u003ckbd\u003eclosure\u003c/kbd\u003e: enable the closure mode;\n- \u003ckbd\u003eexterns\u003c/kbd\u003e: enable the externs mode;\n- \u003ckbd\u003enoSuppress\u003c/kbd\u003e: don't add `@suppress` annotations (see the [files](#keeping-types-in-separate-file) section below).\n- \u003ckbd\u003eignore:_nsType,Type\u003c/kbd\u003e: the types to ignore when placing JSDoc into JS files. This can be useful, for example, when the package is built with _Depack_ and has no dependencies, but depends on imported types from other packages. Therefore, these imported types need to be vendored using a separate file, and then imported from there, rather than from their original source file. See [`@zoroaster/mask/types/vendor.js`](https://github.com/contexttesting/mask/blob/master/types/vendor.js) and [`@zoroaster/mask/types/index.js`](https://github.com/contexttesting/mask/blob/master/types/index.js) for a practical application.\n- \u003ckbd\u003eskipNsDecl\u003c/kbd\u003e: Disables the declaration of the namespace. The types will still be prefixed with a namespace, but it won't be declared at the top as `/** @const */ var ns = {}`. This is useful when the externs are split by multiple files, and the namespace will only need to appear in one of them, otherwise the `Variable _ns declared more than once.` error will be thrown.\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/4.svg?sanitize=true\" width=\"25\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n### Missing Types Warnings\n\nWhen placing _JSDoc_ into source code files where functions are annotated with `@params`, _Typal_ in addition to expanding object arguments into the developer-friendly notation as discussed above, will check to see if the types were found in the xml files specified in via the `/* typal types.xml */` marker to warn of possible errors. This feature aims at helping to identify when some annotations were not done properly, e.g., when missing a namespace, an import, or when type names become outdated. This does not work for record types such as `{}` since although we have a parser for types themselves, we only use a regular expression which cannot understand things like `@param {{ s: string, t }}` at the moment. Also only [Closure-style types](https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System#optional) are parsed, i.e., _VSCode_ JSDoc is not supported right now, and the union must be explicitly put in parenthesis.\n\n```js\n/**\n * @param {stream.Writable} writable\n * @param {stream.Readable} readable\n * @param {_ns.Type} type\n * @param {_ns.MissingType} missingType\n * @param {Array\u003c_ns.MissingType\u003e} array\n * @param {Promise\u003cMissingType\u003e} promise\n * @param {Object\u003cstring, _ns.MissingType\u003e} object\n * @param {(Type | MissingType | _ns.Type)} union\n * @param {(s: string) =\u003e number} error\n * @param {MissingType \u0026 Type2} intersection Only first type will be parsed\n * @param {string} string\n */\nfunction example (\n  writable, readable,\n  type, missingType,\n  array, promise, object, union,\n  error,\n  string,\n) {}\n\n/* typal example/warnings.xml */\n```\n```\nDetected type marker: example/warnings.xml\nType stream.Readable was not found.\nexample/warnings.js:3:11\nType _ns.MissingType was not found.\nexample/warnings.js:5:11\nType _ns.MissingType in Array\u003c_ns.MissingType\u003e was not found.\nexample/warnings.js:6:11\nType MissingType in Promise\u003cMissingType\u003e was not found.\nexample/warnings.js:7:11\nType _ns.MissingType in Object\u003cstring, _ns.MissingType\u003e was not found.\nexample/warnings.js:8:11\nType Type in (Type | MissingType | _ns.Type) was not found.\nexample/warnings.js:9:11\nType MissingType in (Type | MissingType | _ns.Type) was not found.\nexample/warnings.js:9:11\nError while parsing the type (s: string) =\u003e number\nExpecting closing )\nexample/warnings.js:10:11\nType MissingType in MissingType \u0026 Type2 was not found.\nexample/warnings.js:11:11\n```\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/5.svg?sanitize=true\" width=\"25\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n### Keeping Types In Separate File\n\nIf the types are numerous and it is desired to put them in a separate JS file (like `types.d.ts` but for JSDoc) and then import them in code from there for expansions of function's configs, it is possible with the `-t` argument pointing to the location of XML files. Keeping all files in a `types.js` file allows to import them from anywhere in the code, or other packages (the file needs to be added to the `files` field of `package.json`, if such field exists).\n\n_For example, we can create a `types.js` file with the `typal` marker:_\n\n```js\n// types.js\nexport {} // important for enabling of importing\n/* typal types/index.xml closure noSuppress */\n\n```\n\nThe types can be placed in there with `typal types.js` command. We also add the `noSuppress` command because the file will not be imported and checked by the _Google Closure Compiler_ therefore the `@suppress` annotations would be redundant. Now the aim is to update the source code which has a variable of a particular type that we want to expand and we run `typal src/index.js -t types/index.xml` to do that:\n\n```js\n// src/index.js\n/**\n * @param {_ns.Config} config\n */\nfunction example(config = {}) {\n  const { test } = config\n}\n\n// manually add the namespace and dependencies' imports\n/**\n * @suppress {nonStandardJsDocs}\n * @typedef {import('stream').Readable} stream.Readable\n */\n/**\n * @suppress {nonStandardJsDocs}\n * @typedef {import('../types').Config} _ns.Config\n */\n```\n```js\n// src/index.js\n/**\n * @param {_ns.Config} config The config for the program\n * @param {string} config.test The test property.\n * @param {stream.Readable} config.rs The stream to read.\n */\nfunction example(config = {}) {\n  const { test } = config\n}\n\n// manually add the namespace and dependencies' imports\n/**\n * @suppress {nonStandardJsDocs}\n * @typedef {import('stream').Readable} stream.Readable\n */\n/**\n * @suppress {nonStandardJsDocs}\n * @typedef {import('../types').Config} _ns.Config\n */\n```\n\nAny external types referenced in properties must be manually imported, because otherwise their types will be unknown in the scope of the file. This can be done with the snippet that can be put either in the workspace directory as `.vscode/import.code-snippets`, or configured to be included in _\u003ca name=\"user-snippet\"\u003eUser Snippet\u003c/a\u003es_ (\u003ckbd\u003e⌘\u003c/kbd\u003e\u003ckbd\u003e⇧\u0026nbsp;\u003c/kbd\u003e\u003ckbd\u003eP\u003c/kbd\u003e \u003e Preferences: Configure User Snippets).\n\n```json\n{\n\t\"Import Type And Suppress\": {\n\t\t\"prefix\": \"@typedef\",\n\t\t\"body\": [\n\t\t\t\"/**\",\n\t\t\t\" * @suppress {nonStandardJsDocs}\",\n\t\t\t\" * @typedef {import('$1')$2} $3\",\n\t\t\t\" */\"\n\t\t],\n\t\t\"description\": \"Insert import typedef\"\n\t}\n}\n```\n\nIn future, we plan to introduce full-scale management of types so that all import statements will be added automatically by _Typal_.\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/6.svg?sanitize=true\" width=\"25\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n### Migration\n\nWhen there are JSDoc types written in JavaScript files, and they need to be put in the `types.xml` file, it can be done automatically with the `--migrate` command. In this case, _Typal_ will scan the source code for the type definitions and their properties, defined as `@prop` or `@property` tags, and place them either in the output file when specified, or print to the stdout. This will help to move all types into XML declarations, which can then be manually adjusted if necessary, and embedded into the source code using the `/* typal types.xml */` marker, and in README documentation using [_Documentary_](https://artdecocode.com/documentary/).\n\n\u003ctable\u003e\n\u003ctr\u003e\u003cth\u003eUsing Migrate Command\u003c/th\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\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\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\nFor example, the types above can be extracted into the types file using the \u003ccode\u003etypal src/index.js -m [-o types/index.xml]\u003c/code\u003e command.\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\n\n```xml\n\u003ctypes\u003e\n  \u003cimport name=\"StorageEngine\" from=\"koa-multer\" /\u003e\n  \u003cimport name=\"IncomingMessage\" from=\"http\" /\u003e\n  \u003cimport name=\"File\" from=\"koa-multer\" /\u003e\n  \u003ctype name=\"Example\" desc=\"An example type.\" /\u003e\n  \u003ctype name=\"SessionConfig\" desc=\"Description of Session Config.\"\u003e\n    \u003cprop string name=\"key\"\u003e\n      The cookie key.\n    \u003c/prop\u003e\n    \u003cprop type=\"number|'session'\" name=\"maxAge\" default=\"86400000\"\u003e\n      maxAge in ms. Default is 1 day.\n    \u003c/prop\u003e\n    \u003cprop boolean name=\"overwrite\" default=\"true\"\u003e\n      Can overwrite or not.\n    \u003c/prop\u003e\n    \u003cprop boolean name=\"httpOnly\" default=\"true\"\u003e\n      httpOnly or not or not.\n    \u003c/prop\u003e\n    \u003cprop boolean name=\"signed\" default=\"false\"\u003e\n      Signed or not.\n    \u003c/prop\u003e\n    \u003cprop opt boolean name=\"rolling\"\u003e\n      Force a session identifier cookie to be set.\n    \u003c/prop\u003e\n    \u003cprop opt boolean name=\"renew\"\u003e\n      Renew session when session is nearly expired.\n    \u003c/prop\u003e\n  \u003c/type\u003e\n\u003c/types\u003e\n```\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/7.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n## Schema\n\nThe XML schema supports types, imports, methods, properties and functions (which are aliases to properties with special attributes used to construct a function type).\n\n\u003ckbd\u003e📝 [Typal Schema](../../wiki/Schema)\u003c/kbd\u003e\n\n```xml\n\u003ctypes\u003e\n  \u003cimport from=\"http\" name=\"IncomingMessage\"\n    link=\"https://nodejs.org/api/http.html#incoming_message\"\n    desc=\"The readable stream from the connection.\" /\u003e\n\n  \u003ctype name=\"Example\" \u003e\n    \u003cprop type=\"string\" name=\"test\"\u003eThe property.\u003c/prop\u003e\n    \u003cfn async args=\"number\" return=\"boolean\"\u003eA method property.\u003c/fn\u003e\n  \u003c/type\u003e\n\n  \u003cmethod name=\"sponsor\" \u003e\n    \u003carg name=\"amount\"\u003eThe amount to contribute.\u003c/arg\u003e\n    Become a sponsor on GitHub.\n  \u003c/type\u003e\n\u003c/types\u003e\n```\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/8.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n## Markdown Documentation\n\n_Typal_ allows to paste types into documentation using the [_Documentary_](http://artdecocode.com/documentary/) package. It will also link the types it knows about for easier navigation. The supported types are based on the [Google Closure Compiler types](https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System#optional) and include the following:\n\n__\u003ca name=\"type-type\"\u003e`Type`\u003c/a\u003e__: A type which can be linked.\n\n\n__\u003ca name=\"type-example\"\u003e`Example`\u003c/a\u003e__: An example type which can link to other types.\n\u003ctable\u003e\n \u003cthead\u003e\u003ctr\u003e\n  \u003cth\u003eName\u003c/th\u003e\n  \u003cth\u003eType \u0026amp; Description\u003c/th\u003e\n \u003c/tr\u003e\u003c/thead\u003e\n \u003ctr\u003e\n  \u003ctd rowSpan=\"3\" align=\"center\"\u003etype\u003c/td\u003e\n  \u003ctd\u003e\u003cem\u003e\u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003e?Type\u003c/a\u003e\u003c/em\u003e\u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd\u003e\n   The type itself, possibly nullable.\n  \u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd rowSpan=\"3\" align=\"center\"\u003eunion\u003c/td\u003e\n  \u003ctd\u003e\u003cem\u003e!(\u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003eType\u003c/a\u003e | string)\u003c/em\u003e\u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd\u003e\n   The union of types.\n  \u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd rowSpan=\"3\" align=\"center\"\u003erecord\u003c/td\u003e\n  \u003ctd\u003e\u003cem\u003e{ t: \u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003eType\u003c/a\u003e, r }\u003c/em\u003e\u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd\u003e\n   The record with a type.\n  \u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd rowSpan=\"3\" align=\"center\"\u003eapplication\u003c/td\u003e\n  \u003ctd\u003e\u003cem\u003eObject\u0026lt;string, \u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003eType\u003c/a\u003e\u0026gt;\u003c/em\u003e\u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd\u003e\n   The application with a type.\n  \u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd rowSpan=\"3\" align=\"center\"\u003efunction\u003c/td\u003e\n  \u003ctd\u003e\u003cem\u003e(this: \u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003eType\u003c/a\u003e, arg0: string, arg1: \u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003e!Type\u003c/a\u003e) =\u003e \u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003eType\u003c/a\u003e\u003c/em\u003e\u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd\u003e\n   The function with arguments and return type.\n  \u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd rowSpan=\"3\" align=\"center\"\u003evariable-args\u003c/td\u003e\n  \u003ctd\u003e\u003cem\u003e(...args: \u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003eType\u003c/a\u003e[]) =\u003e ?\u003c/em\u003e\u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd\u003e\n   Functions with \u003ccode\u003e...\u003c/code\u003e for variable argument types.\n  \u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd rowSpan=\"3\" align=\"center\"\u003evscode-function\u003c/td\u003e\n  \u003ctd\u003e\u003cem\u003e(type: \u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003eType\u003c/a\u003e) =\u003e \u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003eType\u003c/a\u003e\u003c/em\u003e\u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\u003c/tr\u003e\n \u003ctr\u003e\n  \u003ctd\u003e\n   Linking in the \u003cem\u003eVSCode\u003c/em\u003e (\u003cem\u003eTypeScript\u003c/em\u003e) functions is also supported when properties are written as functions.\u003cbr/\u003e\n   \u003ckbd\u003e\u003cstrong\u003etype*\u003c/strong\u003e\u003c/kbd\u003e \u003cem\u003e\u003ccode\u003e\u003ca href=\"#type-type\" title=\"A type which can be linked.\"\u003eType\u003c/a\u003e\u003c/code\u003e\u003c/em\u003e: The type.\n  \u003c/td\u003e\n \u003c/tr\u003e\n\u003c/table\u003e\n\n[Used source types](example/md.xml).\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/9.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n## Copyright\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      \u003ca href=\"https://artd.eco\"\u003e\n        \u003cimg width=\"100\" src=\"https://raw.githubusercontent.com/wrote/wrote/master/images/artdeco.png\"\n          alt=\"Art Deco\"\u003e\n      \u003c/a\u003e\n    \u003c/th\u003e\n    \u003cth\u003e© \u003ca href=\"https://artd.eco\"\u003eArt Deco\u003c/a\u003e   2019\u003c/th\u003e\n    \u003cth\u003e\n      \u003ca href=\"https://www.technation.sucks\" title=\"Tech Nation Visa\"\u003e\n        \u003cimg width=\"100\" src=\"https://raw.githubusercontent.com/idiocc/cookies/master/wiki/arch4.jpg\"\n          alt=\"Tech Nation Visa\"\u003e\n      \u003c/a\u003e\n    \u003c/th\u003e\n    \u003cth\u003e\u003ca href=\"https://www.technation.sucks\"\u003eTech Nation Visa Sucks\u003c/a\u003e\u003c/th\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/-1.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartdecocode%2Ftypal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartdecocode%2Ftypal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartdecocode%2Ftypal/lists"}