@darlean/canonical-json
v2.0.0-alpha.10
Published
Library to (de)serialize canonical value objects from/to JSON.
Downloads
240
Maintainers
Readme
Package @darlean/canonical-json
Darlean Canonical JSON provides a serialization format for canonical values. It can be used together with the @darlean/canonical and @darlean/valueobjects packages.
The serialization produces valid JSON that looks very much like regular JSON.
The differences are:
- All primitive data types are represented as string. After the string representation of the value, a type annotation follows between brackets
(
and)
. The type annotation contains the physical type and the logical type. - Mappings are represented as objects. A special entry called
type
is added for the typer annotation. To avoid confusion, all other map keys are prefixed with a colon:
. - Sequences are represented as arrays. The first array element contains the type annotation.
Installation
npm install @darlean/canonical-json
Usage
Serialization
import { ArrayCanonical, BinaryCanonical, BoolCanonical, DictCanonical, FloatCanonical, IntCanonical, MomentCanonical, StringCanonical} from '@darlean/canonical';
import { CanonicalJsonDeserializer, CanonicalJsonSerializer } from '../canonical-json';
const struct = DictCanonical.from(
{
'first-name': StringCanonical.from('Jantje', ['name', 'first-name']),
'last-name': StringCanonical.from('DeBoer', ['last-name']),
'age': IntCanonical.from(21, ['age-in-years']),
'whisdom': ArrayCanonical.from(
[BoolCanonical.from(true, ['fact']), BoolCanonical.from(false, ['fact'])],
['facts']
),
'length': FloatCanonical.from(180.5, ['meters']),
'born': MomentCanonical.from(new Date('2000-12-31T18:30:00.000Z'), ['birthday']),
'data': BinaryCanonical.from(Buffer.from('BINARY'), ['binary-data'])
},
['person']
);
const serializer = new CanonicalJsonSerializer();
const binary = serializer.serialize(struct);
This results in the following JSON:
{
"type": "person",
":first-name": "Jantje (name.first-name s)",
":last-name": "DeBoer (last-name s)",
":age": "21 (age-in-years i)",
":whisdom": [
"facts",
"true (fact b)",
"false (fact b)"
],
":length": "180.5 (meters f)",
":born": "978287400000 (birthday m)",
":data": "QklOQVJZ (binary-data 6)"
}
Deserialization
Serialized data can be deserialized as follows:
const deserializer = new CanonicalJsonDeserializer();
const canonical = deserializer.deserialize(binary);
const struct2 = canonical.asDict();
console.log(struct2['first-name'].stringValue); // Prints "Jantje"
console.log(struct2['first-name'].logicalTypes); // Prints "['name', 'first-name']"
Value objects
To simplify working with canonical objects, consider the use of value objects: