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');

1. Mix it into an existing object

var optionsApi = require('options-api');
var obj = {};
 
optionsApi.mixin(obj);
obj.set('option', 'value');

1. 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.

Back to Top

Static API Parameters

Back to Top

Core API

Core Methods

Core Method Aliases

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

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