Many applications and modules maintain a dictionary of options available to consumers. I've frequently found myself adding this functionality to my code. So, I figured, why not just package it up in an npm module and share it with the world. I'm sure someone out there may find it useful. That when I decided to publish options-api.

options-api allows you to easily set, get and optionally validate key/value pairs with a simply API, so that you can store/retreive your module's or application's configuration. It's a simple in-memory options store you can use standalone, mix into an existing object, or attach to an existing class.

I took inspiration from some awesome open-source projects like KeystoneJS and Grappling Hook so the api is friendly and intuitive.

If I haven't bored you and you're still interested please read on.

• Installation
• Usage
• Static API
• Static API Parameters
• Core API
• Core API Parameters
• Examples
• Unit Testing
• Attributions
• License
• Release Notes

Installation

options-api is available on npm.

npm install --save options-api

Back to Top

Usage

options-api a number of static methods that will easily let in incorporate its functionality into your projects in a variety of circumstances.

1. Create a standalone instance

var optionsApi = require('options-api');
var instance = optionsApi.create();

instance.set('option', 'value');

2. Mix it into an existing object

var optionsApi = require('options-api');
var obj = {};

optionsApi.mixin(obj);
obj.set('option', 'value');

3. Attach it to an existing class

var optionsApi = require('options-api');
var Clazz = function() {
  this.something = 'something else';
};
Clazz.prototype.xxx = function() {};
Clazz.prototype.yyy = function() {};
Clazz.prototype.zzz = function() {};

optionsApi.attach(Clazz);

var instance = new Clazz();
instance.set('option', 'value');

Back to Top

Static API

The static API methods provide you with a means to incorporate options-api into your app or module.

Method	Parameters	Description
.create()	defauts (optional) validators (optional)	Syntax: .create([<defaults>[,<validators>]]) Creates a standalone instance of options-api
.mixin()	instance defauts (optional) validators (optional)	Syntax: .mixin(<instance>[,<defaults>[,<validators>]]) Adds options-api functionality to an existing object
.attach()	class defauts (optional) validators (optional)	Syntax: .attach(<class>[,<defaults>[,<validators>]]) Adds option-api functionality to the prototype of an existing class

Back to Top

Static API Parameters

Parameter	Type	Description
defaults	object	Object hash of key/value pairs with default values for options, where the keys are the option names and values are the defaults.
validators	object	Object has of key/value pairs, where the keys as the option names and the values are the validators. Validators can be either a function (which takes teh value to be validated as an argument and return a boolean indication if the validation was successful) or a regular expression.
instance	object	Object onto which you would like to add options-api functionality
class	constructor object	Class, the prototype of which you would like add options-api functionality

Back to Top

Core API

Core Methods

Method	Parameters	Description
.set()	option value	Syntax: .set(<option>,<value>) Set an options value
.get()	option	Syntax: .get(<option>) Retrieve an options value
.unset()	option	Syntax: .unset(<option>) Remove an existing option
.config()	options	Syntax: .config(<options>) Set multiple options
.enable()	option	Syntax: .enable(<option>) Set an option's value to true
.disable()	option	Syntax: .disable(<option>) Set an options's value to false
.defaults()	defaults	Syntax: .defaults(<defaults>) Sets default values for options
.validators()	validators	Syntax: .validators(<validators>) Specify option validators
.reset()	n/a	Syntax: .reset() Sets all options back to their configured defaults
.list()	n/a	Syntax: .list() Gets an object with all current options

Core Method Aliases

Method	Parameters	Description
.add()	option value	Syntax: .add(<option>,<value>) Alias of .set()
.remove()	option	Syntax: .remove(<option>) Alias of .unset()

Instance methods are chainable

With the obvious exception of the .get() (which returns the requested option value) all instance methods are chainable.

For example, you can:

var instance = optionsApi.create();
instance
  .defaults({ option1: 'default value' })
  .validators({ option1: /^default/ })
  .enable('option2');

Back to Top

Core API Parameters

Parameter	Type	Description
option	string	Option name
options	object	Object hash of key/value pairs representing multiple options to set
value	any	Value to which to set the option
defaults	object	See defaults above (under Static API Parameters)
validators	object	See validators above (under Static API Parameters)

Examples

Check out the sample code for each of the core API methods.

.set()/.get()

var optionsApi = require('options-api');
var instance = optionsApi.create();

instance.set('option1', 'value1');

console.log('option1:', instance.get('option1'));
console.log('option2:', instance.get('option2'));

Output:

option1: value1
option2: undefined

Back to Core API

.add()

Alias of .set()

.unset()

var optionsApi = require('options-api');
var instance = optionsApi.create();

instance.set('option1', 'value1');
instance.unset('option1');

console.log('option1:', instance.get('option1'));

Output:

option1: undefined

Back to Core API

.remove()

Alias of .unset()

Back to Core API

.config()

var optionsApi = require('options-api');
var instance = optionsApi.create();

instance.config({
  option1: 'value1',
  option2: 'value2'
});

console.log('option1:', instance.get('option1'));
console.log('option2:', instance.get('option2'));

Output:

option1: value1
opiion2: value2

Back to Core API

.enable()/.disable()

var optionsApi = require('options-api');
var instance = optionsApi.create();

instance.enable('option1');
instance.disable('option2');

console.log('option1:', instance.get('option1'));
console.log('option2:', instance.get('option2'));

Output:

option1: true
option2: false

Back to Core API

.defaults()

var optionsApi = require('options-api');
var instance = optionsApi.create();

instance.defaults({
  option1: 'value1',
  option2: 'value2'
});

console.log('option1:', instance.get('option1'));
console.log('option2:', instance.get('option2'));

Output:

option1: value1
opiion2: value2

Back to Core API

.validators()

var optionsApi = require('options-api');
var instance = optionsApi.create();

instance.validators({
  option1: function(value) {
    return typeof value === 'number' && value > 0;
  },
  option2: /\.*js$/
});

instance.set('option1', 1);
instance.set('option2', 'file.js');

console.log('option1:', instance.get('option1'));
console.log('option2:', instance.get('option2'));

instance.set('option1', 0);

Output:

option1: 1
opiion2: file.js

InvalidOption: "0" is not a valid value for the "option1" option
    at Object.set ...

Back to Core API

.reset()

var optionsApi = require('options-api');
var instance = optionsApi.create();

instance.defaults({
  option1: 'default value1',
  option2: 'default value2'
});

instance.set('option1', 'another value1');
instance.set('option2', 'another value2');

instance.reset();

console.log('option1:', instance.get('option1'));
console.log('option2:', instance.get('option2'));

Output:

option1: value1
opiion2: value2

Back to Core API

.list()

var optionsApi = require('options-api');
var instance = optionsApi.create();

instance.defaults({
  option1: 'default value1',
  option2: 'default value2'
});

console.log(instance.list());

Output:

{ option1: 'default value1', option2: 'default value2' }

Back to Core API

Unit Testing

To test options-api simply clone the repo and run npm test.

git clone https://github.com/AgentiaSystems/options-api.git
cd options-api
npm test

You can also run lint test and check the test coverage.

npm run lint
npm run cover  // <-- report will be store in the `.coverage` folder

Back to Top

Attributions

This work was partly inspired by KeystoneJS (thank you @JedWatson et al) and Grappling Hook (thank you @crynders).

Back to Top

License

options-api is free and open source under the MIT License.

Copyright (c) 2015 Johnny Estilles, http://www.agentia.asia

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Back to Top