Converter methods

Contents

• #serialize()
• #parse()
• #dump()
• #restore()
• #extendWith()
• #overrideBy()
• #exclude()
• #withOptions()

#serialize()

Type: (source: any): string

Dump a value using #dump() and then stringify it using given serializer (JSON by default). All arguments are passed to serializer#serialize() with first argument dumped.

Example:

conv.serialize(new Date) // returns '{"$Date":"2015-06-07T12:34:56.789Z"}'

#parse()

Type: (dumped: string): any

Parse a value using given serializer (JSON by default) then restore it using #restore(). All arguments are passed to serializer#parse() with first argument restored.

Example:

conv.parse('{"$Date":"2015-06-07T12:34:56.789Z"}') // returns new instance of Date

#dump()

Type: (source: any): JSONValue

This method is called in #serialize(), preparing a value for serialization from top to bottom. It does the following:

• finds appropriate spec (does not modify value if no spec found),
• calls spec.dump() method,
• recursively calls itself each property or element of the dumped value,
• wraps result using prefix, token and namespace, turning dumped into {$namespace.Token: dumped}.

Example:

conv.dump(new Date) // returns object: {$Date: '2015-06-07T12:34:56.789Z'}

#restore()

Type: (dumped: JSONValue): any

This method is called in #parse(), restoring source value from dumped form from bottom to top. It does the following:

• recursively calls itself for each property or element of the dumped value,
• find appropriate spec using prefix, token and namespace (does not modify value if no spec found),
• unwraps the dumped value turning {$namespace.Token: dumped} into dumped,
• calls spec.restore() on the result.

Example:

conv.restore({$Date: '2015-06-07T12:34:56.789Z'}) // returns new instance of Date

#extendWith()

Type: (conv: spec|spec[]|CompositeConv|CompositeConv[]): CompositeConv

Creates new converter extending this with new convertible types. Throws an error when resulting spec list is inconsistent:

• when any class is in more than one class spec,
• when any prototype is in more then one proto spec,
• when there are two equal tokens in the same namespace. Prefix and serializer are taken from the first converter.

Example:

class Dummy {}
var conv = conv.extendWith({class: Dummy, dump: () => null});

conv.serialize(new Dummy); // returns '{"$Dummy": null}'
conv.parse('{"$Dummy": null}'); // returns new instance of Dummy

#overrideBy()

Type: (conv: spec|spec[]|CompositeConv|CompositeConv[]): CompositeConv

Creates new converter, works as #extendWith() but overrides former specs when the spec list becomes inconsistent. Prefix and serializer are taken from the last converter.

Example:

var conv = conv.overrideBy({
    class: Date,
    encode: "valueOf"
});
conv.serialize(new Date); // returns '{"$Date":"2015-06-07T12:34:56.789Z"}'
conv.serialize(new Date);   // returns '{"$Date": 1433680496789}'

#exclude()

Type:

({
    class?: Constructor,
    proto?: object,
    token?: string,
    namespace?: string
}): CompositeConv

Creates new converter with given class, prototype, token or namespace excluded. Also there is a difference in putting token and namespace together in contrast to specifying just one property:

• just token: remove a single spec with the same token and no namespace;
• both properties: remove a single spec with the same token and namespace;
• just namespace: remove all specs with that namespace.

Example:

var conv1 = require('conv'),
    conv2 = conv1.exclude({class: Date})

conv1.serialize(new Date) // returns '{"$Date":"2015-06-07T12:34:56.789Z"}'
conv2.serialize(new Date) // returns '"2015-06-07T12:34:56.789Z"'

#withOptions()

Type: (options: options): CompositeConv

Creates new converter with some options changed.

Example:

var conv = conv.withOptions({prefix: '#'});
conv.serialize(new Date); // returns '{"$Date":"2015-06-07T12:34:56.789Z"}'
conv.serialize(new Date);   // returns '{"#Date":"2015-06-07T12:34:56.789Z"}'