nconf-lite/README.md

102 lines
3.1 KiB
Markdown
Raw Normal View History

2011-04-02 08:59:18 +00:00
# nconf
A hybrid local / remote configuration storage library for node.js.
## Installation
### Installing npm (node package manager)
```
2011-04-02 08:59:18 +00:00
curl http://npmjs.org/install.sh | sh
```
2011-04-02 08:59:18 +00:00
### Installing nconf
```
2011-04-02 08:59:18 +00:00
[sudo] npm install nconf
```
2011-04-02 08:59:18 +00:00
## Usage
Using nconf is easy; it is designed to be a simple key-value store with support for both local and remote storage. Keys are namespaced and delimited by `:`. Lets dive right into sample usage:
``` js
2011-04-02 08:59:18 +00:00
var fs = require('fs'),
nconf = require('nconf');
//
2011-05-20 08:21:46 +00:00
// Setup nconf to use the 'file' store and set a couple of values;
2011-04-02 08:59:18 +00:00
//
nconf.use('file', { file: 'path/to/your/config.json' });
nconf.set('database:host', '127.0.0.1');
nconf.set('database:port', 5984);
//
// Get the entire database object from nconf
//
var database = nconf.get('database');
//
// Save the configuration object to disk
//
nconf.save(function (err) {
fs.readFile('path/to/your/config.json', function (err, data) {
console.dir(JSON.parse(data.toString()))
});
});
```
2011-04-02 08:59:18 +00:00
## Storage Engines
### Memory
2011-04-02 09:13:34 +00:00
A simple in-memory storage engine that stores a nested JSON representation of the configuration. To use this engine, just call `.use()` with the appropriate arguments. All calls to `.get()`, `.set()`, `.clear()`, `.reset()` methods are synchronous since we are only dealing with an in-memory object.
``` js
2011-04-02 09:13:34 +00:00
nconf.use('memory');
```
2011-04-02 08:59:18 +00:00
### File
2011-07-08 21:01:22 +00:00
Based on the Memory store, but provides additional methods `.save()` and `.load()` which allow you to read your configuration to and from file. As with the Memory store, all method calls are synchronous with the exception of `.save()` and `.load()` which take callback functions. It is important to note that setting keys in the File engine will not be persisted to disk until a call to `.save()` is made.
2011-04-02 09:13:34 +00:00
``` js
2011-04-02 09:13:34 +00:00
nconf.use('file', { file: 'path/to/your/config.json' });
```
2011-04-02 09:13:34 +00:00
The file store is also extensible for multiple file formats, defaulting to `JSON`. To use a custom format, simply pass a format object to the `.use()` method. This object must have `.parse()` and `.stringify()` methods just like the native `JSON` object.
2011-04-02 08:59:18 +00:00
### Redis
2011-07-08 21:01:22 +00:00
There is a separate Redis-based store available through [nconf-redis][0]. To install and use this store simply:
``` bash
$ [sudo] npm install nconf
$ [sudo] npm install nconf-redis
```
Once installing both `nconf` and `nconf-redis`, you must require both modules to use the Redis store:
2011-04-02 09:13:34 +00:00
``` js
2011-07-08 21:01:22 +00:00
var nconf = require('nconf');
//
// Requiring `nconf-redis` will extend the `nconf`
// module.
//
require('nconf-redis');
2011-04-02 09:13:34 +00:00
nconf.use('redis', { host: 'localhost', port: 6379, ttl: 60 * 60 * 1000 });
```
2011-04-02 09:13:34 +00:00
2011-04-02 08:59:18 +00:00
## More Documentation
2011-04-02 09:13:34 +00:00
There is more documentation available through docco. I haven't gotten around to making a gh-pages branch so in the meantime if you clone the repository you can view the docs:
```
2011-04-02 09:13:34 +00:00
open docs/nconf.html
```
2011-04-02 08:59:18 +00:00
## Run Tests
Tests are written in vows and give complete coverage of all APIs and storage engines.
```
2011-04-02 08:59:18 +00:00
vows test/*-test.js --spec
```
2011-04-02 08:59:18 +00:00
2011-07-08 21:01:22 +00:00
#### Author: [Charlie Robbins](http://nodejitsu.com)
[0]: http://github.com/indexzero/nconf