# Rates

### Install

```
yarn add q3-schema-rates
```

### Usage

#### Schema

For most applications, just the name and value properties will suffice. For those with more complex requirements, we provide an easy way to implement geographic and tiered rate decks.

| Property      | Description                                                                           | Type             |
| ------------- | ------------------------------------------------------------------------------------- | ---------------- |
| `name`        | The user-friendly identifier for the rate                                             | `string`         |
| `description` | The purpose/context of the rate value                                                 | `string`         |
| `value`       | The numeric value                                                                     | `number`         |
| `label`       | A group/shared rate deck                                                              | `string`         |
| `regions`     | A set of geographical regions for which the rate applies                              | `array [string]` |
| `threshold`   | An equation for qualifying the rate. It must start with "==", ">", "<", "<=" or ">=". | `string`         |

#### Methods

The Rate schema ships with only one method - a helper function for evaluating threshold values.

| Name             | Description                               | Parameters      | Returns   |
| ---------------- | ----------------------------------------- | --------------- | --------- |
| `meetsThreshold` | Evaluates the stored threshold expression | `string/number` | `boolean` |

#### Statics

The Rate schema also includes a few static decorators for querying rates that satisfy multiple threshold values.

| Name                           | Description                                             | Parameters       | Returns  |
| ------------------------------ | ------------------------------------------------------- | ---------------- | -------- |
| `findAndReduceByThresholdAsc`  | Will find lowest matching value in the rate collection  | `object, number` | `number` |
| `findAndReduceByThresholdDesc` | Will find highest matching value in the rate collection | `object, number` | `number` |

### Example

```javascript
const Rate = require('q3-schema-rates');
const mongoose = require('mongoose');

const Model = mongoose.model('rates', Rate);

const sample = new Model({
    name: 'Example',
    threshold: '>10'
    value: 12,
});

sample.meetsThreshold(5); // returns false
sample.meetsThreshold(11); // returns true
```