Skip to main content
Deno 2 is finally here 🎉️
Learn more

ts_serialize ci release License: MIT

A zero dependency library for serializing data.

ts_serialize can help you with:

  • converting camelCase class members to snake_case JSON properties for use with a REST API
  • excluding internal fields from REST API payloads
  • converting data types to an internal format, for example: Date’s

Supported Serialize Types

Installing

Deno

import/export what you need from https://deno.land/x/ts_serialize@<version>/mod.ts in your deps.ts file. <version> will be a a tag found on our releases page. The version can be omitted ot get the default branch, however, it is recommended to use a tagged version.

Node

Add the URL to your package.json file in dependencies

{
  "dependencies": {
    "ts_serialize": "git+https://github.com/gamebridgeai/ts_serialize.git#v1.0.0"
  }
}

Usage

Basic

Import Serializable and SerializeProperty, extend Serializable with your class and use the SerializeProperty decorator on any properties you want serialized. Passing a string as an argument to SerializeProperty causes the property to use that name as the key when serialized.

class Test extends Serializable<Test> {
  @SerializeProperty()
  propertyOne = "Hello";
  @SerializeProperty("property_two")
  propertyTwo = "World!";
  notSerialized = "not-serialized";
}

assert(new Test().toJson(), `{"propertyOne":"Hello","property_two":"World!"}`);
const test = new Test().fromJson(
  `{"propertyOne":"From","property_two":"Json!", "notSerialized": "changed" }`
);
assertEquals(test.propertyOne, "From");
assertEquals(test.propertyTwo, "Json!");
assertEquals(test.notSerialized, "not-serialized");

Advanced

SerializeProperty also excepts an options object with the properties:

  • serializedName (Optional) {string} - Used as the key in the serialized object
  • toJsonStrategy (Optional) {ToJsonStrategy} - Function or ToJsonStrategy used when serializing
  • fromJsonStrategy (Optional) {FromJsonStrategy} - Function or FromJsonStrategy used when deserializing

Strategies

Strategies are functions or a composed list of functions to execute on the values when serializing or deserializing. The functions take one argument which is the value to process.

const myCustomFromJsonStrategy = (v: string): string => BigInt(v);
const myCustomToJsonStrategy = (v: BigInt): string => v.toString();

class Test extends Serializable<Test> {
  @SerializeProperty({
    serializedName: "big_int",
    fromJsonStrategy: myCustomFromJsonStrategy,
    toJsonStrategy: myCustomToJsonStrategy,
  })
  bigInt!: BigInt;
}

const mockObj = new Test().fromJson(`{"big_int":"9007199254740991"}`);
assertEquals(mockObj.bigInt.toString(), "9007199254740991");
assertEquals(mockObj.toJson(), "9007199254740991");

Dates

Dates can use the fromJsonStrategy to revive a serialized string into a Date object. ts_serialize provides a ISODateFromJson function to parse ISO Dates.

class Test extends Serializable<Test> {
  @SerializeProperty({
    fromJsonStrategy: ISODateFromJson,
  })
  date!: Date;
}

const mockObj = new Test().fromJson(`{"date":"2020-06-04T19:01:47.831Z"}`);
assert(mockObj.date instanceof Date);
assertEquals(mockObj.date.getFullYear(), 2020);

createDateStrategy() can be use to make a reviving date strategy. Pass a regex to make your own.

const fromJsonStrategy = createDateStrategy(/^(\d{4})-(\d{2})-(\d{2})$/);

class Test extends Serializable<Test> {
  @SerializeProperty({ fromJsonStrategy })
  date!: Date;
}

const mockObj = new Test().fromJson(`{"date":"2099-11-25"}`);
assert(mockObj.date instanceof Date);
assertEquals(mockObj.date.getFullYear(), 2099);

Inheritance

Inherited classes override the key when serializing. If you override a property any value used for that key will be overridden by the child value. With collisions the child always overrides the parent

class Test1 extends Serializable<Test1> {
  @SerializeProperty("serialize_me")
  serializeMe = "nice1";
}

class Test2 extends Test1 {
  @SerializeProperty("serialize_me")
  serializeMeInstead = "nice2";
}

const test = new Test2();
assertEquals(test.serializeMe, "nice1");
assertEquals(test.serializeMeInstead, "nice2");
assertEquals(test.toJson(), `{"serialize_me":"nice2"}`);

Nested Class Serialization

ToJson:

class Test1 extends Serializable<Test1> {
  @SerializeProperty("serialize_me_1")
  serializeMe = "nice1";
}

class Test2 extends Serializable<Test2> {
  @SerializeProperty({
    serializedKey: "serialize_me_2",
  })
  nested: Test1 = new Test1();
}

const test = new Test2();
assertEquals(test.toJson(), `{"serialize_me_2":{"serialize_me_1":"nice1"}}`);

FromJson:

class Test1 extends Serializable<Test1> {
  @SerializeProperty("serialize_me_1")
  serializeMe = "nice1";
}

class Test2 extends Serializable<Test2> {
  @SerializeProperty({
    serializedKey: "serialize_me_2",
    fromJsonStrategy: (json) => new Test1().fromJson(json),
  })
  nested!: Test1;
}

const test = new Test2();
test.fromJson(`{"serialize_me_2": { "serialize_me_1":"custom value"}}`);
assertEquals(test.nested.serializeMe, "custom value");

Mulitple strategy functions

toJsonStrategy and fromJsonStrategy also have provided functions with the same name to build out strategies with multiple functions.

const addWord = (word: string) => (v: string) => `${v} ${word}`;
const shout = (v: string) => `${v}!!!`;
const fromJsonStrategy = fromJsonStrategy(addWord("World"), shout);

class Test extends Serializable<Test> {
  @SerializeProperty({ fromJsonStrategy })
  property!: string;
}

assertEquals(new Test().fromJson(`{"property":"Hello"}`), "Hello World!!!");

Built With

Contributing

We have provided resources to help you request a new feature or report and fix a bug.

  • CONTRIBUTING.md - for guidelines when requesting a feature or reporting a bug or opening a pull request
  • DEVELOPMENT.md - for instructions on setting up the environment and running the test suite
  • CODE_OF_CONDUCT.md - for community guidelines

Versioning

We use SemVer for versioning.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments