1.5.9 • Public • Published


Build Status Coverage Status

Papillon is a smart change detection library.

The library is using the fact, that changes of data in the context of the browser cannot be provided more often than the refresh rate of the browser.

Instead of watching every change, the library creates a frozen states of objects between repaints and provides the difference between these states.

Getting started

npm install papillon
import { Observer, State } from 'papillon';

NPM package contains UMD built version of the library in dist/ path.


State provides an singleton interface for storing state of object. Only last state and changes between this and the previous state are stored.

Singleton pattern ensures low memory usage and consistent states for objects that reference to themselves.

Module uses a state counter that increase only before next repaint. Checking state multiply times before counter is changed yields the same results.

Static methods

let statestamp =

Returns the current value of the state counter.



let state = new State({ one: 'two' });


  • Object target object


  • - reference to object, which state is stored
  • state.lastCheck - value of state counter when target was checked
  • state.lastChange - value of state counter when target has changed
  • state.changelog - list of changes between previous and current state


 one: { type: 'set', oldKey: 'five' },
 two: { type: 'set', oldValue: 'some'},
 three: { type: 'delete', oldValue: 'before removed'},
 four: { type: 'modify', changelog: {...} }
  • set - Set reference or primitive value.
  • delete - Deleted property.
  • modify - Nested changes of Object property in changelog.
  • oldValue - Property value from last state.
  • oldKey - Property key from last state which value was moved to this property. Paremeter is set only when new value of old property has changed. In another words, it is set only for relocated properties, not copied.


Checks if target object has changed from last state. If it is true, method regenerates changelog.


This module connects changes of observed object properties with callback action. Callback method is called with changelog state property.

Observed property is redefined as getter/setter. Getting or setting that property will trigger request for state change detection before next repaint.


let host = {test: 'one'};
let observer = new Observer(host, 'test', changelog => {
// Will trigger log in console before next repaint
host.test = 'two';


  • Object host object
  • String | Array<String> properties - one or more properties
  • Function callback - takes changelog object as argument


Schedule change detection with window.requestAnimationFrame.

This method is called when the observed property is set or get. You do not have to use this method directly. If your code changes object by other reference then observed property, you have to schedule checking manually.


Cancel scheduled checking request and revert observed properties to original definition. If your code do not requires object with original definition of observed properties you do not have to call this method.

After destroying Observer instance, accessing properties will not trigger check() method.


Feel free to contribute project. Fork repository, clone and run:

npm install && npm run develop

Write some code, provide proper tests and pull request to this repository.


Papillon is released under the MIT License.

Package Sidebar


npm i papillon

Weekly Downloads






Last publish


  • smalluban