value-transformer

Warning! This library is at an early stage of development. The API may change without backwards compatibility.

This library allows you to serialize/deserialize complex data using transformers. There is no need to interact with the raw representation: the signature of JSON literals and ArrayBuffers is encapsulated.

Example

export class VectorPictureDto {
  @asString()
  public readonly url: string;

  public constructor(url: VectorPictureDto['url']) {
    this.url = url;
  }
}

export class BitmapPictureDto {
  @asMap(asString(), asString())
  public readonly urls: ReadonlyMap<string, string>;

  public constructor(urls: BitmapPictureDto['urls']) {
    this.urls = urls;
  }
}

export class PictureDto {
  @asDate()
  public readonly createAt: ReadonlyDate;

  @asFloat64()
  public readonly rating: number;

  @asSet(asString())
  public readonly tags: ReadonlySet<string>;

  @asUnion([asClass(BitmapPictureDto), asClass(VectorPictureDto)])
  public readonly type: BitmapPictureDto | VectorPictureDto;

  public constructor(
    createAt: PictureDto['createAt'],
    rating: PictureDto['rating'],
    tags: PictureDto['tags'],
    type: PictureDto['type'],
  ) {
    this.createAt = createAt;
    this.rating = rating;
    this.tags = tags;
    this.type = type;
  }
}

const transformer = asClass(PictureDto);

API

All transformers implement the methods (listed below) in the abstract class ValueTransformer.

compatibleWith(data)

Check compatibility with the type.

decoder()

TODO doc

encode(data)

TODO doc

fromLiteral(literal)

Strictly check the literal for validity and deserialize it into data.

toLiteral(data, compact)

Serialize the passed data into a JSON-like literal.

Transformers

Simple transformers

Name	Type	Usage example
asBoolean	boolean	asBoolean()
asFloat64	number	asFloat64()
asInt8	number	asInt8()
asInt16	number	asInt16()
asInt32	number	asInt32()
asUint8	number	asUint8()
asUint16	number	asUint16()
asUint32	number	asUint32()
asBigInt	bigint	asBigInt()
asString	string	asString()
asDate	Date	asDate()
asRegExp	RegExp	asRegExp()

Collection transformers

Name	Type	Usage example
asArray	Array	asArray(asString())
asSet	Set	asSet(asString())
asMap	Map	asMap(asString(), asString())

asNever

Blocks any transformations.

Usage

The value can only be null:

const transformer = asNullable(asNever());

Ensuring that the collection is empty:

const transformer = asArray(asNever());

const transformer = asSet(asNever());

const transformer = asMap(asNever(), asNever());

As a stub when updating variants in asUnion:

// version 1
const transformer = asUnion([
  asClass(MediaDto), // actual in version 1
  asClass(BinaryFileDto), // index is 1
]);

// version 2
const transformer = asUnion([
  asNever(), // unactual in version 2
  asClass(BinaryFileDto), // index still 1
  asClass(VideoDto),
  asClass(AudioDto),
]);

asUnion

Combines several transformers. The first transformer passed compatibleWith is used for serialization.

Usage

String or number:

const transformer = asUnion([asString(), asFloat64()]);

String or array of strings:

const transformer = asUnion([asString(), asArray(asString())]);

Classes:

const transformer = asUnion([
  asClass(LandscapeDto),
  asClass(PortraitDto),
  asClass(UnderWaterDto),
]);

asNullable

The value may be null.

Usage

Only null:

const transformer = asNullable(asNever());

String or null:

const transformer = asNullable(asString());

asClass

Transforms the fields of the passed class that have decorators.

Usage

Empty class

class Foo {}

const transformer = asClass(Foo);

asEnumFloat64

Transformation of numeric enum.

Usage

enum Direction {
  UP = 0,
  DOWN = 1,
  LEFT = 2,
  RIGHT = 3,
}

const transformer = asEnumFloat64(UserDto);

asEnumString

Transformation of string enum.

Usage

enum Direction {
  UP = 'up',
  DOWN = 'down',
  LEFT = 'left',
  RIGHT = 'right',
}

const transformer = asEnumString(UserDto);

asUuidString

Transformation of UUID string.

Usage

type UserId = UuidString & {readonly __userId: unique symbol};

const transformer = asUuidString<UserId>();