{"id":13903217,"url":"https://github.com/yatki/read-env","last_synced_at":"2025-04-10T05:08:20.626Z","repository":{"id":25702973,"uuid":"105992479","full_name":"yatki/read-env","owner":"yatki","description":"🔧 Transform environment variables into JSON object with sanitized values.","archived":false,"fork":false,"pushed_at":"2023-01-07T02:17:08.000Z","size":1034,"stargazers_count":73,"open_issues_count":15,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-10T05:08:13.998Z","etag":null,"topics":["config","configuration","env","environment-variables","javacript","json","nodejs","parse","process","read-env","sanitize","typescript"],"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/yatki.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}},"created_at":"2017-10-06T10:27:02.000Z","updated_at":"2024-11-25T20:55:01.000Z","dependencies_parsed_at":"2023-01-14T03:13:51.445Z","dependency_job_id":null,"html_url":"https://github.com/yatki/read-env","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yatki%2Fread-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yatki%2Fread-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yatki%2Fread-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yatki%2Fread-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yatki","download_url":"https://codeload.github.com/yatki/read-env/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161272,"owners_count":21057555,"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":["config","configuration","env","environment-variables","javacript","json","nodejs","parse","process","read-env","sanitize","typescript"],"created_at":"2024-08-06T22:01:52.941Z","updated_at":"2025-04-10T05:08:20.600Z","avatar_url":"https://github.com/yatki.png","language":"TypeScript","funding_links":[],"categories":["typescript"],"sub_categories":[],"readme":"# read-env\n\n\u003e Transform environment variables into JSON object with sanitized values.\n\n[![NPM version](https://badge.fury.io/js/read-env.svg)](https://www.npmjs.com/package/read-env)\n[![npm](https://img.shields.io/npm/dt/read-env.svg)](https://www.npmjs.com/package/read-env)\n[![Coverage Status](https://coveralls.io/repos/github/yatki/read-env/badge.svg?branch=master\u0026)](https://coveralls.io/github/yatki/read-env?branch=master)\n[![Dependencies](https://david-dm.org/yatki/read-env/status.svg)](https://david-dm.org/yatki/read-env)\n\n\u003e See docs for previous version [v1.3.x](https://github.com/yatki/read-env/tree/v1.3.0).\n\nMain purpose of this library is to allow developers to configure their applications with environment variables. See: [a use case example](#use-case-example).\n\n## What's New with v2.x 🚀\n\n- Migrated to Typescript, Yay! 🎉\n- Simplified API\n- With new `separator` option,nested object constructions are possible.\n- New `source` option allows you to use other objects, other than `process.env`\n\n## Migrating from v1.x to v2.x\n\n- `default` export is **deprecated**. Please use named export `readEnv` as below:\n\n```js\nconst { readEnv } = require('read-env');\n// Or\nimport { readEnv } from 'read-env';\n// Or in browser\nwindow.readEnv('EXAMPLE');\n```\n\n- `parse` option was renamed as `sanitize`.\n- `transformKey` option was renamed as `format`.\n- Deprecated options: `ignoreInvalidJSON`, `prefix`, `filter`,\n\n## Install\n\n```\nnpm install --save read-env\n```\n\nor\n\n```\nyarn add read-env\n```\n\n## Basic Usage\n\nLet's say you have some environment variables starting with prefix \"**EXAMPLE\\_**\" like below:\n\n```text\nEXAMPLE_OBJECT='{\"prop\": \"value\"}'\nEXAMPLE_ARRAY='[1,2,3, \"string\", {\"prop\": \"value\"}, 5.2]'\nEXAMPLE_INVALID_OBJECT='{\"prop\": }\"value\"}'\nEXAMPLE_INVALID_ARRAY='[1,2,3, \"string\", ]{\"prop\": \"value\"}, 5.2]'\nEXAMPLE_TRUE='true'\nEXAMPLE_FALSE='false'\nEXAMPLE_INT='5'\nEXAMPLE_NEGATIVE_INT='-11'\nEXAMPLE_FLOAT='5.2456'\nEXAMPLE_NEGATIVE_FLOAT='-2.4567'\nEXAMPLE_INT_ZERO='0'\nEXAMPLE_FLOAT_ZERO='0.00'\nEXAMPLE_NEGATIVE_INT_ZERO='-0'\nEXAMPLE_NEGATIVE_FLOAT_ZERO='-0.00'\nEXAMPLE_STRING='example'\nEXAMPLE_DEEP__OBJECT__PROPERTY='value'\n```\n\napp.js\n\n```js\nimport { readEnv } from 'read-env';\n\nconst result = readEnv('EXAMPLE');\nconsole.log(result);\n```\n\nResult:\n\n```json\n{\n  \"object\": { \"prop\": \"value\" },\n  \"array\": [1, 2, 3, \"string\", { \"prop\": \"value\" }, 5.2],\n  \"invalidObject\": \"{\\\"prop\\\": }\\\"value\\\"}\",\n  \"invalidArray\": \"[1,2,3, \\\"string\\\", ]{\\\"prop\\\": \\\"value\\\"}, 5.2]\",\n  \"true\": true,\n  \"false\": false,\n  \"int\": 5,\n  \"negativeInt\": -11,\n  \"float\": 5.2456,\n  \"negativeFloat\": -2.4567,\n  \"intZero\": 0,\n  \"floatZero\": 0,\n  \"negativeIntZero\": -0,\n  \"negativeFloatZero\": -0,\n  \"string\": \"example\",\n  \"deep\": {\n    \"object\": {\n      \"property\": \"value\"\n    }\n  }\n}\n```\n\n## API\n\n### `readEnv(prefix?: string, options: ReadEnvOptions = {})`\n\n**Input:**\n\n- `prefix` (type: `string`, default: `undefined`): filters environment variables by prefix\n- `options` (type: `ReadEnvOptions`, default: `{}`): options object to change function's behaviour\n\n**Returns:** `object` (type: _Record\u003cstring,any\u003e_), returns the instance, so add methods are chainable.\n\n### Options\n\n**Default Options:**\n\n```js\n{\n  \"source\": process.env,\n  \"format\": \"camelcase\",\n  \"separator\": \"__\",\n  \"sanitize\": {\n    \"object\": true,\n    \"array\": true,\n    \"bool\": true,\n    \"int\": true,\n    \"float\": true\n  },\n  \"includePrefix\": false\n}\n```\n\n- [`options.source`](#optionssource)\n- [`options.format`](#optionsformat)\n- [`options.separator`](#optionsseparator)\n- [`options.sanitize`](#optionssanitize)\n- [`options.includePrefix`](#optionsincludeprefix)\n\n#### `options.source`\n\n- Type: `object`\n- Default: `process.env`\n\nThe source object that will be filtered, sanitized and formatted.\n\n**Type Signature:**\n\n```ts\ninterface Source {\n  [key: string]: string | undefined;\n}\n```\n\n#### `options.format`\n\n- Type: `boolean | string | function`\n- Default: `camelcase`\n\nFormat environment variable name.\n\nIt's value can be:\n\n- a `boolean`, if set to `false`, formatting is disabled\n- a `string`, one of which `camelcase`, `pascalcase`, `lowercase`, `uppercase`\n- a `function`, with `(rawVarName: string) =\u003e string` type signature\n\n#### `options.separator`\n\n- Type: `boolean | string`\n- Default: `__`\n\nAllows you construct nested objects from environment variable name.\n\n- If set to `false`, constructing nested objects is disabled\n\n**Example:**\n\n```js\nconst { readEnv } = require('read-env');\n\nconst testInput = {\n  EXAMPLE_DEEP__OBJECT_PROPERTY1: 'value1',\n  EXAMPLE_DEEP__OBJECT_PROPERTY2: 'value2',\n};\n\nconst result = readEnv('EXAMPLE', {\n  source: testInput,\n  separator: '_',\n});\nconsole.log(result);\n```\n\nResult:\n\n```json\n{\n  \"deep\": {\n    \"object\": {\n      \"property1\": \"value1\",\n      \"property2\": \"value2\"\n    }\n  }\n}\n```\n\n#### `options.sanitize`\n\n- Type: `boolean | object`,\n- Default: `{}`\n\nSanitize object consists of following properties which is used to\n\n- `object` (type: _bool_, default: _true_): sanitize stringified object\n\n  \u003e value must be valid JSON input, see: [JSON.parse](\u003chttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Using_JSON.parse()\u003e).\n\n- `array` (type: _bool_, default: _true_): sanitize stringified array\n  \u003e value must be valid JSON input, see: [JSON.parse](\u003chttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Using_JSON.parse()\u003e).\n- `int` (type: _bool_, default: _true_): sanitize numbers into integer\n  \u003e value must be consist of only digits.\n- `float` (type: _bool_, default: _true_): sanitize numbers into float\n  \u003e value must be consist of only digits with decimal point.\n- `bool` (type: _bool_, default: _true_): sanitize value into boolean\n  \u003e value must have case insensitive match with \"true\" or \"false\".\n\n#### `options.includePrefix`\n\n- Type: `boolean`\n- Default: `false`\n\nIf set to true, keeps the given prefix in property names.\n\n## Use Case Example\n\nIn past, I used [Nightmare](https://github.com/segmentio/nightmare) for _acceptance testing_ and tests had different configurations based on the\nenvironment they were running on.\n\nSo, I simply used read-env, and nightmare is fully configurable with environment variables :)\n\n```js\nimport Nightmare from 'nightmare';\nimport { readEnv } from 'read-env';\n\nconst nightmareConfig = readEnv('MY_NIGHTMARE');\nconst nightmare = Nightmare(nightmareConfig);\n```\n\nInstead of writing code like below:\n\n```js\nimport Nightmare from 'nightmare';\n\nconst nightmare = Nightmare({\n  show: process.env.MY_NIGHTMARE_SHOW || false,\n  width: process.env.MY_NIGHTMARE_WIDTH || 1280,\n  height: process.env.MY_NIGHTMARE_HEIGHT || 720,\n  typeInterval: process.env.MY_NIGHTMARE_TYPE_INTERVAL || 50,\n  //... other properties go forever\n});\n```\n\n## Contribution\n\nAs always, I'm open to any contribution and would like to hear your feedback.\n\n### Just an important reminder:\n\nIf you are planning to contribute to **any** open source project,\nbefore starting development, please **always open an issue** and **make a proposal first**.\nThis will save you from working on features that are eventually going to be rejected for some reason.\n\n## LICENCE\n\nMIT (c) 2020 Mehmet Yatkı\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyatki%2Fread-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyatki%2Fread-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyatki%2Fread-env/lists"}