options-api

Option getter/setter/validator for Node.js modules and apps

Showing:

Popularity

Downloads/wk

147

GitHub Stars

1

Maintenance

Last Commit

6yrs ago

Contributors

0

Package

Dependencies

3

Size (min+gzip)

2.3KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

logo

Build Status Code Climate Test Coverage

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

npm

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.

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

ParameterTypeDescription
defaultsobjectObject hash of key/value pairs with default values for options, where the keys are the option names and values are the defaults.
validatorsobjectObject 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.
instanceobjectObject onto which you would like to add options-api functionality
classconstructor
object
Class, the prototype of which you would like add options-api functionality

Back to Top

Core API

Core Methods

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

Core Method Aliases

MethodParametersDescription
.add()option
value
Syntax: .add(<option>,<value>)
Alias of .set()
.remove()optionSyntax: .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

ParameterTypeDescription
optionstringOption name
optionsobjectObject hash of key/value pairs representing multiple options to set
valueanyValue to which to set the option
defaultsobjectSee defaults above (under Static API Parameters)
validatorsobjectSee 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

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100