TS-Serializer

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

Informations

⚠️ 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

Configure your models

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.

Serialization

const object: MyClass = new MyClass();

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

Deserialization

class MyClass {
  // ...
}

const data: any = {};


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

Serializer configuration

You can configure serializer using NormalizerConfiguration class :

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

Groups

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 :

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

JsonProperty

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.

JsonPropertyContext

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

JsonTypeSupports

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

NormalizerConfiguration

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

CustomConverter

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.

SerializerOptions

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