Menu toggle
Fork me on GitHub

agave.js

Cleaner, simpler JavaScript for ES5 environments

Build Status Doge Status

Agave.js safely extends native JavaScript objects with helpful, intuitive methods that make your code shorter and more readable.

Agave works on current versions of Chrome, Firefox, Safari, IE9-11 and node.

What does Agave provide?

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

kind

Tells you the 'kind' of an object, the same way you'd expect it. Specifically it returns the closest prototype in the inheritance tree or, for always-primitive types like 'null' and 'undefined', the primitive name.

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

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

Object methods

The following examples are based on this sample object:

var mockObject = {
  foo: 'bar',
  baz: {
    bam:'boo',
    zar:{
      zog:'something useful'
    }
  }
}
.getKeys()

Returns an array of the object's keys.

mockObject.getKeys()

Returns:

['foo','baz']
.getSize()

Returns the number of properties in the object.

mockObject.getSize()

Returns:

2
.getPath(path)

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 are missing, return undefined. This is very useful for useful for checking JSON API responses where something useful is buried deep inside an object. Eg, the following code:

mockObject.getPath('/baz/zar/zog')

or, alternatively:

mockObject.getPath(['baz','zar','zog'])

will return:

'something useful'

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

.clone()

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

.forEach(function)

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

.extend(newProperties)

Applies the properties from newProperties object to the existing object.

mockObject.avextend({
  'gnar':{
    shub:'zoo'
  },
  'gert':{
    yaz:'frub'
  }
});

will return:

{
  "foo":"bar",
  "baz":{
    "bam":"boo",
    "zar":{
      "zog":"victory"}
    },
    "null":{
      "yarr":{
        "parrot":"ahoy"
      }
    },
  "gnar":{
    "shub":"zoo"
  },
  "gert":{
    "yaz":"frub"
  }
}

Array methods

.clone()

Returns a shallow clone of the object.

.contains(item)

returns true if the array contains the item.

['one','two','three'].contains('two')

Returns:

true
.findItem(testfunction)

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

.extend(newarray)

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

.toNodeList()

Turns an array of Elements into a NodeList.

.remove(member)

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

Function methods

.throttle(wait)

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.

String methods

.contains(substring)

returns true if a string contains the substring

'elephantine'.contains('tin')

Returns:

true
.startsWith(substring)

returns true if a string starts with the substring

.endsWith(substring)

returns true if a string ends with the substring

'Hello world'.endsWith('world'))

Returns:

true
.strip(characters)

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

'Hello world'.strip('Hld')

Returns:

'ello wor'
.leftStrip(characters)

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

.rightStrip(characters)

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

.forEach(iterationFunction)

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

.repeat(times)

Repeat the string times times.

.reverse()

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:

(5).days()

Returns:

432000000

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:

(2).days().before()

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)')
(3).weeks().after(joinedCompanyDate)

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
.pow(exponent)

Returns the number multiplied by itself exponent times.

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

NodeList methods

NodeLists are what's returned when you use the document.querySelectorAll(), or similar methods.

For example, given the following document:

<html>
  <body>
    <article>
      <heading>Sample document</heading>
      <author></author>
      <p>Carles portland banh mi lomo twee.</p>
      <p>Narwhal bicycle rights keffiyeh beard.</p>
      <p>Pork belly beard pop-up kale chips.</p>
    </article>
  </body>
</html>

We can fetch a list of all paragraphs:

var paragraphs = document.getElementsByTagName('p');

Agave adds a number of useful methods that you can use both server-side and client side.

.reverse()

Returns a reversed version of the nodeList.

.forEach(iterationFunction)

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

Here's an example of changing every paragraph in a document to say 'Hello' (look ma, No JQuery!).

paragraphs.forEach(function(paragraph){
  paragraph.innerText = 'Hello.';
})

Element methods

Agave also provides useful methods for Elements.

.createChild(name, attributes, innerText)

Make a new child element, with the tag name, any attributes, and inner text specified.

var article = document.querySelector('article');
article.createChild('p',{'id':'testpara'},'hey there');

Would create a new

<p id="testpara">hey there</p>

element beneath

 <article>
.matches(selector)

Returns true if the element matches the selector provided.

.applyStyles(styles)

Apply the styles mentioned to the element.

.ancestorNodes(selector)

Returns a NodeList of an element's parents, from closest to farthest ancestor. If selector is provided, only the parents which match the selector will be returned.

.toggleClass(className)

Toggles a class.

.getParentIndex()

Return index of the element under its parents. Eg, if the element is the fourth child, return 3.

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?

Concerns

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():

console.log(Object.prototype.toString)
function toString() { [native code] }

console.log(Object.prototype.oldStyleMethod)
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:

agave.enable('av');

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

On the server (node.js)

Just run:

npm install agave

Then in your code:

var agave = require('agave');
agave.enable('yourPrefix');

In the browser, on the server using RequireJS, or shared between the browser and server.

Agave is provided as an AMD module. You'd normally load it as a dependency for your own module, either in the browser or on node.js, using RequireJS:

define('yourmodulename', ['agave'], function (agave) {
  // Start Agave, optionally you can also provide a prefix of your choice.
  agave.enable('yourPrefix');

  // Your code here...

})

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.

Tests

Install node.js, and run:

npm install
mocha

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.

License

MIT license.

Author

Mike MacCana (mike.maccana@gmail.com)