Menu toggle
Fork me on GitHub


Cleaner, simpler JavaScript for ES6

Build Status

Agave.js safely extends native JavaScript objects with useful things you'll use every day.

What does Agave provide?

Remember, all methods are available under the prefix you enabled agave with (if any).


Tells you the closest prototype in the inheritance tree or, for always-primitive types like 'null' and 'undefined', the primitive name. Think of it like a typeof() that does what you expect.

So you can access it easily, kind() is a global (of course, it's prefixed like everything else in Agave).

kind(37) === 'Number'
kind(3.14) === 'Number'
kind(Math.LN2) === 'Number'
kind(Infinity) === 'Number'
kind(Number(1)) === 'Number'
kind(NaN) === 'NaN'
kind('') === 'String'
kind('bla') === 'String'
kind(String("abc")) === 'String'
kind(new String("abc")) === 'String'
kind(true) === 'Boolean'
kind(false) === 'Boolean'
kind(new Boolean(true)) === 'Boolean'
kind([1, 2, 4]) === 'Array'
kind(new Array(1, 2, 3)) === 'Array'
kind({a:1}) === 'Object'
kind(new Object()) === 'Object'
kind(new Date()) === 'Date'
kind(function(){}) === 'Function'
kind(new Function("console.log(arguments)")) === 'Function'
kind(Math.sin) === 'Function'
kind(undefined) === 'undefined'
kind(null) === 'null'

Object methods

The following examples are based on this sample object:

var mockObject = {
  foo: 'bar',
  baz: {
      zog:'something useful'

Returns an array of the object's keys.




Returns the number of properties in the object.




Provided with either a '/' separated path, or an array of keys, get the value of the nested keys in the object. If any of the keys along the way are missing, return undefined. This is very useful for useful for checking JSON API responses where something useful may be buried deep inside an object, but you don't want to error out if the path doesn't exist. Eg, the following code:


or, alternatively:


will return:

'something useful'

However, checking for a path that doesn't exist:


will simply return:


Keys, of course, could be strings, array indices, or anything else.


Returns a deep clone of the object, so that modifications to the new object will not affect the original.


Iterates over the object's keys and values, using the function provided.


Applies the properties from newProperties object to the existing object.


will return:


Array methods


Returns a shallow clone of the object.


returns true if the array contains the item.




When provided with a function to test each item against, returns the first item that where testfunction returns true.


Adds the items from newarray to the end of this array.


Turns an array of Elements into a NodeList.


Removes member from the array, returning true if the member was found, false otherwise.

Function methods


Run a function after it hasn't been invoked for 'wait' ms. Commonly used to stop repeated calls to a function overlapping each other (sometimes called 'bouncing').

For example, window.resize() events normally fire repeatedly as a user resizes a window, causing functions that are waiting for the 'resize' event to run at the same time, which can cause problems.

var updateLayout = function(event) {
  console.log('Updating layout!')

window.addEventListener("resize", updateLayout.throttle(500));

Will wait until the user has stopped dragging the window for 500ms before printing:

Updating layout!

on the console.

.repeat(arguments, interval, leadingEdge)

Run the function repeatedly at the interval (in ms). If leadingEdge is true, run the function immediately too.

var doThing = function(first, second){
  console.log('first', first, 'second', second)

var interval = doThing.repeat(['red', 'pandas'], 1000, true)

Will run doThing() immediately, then every second afterwards.

String methods


returns the string, with the specified characters removed from the beginning and end.

'Hello world'.strip('Hld')


'ello wor'

returns the string, with the specified characters removed from the beginning.


returns the string, with the specified characters removed from the end.


Runs iterationFunction over each character in the String. Just like ES5's inbuilt Array.forEach().


Returns a backwards copy of the string.

Number methods

Note: wrap numbers in brackets to use methods on them, otherwise the '.' is interpreted as a decimal point.

.seconds, .minutes(), .hours(), .days(), and .weeks()

Converts a number into the amount of milliseconds for a timespan. For example:




Since 5 days is 432000000 milliseconds.

.before(), .after()

Turns a number (assumed to be an amount of milliseconds) into the Date in the past (using .before) or the future (using .after). You'd typically combine this with .seconds, .hours, .days, and .weeks to easily get a date a certain amount of units in the past or the future. For example:


Returns a Date for 2 days ago, eg:

Tue Jun 04 2013 22:16:50 GMT+0100 (BST)

You can also specify a date to be before/after. For example:

var joinedCompanyDate = new Date('Tue Jun 04 2013 1:00:00 GMT+0100 (BST)')

Returns a Date for 3 weeks after that date, eg:

Thu Jun 27 2013 22:44:05 GMT+0100 (BST)
.round(), .ceil(), .floor(), .abs()

Returns the value corresponding to Math.round(number) etc.

number = 4.2;
number.round(); // 4
number.ceil();  // 5
number.floor(); // 4

number = -4.2;
number.abs();        // 4.2
number.abs().ceil(); // 5

Returns the number multiplied by itself exponent times.

(5).pow(3); // 125

Why would I want to use Agave?

Agave will make your code shorter and more readable.

How Does Agave Compare to Sugar.js?

Sugar.js is an excellent project and was the inspiration for Agave. Like Sugar, Agave provides useful additional methods on native objects. Here are the the differences:

How Does Agave Compare to Underscore.js and Lodash?


I read that adding methods to prototypes is bad

Agave addresses a number of concerns people have raised over the years since Prototype.JS first began extending built ins. Andrew Dupont's talk at JSConf 2011 provides an excellent overview on how the JS community has approached this topic over time.

Q. Will Agave methods appear when iterating over objects?

A. No. Methods will never appear when iterating over objects.

Adding methods to inbuilt objects was bad, back on ES3 browsers like IE8 and Firefox 3 and older. ES3 didn't provide a way for developers to add their own non-enumerable properties to inbuilt objects.

Let's see the problem: open your browser console right now and add a method, the traditional way:

Object.prototype.oldStyleMethod = function oldStyleMethod (){}

And make an object:

var myobject = {};

Watch what happens when we iterate over the object:

for (var key in myobject) { console.log(key) };

You can see the problem: 'oldStyleMethod' shows up as one of myobject's keys. This will break things and is indeed bad.

But wait a sec: Objects already have some methods out of the box. Like toString():

function toString() { [native code] }

function oldStyleMethod(){}

Why are only our add-on methods showing up as keys? Why don't the native, inbuilt methods appear in our 'for' loop?

The answer is that inbuilt methods in JavaScript have always been non-enumerable. But in ES3, you never had the ability to make your own non-enumerable methods.

ES5 - the current version of JavaScript created in 2009 that Chrome, Firefox, and IE9-11, as well as node.js use - specifically allows for the addition of new non-enumerable properties via Object.defineProperty().

So open a new tab. Let's try again, ES5-style:

Object.defineProperty( Object.prototype, "newStyleMethod", {value: function newStyleMethod(){}, enumerable: false});

for (var key in myobject) { console.log(key) };

Hrm, it seems newStyleMethod(), just like toString(), doesn't interfere with our loops.

This is exactly what Agave uses. As a result, Agave's methods will never show up in for loops.

So if you're OK with Agave's requirements - ie, you support only ES5 environments like current generation browsers and node - you can use Agave.

Q. Future ES versions or other libraries might use the same method names to do different stuff

A. That's why Agave uses prefixes

Another concern may be naming or implementation conflicts - ie, another library or perhaps a new version of ES includes some code that uses the same method name to do something differently. This is why Agave makes you to prefix every method it provides. Just start it with:


or any prefix of your choice to have all the methods prefixed with whatever string you like.

Using a prefix is the preferred mechanism for publicly distributed libraries that use Agave.

The prefix can be as short or as long as you like. In my own experience I've found two letters has been enough to avoid conflicts in the last year I've been using Agave, prior to its public release. If you're think this might not be enough to satisfy the need for uniqueness, use a longer prefix. If you're feeling adventurous (and you strongly control the libraries used in your projects) you can use no prefix at all.

Q. There are new methods on my window object!

A. Yes, window is an object. This is how JS works.

Everything's an object in JS, so everything has has object methods. We mentioned object.toString() earlier - there's a window.toString() in your browser, and a global.toString() in Node that JS provides because window and global are objects.

When running agave, the additional methods added to Object.prototype will appear on window and global just like the inbuilt ones. You might find this odd, but it's expected behavior.

You may find this useful - for example, if you wanted to find out whether some deeply nested set of keys exists underneath window, then .getPath() is awfully handy.

It would make things nicer if a future version of JS allowed us to isolate prototypes between modules. But it certainly won't kill us in the meantime if we're using prefixed, non-enumerable methods.

Using Agave

In the browser, on the server, or both:

Just run:

npm install agave

Then in your code:

var agave = require('agave');
// Start Agave, providing a prefix of your choice.

All the methods above are now available.

I've got stuff to add!

Awesome. Fork the repo, add your code, add your tests to tests.js and send me a pull request.


Install node.js, and run:

npm install

Inside the folder you downloaded Agave to.

What browsers does Agave support?

Any ES5 compatible environment. This includes current Chrome, current Firefox, current Safari, IE9-11 and node.js.

What about IE8 and Firefox 3 support?

Sorry, but this isn't possible. ES3 browsers like IE8 and Firefox 3 don't support Object.defineProperty() and it cannot be emulated via shims.


MIT license.


Mike MacCana (