dahelpers

DaHelpers

These are da helpers to help you out.

A growing collection of miscellaneous general-purpose helper function for JavaScript in browsers and on NodeJS.

Installation

This module is in UMD format. It can be used with an AMD loader such as RequireJS, on NodeJS, or in browsers using <script> tag.

NodeJS

Install with NPM:

npm install dahelpers

volo

Install with:

volo add foxbunny/dahelpers

Browser

Either require() it if using RequireJS, or add a <script> tag. When using with the <script> tag, the module will create a dahelpers global.

Usage tips

Here are some usage tips that can make using DaHelpers easier.

Using function stand-alone

All function can be decoupled from the dahelpers module/global and used stand-alone. For example:

var type = dahelpers.type;
var thousands = dahelpers.thousands;
type('foo');
thousands(3000);

If you are using CoffeeScript, this can be even easier:

{type, thousands} = dahelpers;
type 'foo'
thousands 3000

Type detection using type()

We all know that the typeof can be quite awkward and limited, and sometimes plain wrong. The DaHelpers' type() function aims to fix this by wrapping the Object.prototype.toString and performing some formatting to make it less cumbersome.

var type = dahelpers.type;
type(null);       // 'null'
type(undefined);  // 'undefined'
type(1);          // 'number'
type(/abc/);      // 'regexp'

The same function can also be used to test the type for convenience.

type(null, 'null'); // true
type(1, 'string');  // false

Note that the case of the second argument does not matter. This is perfectly valid:

type(/abc/, 'RegExp'); // true
type(/abc/, 'regexp'); // true
type(/abc/, 'REGEXP'); // true

Modifying Underscore template() to add DaHelpers

Here is a pattern for including DaHelpers in UnderscoreJS templates.

var type = dahelpers.type;
var extend = dahelpers.extend;
var origTemplate = _.template;
_.template = function(src, data, settings) {
  if (type(data, 'undefined')) {
    var precompiled = origTemplate(src, data, settings);
    return function(data) {
      return precompiled(extend({d: dahelpers}, data));
    }
  } else {
    return origTemplate(src, extend({d: dahelpers}, data), settings);
  }
};

This makes DaHelpers available as d within the templates. Now you can:

_.template("Here's <%= d.currency(money) %>", {money: 200})
// returns "Here's $200.00"

Prototypal inhertiance with create()

DaHelper includes a create() function which can be used for doing prototypal inhertiance. For example:

var parent = {
   name: 'Fred',
   lastName: 'Stevens',
   fullName: function () {
      return this.name + ' ' + this.lastName;
   }
};

var child = dahelpers.create(parent, {
    title: 'Mr',
    fullName: function () {
        return this.title + '. ' + this.__super__.fullName.call(this);
    }
});

child.fullName();  // returns 'Mr. Fred Stevens'

The first argument to create() is the parent object. The other arguments are optional, and they are mixin objects whose properties are deep-copied into the created object. You will notice that the created object also has a __super__ property which points to the parent object (i.e., the child's prototype).

Create and use iterator objects with iter().

DaHelpers supports lazy iteration in the same vein as Dan Tao's LazyJS, although not as fully-featured. The iterator object allows us to specify any number of composable functions that will be applied to sequence members when we actually need them, rather than immediately.

The iterator object currently has a very limited API that has lazy mapping via the #apply() method, and eager (non-lazy) methods such as #map(), #filter(), #reduce() and similar (see full API docs). Here we will take a look at the lazy #apply() method.

var seq = [1, 2, 3];
var fn = function (n) { return (n + 1) * 2; };
var iterator = dahelpers.iter(seq);
iterator.apply(fn);
iterator.get(1);  // Returns 6 (=== (2 + 1) * 2)

Unlke map, in the above example the fn function only gets called once, when we call the get() method. The functions passed to apply are composable, so we can break the above down to:

var seq = [1, 2, 3];
var fn1 = function (n) { return n + 1; };
var fn2 = function (n) { return n * 2; };
var iterator = dahelpers.iter(seq);
iterator.apply(fn2, fn1);
iterator.get(1);  // Returns 6 (same as the first time)

In the above example, applying fn2 then fn1 is the same as saying fn2(fn1(item)) for each item in the sequence. The last function specified is the innermost.

The iterator object maintains an internal counter which points to current index. When #get() is called, this index is updated to the index used to retrieve the item. This internal counter is set to -1 initially.

The iterator also has #next() and #prev() methods that retrieve the next and previous item respectively. They work the same way as the #get() method and functions are applied only when the methods are called, and they use the internal counter to determine what the next or previous item is.

var seq = [1, 2, 3];
var fn1 = function (n) { return n + 1; };
var fn2 = function (n) { return n * 2; };
var iterator = dahelpers.iter(seq);
iterator.apply(fn2, fn1);
iterator.next();  // Returns 4
iterator.next();  // Returns 6
iterator.next();  // Returns 8
iterator.next();  // Error: No more items

As you can see from the example, the #next() method will throw an exception when there are no more items. This is by design. The #prev() method works exactly the same way but in reverse, and throws an error when there are no previous items or the counter is -1.

API documentation

The full API documentation can be found in the doc directory.

Reporting bugs

Report all bugs and feature requests to the GitHub issue tracker.