Surrial
Serialize anything. Pretty surreal!
Install
Install using your favorite package manager:
npm install surrial# OR yarn add surrial
Usage
const serialize deserialize surrial = ; { thisname = name; thisparent = parent; } { return thing; } const stringified = ; /* => '{ "a": 1, "b": new Date("2018-02-13T20:27:39.073Z"), "c": /foo/, "d": new Set([1, 2, 3]), "e": new Map([[1, "one"], [2, "two"]]), "f": class Person { constructor(name, parent) { this.name = name; this.parent = parent; } }, "g": function identity(thing) { return thing; } }' */ const output = /* =>{ a: 1, b: 2018-02-13T20:32:52.218Z, c: /foo/, d: Set { 1, 2, 3 }, e: Map { 1 => 'one', 2 => 'two' }, f: [Function: Person], h: [Function: identity] } */
Also supports serializing instances of classes for known classes.
const p = 'Foo' 'Bar' null;const knownClasses = Person;const personString = ;// => 'new Person("Foo", new Person("Bar", null))' const copy = ;// => Person { name: 'Foo', parent: Person { name: 'Bar', parent: null } }
An example of the surrial
tag for template literals:
const decade = 2010 1 1 2020 1 1;surrial`new Set()`;// => 'new Set([new Date("2010-01-31T23:00:00.000Z"),new Date("2020-01-31T23:00:00.000Z")])'
You can customize the output string using the surrialize()
method (comparable to the toJSON
method for JSON.stringify
).
// A typescript example ;;;expectoutput.instanceOfPerson;expectoutput.deep.eqinput;
Api
TypeScript typings are included in the library.
/** * A surrial template tag, useful for building templates strings while enforcing the values to be serialized using surrial. * @param templateLiterals The template literals * @param values The values to be serialized using surrial */ { /** * Serializes the thing to a javascript string. This is NOT necessarily a JSON string, but will be valid javascript. * @param thing The thing to be serialized * @param knownClasses the classes of which instances are serialized as constructor calls (for example "new Person('Henry')"). */: string { /** * Deserializes a string into it's javascript equivalent. CAUTION! Evaluates the string in the current javascript engine * (`eval` or one of its friends). Be sure the `serializedThing` comes from a trusted source! * @param serializedThing The string to deserialize * @param knownClasses A list of known classes used to provide as constructor functions */: any;
Features
- Serializes all primitive types
- Serializes plain objects as JSON
- Support for build in types:
Date
,RegExp
,Map
,Set
andBuffer
- Support for functions and classes using their
toString()
- Support for instances of classes using
new MyClass()
syntax (see limitations). - Support for deeply nested build in types/class instances
- Has a light footprint (< 200 lines of code).
- Written in typescript (type definition included).
- Deserialize using a
deserialize
convenience method. This uses thenew Function(/*...*/)
(comparable toeval
) (see limitations). - Serialize values in a template with a handy
surrial
tagged template literal. - Allow a custom serialize function using
surrialize
.
Limitations
Surrial, like any serialization library, has some limitations, but supports my personal use case. If you need more functionality, don't hesitate to open an issue. I'm always in for a discussion.
Circular references
Circular references are not supported.
Deserializing is no security feature (you will get hacked!)
When you call the deserialize
method, any string will be interpreted as javascript using the new Function(...)
constructor. Keep in mind that any arbitrary code will be executed in the global scope of your current javascript engine! Please don't use this library to deserialize strings coming from untrusted sources!
Class instances
Class instances are serialized using their constructor. Any additional properties are ignored.
{ thisname = name; } const p = 'foo';page = 10; // => ignored;// => 'new Person("foo")'
Both the class
syntax and prototype
syntax (es5 syntax) are supported here.
When serializing an instance of a class, it is assumed that the constructor parameters are also properties (or attributes) of that class. If not, that parameter will be undefined.
{ thisname = n; // => ignored thisage = age; } const p = 'foo' 42;;// => 'new Person(undefined, 42)'
When serializing a class instance, only classes you specify as knownClasses
are actually serialized using new MyClass()
,
by default it would just have a JSON format.
{ thisname = name; };// => { "name": "foo" } ;// => new Person("foo")
When deserializing a class instance, you are responsible for providing a class definition (or a class with the same name).
{ thisname = name; };// => ReferenceError: Person is not defined ;// => OK: Person { name: 'Foo' }
Acknowledgements
- This library is strongly influenced by serialize-javascript. This might be what you're looking for when you don't need the class instance serialization support.
- A library which supports circular references: circular-json
- Know the class that you're serializing to? serialize.ts might be for you. This one also looks good: cerialize