Sprinkles

Sprinkles is ActiveSupport for your browser.

The goal of this project is to isolate a small collection of helpers and extensions to make our lives as front-end engineers a little easier — just like ActiveSupport has done for Ruby on Rails engineers.

Though syntatically optimal, monkey patching is general considered a bad idea so Sprinkles prefixes all methods and globals with a "$" to differentiate them from any native methods your client may have.

In Sprinkles, you'll find:

Array extensions
Cookies
Date extensions
Query string params
String inflections
XHR helpers

What you won't find in this project is:

Effects or animation (e.g., fadeOut())
Browser backwards-compatibility
Heavy-handed DOM manipulation (e.g., wrapAll())
DOM selection (e.g., Sizzle)
Anything a modern browser can already do

This project is under active development so things will change dramatically as it matures. For contributions, please fork and submit pull requests.

Array Extensions

Your browser is all grown up! Let it loop(), map(), and reduce() your arrays.

var pies = ["apple", "pecan", "cherry"];

pies.forEach(function(pie, i) {
  alert("Do you like " + pie + " pie ?");
});

pies.map(function(pie, i) {
  return pie + " pie";
}); // Returns ["apple pie", "pecan pie", "cherry pie"]

pies.reduce(function(previousPie, currentPie) {
  return previousPie + "," + currentPie;
}); // Returns "apple,pecan,cherry"

Sprinkles adds $flatten() to Array.prototype.

[[1], [2], [3]].$flatten(); // Returns [1, 2, 3]

Cookies

Working with cookies isn't very fun if all you have is document.cookie. Sprinkles adds document.$cookies that makes managing cookies a little easier. The API is designed to closely match that of localStorage.

document.$cookies.setItem("foo", "bar"); // Write a cookie, "foo", with value "bar"
document.$cookies.getItem("foo");        // Returns "bar"
document.$cookies.removeItem("foo");     // Remove cookie, "foo"
document.$cookies.clear();               // Remove all cookies

Sprinkles always assumes the path on all your cookies is / and does not support cookies that specify domain, max-age, expires, or secure — maybe one day.

Date Extensions

Manipulating a date in plain old JavaScript is no fun. Sprinkles makes it better.

var d = new Date(1986, 0, 24, 20, 25); // Jan 24th, 1986 at 20:25
d.$beginningOfDay();                    // Jan 24th, 1986 at 00:00
d.$endOfDay();                          // Jan 24th, 1986 at 23:59
d.$beginningOfMonth();                  // Jan  1st, 1986 at 00:00
d.$endOfMonth();                        // Jan 31st, 1986 at 23:59
d.$tomorrow();                          // Jan 25th, 1986 at 20:25
d.$yesterday();                         // Jan 23rd, 1986 at 20:25
d.$monthName();                         // "January"
d.$dayName();                           // "Friday"

DOM Manipulation

Sprinkles won't do things a modern browser can already do, even if that means a bit more typing.

var results = document.querySelector("#results"), // Retrieve an element
    result  = document.createElement("div");      // Create an element

result.classList.add("result");                   // Add a class to an element
result.textContent = "One more thing...";         // Set the content of an element

results.appendChild(result);                      // Add an element as a child

If you do a lot of this, maybe you should write a function like createElement(name, content, parent).

Query String Params

Read the query string params off any URL with the class methods Sprinkles adds to Location:

Location.$getParams("http://example.com/?a=1&b=2")     // Returns { "a": "1", "b": "2" }
Location.$getParam("http://example.com/?a=1&b=2", "a") // Returns "1"

Sprinkles also adds instance methods Location to read query string params from the current window's location:

// Assuming window.location = "http://example.com/?a=1&b=2"
window.location.$getParams()   // Returns { "a": "1", "b": "2" }
window.location.$getParam("a") // Returns "1"

String Inflections

ActiveSupport has a bunch of slick string inflections. Sprinkles just has the one for now.

"1".$ordinalize()  // "1st"
"22".$ordinalize() // "22nd"

XHR (AJAX)

Creating an XMLHttpRequest object from scratch is tedious, so get() and getJSON() have been added as methods on window as convenience.

window.$get("http://example.com/plain-text",
  function(text) { console.log(text) },     // success
  function(text) { console.log(text) }      // error
);

window.$getJSON("http://example.com/json",
  function(object) { console.log(object) }, // success
  function(object) { console.log(object) }  // error
})

Development

Sprinkles uses Grunt to run development-oriented tasks. Grunt relies on Node Packaged Modules (NPM). You can install NPM with Homebrew. With NPM installed and from inside the Sprinkles project root run:

npm install

This is the Ruby equivalent of running bundle install. Now you can run the following tasks individually:

grunt concat
grunt qunit
grunt jshint
grunt uglify

You can also run grunt test to validate syntax and test. When you're work is done, run grunt to validate, test, concatenate, and minify.

dylanjha / sprinkles