org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/config-chain/readme.markdown

   1 #config-chain
   2
   3 USE THIS MODULE TO LOAD ALL YOUR CONFIGURATIONS
   4
   5 ``` js
   6
   7   //npm install config-chain
   8
   9   var cc = require('config-chain')
  10     , opts = require('optimist').argv //ALWAYS USE OPTIMIST FOR COMMAND LINE OPTIONS.
  11     , env = opts.env || process.env.YOUR_APP_ENV || 'dev' //SET YOUR ENV LIKE THIS.
  12
  13   // EACH ARG TO CONFIGURATOR IS LOADED INTO CONFIGURATION CHAIN
  14   // EARLIER ITEMS OVERIDE LATER ITEMS
  15   // PUTS COMMAND LINE OPTS FIRST, AND DEFAULTS LAST!
  16
  17   //strings are interpereted as filenames.
  18   //will be loaded synchronously
  19
  20   var conf =
  21   cc(
  22     //OVERRIDE SETTINGS WITH COMMAND LINE OPTS
  23     opts,
  24
  25     //ENV VARS IF PREFIXED WITH 'myApp_'
  26
  27     cc.env('myApp_'), //myApp_foo = 'like this'
  28
  29     //FILE NAMED BY ENV
  30     path.join(__dirname,  'config.' + env + '.json'),
  31
  32     //IF `env` is PRODUCTION
  33     env === 'prod'
  34       ? path.join(__dirname, 'special.json') //load a special file
  35       : null //NULL IS IGNORED!
  36
  37     //SUBDIR FOR ENV CONFIG
  38     path.join(__dirname,  'config', env, 'config.json'),
  39
  40     //SEARCH PARENT DIRECTORIES FROM CURRENT DIR FOR FILE
  41     cc.find('config.json'),
  42
  43     //PUT DEFAULTS LAST
  44     {
  45       host: 'localhost'
  46       port: 8000
  47     })
  48
  49   var host = conf.get('host')
  50
  51   // or
  52
  53   var host = conf.store.host
  54
  55 ```
  56
  57 FINALLY, EASY FLEXIBLE CONFIGURATIONS!
  58
  59 ##see also: [proto-list](https://github.com/isaacs/proto-list/)
  60
  61 WHATS THAT YOU SAY?
  62
  63 YOU WANT A "CLASS" SO THAT YOU CAN DO CRAYCRAY JQUERY CRAPS?
  64
  65 EXTEND WITH YOUR OWN FUNCTIONALTY!?
  66
  67 ## CONFIGCHAIN LIVES TO SERVE ONLY YOU!
  68
  69 ```javascript
  70 var cc = require('config-chain')
  71
  72 // all the stuff you did before
  73 var config = cc({
  74       some: 'object'
  75     },
  76     cc.find('config.json'),
  77     cc.env('myApp_')
  78   )
  79   // CONFIGS AS A SERVICE, aka "CaaS", aka EVERY DEVOPS DREAM OMG!
  80   .addUrl('http://configurator:1234/my-configs')
  81   // ASYNC FTW!
  82   .addFile('/path/to/file.json')
  83
  84   // OBJECTS ARE OK TOO, they're SYNC but they still ORDER RIGHT
  85   // BECAUSE PROMISES ARE USED BUT NO, NOT *THOSE* PROMISES, JUST
  86   // ACTUAL PROMISES LIKE YOU MAKE TO YOUR MOM, KEPT OUT OF LOVE
  87   .add({ another: 'object' })
  88
  89   // DIE A THOUSAND DEATHS IF THIS EVER HAPPENS!!
  90   .on('error', function (er) {
  91     // IF ONLY THERE WAS SOMETHIGN HARDER THAN THROW
  92     // MY SORROW COULD BE ADEQUATELY EXPRESSED.  /o\
  93     throw er
  94   })
  95
  96   // THROW A PARTY IN YOUR FACE WHEN ITS ALL LOADED!!
  97   .on('load', function (config) {
  98     console.awesome('HOLY SHIT!')
  99   })
 100 ```
 101
 102 # BORING API DOCS
 103
 104 ## cc(...args)
 105
 106 MAKE A CHAIN AND ADD ALL THE ARGS.
 107
 108 If the arg is a STRING, then it shall be a JSON FILENAME.
 109
 110 SYNC I/O!
 111
 112 RETURN THE CHAIN!
 113
 114 ## cc.json(...args)
 115
 116 Join the args INTO A JSON FILENAME!
 117
 118 SYNC I/O!
 119
 120 ## cc.find(relativePath)
 121
 122 SEEK the RELATIVE PATH by climbing the TREE OF DIRECTORIES.
 123
 124 RETURN THE FOUND PATH!
 125
 126 SYNC I/O!
 127
 128 ## cc.parse(content, file, type)
 129
 130 Parse the content string, and guess the type from either the
 131 specified type or the filename.
 132
 133 RETURN THE RESULTING OBJECT!
 134
 135 NO I/O!
 136
 137 ## cc.env(prefix, env=process.env)
 138
 139 Get all the keys on the provided env object (or process.env) which are
 140 prefixed by the specified prefix, and put the values on a new object.
 141
 142 RETURN THE RESULTING OBJECT!
 143
 144 NO I/O!
 145
 146 ## cc.ConfigChain()
 147
 148 The ConfigChain class for CRAY CRAY JQUERY STYLE METHOD CHAINING!
 149
 150 One of these is returned by the main exported function, as well.
 151
 152 It inherits (prototypically) from
 153 [ProtoList](https://github.com/isaacs/proto-list/), and also inherits
 154 (parasitically) from
 155 [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter)
 156
 157 It has all the methods from both, and except where noted, they are
 158 unchanged.
 159
 160 ### LET IT BE KNOWN THAT chain IS AN INSTANCE OF ConfigChain.
 161
 162 ## chain.sources
 163
 164 A list of all the places where it got stuff.  The keys are the names
 165 passed to addFile or addUrl etc, and the value is an object with some
 166 info about the data source.
 167
 168 ## chain.addFile(filename, type, [name=filename])
 169
 170 Filename is the name of the file.  Name is an arbitrary string to be
 171 used later if you desire.  Type is either 'ini' or 'json', and will
 172 try to guess intelligently if omitted.
 173
 174 Loaded files can be saved later.
 175
 176 ## chain.addUrl(url, type, [name=url])
 177
 178 Same as the filename thing, but with a url.
 179
 180 Can't be saved later.
 181
 182 ## chain.addEnv(prefix, env, [name='env'])
 183
 184 Add all the keys from the env object that start with the prefix.
 185
 186 ## chain.addString(data, file, type, [name])
 187
 188 Parse the string and add it to the set.  (Mainly used internally.)
 189
 190 ## chain.add(object, [name])
 191
 192 Add the object to the set.
 193
 194 ## chain.root {Object}
 195
 196 The root from which all the other config objects in the set descend
 197 prototypically.
 198
 199 Put your defaults here.
 200
 201 ## chain.set(key, value, name)
 202
 203 Set the key to the value on the named config object.  If name is
 204 unset, then set it on the first config object in the set.  (That is,
 205 the one with the highest priority, which was added first.)
 206
 207 ## chain.get(key, [name])
 208
 209 Get the key from the named config object explicitly, or from the
 210 resolved configs if not specified.
 211
 212 ## chain.save(name, type)
 213
 214 Write the named config object back to its origin.
 215
 216 Currently only supported for env and file config types.
 217
 218 For files, encode the data according to the type.
 219
 220 ## chain.on('save', function () {})
 221
 222 When one or more files are saved, emits `save` event when they're all
 223 saved.
 224
 225 ## chain.on('load', function (chain) {})
 226
 227 When the config chain has loaded all the specified files and urls and
 228 such, the 'load' event fires.