Typescript type annotations give us compile-time guarantees, but at run-time, when data flows from the server to our clients, lots of things can go wrong.
JSON decoders validate the JSON before it comes into our program. So if the data has an unexpected structure, we learn about it immediately.
If you are new to JSON decoding, you may want to read the introductory article Decoding JSON with Typescript about why and how to use this library.
npm install ts.data.json --save
type User = {
firstname: string;
lastname: string;
};
const userDecoder = JsonDecoder.object<User>(
{
firstname: JsonDecoder.string,
lastname: JsonDecoder.string
},
'User'
);
const jsonObjectOk = {
firstname: 'Damien',
lastname: 'Jurado'
};
userDecoder
.decodePromise(jsonObjectOk)
.then(user => {
console.log(`User ${user.firstname} ${user.lastname} decoded successfully`);
})
.catch(error => {
console.log(error);
});
// Output: User Damien Jurado decoded successfully
const jsonObjectKo = {
firstname: 'Erik',
lastname: null
};
userDecoder
.decodePromise(jsonObjectKo)
.then(user => {
console.log('User decoded successfully');
})
.catch(error => {
console.error(error);
});
// Output: <User> decoder failed at key "lastname" with error: null is not a valid string
string: Decoder<string>
Creates a string decoder.
JsonDecoder.string.decode('hi'); // Ok<string>({value: 'hi'})
JsonDecoder.string.decode(5); // Err({error: '5 is not a valid string'})
number: Decoder<number>
Creates a number decoder.
JsonDecoder.number.decode(99); // Ok<number>({value: 99})
JsonDecoder.string.decode('hola'); // Err({error: 'hola is not a valid number'})
boolean: Decoder<boolean>
Creates a boolean decoder.
JsonDecoder.boolean.decode(true); // Ok<boolean>({value: true})
JsonDecoder.boolean.decode(null); // Err({error: 'null is not a valid boolean'})
object<a>(decoders: DecoderObject<a>, decoderName: string, keyMap?: DecoderObjectKeyMap<a>): Decoder<a>
Creates an object decoder.
Key/value pair that has to comply with the <a> type.
The type of the object we are decoding. i.e. User. It is used to generate meaningful decoding error messages.
Optional key/value pair to map JSON-land keys with Model-land keys. Useful when the JSON keys don't match with the decoded type keys.
type User = {
firstname: string;
lastname: string;
};
const userDecoder = JsonDecoder.object<User>(
{
firstname: JsonDecoder.string,
lastname: JsonDecoder.string
},
'User'
);
const jsonOk = {
firstname: 'Damien',
lastname: 'Jurado'
};
userDecoder.decode(jsonOk);
// Output: Ok<User>({value: {firstname: 'Damien', lastname: 'Jurado'}})
const jsonKo = {
firstname: null,
lastname: 'Satie'
};
userDecoder.decode(jsonKo);
// Output: Err({error: '<User> decoder failed at key "firstname" with error: null is not a valid string'})const userDecoder = JsonDecoder.object<User>(
{
firstname: JsonDecoder.string,
lastname: JsonDecoder.string
},
'User',
{
firstname: 'fName',
lastname: 'lName'
}
);
const jsonOk = {
fName: 'Nick',
lName: 'Drake'
};
userDecoder.decode(json);
// Output: Ok({value: {firstname: 'Nick', lastname: 'Drake'}})
const jsonKo = {
fName: 'Nick'
};
userDecoder.decode(json);
// Output: Err({error: '<User> decoder failed at key "lastname" (mapped from the JSON key "lName") with error: undefined is not a valid string'})
array<a>(decoder: Decoder<a>, decoderName: string): Decoder<Array<a>>
Creates an array decoder.
The decoder used to decode every Array<a> item.
The type of the object we are decoding. i.e. User[]. It is used to generate meaningful decoding error messages.
JsonDecoder.array<number>(JsonDecoder.number, 'number[]').decode([1, 2, 3]);
// Output: Ok<number[]>({value: [1, 2, 3]})
JsonDecoder.array<number>(JsonDecoder.number, 'number[]').decode([1, '2', 3]);
// Output: Err({error: '<number[]> decoder failed at index 1 with error: "2" is not a valid number'})
dictionary<a>(decoder: Decoder<a>, decoderName: string): Decoder<{ [name: string]: a }>
Creates a dictionary decoder.
The decoder used to decode every value of the key/value pairs.
The type of the object we are decoding. i.e. User. It is used to generate meaningful decoding error messages.
JsonDecoder.dictionary(JsonDecoder.number, 'Dict<number>').decode({
a: 1,
b: 2
});
// Output: Ok<Dict<number>>({value: {a: 1, b: 2}})
JsonDecoder.dictionary(JsonDecoder.number, 'Dict<number>').decode({
a: 1,
b: 2,
c: null
});
// Output: Err({error: '<Dict<number>> dictionary decoder failed at key "c" with error: null is not a valid number'})
oneOf<a>(decoders: Array<Decoder<a>>, decoderName: string): Decoder<a>
The oneOf decoder tries to decode the provided JSON with any of the provided decoders. It returns Ok with the first successful decoded value or Err if all decoders fail.
The array of possible decoders that the JSON can be decoded with.
The type of the object we are decoding. i.e. number | string. It is used to generate meaningful decoding error messages.
JsonDecoder.oneOf<string | number>(
[JsonDecoder.string, JsonDecoder.number],
'string | number'
).decode(1);
// Output: Ok<string | number>({value: 1})
JsonDecoder.oneOf<string | number>(
[JsonDecoder.string, JsonDecoder.number],
'string | number'
).decode(true);
// Output: Err({error: "<string | number> decoder failed because true can't be decoded with any of the provided oneOf decoders"})
allOf<T extends Array<Decoder<unknown>>, R = AllOfDecoderReturn<T>>(decoders: T): Decoder<R>
The allOf decoder tries to decode the provided JSON with all of the provided decoders, in order. The output of one decoder is passed as input to the next decoder. It returns Ok with the last successful decoded value or Err if any decoder fails.
The allOf decoder allows you to combine multiple decoders. It is probably most useful when combined with custom decoders you may make for your application.
An array of decoders that the JSON should be decoded with.
Simple examples:
JsonDecoder.allOf(
JsonDecoder.string,
JsonDecoder.failover(10, JsonDecoder.number)
).decode('hola'),
// Output: Ok({value: 10})
JsonDecoder.allOf(
JsonDecoder.string,
JsonDecoder.failover(10, JsonDecoder.number)
).decode(5),
// Output: Err({error: "5 is not a valid string})Example using a custom hasLength() decoder (an example here):
JsonDecoder.allOf(
JsonDecoder.array(JsonDecoder.number, 'latLang'),
hasLength<[number, number]>(2)
).decode([-123.34324, 23.454365]);
// Output: Ok({value: [-123.34324, 23.454365]})
JsonDecoder.allOf(
JsonDecoder.array(JsonDecoder.number, 'latLang'),
hasLength<[number, number]>(2)
).decode([1, 2, 3]);
// Output: Err({error: "hasLength() decoder failed because the provided array is of length 3."})
lazy<a>(mkDecoder: () => Decoder<a>): Decoder<a>
Decoder for recursive data structures.
Function that returns a decoder.
type Node<a> = {
value: a;
children?: Node<a>[];
};
const treeDecoder: JsonDecoder.Decoder<Node<string>> = JsonDecoder.object<
Node<string>
>(
{
value: JsonDecoder.string,
children: JsonDecoder.oneOf<Node<string>[]>(
[
JsonDecoder.lazy(() => JsonDecoder.array(treeDecoder, 'Node<a>[]')),
JsonDecoder.isUndefined([])
],
'Node<string>[] | isUndefined'
)
},
'Node<string>'
);
treeDecoder.decode({
value: 'root',
children: [
{ value: '1' },
{ value: '2', children: [{ value: '2.1' }, { value: '2.2' }] }
]
});
// Output: Ok<Node<string>>({value: {value: 'root', children: [....]}})
treeDecoder.decode({
value: 'root',
children: null
});
// Output: Err({error: "<Node<string>> decoder failed at key 'children' with error: <Node<string>[] | isUndefined> decoder failed because null can't be decoded with any of the provided oneOf decoders"})
failover<a>(defaultValue: a, decoder: Decoder<a>): Decoder<a>
Creates a decoder that returns a default value on failure.
The returned Ok default value when the decoder fails.
The decoder that the JSON will be decoded with.
JsonDecoder.failover('default value', JsonDecoder.string).decode(
'This is fine'
);
// Ok<string>({value: 'This is fine'})
JsonDecoder.failover('default value', JsonDecoder.string).decode(null);
// Ok<string>({value: 'default value'})
succeed: Decoder<any>
Creates a decoder that always succeeds.
JsonDecoder.succeed.decode(null); // Ok<any>({value: null})
fail<a>(error: string): Decoder<a>
Creates a decoder that always fails.
The error message that will be returned with the Err instance.
JsonDecoder.fail('Something wrong happened').decode('This is fine');
// Err({error: 'Something wrong happened'})
isNull<a>(defaultValue: a): Decoder<a>
Succeeds when JSON is strictly (===) null and returns a defaultValue.
The returned default value when JSON is null.
JsonDecoder.isNull('default value').decode(null);
// Ok({value: 'default value'})
JsonDecoder.isNull('default value').decode(999);
// Err({error: '999 is not null'})
isUndefined<a>(defaultValue: a): Decoder<a>
Succeeds when JSON is strictly (===) undefined and returns a defaultValue.
The returned default value when JSON is undefined.
JsonDecoder.isUndefined('default value').decode(undefined);
// Ok({value: 'default value'})
JsonDecoder.isUndefined('default value').decode(999);
// Err({error: '999 is not undefined'})
isExactly<a>(value: a): Decoder<a>
Succeeds when JSON is strictly (===) value: a and returns value: a.
The value that will be returned when the JSON is strictly equal to it.
JsonDecoder.isExactly(true).decode(true);
// Ok({value: true})
JsonDecoder.isExactly(999).decode(true);
// Err({error: 'true is not 999'})
constant<a>(value: a): Decoder<a>
Decoder that always succeeds returning value.
The value that will always be returned.
JsonDecoder.constant(true).decode(false);
// Ok({value: true})