Package Exports

@wessberg/marshaller

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@wessberg/marshaller) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Marshaller [![NPM version][npm-image]][npm-url]

A class that can map various data types back and forth between a string representation that can be transferred over the wire or evaluated using eval() or new Function() expressions and back to the native environment. This is equivalent to JSON.parse() and JSON.stringify() except with a much broader scope.

Installation

Simply do: npm install @wessberg/marshaller.

DISCLAIMER

This is an early version. There may still be bugs. If you run into some, please submit an issue on GitHub.

Usage

const marshaller = new Marshaller();

// Convert even complex data into a string representation, for example so it can be sent over the network.
marshaller.marshal({
    a: 1,
    b: new Date(),
    c: /foo/,
    d: [1, "1", new Set([1, 2, 3])],
    e: new (class Foo {})
}); // returns: {"a": 1, "b": new Date("2017-06-27T16:55:07.357Z"), "c": /foo/, "d": [1,"1",new Set([1,2,3])], "e": new (class Foo {static get __INSTANCE__VALUES_MAP () {return {}}})()}

// Convert the data back into complex types for the host environment.
const unmarshalled = marshaller.unmarshal(`{"a": 1, "b": new Date("2017-06-27T16:55:07.357Z"), "c": /foo/, "d": [1,"1",new Set([1,2,3])], "e": new (class Foo {static get __INSTANCE__VALUES_MAP () {return {}}})()}`);

// The data will have proper types
typeof unmarshalled.a === "number"; // true
unmarshalled.b instanceof Date; // true
unmarshalled.c instanceof RegExp; // true
Array.isArray(unmarshalled.d); // true
const [first, second, third] = unmarshalled.d;

// The Set will have the correct entries
third instanceof Set // true
third.has(2) // true

// Even the class instance can be reconstructed, including its members.
unmarshalled.e instanceof Foo // true

As you can see, there is really no limit to the kind of data you can marshall/unmarshall. The library was written with the primary purpose of being able to cast anything to/from a string representation so it could be networked, even instances of classes with mutated properties. This makes it possible to send class instances back and forth between a client and server.

For example:

Client

class Foo {
    public isMutated: boolean = false;
}

const marshaller = new Marshaller();
const instance = new Foo();
instance.isMutated = true;

// Marshal the class instance so it can be sent over the wire
const marshalled = marshaller.marshal(instance);

// Send it over HTTP...

Server

const marshaller = new Marshaller();

// Upon receiving a request from the client...
const unmarshalled = marshaller.unmarshal(marshalledPayload);
unmarshalled instanceof Foo; // true
unmarshalled.isMutated; // true

Use cases

This API is relatively low-level and allows for designing high-level APIs that abstracts away any need to go to a string representation and back. Some include transferring data over the network while others include storing data in a serialized database (such as localStorage).

An example could be a controller for a REST API endpoint, e.g.:

class TodoController extends Controller {
    
    @PUTEndpoint("/api/todos/:id")
    async putTodoItem (todo: TodoItem) {
        await put("todos", todo.id, todo);
    }
}

Where the base controller unmarshals the input data before passing it on to user-facing controllers. There are many use cases for marshalling data though, and yours may be different.

API

`marshal()`

marshal<T> (data: T): string

Params

`data: T`

The input data.

Returns

`string`

The marshalled string representation of the data.

`unmarshal()`

unmarshal<T> (data: string): T|{}|null|undefined

Params

`data: string`

The marshalled input data

Returns

`T|{}|null|undefined`

The unmarshalled data. Can be anything.

Roadmap

Casting from/to Set.
Casting from/to object.
Casting from/to string.
Casting from/to number.
Casting from/to boolean.
Casting from/to Array.
Casting from/to symbol.
Casting from/to class.
Casting from/to constructor.
Casting from/to null.
Casting from/to undefined.
Casting from/to Date.
Casting from/to Function
Casting from/to Map
Casting from/to WeakSet (*)
Casting from/to WeakMap (*)
Casting from/to RegExp

The (*) means that the types cannot be restored to their initial state since the keys are weak and not iterable. There are no way of restoring the state. Instead, new instances will be created.

