null

Object methods

.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 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:

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

or, alternatively:

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

will return:

'something useful'

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

mockObject.getPath(['baz','gur','yak'])

will simply return:

undefined

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.

String methods

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

.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:

.pow(exponent)

Why would I want to use Agave?

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:

Agave has been affected by none of the conflicts that have affected SugarJS. Not affected by the String.prototype.namespace() conflict or the Array.prototype.find() conflict or any other conflict.

Agave extends all prototypes using a user-specified prefix to avoid collisions. This is one reason why Agave requires an ES5 browser (ie, Agave doesn't work with IE8).

Since Agave uses non-enumerable methods, regular 'for' loops work with Agave. You don't have to use hasOwnProperty() all the time.

SugarJS avoids extending Object. Agave has prefixing and non-enumerable methods, Agave provides extra methods on Object - and again, has been unaffected by any conflicts with other libraries or ES itself.

Agave does not attempt to support IE8 and other ES3 browsers, resulting in a much smaller code base that is free of ES3 shims.

Agave focuses only on things JS programmers do every day, and is much smaller than Sugar.js. Sugar.js has String.prototype.humanize() and String.prototype.hankaku(). Agave won't ever have those.

How Does Agave Compare to Underscore.js and Lodash?

Agave.js provides methods to complement those provided by ES5, rather than functions attached to punctuation.

Agave doesn't require a separate string library.

Agave does not attempt to support IE8 and other ES3 browsers, resulting in a much smaller code base that is free of ES3->ES5 shims.

Agave is probably not as fast as lodash - it deliberately chooses simple, more obvious code over faster but more obscure options. This shouldn't make much difference to most people, but if it does, you can easily patch Agave to use any preferred techniques.

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

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.