@witty-services/ts-serializer
TypeScript icon, indicating that this package has built-in type declarations

1.1.0 • Public • Published

TS-Serializer

ts-serializer-ci Coverage Status npm version GitHub GitHub repo size GitHub last commit GitHub issues GitHub top language

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

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

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Tag
  • 1.1.0
    1
    • latest

Version History

Package Sidebar

Install

npm i @witty-services/ts-serializer

Weekly Downloads

33

Version

1.1.0

License

MIT

Unpacked Size

43.5 kB

Total Files

47

Last publish

Collaborators

  • lexwitty
  • thomasnisole
  • rmartineau
  • corentin.langlais
  • oguerin