Nutritious Pumpkin Masses

    transit-immutable-js

    0.8.0 • Public • Published

    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.

    npm version Build Status Coverage Status MIT Licensed

    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 output
    • class function - a constructor function that can be used to identify the type via an instanceof check
    • write function(value) - a function which will receive an instance of your type, and is expected to create some serialisable representation of it
    • read 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

    Keywords

    none

    Install

    npm i transit-immutable-js

    DownloadsWeekly Downloads

    12,807

    Version

    0.8.0

    License

    MIT

    Unpacked Size

    36.7 kB

    Total Files

    12

    Last publish

    Collaborators

    • glenjamin