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.

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.

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.

Only null:

const transformer = asNullable(asNever());

String or null:

const transformer = asNullable(asString());

asClass

Transforms the fields of the passed class that have decorators.

Empty class

class Foo {}

const transformer = asClass(Foo);

asEnumFloat64

Transformation of numeric enum.

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

const transformer = asEnumFloat64(UserDto);

asEnumString

Transformation of string enum.

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

const transformer = asEnumString(UserDto);

asUuidString

Transformation of UUID string.

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

const transformer = asUuidString<UserId>();