Easily add filtering, sorting, and pagination to your REST API through your old friend: the query string!
npm install @truepic/queryql
!GitHub Actions
QueryQL makes it easy to add filtering, sorting, and pagination to your Node.js
REST API through your old friend: the query string!
Read our introductory article
to learn more about why we wrote it and the problems it solves at
Truepic.
QueryQL works with any Node.js web framework (be it Express, Koa, etc.),
supports any query builder / ORM through _adapters_, and allows for custom
_validators_ so you can define validation in a familiar way.
Out of the box, QueryQL supports the following:
- Adapter: Knex (works with
Objection.js and other ORMs that use
Knex)
- Validator: Joi
``bash`
npm install @truepic/queryql
QueryQL takes a parsed query string (like Express' req.query) and translates
it into the appropriate function calls that your query builder / ORM understands
to filter, sort, and paginate the records.
(Make sure your framework uses a query string parser that supports nested
objects. Node.js's native
querystring module _does not_, but
a package like qs does. It's usually a simple
config change to switch.)
Let's consider an example to illustrate:
`
/images?filter[id][in][]=2&filter[id][in][]=3&filter[status]=open&sort=name&page[size]=10
`js`
{
filter: {
id: {
in: [2, 3],
},
status: 'open',
},
sort: 'name',
page: {
size: 10,
},
}
To support this query, QueryQL only requires you to define (whitelist) what's
allowed through what we call a _querier_. Here's how one might look for the
/images endpoint:
`js
const QueryQL = require('@truepic/queryql')
class ImageQuerier extends QueryQL {
defineSchema(schema) {
schema.filter('id', 'in')
schema.filter('status', '=')
schema.sort('name')
schema.page()
}
}
`
With your querier defined, you can now call it in your router / controller.
Here's how it might look in an Express route:
`js
app.get('/images', async (req, res, next) => {
const querier = new ImageQuerier(req.query, knex('images'))
let images
try {
images = await querier.run()
} catch (error) {
// Handle validation error, such as by passing to an Express error handler:
next(error)
}
res.send({ images })
})
`
Behind-the-scenes, QueryQL takes your initial query builder (knex('images')),querier.run()
and applies the following Knex chain when is called:
`js`
builder
.where('id', 'in', [2, 3])
.where('status', '=', 'open')
.orderBy('name', 'asc')
.limit(10)
.offset(0)
(Remember: While Knex is our default adapter and the query builder used in this
example, adapters can be written for any query builder / ORM.)
This is a simple example, but hopefully it illustrates how easy it is to add
filtering, sorting, and pagination to your REST API _without_ manually touching
your query builder / ORM.
Read the full documentation to learn how to add validation, customize
the queries, and more.
The only prerequisite is a compatible version of Node.js (see engines.node inpackage.json).
Install dependencies with npm:
`bash`
npm install
Jest is our testing framework of choice. We strive for
100% code coverage.
To run the tests:
`bash`
npm test
During development, it's recommended to run the tests automatically on file
change:
`bash`
npm test -- --watch [--notify]
Prettier is setup to enforce a consistent code style.
It's highly recommended to
add an integration to your editor
that automatically formats on save.
ESLint is setup with the
"recommended" rules to enforce a level
of code quality. It's also highly recommended to
add an integration to your editor
that automatically formats on save.
To run via the command line:
`bash`
npm run lint
When the development branch is ready for release,
Release It! is used to orchestrate
the release process:
`bash`
npm run release
Once the release process is complete, merge the development branch into themain` branch, which should always reflect the latest release.