node package manager

nativity

Safely install functions on object prototypes.

nativity

Safely add methods to native object prototypes.

  • Doesn't overwrite existing properties with same name by default for safety.
  • If you do overwrite properties, you can access and restore them at any time.
  • Automatically forwards "this" as first argument to installed functions. This is the magic that makes non-prototype functions work as prototype functions.

Install

$ npm install --save nativity

Usage

var nativity = require('nativity');
var _ = require('underscore');

nativity.install(Array.prototype, _, ['findWhere', 'pluck']);

var people = [
	{ name: 'Tina', age: 45 },
	{ name: 'Todd', age: 48 },
	{ name: 'Tucker', age: 10 }
];

console.log(people.findWhere({ name: 'Todd' }));
// { name: 'Todd', age: 48 }

console.log(people.pluck('name'));
// ['Tina', Todd', 'Tucker']

You can install a single method:

nativity.installOne(String.prototype, _.template, 'format');

console.log('Hello <%= name %>!'.format({ name: 'Bartholomew' }));
// Hello Bartholomew!

API

nativity.install

Assigns the props from the source object to the destination object. Functions are converted to forward 'this' as the first argument.

nativity.install(destObject, srcObject[, props][, options]);

nativity.installOne

Assigns the value to the source object at the given key. If the value is a function it will be converted to forward 'this' as the first argument.

nativity.installOne(destObject, value, key[, options]);

Options

Defaults:

nativity.install(Array.prototype, _, ['findWhere', 'pluck'], {

	// do not override existing properties on the host object
	safe: true,

	// only add properties that are functions
	functionsOnly: false,

	// specifies the argument index at which to forward 'this'
	thisIndex: 0

});

Restoration

Nativity installs methods on objects safely, that is, you can access overwritten properties and restore them at any time.

var mylib = {
	map: function(arr) { return 'blurp' },
	filter: function(arr) { return 'skronk' },
	dud: function() { return 'dud'; }
};
var installation = nativity.install(Array.prototype, mylib, { safe: false });

console.log([1,2,3].map(function(n) { return n*n; }));
// 'blurp'

console.log(installation.overwritten);
// 2

console.log(installation.new);
// { dud: [Function] }

console.log(installation.prev);
// { map: [Function], filter: [Function] }

installation.restore();
console.log([1,2,3].map(function(n) { return n*n; }));
// [1,4,9]

Notes

Technically, nativity is written such that it can add properties to any object (i.e. _.defaults). It is the automatic forwarding of "this" as the first argument to installed methods that makes it special.

_.pluck(people, 'name')
people.pluck('name')

Why is this better?

  • Mimics Subject-Verb-Object structure of the English language
  • More object-oriented
  • Inherently chainable

Build Notes

$ gulp --require coffee-script/register

Plugins

Nativity is designed for library authors to expose appropriate methods for use on native object prototypes in a safe manner. See the nativity plugins below for examples. Submit a pull request to add yours to the list.