Minimalistic, flexible and easy-to-use JSON mapper 🍰 🍭 🎉
npm install magic-mapper --save
yarn add magic-mapper
This tiny library helps you to map one JSON object into another. Its basic features are:
- selective property transformations
- exclusive property selection
- global property and value transformation
If using a schema you can define how to transform object properties selectively, e.g.
const originalObject = { id : 1, name: 'John', lastName: 'Doe', birthDate: '1996-03-27T17:03:02Z' } const mapper = new MagicMapper(); const mappedObject = mapper.map(originalObject, { birthDate: date => moment(date).locale('de').format('LLLL') }) /* mappedobject = { id : 1, name: 'John', lastName: 'Doe', birthDate: 'Mittwoch, 27. März 1996 14:03' } */ Per default, all properties are mapped, but you may want to select only a subset of the properties.
const originalObject = { id : 1, name: 'John', lastName: 'Doe', birthDate: '1996-03-27T17:03:02Z' } const mapper = new MagicMapper({exclusive: true}); //< set exclusive flag const mappedObject = mapper.map(originalObject, { birthDate: date => moment(date).locale('de').format('LLLL') }) /* mappedobject = { birthDate: 'Mittwoch, 27. März 1996 14:03' } */ Sometimes, you want to apply some transformations for all properties. You can either use a global transformation function for the property values, or even for the property names itself.
const originalObject = { id : 1, name: 'John', lastName: 'Doe', birthDate: '1996-03-27T17:03:02Z' } const mapper = new MagicMapper({ propertyTransform: propertyName => propertyName[0].toUpperCase() + propertyName.substr(1), valueTransform: value => typeof value === 'string' ? value.toUpperCase() : value }); const mappedObject = mapper.map(originalObject, { birthDate: date => moment(date).locale('de').format('LLLL') }) /* mappedobject = { Id : 1, Name: 'JOHN', LastName: 'DOE', BirthDate: 'Mittwoch, 27. März 1996 14:03' } */ The schema is used for two purposes,
- Define exclusive mapping
- Define property transformations
☠ When used for exclusive mapping a schema is mandatory.
A schema is just a JSON object, that should match structurally to the input object. The values describe how to map the related property. Following value types are possible
- Function - use a fn(value) or (v) => {...} to transform the value into something new
- Fixed Value - to use the value directly
- MagicMapper.Direct - a symbol to express that original value shall be used -> when using options.exclusive=false the direct mapping is applied automatically for all properties, except the schema says something different.
☠ When using global property transformation, use the transformed property names instead.
const originalObject = { id : 1, name: 'John', lastName: 'Doe', birthDate: '1996-03-27T17:03:02Z' } const mapper = new MagicMapper(); //< implicitely exclusive=false, no global transformation const mappedObject = mapper.map(originalObject, { id: null, // maps always 'null' name: MagicMapper.Direct, // uses original value birthDate: date => moment(date).locale('de').format('LLLL') // transforms date }) /* mappedobject = { id: null, name: 'John', lastName: 'Doe' //< was mapped implicitely birthDate: 'Mittwoch, 27. März 1996 14:03' } */Mapping nested objects is straightforward. Just define a nested schema conforming your needs.
const originalObject = { id : 1, name: 'John', lastName: 'Doe', birthDate: '1996-03-27T17:03:02Z', father: { id : 1, name: 'John Sr.', lastName: 'Doe', birthDate: '1956-01-02T14:56:20Z', } } const toGermanDate = date => moment(date).locale('de').format('LLLL'); const mapper = new MagicMapper(); const mappedObject = mapper.map(originalObject, { birthDate : toGermanDate, father: { birthDate: toGermanDate } // nested mapping })You can also combine mapping functions to map nested objects with different mappers
const originalObject = { id : 1, name: 'John', lastName: 'Doe', birthDate: '1996-03-27T17:03:02Z', father: { id : 1, name: 'John Sr.', lastName: 'Doe', birthDate: '1956-01-02T14:56:20Z', } } const toGermanDate = date => moment(date).locale('de').format('LLLL'); const mapper = new MagicMapper(); const fatherMapper = new MagicMapper({exclusive:true}); const mappedObject = mapper.map(originalObject, { birthDate : toGermanDate, father: f => fatherMapper.map(f, { name: MagicMapper.Direct, lastName : MagicMapper.Direct }) })Arrays can be mapped as it were normal objects. If the initial object is an Array, the mapped result will be an Array, too.
const originalObject = [ {a:1},{a:2} ] const mapper = new MagicMapper(); const mappedObject = mapper.map(originalObject, { a : a => a * 2 }) /* mappedObject = [{a:2},{a:4}] */ If you want to transform the arrays values you can simply do this: ```javascript const originalObject = { values : [ 1,2,3 ] } const mapper = new MagicMapper(); const mappedObject = mapper.map(originalObject, { values : a => a.map( v => v*2 ) }) /* mappedObject = { values: [2,4,6] } */