transit-immutable-js

transit-immutable-js

Transit serialisation for Immutable.js.

Transit is a serialisation format which builds on top of JSON to provide a richer set of types. It is extensible, which makes it a good choice for easily providing serialisation and deserialisation capabilities for Immutable's types.

Install

npm install transit-immutable-js

You must also be using immutable for this to be any use.

I have chosen to apply very broad npm peerDependencies for simplicity, please check that the versions you have pulled in actually work.

Usage

var transit = require('transit-immutable-js');
var Immutable = require('immutable');

var m = Immutable.Map({with: "Some", data: "In"});

var str = transit.toJSON(m);

console.log(str)
// ["~#cmap",["with","Some","data","In"]]

var m2 = transit.fromJSON(str);

console.log(Immutable.is(m, m2));
// true

This library also manages to preserve objects which are a mixture of plain javascript and Immutable.

var obj = {
  iMap: Immutable.Map().set(Immutable.List.of(1, 2, 3), "123"),
  iList: Immutable.List.of("a", "b", "c"),
  array: [ "javascript", 4, "lyfe" ]
}

console.log(transit.fromJSON(transit.toJSON(obj)));
// { iMap: Map { [1,2,3]: "123" },
//  iList: List [ "a", "b", "c" ],
//  array: [ 'javascript', 4, 'lyfe' ] }

API

transit.toJSON(object) => string

Convert an immutable object into a JSON representation

transit.fromJSON(string) => object

Convert a JSON representation back into an immutable object

The withXXX methods can be combined as desired.

transit.withFilter(function) => transit

Create a modified version of the transit API that deeply applies the provided filter function to all immutable collections before serialising. Can be used to exclude entries.

transit.withRecords(Array recordClasses) => transit

Creates a modified version of the transit API with support for serializing/deserializing Record objects. If a Record is included in an object to be serialized without the proper handler, on encoding it will be encoded as an Immutable.Map.

Example Record Usage:

var FooRecord = Immutable.Record({
  a: 1,
  b: 2,
}, 'foo');

var data = new FooRecord();

var recordTransit = transit.withRecords([FooRecord]);
var encodedJSON = transit.toJSON(data);