mappr

A tiny JavaScript utility to assist with Functional object mapping.

---

• Install
• Why?
• Usage
• Basics
  • Strings
  • Objects
  • Functions
• Advanced
  • Chaining
  • Composing
  • Combining

Install

npm install --save mappr

Why?

By following principles of functional programming, your code contains less bugs, and is more easily testable. The two important pillars here are immutability and pure functions.

Object mapping is a frequent, often badly implemented, problem in coding. Different APIs use different data structures etc...

mappr will help you write good functional data mapping functions.

Resources

• Functional programming (Wikipedia)
• Functional programming should be your 1 priority
• Why functional languages?

Usage

mappr is exposed as a function.

var mappr = require('mappr');

mappr( … );
mappr.compose( … );

ES Module

import mappr from 'mappr';

mappr( … );
mappr.compose( … );

Basics

mappr(...string|object|function):function

Create a mapper function by invoking mappr with one or more arguments. Mappers can be strings, objects, or functions.

Strings

var getName = mappr('user.name');

var name = getName({ user: { name: 'Jane' } });

// name = 'Jane'

String mappers are created by passing a string to mappr. This creates a mapper function that will retrieve nested JSON data using the provided string.

Note: uses lodash.get internally

Objects

var getUser = mappr({
    name: 'data.firstName'
});

var user = getUser({ data: { firstName: 'Jane' } });

// user = { name: 'Jane' }

An object mapper is created by passing an object into mappr. This creates a mapper function that will construct a JSON object. The object keys will be used as-is, the values will be parsed recursively by mappr.

This means the following two examples are exactly the same in execution.

var getUser = mappr({
    name: 'user.firstName'
});

var getUser = mappr({
    name: mappr('user.firstName')
});

This is just FYI. You'll never have to write the latter.

Functions

Lastly a function mapper create a function, that executes a function.

var getUserName = mappr(function (name) {
  return name.firstName + ' ' + name.lastName;
});

var username = getUserName({
    firstName: 'Jane',
    lastName: 'Doe'
});

// username = 'Jane Doe'

By itself not very useful. Its power stems from composing it with other mappers.

Advanced

Chaining

mappr takes one or more arguments. When more arguments are provided the results are chained. The output of the preceding function is provided as the input of the proceding function.

var getUsername = mappr(
    'user.name',
    function trim(userName) {
        return userName.trim();
    },
    function toUpper(userName) {
        return userName.toUpperCase();
    }
)

var username = getUsername({ user: { name: '  Jane  ' } });

// username = 'JANE'

Composing

mappr.compose(...string|object|function):function

compose allows you to combine multiple mappers together and merge their results into one object.

var mapName = mappr({
  name: 'user.firstName',
  familyName: 'user.lastName',
});

var mapAddress = mappr({
  address: function (src) {
    return src.user.street + ' ' + src.user.streetNumber;
  }
});

var mapUser = mappr.compose(mapName, mapAddress);

var user = mapUser({
  user: {
    firstName: 'Jane',
    lastName: 'Doe',
    street: 'Barstreet',
    streetNumber: '18'
  }
});

// user = {
//   name: 'Jane',
//   familyName: 'Doe',
//   address: 'Barstreet 18'
// }

Combining

mappr quickly gets very powerful when combining with other FP libraries. Here is an example when used with Lodash FP.

var _ = require('lodash/fp');

var mapUser = mappr.compose(
  _.pick(['firstName', 'lastName']),
  {
    articles: mappr('posts', _.map(_.omit(['id']))),
  }
);

var user = mapUser({
  firstName: 'Jane'
  lastName: 'Doe',
  gender: 'female',
  posts: [
    { id: '1', title: 'My Post 1', upvoteCount: 123 },
    { id: '2', title: 'My Post 2', udpateCount: 456 }
  ]
});

// user = {
//   firstName: 'Jane',
//   lastName: 'Doe',
//   articles: [
//     { title: 'My Post 1', upvoteCount: 123 },
//     { title: 'My Post 2', upvoteCount: 456 }
//   ]
// }

ES2015

ES2015 makes everything nicer.

const mapUser = mappr({
  name: (src) => `${src.firstName} ${src.lastName}`
});

const user = mapUser({
    firstName: 'Jane',
    lastName: 'Doe'
});

// user = {
//   name: 'Jane Doe'
// }