Configorama

Dynamic configuration values with variable support.

Works with yml, json, toml config formats and anything that parsed down to a plain ol' javascript object

About

Configorama extends your configuration with a powerful variable system. It resolves configuration variables from:

• CLI options
• ENV variables
• File references
• Other Key/values in config
• Async/sync JS functions
• Any source you'd like...

See tests for more examples.

Table of Contents

• About
• Usage
• Variable Sources
  • Environment variables
  • CLI option flags
  • Self references
  • File references
  • Sync/Async file references
  • Git references
  • Filters (experimental)
  • Functions (experimental)
  • More Examples
• Custom Variable Sources
• FAQ
• Whats new
• Inspiration

Usage

Async API:

const path = require('path')
const configorama = require('configorama')
const cliFlags = require('minimist')(process.argv.slice(2))

// Path to yaml/json/toml config
const myConfigFilePath = path.join(__dirname, 'config.yml')

const config = await configorama(myConfigFilePath, {
  options: args
})

Sync API:

const path = require('path')
const configorama = require('configorama')
const cliFlags = require('minimist')(process.argv.slice(2))

// Path to yaml/json/toml config
const myConfigFilePath = path.join(__dirname, 'config.yml')

const config = configorama.sync(myConfigFilePath, {
  options: cliFlags
})

Variable Sources

Environment variables

apiKey: ${env:SECRET_KEY}

CLI option flags

# CLI option. Example `cmd --stage dev` makes `bar: dev`
bar: ${opt:stage}

# Composed example makes `foo: dev-hello`
foo: ${opt:stage}-hello

Self references

foo: bar

# Self file reference. Resolves to `bar`
one: ${self:foo}

# Shorthand self reference. Resolves to `bar`
two: ${foo}

File references

# import full yml/json/toml file via relative path
yamlFileRef: ${file(./subFile.yml)}

# import sub values from files. This imports other-config.yml `topLevel:` value
yamlFileValue: ${file(./other-config.yml):topLevel}

# import sub values from files. This imports other-config.json `nested.value` value
yamlFileValueSubKey: ${file(./other-config.json):nested.value}

# fallback to default value if file not found
fallbackValueExample: ${file(./not-found.yml), 'fall back value'}

Sync/Async file references

asyncJSValue: ${file(./async-value.js)}
# resolves to 'asyncval'

${file(./asyncValue.js)} will call into async-value and run/resolve the async function with values. These values can be strings, objects, arrays, whatever.

/* async-value.js */
module.exports = (config) => {
  return fetchSecretsFromRemoteStore()
}

function fetchSecretsFromRemoteStore() {
  return delay(1000).then(() => {
    return Promise.resolve('asyncval')
  })
}

function delay(t, v) {
  return new Promise((resolve) => setTimeout(resolve.bind(null, v), t))
}

Git references

Resolve values from cwd git data.

repository: ${git:repository}

describe: ${git:describe}

branch: ${git:branch}

commit: ${git:commit}

sha1: ${git:sha1}

message: ${git:message}

remote: ${git:remote}

remoteDefined: ${git:remote('origin')}

remoteDefinedNoQuotes: ${git:remote(origin)}

repoUrl: ${git:repoUrl}

Filters (experimental)

Filters will transform the resolved variables

toUpperCaseString: ${'value' | toUpperCase }

toKebabCaseString: ${'valueHere' | toKebabCase }

key: lol_hi

keyTwo: lol_hi

toKebabCase: ${key | toKebabCase }

toCamelCase: ${keyTwo | toCamelCase }

Functions (experimental)

Functions will convert resolved config values with various methods.

object:
  one: once
  two: twice

objectTwo:
  three: third
  four: fourth

mergeObjects: ${merge(${object}, ${objectTwo})}

More Examples

See the tests folder for a bunch of examples!

Custom Variable Sources

Configorama allows you to bring your own variable sources.

There are 2 ways to resolve variables from custom sources.

1. Use the baked in javascript method for sync or aysnc resolution.

2. Add your own variable syntax and resolver.

   const config = configorama('path/to/configFile', {
     variableSources: [{
       // Match variables ${consul:xyz}
       match: RegExp(/^consul:/g),
       // Custom variable source. Must return a promise
       resolver: (varToProcess, opts, currentObject) => {
         // Make remote call to consul
         return Promise.resolve(varToProcess)
       }
     }]
   })
   console.log(config)

   This would match the following config:

   key: ${consul:xyz}

FAQ

Q: Why should I use this?

Never rendering a stale configuration file again!

Q: Does this work with serverless.yml

Yes it does. Using serverless.js as your main entry point!

/* serverless.js */
const path = require('path')
const configorama = require('configorama')
const args = require('minimist')(process.argv.slice(2))

// Path to serverless config to be parsed
const yamlFile = path.join(__dirname, 'serverless.config.yml')

module.exports = configorama.sync(yamlFile, { options: args })

Whats new

How is this different than the serverless variable system?

1. You can use it with any other tool you'd like. Just include configorama and go nuts.

2. It's pluggable. Add whatever variable syntax/sources you wish.

3. Filters! You can filter values before they are resolved.

   key: ${opt:stage | toUpperCase}

4. Cleaner self references

   keyOne:
     subKey: hi
   
   # Before
   key: ${self:keyOne.subKey}
   
   # Now
   key: ${keyOne.subKey}

5. Numbers as defaults are supported

   key: ${env:whatever, 2}

6. TOML, YML, JSON, etc support

   Configorama will work on any configuration format that can be converted into a JS object.

   Parse any config format and pass it into configorama.

7. Configorama has a number of built-in functions.

   Build in functions can be used within expressions as another way to transform and combine values. These are similar to the operators but all follow a common syntax:

   <FUNCTION NAME>(<ARGUMENT 1>, <ARGUMENT 2>)

   example:

   ${merge('one', 'two')} => 'onetwo'

Alt libs

• https://github.com/01alchemist/sls-yaml

Inspiration

This is forked out of the serverless framework variable system.

Mad props to:

erikerikson, eahefnawy, HyperBrain, ac360, gcphost, pmuens, horike37, lorengordon, AndrewFarley, tobyhede, johncmckim, mangas, e-e-e, BasileTrujillo, miltador, sammarks, RafalWilinski, indieisaconcept, svdgraaf, infiniteluke, j0k3r, craigw, bsdkurt, aoskotsky-amplify, and all the other folks who contributed to the variable system.

Additionally these tools were very helpful:

• yaml-boost
• serverless-merge-config
• terraform variables