ts-deserializable v1.1.1

Table of contents

• Installation
• Description
• Getting Started
• API

Installation

npm install ts-deserializable --save

Description

TS-Deserializable is a typescript library that uses metadata and reflection to deserialize unverified data from an external location (like an XMLHttpRequest request) to an instance of a class with a provided decorator config pattern. Data mapping can be applied to conform data to your classes and fallback values must be given in case data is missing. Logging can occur in various ways to report any missing or invalid data where needed.

Getting Started

To begin, define a log level of either ignore, warn, error, or throw with @DsClass(). Then, define how data will map to a classes' properties with @DsProp().

@DsClass() log levels determine where you get notified of missing properties. When a fallback value has to be used, the reporter will either ignore logging it, log a warn message, log an error message, or actually throw an error.

@DsProp() chains must always end with a fallback value or fb() - even if that value is undefined. @DsProp() prop chains also provide a few operators for mapping data from objects to your class, see the API section for a full list of operators.

Quick Examples:

/* Basic fallback example */
@DsClass().ignore()
class User extends Deserializable<User> {

  @DsProp().fb('')
  name: string;

  @DsProp().fb(() => '')
  email: string;

  info: string;
}

const user = new User().deserialize({});
// user == { name: '', email: '' }

/* Map examples */
@DsClass().warn()
class Group extends Deserializable<Group> {

  @DsProp().map((s) => s + '!').fb('Test')
  title: string;

  @DsProp().mapToArray(User).fb([])
  users: User[];
}

const group = new Group().deserialize({ title: 'My Group' });
// group == { title: 'MyGroup!', users = [ {name: '', email: ''}, { name: '', email: ''} ]}

/* Resolver examples */
@DsClass().error()
class MyFormData extends Deserializable<MyFormData> {

  @DsProp().resolve(obj => obj.optionA).fb('')
  option1: string;

  @DsProp().dotResolve('optionB').fb('')
  option2: string;

  @DsProp().dotResolve('extras.optionC').fb('')
  option3: string;

  @DsProp().dotResolve(['extras', 'optionD']).fb('')
  option4: string;
}

const formData = new MyFormData().deserialize({
  optionA: 'A',
  optionB: 'B',
  extras: { optionC: 'C', optionD: 'D' }
});
// formData == { option1: 'A', option2: 'B', option3: 'C', option4: 'D' }

/* Basic Chaining Example */
@DsClass().warn()
class NumberStringToNumber extends Deserializable<NumberStringToNumber> {

  @DsProp()
    .dotResolve('someStrings.thisString')
    .map((val) => parseInt(val))
    .validateNumber()
    .fb(0)
  val!: number;
}

const result = new BasicChain().deserialize({ someStrings: { thisString: '42' } });
// result = { val: 42 }

API

Deserializable

Abstract Class

Deserializable is an abstract class that implements the deserialize(obj: any): any method. This is the method that ts-deserializable uses for deserializing data. For quick and easy use your classes can extend this class. However, if you need to extend another class and want to avoid mixins you can alternatively choose to implement it instead. Any logic placed in the implemented deserialize method will not be called.

This class can also be extended or implemented without the use of ts-deserializable decorators and will still be compatible with classes that do.

class User extends Deserializable<User> { ... }

class User implements Deserializable<User> { 
  deserialize(obj: any): any { ... }
}

@DsClass()

Class Decorator

Class operators simply set the log level for any DsProps applied to any child properties of a class instance. A @DsClass decorator with a defined log level is required in order for any @DsProp decorators to be evaluated.

@DsProp()

Property Decorator

There are three types of property operators basic, resolver, and validator. APIs for each of them are listed below. Operators are applied in order and can be chained. No matter what operators are applied to a @DsProp chain, the fallback or fb() operator is required at the end of the chain as it will actually return the built property decorator.

Basic Operators

Resolver Operators

Resolver operators can be used to resolve structural differences between the object being deserialized and the desired class.

Validator Operators

Validator operators can be used to catch when certain conditions are not met.

TODO:

• Create more validators
• Create more operators for common mapping use cases
• Allow for a user provided "deserializable" method that gets called after all prop chains resolve