{"id":14156056,"url":"https://github.com/zoontek/valienv","last_synced_at":"2025-04-09T16:11:00.078Z","repository":{"id":37800428,"uuid":"460041424","full_name":"zoontek/valienv","owner":"zoontek","description":"A simple environment variables validator for Node.js, web browsers and React Native ✓","archived":false,"fork":false,"pushed_at":"2025-02-04T16:38:47.000Z","size":710,"stargazers_count":35,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T16:10:50.380Z","etag":null,"topics":["env","environment","validation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/zoontek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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},"funding":{"github":["zoontek"]}},"created_at":"2022-02-16T14:34:41.000Z","updated_at":"2025-02-04T23:19:00.000Z","dependencies_parsed_at":"2024-02-26T10:28:08.530Z","dependency_job_id":"7180065d-9ad1-4cdf-a78e-df7839caa202","html_url":"https://github.com/zoontek/valienv","commit_stats":{"total_commits":49,"total_committers":2,"mean_commits":24.5,"dds":"0.12244897959183676","last_synced_commit":"11aa6f8226980dfd834ac4e27f76f53d4d64751d"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoontek%2Fvalienv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoontek%2Fvalienv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoontek%2Fvalienv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoontek%2Fvalienv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zoontek","download_url":"https://codeload.github.com/zoontek/valienv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065284,"owners_count":21041872,"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":["env","environment","validation"],"created_at":"2024-08-17T08:05:11.244Z","updated_at":"2025-04-09T16:11:00.060Z","avatar_url":"https://github.com/zoontek.png","language":"TypeScript","funding_links":["https://github.com/sponsors/zoontek"],"categories":["others"],"sub_categories":[],"readme":"# ✓ valienv\n\nA simple environment variables validator for Node.js, web browsers and React Native.\n\n[![mit licence](https://img.shields.io/dub/l/vibe-d.svg?style=for-the-badge)](https://github.com/zoontek/valienv/blob/main/LICENSE)\n[![npm version](https://img.shields.io/npm/v/valienv?style=for-the-badge)](https://www.npmjs.org/package/valienv)\n[![bundlephobia](https://img.shields.io/bundlephobia/minzip/valienv?label=size\u0026style=for-the-badge)](https://bundlephobia.com/result?p=valienv)\n\n## Installation\n\n```sh\n$ npm i valienv --save\n# --- or ---\n$ yarn add valienv\n```\n\n## 📘 Usage\n\nThis library exports a main function: `validate`.\u003cbr\u003e\nUsing `validators`, you can parse, validate and type required environment variables (other variables will be excluded).\n\n```ts\nimport { boolean, number, oneOf, string, validate } from \"valienv\";\n\n// with process.env = {\n//   ACCENT_COLOR: \"#0099e5\",\n//   TIMEOUT_MS: \"5000\",\n//   ENABLE_ANALYTICS: \"true\",\n//   NODE_ENV: \"development\",\n// }\n\nexport const env = validate({\n  env: process.env,\n  validators: {\n    // we validate env using bundled validators\n    ACCENT_COLOR: string,\n    TIMEOUT_MS: number,\n    ENABLE_ANALYTICS: boolean,\n    NODE_ENV: oneOf(\"development\", \"test\", \"production\"),\n  },\n});\n\n// -\u003e typeof env = Readonly\u003c{\n//   ACCENT_COLOR: string;\n//   TIMEOUT_MS: number;\n//   ENABLE_ANALYTICS: boolean;\n//   NODE_ENV: \"development\" | \"test\" | \"production\";\n// }\u003e\n```\n\n_⚠️  In case of incorrect environment variables, the function will either exit the process or throw an EnvValidationError, exposing the variable names (but not their values) to prevent your application from starting._\n\n#### overrides\n\nThe `overrides` option is useful to override some variables in some contexts.\n\n```ts\nimport { string, validate } from \"valienv\";\n\n// with process.env = {\n//   CONTACT_EMAIL: \"zoontek@github.com\",\n// }\n\nexport const env = validate({\n  env: process.env,\n  validators: {\n    CONTACT_EMAIL: string,\n  },\n  overrides: {\n    ...(process.env.NODE_ENV === \"test\" \u0026\u0026 {\n      CONTACT_EMAIL: \"no-mail\",\n    }),\n  },\n});\n\n// -\u003e typeof env = Readonly\u003c{ CONTACT_EMAIL: string }\u003e\n```\n\n_⚠️  The values set has to be correctly typed but are **not** validated._\n\n### Custom validators\n\nBy default, `valienv` exports 6 validators: `string`, `number`, `boolean`, `url`, `port` and `email`. It also offers `oneOf`, a helper to create validators for union of string literals.\n\nIt's very easy to write your own:\n\n```ts\nimport { validate, Validator } from \"valienv\";\n\n// A validator take raw input, try to parse it and\n// returns the result in case of valid value:\nconst buffer: Validator\u003cBuffer\u003e = (value: string = \"\") =\u003e {\n  const valid = /^[A-F\\d]+$/i.test(value);\n\n  if (valid) {\n    return Buffer.from(value);\n  }\n};\n\n// with process.env = {\n//   COOKIE_KEY: \"aba4a6fb2222ef28d81e4be445a51fba\",\n// }\n\nexport const env = validate({\n  env: process.env,\n  validators: {\n    COOKIE_KEY: buffer,\n  },\n});\n\n// -\u003e typeof env = Readonly\u003c{ COOKIE_KEY: Buffer }\u003e\n```\n\nYou can even go wild by using stricter types, complex parsing, your favorite validation library, etc! 🔥\n\n```ts\nimport validator from \"validator\";\nimport { validate } from \"valienv\";\n\n// with process.env = {\n//   ETHEREUM_ADDRESS: \"0xb794f5ea0ba39494ce839613fffba74279579268\",\n//   OPENED_COUNTRIES: \"FR,BE,DE\",\n// }\n\nexport const env = validate({\n  env: process.env,\n  validators: {\n    // inlined validators return types are correctly inferred\n    ETHEREUM_ADDRESS: (value = \"\") =\u003e {\n      if (validator.isEthereumAddress(value)) {\n        return value;\n      }\n    },\n    OPENED_COUNTRIES: (value = \"\") =\u003e {\n      const array = value.split(\",\");\n\n      if (array.every(validator.isISO31661Alpha2)) {\n        return array;\n      }\n    },\n  },\n});\n\n// -\u003e typeof env = Readonly\u003c{\n//   ETHEREUM_ADDRESS: string;\n//   OPENED_COUNTRIES: string[];\n// }\u003e\n```\n\n### Optional values\n\nAs it's a common pattern to have some optional environment values, we provide `optional`, a small helper to wrap every validator with:\n\n```ts\nimport { optional, string, validate } from \"valienv\";\n\nconst env = validate({\n  env: process.env,\n  validators: {\n    FOO: optional(string),\n  },\n});\n\nif (env.FOO.defined) {\n  console.log(env.FOO.value); // FOO.value can only be accessed when defined is true\n}\n```\n\nYou can also wrap validators using a library of your choice. Here's an example with [`@swan-io/boxed`](https://github.com/swan-io/boxed):\n\n```ts\nimport { string, validate } from \"valienv\";\nimport { Option } from \"@swan-io/boxed\";\n\nconst optional =\n  \u003cT\u003e(validator: Validator\u003cT\u003e): Validator\u003cOption\u003cT\u003e\u003e =\u003e\n  (value) =\u003e\n    Option.fromUndefined(validator(value));\n\nconst env = validate({\n  env: process.env,\n  validators: {\n    FOO: optional(string),\n  },\n});\n\nenv.FOO.match({\n  Some: (value) =\u003e {\n    // env.FOO is set, you can use its value\n  },\n  None: () =\u003e {\n    // env.FOO isn't set\n  },\n});\n```\n\n## ❓ Questions\n\n#### Why not handling `NODE_ENV` for us?\n\nFrontend bundlers generally **statically replace** `process.env.NODE_ENV` values at build time, allowing minifiers like [`terser`](https://github.com/terser/terser) to eliminate dead code from production build. Aliasing `NODE_ENV` would prevent such optimisations.\u003cbr /\u003e\nBut if you are working with Node.js, feel free to use `oneOf` on `NODE_ENV` if you want.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoontek%2Fvalienv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoontek%2Fvalienv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoontek%2Fvalienv/lists"}