Changelog

2.0.3 (2017-07-28)

Added changelog (e1c2253)
Bumped version (f6bc236)
Fixed an issue where regular expressions would be matched falsely at times (11be80e)
Update .gitignore (8fd18c2)
Update package.json (b1c9b2f)

2.0.2 (2017-06-28)

2.0.2 (4b2f784)
Fixed an issue where strings containing dates would be falsely unmarshalled as dates instead of regu (358a542)

2.0.1 (2017-06-28)

2.0.1 (28ed02a)
Bumped TypeDetector dependency. Allowed construction without explicitly calling the constructor with (71eea6c)
Updated version number in README (209ecaa)

2.0.0 (2017-06-27)

2.0.0 (4f60567)
Major overhaul (c4ba740)

1.0.24 (2017-06-26)

1.0.24 (839e30b)
Added mapping to/from Date (0b57890)

1.0.23 (2017-06-12)

1.0.23 (8abc77d)
Added a disclaimer to the README. (b235897)

1.0.22 (2017-05-18)

1.0.22 (3a23ae3)
Added mapping to/from Map. (702a144)

1.0.21 (2017-05-17)

1.0.21 (6b851f3)
Made sure that quoted strings will not be re-quoted. (68cf172)

1.0.20 (2017-05-17)

1.0.20 (ea9016e)
Added marshalling to/from class instances and class constructors. (7e61330)

1.0.19 (2017-05-16)

1.0.19 (d0d6ae7)
Corrected issues with marshalling global/window/self/root. (e4c6e22)

1.0.18 (2017-05-14)

1.0.18 (854eded)
Improved stringifying functions inside object literals. (f6c6503)

1.0.17 (2017-05-14)

1.0.17 (d4b3014)
Corrected some issues with marshalling to/from undefined (7bbec70)

1.0.16 (2017-05-06)

1.0.16 (327ff74)
Bumped dependency. (385d5e5)

1.0.15 (2017-05-06)

1.0.15 (a468eae)
Added the 'getTypeOf' method to the interface (c793276)

1.0.14 (2017-05-06)

1.0.14 (bb29057)
Added a proxy for the method of the dependent library. (1f6c8da)

1.0.13 (2017-05-05)

1.0.13 (d09b5e5)
Small fixes to the function regexes. (e5f4574)

1.0.12 (2017-05-05)

1.0.12 (f19ca32)
Switched to for marshalling strings to objects. (12e4f09)

1.0.11 (2017-05-05)

1.0.11 (0e69bbf)
Fixed a bug with marshalling strings that contains the word function. (19c762c)

1.0.10 (2017-05-04)

1.0.10 (2dfc96f)
The Marshaller can no marshal to objects if that is the most probable type, even if a hint is not gi (0f46f24)

1.0.9 (2017-05-04)

1.0.9 (4a2ca53)
Moved null checks up to fix errors (b855e5e)
Moved null checks up to fix errors (db239f2)

1.0.8 (2017-05-04)

1.0.8 (c3b8244)
Added marshalling to/from . (7af148f)

1.0.7 (2017-05-04)

1.0.7 (4db2917)
Marshalling objects to string no longer uses JSON.stringify. Rather, it tries to correctly format th (f4e9312)

1.0.6 (2017-05-03)

1.0.6 (1c8057a)
Added marshalling to/from (e38c8c0)

1.0.5 (2017-04-30)

1.0.5 (2d4e55f)
Fixed a bug where errors could be thrown while attempting to marshal a string using heuristics. (7fc9f64)

1.0.4 (2017-04-26)

1.0.4 (c792663)
Made a correction for marshalling strings to buest guess (554f86d)

1.0.3 (2017-04-26)

1.0.3 (03dc3a1)
Added marshalling to/from symbol (43ed7c1)

1.0.2 (2017-04-24)

1.0.2 (0cf7298)
Updated README and a few typings. (38738d3)

1.0.1 (2017-04-23)

1.0.1 (5bbffc4)
Added .idea to npmignore (c9f198c)
First commit (d8ec92b)
Made the package scoped for private access (807a605)