options-api

    1.1.0 • Public • Published

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

    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

    Install

    npm i options-api

    DownloadsWeekly Downloads

    271

    Version

    1.1.0

    License

    MIT

    Last publish

    Collaborators

    • johnnyestilles