README
ts-jackson
A typescript library to deserialize and serialize json into classes and vice versa. You can use different path pattern
to resolve deeply nested structures. Every path pattern provided by lodash.set
function is supported.
Check out src/examples as a reference.
- Installation
- Imports
- Serializable
- JsonProperty
- Deserialize
- Serialize
- Using constructor arguments
- SerializableEntity
Installation:
npm install ts-jackson --save
# or
yarn add ts-jackson
For tsconfig.json
file set experimentalDecorators
and emitDecoratorMetadata
to true
to allow
decorators support:
{
"compilerOptions": {
"emitDecoratorMetadata": true,
"experimentalDecorators": true
}
}
Api:
Imports:
import { JsonProperty, Serializable, deserialize, serialize, SerializableEntity } from 'typescript-json-serializer';
Decorators
Serializable
To mark your class as serializable wrap your class with Serializable decorator:
@Serializable()
class Class {}
JsonProperty
/**
* JsonProperty params
*
* @param {string} path -- path pattern for the property
* supports every pattern provided by lodash/get|set object
* @param {boolean} required throws an Error if json is missing required property
* @param {Function | Function[]} type Optional. In most cases there is no need to specify
* type explicitly. You can also provide array of type constructors for tuple support.
* @param {Function} elementType due to reflect-metadata restriction one should
* explicitly set elementType property to correctly serialize/deserialize Array
* or Set values
* @param {Function} validate function for validating json values. Throws an error
* if property fails to pass validate check
* @param {Function} deserialize function for custom deserialization
* @param {Function} serialize function for custom serialization
* @param {Function} afterDeserialize takes deserialized instance and deserialized property. Should return new property value.
*/
declare type Params<P> = {
path?: string
paths?: string[]
required?: boolean
type?:
| (new (...args: any[]) => P)
| {
[K in keyof P]: new (...args: any[]) => P[K]
}
elementType?: new (...args: any[]) => P extends [] ? P[0] : any
validate?: (property: P) => boolean
deserialize?: (jsonValue: any) => P
serialize?: (property: P) => any
afterDeserialize?: (
deserializedInstance: InstanceType<new (...args: any[]) => any>,
propertyValue: any
) => P
beforeSerialize?: (propertyValue: P) => any
afterSerialize?: (serializedData: any) => any
}
/**
* Decorator. Collects annotated property metadata.
* Takes as a param either a single string param (path),
* Array of strings (multiple paths), or param object.
* @param {string | |string[] | Params } arg
*/
export default function JsonProperty<P = unknown>(
arg?: Params<P> | string | string[]
): (object: Object, propertyName: string) => void
Path:
The path property can be set in a few different ways:
// By inferring path from the property name:
class Cat {
@JsonProperty()
name: string
}
// As a string argument
class Track {
@JsonProperty('duration_ms')
durationMs: number
}
// As an Option parameter
class Track {
@JsonProperty({
path: 'duration_ms'
})
durationMs: number
}
Path property supports different formats for resolving deeply nested structures provided by lodash
_.set(object, path, value)
Multiple paths
You can resolve property as a combination of multiple json paths, provided either as Params
property or
as an argument to @JsonProperty
decorator:
const json = {
images: {
smallImage: {
url: 'mediumImageUrl',
},
mediumImage: {
url: 'mediumImageUrl',
},
bigImage: {
url: 'bigImageUrl',
},
},
}
@Serializable()
class Playlist {
@JsonProperty({
paths: ['images.smallImage', 'images.mediumImage', 'images.bigImage'],
elementType: Image,
})
images: Image[]
}
You can also provide custom deserialize, beforeSerialize functions:
const json = {
images: [
{
url: 'mediumImageUrl',
},
{
url: 'mediumImageUrl',
},
{
url: 'bigImageUrl',
},
],
}
@Serializable()
class Playlist {
@JsonProperty({
paths: ['images[0]', 'images[2]'],
elementType: Image,
deserialize: ([icon, cover]: Image[]) => ({ icon, cover }),
beforeSerialize: (images) => [images.icon, images.cover],
})
images: {
icon: Image
cover: Image
}
}
Resolving deeply nested structures:
const trackJson = {
track: {
id: 'some id',
},
}
@Serializable()
class Track {
@JsonProperty('track.id')
readonly id: string
}
const deserialized = deserialize(trackJson, Track)
// Track { id: 'some id' }
serialize(deserialized)
// { track: { id: 'some id' } }
Resolving array structures
const jsonData = {
images: {
items: [
{
height: 300,
url:
'https://i.scdn.co/image/ab67616d0000b27380368f0aa8f90c51674f9dd2',
width: 300,
},
{
height: 640,
url:
'https://i.scdn.co/image/ab67616d00001e0280368f0aa8f90c51674f9dd2',
width: 640,
},
],
},
}
@Serializable()
class Playlist {
@JsonProperty('images.items[1]')
readonly backgroundImage: Image
}
const deserialized = deserialize(jsonData, Playlist)
// Playlist {
// backgroundImage: Image {
// height: 640,
// width: 640,
// url: 'https://i.scdn.co/image/ab67616d00001e0280368f0aa8f90c51674f9dd2'
// }
// }
const serialized = serialize(deserialized)
// {
// images: {
// items: [undefined, {
// height: 640,
// width: 640,
// url: 'https://i.scdn.co/image/ab67616d00001e0280368f0aa8f90c51674f9dd2',
// }],
// },
// }
For more patterns for resolving structures check out lodash/get docs.
deserialize
/**
* Function to deserialize json to Serializable class
*
* @param {Record<string, unknown> | string} json
* @param serializableClass Class to which json should be serialized
* @param args an arguments to be provided to constructor.
* For example Cat(readonly name, readonly color)
* deserialize({}, Cat, 'Moon', 'black')
*/
export default function deserialize<T, U extends Array<unknown>>(
json: Record<string, unknown> | string,
serializableClass: new (...args: [...U]) => T,
...args: U
): T
serialize
/**
* Function to serialize Serializable class to json
*
* @param {Function} instance serializable instance
* @returns {Record<string, unknown>} json
*/
export default function serialize<
T extends new (...args: unknown[]) => unknown
>(instance: InstanceType<T>): Record<string, unknown> {
Examples
const trackJson = {
track: {
id: 'some id',
},
}
@Serializable()
class Track {
@JsonProperty('track.id')
readonly id: string
}
const deserializedClassIntance = deserialize(trackJson, Track)
const serializedJson = serialize(deserializedClassIntance)
Using constructor arguments:
// using constructor params:
@Serializable()
class Image {
@JsonProperty({ required: true })
readonly url: string
constructor(readonly width: number, readonly height: number) {
}
}
deserialize({url: 'url'}, Image, 5, 3)
const deserializedClassIntance = deserialize({url: 'some url'}, Image, 5, 4)
const serializedJson = serialize(deserializedClassIntance)
SerializableEntity
/**
* @class
* Utility class that encapsulates deserialize, serialize
* and the need for @Serializable explicit decoration.
*/
export default class SerializableEntity {
/**
* @method Returns stringified results
* of serialize method call
*/
stringify(): string
serialize(): Record<string, unknown>
static deserialize<T, U extends Array<unknown>>(
this: {
new (...params: [...U]): T
},
json: Record<string, unknown>,
...args: U
): T
}
// Example:
class Image extends SerializableEntity {
@JsonProperty()
readonly height?: number
@JsonProperty()
readonly width?: number
@JsonProperty({ required: true })
readonly url: string
}
const imageJson = {
height: '234',
width: '123',
url: 'http://localhost:8080',
}
const image = Image.deserialize(imageJson)
// Image { height: 234, width: 123, url: 'http://localhost:8080' }
image.serialize()
// { height: 234, width: 123, url: 'http://localhost:8080' }
image.stringify()
// '{"height":234,"width":123,"url":"http://localhost:8080"}'