npm package: @relayin/component-formula-parser
Description: Parses the formula string passed to payroll components
Author: virk,relayin
Latest version: 1.0.0

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of contents

- [Component Formula Parser](#component-formula-parser)
  - [Installation](#installation)
  - [Usage](#usage)
  - [Valid Expressions](#valid-expressions)
  - [Invalid Expressions](#invalid-expressions)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Component Formula Parser
> Parses the components formula expression

[![circleci-image]][circleci-url] [![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]

Platform agnostic library to parse the formula expression into a parsed object. It allows a narrow subset of expressions and more can be added on demand.

The Payroll components of Relay allows defining a formula that can apply a percentage on the sum of one of more components. For example:

```
12% of (BASIC + HRA)
```

is represented as

```
12 * (#<id-of-basic> + #<id-of-hra>)
```

This library parses the given expression into the following object.

```js
{
  "value": 12,
  "operator": "MULTIPLY",
  "components": ['id-of-basic', 'id-of-hra']
}
```

Since, `addition` is the only allowed expression between multiple components. We return a flat array of component ids. Once we will introduce other expressions like `multiple`, `divison`, then we will have to convert this array into a tree.

Allowing expressions like `multiple` and `divison` are not that simple, since they need to be translated into the UI as well and we are not sure, if we will ever do that or not.

## Installation
Install the package from npm registry as follows:

```sh
npm i @relayin/component-formula-parser
```

## Usage
```ts
import { parse } from '@relayin/component-formula-parser'
const output = parse('12 * (#1 + #2)')
```

Output

```json
{
  "errors": [],
  "parsed": {
    "operator": "MULTIPLY",
    "value": 12,
    "components": [
      "1",
      "2"
    ]
  }
}
```

## Valid Expressions
- `12 * (#1 + #2)`
- `(#1 + #2) * 12`
- `12*(#1+#2)`
- `12 * (#1+#2) + 20 + 80`: Here the addition of `20` + `80` are ignored. We don't allow literal values.
- `12 * (#1 + 10 + #2)`: Here the `addition` of `10` is ignore. We don't allow literal values.
- `0 * (#1 + #2)`

## Invalid Expressions
- `12(#1+#2)`: The operator is missing
- `*(#1+#2)`: The value is missing
- `0 * (#1 #2)`: Additional operator between two components is missing.

[circleci-image]: https://img.shields.io/circleci/project/github/RelayIN/component-formula-parser/master.svg?style=for-the-badge&logo=circleci
[circleci-url]: https://circleci.com/gh/RelayIN/component-formula-parser "circleci"

[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
[typescript-url]:  "typescript"

[npm-image]: https://img.shields.io/npm/v/@relay/component-formula-parser.svg?style=for-the-badge&logo=npm
[npm-url]: https://npmjs.org/package/@relay/component-formula-parser "npm"

[license-image]: https://img.shields.io/npm/l/@relay/component-formula-parser?color=blueviolet&style=for-the-badge
[license-url]: LICENSE.md "license"