API Transformer Provider for the AdonisJs framework. This library provides a presentation and transformation layer for complex data output.
- Create a “barrier” between source data and output, so changes to your models do not affect API response
- Include relationships for complex data structures
- Manipulate and typecast data in one place only
- Installation
- Simple Example
- Resources
- Transformers
- EagerLoading
- Serializers
- Pagination
- Fluent Interface
- Credits
Run this command to install the package and follow the instructions in instructions.md.
adonis install adonis-bumblebeeFor the sake of simplicity, this example has been put together as one simple route function. In reality, you would create dedicated Transformer classes for each model. But we will get there, let's first have a look at this:
Route.get('/', async ({ response, transform }) => {
const users = await User.all()
return transform.collection(users, user => ({
firstname: user.first_name,
lastname: user.last_name
}))
})You may notice a few things here: First, we can import transform from the
context, and then call a method collection on it. This method is called a
resources and we will cover it in the next section. We pass our
data to this method along with a transformer. In return, we get
the transformed data back.
Resources are objects that represent data and have knowledge of a “Transformer”. There are two types of resources:
- Item - A singular resource, probably one entry in a data store
- Collection - A collection of resources
The resource accepts an object or an array as the first argument, representing the data that should be transformed. The second argument is the transformer used for this resource.
The simplest transformer you can write is a callback transformer. Just return an object that maps your data.
const users = await User.all()
return transform.collection(users, user => ({
firstname: user.first_name,
lastname: user.last_name
}))But let's be honest, this is not what you want. And we would agree with you, so let's have a look at transformer classes.
The recommended way to use transformers is to create a transformer class. This allows the transformer to be easily reused in multiple places.
You can let bumblebee generate the transformer for you by running:
adonis make:transformer UserThe command will create a new classfile in app/Transformers/. You can also
create the class yourself, you just have to make sure that the class extends
Bumblebee/Transformer and implements at least a transform method.
const BumblebeeTransformer = use('Bumblebee/Transformer')
class UserTransformer extends BumblebeeTransformer {
transform (model) {
return {
id: model.id,
firstname: model.first_name,
lastname: model.last_name
}
}
}
module.exports = UserTransformerNote: You also get the context as the second argument in the transform
method. Through this, you can access the current request or the authenticated
user.
Note: A transformer can also return a primitive type, like a string or a number, instead of an object. But keep in mind that including additional data, as covered in the next section, only work when an object is returned.
Once the transformer class is defined, it can be passed to the resource as the second argument.
const users = await User.all()
return transform.collection(users, 'UserTransformer')If the transformer was placed in the default location App/Transformers, you
can reference it by just passing the name of the transformer. If you placed the
transformer class somewhere else or use a different path for your transformers,
you may have to pass the full namespace or change the default namespace in the
config file. Lastly, you can also pass a reference to the transformer class
directly.
Note: Passing the transformer as the second argument will terminate the fluent
interface. If you want to chain more methods after the call to collection or
item you should only pass the first argument and then use the transformWith
method to define the transformer. See Fluent Interface
When transforming a model, you may want to include some additional data. For example, you may have a book model and want to include the author for the book in the same resource. Include methods let you do just that.
Includes defined in the defaultInclude getter will always be included in the
returned data.
You have to specify the name of the include by returning an array of all
includes from the defaultInclude getter. Then you create an additional method
for each include, named like in the example: include{Name}.
The include method returns a new resource, that can either be an item or a
collection. See Resources.
class BookTransformer extends BumblebeeTransformer {
static get defaultInclude () {
return [
'author'
]
}
transform (book) {
return {
id: book.id,
title: book.title,
year: book.yr
}
}
includeAuthor (book) {
return this.item(book.getRelated('author'), AuthorTransformer)
}
}
module.exports = BookTransformerNote: Just like in the transform method, you can also access to the context
through the second argument.
Note: If you want to use snake_case property names, you would still name the
include function in camelCase, but list it under defaultInclude in snake_case.
An availableInclude is almost the same as a defaultInclude, except it is not
included by default.
class BookTransformer extends BumblebeeTransformer {
static get availableInclude () {
return [
'author'
]
}
transform (book) {
return {
id: book.id,
title: book.title,
year: book.yr
}
}
includeAuthor (book) {
return this.item(book.getRelated('author'), AuthorTransformer)
}
}
module.exports = BookTransformerTo include this resource you call the include() method before transforming.
return transform.include('author').item(book, BookTransformer)These includes can be nested with dot notation too, to include resources within other resources.
return transform.include('author,publisher.something').item(book, BookTransformer)In addition to the previously mentioned include method, you can also enable
parseRequest in the config file. Now bumblebee will automatically parse the
?include= GET parameter and include the requested resources.
Sometimes you may want to transform some model in a slitely different way while sill utilizing existing include methods. To use out book example, you may have an api endpoint that returns a list of all books, but you don't want to include the summary of the book in this response to save on data. However, when requesting a single book you want the summary to be included.
You could define a separate transformer for this, but it would be much easier if you could reuse the existing book transformer. This is where transform variants come in play.
class BookTransformer extends BumblebeeTransformer {
transform (book) {
return {
id: book.id,
title: book.title,
year: book.yr
}
}
transformWithSummary (book) {
return {
...this.transform(book),
summary: book.summary
}
}
}
module.exports = BookTransformerWe define a transformWithSummary method that calls our existing transform
method and adds the book summary to the result.
Now we can use this variant by specifing it as follows:
return transform.collection(books, 'BookTransformer.withSummary')When you include additional models in your transformer be sure to eager load these relations as this can quickly turn into n+1 database queries. If you have defaultIncludes you should load them with your initial query. In addition, bumblebee will try to load related data if the include method is named the same as the relation.
To ensure the eager-loaded data is used, you should always use the
.getRelated() method on the model.
Sometimes you need to add just a little bit of extra information about your
model or response. For these situations, we have the meta method.
const User = use('App/Models/User')
const users = await User.all()
return transform
.meta({
access: 'limited'
})
.collection(users, UserTransformer)How this data is added to the response is dependent on the Serializer.
When dealing with large amounts of data, it can be useful to paginate your API
responses to keep them lean. Adonis provides the paginate method on the query
builder to do this on the database level. You can then pass the paginated models
to the paginate method of bumblebee and your response will be transformed
accordingly. The pagination information will be included under the pagination
namespace.
const User = use('App/Models/User')
const page = 1
const users = await User.query().paginate(page)
return transform.paginate(users, UserTransformer)After your data passed through the transformer, it has to pass through one more
layer. The Serializer will form your data into its final structure. The
default serializer is the PlainSerializer but you can change this in the
settings. For smaller APIs, the PlainSerializer works fine, but for larger
projects, you should consider the DataSerializer.
This is the simplest serializer. It does not add any namespaces to the data. It is also compatible with the default structure that you get when you return a lucid model from a route.
// Item
{
foo: 'bar'
}
// Collection
[
{
foo: bar
},
{...}
]There is one major drawback to this serializer. It does not play nicely with metadata:
// Item with meta
{
foo: 'bar',
meta: {
...
}
}
// Collection
{
data: [
{...}
],
meta: {
...
}
}Since you cannot mix an Array and Objects in JSON, the serializer has to add a
data property if you use metadata on a collection. The same is true if you use
pagination. This is why we do not recommend using PlainSerializer when using
these features. But other than that, this serializer works great for small and
simple APIs.
This serializer adds the data namespace to all of its items:
// Item
{
data: {
foo: 'bar',
included: {
data: {
name: 'test'
}
}
}
}
// Collection
{
data: [
{
foo: bar
},
{...}
]
}The advantage over the PlainSerializer is that it does not conflict with meta
and pagination:
// Item with meta
{
data: {
foo: 'bar'
},
meta: {
...
}
}
// Collection
{
data: [
{...}
],
meta: {...},
pagination: {...}
}This serializer works similarly to the DataSerializer, but it only adds the
data namespace on the first level.
// Item
{
data: {
foo: 'bar',
included: {
name: 'test'
}
}
}Bumblebee has a fluent interface for all the setter methods. This means you can
chain method calls which makes the API more readable. The following methods are
available on the transform object in the context and from Bumblebee.create()
(see below).
Chainable methods:
collection(data)item(data)null(data)paginate(data)meta(metadata)transformWith(transformer)usingVariant(variant)withContext(ctx)include(include)setSerializer(serializer)serializeWith(serializer)(alias forsetSerializer)
Terminating methods:
collection(data, transformer)item(data, transformer)paginate(data, transformer)toJSON()
You may want to use the transformer somewhere other than in a controller. You can import bumblebee directly by the following method:
const Bumblebee = use('Adonis/Addons/Bumblebee')
let transformed = await Bumblebee.create()
.collection(data)
.transformWith(BookTransformer)
.withContext(ctx)
.toJSON()You can use the same methods as in a controller. With one difference: If you
need the context inside the transformer, you have to set it with the
.withContext(ctx) method since it is not automatically injected.
Special thanks to the creator(s) of Fractal, a PHP API transformer that was the main inspiration for this package. Also, a huge thank goes to the creator(s) of AdonisJS for creating such an awesome framework.
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![greenkeeper[bot] avatar](https://avatars.githubusercontent.com/in/505?v=4 "greenkeeper[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent