{"id":16682582,"url":"https://github.com/jchip/xenv-config","last_synced_at":"2025-08-28T17:07:29.125Z","repository":{"id":57401272,"uuid":"95088878","full_name":"jchip/xenv-config","owner":"jchip","description":"Load config from env, user config, or default spec","archived":false,"fork":false,"pushed_at":"2020-03-21T08:24:40.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-21T13:47:37.405Z","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/jchip.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-06-22T07:46:36.000Z","updated_at":"2020-03-21T08:24:39.000Z","dependencies_parsed_at":"2022-09-19T04:50:43.952Z","dependency_job_id":null,"html_url":"https://github.com/jchip/xenv-config","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxenv-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxenv-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxenv-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fxenv-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jchip","download_url":"https://codeload.github.com/jchip/xenv-config/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243392326,"owners_count":20283565,"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-12T14:08:00.203Z","updated_at":"2025-03-13T11:17:57.964Z","avatar_url":"https://github.com/jchip.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url]\n[![Dependency Status][daviddm-image]][daviddm-url] [![devDependency Status][daviddm-dev-image]][daviddm-dev-url]\n\n# xenv-config\n\nLoad config from env, user config, or default spec.\n\n## Install\n\n```bash\n$ npm i xenv-config --save\n```\n\n## Usage\n\n```js\nconst xenvConfig = require(\"xenv-config\");\nconst spec = {\n  fooOption: { env: \"FOO_OPTION\", default: false },\n  barOption: { env: \"BAR_OPTION\", type: \"number\" },\n  zooOption: { default: false, type: \"truthy\" },\n  jsonOption: { env: \"JSON_OPTION\", type: \"json\" }\n};\n\nprocess.env.BAR_OPTION = \"900\";\nprocess.env.JSON_OPTION = \"{b:90}\";\nconst config = xenvConfig(spec, { zooOption: true, jsonOption: { a: 50 } });\n\nexpect(config).to.deep.equal({\n  fooOption: false,\n  barOption: 900,\n  zooOption: true,\n  jsonOption: { a: 50, b: 90 }\n});\n\nexpect(config.__$trace__).to.deep.equal({\n  fooOption: { src: \"default\" },\n  barOption: { src: \"env\", name: \"BAR_OPTION\" },\n  zooOption: { src: \"option\" },\n  jsonOption: { src: \"env,option\" }\n});\n```\n\n## API\n\n```js\nxenvConfig(spec, userConfig, options);\n```\n\n- `spec` - specification of the configs\n- `userConfig` - configuration from the user (use if not declared in env)\n- `options` - options\n\nReturns `config` object.\n\n- Each key that exist has the value that's determined\n- A hidden field `__$trace__` that contains data to indicate where each config key's value was determined from\n\n`options`:\n\n- `_env` - Object that represents environment instead of `process.env`\n- `merge` - function to merge `json` object instead of using `Object.assign`\n\n## Spec\n\nThe spec is a JSON object with the following format:\n\n```js\n{\n  \"\u003coptionKey\u003e\": {\n    env: \"ENV_VAR_NAME\",\n    envMap: {},\n    default: \u003cdefault_value\u003e,\n    type: \"\u003ctype\u003e\",\n    post: (val, trace) =\u003e {}\n  }\n}\n```\n\n- Each `optionKey` specifies the name of the option\n- Its value should be an object with the following fields:\n  - `env`: the name (or array of names) of the environment varialbe(s) to check first. If it's `true`, then use `optionKey` as the env variable name.\n  - `envMap`: an object of mapping env value to another value.\n  - `default`: the default value or a function to return the default value.\n  - `type`: indicate how to interpret and convert the string from `process.env`.\n  - `post`: callback to post process value\n\n\u003e All fields are `optional`, if they are all skipped, then the config option will be determined from `userConfig` only.\n\u003e\n\u003e Without either `default` or `type`, the value from `env` will remain as a string.\n\u003e\n\u003e If `default` is a function, then `type` must be defined or it will be `string`.\n\u003e\n\u003e If `env` is an array, then the first one that finds a value in `process.env` will be used.\n\u003e\n\u003e If `env` is `true`, then use `optionKey` as the name to look up from `process.env`.\n\n### Types\n\nWhen loading from `env`, in order to indicate what value to convert the string into, the type can be one of.\n\n- `string` - no conversion\n- `number` - (integer) convert with `parseInt(x,10)`\n- `float` - (float) convert with `parseFloat(x)`\n- `boolean` - (boolean) convert with `x === \"true\" || x === \"yes\" || x === \"1\" || x === \"on\"`\n- `truthy` - (boolean from truthy check) convert with `!!x`\n- `json` - (JSON) parsed with `JSON.parse`\n\n\u003e If `type` is not specified, and `default` exist and not a function, then `typeof default` will be used.\n\n### Trace\n\nThe hidden field `__$trace__` contain data for each key to indicate where its value was determined from.\n\n- If the value's from env, then it's `{src: \"env\", name: \"ENV_OPTION_NAME\"}`\n- If the value's from user config, then it's `{src: \"option\"}`\n- If the value's from default, then it's `{src: \"default\"}`\n\n### json Type\n\n`json` type is slightly different.\n\n- If `default` is an object like `{}`, then type is detected to be `json`, unless spec has `type` explicitly.\n- Values from all three sources are combined in the following order `env`, `option`, `default`.\n- It uses `Object.assign` to combine values unless you pass in a `merge` function in options. For example, merge from `lodash`.\n- `trace.src` would be a comma separate list of them. For example, `\"env,option\"`, `\"env,option,default\"`, or `\"option,default\"`\n\n## Option Orders\n\nThe order of source to check are:\n\n1.  The `env` if it's defined in the spec and `process.env` contains the variable\n2.  The value from `userConfig` directly if it contains the `optionKey`\n3.  The default value from spec if it's declared\n4.  Nothing\n\n[travis-image]: https://travis-ci.org/jchip/xenv-config.svg?branch=master\n[travis-url]: https://travis-ci.org/jchip/xenv-config\n[npm-image]: https://badge.fury.io/js/xenv-config.svg\n[npm-url]: https://npmjs.org/package/xenv-config\n[daviddm-image]: https://david-dm.org/jchip/xenv-config/status.svg\n[daviddm-url]: https://david-dm.org/jchip/xenv-config\n[daviddm-dev-image]: https://david-dm.org/jchip/xenv-config/dev-status.svg\n[daviddm-dev-url]: https://david-dm.org/jchip/xenv-config?type=dev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchip%2Fxenv-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjchip%2Fxenv-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchip%2Fxenv-config/lists"}