observify-js v1.1.13
Observify JS
Observify is a bare-bones observable and eventing library using Proxies. This library enables you to attach event handlers to your objects so you can be notified when specific properties change. This will also allow you to lock and unlock write access to any property of an object.
A collection of demos will soon be available. Until then, please have a look at the basic demos below as examples of the many ways you could use this in development.
CDN
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/observify-js@1.1.13"></script>
Install
You can install Observify using NPM or Bower
NPM
npm i observify-js --save
Bower
bower i observify-js
Importing
Browser
<script type="text/javascript" src="_your_modules_path/observify.min.js"></script>
Module
import Observify from 'Observify';
Require
const Observify = require('Observify');
RequireJS
require("Observify", function(Observify){
...
});
Examples
.listen
You can bind change listeners to any prop regardless of its type. Deeply nested props can be bound using dot notation.
Listen to root level object property changes
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
person.listen('age', function(newValue, oldValue, propName, eventname) {
console.log(newValue, oldValue);
});
person.age++;
>> 15, 14
Listen to nested object property changes
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
person.listen('tshirt.logo.brand', function(newValue, oldValue, propPath) {
console.log(newValue, oldValue);
});
person.tshirt.logo.brand = 'rvca';
>> rvca, volcom
.unlisten
You can unbind one or all listeners bound to an object property
Remove a single listener
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
const ageChangeCallback = function(newValue, oldValue) {
console.log('The persons age was changed from:', oldValue, ' to ', newValue);
};
person.listen('age', ageChangeCallback);
person.listen('age', function(newValue, oldValue) {
console.log('Secondary callback', oldValue, ' to ', newValue);
});
person.age++;
>> The persons age was changed from: 14 to 15
>> Secondary callback 14 to 15
// remove listener
person.unlisten('age', ageChangeCallback);
person.age++;
>> Secondary callback 14 to 15
Remove all listeners
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
const ageChangeCallback = function(newValue, oldValue) {
console.log('The persons age was changed from:', oldValue, ' to ', newValue);
};
person.listen('age', ageChangeCallback);
person.listen('age', function(newValue, oldValue) {
console.log('Secondary callback', oldValue, ' to ', newValue);
});
person.age++;
>> The persons age was changed from: 14 to 15
>> Secondary callback 14 to 15
// remove listener
person.unlisten('age');
person.age++;
>>
.on
You can create and dispatch custom events to control object updates and/or handle any additional logic needed.
Creating a custom event
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
person.on('changeAge', function(){ this.age++ });
person.listen('age', function(newValue, oldValue) {
console.log('The persons age was changed from:', oldValue, ' to ', newValue);
});
person.trigger('changeAge');
>> The persons age was changed from: 14 to 15
.off
You can unbind one or all namespaced event callbacks
Remove a single callback
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
const onChanegAge = function(){ this.age++ };
person.on('changeAge', onChanegAge);
person.trigger('changeAge');
>> 15
person.off('changeAge', onChanegAge);
person.trigger('changeAge');
>>
Remove all callbacks
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
person.on('changeAge', function(){
console.log('callback 1');
});
person.on('changeAge', function(){
console.log('callback 2');
});
person.on('changeAge', function(){
console.log('callback 3');
});
person.trigger('changeAge');
>> callback 1
>> callback 2
>> callback 2
person.off('changeAge');
person.trigger('changeAge');
>>
.trigger
Once you've created some custom events you can invoke them using .trigger
Invoking a custom event
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
person.on('changeAge', function(){
console.log('callback 1');
});
person.trigger('changeAge');
>> callback 1
.lock
You can prevent writes (aka lock) to the entire object or specific properties. Any associated listeners will be ignored once a property has been locked.
Invoking a custom event
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
person.lock('tshirt.logo');
person.tshirt.logo.brand = 'rvca';
>> person.tshirt.logo.brand is still 'volcom'
.unlock
You can unlock a property to make changes and lock it again (if needed). Once a property has been unlocked all property listeners will be restored.
const person = Observify({
eyes: 'green',
age: 14,
hair: 'brown',
tshirt: {
color: 'white',
logo: {
brand: 'volcom'
}
}
});
person.lock('tshirt.logo');
person.tshirt.logo.brand = 'rvca';
>> person.tshirt.logo.brand is still 'volcom'
person.unlock('tshirt.logo');
person.tshirt.logo.brand = 'rvca';
>> person.tshirt.logo.brand is now 'rvca';
Setup
npm install
Tests
To start Karma and execute all unit tests with coverage, run:
npm run unit