Agnese -   

Agnese is an object mapper that allows you to transform an object (or array) into another one with different structure.

The target is to completely remove or a least separate and organize the mapping code from our projects making it easy to maintain. In order to achieve this mission, Agnese makes possible to define the new structure in a JSON/YAML file and using directly there simple conditions and arithmetic operations with Quara, a tiny JavaScript interpreted language.

For more complex needs, you can create your own preprocessors and point to them with different arguments to treat any data you want.

Table of Contents

- Features
- Installation
- Getting started
- Simple mapping example
- Autocompletion
- JSON
- YAML
- Easy CSV generation
- License

Features

- Convert source data to objects, arrays, strings or simple data based on mapping configuration.
- Read mapping configuration from JSON file.
- Conditional fields/items powered by Quara*.
- Array iteration.
- Possibility of define a default value for a field.
- Assign values by their paths in source data.
- Force types and casting.
- Use of custom functions to preprocess values before assign them.
- Values from conditional path (switch).
- YAML optional support.

> *Quara is a simple JavaScript interpreted language that will be available soon as a separate module.

Installation

Agnese is available as an NPM package:

``bash
npm install agnese
`

If you prefer download it from Github Packages (take a look at the documentation):

`bash
npm install @wandeber/agnese
`

Getting started

We will use the next source data in the examples throughout this document:

`javascript
const sourceData = {
name: "Gohan",
surname: "Son",
isAlive: true,
isDeath: false,
alias: [
"Great Saiyaman",
"The Golden Fighter",
"The Golden Warrior",
"The Chosen One",
"Monkey boy"
],
characteristics: {
race: "Human/Saiyan",
gender: "Male",
age: "10",
height: 176.5,
weight: 61
},
transformations: [
{
name: "Super Saiyan",
power: "Uff...",
level: 1
},
{
name: "Super Saiyan II",
power: "Ask Cell... (De locos...)",
level: 2
}
]
};
`

#### Simple mapping example:

One of the most awesome things about this module is you can keep all your mapping info in a separate JSON file.

##### map-info.json

`json
{
"type": "Object",
"fields": [
{
"name": "lastname",
"if": {
"quara": "surname == \"Son\""
},
"value": {
"fromPath": "surname"
}
}
]
}
`

##### JavaScript code to map from JSON file

`javascript
let mapper = new Agnese();
mapper.setMapInfo("map-info.json");
let target = mapper.map(sourceData);
`

The variable target will contain the next object:

`js
{
lastname: "Son"
}
`

Since the code is almost completely common to any case of use, sometimes you will only find the map info or settings in future examples of this document.

> While I complete this documentation, I recommend you take a look at the examples used in the unit tests.

$3

Agnese provides JSON schemas that you can use with VSCode to enable autocompletion and validation.

#### JSON

`json
{
"$schema": "node_modules/agnese/schema/index.json",
"value": {
"type": "Integer",
"fromPath": "characteristics.age"
}
}
`

#### YAML

You need to install the YAML extension.

`yaml


yaml-language-server: $schema=node_modules/agnese/schema/index.json


type: Object
fields:
- name: parent
value:
default: Son Goku
``

Easy CSV generation

If you think on CSV as an object with one unique level, you can easily map any data to CSV or other similar structure.

License

Agnese © 2020 by Bernardo A. Siverio (wandeber) is licensed under CC BY-ND 4.0