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