ghostrap

Observe the object property getter, setter or method calls and add custom behavior.

ghostrap can intercept object on any timing (e.g. property value change, assignment, function invocation, etc).

Installation

In Browser:

<script src="ghostrap.js"></script>

or

<script src="ghostrap.min.js"></script>

Function object ghostrap will defined in the global scope.

In Node.js:

npm install ghostrap

var ghostrap = require('ghostrap');

bower:

bower install ghostrap

Usage

ghostrap

ghostrap is a handy constructor. new operator is not needed.

• ghostrap ( target )
  @param {Object} target The target object to trap.
  @return {ghostrap} Return an instance of ghostrap.

In this example, outputs a log when the object message has change.

var myModel = {
  id: 1,
  message: 'Hello'
};

var ghost = ghostrap(myModel);
ghost.on('change:message', function() {
  console.log('message changed!');
});

myModel.message = 'Good evening';
// message changed!
myModel.message = 'Good night';
// message changed!

on

Add new handler.

• on ( type, func )
  @param {string} type Type of listener/trigger.
  @param {function} func handler function.
  @return {ghostrap} Return an instance of ghostrap.

type

The first argument type separates by a colon. 'when:propName' e.g. 'get:myPropName'

when:

• beforeget
  trigger on before get.
• get
  trigger on get.
• beforeset
  trigger on before set value.
• set
  trigger on set value.
• beforeapply
  trigger on before function calls.
• apply
  trigger on function calls.
• change
  trigger on changed value.

handler

The second argument func is a handler function. On callback arguments are following.

function(target, key, value, args) { ... }

• target : target object.
• key : target key.
• value : value to be returned.
• args : original function arguments. ('apply' or 'beforeapply')

Example:

var myData = {
  data: '',
  maxLength: 20
};

var ghost = ghostrap(myData);
ghost.on('set:data', function(target, key, value) {
  // Truncate data value to the maximum length when set new data.
  if (value.length > myData.maxLength) {
    value = value.substr(0, myData.maxLength - 3) + '...';
  }
  return value;
});

myData.data = 'Lorem ipsum dolor sit amet';
console.log(myData.data); // 'Lorem ipsum dolor...'

once

Add a new handler. Just like on, but handler is called only once.

off

Remove a handler. If argument type is specified, same types handlers are removed. If argument func is specified, same handlers are removed. If arguments is omitted, all handlers are removed.

• off ( [type] [, func] )
  @param {string} [type] Type of listener/trigger.
  @param {function} [func] handler function.
  @return {ghostrap} Return an instance of ghostrap.

Example:

var myModel = {
  id: 1,
  message: 'Hello'
};

function onMessageChange(target, key, value) {
  console.log('message changed!', value);
}

var ghost = ghostrap(myModel);
ghost.on('change:message', onMessageChange);

myModel.message = 'Good evening';
// message changed!
myModel.message = 'Good night';
// message changed!

ghost.off('change:message', onMessageChange);

myModel.message = 'Good morning';
// no console logs.

clear

Clear all handlers and release the target object reference.

• clear ( )
  @return {ghostrap} Return an instance of ghostrap.

License

MIT