# phojs

> Declarative configuration framework

Latest version **0.1.6** (published 2023-01-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install phojs
pnpm add phojs
yarn add phojs
bun add phojs
```

Provides the command `pho`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.6 |
| Published | 2023-01-01 |
| First published | 2022-07-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 46.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | phojs |

## Links

- npm: https://www.npmjs.com/package/phojs
- npm.io page: https://npm.io/package/phojs

## Dependencies (4)

- [fdir](https://npm.io/package/fdir.md) ^5.3.0
- [debug](https://npm.io/package/debug.md) ^4.3.4
- [yargs](https://npm.io/package/yargs.md) ^17.3.1
- [graph-data-structure](https://npm.io/package/graph-data-structure.md) ^2.0.0

## Recent versions

- 0.1.6 (latest) — 2023-01-01
- 0.1.4 — 2023-01-01
- 0.1.3 — 2022-12-01
- 0.1.1 — 2022-09-18
- 0.1.0 — 2022-07-27

## README

<div align="center">

![phojs logo](https://user-images.githubusercontent.com/2085411/181236639-0d528c9a-141d-47c4-94a7-eef5677eb836.png)
# Phở
### <i>The super-tasty configuration framework</i>

Allows you to define configuration declaratively together with supercharged validation and flexability.
  
Inspired by the popular python libraries [flag](https://abseil.io/docs/python/guides/flags), and [cerberus](https://github.com/pyeve/cerberus).

</div>


## Installation

```shell
# Using NPM
npm install phojs

# If you fancy yarn
yarn add phojs
```

## Examples

#### Basic

```javascript
const pho = require('phojs')

pho.create(async (root) => {
  root.field('firstname', 'string', 'Your first name').required()
  root.field('lastname', 'string', 'Your last name').required()
  root.field('nickname', 'string', 'Your nickname')
    .required()
    .oneOf('Neo', 'Morpheus', 'Trinity')
  root.field('age', 'number', 'Your age')

  root.category('measurements', 'Body Measurements', (measurements) => {
    measurements.field('height', 'number', 'Your height in centimeters')
    measurements.field('weight', 'number', 'Your weight in kilograms')
  })
})

const validatedConfig = pho.parse({
  firstname: 'Kaladin',
  lastname: 'Stormblessed',
  nickname: 'Neo',
  measurements: {
    height: 170,
    weight: 70,
  },
})
```

#### Field Dependencies

Fields can have validators and modifiers attached to them. 
pho provides some basic ones, but you can write your own of course :)

These validators/modifiers can depend on other fields to in order to work, so they we will called with their dependencies are arguments.
_Note_:
Modifiers are run before validators.

```javascript
const {pho, FieldValidationError} = require('phojs')

pho.create((root) => {
  root.field('first', 'number', 'First number').required()
  root.field('second', 'number', 'Second number').required()

  root.category('calculations', 'Calculation results', (calculations) => {
    calculations
      .field('sum', 'number', 'Sum of first and second')
      .modify('sum', (field, value, first, second) => first + second, ['first', 'second']) // sum field needs both first and second to make sense
      .validate('ensure upper bound', (field, value) => {
        if (value > 1000){
          throw new FieldValidationError(`Sum is too big (value=${value})`)
        }
      })
  })

  root.category('statistics', 'Number statistics', (stats) => {
    stats.field('avg', 'number', 'average of the first and second')
      .modify('avg', (field, value, sum) => sum / 2, ['calculations.sum'])
    })
  })
})


const result = pho.parse({
  first: 10,
  second: 20,
})

// result will be
// {
//   first: 10,
//   second: 20,
//   calculations: {
//     sum: 20 + 10,
//   },
//   statistics: {
//     avg: (20 + 10) / 2,
//   },
// }
```

## Testing

```
# Clone the repo

# install dependencies
$ npm install

# or
$ yarn

# run tests
$ yarn test
```

---
_Source: https://npm.io/package/phojs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._