npm package: @lizmstanley/to-unit-decorator
Description: Typescript decorator for unit of measure conversions
Author: Liz Stanley
Latest version: 1.0.0

# to-unit-decorator 

Typescript decorators to convert between different units of measure. 
Two decorators are required for this, a method decorator and a parameter decorator.
Individual parameters can specify different unit conversions.

See https://www.typescriptlang.org/docs/handbook/decorators.html for more information
about decorators. Note the section on decorator factories, as that's how it's being
implemented here.

### @ConvertUnits method decorator
The way a method decorator works in Typescript is that it can alter the behavior
of the method by rewriting the method. In this case what we want to do is: for each 
decorated argument, convert its value and then execute the method with the converted values. 
This is very similar to how AOP works in Java, with annotations. 

A method decorator includes a property descriptor (the property being, the method itself). 
From there we can determine what arguments the method has, and manipulate their values. 

The implementation for this decorator is the ConvertUnits() function in `ConverterDecorators.ts`.

### @ToUnit parameter decorator
Parameter decorators are very different. They can't alter any values themselves. 
All they can do is detect that a parameter was decorated. 

Since there is no property descriptor for
this type of decorator, we don't have access to the parameter value. We have to extract the
info from the decorator (unit of measure that we're converting to, and optional precision), store
it in the decorator metadata, and then we can use that in the method decorator to convert the
incoming argument unit to the one specified by the parameter decorator. Arrays are used to line 
up the method argument with the correct parameter decorator. 

This all may seem a bit hacky, but it's the way the Typescript documentation says to do it. 
See https://www.typescriptlang.org/docs/handbook/decorators.html#parameter-decorators

The implementation for this decorator is the ToUnit() function in `ConverterDecorators.ts`.

### Usage 
Decorate a method with `@ConvertUnits()`, and one or more parameters of that method with `@ToUnit`.
The parameter decorator takes the following arguments:

 * unit: the unit of measure to convert the argument to, chosen from the UnitOfMeasure enum
 * precision: optional number of decimal places for the resulting value (default is 2)

Decorated parameters need to be of the MeasuredValue type, which includes the following attributes:

 * value: the numeric value to be converted, can be a number or a string 
 * unit: the unit of measure to convert the value from, chosen from the UnitOfMeasure enum
 * precision: optional number of decimal places, overriding the precision of the decorator

Example use, with val = `{unit: UnitOfMeasure.FEET, val: 10}` 

```
 @ConvertUnits()
 public myFunction(@ToUnit(UnitOfMeasure.METERS) val: MeasuredValue) {
    console.log(val.value); //val.value = 3.05, with default precision of 2	
 }
```

The decorator will automatically convert the argument's value 
from meters to feet. If the incoming value is already in the unit specified for 
@ToUnit, or no appropriate converter is found, the value will be left as is. 

See ConverterDecoratorsTest for more usage examples.

To add a new unit of measure:
 * Add a new entry in the UnitOfMeasure enum
 
To add a new converter:
 * Write new conversion functions (if none exist already for the conversion(s) needed) 
 conforming to the ConvertFunction interface.
 * Add an entry to the toConverters list, specifying the unit to
 convert to, and which conversion function(s) will convert to that
 unit  
 
 An example use case. We have a new requirement to store volume amounts
 as liters. Some of our data comes in as gallons. 
 
  * Add entries GALLON, LITER to the UnitOfMeasure enum
  * Write a new conversion function convertGallonsToLiters
  which implements the ConvertFunction interface (and a unit test for it)
  * Add a converter to the toUnitConverters, with 
    * toUnit: UnitOfMeasure.LITER
    * converters: a list entry with fromUnit = UnitOfMeasure.GALLON and 
    convertFunction = convertGallonsToLiters
  * Add a test method in the decorator unit test class, TestClass, called testLiters, 
 annotated with @ConvertUnits() at the method level, @ToUnit(UnitOfMeasure.LITER) for the parameter.
  * Create a test method following existing examples, and pass in a VolumeValue with liters, and another with gallons. 
  * Invoke the unit method and verify that the values set by the decorated method are correct.