unit-compare
Version:
Compare byte and datetime units
222 lines (155 loc) • 5.13 kB
Markdown
# unit-compare
[](https://travis-ci.org/nspragg/unit-compare) [](https://coveralls.io/github/nspragg/unit-compare?branch=master)
> Compare date/time and byte units
* [Installation](#installation)
* [Features](#features)
* [Demo](#demo)
* [Usage](#usage)
* [API](#api)
* [Instance methods](#instance-methods)
* [Test](#test)
* [Contributing](#contributing)
## Installation
```
npm install --save unit-compare
```
## Features
* Compares bytes sizes
* Compares ISO datetimes
## Usage
The example below asserts if a number if less then 10 megabytes:
```js
const compare = require('unit-compare');
const n = 1024;
const isLessThen10Mb = compare.isNumber(n).assert('<10mb')
if (isLessThen10Mb) {
console.log(`${n} is less than 10mb`);
}
```
#### Byte unit comparisons
Assert if a given number against a string byte size expression:
```js
const greaterThan10kb = compare.isNumber(n).assert('>10kb')
```
Using comparison methods directly:
```js
const greaterThan10kb = compare.isNumber(n).lessThan(10, 'k');
```
#### Compare dates with a string expression
Assert if a given number against a string datetime expression:
```js
const date = moment();
const equalTo10Mins = compare.isDate(date).assert('>10 minutes');
```
Using comparison methods directly:
```js
const date = moment().subtract(10, 'minutes');
const greaterThan10kb = compare.isDate(date).lessThan(10, 'days');
```
## API
### `compare.isDate() -> DateAssertion`
##### Parameters
* ISO string date
##### Returns
Returns an DateAssertion instance.
### `compare.isNumber() -> ByteAssertion`
##### Parameters
* Accepts an integer
##### Returns
Returns a ByteAssertion instance.
## ByteAssertion
### `.assert(sizeExpression) -> boolean`
##### Parameters
* sizeExpression - accepts a positive integer representing the file size. File size units are:
* bytes, specified using __b__.
* kilobytes, specified using __k__ or __kb__,
* megabytes, specified using __m__ or __mb__
* terabytes, specified using __t__ or __tb__
* gigabytes, specified using __g__ or __gb__
If no unit is specified, __bytes__ is used by default.
Optionally, expressions can be prefixed with a comparison operator, including:
* less than using __<__
* greater than using __>__
* equality using __==__ or __=__
* less than or equal to using __<=__
* greater than or equal to __\>=__
Examples:
* equal to 10 bytes: __10__
* equal to 10 bytes: __==10b__
* less than 10 bytes: __<10__
* greater than 50 megabytes: __>10mg__
### `.lessThan(int, unit) -> boolean`
##### Parameters
* integer
* unit - k, m, g, t
### `.greaterThan(int, unit) -> boolean`
##### Parameters
* integer
* unit - k, m, g, t
### `.equalTo(int, unit) -> boolean`
##### Parameters
* integer
* unit - k, m, g, t
### `.greaterThanOrEqual(int, unit) -> boolean`
##### Parameters
* integer
* unit - k, m, g, t
### `.lessThanOrEqual(int, unit) -> boolean`
##### Parameters
* integer
* unit - k, m, g, t
## DateAssertion
##### Parameters
* dateExpression - accepts a time unit. Time units are:
* minutes, specified using __minutes__, __m__, __mins__, __min__.
* hours, specified using __hours__, __h__, __hour__.
* days, specified using __days__, __d__, __day__.
If no unit is specified, __days__ is used by default.
Optionally, expressions can be prefixed with a comparison operator, including:
* less than using __<__
* greater than using __>__
* equality using __==__ or __=__
If no comparison operator is specified, equality is used by default.
Examples:
* equal to 10 days: __10__
* equal to 10 minutes: __== minutes__
* less than 10 hours: __< 10 hours__
* greater than 50 minutes: __>50minutes__
* less than 50 minutes: __<50m__
##### Returns
* Returns boolean
### `.lessThan(int, timeUnit) -> boolean`
##### Parameters
* integer
* timeUnit - minutes, hours, days
### `.greaterThan(int, timeUnit) -> boolean`
##### Parameters
* integer
* timeUnit - minutes, hours, days
### `.equalTo(int, timeUnit) -> boolean`
##### Parameters
* integer
* timeUnit - minutes, hours, days
### `.greaterThanOrEqual(int, timeUnit) -> boolean`
##### Parameters
* integer
* timeUnit - minutes, hours, days
### `.lessThanOrEqual(int, timeUnit) -> boolean`
##### Parameters
* integer
* timeUnit - minutes, hours, days
## Test
```
npm test
```
To generate a test coverage report:
```
npm run coverage
```
## Contributing
* If you're unsure if a feature would make a good addition, you can always [create an issue](https://github.com/nspragg/unit-compare/issues/new) first.
* We aim for 100% test coverage. Please write tests for any new functionality or changes.
* Any API changes should be fully documented.
* Make sure your code meets our linting standards. Run `npm run lint` to check your code.
* Maintain the existing coding style. There are some settings in `.jsbeautifyrc` to help.
* Be mindful of others when making suggestions and/or code reviewing.