Skip to content
This repository has been archived by the owner on Jun 24, 2024. It is now read-only.
/ value-transformer Public archive

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.

License

Notifications You must be signed in to change notification settings

demensky/value-transformer

Repository files navigation

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.

CI

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>();

About

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.

Topics

Resources

License

Stars

Watchers

Forks