# {%= name %} {%= badge("fury") %} {%= badge("travis") %}

> {%= description %}


{%= include("install-npm", {save: true}) %}

## TOC

<!-- toc -->


## Usage

**Utils grouped by collection**

The top level export gives you an object with utils grouped into collections, like `array`, `object`, `math`, etc:

```js
var utils = require('{%= name %}');
//=> {array: {flatten: [function], ...}, collection: {...}}
```

See [example.md](./example.md) for an example of the `utils` object.


**Get all utils on one object**

If you want all utils on a single object (e.g. not grouped by collection):

```js
// all utils are on the `_` property
var utils = require('{%= name %}')._;
```

**Only get a specific collection**

If you just want the `string` or `object` utils:

```js
var string = require('{%= name %}').string;
var object = require('{%= name %}').object;
```

## API
{%= apidocs("lib/**/*.js") %}

## Code coverage

Please help improve code coverage by [adding unit tests](#contributing).

```
{%= coverage("coverage/summary.txt") %}
```

## Running tests
{%= include("tests") %}

## Contributing
> {%= include("contributing") %}

### Adding utils

If you want to do a PR to add a util, please read the following first:
 
  - follow the same coding style as the rest of the library, same with code comments
  - add sufficient unit tests
  - Install dev dependencies and [run verb](#running-verb)
  - Look over the README to make sure that verb rendered out the docs with your method and code comments.

**Adding external modules as dependencies**

  - External modules will only be considered if they meet the same quality and coding standards as the rest of the library. At minimum this includes documentation, code comments, and unit tests. Benchmarks are also strongly preferred.

### Updating the docs

Do not edit the readme manually since [verb] is used to generate documentation. 

  - API docs: If you see an error in the API documentation, just update the code comments for that method, then [run verb](#running-verb).
  - Everything else, please look over the [.verb.md](./.verb.md) template to see where the error is, then [run verb](#running-verb).

### Running verb
{%= include("run-verb") %}


## About

**Why another utils lib?**

  - I'm a node.js developer. I want fast, light, dependable utility functions for node.js projects. 
  - Do you really need bloated, everything-but-the-kitchen-sink functions that are guaranteed to work with IE 4, **for your Yeoman generator or gulp plugin**!? Nonsense. 
  - The benchmarks that accompany many of the functions in the library show that in some cases, the penalty for using such "kitchen-sink" code is a 2,000-5,000% reduction in speed. Sometimes greater.

**Project goals**

  - Fastest implementation of each method, without too much compromise. Covering uncommon cases is fine, but don't go overboard.
  - Clean well-documented, commented code.
  - [When it makes sense](#adding-utils), external libraries are used and exposed instead of writing new code. 
  - Focus on node.js usage and projects that are likely to use a number of these utils in one project. If you only need one or two of these in a small project, don't use this. Use small modules that do only one thing.

## Related projects
> This project depends on these great libraries. If you don't need a full utility belt for your project, any of these can be used by themselves:

{%= related(Object.keys(dependencies)) %}

## Author
{%= include("author") %}

## License
{%= copyright() %}
{%= license() %}

***

{%= include("footer") %}