{"id":15361842,"url":"https://github.com/tj/eson","last_synced_at":"2025-04-14T16:02:04.042Z","repository":{"id":2793983,"uuid":"3794198","full_name":"tj/eson","owner":"tj","description":"Extended (pluggable) JSON for node - great for configuration files and JSON transformations","archived":false,"fork":false,"pushed_at":"2014-02-11T01:23:19.000Z","size":208,"stargazers_count":150,"open_issues_count":5,"forks_count":14,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-04T15:18:26.891Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/tj.png","metadata":{"files":{"readme":"Readme.md","changelog":"History.md","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":"2012-03-22T03:40:59.000Z","updated_at":"2023-08-19T17:41:11.000Z","dependencies_parsed_at":"2022-09-01T22:31:15.015Z","dependency_job_id":null,"html_url":"https://github.com/tj/eson","commit_stats":null,"previous_names":["visionmedia/eson"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tj%2Feson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tj%2Feson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tj%2Feson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tj%2Feson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tj","download_url":"https://codeload.github.com/tj/eson/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248914005,"owners_count":21182356,"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-10-01T12:56:53.429Z","updated_at":"2025-04-14T16:02:04.013Z","avatar_url":"https://github.com/tj.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\n# eson\n\n  Extended JSON for node.\n\n## Installation\n\n```\n$ npm install eson\n```\n\n## Parser\n\n  Currently only the parser portion is implemented, useful for configuration files.\n  For example a typical configuration file might look something like the following:\n\n```js\n{\n  \"views\": \"/www/example.com/views\",\n  \"view engine\": \"jade\",\n  \"poll interval\": 5000,\n  \"canvas size\": { \"width\": 800, \"height\": 600 }\n}\n```\n\n With Extended JSON you can define plugin functions, or use ones\n bundled with eson to transform the input, allowing for more\n declarative configurations as shown here:\n\n```js\n{\n  \"views\": \"{root}/views\",\n  \"view engine\": \"jade\",\n  \"poll interval\": \"5 seconds\",\n  \"canvas size\": \"800x600\"\n}\n```\n\n### Writing plugins\n\n Writing a plugin is simple, it's a function which takes the signature `(key, val, parser)`. Let's write one that transforms every value to \"foo\":\n\n```js\nfunction foo(key, val, parser) {\n  return 'foo';\n}\n```\n\n Then use the plugin like so:\n\n```js\nvar eson = require('eson');\n\nvar conf = eson()\n  .use(foo)\n  .read('path/to/config.json');\n```\n\n Now suppose `path/to/config.json` contained `{ \"foo\": \"bar\", \"bar\": \"baz\" }`,\n the `foo()` plugin would yield `{ \"foo\": \"foo\", \"bar\": \"foo\" }`. So you get the picture,\n with this we can accept arbitrary strings such as \"5 seconds\" and transform\n it to the more useful `5000` milliseconds representation.\n\n Many plugins may of course be used, and _all_ will be executed regardless, so if necessary\n subsequent plugins may still make modifications. Depending on what the plugins the order used _may_ have an effect on the JSON.\n\n```js\neson()\n  .use(eson.ms)\n  .use(eson.include)\n  .use(eson.dimensions)\n  .use(eson.replace('{root}', '/www/example.com'))\n  .parse('{ \"interval\": \"15 minutes\" }');\n```\n### eson.ms\n\n  The milliseconds plugin supports strings like \"5s\", \"5 seconds\", \"3 days\", etc:\n  \n```js\neson()\n  .use(eson.ms)\n  .parse('{ \"interval\": \"15 minutes\" }');\n```\n\nyields:\n\n```js\n{ interval: 900000 }\n```\n\n### eson.include\n\n  The include plugin allows you to literally include other JSON files. This works in\n  both arrays and object literals, and loads relative to the callee's file. For example:\n  \n```js\neson()\n  .use(eson.include)\n  .parse('{ \"prod\": \"include config/production\" }');\n```\n\nyields:\n\n```js\n{ prod: { whatever: 'is', within: 'config/production.json' }}\n```\n\n You can also include multiple files via a glob. This has a special syntax and works in one of three ways.\n\nConsider a config folder containing the following two files:\n\n*database.json:*\n```json\n{\"db\", \"redis\"}\n```\n*app.json:*\n```json\n{\"listen\", 3000}\n```\n\n##### Merging multiple files into one:\n\n```js\n\neson()\n  .use(eson.include)\n  .parse('{ \"prod\": \"include config/*\" }');\n```\nyields:\n\n```js\n{\n\tprod: {\n\t\tdb: \"redis\",\n\t\tlisten: 3000\n\t}\n}\n```\n\n##### Collect files into a map, keyed by filename:\n\n```js\n\n// use curly brackets to collect as a map\neson()\n  .use(eson.include)\n  .parse('{ \"prod\": \"include { config/* }\" }');\n\n```\n\nyields:\n\n\n```js\n{\n\tprod: {\n\t\tdatabase: {\n\t\t\tdb: \"redis\"\n\t\t},\n\t\tapp: {\n\t\t\tlisten: 3000\n\t\t}\n\t}\n}\n\n```\n\n##### Collect files as an array:\n\n\n```js\n\n// use square brackets to collect as an array\neson()\n  .use(eson.include)\n  .parse('{ \"prod\": \"include [ config/* ]\" }'); \n\n```\n\nyields:\n\n```js\n{\n\tprod: [\n\t\t{db: \"redis\"},\n\t\t{listen: 3000}\n\t]\n}\n```\n\n\n### eson.bools\n\n  Convert \"yes\", \"no\", \"on\", \"off\", \"enabled\", \"disabled\" into booleans.\n\n### eson.env([prefix])\n\n  Allow environment variables to define config values. If you have the following:\n\n```js\n{\n  \"upload path\": \"/data/uploads\"\n}\n```\n\n  You could then export `UPLOAD_PATH=/tmp` to change this value. Optionally when\n  a `prefix` is given such as \"MYAPP_\" then you must prefix such as `MYAPP_UPLOAD_PATH=/tmp`.\n\n### eson.replace(str, val)\n\n  The replace plugin allows you to replace arbitrary substrings, useful\n  for constants such as the application's root directory etc.\n  \n```js\neson()\n  .use(eson.replace('{root}', '/www/example.com'))\n  .parse('{ \"upload path\": \"{root}/tmp\" }');\n```\n\nyields:\n\n```js\n{ \"upload path\": \"/www/example.com/tmp\" }\n```\n\n### eson.args([args])\n\n  Parse from the given `args` or __ARGV__. For example if you have a setting\n  named \"dev ui\" with a default value of `false`, `--dev-ui` would enable it,\n  or `--dev-ui yes` would provide the value \"yes\" which is of course also truthy.\n\n  To compliment `--NAME` you may also negate this, if \"dev ui\" is enabled by default\n  then you may use `--no-dev-ui` to disable it.\n\n### eson.glob\n\n  The glob plugin allows you to specify glob strings, prefixed by \"glob\":\n  \n```js\neson()\n  .use(eson.glob)\n  .parse('{ \"js\": \"glob public/{js,vendor}/*.js\" }');\n```\n\nyields:\n\n```js\n{ js: [\"public/js/app.js\", \"public/js/user.js\", \"public/vendor/jquery.js\"] }\n```\n\n## moar!\n\n  That's it for now, just experimenting with it, feel free to send me a PR\n  or open and issue if you have some ideas. I'd like to keep everything\n  valid JSON, for example you can use the `include` plugin to include\n  env-specific config into package.json, and package.json remains a\n  valid JSON document.\n\n  For addition documentation view the [test markdown](https://github.com/visionmedia/eson/blob/master/tests.md).\n\n## Running tests\n\n```\n$ npm install\n$ make test\n```\n\n## License \n\n(The MIT License)\n\nCopyright (c) 2012 TJ Holowaychuk \u0026lt;tj@vision-media.ca\u0026gt;\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n'Software'), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\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 OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftj%2Feson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftj%2Feson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftj%2Feson/lists"}