A typescript library for JSON serialization
npm install @adllang/jsonbindingKey features:
* bidirectional (ie serialization and deserialization)
* handles builtin types like bigint, Date, Map and Set
* extensible
* errors that describe the location of parse failures
* support for unions, generics and custom types
* typescript implementation
Here's a brief comparison with zod.
The core of the library is the type:
``
interface JsonBinding
toJson(t: T): Json;
fromJson(json: Json): T;
};
A JsonBinding of type T captures the ability to serializeT
a value of type to JSON, and to deserialize a value ofT
type from JSON. JsonBindings can be easily constructed
via library functions. For example
`
import { JsonBinding } from "@adllang/jsonbinding";
import * as jb from '@adllang/jsonbinding';
interface User {
name: string,
birthday: Date,
}
const JB_USER: JsonBinding
name: jb.string(),
birthday: jb.date(),
});
``
Then usage is:
`
> JB_USER.toJson({name: "Robin", birthday:new Date()})
{"birthday": 1720998670768, "name": "Robin"}
> JB_USER.fromJson({"birthday": 1720998670768, "name": "Robin"})
{ "birthday": 2024-07-14T23:11:10.768Z, "name": "Robin"}
> JB_USER.fromJson({"name": "Robin"})
UncaughtError: expected an object with field birthday at $
In the previous example, I like having the User interface explicit
in the code. But you can infer it from the JsonBinding, in the
style of zod:
`
import { JsonBinding } from "@adllang/jsonbinding";
import * as jb from '@adllang/jsonbinding';
const JB_USER = jb.object({
name: jb.string(),
birthday: jb.date(),
});
type User = jb.Infer
``
The following primitives are provided:
`
function string(): JsonBinding
function number(): JsonBinding
function boolean(): JsonBinding
function nullv(): JsonBinding
function json(): JsonBinding
function date(): JsonBinding
function bigint(): JsonBinding
Technically, date() and bigint() are implemented as mapped bindings (see below)
The libraries object() functions builds JSON bindings for typescript objects and interfaces. A simple example:
`
interface User {
name: string,
birthday: Date,
roles: string[],
}
const JB_USER: JsonBinding
name: jb.string(),
birthday: jb.date(),
roles: jb.array(jb.string()),
});
`
Default values for fields can also be specified, and these will be used when deserialising json streams that lack
these fields. Hence, in this example:
`
interface User {
name: string,
roles: string[],
}
const JB_ROLE_ARRAY = jb.array(jb.string());
const JB_USER: JsonBinding
name: jb.string(),
roles: jb.withDefault(JB_ROLE_ARRAY, []),
});
`
the roles field need not be present for successful deserialization:
`
> const u = JB_USER.fromJson({name:"Fred"});
> u.name
'Fred'
> u.roles
[]
The library has support for discriminated unions, using the union() function.
`
interface Rectangle {
width: number,
height: number
};
interface Circle {
radius: number;
};
type Shape
= {kind: 'rectangle', value: Rectangle}
| {kind: 'circle', value: Circle};
const JB_RECTANGLE = jb.object({
width: jb.number(),
height: jb.number(),
});
const JB_CIRCLE = jb.object({
radius : jb.number(),
});
const JB_SHAPE: JsonBinding
{kind: 'rectangle', value: JB_RECTANGLE},
{kind: 'circle', value: JB_CIRCLE},
]);
`
are supported via the following functions:
`
function map
function set
function pair
Mapped types in this library support conversions on serialization and deserialization. One constructs a JsonBinding forJsonBinding
a mapped type by providing a for the underlying type, and a pair of conversion functions to convert the
underlying type from/to the mapped type.
The serialisation of typescript Date objects is an example of this. We want the in memory presentation to be a Date
object, but we wish to serialize it as the number of milliseconds since the epoch. This is written as:
`
const JB_DATE: JsonBinding
jb.number(), // serialize as a number
d => d.getTime(), // convert a Date to a number
n => new Date(n), // convert a number to a Date
);
Mapped types can also be used to create JsonBindings for typescript classes. For example
`
class Point2D {
constructor(readonly x: number, readonly y: number) {
}
add(offset: Point2D): Point2D {
return new Point2D(this.x + offset.x, this.y + offset.y);
}
}
const JB_POINT_2D: JsonBinding
jb.object({x: jb.number(), y: jb.number()}),
p => p,
p => new Point2D(p.x, p.y)
);
`
A JsonBinding for a generic type can be constructed by writing a function to build the JsonBinding that takes as parameters the JsonBindings of
the generic type parameters. Referencing the Point2D example:
` { (jbPoint: JsonBinding ): JsonBinding const JB_PATH_2D: JsonBinding
interface Path
points: P[]
};
function jbPath
return jb.object({
points: jb.array(jbPoint),
});
}
A lazy() combinator is available to facilitate creating JsonBindings for recursive
types.
`
interface Category {
name: string,
subcategories: Category[]
}
function jbCategory(): JsonBinding
return jb.object({
name: jb.string(),
subcategories: jb.array(jb.lazy(() => jbCategory())),
});
}
`
The library includes JsonBinding helpers
for string keyed maps:
`
export type StringMap
export function stringMap
`
for values that may be null or some other type:
`
export function orNull
for values that may be undefined or some other type:
`
export function orUndefined
Zod deserves credit for introducing robust typescript defined
schema validations. It's widespread use reflects it's value. The ts-jsonbinding
library was built primarily to address the following key limitation of Zod:
zod is validation/deserialization only. It can take accept external input, validate it, and
then map it to internal typescript types. But it has no direct support for the opposite
serialization path. As a concrete example zod has no equivalent for the JB_USER.toJson method
here
For my needs writing data to JSON (ie serialisation) is just as important as validation
and parsing (ie deserialization). JSON.stringify() only does the right thing for a
small fraction of possible data types, and various other libraries try and help
with this (eg superjson).
ts-jsonbinding is a single library to deal with both serialization and deserialization
needs, with complete flexibility of the mapping between runtime values and their
representation in JSON.
Build and test:
`
deno test
Publish to JSR:
`
deno publish
Publish to NPM:
`
deno task build_npm
cd npm
npm login
npm publish