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