# morx

> Simple param extractor and validation util.

Latest version **0.0.5** (published 2016-12-08) · ISC license · 0 weekly downloads

## Install

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

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.5 |
| Published | 2016-12-08 |
| First published | 2016-09-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 (+4 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 6 |
| Author | 4y0 |
| Maintainers | 4y0 |
| Keywords | validator, validation, api-spec, morx |

## Links

- npm: https://www.npmjs.com/package/morx
- Repository: https://github.com/4y0/morx
- Homepage: https://github.com/4y0/morx#readme
- Issues: https://github.com/4y0/morx/issues
- npm.io page: https://npm.io/package/morx

## Dependencies (2)

- [mosc](https://npm.io/package/mosc.md) 1.0.0
- [validator](https://npm.io/package/validator.md) 5.7.0

## Alternatives

- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads

## Recent versions

- 0.0.5 (latest) — 2016-12-08
- 0.0.4 — 2016-11-21
- 0.0.3 — 2016-10-19
- 0.0.2 — 2016-10-02
- 0.0.1 — 2016-09-13
- 0.0.0 — 2016-09-12

## README

# MORX. A simple util for validation and parameter transformation

## How to use

### Install morx
`npm install morx`

### Basic Usage
```
var morx = require('morx');
var spec = morx.spec() //Begin spec-ing parameters
           .build('id', 'required:true, map:user_id')
           .build('username', 'required:true')
           .end(); //End parameter spec-ing

//Call validation
var validated = morx.validate({id:23, username:'demio9009'}, spec);
console.log(validated);
/*
{
    no_errors:true,
    error_messages:"",
    params:{
        'user_id':23,
        'username':'demio9009'
    },
    excluded_params:{},
    failed_params:[]
}
*/
```

### Using validators and filters
```
var morx = require('morx');
var spec = morx.spec() //Begin spec-ing parameters
           .build('id', 'required:true, validators:isInt, map:user_id')
           .build('username', 'required:true, validators:isAlphanumeric.isAscii, filters:toUpper')
           .end(); //End parameter spec-ing

//Call validation
var validated = morx.validate({id:23, username:'demio9009'}, spec);
console.log(validated);
/*
{
    no_errors:true,
    error_messages:"",
    params:{
        'user_id':23,
        'username':'DEMIO9009'
    },
    failed_params:[]
}
*/
```

### Spec-ing with morx
```
spec = {
    'paramTovalidate':ValidationExtractionAndTransformationRules
}
```
`paramToValidate` - The key / name of the parameter to apply the ObjectValidationRequirements to. E.g. `id` , `username` e.t.c. If you passing an array as your Parameter source, valid values for `paramToValidate` include 0,1 e.t.c.

`ValidationExtractionAndTransformationRules` - Key/value pair of a list of rules to use for validating, extracting and transforming `paramToValidate` as found in the parameter source. It has the following properties:

* `required` : (boolean `True` or `False`) indicates whether or not `paramToValidate` is required. Internally morx checks to see if `paramToValidate` is `undefined` or `""`
* `map` : If present, indicates the key `paramToValidate` should be returned with. Without `map`, `id` will be returned as `id`. With map (`map:user_id`), `id` will be returned as `user_id` (see example under basic usage)
* `validators`: A dot separated list of validators to apply to `paramToValidate`. Internally, morx uses the [validator](https://www.npmjs.com/package/validator) package on npm to validate parameter values. A list of supported validators can be found [here](https://www.npmjs.com/package/validator#validators). 
* `filters` : A dot separated list of filters / sanitizers to apply to `paramToValidate`. All filters with the exception of `toUpper` and `toLower` are the same as those provided by the validator package. A list can be found [here](https://www.npmjs.com/package/validator#sanitizers). 
* `not_param` : A boolean value indicated wether the `paramToValidate` should be returned as part of the extracted params. Useful for cases when a parm is required but not needed for functional operations. 

Parameter specs can be created either using object literals or morx's inbuilt spec-er:
```
var paramSpec = morx.spec() //Begin spec-ing parameters
    .build('id', 'required:true, map:user_id')
    .build('username', 'required:true')
    .end(); //End parameter spec-ing
/*
paramSpec is the same as the object literal:
{
    id:{
        required:true,
        map:'user_id'
    },
    username:{
        required:true,
    }
}
*/
```

### validating with morx

The morx validator takes three arguments, the first two are required.  
`var validated = morx.validate(ParameterSource, ParameterSpec, validationOptions)`

* `ParameterSource` - The object / array source to validate the ParameterSpec against i.e The parameters defined in the spec will be looked up in the parameter source. In a function, the `arguments` array-like object is a valid parameter source. In a web app / api, the req.body, req.params, req.query objects are all valid parameter sources. (When using `arguments`, an interesting usecase could be to use the `map` spec property to transform arguments passed to a function into an object)
* `ParameterSpec` - The spec definition with which to validate and extract values from the parameter source. See specing with morx for a more detailed explanation. The spec also precludes needless parameters from filtering into your apps. In cases of APIs / web projects where req.body / req.query could contain a number of properties, spec-ing ensures only what's needed by a function / service / endpoint is extracted
* `ValidationOptions` - The options that define the way morx handles validation success or faliure. By default, morx will not fail until all parameters defined in the spec requirements have been checked - even if one of the requirements of a spec is not met. It will return all failed params as well as error messages. With `ValidationOptions` we can fine-tune this behavior. There are three main properties:
    * `fail_on_first_error` - If this is set to true, morx will fail (i.e return to the calling function) at the first occurence of a validation error
    * `throw_error` - If this is set to true, instead of returning a well formed object, morx will throw an error with the validation error messages
    * `throw_error_on_first_fail` - Similar to `fail_on_first_error` but instead of returning, an error with the validation error message is thrown.

### Auto-test generation with [morx-cha](https://www.npmjs.com/package/morx-cha)

To use morx with [morx-cha](https://www.npmjs.com/package/morx-cha), the additional spec properties are required

* `eg` - Example value for the parameter
* `eg_specialcase` - Example special case value for the parameter, e.g. eg_invalid_email or eg_exists e.t.c. _This is yet to be implemented_

See example [here](https://github.com/4y0/morxcha/tree/master/examples)

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