A TINY, fail-fast, lazy, immutable Javascript objects library.
JavaScript
Clone or download
Latest commit 791da76 Oct 13, 2016
Permalink
Failed to load latest commit information.
__test__ Add symbol to IMMUTABLE_TYPES Oct 13, 2016
dist Add symbol to IMMUTABLE_TYPES Oct 13, 2016
src Add symbol to IMMUTABLE_TYPES Oct 13, 2016
.gitignore Initial commit Aug 8, 2015
.travis.yml Update travis file Dec 9, 2015
LICENSE Initial commit Aug 8, 2015
README.md release 2.0.0 Nov 25, 2015
package.json Releases 3.0.0 Oct 14, 2016

README.md

immu NPM Module NPM download count Build Status

emu

A TINY, fail-fast, lazy, "naked", simple immutable Javascript objects library.

  • By TINY, less than 1k gzipped and minified.
  • By fail-fast, I mean you'll be notified if you try to change a property.
  • By lazy, I mean it doesn't evaluate the mutability of a property until it absolutely has to.
  • By naked, I mean they work like regular objects and arrays.
  • By simple, I mean that it doesn't add any extra features to your code (except immutability, of course).

What Immu Aims To Solve

Immu aims to solve 2 things:

  1. Immutable javascript Objects (Arrays are objects in Javascript).
  2. Fail-fast errors with detailed exceptions upon attempting to mutate Objects.

Immu does not attempt to add functionality to Arrays, introduce complex data structures like Map and Set, or provide a complete solution with cursors and stores. Immu is meant to be the simplest possible solution to providing immutable objects while maintaining the native API for those objects (including Array methods).

Other libraries that are similar but do more:

Each of these libraries are GREAT in their implementation and at the problems they solve:

Why Use Immutable Data?

Bugs happen because developers write them. This just puts one more layer between you and your code exploding. Immutable data can't promise to help you avoid all bugs, but can help you reason about your state much easier!

Install

npm install immu --save

Usage

'use strict';

let immu = require('immu');

let user = {
  name: 'Scott',
  age: 31,
  location: 'somewhere'
};

let immutableUser = immu(user);

try {
  immutableUser.name = 'Unchangeable';
}
catch (e) {
  console.error(e.message); // Cannot change value of an immutable property
}

console.log(immutableUser.name) // Scott

// Get the raw object back
console.log(immutableUser.toJS()); // {name: 'Scott', age: 31, location: 'somewhere'}

let list = immu([1, 2, 3, 4]);
let newList = list
  .map(item => item + 1)
  .filter(item => item % 2 === 0);
  
console.log(Array.isArray(list)) // true

Run Tests

git clone https://github.com/scottcorgan/immu.git && cd immu
npm install
npm test