settns

environment-based settings for javascript

Installation

npm

For npm-based node.js projects, settns can be best installed by adding it to your project's package.json dependencies. First find the current version by running:

npm info settns version

then create or edit your existing package.json file (in your project's root) adding settns to its dependencies. Replace the "0.0.1" (leave the quotes) with the appropriate version.

{
    "name": "coolapp",
    "description": "my cool app",
    "version": "0.0.1",
    "private": true,
    "dependencies": {
        "settns": "0.0.1"
    }
}

then running,

npm install

git

The git repository may be directly cloned into your project:

git clone https://github.com/akb/settns.git

direct download

https://raw.github.com/akb/settns/master/lib/settns.js

Usage

in a web browser

<script src="js/settns.js"></script>

node.js

var settns = require("settns");

Guide

settings

A setting is an addressable value accessible through the settns function.

settns("ship.registry-number", "NCC-1701");

console.log(settns("ship.registry-number"));
> "NCC-1701"

defaults

You may set defaults for any setting which settns automatically falls back to if no setting is found for the current environment.

settns.default("ship.name", "Enterprise");
settns.default("ship.registry-number", "NCC-1701");

settns("ship.registry-number", "NCC-1701-A");

console.log(settns("ship.name"));
> "Enterprise"

console.log(settns("ship.registry-number"));
> "NCC-1701-A"

environments

Settings are stored in an environment. Settns has a current envrionment which values are read from.

settns.environment("search for spock");

console.log(settns.environment());
> "search for spock"

settns("ship.registry-number", "NCC-1701");

settns.environment("voyage home");
settns("ship.registry-number", "NCC-1701-A");

settns.environment("search for spock");

console.log(settns("ship.registry-number"));
> "NCC-1701"

settns.environment("voyage home");

console.log(settns("ship.registry-number"));
> "NCC-1701-A"

You may change a setting for a particular environment without changing the current environment:

settns("ship.registry-number", "NCC-1701-D", "next generation");

console.log(settns.environment());
> "voyage home"

console.log(settns("ship.registry-number"));
> "NCC-1701-A"

settns.environment("next generation");

console.log(setns("ship.registry-number"));
> "NCC-1701-D"

Example

An example of how a contrived web server might use settns to provide seperation of different environments.

var settns = require("settns");

settns.default({
  "server": {
    "port": 3000,
    "hostname": "example"
  }
});

settns.environment("development", {
  "server.alias": ["localhost", "127.0.0.1"]
});

settns.environment("production", {
  "server": {
    "port": 80,
    "hostname": "example.com",
    "alias": ["www.example.com"]
  }
});

API Reference

settns(address[, value][, environment]);

Sets or retrieves a setting.

settns.environment([name][, settings]);

Sets or retrieves the current environment, or sets multiple settings for specified environment.

settns.default(settings|address[, value]);

Sets or retrieves a default value for a setting, or sets multple defaults at once.

settns.reset();

Deletes all settings, causing all to revert to defaults.

settns.on(event, callback);

Binds a callback to an event.

events

"change"

Emitted when a setting's changes to a different value.

"update"

Emitted when a setting's value is updated, whether it is a new value or is unchanged.

"reset"

Emitted when settings are reset to their defaults.

Running Tests

From the project root directory, run the unit tests with:

sbin/jasmine-node spec

License

View the LICENSE file.