Documentation chapters
Type

Serialization

Serialization is the process of converting data types to a format suited for example for transportation or storage. Deserialization is the process that reverts that. This happens losslessly, which means the data can be converted to and from a serialization target without losing data type information or data itself.

In JavaScript, serialization usually occurs between JavaScript objects and JSON. JSON supports only string, number, boolean, object, and arrays. JavaScript, on the other hand, supports many more types such as BigInt, ArrayBuffer, typed arrays, Date, custom class instances, and many more. Now, to transmit JavaScript data to a server using JSON you need a serialization process (on the client) and a deserialization process (on the receiving server), or vice-versa if the server sends data serialized as JSON to the client.

Deepkit Type supports custom serialization targets but comes pre-bundled with a JSON serialization target. Using @deepkit/bson you could also use BSON as serialization target. To build your own serialization target (for example for a database driver), see the chapter Customer Serializer.

There are three main functions available: serialize, deserialize, and validatedDeserialize. Under the hood of these functions the globally available JSON serializer import { serializer } from '@deepkit/type' is used.

Note that validation is not run automatically. Use validatedDeserialize to use validation while deserializing. You can use the functions validate or validates on deserialized data, see chapter Validation.

deserialize

deserialize converts data to JavaScript types based on the given type. Per default is uses the JSON serializer. This is usually called deserialization, as it converts data from our serialization target (in our case JSON) to the data types of the runtime. cast is an alias to deserialize.

import { deserialize } from '@deepkit/type';

class MyModel {
    id: number = 0;
    created: Date = new Date;

    constructor(public name: string) {
    }
}

const myModel = deserialize<MyModel>({
    id: 5,
    created: 'Sat Oct 13 2018 14:17:35 GMT+0200',
    name: 'Peter',
});

When data can not be converted correctly a ValidationError is thrown.

When JavaScript types are passed, they are used as-is. For example, if you pass a Date object to created, then it works as well.

Soft type conversion

The deserialization processes has soft type conversion implemented. This means it can accept strings and numbers for number types, or a number for a string type. This is useful for example when accepting data via a URL query and passing it to the schema deserializer. Since URL query is string only, Deepkit Type tries to resolve the types nonetheless for numbers and booleans.

  • number|bigint: Properties marked as number or bigint accept string numbers. parseFloat will be used.
  • boolean: Properties marked as boolean accept numbers and strings.
    0, '0', 'false' will be interpreted as boolean false.
    1, '1', 'true' will be interpreted as boolean true.
import { deserialize } from '@deepkit/type';

deserialize<boolean>('false')).toBe(false);
deserialize<boolean>('0')).toBe(false);
deserialize<boolean>('1')).toBe(true);

deserialize<number>('1')).toBe(1);

serialize

serialize converts JavaScript data types to the serialization formation. Per default is uses the JSON serializer. This is usually called serialization, as it serializes a data structure to a target format (in our case JSON).

In order to produce a JSON string, you have to call the JSON serializer, and then on the result JSON.stringify().

import { serialize } from '@deepkit/type';

class MyModel {
    id: number = 0;
    created: Date = new Date;

    constructor(public name: string) {
    }
}

const model = new MyModel('Peter');

const jsonObject = serialize<MyModel>(model);
console.log(jsonObject);
const json = JSON.stringify(jsonObject);
This would output:
{
  id: 0,
  created: '2021-06-10T15:07:24.292Z',
  name: 'Peter'
}

validatedDeserialize

validatedDeserialize deserializes the data and runs all validators. It throws a detailed error object when validation fails.

Made in Germany