Hertzbel, JavaScript's First Frequency and Decibel Conversion Library
Tags: javascript, npm, frequency, decibel
Published: 2020-08-21 15:21:31


A few weeks ago, my company started working on a new project for the satellite communications market. While I looked over user stories and tech requirements, I realized that there were no useful JavaScript libraries built to handle frequency conversions or decibel calculations.

I quickly set out to make an all-in-one library that my company, my industry, and general users can call from to handle all those tricky (and sometimes painful) decibel and frequency calculations. Thus I present Hertzbel, JavaScript's first frequency, and decibel conversion library.

{% github Awmages/hertzbel %}

## Hertz

Hertzbel can take a frequency string and convert it to another frequency, add two frequencies together, subtract frequencies, multiply frequencies with integers, and divide with integers.

### Frequency Conversion
Translate any frequency from Hz, kHz, MHz, GHz, THz to another.

#### note that values entered must be strings or numbers. Numbers will be considered to be in Hz base units.

#### Example 1 `toMegaHz({string | number})`
``` javascript
import {toMegaHz} from "hertzbel";
toMegaHz("1 GHz");
-> "1000.000000 MHz"
```
A couple of things to take note of here:
* toMegaHz can accept any combination of "1 GHz" (e.g., "1ghz", "1GHz", "1  GHZ  ")
* Depending on the to function, values will always show to Hz.
* the ToHz functions series can be strung together to work with other hertzbel calculations.

#### Example 2 `toTeraHz({string | number})`
``` javascript
import {toTeraHz} from "hertzbel";
toTeraHz("101 MHz");
-> "0.000101000000 THz"
```
In this example, I went to an extreme only to convey how cleanly hertzbel handles frequency conversions.

The complete list of toHz functions is:
* ToHz()
* ToKiloHz()
* ToMegaHz()
* ToGigaHz()
* ToTeraHz()

### Frequency Addition
Add any two frequencies together. The leading parameter will determine the resulting units.

#### note that values entered must be strings or numbers. Numbers will be considered to be in Hz base units.

#### Example 1 `addFreq({string | number}, {string | number})`
``` javascript
import {addFreq} from "hertzbel";
addFreq("10khZ", 1001);
-> "11.001 kHz"
```
* As mentioned before, hertzbel will handle any frequency string as long as it has the right spelling.
* Using a number will force hertzbel to assume it is in Hz
* Note the returned value gives values down to the Hz

### Example 2 `addFreq({string | number}, {string | number})`
``` javascript
import {addFreq} from "hertzbel";
addFreq("10 MHz", "1 GHz");
-> "1010.000000 MHz"
```

### Frequency Subtraction
Subtracts one frequency from another. The leading parameter will determine the resulting units.

### Example `subFreq({string | number}, {string | number})`
``` javascript
import {subFreq} from "hertzbel";
subFreq("10760 MHz", "1500 MHz");
-> "9260.000000 MHz"
```

### Frequency Multiplication
Multiples a frequency against an integer

### Example `multFreq({string | number}, {number})`
``` javascript
import {multFreq} from "hertzbel";
multFreq("500 Hz", 50);
-> "25000 Hz"
```

### Frequency Division
Divides a frequency against an integer

### Example `divFreq({string | number}, {number})`
``` javascript
import {divFreq} from "hertzbel";
divFreq("3000 MHz", 401)
-> "7.481297 MHz"
```

### Stringing Frequency Functions
Hertzbel allows users to string frequency functions.

### Example 1
User wants to divide 3000 MHz by 601 then convert that value to kHz
``` javascript
import {toKiloHz, divFreq} from "hertzbel";
toKiloHz(divFreq("3000 MHz", 601));
-> "4991.681 kHz"
```
### Example 2
User wants to add three frequencies together: 100 kHz, 250 kHz, and 450 kHz.
``` javascript
import {addFreq} from "hertzbel";
addFreq(addFreq("100 kHz", "250 kHz"), "450 kHz"))
-> "800.000 kHz"
```

## Decibel

The second piece of the hertzbel library is decibel conversion. RF, satcom, and other types of engineers have to convert power from Watts to decibels and back periodically.

Hertzbel offers a simple way to perform dB conversions (though it is limited to Watts currently).

### From Watts to Decibels
Translates values from any Watt to any decibel. Users may enter a string or number as parameters into the function. Numbers will be considered to be in mW.

### Example 1 `toDbm({string | number})`
``` javascript
import {toDbm} from "hertzbel";
toDbm("20 mw");
-> "13 dBm"
```
### Example 2 `toDbuw({string | number})`
``` javascript
import {toDbuw} from "hertzbel";
toDbuw("1W";
-> "60 dBuW"
```
The complete list of toDb is:
* toDbuw()
* toDbm()
* toDbW()

### From Decibels to Watts
Converts values of any decibel to any Watt. Users must use a string.

### Example 1 `toW({string})`
``` javascript
import {toW} from "hertzbel";
toW("40 dbuw");
-> "0.01 W"
```

### Example 2 `toMw({string})`
``` javascript
import {toMw} from "hertzbel";
toMw("-3 dbm");
-> "0.5011 mW"
```

The complete list of toW is:
* toUw()
* toMw()
* toW()

## Download
Try out hertzbel instantly in your JavaScript app, just download with `npm add hertzbel` or `yarn add hertzbel` and start making something. View the npm library here [hertzbel](https://www.npmjs.com/package/hertzbel).


## Conclusion
As a member of the Satcom community, I sincerely hope more libraries like hertzbel will appear in the open source ecosystem for newer languages.

The JavaScript language is very conducive to writing fast code; it is widely supported, and extremely easy to configure. I, for one, feel like its time to start pushing Satcom software in a new direction, and hopefully, hertzbel will help start the transition.