{"id":20857560,"url":"https://github.com/openlayers/babel-plugin-jsdoc-closure","last_synced_at":"2025-05-12T08:30:59.803Z","repository":{"id":66035618,"uuid":"120426068","full_name":"openlayers/babel-plugin-jsdoc-closure","owner":"openlayers","description":"Transpiles JSDoc types from namepaths to types for Closure Compiler","archived":false,"fork":false,"pushed_at":"2018-06-12T07:46:55.000Z","size":25,"stargazers_count":5,"open_issues_count":2,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-10T22:40:43.810Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openlayers.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2018-02-06T08:43:40.000Z","updated_at":"2023-12-17T02:19:00.000Z","dependencies_parsed_at":"2023-02-22T22:01:40.936Z","dependency_job_id":null,"html_url":"https://github.com/openlayers/babel-plugin-jsdoc-closure","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openlayers%2Fbabel-plugin-jsdoc-closure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openlayers%2Fbabel-plugin-jsdoc-closure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openlayers%2Fbabel-plugin-jsdoc-closure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openlayers%2Fbabel-plugin-jsdoc-closure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openlayers","download_url":"https://codeload.github.com/openlayers/babel-plugin-jsdoc-closure/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225130468,"owners_count":17425506,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-18T04:41:04.240Z","updated_at":"2024-11-18T04:41:04.927Z","avatar_url":"https://github.com/openlayers.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# babel-plugin-jsdoc-closure\n\nTranspiles JSDoc types from [namepaths](http://usejsdoc.org/about-namepaths.html) with [module identifiers](http://usejsdoc.org/howto-commonjs-modules.html#module-identifiers) to types for Closure Compiler.\n\nThis is useful for type checking and building an application or library from a set of ES modules with Closure Compiler, without the use of any additional bundler.\n\n## Installation\n\n    npm install babel-cli babel-plugin-jsdoc-closure\n\n### Configuration\n\nCreate a `.babelrc` file in the root of your project to enable the plugin:\n\n```json\n{\n  \"plugins\": [\"jsdoc-closure\"],\n}\n```\n\n**Note**: When your code uses Closure type casts (i.e. something like `/** @type {Custom} */ (foo)`), you need to configure Babel to use recast as parser and generator by modifying your `.babelrc` file:\n\n```json\n{\n  \"plugins\": [\"jsdoc-closure\"],\n  \"parserOpts\": {\n    \"parser\": \"recast\"\n  },\n  \"generatorOpts\": {\n    \"generator\": \"recast\"\n  }\n}\n```\n\nYou will also need to install recast to make this work:\n\n    npm install recast\n\nTo run the transform on your sources (`src/`) and output them to `build/`, run\n\n    node_modules/.bin/babel --out-dir build src\n\nTo build your project, create a simple build script (e.g. `build.js`) like this:\n\n```js\nconst Compiler = require('google-closure-compiler').compiler;\n\nconst compiler = new Compiler({\n  js: [\n    'build/**.js',\n    // add directories for your dependencies, if any, here\n  ],\n  entry_point: 'build/index.js',\n  module_resolution: 'NODE',\n  dependency_mode: 'STRICT',\n  process_common_js_modules: true,\n  jscomp_error: ['newCheckTypes'],\n  // Uncomment and modify for dependencies without Closure annotations\n  //hide_warnings_for: ['node_modules']\n  js_output_file: 'bundle.js'\n});\n\ncompiler.run((exit, out, err) =\u003e {\n  if (exit) {\n    process.stderr.write(err, () =\u003e process.exit(exit));\n  } else {\n    process.stderr.write(out);\n    process.stderr.write(err);\n  }\n});\n```\n\nTo run the Compiler, simply call\n\n    node build.js\n\n## What the plugin does\n\n### Convert module namepaths to imported types\n\nClosure Compiler does not allow JSDoc's [namepaths](http://usejsdoc.org/about-namepaths.html) with [module identifiers](http://usejsdoc.org/howto-commonjs-modules.html#module-identifiers) as types. Instead, with `module_resolution: 'NODE'`, it recognizes types that are imported from other files. Let's say you have a file `foo/Bar.js` with the following:\n\n```js\n/** @module foo/Bar */\n\n/**\n * @constructor\n * @param {string} name Name.\n */\nconst Bar = function(name) {\n  this.name = name;\n};\nexport default Bar;\n```\n\nThen you can use the `Bar` type in another module with\n\n```js\n/**\n * @param {module:foo/Bar} bar Bar.\n */\nfunction foo(bar) {}\n```\n\nThis is fine for JSDoc, and this plugin transforms it to something like\n\n```js\n/**\n * @param {foo$Bar} bar Bar.\n */\nfunction foo(bar) {}\nconst foo$Bar = require('./foo/Bar');\n```\n\nWith this, the type definition is recognized by Closure Compiler.\n\n### Convert JSDoc object typedefs to Closure structural interfaces\n\nJSDoc uses a nice, documentable format for `{Object}` typedefs:\n\n```js\n/**\n * @typedef {Object} Foo\n * @property {string} bar Bar.\n * @property {module:types.Baz} baz Baz.\n */\n```\n\nSuch typedefs are not understood by Closure compiler, so they are transformed to something like\n\n```js\n/** @interface */\nexport function Foo() {};\n\n/** @type {(string)} */\nFoo.prototype.bar;\n\n/** @type {(_types_Baz)} */\nFoo.prototype.baz;\n```\n\nProperties marked as optional with JSDoc notation are also handled. The plugin will transforms `@property {number} [foo] Foo.` or `@property {number=} foo Foo.` to `foo: (undefined|number)`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenlayers%2Fbabel-plugin-jsdoc-closure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenlayers%2Fbabel-plugin-jsdoc-closure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenlayers%2Fbabel-plugin-jsdoc-closure/lists"}