After many hours of development, I finally released the first version of the
jackson-js library. As the name implies,
jackson-js decorators are heavily inspired by the Java annotations of the famous Java FasterXML/jackson library.
You can install it using
npm install —-save jackson-js and it can be used on both client (browser) and server (Node.js) side.
Why this library? What’s the difference between using this library instead of
For simple cases, you don't need this library of course, you can just use
JSON.stringify to serialize/deserialize JSON.
@JsonIgnore(), and more. However, this library uses
JSON.stringify under the hood.
contextoption (similar packages are: class-transformer and TypedJSON); instead, with
- it supports more advanced Object concepts such as polymorphism and Object identity;
- it supports cyclic object serialization/deserialization;
BigInt, Typed Arrays (such as
This library can be useful in more complex cases, for example when you want to:
- manipulate JSON in depth;
- preserve type information (using polymorphic type handling decorators:
@JsonTypeName. A similar package is TypedJSON);
- hide some properties for certain HTTP endpoints or some other external service;
- have different JSON response for some external application or manage different JSON data coming from other application (for example you need to communicate with a Spring Boot application that uses different JSON Schema for the same model or with other applications made with Python, PHP, etc...);
- manage cyclic references;
Most of the use cases of the Java FasterXML/jackson annotations are similar or equal.
In this article, I will present a basic example for each decorator.
The main classes that
ObjectMapper provides functionality for both reading and writing JSON and applies
jackson-js decorators. It will use instances of
JsonStringifier for implementing actual reading/writing of JSON. It has two methods:
T, based on the context given) with decorators applied.
JsonParser provides functionality for writing JSON and applies
jackson-js decorators. The main methods are:
T, based on the context given) with decorators applied;
transform(value: any, context?: JsonParserContext): any: a method for applying
JsonStringifier provides functionality for reading JSON and applies
jackson-js decorators. The main methods are:
transform(value: any, context?: JsonStringifierContext): any: a method for applying
Before we go on, I need to say that the most important decorators are:
Dateor a custom Class type.
Later, they will be explained in more detail.
@JsonAlias decorator defines one or more alternative names for a property during deserialization.
@JsonAnyGetter decorator allows the flexibility of using a Map or an Object Literal field as standard properties.
@JsonAnySetter allows us to define a logical "any setter" mutator using a non-static two-argument method to be used as a "fallback" handler for all otherwise unrecognized properties found from JSON content.
@JsonAppend can be used to add "virtual" properties to be written after regular properties.
@JsonBackReference decorators can handle parent/child relationships and work around loops.
As said before, the
[Number] for properties of type number or
[Array, [Number]] for properties of type
[Map, [String, Object]] for properties of type
Map<string, any> using
[Map, [String, Object]] or
[Array, [Set, [Object]]].
We can use the
@JsonCreator decorator to define constructors and factory methods as one to use for instantiating new instances of the associated class.
It’s very helpful when we need to deserialize some JSON that doesn’t exactly match the target entity we need to get, also with the help of the
@JsonDeserialize are used to indicates the use of a custom serializer/deserializer.
@JsonFilter can be used to indicate which logical filter is to be used for filtering out properties of type (class) decorated.
@JsonFormat is a general-purpose decorator used for configuring details of how values of properties are to be serialized.
@JsonSetter are alternatives to more general
@JsonProperty decorator to mark a method as a getter/setter method for a logical property.
@JsonIdentityInfo indicates that Object Identity should be used when serializing/deserializing values - for instance, to deal with infinite recursion type of problems.
@JsonIdentityReference can be used for customizing details of a reference to Objects for which "Object Identity" is enabled (see
@JsonIdentityInfo). The main use case is that of enforcing the use of Object Id even for the first time an Object is referenced, instead of the first instance being serialized as full Class.
@JsonIgnore is used to mark a property to be ignored at the field level during serialization and deserialization.
@JsonIgnoreProperties can be used as a class-level decorator that marks a property or a list of properties that will be ignored during serialization and deserialization.
@JsonIgnoreType indicates that all properties of decorated type are to be ignored during serialization and deserialization.
@JsonInclude can be used to exclude properties with empty/null/default values.
@JsonInject decorator is used to indicate that value of decorated property will be injected during deserialization.
@JsonNaming decorator is used to choose the naming strategies (
LOWER_DOT_CASE) for properties in serialization, overriding the default.
@JsonProperty can be used to define a non-static method as a "setter" or "getter" for a logical property or non-static object field to be used (serialized, deserialized) as a logical property.
@JsonPropertyOrder can be used to specify the order of properties on serialization.
@JsonRootName decorator is used - if wrapping is enabled - to specify the name of the root wrapper to be used.
@JsonTypeInfo: indicates details of what type information to include in serialization; API: JsonTypeInfo - decorator options JsonTypeInfoOptions;
@JsonSubTypes: indicates sub-types of the annotated type; API: JsonSubTypes - decorator options JsonSubTypesOptions;
@JsonTypeName: defines a logical type name to use for annotated class; API: JsonTypeName - decorator options JsonTypeNameOptions.
@JsonTypeId decorator is used to indicate that the annotated property should be serialized as the type id when including polymorphic type information, rather than as a regular property. That polymorphic metadata is used during deserialization to recreate objects of the same subtypes as they were before serialization, rather than of the declared supertypes.
@JsonUnwrapped defines values that should be unwrapped/flattened when serialized/deserialized.
@JsonValue decorator indicates that the value of decorated accessor (either field or "getter" method) is to be used as the single value to serialize for the instance, instead of the usual method of collecting properties of value.
@JsonView decorator is used for indicating view(s) that the property that is defined by method or field decorated is part of. If multiple View class identifiers are included, the property will be part of all of them. It is also possible to use this decorator on classes to indicate the default view(s) for properties of the type, unless overridden by per-property decorator.
In the next part ("Jackson-js: Examples for client (Angular) and server (Node.js) side (Part 2)"), I will give a simple example using
jackson-js with Angular 9 for the client side and two examples for the server side: one using Node.js + Express + SQLite3 (with Sequelize 5) and another one using Node.js + LoopBack 4.