enhanced-property

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