kaiu-lab / serializer

Simple JSON deserializer for typescript applications

serializer

Table of contents

• About
• Installation
• Usage
• Usage with Angular
• Advanced Usage
• Documentation
• Development
• License

About

Serializer is a serialization library written in Typescript made to handle typing in deserialized objects.

Installation

Install through npm:

npm install --save @kaiu/serializer

Usage

Deserialize

import { Serializer } from '@kaiu/serializer';

const serializer = new Serializer();

class Foo {
    bar: string;

    public getUpperCaseBar(): string {
        return this.bar.toUpperCase();
    }
}

const foo = serializer.deserialize<Foo>({ bar: 'baz' }, Foo);

console.log(foo.getUpperCaseBar()); // Will print "BAZ"

More details: Class Serializer

Serialize

import { Serializer, Transient } from '@kaiu/serializer';

const serializer = new Serializer();

class Foo {
    bar: string;
    
    @Transient()
    secret: string;

    public getUpperCaseBar(): string {
        return this.bar.toUpperCase();
    }
}

const foo = new Foo();
foo.bar = 'baz';
foo.secret = 's3cr3t';

console.log(serializer.serialize(foo)); // Will print '{ "bar": "baz" }'

More details: Class Serializer

Usage with Angular

In order to use the serializer properly inside an Angular application, we created an angular wrapper to provide this serializer as an Injectable service: https://github.com/kaiu-lab/ng-serializer

Advanced Usages

Deep class fields

    import { Serializer, DeserializeAs } from '@kaiu/serializer';

    class Bar {
        baz: string;
   
       public getUpperCaseBaz(): string {
           return this.baz.toUpperCase();
       }   
    } 

   class Foo {
       @DeserializeAs(Bar) 
       bar: Bar;
   }
    
    const foo = serializer.deserialize<Foo>({ bar: { baz: 'baz' } }, Foo);

    console.log(foo.bar.getUpperCaseBar()); // Will print "BAZ"

More details: DeserializeAs

Arrays

import { Serializer } from '@kaiu/serializer';

const serializer = new Serializer();

class Foo {
    bar: string;

    public getUpperCaseBar(): string {
        return this.bar.toUpperCase();
    }
}

const foo = serializer.deserialize<Foo>([{ bar: 'baz' }, { bar: 'buz' }], [Foo]);

console.log(foos[1].getUpperCaseBar()); // Will print "BUZ"

Discriminant field

import { Serializer, Registry, Parent } from '@kaiu/serializer';

@Parent({
    discriminatorField: 'type',
    allowSelf: true // This one is optional.
})
export class Vehicle {
     type: string;
     color: string;

     public getDescription(): string {
        return 'I am just a vehicle';
     }
}

export class Car extends Vehicle {
    public getDescription(): string {
        return 'I am a car, I can move using wheels';
    }
}

const registry = new Registry();

registry.add([
     {
         parent: Vehicle,
         children: {
             car: Car
         }
     }
]);

const serializer = new Serializer(registry);

const foo = serializer.deserialize<Vehicle>({type: 'car', color: 'red'}, Vehicle);

console.log(foo.getDescription()); // Will print "I am a car, I can move using wheels"

More details: Class Registry

Property mapping

export class Example{
     @DeserializeFieldName('bar')
     foo: string;
}

const result = serializer.deserialize<Example>({ bar: 'hey' }, Example);
console.log(result.foo); // Will print 'hey'

More details: DeserializeFieldName

Documentation

Everything is detailed on our documentation website.

Development

Prepare your environment

• Install Node.js and NPM
• Install local dev dependencies: npm install while current directory is this repo

Testing

Run npm test to run tests once or npm run test:watch to continually run tests.

Release

• Bump the version in package.json (once the module hits 1.0 this will become automatic)

npm run release

License

MIT

serializer's Issues

Add support for serialization

With the aim of proposing a fully featured library, it would be necessary to manage the serialization in addition to the deserialization.

• Some projects may want to use this lib server side and need to serialize object instead of deserialize.
• We can think about a complexe serialization process before sending data with some Ajax call client side.

Add proper type matching instead of any.

We want to match a proper type instead of any in deserialize's signature

public deserialize<T>(obj: any, clazz?: any /* TODO See if we can change this any */): T

A good example of implementation can be found here: microsoft/TypeScript#17572 (comment)

Configure tslint properly

The main rules we want are:

