ts-deserializer v1.0.3

Table of contents

• Installation
• Description
• API Documentation

Installation

npm install ts-deserializer --save

Description

ts-deserializer can be used to deserialize data from one class to another. Another common use case is deserializing data that should be of a given type to itself. This is useful when dealing with unverified data from an external location like an XMLHttpRequest request.

Functional operators can be chained to resolve properties across types, map functions, deserialize child content, validate values, and provide fallback values should something not exist or go wrong. Logging can occur in various ways to report any missing or invalid data where needed.

A goal of ts-deserializer is for no deserialized object to have properties that should be defined be undefined. If used correctly, theoretically you should never have to check for undefined properties. Any properties that are missing or contain unexpected data will be logged as configured.

Quick Examples:

/* Basic fallback example */
class User implements Deserializable<User> {
  name: string;
  email: string;
  info: string;

  deserialize(user: User): User {
    let deserializer = new Deserializer<User, User>({
      logLevel: DeserializerLogLevel.None,
      resolvers: [
        resolve('name')
          .fallback(''),
        resolve('email')
          .fallback(() => ''),
      ]
    });
    return deserializer.deserialize(user, this);
  }
}

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

/* Map examples */
class Group implements Deserializable<Group> {
  title: string;
  primaryUser: User;
  users: User[]

  deserialize(group: Group): Group {
    let deserializer = new Deserializer<Group, Group>({
      logLevel: DeserializerLogLevel.None,
      resolvers: [
        resolve('title')
          .map((t) => t + '!')
          .fallback('Test'),
        resolve('primaryUser')
          .deserializeTo(User)
          .fallback(),
        resolve('users')
          .deserializeToArrayOf(User)
          .fallback([])
      ]
    });
    return deserializer.deserialize(group, this);
  }
}

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

/* Resolve -> to examples */
class MyFormData implements Deserializable<MyFormData> {
  option1: string;
  option2: string;
  option3: string;

  deserialize(formData: OtherFormData): MyFormData {
    let deserializer = new Deserializer<OtherFormData, MyFormData>({
      logLevel: DeserializerLogLevel.Error,
      resolvers: [
        resolve('optionA')
          .to('option1')
          .fallback(''),
        resolve('optionB')
          .to('option2')
          .fallback(''),
        resolve('extras.optionC')
          .to('option3')
          .fallback('')
      ]
    });
    return deserializer.deserialize(formData, this);
  }
}

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

/* Basic Chaining Example */
class NumberStringToNumber implements Deserializable<BasicChain> {
  val: number;

  deserialize(obj: any): BasicChain {
    let deserializer = new Deserializer<any, BasicChain>({
      logLevel: DeserializerLogLevel.Warn,
      resolvers: [
        resolve('someStrings.thisString')
          .to('val')
          .map((val) => parseInt(val))
          .validateNumber()
          .fallback(0)
      ]
    });
    return deserializer.deserialize(obj, this);
  }
}

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

API Documentation

Exported Objects

• Deserializable - interface
• Deserializer<T1,T2> - class
• DeserializerConfig - interface
• DeserializerLogLevel - enum
• resolve - factory function
• DeserializerResolverBuilder - builder class

Deserializable

Interface

Deserializable is an interface that requires a deserialize(obj: any): any method. It provides a recommended pattern for deserializing classes.

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

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

Deserializer

Class

The Deserializer<T1,T2> class is used to deserialize objects of type T1 to type T2. It's only parameter is a DeserializerConfig seen below.

DeserializerConfig

Interface

A Deserializer constructor requires a DeserializerConfig as it's only parameter. This object is used to configure a deserializer.

DeserializerLogLevel

Enum

A DeserializerLogLevel is used to set log levels across all resolvers in a deserializer or to override the deserializer log level at the resolver level. There are four log levels:

resolve

Factory

The resolve function is a useful factory for quickly creating DeserializerResolverBuilders.

DeserializerResolverBuilder

Builder Class

A DeserializerResolverBuilder is the builder class used to define resolvers that can be passed to a Deserializer via a DeserializerConfig.

There are four types of operators each outlined below:

Deserializer Operators

Deserializer Operators are used to define the property on T1 that data should be deserialized from. The property on T2 that data should be deserialized to. As well as a fallback value should T1 be undefined or some other issue occur in the operator chain.

The resolve operator is required. Without it no fromProp or toProp can be determined.

The fallback operator is required. It serves as the "build" method for this builder class.

Functional Operators

Functional Operators are used to manipulate data as it is being deserialized. They can be used to map data to functions, trigger side effects, or deserialize child content.

Validators

Validator can be used to catch when certain conditions are not met. If any validator returns false the issue is logged and the fallback value is returned.

Logging Overrides

Logging overrides can be used to set custom logging settings for a given resolver. The logging settings set at the Deserializer level will be overridden with these. See DeserializerLogLevel for a list of available log levels.

TODO:

• Create more validators
• Create more operators for common mapping use cases
• Add reusable resolver examples
• Add resolver logging override examples