Merge pull request #4 from uber/set-remote

Implement `setRemote`, `multiSet()` and `freeze()`

Author: Raynos

README.md

@@ -53,16 +53,22 @@ You can also call the process with
 ### `var config = fetchConfig(dirname, opts)`
 
 ```ocaml
-playdoh-server/config := (dirname: String, opts?: {
+type Keypath : String | Array<String>
+
+zero-config := (dirname: String, opts?: {
     argv?: Array<String>,
     dc?: String,
     blackList?: Array<String>,
     env?: Object<String, String>,
     seed?: Object<String, Any>
 }) => {
-    get: (keypath?: String) => Any,
-    set: (keypath: String, value: Any) => void,
-    __state: Object<String, Any>
+    get: (keypath?: Keypath) => Any,
+    set: ((keypath: Keypath, value: Any) => void) &
+        (value: Any) => void,
+    freeze: () => void,
+    getRemote: (keypath?: Keypath) => Any,
+    setRemote: ((keypath: Keypath, value: Any) => void) &
+        (value: Any) => void
 }
 ```
 
@@ -214,6 +220,46 @@ You can call `config.set("port", 9001)` to set the port value.
   You can call `config.set("playdoh-logger.kafka.port", 9001)` to
   set then nested kafka port config option.
 
+Note you can also call `config.set(entireObject)` to merge an
+  entire object into the `config` instance. This will use 
+  deep extend to set all the key / value pairs in `entireObject`
+  onto the config instance.
+
+#### `config.freeze()`
+
+Since the `config` object is supposed to represent a set of
+  static, immutable configuration that's loaded at process
+  startup time it would be useful to enforce this.
+
+Once you are ready to stop mutating `config` you can call
+  `.freeze()`. Any future calls to `.set()` will throw a 
+  config frozen exception.
+
+Note that you can always call `config.setRemote()` as that is
+  not effected by `.freeze()`
+
+#### `var value = config.getRemote(keypath)`
+
+The same as `config.get()` but gets from a different in memory
+  object then `config.get()`.
+
+It's recommended that you use `config.get()` and `config.set()`
+  for any local configuration that is static and effectively
+  immutable after process startup.
+
+You can use `config.getRemote()` and `config.setRemote()` for
+  any dynamic configuration that is effectively controlled
+  remotely outside your program.
+
+#### `config.setRemote(keypath, value)`
+
+The same as `config.set()` but sets to a different in memory
+  objec then `config.set()`.
+
+You can use `config.getRemote()` and `config.setRemote()` for
+  any dynamic configuration that is effectively controlled
+  remotely outside your program.
+
 ## Installation
 
 `npm install zero-config`

config-wrapper.js

@@ -0,0 +1,79 @@
+var getPath = require('dotty').get;
+var putPath = require('dotty').put;
+var deepExtend = require('deep-extend');
+
+var errors = require('./errors.js');
+
+module.exports = ConfigWrapper;
+
+function ConfigWrapper(configObject) {
+    var frozen = false;
+
+    return {
+        get: getKey,
+        set: setKey,
+        freeze: freeze
+    };
+
+    function getKey(keyPath) {
+        if (!keyPath) {
+            return configObject;
+        }
+
+        return getPath(configObject, keyPath);
+    }
+
+    function setKey(keyPath, value) {
+        if (frozen) {
+            throw errors.SetFrozenObject({
+                keyPath: keyPath,
+                valueStr: JSON.stringify(value),
+                value: value
+            });
+        }
+
+        if (arguments.length === 1) {
+            return multiSet(keyPath);
+        }
+
+        if (!isValidKeyPath(keyPath)) {
+            throw errors.InvalidKeyPath({
+                keyPath: keyPath
+            });
+        }
+
+        var v = getKey(keyPath);
+
+        if (typeof v === 'object' && v !== null) {
+            v = deepExtend({}, v, value);
+        } else {
+            v = value;
+        }
+
+        return putPath(configObject, keyPath, v);
+    }
+
+    function freeze() {
+        frozen = true;
+    }
+
+    function multiSet(obj) {
+        if (obj === null || typeof obj !== 'object') {
+            throw errors.InvalidMultiSetArgument({
+                objStr: JSON.stringify(obj),
+                obj: obj
+            });
+        }
+
+        Object.keys(obj).forEach(setEachKey);
+
+        function setEachKey(key) {
+            setKey([key], obj[key]);
+        }
+    }
+}
+
+function isValidKeyPath(keyPath) {
+    return typeof keyPath === 'string' ||
+        Array.isArray(keyPath);
+}

errors.js

