envfull

Parsing and working with command line arguments, env and .env file, config file.

Usage no npm install needed!

<script type="module">
  import envfull from 'https://cdn.skypack.dev/envfull';
</script>

README

ENVFULL"> ENVFULL

Pipeline Npm Downloads License Node Collaborators

What is it?

This module is simple, no dependencies environment and cli parser used for parsing arguments from commands, properties from config and variables from environment. Envfull loads data from this sources and merge it together into one result.

  1. Load variables from .env file and enrich this data from process.env. This will create object with environmental variables loaded from file and from environment.
  2. Load data from config (if you provided path to config). This will create object with variables from your config. Actual supported configs are: .json
  3. Load data from command line arguments and create object with variables and rest of items on command line.
  4. Merge these data with this order (env, config, command line) into one object, enrich this object by defined defaults values and return it.

Install

With npm do:

npm install envfull
Types and types resolving

Envfull uses behaviour of javascript and try to conver values into typed values. So when there is 9999 in variables, it will be typed as Number. If here is true or false it will be typed as boolean. Same this has happend with command line arguments with same name. If you use --only 1 --only 2 Envfull make results as array [1, 2]. But if you use only --only 1 variable will be presented as number 1. Because of it, you can force force typed on same keys. More info you can read below in section Options - forced types

Examples

You can try ENVFULL playground on repl.it!

Test envfull and check if you can use it in your app. Live example with predefined command line arguments can help you too understand how envfull is working.

replit

More examples can be found here! And if you want to add new one, just make and merge request and add your example to help others.

Typescript usage example
import {envfull} from "envfull";
//without any settings
const parsed = envfull(process)();
import {envfull} from "envfull";
//calling with json config
const parsed = envfull(process)("/path/to/config/config.json");
import {envfull} from "envfull";
//with basic settings
type Settings = {
    db: {
        host: string;
        port: number;
    };
    production: boolean;
    user: {
        login: string | null;
    }
}
const parsed = envfull<Settings>(process, {
    //defaults vales
    defaults: {
        db: {
            host: "http://localhost",
            port: 9999
        },
        production: false
    },
    //alias for fields
    aliases: {
        db: {
            host: ["host"],
            port: ["port"]
        },
        production: ["p"],
        "user.login": ["username"]
    }
})();
console.log(parsed.$); //Object tree with variables, merged from environmental variables also
console.log(parsed._); //Rest of items on command-line
console.log(parsed["--"]); //No parsed data after -- in command line
Javascript usage example
const envfull = require("envfull").envfull;
const parsed = envfull(process)();
const envfull = require("envfull").envfull;
//calling with json config
const parsed = envfull(process)("/path/to/config/config.json");
const envfull = require("envfull").envfull;
//with basic settings
const parsed = envfull(process, {
    //defaults vales
    defaults: {
        db: {
            host: "http://localhost",
            port: 9999
        },
        production: false
    },
    //alias for fields
    aliases: {
        db: {
            host: ["host"],
            port: ["port"]
        },
        production: ["p"],
        "user.login": ["username"]
    }
})();
console.log(parsed.$); //Object tree with variables, merged from environmental variables also
console.log(parsed._); //Rest of items on command-line
console.log(parsed["--"]); //No parsed data after -- in command line

Options

import {envfull} from "envfull";
const parsed = envfull(process, opts = {})();

opts.env: Array<string | RegExp>

List of all variables or regular expresion for variables name that will be import from ENV store on NodeJS. For example if you will be used only "APP.USERNAME" and "APP.TOKEN" in you app, you can use

const opts = {
    env: ["APP.USERNAME", "APP.TOKEN"]
}

or with using RegExp

const opts = {
    env: [/APP\.[A-Za-z0-9]/]
}

Envfull will load only these variables from ENV store and rest will be ignored. By default all ENV variables are imported.

opts.aliases: Partial<T> | Object

This are aliases for some variables. Aliases are defined by partial object structure or you can define it like object mapping where levels are split by ..

Sou you can defined aliases by

const opts = {
    aliases: {
        db: {
            host: ["APP.DB.HOST"],
            port: ["APP.DB.PORT"]
        }       
    }
}

or you can use string maps version of aliases

const opts = {
    aliases: {
        "db.host": ["APP.DB.HOST"],
        "db.port": ["APP.DB.PORT"]
    }
}

Both are valid settings, but if you use typescript, first version is recommended, because typescript will be showing properties of object.

opts.defaults: Partial | Object

Default values for variables that are missing. If you not specified variables in command line, config or in ENVIRONMENTS variables, envfull will use this default and fill results objects. Defaults are defined by partial object structure or you can define it like object mapping where levels are split by ..

Sou you can defined defaults by

const opts = {
   defaults: {
        db: {
            host: "http://localhost",
            port: 3333
        }       
   }
}

or you can use string maps version of defaults

const opts = {
   defaults: {
        "db.host": "http://localhost",
        "db.port": 3333
   }
}

Options - forced types

You can force type on specified variables. Keys defined on settings will be always converted into specified typed value even if is not in right type. For example db.port will be always number, so if you send value "test", this variable will have value NaN because "test" is can not be converted to number. Same is with other types.

const opts = {
   strings: ["db.host"],
   numbers: ["db.port"],
   booleans: ["db.test"],
   arrays: ["only"]
}

Donate me 😉

QR Paypal

License

MIT - MIT License