tjmapper v0.9.5

TJMapper

TJMapper is small library for mapping Javascript Objects to JSON.

Installation

Use the NodeJS package manager npm to install TJMapper.

npm install tjMapper

To use TJMapper in your project, enable the experimental Decorators option in your tsconfig.json.

{
  ...
  "experimentalDecorators" : true
  ...
}

Usage

TJMapper provides three decorators to declare mappable entities and properties:

• tjEntity
• tjBaseTypeProperty
• tjObjectProperty

tjEntity

Use this decorator to make a class known to the TJMapper environment.

@tjEntity()
class Mappable {
  public id : number;
  public name : string;
}

The class' prototype is altered by adding the field _tj_entity_id!

Classes without this decorator cannot be mapped!

The decorator accepts one parameter object, which consists of two optional fields: typeField and typeName, which default to "type" and the class name respectively.

@tjEntity({ typeName : "super_mappable" })
class Mappable {
  public id : number;
  public name : string;
}

In the above case, when using type information for mapping, the resulting JSON will include "type" : "super_mappable".

Lastly, classes inherit their typeField value from their (mapped) superclasses.

tjBaseProperty

Use this decorator to make a basic type (number, string, etc.) and Date property known to the TJMapper environment.

@tjEntity()
class Mappable {

  @tjBaseProperty()
  public id : number;

  @tjBaseProperty()
  public name : string;

  @tjBaseProperty({ isDate : true })
  public creation_time : Date,
}

You can use the isDate field to map a Date object, in which case, the UNIX timestamp is used. Besides that, the decorator allows further options:

• name: specifies the field name of this property in the resulting JSON. Defaults to the property name.
• onNull: specifies how to treat null values. You can choose to either ignore the property or use a constant value instead.
• profiles: Specify under which profiles, this property is mapped.
• excludeDefault: Specify to exclude this property from mapping under the default profile.
• isArray: specifies to treat this property as an array. All items are mapped with the specified options, except onItemNull is used to handle the case of null items.

Profiles

With profiles, you can specify what parts of an object you wish to map. A predefined profile exists, default, which is used for mappings without a specified profile. Any property will be mapped under the default profile, if not specified otherwise.

tjObjectProperty

Similar to tjBaseProperty, except this one is used for properties pointing to objects.

@tjEntity()
class Reference {

  @tjBaseProperty({profiles : [ "on_ref" ], excludeDefault : true })
  public name : string;

  @tjObjectProperty({ onCircular : { tjCircularStrategy.PROFILE, profile : "id_only" } })
  public holder : Mappable;

}

@tjEntity()
class Mappable {

  @tjBaseProperty({ profiles : [ "id_only" ] })
  public id : number;

  @tjObjectProperty({ profiles : [ ["ref_only", "on_ref"] ] })
  public ref : Reference;
}

The optional fields work the same as with TjBaseTypeOptions, except profiles, which takes an array of profiles pairs. Each pair defines what profile maps onto which for mapping the property. You can also use only one profile in a pair, in which case it maps onto the default profile. If you want profiles to map onto themselves, you can declare them with the propagate field. Lastly, you can specify are mapping for the default profile by using profileOnDefault, which default to the default profile.

Furthermore, you can define how circular references are handled with onCircular. Per default, the property is ignored, however you can specify an alternative profile to map the circular reference.

Mapping

Use the provided map function to map an object.

map(someMappableObject)
map(someMappableObject, { useType : true, profile : "id_only" })

You can specify what profile to use (defaults to the default profile) and whether to include type information. The examplatory results for both results can be seen below.

{
  "id" : 1,
  "ref" : {
    "holder" : {
      "id" : 1
    }
  }
}

{
  "id" : 1,
  "type" : "Mappable"
}

Future Features

Some coming features are already in the works:

• Evaluate functions and include their results in the JSON mappings
• Add property of the super class to sub class specifiy profiles
• Add configurations, such as when to emitt warnings, errors, etc.