# @mokd/parz

> A simple utility for parsing and validation of values.

Latest version **0.0.8** (published 2022-10-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install @mokd/parz
pnpm add @mokd/parz
yarn add @mokd/parz
bun add @mokd/parz
```

## Health

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

Positive: has types; no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.8 |
| Published | 2022-10-14 |
| First published | 2022-10-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 12 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | mokd |
| Maintainers | mokd |

## Links

- npm: https://www.npmjs.com/package/@mokd/parz
- Homepage: https://github.com/mokd/parz
- npm.io page: https://npm.io/package/@mokd/parz

## Recent versions

- 0.0.8 (latest) — 2022-10-14
- 0.0.7 — 2022-10-14
- 0.0.6 — 2022-10-14
- 0.0.5 — 2022-10-14
- 0.0.4 — 2022-10-11
- 0.0.3 — 2022-10-10
- 0.0.2 — 2022-10-10
- 0.0.1 — 2022-10-10

## README

# Parz

A simple utility for parsing and validating values. The motivation behind is stateless validaton of html input fields.

You can chain multiple validators and parsers with `then`. If a validator fails, it will keep on validating and return the results for all validators. If a parser fails, it will stop and return all the errors up to that point.

## Usage

Start by creating a validator. `createValidator` expects two functions, one for validation `T -> boolean`, and one for error handling `T -> NonEmptyArray<string>`.  

```ts
import { createValidator } from '@mokd/parz'

const stringOfLength5 = createValidator(
    (str : string) => str.length === 5,
    (str) => [`String is not length 5, it is actually of length ${str.length}`]
)
```

Once you have a validator, you can do this:

```ts
import { startWith, isJust } from '@mokd/parz'

const validationResult = startWith("Hello")
    .then(stringOfLength5)
    .value()

if (isJust(validationResult)) {
    console.log(validationResult.target) // target is string
}
```

Sometimes, we also want to parse/transform. `createParser` takes two functions, one `TOriginal -> TParsed`, and one `TOriginal -> NonEmptyArray<string>`. To indicate parsing failure, you **must** return `null` on failure. If not, you'll have undefined behaviour.

```ts
import { createParser } from '@mokd/parz'

const stringToInteger = createParser(
    (str : string) => {
        const res = parseInt(str)
        if (isNaN(res)) return null;
        return res;
    }, 
    (str) => [`${str} cannot be parsed to an integer`]
)
```

Parsers and validators can be composed:

```ts
const onesAndThenZeros = createValidator(
    (str : string) => RegExp(/^10+$/).test(str), 
    (str) => [`${str} must start with a one and end with one or more zeroes`]
)

const stringToInteger = createParser(
    (str : string) => {
        const res = parseInt(str)
        if (isNaN(res)) return null;
        return res;
    }, 
    (str) => [`${str} cannot be parsed to an integer`]
)

const atLeastOneThousand = createValidator(
    (n : number) => n > 1000, 
    (n) => [`${n} must be at least 1000`]
)

const fn = (oneAndZeroes : string) => startWith(oneAndZeroes)
        .then(onesAndThenZeros)
        .then(stringToInteger)
        .then(atLeastOneThousand)
        .value() 
        
const successResult = fn("10000") 

if (isJust(successResult)) {
    console.log(successResult.target) // target is number
    console.log(successResult.original) // original is string
}

const failResult = fn("100")

if (isJust(failResult)) {
    console.log(failResult.errors) // errors is string[], as specified in the second type parameter of startWith
    console.log(failResult.original) // original is string
}
```

Example for composite values. `deflate` accepts a `Record<string, ParzRes<unknown, unknown>>`, and returns an object with `mapDeflated`, which lets you operate on the `ParzOK` target values, if and only if all values in the record evaluate to `ParzOk`. The `mapDeflated` function returns a `ParzRes`, which lets you compose additional validators and parsers.

```ts

const length = startWith("10").then(stringToInteger).value()
const width = startWith("10").then(stringToInteger).value()
const height = startWith("10").then(stringToInteger).value()

const maybeVolume = deflate({length, width, height}).mapDeflated(x => x.length*x.width*x.height).value()

if (isJust(maybeVolume)) {
    console.log(maybeVolume.target) // value is number
}

```

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