{"id":14384865,"url":"https://github.com/bahmutov/comment-value","last_synced_at":"2025-09-29T05:31:47.296Z","repository":{"id":57204158,"uuid":"79189433","full_name":"bahmutov/comment-value","owner":"bahmutov","description":"Instruments a Node program and updates its comments with computed expression values","archived":false,"fork":false,"pushed_at":"2017-02-14T04:55:22.000Z","size":1289,"stargazers_count":27,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-12-27T20:07:25.476Z","etag":null,"topics":["comment","helper","nodejs","value"],"latest_commit_sha":null,"homepage":"https://www.youtube.com/watch?v=6-fAMqqYQ7g","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bahmutov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-17T04:47:41.000Z","updated_at":"2023-09-08T17:19:31.000Z","dependencies_parsed_at":"2022-09-18T00:51:00.263Z","dependency_job_id":null,"html_url":"https://github.com/bahmutov/comment-value","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahmutov%2Fcomment-value","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahmutov%2Fcomment-value/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahmutov%2Fcomment-value/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahmutov%2Fcomment-value/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bahmutov","download_url":"https://codeload.github.com/bahmutov/comment-value/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234594211,"owners_count":18857419,"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":["comment","helper","nodejs","value"],"created_at":"2024-08-28T18:01:43.948Z","updated_at":"2025-09-29T05:31:41.967Z","avatar_url":"https://github.com/bahmutov.png","language":"JavaScript","readme":"# comment-value\n\n\u003e Instruments a Node program and updates its comments with computed expression values\n\n[![NPM][npm-icon] ][npm-url]\n\n[![Build status][ci-image] ][ci-url]\n[![semantic-release][semantic-image] ][semantic-url]\n[![js-standard-style][standard-image]][standard-url]\n\n## Why?\n\nWriting and maintaining code examples is hard. Often the values shown in\nthe comments (think blog posts) are out of date and incorrect.\n\nRead more about the problem and this tool solves it in blog post\n[Accurate values in comments](https://glebbahmutov.com/blog/accurate-values-in-comments/).\n\n## What does comment-value do?\n\n`comment-value` (or available aliases `values`, `comment`, `comments`)\nexecutes your Node program, instrumenting it on the fly.\nEvery time it sees a special comment that starts with `//\u003e`,\nit will set it value from whatever the expression immediately to its left is.\n\nWhen Node finishes, the file is saved back with updated comments.\n\n[![comment-value in action](images/comment-value.png)](https://comment-values-awgxclhogn.now.sh/comment-values.webm)\n\nClick on the above screen shot to see 15 second demo clip.\n\n## Watch mode\n\nAutomatically (well, as long as `chokidar` works) reruns and updates comments\nin the source file. See the\n[video](https://glebbahmutov.com/comment-value/comment-value-watch-mode.webm),\nit is awesome!\n\n## Install and use\n\nInstall `comment-value` either as a global or as a local package.\n\n```\nnpm install -g comment-value\n```\n\nUse either using `node -r comment-value index.js` or via CLI alias:\n`comment-value`, `values` or `cv` like this `values index.js`.\n\nAlias `values` is the preferred way. It allows\n\n* Watch files for changes and rerun with `-w, --watch` option\n* Print instrumented file with `-i, --instrumented` option\n\n## Example\n\nAdd a few comments that start with `//\u003e` to `index.js`. You can put anything\nafter that into the comment.\n\n```js\n// index.js\nconst add = (a, b) =\u003e a + b\nadd(2, 3) //\u003e\nadd(2, -3) //\u003e ? anything here\n// you can also print variables\nconst t = typeof add\n// t:\n// or variable types directly\n// add::\n```\n\nRun the `comment-value` script which runs your Node\n\n```sh\n$ comment-value index.js\n```\n\nThe `index.js` will now contain\n\n```js\n// index.js\nconst add = (a, b) =\u003e a + b\nadd(2, 3) //\u003e 5\nadd(2, -3) //\u003e -1\n// you can also print variables!\nconst t = typeof add\n// t: \"function\"\n// add:: \"function\"\n```\n\n## Comment format\n\nYou can start special value comments to be updated with strings\n`//\u003e`, `//=\u003e`, `//~\u003e`, `// \u003e`, `// =\u003e` and even `// ~\u003e`.\n\nFor variables, use line comment with just variable name followed by `:`,\nfor example\n\n```js\nfunction add(a, b) {\n  // a:\n  // b:\n}\nadd(10, 2)\n```\n\nwhich will produce\n\n```js\nfunction add(a, b) {\n  // a: 10\n  // b: 2\n}\nadd(10, 2)\n```\n\nTo print the type of a variable, use variable name followed by `::`, for\nexample\n\n```js\nfunction add(a, b) {\n  // a:: \"number\"\n  // b:: \"string\"\n}\nadd(10, 'foo')\n```\n\n## Composed functions\n\nYou can even get results from composed functions, for example, the values\nbelow were all computed automatically\n\n```js\nvar R = require('ramda')\nR.compose(\n  Math.abs,     //=\u003e 7\n  R.add(1),     //=\u003e -7\n  R.multiply(2) //=\u003e -8\n)(-4) //=\u003e 7\n```\n\n## Mixing values and types\n\nYou can record either values or types of values\n\n```js\nvar R = require('ramda')\nR.compose(\n  Math.abs,     //:: number\n  R.add(1),     //=\u003e -7\n  R.multiply(2) //=\u003e -8\n)(-4)\n// :: number\n```\n\n## Console log statements\n\nIf the value comment is on the left of `console.log(value)` expression,\nthen it will be updated with the `value`.\n\n```js\n// index.js\nconsole.log(2 + 40) //\u003e ?\n```\n\n```sh\n$ comment-value index.js\n42\n```\n\n```js\n// index.js\nconsole.log(2 + 40) //\u003e 42\n```\n\n## Debug\n\nTo see verbose messages while this module runs, set the environment\nvariable `DEBUG` before running\n\n```\nDEBUG=comment-value node ...\n```\n\nThe instrumenting function has a global emitter, you can receive messages\nwhen special comments are found and when an expression is wrapped.\nFor example this code will produce the following events\n\n```js\n// index.js\nconsole.log(2 + 40) //\u003e ??\n// spec.js\nlet emitter\nbeforeEach(() =\u003e {\n  emitter = global.instrument\n})\nit('finds the comment', () =\u003e {\n  const comments = []\n  const wrapped = []\n  emitter.on('comment', c =\u003e comments.push(c))\n  emitter.on('wrap', w =\u003e wrapped.push(w))\n  instrument(source)\n  // comments will be [\"\u003e ??\"]\n  // wrapped will be [\"2 + 40\"]\n})\n```\n\nThis is an internal feature and is used during unit tests.\n\n### Small print\n\nAuthor: Gleb Bahmutov \u0026lt;gleb.bahmutov@gmail.com\u0026gt; \u0026copy; 2017\n\n* [@bahmutov](https://twitter.com/bahmutov)\n* [glebbahmutov.com](http://glebbahmutov.com)\n* [blog](http://glebbahmutov.com/blog)\n\nLicense: MIT - do anything with the code, but don't blame me if it does not work.\n\nSupport: if you find any problems with this module, email / tweet /\n[open issue](https://github.com/bahmutov/comment-value/issues) on Github\n\n## MIT License\n\nCopyright (c) 2017 Gleb Bahmutov \u0026lt;gleb.bahmutov@gmail.com\u0026gt;\n\nPermission is hereby granted, free of charge, to any person\nobtaining a copy of this software and associated documentation\nfiles (the \"Software\"), to deal in the Software without\nrestriction, including without limitation the rights to use,\ncopy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following\nconditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES\nOF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT\nHOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,\nWHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR\nOTHER DEALINGS IN THE SOFTWARE.\n\n[npm-icon]: https://nodei.co/npm/comment-value.svg?downloads=true\n[npm-url]: https://npmjs.org/package/comment-value\n[ci-image]: https://travis-ci.org/bahmutov/comment-value.svg?branch=master\n[ci-url]: https://travis-ci.org/bahmutov/comment-value\n[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg\n[semantic-url]: https://github.com/semantic-release/semantic-release\n[standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg\n[standard-url]: http://standardjs.com/\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbahmutov%2Fcomment-value","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbahmutov%2Fcomment-value","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbahmutov%2Fcomment-value/lists"}