node-immutable-object

imobject allows you to create deep immutable JavaScript objects. Once the properties are set additional properties can't be added and the initial properties cannot be modified.

Installation

To use imobject, cd into your project directory and install imobject with npm or yarn.

npm

$ cd /to/project/directory
$ npm install imobject --save

yarn

$ cd /to/project/directory
$ yarn add imobject

Usage

To create an imobject, simply require the npm package and cast your standard JavaScript objects into imobjects.

const IMObject = require('imobject');

var immutable = new IMObject({
    foo: 'bar',
    nested: {
        foo: 'baz'
    }
});

// To access properties simply use the dot operator
console.log(immutable.foo);
// -> bar

console.log(immutable.nested.foo);
// -> baz

// If you attempt to modify a property an exception will be thrown
immutable.nested.foo = 'newvalue'
// -> ERROR!

// If you attempt to add a new property an exception will be thrown
immutable.newprop = 'newvalue'
// -> ERROR!

Instance Methods

get

get works just like the dot operator with the added benefit of providing a default value if the path requested is not set.

const IMObject = require('imobject');

var immutable = new IMObject({
    foo: 'bar',
    nested: {
        foo: 'baz'
    }
});

console.log(immutable.get('foo'));
// -> bar

console.log(immutable.get('nested.foo',  'defaultvalue'));
// -> baz

console.log(immutable.get('nested.notset', 'defaultvalue'));
// -> defaultvalue

has

has returns a boolean value indicating whether or not a given path is set.

const IMObject = require('imobject');

var immutable = new IMObject({
    foo: 'bar',
    nested: {
        foo: 'baz'
    }
});

console.log(immutable.has('foo'));
// -> true

console.log(immutable.has('nested.foo'));
// -> true

console.log(immutable.hast('nested.notset'));
// -> false

Known Issues

Custom objects are not immutably cloned because it is not safe to do so. Immutability only works on for the following types: String, Boolean, Object, Number, Array, Date, RegExp.