read-conf

Speed, functionality, simplicity - choose two.

This fundamental tradeoff in programming is as true as always. We are just better at hiding complexity - regular severe security flaws are a reminder of what we already hid away.

The only way we can improve this tradeoff is clever program design.

Over the last few years of programming I produced two very helpful guidelines

• separate by functionality
• aim for declarative programming

Separation by functionality

Separation by functionality greatly improves extendability and understandability - thus maintainability.

You probably experienced the need for a major refactoring or even a complete rewrite at least once. And you will remember the large impact this had on your project - This happens when functionality isn't separated properly.

See hook-up for a deeper description and a useful design pattern.

Aim for declarative programming

Make your programs work with configuration files - the most common type of declarative programming. They can be easily read, merged, diffed and shared.

Common settings of different projects can be easily extracted and maintained in one place.

This package is an allround tool for reading configuration files.

Features

• reading ES7, coffeescript, typescript configuration files
• watch functionality
• schema validation
• doc generation from schema
• loads plugins

Install

npm install --save read-conf

Usage

readConf = require("read-conf")
// readConf(options:Object):Promise
{config} = await readConf({name:"filename"})

// short form is allowed
packageJson = await readConf("package")

Options

Name	type	default	description
name	String	-	filename of the config
extensions	Array	["js","json","coffee","ts"]	extensions to look out for
folders	Array or String	process.cwd()	folder(s) to search in, can be relative to cwd or absolute
filename	String	-	absolute path to the config
default	Object	-	the config will be merged into this
assign	Object	-	this will be merged into the config
concatArrays	Boolean	false	concat arrays when merging
required	Boolean	true	will throw when no configuration file is found
schema	String or Object	-	File or Object used to validate configuration file
cb	Function	-	callback which is called with config obj
watch	Boolean	false	watches configuration file and dependencies for changes
cancel	Function	-	Is called on file change
plugins	Boolean or Object	false	activate plugin management
prop	String	"config"	where to save config object
base	Object	{}	Object where config is saved to

Return value

readConf returns a Promise, which resolves with different values depending on availability of a cb function.

base = new Class SomeClass

// without cb
readConf({name:"filename", base: base, prop:"conf"})
.then((value) => {
  value === base // true
  base.conf // content of file: "filename" 
  base.readConfig // Options object from above
})

// with cb
readConf({name:"filename", base: base, prop:"conf", cb: (value) => {
  value === base // true
  base.conf // content of file: "filename" 
  base.readConfig // Options object from above
  base.readConfig.hash // hash of config
  return () => {
    // do cleanUp
    // will be called on close(), SIGINT, SIGTERM and SIGHUP
  }
}}).then((value) => {
  value // Options object from above
  value.bases[0] === base // true
  value.close // to close watcher and call cancel cb if watch == true
  value.watcher // chokidar filewatcher
})

Plugins

// example
// config.js
module.exports = {
  plugins: ["somePlugin"] // plugins will be read in asynchronously 
}
// where you read config.js
conf = await readConf({name:"config",plugins:true})
conf.plugins[0].pluginPath // will have the resolved path of `somePlugin` package
conf.plugins[0].plugin // will have content of `somePlugin` package

Name	type	default	description
plugins.prop	String	"plugins"	Where to look for plugins in configuration
plugins.disableProp	String	"disablePlugins	Where to look for disable plugins in configuration
plugins.prepare	Function	-	Prepare configuration before loading plugins
plugins.paths	Array	[process.cwd()]	Where plugins are searched

Schema

// example
// where you read config.js
conf = await readConf({name:"config",plugins:true,schema:{
  plugins: {
    type: Array,
    default: ["somePlugin"],
    
    // For documentation if default is not suitable
    _default: "Will load somePlugin",
    required: true, // will throw if not present
    desc: "Plugins to load", // For documentation
  },
  plugins$_item: String,
  propWithInvalidType: [Number, Function, RegExp],
  someObject: {
    type: Object

    // will not allow other children properties then specified in schema
    strict: true 
  },
  someObject$inSchema: Boolean
}})
// config.js
module.exports = {
  plguins: [], // will throw "plguins is no expected prop"
  propWithInvalidType: "", // will throw "invalid type"
  someObject: {

    // will throw someObject.notInSchema is no expected prop
    // because someObject is strict
    notInSchema: true 
  }
}

Generate documentation

# terminal
toDoc --help

# usage: toDoc (schema file)

# schema file is optional and defaults to "configSchema.[js|json|coffee|ts]"
# in "src/", "lib/", "/"

License

Copyright (c) 2018 Paul Pflugradt Licensed under the MIT license.