timestring/README.md

# Timestring

[![Version](https://img.shields.io/npm/v/timestring.svg?style=flat-square)](https://www.npmjs.com/package/timestring)
[![Build Status](https://img.shields.io/travis/mike182uk/timestring.svg?style=flat-square)](http://travis-ci.org/mike182uk/timestring)
[![Code Climate](https://img.shields.io/codeclimate/github/mike182uk/timestring.svg?style=flat-square)](https://codeclimate.com/github/mike182uk/timestring)
[![Coveralls](https://img.shields.io/coveralls/mike182uk/timestring/master.svg?style=flat-square)](https://coveralls.io/r/mike182uk/timestring)
[![npm](https://img.shields.io/npm/dm/timestring.svg?style=flat-square)](https://www.npmjs.com/package/timestring)
[![License](https://img.shields.io/github/license/mike182uk/timestring.svg?style=flat-square)](https://www.npmjs.com/package/timestring)

Parse a human readable time string into a time based value.

## Installation

```bash
npm install --save timestring
```

## Usage

### Overview

```js
var timestring = require('timestring');

var str = '1h 15m';
var time = timestring(str);

console.log(time); // will log 4500
```

**By default the returned time value from `timestring` will be in seconds.**

The time string can contain as many time groups as needed:

```js
var str = '1d 3h 25m 18s';
var time = timestring(str);

console.log(time); // will log 98718
```

and can be as messy as you like:

```js
var str = '1 d    3HOurS 25              min         1   8s';
var time = timestring(str);

console.log(time); // will log 98718
```

### Keywords

Timestring will parse the following keywords into time values:

1. `s, sec, secs, second, seconds` - will parse to seconds
2. `m, min, mins, minute, minutes` - will parse to minutes
3. `h, hr, hrs, hour, hours` - will parse to hours
4. `d, day, days` - will parse to days
5. `w, week, weeks` - will parse to weeks
6. `mth, mths, month, months` - will parse to months
7. `y, yr, yrs, year, years` - will parse to years

Keywords can be used interchangeably:

```js
var str = '1day 15h 20minutes 15s';
var time = timestring(str);

console.log(time); // will log 141615
```

### Return Time Value

By default the return time value will be in seconds. This can be changed by passing one of the following strings as an argument to `timestring`:

1. `s` - Seconds
2. `m` - Minutes
3. `h` - Hours
4. `d` - Days
5. `w` - Weeks
6. `mth` - Months
7. `y` - Years

```js
var str = '22h 16m';

var hours = timestring(str, 'h'); // 22.266666666666666
var days = timestring(str, 'd'); // 0.9277777777777778
var weeks = timestring(str, 'w'); // 0.13253968253968254
```

### Optional Configuration

A few assumptions are made by default:

1. There are 24 hours per day
2. There are 7 days per week
3. There are 4 weeks per month
4. There are 12 months per year

These options can be changed by passing an options object as an argument to `timestring`.

The following options are configurable:

1. `hoursPerDay`
2. `daysPerWeek`
3. `weeksPerMonth`
4. `monthsPerYear`

```js
var str = '1d';
var opts = {
	hoursPerDay: 1
}

var time = timestring(str, 'h', opts);

console.log(time); // will log 1
```

In the example above `hoursPerDay` is being set to `1`. When the time string is being parsed, the return value is being specified as hours. Normally `1d` would parse to `24` hours (as by default there are 24 hours in a day) but because `hoursPerDay` has been set to `1`, `1d` will now only parse to `1` hour.

This would be useful for specific application needs.

*Example  - Employees of my company work 7.5 hours a day, and only work 5 days a week. In my time tracking app, when they type `1d` i want 7.5 hours to be tracked. When they type `1w` i want 5 days to be tracked etc.*

```js
var opts = {
	hoursPerDay: 7.5,
	daysPerWeek: 5
}

var hoursToday = timestring('1d', 'h', opts);
var daysThisWeek = timestring('1w', 'd', opts);

console.log(hoursToday); // will log 7.5
console.log(daysThisWeek); // will log 5
```