JsonImmutable
Immutable.JS structure-aware JSON serializer/deserializer built around the native JSON
API.
Motivation
By using the native JSON
API, Immutable.JS structures are serialized as plain objects and arrays with no type information. The goal was to preserve both Immutable.JS Iterable
types (maps, lists, etc.) and Record
types. immutable.Map
supports and preserves key types while plain JavaScript object keys are coerced to strings. These types should also preserved.
Usage
Plain Objects and Primitive Types
const data = 'a': 'b' 'c': 123 'd': true // Serializeconst json = // json == '{"a":"b","c":123,"d":true}' // Deserializeconst result =
Native Object Types
const data = 'created_at': '2016-09-08' 'pattern': /iamnative/g // Serializeconst json = // json == '{"created_at":{"__date":"2016-09-08T00:00:00Z"},"pattern":{"__regexp":"/iamnative/g"}}' // Deserializeconst result =
bignumber.js Types
let x = '1111222233334444555566'; // Serializeconst json = // json == '{"__bignumber":1111222233334444555566}' // Deserializeconst result =
Immutable Records
const SampleRecord = immutable const data = 'x': // Serializeconst json = // json == '{"x":{"__record":"SampleRecord","data":{"a":5}}}' // Deserializeconst result =
Record types can be named. This is utilized by the serializer/deserializer to revive immutable.Record
objects. See the SampleRecord
name passed into immutable.Record()
as the second argument.
NOTE: When an unknown record type is encountered during deserialization, an error is thrown.
General Immutable Structures
const data = 'x': immutable // Serializationconst json = // json == '{"x":{"__iterable":"Map","data":[["y",{"__iterable":"List","data":[1,2,3]"}]]}}' // Deserializeconst result =
-
Immutable structures, plain objects and primitive data can be safely composed together.
-
immutable.Map
key type information is preserved as opposed to the bareJSON
API.
NOTE: When an unknown Immutable iterable type is encountered during deserialization, an error is thrown. The supported types are List
, Map
, OrderedMap
, Set
, OrderedSet
and Stack
.
API
-
serialize()
Arguments:
data
: The data to serialize.options={}
: Serialization options.pretty=false
: Whether to pretty-print the result (2 spaces).
Return value:
string
: The JSON representation of the input (data
).
-
deserialize()
Arguments:
json
: A JSON representation of data.options={}
: Deserialization options.recordTypes={}
:immutable.Record
factories.
Return value:
any
: Deserialized data.
Streaming API
-
createSerializationStream()
Arguments:
data
: The data to serialize.options={}
: Serialization options.pretty=false
: Whether to pretty-print the result (2 spaces).bigChunks=false
: Whether the serialized data should only be split into chunks based on the reader speed. By default, each data structure level is processed in its own event loop microtask which.- NOTE: When
bigChunks=true
, a (possibly substantial) portion of the data is serialized synchronously.
- NOTE: When
Return value:
stream.PassThrough<!Buffer>
: A readable stream emitting the JSON representation of the input (data
).
Running Tests
- Clone the repository.
npm install
npm test