npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@logdna/env-config

v2.0.1

Published

Configuration package for reading environment variables

Downloads

1,191

Readme

Coverage Status

All Contributors

@logdna/env-config

Node.js Package to define, document, and assert environment variables

Install

$ npm install --save @logdna/env-config

Test

$ npm t

Usage

The recommended way to structure applications with this package is as follows:

// config.js

'use strict'

const Config = require('@logdna/env-config')
const config = new Config([
  Config.string('loglevel').default('info')
, Config.number('port').default(3000)
])

module.exports = config
// index.js
//
// The following env vars can be set:
//
// LOGLEVEL - defaults to info
// PORT - default to 3000
//

'use strict'

const http = require('http')
const config = require('./config.js')

// This validates that we have the necessary env vars.
config.validateEnvVars()

http.listen(config.get('port'), () => {
  log.info('listen', config.get('port'))
})

Under the hood, Config is a <Map>, so use it like one.

This package also provides a way to automatically generate documentation for the environment variables for a service.

If the doc directory does not exist, it can be created using the following:

$ mkdir -p doc

Then, add a generate script to the service's package.json that looks similar to this:

config-doc config.js > doc/env.md

You should also add a link to this document in the README.md of the service.

API

new Config(input)

  • input <Array> Array of objects that represent a single rule.

Each input item should be a Definition. See "Static Methods" below.

Static Methods


The following static methods return a Definition that can be used.

Config.string(name)

  • name <String> Name of the config rule. The environment variable read for this rule will be name uppercased with - replaced with _.

This defines a configuration definition for an environment variable that is a <String>.

Returns: Definition

Config.number(name)

  • name <String> Name of the config rule. The environment variable read for this rule will be name uppercased with - replaced with _.

This defines a configuration defintion for an environment variable that is a <Number>.

Returns: Definition

Config.boolean(name)

  • name <String> Name of the config rule. The environment variable read for this rule will be name uppercased with - replaced with _.

This defines a configuration definition for an environment variable that is a <Boolean>.

Returns: Definition

Config.regex(name)

  • name <String> Name of the config rule. The environment variable read for this rule will be name uppercased with - replaced with _.

This defines a configuration definition for an environment variable that matches a <RegExp>.

Returns: Definition

Config.enum(name)

  • name <String> Name of the config rule. The environment variable read for this rule will be name uppercased with - replaced with _.

A single value will be read from the environment variable as described, but it must exist in the allowed list of .values(). Every enum type needs to implement a .values() array.

Config.list(name)

  • name <String> Name of the config rule. The environment variable read for this rule will be name uppercased with - replaced with _.

Much like a CSV - an environment variable will be read and parsed into an array of a specific type. The type can be of string, boolean, or number. This is defined by calling .type(). All empty values generated by trailing characters are removed

Instance Methods


Config#toJSON()

Returns a JSON representation of the config object. This will only work for Primitive values, objects, and arrays.

Config#validateEnvVars()

This should be called to validate that the required environment variables have been passed and that they satisfy the requirements. If any are not passed, or do not satisfy the requirements, an error will be thrown.

Definition

This is a private prototype that offers the following methods:

Definition#required()

Specifies that this env var is required to have a value (env vars are optional by default). This means that a value must be provided, and it cannot be the empty string, ''.

Returns this to allow chaining.

Definition#desc(str)

This sets the description for the env var that will be used for docs. This is an alias for the Definition#description(str) method.

Returns this to allow chaining.

Definition#description(str)

This sets the description for the env var that will be used for docs.

Returns this to allow chaining.

Definition#default(def)

This sets the default value of the rule. This does not set the actual env var, but the value in the config's <Map> will show the default value if the env var's value is empty.

The default value will be applied for an unset var as well as a value of ''.

Returns this to allow chaining.

Definition#allowEmpty()

allowEmpty() tells the definition to accept an empty value in place of the provided non-empty .default() for cases where an empty value is valid and/or expected. Without this option, the default value will be used when an empty value is detected for a given type. A common use for this is to allow '' as a value for a .string() definition. In other words, allowEmpty() is a no-op without a default().

The empty values for the config types supported by this package are as follows:

| Type | Final Value | | --- | --- | | string | '' | | number | 0 | | boolean | false | | list | [] |

Definition#toJSON()

Returns a JSON representation of the configuration Definition.

Definition#match(re)

This method can only be used with Config.regex(). Otherwise, an error will be thrown.

Returns this to allow chaining.

Definition#min(n)

  • n <Number> The minimum value for the rule

This method can only be used with Config.number(). Otherwise, an error will be thrown.

Returns this to allow chaining.

Definition#max(n)

  • n <Number> The maximum value for the rule

This method can only be used with Config.number(). Otherwise, an error will be thrown.

Returns this to allow chaining.

Definition#values(arr)

  • arr <Array> An array of acceptable values for an enum type.

This method can only be used with Config.enum(). The final value must exist in the values arr, or an error is thrown.

Definition#type(type)

  • type <String> The type of value expected within a list can be one of:
    • number
    • boolean
    • string

Definition#separator(value)

default: /\s+|,/

Custom Errors

'MissingEnvError'

  • <Error>
    • name <String> Static value of MissingEnvError
    • type <String> Describes the definition: string, number, boolean, regex, or enum

This error is thrown if Definition#required was used, but no such environment variable or value was discovered.

'RequiredDefaultMutexError'

  • <Error>
    • name <String> Static value of RequiredDefaultMutexError
    • type <String> Describes the definition: string, number, boolean, regex, or enum

This error is thrown if Definition#required and Definition#default are used together in a definition. A non-empty value must be provided for required variables, thus setting a default value for those is a dead code path. These two options are mutually exclusive.

'RegExpError'

  • <Error>
    • name <String> Static value of RegExpError
    • expected <RegExp> The regular expression that is expected to match the discovered value
    • actual (Any) The value that was discovered in the environment
    • env <String> The name of the evironment variable that is supposed to hold the value (upper cased with underscores, e.g. MY_VARIABLE)

This error is thrown if Config.regex() was used, but the discovered value in the environment did not match the pattern.

'EnumError'

  • <Error>
    • name <String> Static value of EnumError
    • expected <Array> The list of acceptable values for the definition
    • actual (Any) The value that was discovered in the environment
    • env <String> The name of the evironment variable that is supposed to hold the value (upper cased with underscores, e.g. MY_VARIABLE)

This error is thrown if Config.regex() was used, but the discovered value in the environment did not match the pattern.

'ListError'

  • <Error>
    • name <String> Static value of EnumError
    • expected <Array> The list of acceptable values for the definition
    • actual (Any) An invalid value that found withing the list
    • input <String> The the value of the environment variable after it was parsed and sanitized
    • original <String> The original value from the environment variable
    • type <String> The defined value type of the list property
    • env <String> The name of the evironment variable that is supposed to hold the value (upper cased with underscores, e.g. MY_VARIABLE)

This error is thrown if Config.list() was used, but the discovered value in the environment contained an invalid value

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!