express-serializer
Serialization helper to handle arrays and property filtering for Express APIs.
Developed at the Media Engineering Institute (HEIG-VD).
Usage
The most basic usage of this module is to call your own serialization functions to serialize objects:
const express = ;const serializer = ; const router = express; router;
Arrays
Now for the interesting part. It will automatically serialize each object in an array:
// Get an array of objects to serialize.const users = first_name: 'John' last_name: 'Doe' birth_date: first_name: 'Bob' last_name: 'Smith' birth_date: ; // Use the same serialization function as before. { return firstName: userfirst_name lastName: userlast_name age: - user ;} // Each object in the array will be serialized with your function.;
Passing serialization options
Any additional options passed to the serializer as the fourth argument will also be passed to your serialization function:
{ const serialized = name: ` ` ; // Use options to customize the behavior of your serialization function. if options && optionsincludeBirthDate serializedbirthDate = userbirth_date return serialized;} // Call the serializer with options.const options = includeBirthDate: true ;;
Filtering
Properties of serialized objects can be whitelisted or blacklisted with the only
and except
options.
Filtering with options
only
and except
can be passed in the serialization options:
const user = first_name: 'John' last_name: 'Doe' birth_date: ; { return firstName: userfirst_name lastName: userlast_name age: - user ;} // Pick only the first name:; // Pick both the first and last names:; // Omit the last name:;
Filtering with query parameters
The only
and except
query parameters have the same effect if present in the HTTP request:
// Pick only the first name://// GET /api/user?only=firstName HTTP/1.1// Accept: application/json; // Pick both the first and last names://// GET /api/user?only=firstName&only=lastName HTTP/1.1// Accept: application/json; // Omit the last name://// GET /api/user?except=lastName HTTP/1.1// Accept: application/json;
Filtering complex objects
You can use a dotted notation in only
and except
to filter properties of more complex objects:
const user = first_name: 'John' last_name: 'Doe' address: city: 'Sunnydale' state: 'California' ; { return firstName: userfirst_name lastName: userlast_name address: useraddress ;} // Pick only the last name and city:const options = only: 'lastName' 'address.city' ; ; // Omit the last name and city through query parameters://// GET /api/user?except=lastName&except=address.city HTTP/1.1// Accept: application/json;
Combining filters
Properties which are both in only
and except
are not included in the serialized object:
// Pick only the first and last names,// and omit the last name and city:const options = only: 'firstName' 'lastName' except: 'lastName' 'address.city' ; ;
If only
and except
are specified both in the options and in query parameters, they are merged:
// Pick only the first and last names through options,// and omit the first name through query parameters://// GET /api/user?except=firstName HTTP/1.1// Accept: application/jsonconst options = only: 'firstName' 'lastName' ; ;
If except
is present in both the options and in query parameters, the union of all except
properties is used:
// Omit the first and last names through options, and omit the state through query parameters://// GET /api/user?except=address.state HTTP/1.1// Accept: application/jsonconst options = only: 'firstName' 'lastName' ; ;
If only
is present in both the options and in query parameters, the intersection of all only
properties is used:
// Pick the first and last names through options,// and pick the first name through query parameters://// GET /api/user?only=firstName HTTP/1.1// Accept: application/jsonconst options = only: 'firstName' 'lastName' ; ;