observify-js

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.

• Babel 7
• Webpack 4
• Jasmine
• Chai
• Sinon
• Karma
• Istanbul

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.

• Observify with DOM elements
• Observify with state

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