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:

npm install agnese

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

npm install @wandeber/agnese

Getting started

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

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

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

JavaScript code to map from JSON file

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

The variable target will contain the next object:

{
  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.

Autocompletion

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

JSON

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

YAML

You need to install the YAML extension.

# 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