configorama

Variable support for configuration files

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
configorama
23120.4.9a month ago6 years agoMinified + gzip package size for configorama in KB

Readme

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

Click to expand
Environment variables CLI option flags Self references File references Sync/Async file references Git references Filters (experimental) Functions (experimental) More Examples

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.

  1. Add your own variable syntax and resolver.
```js
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:

```yml
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.

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

  1. Filters! You can filter values before they are resolved.
```yml
key: ${opt:stage | toUpperCase}
```
  1. Cleaner self references
```yml
keyOne:
  subKey: hi

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

# Now
key: ${keyOne.subKey}
```
  1. Numbers as defaults are supported
```yml
key: ${env:whatever, 2}
```
  1. 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.
  1. 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: