12 Factorial

12 Factorial is a simple lib for building dynamic configuration from environment variables and Consul.

What does it do?

// myconfig.js
import cfg from '12factorial'

// Configs are described as plain javascript objects.
const spec = {

  // they can contain any data you like
  constantValue: 'abc-123',
  someOtherValue: myFunction(),

  // 12factorial.service will synchronise a field
  // with a consul service, or with env vars.
  database: cfg.service('my-db'),

  credentials: {
    // 12factorial.value will synchronise a field
    // with consul's KV store, or with an env var.
    username: cfg.value(),
    password: cfg.value()
  },
}

// 12factorial.build is the factory function that turns your
// object into a synchronised config object
cfg.build(spec).then((x) => doSomethingWithConfig(x))

Using values

The value function synchronises an object field with a scalar value. Env vars take precedence over values stored in Consul, and defaults can be provided. Keys and environment variable names are generated by convention. Values can be declared with a default.

{
  // This can be set with the env var `VALUE` or the consul key `consul-prefix/value`
  value: cfg.value(),

  // this can be set with the env var `NESTED_OBJECT_VALUE` or the 
  // consul key `consul-prefix/nested/object/value`
  nested: {
     object: {
        value: cfg.value()
     }
  },

  // defaults to 'cheese' if no env var or consul key is available.
  defaulted: cfg.value({ default: 'cheese' })
}

Namespacing environment variables

Environment variables can be namespaced. In the following example, we use an envPrefix of myapp. This prefix will be added to the variable names.

spec = {
  nested: {
    value: cfg.value()
  }
}

process.env.MYAPP_NESTED_VALUE = 'beep'

cfg.build(spec, {envPrefix: 'myapp'}).then(config => { 
    console.log(config.nested.value) // prints beep
});

Syncing with consul

Values can be synchronised with Consul by passing consul configuration to 12factor.build. If no consul config is provided, we will skip consul synchronisation. Only the 'prefix' key is required, the other values default to development values. Values are kept up to date with a Consul Watch.

const consulConfig = {

  prefix: 'myapp',     // required.

  host: '127.0.0.1',   // defaults
  port: 8500,
  scheme: 'http'
}

const spec = {
    nested: {
        value: cfg.value()
    }
}

cfg.build(spec, { consul: consulConfig }).then( config => {
        console.log(config.nested.value) // prints the value of myapp/nested/value from consul kv.
});

Using Services

The 12factor.service function synchronises an object key with the address and port of a service. As with values, environment variables take precedence over Consul values. Environment variable names are generated by convention, and support namespacing.

const spec = {
   web: cfg.service('my-web-service'),
   db: cfg.service('my-database')
}

process.env.MYAPP_WEB_ADDRESS = '127.0.0.1'
process.env.MYAPP_WEB_PORT = '3002'

const config = await cfg.build(spec, { envPrefix: 'myapp' })

console.log(config.web.getAddress())             // prints 127.0.0.1:3002
console.log(config.web.buildUri('/hello/world')) // prints 127.0.0.1:3002/hello/world

console.log(config.db.getAddress())              // prints the address + port of the 'my-database' 
                                                 // service registered in Consul.

Using Services from Consul

Services are automatically synchronised from Consul. By default, we use 'http://127.0.0.1:8500' as the address of our consul server. Services from Consul are kept up to date with a Consul watch.

If there are multiple addresses registered for a service, 12factorial will select an address at random and return that address consistently until the service is updated in Consul.

Mixing Values into Services

Occasionally, for ease of consumption, you might want to add extra values into a service object. This is typically useful for storing credentials with a service's address. This use case is covered by the extend method of a service.

const spec = {
    database: cfg.service('myapp-db').extend({
        username: cfg.value(),
        password: cfg.value({ sensitive: true })
    })
}   

const config = await cfg.build(spec)

console.log(config.database.getAddress())
console.log(config.database.username)
console.log(config.database.password)

Type Coercion

Values can be automagically coerced from strings. If you set a default, we will coerce to the same type as the default value. You can override the parsing of your values by passing a reader function.

const spec = {
    number: cfg.value({ default: 123 }).
    bool: cfg.value({ default: true }),
    custom: cfg.value({ reader: function (x) { return {msg: x } } })
}   

process.env.NUMBER = "0xFF"
process.env.BOOL = FALSE // or false
process.env.CUSTOM = 'Hello World'

const config = await cfg.build(spec)

console.log(config.number) // 255
console.log(config.bool) // false
console.log(config.custom.msg) // hello world

Current Status

This is alpha-quality. There are some missing features, and little error handling. This is intended to meet my own requirements for a production system, but may not meet yours. Feel free to play around and report bugs.

Roadmap

• [X] Add logging
• [ ] Make sure we handle errors properly
• [ ] Add type coercion for values
• [ ] Allow consul values to query using data center, tags etc.
• [ ] Extend env var opts to support an arbitrary variable name
• [ ] Support Hashicorp Vault for secrets.
• [ ] Consider supporting other back-ends
• [ ] Basic validity checks, eg. required fields.
• [ ] Reactivity, eg. raise an event when the database service updates so we can close connections etc