Socket
Socket
Sign inDemoInstall

read-env

Package Overview
Dependencies
2
Maintainers
1
Versions
8
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

read-env

Transform environment variables into JSON object with sanitized values.


Version published
Maintainers
1
Weekly downloads
82,707
decreased by-6.47%

Weekly downloads

Readme

Source

read-env

Transform environment variables into JSON object with sanitized values.

NPM version npm Coverage Status Dependencies

See docs for previous version v1.3.x.

Main purpose of this library is to allow developers to configure their applications with environment variables. See: a use case example.

What's New with v2.x 🚀

  • Migrated to Typescript, Yay! 🎉
  • Simplified API
  • With new separator option,nested object constructions are possible.
  • New source option allows you to use other objects, other than process.env

Migrating from v1.x to v2.x

  • default export is deprecated. Please use named export readEnv as below:
const { readEnv } = require('read-env');
// Or
import { readEnv } from 'read-env';
// Or in browser
window.readEnv('EXAMPLE');
  • parse option was renamed as sanitize.
  • transformKey option was renamed as format.
  • Deprecated options: ignoreInvalidJSON, prefix, filter,

Install

npm install --save read-env

or

yarn add read-env

Basic Usage

Let's say you have some environment variables starting with prefix "EXAMPLE_" like below:

EXAMPLE_OBJECT='{"prop": "value"}'
EXAMPLE_ARRAY='[1,2,3, "string", {"prop": "value"}, 5.2]'
EXAMPLE_INVALID_OBJECT='{"prop": }"value"}'
EXAMPLE_INVALID_ARRAY='[1,2,3, "string", ]{"prop": "value"}, 5.2]'
EXAMPLE_TRUE='true'
EXAMPLE_FALSE='false'
EXAMPLE_INT='5'
EXAMPLE_NEGATIVE_INT='-11'
EXAMPLE_FLOAT='5.2456'
EXAMPLE_NEGATIVE_FLOAT='-2.4567'
EXAMPLE_INT_ZERO='0'
EXAMPLE_FLOAT_ZERO='0.00'
EXAMPLE_NEGATIVE_INT_ZERO='-0'
EXAMPLE_NEGATIVE_FLOAT_ZERO='-0.00'
EXAMPLE_STRING='example'
EXAMPLE_DEEP__OBJECT__PROPERTY='value'

app.js

import { readEnv } from 'read-env';

const result = readEnv('EXAMPLE');
console.log(result);

Result:

{
  "object": { "prop": "value" },
  "array": [1, 2, 3, "string", { "prop": "value" }, 5.2],
  "invalidObject": "{\"prop\": }\"value\"}",
  "invalidArray": "[1,2,3, \"string\", ]{\"prop\": \"value\"}, 5.2]",
  "true": true,
  "false": false,
  "int": 5,
  "negativeInt": -11,
  "float": 5.2456,
  "negativeFloat": -2.4567,
  "intZero": 0,
  "floatZero": 0,
  "negativeIntZero": -0,
  "negativeFloatZero": -0,
  "string": "example",
  "deep": {
    "object": {
      "property": "value"
    }
  }
}

API

readEnv(prefix?: string, options: ReadEnvOptions = {})

Input:

  • prefix (type: string, default: undefined): filters environment variables by prefix
  • options (type: ReadEnvOptions, default: {}): options object to change function's behaviour

Returns: object (type: Record<string,any>), returns the instance, so add methods are chainable.

Options

Default Options:

{
  "source": process.env,
  "format": "camelcase",
  "separator": "__",
  "sanitize": {
    "object": true,
    "array": true,
    "bool": true,
    "int": true,
    "float": true
  },
  "includePrefix": false
}
options.source
  • Type: object
  • Default: process.env

The source object that will be filtered, sanitized and formatted.

Type Signature:

interface Source {
  [key: string]: string | undefined;
}
options.format
  • Type: boolean | string | function
  • Default: camelcase

Format environment variable name.

It's value can be:

  • a boolean, if set to false, formatting is disabled
  • a string, one of which camelcase, pascalcase, lowercase, uppercase
  • a function, with (rawVarName: string) => string type signature
options.separator
  • Type: boolean | string
  • Default: __

Allows you construct nested objects from environment variable name.

  • If set to false, constructing nested objects is disabled

Example:

const { readEnv } = require('read-env');

const testInput = {
  EXAMPLE_DEEP__OBJECT_PROPERTY1: 'value1',
  EXAMPLE_DEEP__OBJECT_PROPERTY2: 'value2',
};

const result = readEnv('EXAMPLE', {
  source: testInput,
});
console.log(result);

Result:

{
  "deep": {
    "object": {
      "property1": "value1",
      "property2": "value2"
    }
  }
}
options.sanitize
  • Type: boolean | object,
  • Default: {}

Sanitize object consists of following properties which is used to

  • object (type: bool, default: true): sanitize stringified object

    value must be valid JSON input, see: JSON.parse.

  • array (type: bool, default: true): sanitize stringified array

    value must be valid JSON input, see: JSON.parse.

  • int (type: bool, default: true): sanitize numbers into integer

    value must be consist of only digits.

  • float (type: bool, default: true): sanitize numbers into float

    value must be consist of only digits with decimal point.

  • bool (type: bool, default: true): sanitize value into boolean

    value must have case insensitive match with "true" or "false".

options.includePrefix
  • Type: boolean
  • Default: false

If set to true, keeps the given prefix in property names.

Use Case Example

In past, I used Nightmare for acceptance testing and tests had different configurations based on the environment they were running on.

So, I simply used read-env, and nightmare is fully configurable with environment variables :)

import Nightmare from 'nightmare';
import { readEnv } from 'read-env';

const nightmareConfig = readEnv('MY_NIGHTMARE');
const nightmare = Nightmare(nightmareConfig);

Instead of writing code like below:

import Nightmare from 'nightmare';

const nightmare = Nightmare({
  show: process.env.MY_NIGHTMARE_SHOW || false,
  width: process.env.MY_NIGHTMARE_WIDTH || 1280,
  height: process.env.MY_NIGHTMARE_HEIGHT || 720,
  typeInterval: process.env.MY_NIGHTMARE_TYPE_INTERVAL || 50,
  //... other properties go forever
});

Contribution

As always, I'm open to any contribution and would like to hear your feedback.

Just an important reminder:

If you are planning to contribute to any open source project, before starting development, please always open an issue and make a proposal first. This will save you from working on features that are eventually going to be rejected for some reason.

LICENCE

MIT (c) 2020 Mehmet Yatkı

Keywords

FAQs

Last updated on 02 Apr 2020

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc