morphism

Morphism

In many fields of mathematics, morphism refers to a structure-preserving map from one mathematical structure to another. A morphism f with source X and target Y is written f : X → Y. Thus a morphism is represented by an arrow from its source to its target.

https://en.wikipedia.org/wiki/Morphism

Picture by @Gmulti

---

• Morphism
  • Getting started 🚀
  • What does it do? 🤔
  • Usage 🍔
    • Along with an ES6 Class
    • As a Mapper factory
    • As a Static instance
  • Mapping Schema Examples 💡
    • Dataset sample
    • Flattening and Projection
    • Computing over Flattening / Projection
    • Values Aggregation
    • Mappers Registry 📚
    • API 📚
      • Register
      • Map
      • Get or Set an existing mapper configuration
      • Delete a registered mapper
  • Contribution
  • License

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';

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 many ways:

Along with an ES6 Class

// Target type you want to have
class User {
    constructor(firstName, lastName, phoneNumber){
        this.firstName = firstName;
        this.lastName = lastName;
        this.phoneNumber = phoneNumber;
        this.city = null;
   }
}

// Data source you want to map
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'
                        }
                    ]
             }];
// Mapping Schema ( see more examples below )
let schema = {
    city: 'address.city',
    phoneNumber: (object) => object.phoneNumber.filter(c => c.type === 'home')[0].number;
}

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);

/// *** OUTPUT *** ///

[{
    'firstName': 'John',
    'lastName': 'Smith',
    'phoneNumber': '212 555-1234',
    'city': 'New York'
 }]

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);

Mapping Schema Examples 💡

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'
      }
    ]
  }
];

Flattening and Projection

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

let results = Morphism(mapping, data);

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

Computing over Flattening / Projection

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 Class Type. The transformation sequences are stored as a function in a WeakMap to speed the processing.

Register a mapping configuration along with a Class

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: {}));

Contribution

• Twitter: @renaudin_yann
• Pull requests and stars are always welcome 🙏🏽 For bugs and feature requests, please create an issue

License

MIT © Yann Renaudin