0.5.0 • Public • Published

npm version Build Status

Mappersmith Object

This project is inspired by the Ember.Object project, it aims to provide a light layer on top of your objects/responses to help with common annoyances which the javascript world provides daily. It helps you with a common interface to access attributes and really useful helpers to deal with daily problems.

This project carries the name mappersmith- because it was planned to deeply integrate with Mappersmith project, but this is no longer true, this project doesn't require Mappersmith anymore and can be used standalone.

Browser support

This project was designed considering modern browsers. However, all the methods used are from ES5 and can be included by polyfills.



npm install mappersmith-object


Download the tag/latest version from the build folder

Build from the source

npm install
npm run release


Assuming the following data:

var data = {
  name: "Someone",
  age: 27,
  human: true,
  clicks: 3,
  company: {
    name: "",
    sectors: ["1A", "2B", "9Z"],
    floors: {
      first: "A",
      second: "B"

and the following require:

var MappersmithObject = require('mappersmith-object');

Table of Contents:


Object methods:



This method is used to wrap your objects. With strict: true operations with undefined attributes will raise an exception.

var obj = MappersmithObject.create(data);
// or
var obj = MappersmithObject.create(data, {strict: true});


This method is a constructor function for "models". It takes a model definition and returns a constructor function based on create.

var Person = MappersmithObject.extend({
  profile: function() {
    return this.get('name') + ', age: ' + this.get('age');
var obj = new Person(data);
obj.get('name') // Someone
obj.profile() // Someone, age: 27

Object methods


Returns a plain javascript object with your attributes.

obj.attributes() // {name: 'Someone', ...}

It accepts a list of keys to filter the result.

obj.attributes('name') // {name: 'Someone'}
obj.attributes('name', 'human') // {name: 'Someone', human: true}
obj.attributes('wrong.key', '')
// {wrong: {key: null}, company: {name: ''}}

It will raise exception for invalid keys in strict mode.


Retrieves the value of a property from the object. It accepts chain calls. It works with array indexes.

obj.get('name') // 'Someone'
obj.get('') //
obj.get('') // S
obj.get('company.floors.first') // A
obj.get('company.sectors.0') // 1A
obj.get('company.sectors.1') // 2B
obj.get('company.sectors.-1') // 9Z - the last item
obj.get('company.sectors.99') // null
obj.get('wrong') // null
obj.get('wrong.chain') // null

It's possible to assign a default value.

obj.get('wrong', {default: 'My Name'}) // 'My Name'

It will raise exception for invalid keys in strict mode.

// throws MappersmithObject.Exceptions.StrictViolationException


Sets the provided value to the key, creating inexistent nodes in the process.

obj.set('name', 'Other') // 'Other'
obj.set('', 'Name') // 'Name'
obj.attributes() // {name: 'Other', company: {name: 'Name', ...}, ...}

With inexistent keys/chains:

obj.set('', true) // true
obj.get('') // {chain: true}
obj.get('') // true

If the value assigned is a promise it will be resolved and the value set. A promise will be returned instead of the value.

obj.set('', promiseObj) // Promise (will resolve and set)
obj.set('', promiseObj).then(function(value) {
  console.log(value) // value => promise value
  // return == value (the promise is resolved and the value assigned)

It will raise exception for invalid keys in strict mode.

obj.set('invalid', 'value')
// throws MappersmithObject.Exceptions.StrictViolationException


Fetches data from the object, using the given key. If there is data in the object with the given key, then that data is returned. If there is no such data in the object, then the second argument value will be set and returned.

The second argument can be a value or a function. The function will be executed to generate the value.

obj.fetch('name', 'Default Name') // 'Someone'
obj.fetch('wrong', 'Default value') // 'Default value'
obj.fetch('wrong', function() { return 'Default Value'}) // 'Default value'

It will raise exception for invalid keys in strict mode.

obj.fetch('invalid', 'value')
// throws MappersmithObject.Exceptions.StrictViolationException


Create alias accessors to your attributes. Returns this so it can be chained with other methods.

obj.alias({fullName: 'name'}) // argument: object with {aliasName: 'attributeToBeAliased'}
obj.get('fullName') // 'Someone'
obj.set('fullName', 'New Name')
// obj.get('fullName') => 'New Name'
// obj.get('name') => 'New Name'

It also works with chains:

obj.alias({floors: 'company.floors'})
obj.get('floors') // {first: "A", second: "B"}

When called without arguments returns the alias mapping:

obj.alias() // {fullName: 'name'}

Aliased values can only be returned by attributes when explicit requested, example:

obj.alias({fullName: 'name'})
obj.attributes() // Object without alias: {name: 'Someone', ...}
obj.attributes('fullName', 'age') // {fullName: 'Someone', age: 27}


It checks if a property exists. It won't raise any exception for invalid keys, even in strict mode.

obj.has('name') // true
obj.has('company.floors') // true
obj.has('invalid') // false
obj.has('company.invalid.chain') // false

with {strict: true}:

obj.has('invalid') // false (no exception in this case)

Also aliased as: is'human') // true'enabled') // false


Set the value of a property to the current value plus some amount. The default amount is 1. If the value is not a number false will be returned instead. Undefined keys will be initialized with 1.'clicks') // 4'clicks', 2) // 6'invalid') // 1'name') // false

It will raise exception for invalid keys in strict mode.


Set the value of a property to the current value minus some amount. The default amount is 1. If the value is not a number false will be returned instead. Undefined keys will be initialized with -1.

obj.dec('clicks') // 5
obj.dec('clicks', 3) // 2
obj.dec('invalid') // -1
obj.dec('name') // false

It will raise exception for invalid keys in strict mode.


obj.toggle('human') // false
obj.toggle('human') // true
obj.toggle('invalid') // true
obj.toggle('name') // false
obj.toggle('name') // false


A value is blank if it's false, null, undefined, empty, NaN or a whitespace string. For example, '', ' ', null, undefined, [], and {} are all blank.

obj.isBlank('invalid') // true
// imagine {test1: '', test2: ' a ', test3: {}}
obj.isBlank('invalid') // true
obj.isBlank('test1') // true
obj.isBlank('test2') // false
obj.isBlank('test3') // true

It will return true for invalid keys in strict mode.


A value is present if it's not blank.

obj.isPresent('name') // true
obj.isPresent('invalid') // false

It will return false for invalid keys in strict mode.


Converts the value to an array. If the value is already an array, the same value will be returned. For undefined or null values a blank array ([]) will be returned.

obj.toArray('name') // ['Someone']
obj.toArray('age') // [27]
obj.toArray('invalid') // []
obj.toArray('company.sectors') // ["1A", "2B"]

If called without arguments it will return the object attributes wrapped.

obj.toArray() // [{name: "Someone", ...}]

It will raise exception for invalid keys in strict mode.


Resets the attributes to the original value.

obj.attributes() // {name: 'Someone', ...}
obj.set('name', 'Thor') // 'Thor'
obj.attributes() // {name: 'Thor', ...}
obj.reset() // {name: 'Someone', ...}
obj.attributes() // {name: 'Someone', ...}


Deeply update the attributes.

obj.update({name: 'New', human: false}) // {name: 'New', human: false, ...}
obj.get('name') // 'New'
obj.attributes() // {name: 'New', human: false, ...}


Merges the content into the object. This method provides a way to enhance the object with mixins/modules. extend can be called several times, the methods can be overridden within the next calls.

  greetings: function() {
    return 'Hello ' + this.get('name');
  sectorCountPlus: function(factor) {
    return this.get('company.sectors') + factor;
}) // will return (this) obj
obj.greetings() // 'Hello Someone'
obj.sectorCountPlus(3) // 2 + 3 = 5

It's possible to call extend several times.

var LogMixin = {
  info: function() {
    console.log.apply(this, arguments);
var ToJsonMixin = {
  toJsonString: function() {
    return JSON.stringify(this.attributes());


npm test

Compile and release

Compile: npm run build

Release (minified version): npm run release


See LICENSE for more details.




Package Sidebar


npm i mappersmith-object

Weekly Downloads






Last publish


  • tulios