Neutered Puppy Masquerade

    enhanced-property

    1.0.5 • Public • Published

    enhanced-property Build Status

    enhanced-property let you define an enhanced property which does more than just storing a value. The enhanced property can have:

    • value converter - converts the value before storing it into the property
    • value validator - validate the value before storing it into the property
    • property change callback - callbacks whenever the value of the property changed
    • property type - let you specify the value type the property accepts

    Installation

    npm install --save enhanced-property
    

    Usage

    var enhancedProperty = require('enhanced-property');
        
    var obj = {},
        descriptor = {
        
        value: 5,//default value
        converter: function (value) {return value * 2; },
        validator: function (value) {return value <= 50; },
        propertyChanged: function (obj, prop, oldValue, newValue)
                 {
                    console.log('Property: ' + prop);
                    console.log('Old Value: ' + oldValue);
                    console.log('New Value: ' + newValue);
                 },
        type: 'number',
        writable: true,
        configurable: true
        
        };
    
    enhancedProperty.defineProperty(obj, 'a', descriptor);
    
    obj.a = 8;	//stores 16 (value runs through the converter)
    
    //Property: a
    //Old Value: 5
    //New Value: 16
    
    console.log(obj.a);
    
    // 16
    
    obj.a = 30; //new value is ignored since it’s invalid as per the validator
    console.log(obj.a);	
    
    // 16
    
    //obj.a = 'text' (throws TypeError since property type is number)
    
    

    API

    .defineProperty(obj, prop, descriptor)

    Define or modify a an enhanced property. It throws TypeError if the object is frozen or sealed (There is one exception, please see configurable section).

    Parameters

    {Object} obj

    The object on which to define the property.

    {String} prop

    The name of the property to be defined or modified.

    {Object} [descriptor]

    The descriptor for the property being defined or modified.

    Description

    The descriptor object passed to the defineProperty function contains multiple descriptors that describe the property.

    The descriptor object keys:

    type

    Determine the value type the property accepts. The property accepts any type when the type is not configured.

    Example
    descriptor = 
    {
        type: 'number'
    }
    

    Note: It throw TypeError when assign a value of different type than specified.

    configurable

    Determine whether the property can be re-configured Defaults to false. Note: Throws TypeError when re-configure non-configurable property or when the object is sealed or frozen. Exception to this role is when re-configure only the property writable descriptor from true to false

    Example
    descriptor = 
    {
        configurable: true
    }
    

    enumerable

    Determine whether the property shows up during enumeration of the properties on the corresponding object. Defaults to true.

    Example
    descriptor = 
    {
        enumerable: true
    }
    

    value

    Determine the default value associated with the property. Can be any valid JavaScript value (number, object, function, etc). Defaults to undefined.

    Example
    descriptor = 
    {
        value: 12
    }
    

    writable

    Determine whether the value associated with the property may be changed with an assignment operator or not. Defaults to true. Note: Throws TypeError when assign a value to a non-writable property

    Example
    descriptor = 
    {
        writable: false
    }
    

    converter

    Define the function through which the new value runs before gets assigned to the property. The converter takes one value and returns a new converted.

    Example
    descriptor = 
    {
        converter: function (value) {return value * 2; }
    }
    

    validator

    Define the function that determines whether the new value is valid or not. The new value is ignored and the assignment is skipped silently when the validator returns false. The validator function take one value and return a boolean value determines whether the value is valid or not. Note: The validation runs after the value passed through the converter.

    Example
    descriptor = 
    {
        validator: function (value) {return value <= 50; }
    }
    

    propertyChanged

    Define a callback function that gets called whenever the value of the property changed. The function takes 4 parameters:

    obj

    the object which owns the property

    prop

    the property name

    oldValue

    the property old value

    newValue

    the property new value

    Example
    descriptor = 
    {
        propertyChanged: function (obj, prop, oldValue, newValue) {… }
    }
    

    get

    A function which serves as a getter for the property. if present, it overwrites whatever enhance property generates to provide its features.

    set

    A function which serves as a setter for the property. if present, it overwrites whatever enhance property generates to provide its features.

    obj.getOwnEnhancedPropertyDescriptor(prop)

    returns Read-Only enhanced property descriptor object. obj is the object that owns the enhanced property.

    Parameters

    {String} prop

    prop is the property name.

    License

    MIT © Ahmed AlSahaf

    Install

    npm i enhanced-property

    DownloadsWeekly Downloads

    3

    Version

    1.0.5

    License

    MIT

    Last publish

    Collaborators

    • asahaf