README.md

Morphism

Helps you to transform any object structure to another

Communication

• Twitter: @renaudin_yann
• GitHub Issues

Getting started

Install morphism using npm.

npm install --save morphism

Then require it into any module.

const Morphism = require('morphism'); 

Or using ES6 import style

import Morphism from 'morphism';

If you're using browserify, the morphism npm module also works from the browser.

What does it do?

Morphism uses a semantic configuration to go through the collection of graph objects you have to process. Then it extracts and computes the value from the specified path(s). Finally, it sets this value to the destination property from the schema.

Usage

Morphism is curried function that allows a partial application with a semantic configuration. You can use it in 2 ways:

As a Mapper factory

let mapping = { ... }
let collectionOfObjects = [ ... ]
let anotherCollection = [ ... ]

// produces a reusable mapper from the configuration
let myAwesomeMapper = Morphism(mapping);
myAwesomeMapper(collectionOfObjects);
myAwesomeMapper(anotherCollection);

As a Static instance

const Morphism = require('morphism'); 

let mapping = { ... }
let collectionOfObjects = [ ... ]

// extracts the data straight away 
let results = Morphism(mapping, collectionOfObjects);

Dataset sample

// We'll use this set of data all along the examples
let data = [{
                'firstName': 'John',
                'lastName': 'Smith',
                'address':
                {
                    'city': 'New York',
                    'country': 'USA'
                },
                'phoneNumber':
                    [
                        {
                            'type': 'home',
                            'number': '212 555-1234'
                        },
                        {
                            'type': 'fax',
                            'number': '646 555-4567'
                        }
                    ]
                }];

Simple mapping

let data = [ ... ];
let mapping = { 
                pseudo: 'firstName',
                lastName: 'lastName',
                city: 'address.city' // get a value from a deep path
               };

let results = Morphism(mapping, data);

// results[0]: {
//                 pseudo: 'John',
//                 lastName: 'Smith',
//                 city: 'New York'
//             }

Value transformation

let data = [ ... ];
let mapping = { 
                pseudo: 'firstName',
                lastName: 'lastName',
                city: {
                    path: 'address.city',
                    fn: (city) => city.toLowerCase() // compute a function on the specified path value
                },
                nbContacts: (object) => object.phoneNumber.length // compute a function on the iteratee object

               };

let mapper = Morphism(mapping);
let results = mapper(data);

// results[0]): {
//                 pseudo: 'John',
//                 lastName: 'Smith',
//                 city: 'new york',// <== toLowerCase
//                 nbContacts: 2 // <== computed from the object
//              }

Values Aggregation

let data = [ ... ];

let mapping = {
                user: ['firstName','lastName'] // aggregate the values to an object
                city: 'address.city'
               };

let results = Morphism(mapping, data);

// results[0]: {
//                 user: {
//                     'firstName': 'John',
//                     'lastName': 'Smith'
//                 },
//                 city: 'New York'
//             }

Mappers Registry

Morphism provides a powerful local registry where you can store your mappings' configuration by specifying a Type. The transformation sequences are stored as a function in a WeakMap to speed the processing.

Register a mapping configuration

class User {
    constructor(firstName, lastName, phoneNumber){
        this.firstName = firstName;
        this.lastName = lastName;
        this.phoneNumber = phoneNumber;
    }
}

let mapUser = Morphism.register(User, schema);

// Map using the registered type and the registry
Morphism.map(User, data)

// Or Map using the mapper reference
mapUser(data);

API

Register

Register a mapper for a specific type. The schema is optional.

Morphism.register(type, schema:{});

Map

Map a collection of objects to the specified type

Morphism.map(type, data:[]);

Get or Set an existing mapper configuration

Morphism.setMapper(type, schema:{});

Delete a registered mapper

Morphism.deleteMapper(type, schema:{});

License

MIT © Yann Renaudin