Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/foxbunny/dahelpers

These are da helpers to help you out
https://github.com/foxbunny/dahelpers

Last synced: 28 days ago
JSON representation

These are da helpers to help you out

Awesome Lists containing this project

README 

        
# 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 `` 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](http://danieltao.com/lazy.js/), 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](https://github.com/foxbunny/dahelpers/blob/master/doc/dahelpers.mkd#iterator-object)).

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](https://github.com/foxbunny/dahelpers/blob/master/doc/dahelpers.mkd).



## Reporting bugs



Report all bugs and feature requests to the [GitHub issue

tracker](https://github.com/foxbunny/dahelpers/issues).