# agnese

> This project will help you to map data easily based on a configuration in JSON/YAML.

Latest version **0.6.5** (published 2025-11-16) · CC BY-ND 4.0 license · 0 weekly downloads

## Install

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

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.6.5 |
| Published | 2025-11-16 |
| First published | 2021-05-24 |
| Weekly downloads | 0 |
| License | CC BY-ND 4.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.17.1 |
| Dependencies | 1 |
| Unpacked size | 126.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Bernardo A. Siverio [wandeber] |
| Maintainers | wandeber |
| Keywords | map, map data, mapper, mapping, mappings, data mapper, data-mapper, object mapper, object-mapper, map array, loop, conditions, conditional, if, iterate, array, json, yaml, yml, schema, open, open source, agnese |

## Links

- npm: https://www.npmjs.com/package/agnese
- Repository: https://github.com/wandeber/agnese
- Issues: https://github.com/wandeber/agnese/issues
- npm.io page: https://npm.io/package/agnese

## Dependencies (1)

- [quara](https://npm.io/package/quara.md) ^0.10.12

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.6.5 (latest) — 2025-11-16
- 0.6.4 — 2025-11-11
- 0.6.4-alpha — 2025-11-11
- 0.6.3 — 2024-03-13
- 0.6.2 — 2024-03-13
- 0.5.5 — 2022-09-02
- 0.5.4 — 2022-09-02
- 0.5.3 — 2022-09-02
- 0.5.2 — 2022-07-13
- 0.4.0 — 2022-07-12
- 0.3.1 — 2022-07-02
- 0.3.0 — 2021-06-01
- 0.2.1 — 2021-05-27
- 0.2.0 — 2021-05-27
- 0.1.0 — 2021-05-26
- … 3 more at https://npm.io/package/agnese/versions

## README

# [Agnese](https://www.npmjs.com/package/agnese) - [![GitHub license](https://img.shields.io/badge/license-CC_BY--ND_4.0-blue.svg)](https://github.com/wandeber/agnese?tab=License-1-ov-file#readme) [![Version](https://img.shields.io/github/package-json/v/wandeber/agnese)](https://www.npmjs.com/package/agnese) [![size](https://img.shields.io/bundlephobia/min/agnese)](https://www.npmjs.com/package/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](#features)
- [Installation](#installation)
- [Getting started](#getting-started)
  - [Simple mapping example](#simple-mapping-example)
  - [Autocompletion](#autocompletion)
    - [JSON](#json)
    - [YAML](#yaml)
- [Easy CSV generation](#easy-csv-generation)
- [License](#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](https://www.npmjs.com/package/agnese) package:

```bash
npm install agnese
```

If you prefer download it from [Github Packages](https://github.com/wandeber/agnese/packages/807391) (take a look at the [documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#installing-a-package)):

```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](test/MapInfoFiles).

### Autocompletion

Agnese provides [JSON schemas](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](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-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)](https://github.com/wandeber) is licensed under [CC BY-ND 4.0](https://github.com/wandeber/agnese?tab=License-1-ov-file#readme)

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