• Use const whenever it's possible.
• Allow inferred types.
• Single quotes for strings.
• Spaces around braces and type declarations.
• Triple equal.

The actual tslint.json configuration is almost fine but typedef options have to be tuned and we need to add const rule.

fix codecov's mapping

It seems like codecov is mapping with s strange process, we have some comments uncovered even if we're using https://github.com/webpack-contrib/istanbul-instrumenter-loader.

Example of wtf coverage: https://codecov.io/gh/kaiu-lab/serializer/src/a8b6bfe1a6eb9a47fb2ecf37f1f43cc0b77fc2c9/src/serializer.ts

Create a CONTRIBUTING.md file

The main goal of such a file is to indicate every conventions one has to follow in order to keep the repository and the code clean.

Example: https://github.com/angular/angular/blob/master/CONTRIBUTING.md

Add support for deserializing array of class instances

The deserialization does not handle an array of instances.

For example :

serializer.deserialize<Foo[]>([
    {
        'attrString' : 'val',
        'attrNumber' : 5,
    }, {
        'attrString' : 'foo',
        'attrNumber' : 10,
    },
], Foo);

Clear package.json

The actual devDependency field in our package.json is the one generated from the yeoman generator, we might want to remove some libraries but we have to find out which ones are useless.

Preprocess registrations at register time

Instead of using a dumb Serializer.register() that leaves all the bulk of the processing for when the serializer is used, I think we should move most of the processing during the registration.

Currently, Serializer.register() simply fills an array and checks for some little constraints. On the other side, Serializer.deserialize() process this array each time to find the correct inheritance or other stuff.

I would prefer to do most of the preprocessing at registration time, so Serializer.deserialize() has nothing else to do but actually deserializing.

Preprocessing in the Serializer.register() can also be used to check a certain number of inheritance constraints, to throw errors without having to wait for some Serializer.deserialize() calls.

Add support for callbacks in deserialization lifecycle

We should add support for deserlization callbacks, something like

interface Deserializable {
   beforeDeserialize(event);
   afterDeserialize(event);
}

class Foo implements Deserializable {
   attr1: string;

   @DeserializeAs(Bar)
   attr2: Bar;

   beforeDeserialize(event) {
       event.json.attr1 = event.json.attr1 + '-modified';
   }

   afterDeserialize(event) {
      event.target.attr2.setSomething(event.json.something);
   }
}

We should also support function in place of class inside @DeserializeAs decorator.

const myFunc = (json) => {
    return json.someAttr + ' - ' + json.someOtherAttr;
}

class Foo {
    attr1: string;
 
    @DeserializeAs(myFunc)
    attr2: Bar;
}

All the proposed signature are fakes

Add support for attributes name mapping

We should allow to map a json field into a class attribute with a differente name.

For exemple, the json may contain "prix", and the developper want to map it to the attribute "price" inside its class.

class Foo {
   @Deserialize('prix')
   price: number;
}

Clean remaining javascript files

Some Javascript files are still in the repository, we should delete them from versioning.

The one we saw is karma.conf.js but we should check if there's no other files like this remaining.

We should define the full specs of the deserialization with inheritance

Before going further in the implementation with the risk of having to replace everything if we encounter a new unforeseen case, I think we should set the full specs of the deserialization with inheritance.

This issue should list all cases and how to manage them. This comment will be edited with the latest updates.

• Object without its discriminator field
• Object with unmatching discriminator value
• Register with children that does not extends the parent
• Register with the parent among the children
• Inheritance with implicit matching for the parent itself
• Recursive inheritance, with multiple levels, like grandchildren and further
• Register with the same classe multiple time for different discriminator value
• Register for different classes but the same discriminator value

Edit 2017-24-07

• Remove Inheritance with explicit matching for the parent itself (same as above?) because it's the same as registering the parent
• Add the case for multiple registration of the same classe, or the same disciminatorValue

Fix documentation typos and bad examples

example:
https://github.com/kaiu-io/serializer/blob/master/src/serializer.ts#L18

This cannot be valid because there's no bar property in the example class.

Rename the organization to kaiu-lab in order to be able to create the kaiu-io repo for our website.

add metadata.json file for angular's aot

Because ngc needs every dependency to be aot-compliant, we need to be aot-compliant too.

Meaning that we need to ship some metadatas for aot.

I'll investigate on it and add details on this issue.

Add proper documentation in a github pages site.

Add strictNullChecks and noImplicitReturns flag to tsconfig