envfull

ENVFULL

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.

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
console.log(parsed.config.used); //Boolean that says if config file is loaded and used
console.log(parsed.config.path); //Path for used config file, if config is not used, there is empty string
console.log(parsed.env.used); //Boolean that says if .env file is loaded and used
console.log(parsed.env.path); //Path for used .env file, path is filled always even if env file not used

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
console.log(parsed.config.used); //Boolean that says if config file is loaded and used
console.log(parsed.config.path); //Path for used config file, if config is not used, there is empty string
console.log(parsed.env.used); //Boolean that says if .env file is loaded and used
console.log(parsed.env.path); //Path for used .env file, path is filled always even if env file not used

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

Changelog

[1.0.5] - 2022-11-22

Results from envfull now contains env and config. These properties contain info about loading from env file or config file.

• DEV: Added eslint and prettier + format code