@@ -0,0 +1,74 @@
+var TypedError = require('error/typed');
+
+var InvalidDirname = TypedError({
+    type: 'missing.dirname.argument',
+    message: 'invalid __dirname argument.\n' +
+        'Must call fetchConfig(__dirname).\n' +
+        '__dirname should be a string and is non-optional.\n' +
+        'instead I got {strDirname}.\n' +
+        'SUGGESTED FIX: update the `fetchConfig()` callsite.\n'
+});
+
+var MissingDatacenter = TypedError({
+    type: 'missing.datacenter.file',
+    warning: true,
+    message: 'no such file or directory \'{path}\'.\n' +
+        'expected to find datacenter configuration at {path}.\n'
+});
+
+var DatacenterRequired = TypedError({
+    type: 'datacenter.option.required',
+    message: 'expected `opts.dc` to be passed to fetchConfig.\n' +
+        'must call `fetchConfig(__dirname, { dc: "..." }).\n' +
+        'instead I got opts: {strOpts}.\n' +
+        '`opts.dc` is not optional when NODE_ENV is "production".\n' +
+        'SUGGESTED FIX: update the `fetchConfig()` callsite.\n'
+});
+
+var DatacenterFileRequired = TypedError({
+    type: 'datacenter.file.required',
+    message: 'no such file or directory \'{path}\'.\n' + 
+        'expected to find datacenter configuration at {path}.\n' +
+        'when NODE_ENV is "production" the datacenter file must exist.\n' +
+        'SUGGESTED FIX: configure your system so it has a datacenter file.\n'
+});
+
+var InvalidKeyPath = TypedError({
+    type: 'invalid.keypath',
+    message: 'specified an invalid keypath to `config.set()`.\n' +
+        'expected a string but instead got {keyPath}.\n' +
+        'SUGGESTED FIX: update the `config.set()` callsite.\n'
+});
+
+var InvalidMultiSetArgument = TypedError({
+    type: 'invalid.multi.set',
+    message: 'Invalid `config.set(obj)` argument.\n' +
+        'expected an object but instead got {objStr}.\n' +
+        'SUGGESTED FIX: update the `config.set()` callsite to ' +
+            'be a valid object.\n',
+    objStr: null,
+    obj: null
+});
+
+var SetFrozenObject = TypedError({
+    type: 'set.frozen.object',
+    message: 'Cannot `config.set(key, value)`. Config is ' +
+        'frozen.\n' +
+        'expected `config.set()` not to be called. Instead ' +
+        'it was called with {keyPath} and {valueStr}.\n' +
+        'SUGGESTED FIX: Do not call `config.set()` it was ' +
+        'frozen by someone else.\n',
+    keyPath: null,
+    valueStr: null,
+    value: null
+});
+
+module.exports = {
+    InvalidDirname: InvalidDirname,
+    MissingDatacenter: MissingDatacenter,
+    DatacenterRequired: DatacenterRequired,
+    DatacenterFileRequired: DatacenterFileRequired,
+    InvalidKeyPath: InvalidKeyPath,
+    InvalidMultiSetArgument: InvalidMultiSetArgument,
+    SetFrozenObject: SetFrozenObject
+};

get-config-state.js

@@ -0,0 +1,69 @@
+var flatten = require('flatten-prototypes');
+var configChain = require('config-chain');
+var parseArgs = require('minimist');
+var join = require('path').join;
+var putPath = require('dotty').put;
+
+module.exports = getConfigState;
+
+function getConfigState(dirname, opts) {
+    var cliArgs = parseArgs(opts.argv || process.argv.slice(2));
+    var env = opts.env || process.env;
+    var NODE_ENV = env.NODE_ENV;
+    var dc = opts.datacenterValue;
+    var blackList = opts.blackList || ['_'];
+
+    // hardcoded to read from `./config` by convention
+    var configFolder = join(dirname, 'config');
+
+    // blackList allows you to ensure certain keys from argv
+    // do not get set on the config object
+    blackList.forEach(function (key) {
+        if (cliArgs[key]) {
+            delete cliArgs[key];
+        }
+    });
+
+    /* use config-chain module as it contains a set of 
+        "transports" for loading configuration from disk
+    */
+    var configTree = configChain(
+        // the seed option overwrites everything
+        opts.seed || null,
+        // include all CLI arguments
+        makeDeep(cliArgs),
+        // load file from --config someFilePath
+        cliArgs.config || null,
+        // get datacenter from opts.dc file
+        dc ? dc : null,
+        // load ./config/NODE_ENV.DATACENTER.json
+        dc && NODE_ENV ?
+            join(configFolder, NODE_ENV + '.' + dc.datacenter + '.json') :
+            null,
+        // load ./config/NODE_ENV.json
+        NODE_ENV ? join(configFolder, NODE_ENV + '.json') : null,
+        // load ./config/common.json
+        join(configFolder, 'common.json')
+    );
+
+    // there is a "bug" in config-chain where it doesn't 
+    // support deep extension. So we flatten deeply
+    // https://github.com/dominictarr/config-chain/issues/14
+    var configState = flatten(configTree.store);
+
+    return configState;
+}
+
+// given a shallow object where keys are key paths like:
+// { 'foo.bar': 'baz', 'foo.baz': 'foo' }
+// it returns a deep object with the key paths expanded like:
+// { 'foo': { 'bar': 'baz', 'baz': 'foo' } }
+function makeDeep(obj) {
+    var deepObj = {};
+
+    Object.keys(obj).forEach(function (key) {
+        putPath(deepObj, key, obj[key]);
+    });
+
+    return deepObj;
+}