transit-immutable-js
v0.8.0
Published
Transit serialisation for Immutable.js
Downloads
53,741
Readme
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 of 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' ] }
Usage with transit directly
As well as the nice friendly wrapped API, the internal handlers are exposed in
case you need to work directly with the transit-js
API.
var transitJS = require('transit-js');
var handlers = require('transit-immutable-js').handlers;
var reader = transitJS.reader('json', {handlers: handlers.read});
var writer = transitJS.writer('json-verbose', {handlers: handlers.write});
API
transit.toJSON(object) => string
Convert an immutable object into a JSON representation (XSS Warning)
transit.fromJSON(string) => object
Convert a JSON representation back into an immutable object
transit.handlers.read
object
A mapping of tags to decoding functions which can be used to create a transit reader directly.
transit.handlers.write
transit.map
A mapping of type constructors to encoding functions which can be used to create a transit writer directly.
The various withXXX
methods can be combined as desired by chaining them together.
transit.withExtraHandlers(Array handlers) => transit
Also
transit.handlers.withExtraHandlers(Array handlers) => handlers
Create a modified version of the transit API that knows about more types than it did before. This is primarily useful if you have additional custom datatypes that you want to be able serialise and deserialise. Each entry in this array must be an object with the following properties:
tag
string - a unique identifier for this type that will be used in the serialised outputclass
function - a constructor function that can be used to identify the type via aninstanceof
checkwrite
function(value) - a function which will receive an instance of your type, and is expected to create some serialisable representation of itread
function(rep) - a function which will receive the serialisable representation, and is expected to create a new instance from it
The read
and write
functions should form a matched pair of functions - calling read on the result of write should produce the same value and vice versa. Transit applies encoding and decoding recursively, so you can return any type transit understands from write
, and expect to receive it back in read
later.
transit.withFilter(function) => transit
Also
transit.handlers.withFilter(function) => handlers
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, missingRecordHandler = null) => transit
Also
transit.handlers.withRecords(Array recordClasses, missingRecordHandler = null) => handlers
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
.
missingRecordHandler
is called when a record-name is not found and can be used to handle the missing record manually. If no handler is given, the deserialisation process will throw an error. It accepts 2 parameters: name
and value
and the return value will be used instead of the missing record.
Example Record
Usage:
var FooRecord = Immutable.Record({
a: 1,
b: 2,
}, 'foo');
var data = new FooRecord();
var recordTransit = transit.withRecords([FooRecord]);
var encodedJSON = recordTransit.toJSON(data);
Example missing Record
Usage:
var BarRecord = Immutable.Record({
c: '1',
d: '2'
}, 'bar');
var FooRecord = Immutable.Record({
a: 1,
b: 2,
}, 'foo');
var data = new FooRecord({a: 3, b: 4});
var recordTransitFoo = transit.withRecords([FooRecord]);
var encodedJSON = recordTransitFoo.toJSON(data);
var recordTransitEmpty = transit.withRecords([], function (name, value) {
switch (name) {
case 'foo':
return new BarRecord({c: value.a, d: value.b});
default:
return null;
}
});
var decodedResult = recordTransitEmpty.fromJSON(encodedJSON); // returns new BarRecord({c: 3, d: 4})
XSS Warning
When embedding JSON in an html page or related context (e.g. css, element attributes, etc), care must be taken to sanitize the output. By design, niether transit-js nor transit-immutable-js provide output sanitization.
There are a number of libraries that can help. Including: xss-filters, secure-filters, and many more