Skip to content

A TypeScript serialization/deserialization library to convert objects to/from JSON

License

Notifications You must be signed in to change notification settings

hyperloris/tyson

Repository files navigation

Tyson is a TypeScript serialization/deserialization library to convert objects to/from JSON.

Features

  • Simple toJson() and fromJson() methods for conversions
  • Many options on the property (e.g. custom naming, required and more)
  • Type-safe JSON deserialization
  • Support for multi-type arrays
  • Custom conversions through adapters and factories

Installation

You can install tyson using npm:

npm install --save @hyperloris/tyson

Usage

The primary class to use is Tyson which you can just create by calling new Tyson(). There is also a class TysonBuilder available that can be used to create a Tyson instance with various settings (e.g. register a custom type adapter).

Requirements

There are three requirements to be met in order to make the library work properly:

  • Set experimentalDecorators and emitDecoratorMetadata to true on your tsconfig.json file
  • Properties need to be preceded by the @JsonProperty annotation
  • Properties need to have a default value (e.g. undefined)

A nice example

Let's start with a JSON representing a city:

{
  "name": "Bologna",
  "population": 388884,
  "monuments": ["Piazza Maggiore", "Palazzo Re Enzo"],
  "mayor": {
    "full_name": "Virginio Merola",
    "birthdate": "1955-02-14T00:00:00"
  }
}

Now we need a couple of TypeScript classes:

export class User {
  @JsonProperty("full_name")
  name: string = undefined;
  @JsonProperty({ type: Date })
  birthdate: Date = undefined;
}

export class City {
  @JsonProperty()
  name: string = undefined;
  @JsonProperty()
  population: number = undefined;
  @JsonProperty({ name: "monuments", type: [String] })
  private _monuments: string[] = undefined;
  @JsonProperty("mayor")
  private _mayor: User = undefined;
}

At this point we are ready to use the library:

const tyson = new Tyson();
const city = tyson.fromJson(json, City);
const json = tyson.toJson(city);

Documentation

Tyson API: generated with TypeDoc at every release.

Inspiration

The library is inspired by the Gson library.

License

MIT