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.