node package manager

defined-options

defined-options

Define option properties with optional validation, filter and default value. Read, write, validate and merge option values as simple as possible.

npm Package Version MIT License Travis Build Status

Dependencies Status devDependencies Status Code Climate GPA Code Climate Test Coverage


README IN PROGRESS

API

See also tests and examples.

Options()

See lib/options.js.

Creates a new Options instance. Accepts an object with option definitions as optional argument.

var Options = require('defined-options');
 
var options = new Options({
        text: {
            validate: 'string!empty',
            default: 'foo'
        },
        answer: {
            validate: 'number>0',
            default: 42
        }
    });
 
console.log(options); // { text: [Getter/Setter], answer: [Getter/Setter] } 
console.log(options.getPlainObject()); // { text: 'foo', answer: 42 } 
console.log(options.text); // foo 
console.log(options.answer); // 42 

Options' properties have getters and setters defined via their descriptors. This way validation and filtering is done automagically:

// option 'text' only accepts non-empty strings 
options.text = '';
console.log(options.text); // foo 
options.text = 'bar';
console.log(options.text); // bar 
 
// option 'answer' only accepts numbers > 0 
options.answer = -7;
console.log(options.answer); // 42 
options.answer = 5;
console.log(options.answer); // 5 

.defineOption()

Creates a new option property or replaces an existing one with same name.

Accepts option definition as single argument or option name as first and option definition as second argument.

Returns current Options instance.

options.defineOption({name: 'text', validate: 'string'});
// or 
options.defineOption('text', {validate: 'string'});
Option definition

An option definition object can have the following properties:

  • name
    required
    a non-empty string defining the option name

  • validate
    default: 'any'
    defines how to validate an options value; accepts validate-by-shorthand arguments:

    • a string defining a shorthand string
    • a regular rexpression for a match test
    • a function, receiving a value to test, returning a boolean result
    • an array of shorthand strings, regular expressions and/or functions; validating an option value if any of these tests returns true
  • filter
    default: function(value) {return value;}
    defines a filter function, receiving the validated value, returning the filtered value

  • default
    default: undefined
    defines an option's default value; if set to a function, it will be called to set the default value

Example with all properties:

options.defineProperty({
    name: 'shout',
    default: 'HELLO!',
    validate: 'string!empty',
    filter: function(value) {
        return value.toLowerCase();
    }
});
 
console.log(options.shout); // HELLO! 
options.shout = 'bye!';
options.shout = 1;
console.log(options.shout); // BYE! 

.defineOptions()

Creates new option properties or replaces existing ones with same name using defineOption().

Expects and object with option names as keys and option definitions as values.

Returns current Options instance.

options.defineOptions({
    name: {
        validate: 'string'
    },
    age: {
        validate: 'number>0'
    }
});

.removeOption()

Removes an option. Expects and option name. Returns current Options instance.

options.removeOption('foo');

.hasOption()

Tests is a option is defined. Expects an option name. Returns a boolean result.

options.hasOption('foo');

.getPlainObject()

Returns a plain object with option name as keys and option values as values, without described getters and setters.

console.log(options); // { text: [Getter/Setter], answer: [Getter/Setter] } 
console.log(options.getPlainObject()); // { text: 'foo', answer: 42 } 

.merge()

Alias for mergeOptionValues().

.mergeOptionValues()

Merges an new values into current Options instance and updates an option values if given value is valid.

Expects on or more objects containing option names as keys and option values as values.

Returns current Options instance.

var options = new Options({
        text: {
            validate: 'string!empty',
            default: 'foo'
        },
        answer: {
            validate: 'number>0',
            default: 42
        }
    });
 
console.log(options.getPlainObject()); // { text: 'foo', answer: 42 } 
 
options.merge({
    text: bar,
    answer: -7,
    name: 'Han'
});
 
console.log(options.getPlainObject()); // { text: 'bar', answer: 42 } 

.mergeOptions()

Merges one Options instance into another. Replaces options with same name.

Expects one or more Options instances.

Returns current Options instance.

console.log(options.getPlainObject()); // { text: 'foo', answer: 42 } 
 
options.mergeOptions(new Options({
    name: {
        validate: 'string',
        default: 'Han'
    }
}));
 
console.log(options.getPlainObject()); // { text: 'foo', answer: 42, name: 'Han' } 

.getOptionDefinition()

Returns an option definition as Option instance. Expects an option name.

.getOptionDefinitions()

Returns all option definitions as an object with option names as keys and the respective Option instance as values.

.default()

.setDefaultOptionValue()

.setDefaultOptionValues()

.validate()

.validateOptionValue()

.validateOptionValues()

Option()

License

MIT © 2015 Simon Lepel