TS-Serializer

!ts-serializer-ci
!GitHub
!GitHub repo size
!GitHub last commit
!GitHub issues
!GitHub top language

Serialize and deserialize JSON into strongly typed typescript objects using decorators.

Informations

> :warning: Since version 1.0.10, ``ts-serializer` has been published under `@paddls` namespace. We continue to maintain `@witty-services` namespace.

Summary

* How to install
* How to use
* Configure your models
* Serialization
* Deserialization
* Serialization configuration
* API
* JsonPropertyDecorator
* JsonPropertyContext
* JsonTypeSupports
* NormalizerConfiguration
* CustomConverter
* How to run Unit Tests

How to install

To install the library, run :

`
npm i @paddls/ts-serializer
`
or
`
npm i @witty-services/ts-serializer
`

How to use

$3

``typescript
export class User {

@JsonProperty({readOnly: true})
public id: string;

@JsonProperty()
public firstName: string

@JsonProperty('lastname')
public lastName: string;

@JsonProperty(Address)
public address: Address;

@JsonProperty(() => [Car, Truck])
public vehicles: Vehicle[];

@JsonProperty({groups: ['WithAge', 'OtherGroup']})
public age: number;

@JsonProperty({groups: 'WithSize'})
public size: number;
}

abstract class Vehicle {

@JsonProperty()
public name: string;
}

@JsonTypeSupports((data: { type: 'CAR' | 'TRUCK' }) => data.type === 'CAR')
class Car extends Vehicle {

@JsonProperty()
public seatingCapacity: number;
}

@JsonTypeSupports((data: { type: 'CAR' | 'TRUCK' }) => data.type === 'TRUCK')
class Truck extends Vehicle {

@JsonProperty()
public payloadCapacity: number;
}
``

You can find the full @JsonProperty() decorator configuration in API section.

$3

`typescript
const object: MyClass = new MyClass();

const serializer: Serializer = new Serialize(new Normalizer(), new Denormalizer());
const data: any = serializer.serialize(object);
`

$3

`typescript
class MyClass {
// ...
}

const data: any = {};


const serializer: Serializer = new Serializer(new Normalizer(), new Denormalizer());
const myObject: MyClass = serializer.deserialize(MyClass, data);
`

$3

You can configure serializer using NormalizerConfiguration class :

``typescript
const configuration: NormalizerConfiguration = {
denormalizeNull: false,
denormalizeUndefined: false,
normalizeNull: false,
normalizeUndefined: false
};
``

$3

You can use groups to restrict the serialization/deserialization process. Without any options provided to serializer,
groups configuration aren't used. But if you want to use groups defined in JsonProperty decorator, you can use them like
this :

`typescript
class MyClass {

@JsonProperty()
public attribute1: string;

@JsonProperty({groups: 'Group1'})
public attribute2: string;

@JsonProperty({groups: ['Group1', 'Group2']})
public attribute3: string;

@JsonProperty({groups: 'Group3'})
public attribute4: string;
}

const data: any = {
//...
};


const serializer: Serializer = new Serializer(new Normalizer(), new Denormalizer());
const myObject: MyClass = serializer.deserialize(MyClass, data, {groups: ['Group1', 'Group2']});

// here, myObject has only attribute2 and attribute3 valued
`

API

$3

| Argument | Type | Required | Description |
|---------- | ------ | ---------- | ------------ |
| jsonPropertyContext | JsonPropertyContext | string | Type | No | If no argument is provided, the attribute will be mapped with a field in json object with the same name.
If the argument is a string, the attribute will be mapped with a field in json object named with the provided string.
If the argument is a type, the attribute will be mapped with a field in json object with the same name, but the type provided will be used to make the transformation. |

$3

| Attribute | Type | Required | Description |
|----------- | ------ | ---------- | ------------ |
| field | string | No | You can change the name of mapped field. The attribute accept a path ` 'path.to.myField' ` |
| type | Function | No | You can provide a type to convert json data to an object of Type or convert an object of Type to json data using Type configuration |
| readOnly | boolean | No | You can want to use the attribute configuration only in the deserialization process |
| writeOnly | boolean | No | You can want to use the attribute configuration only in the serialization process |
| customConverter | Converter | No | You can add a custom converter object of type Converter to convert your object |
| groups | string | string[] | No | You can restrict serialization/deserialization process with groups |

$3

| Argument | Type | Required | Description |
|---------- | ------ | ---------- | ------------ |
| context | Function | Yes | This argument sets up the function to call when the serializer searches a type which matches with received data |

$3

| Attribute | Type | Required | Default value | Description |
|----------- | ------ | ---------- | --------------- | ------------ |
| denormalizerNull | boolean | No | false | Denormalizer configuration to not denormalize null values |
| denormalizeUndefined | boolean | No | false | Denormalizer configuration to not denormalize undefined values |
| normalizeNull | boolean | No | false | Normalizer configuration to not normalize null values |
| normalizeUndefined | boolean | No | false | Normalizer configuration to not normalize undefined values |

$3

CustomConverter is an interface to make some converter. TS-Serializer provides a DateConverter to convert a date
to an ISOString and an ISOString to a date.

$3

SerializerOptions is an interface which represents optional options to provide to serialization/deserialization
process.

| Attribute | Type | Required | Default value | Description |
|----------- | ------ | ---------- | --------------- | ------------ |
| groups | string | string[] | No | undefined | Groups to use in serialization/deserialization process |

How to run Unit Tests

To run unit tests and generate coverage, run :

`
npm run test
``