0.5.5 • Public • Published

Agnese - GitHub license version size ci Coverage Status

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


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


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.

  "type": "Object",
  "fields": [
      "name": "lastname",
      "if": {
        "quara": "surname == \"Son\""
      "value": {
        "fromPath": "surname"
JavaScript code to map from JSON file
let mapper = new Agnese();
let target =;

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.


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


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


You need to install the YAML extension.

# yaml-language-server: $schema=node_modules/agnese/schema/index.json
type: Object
  - name: parent
      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.


MIT © Bernardo Alemán Siverio


npm i agnese

DownloadsWeekly Downloads






Unpacked Size

105 kB

Total Files


Last publish


  • wandeber