Wondering what’s next for npm?Check out our public roadmap! »

    @truepic/queryql

    0.9.0 • Public • Published

    QueryQL

    npm CircleCI piratepx

    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:

    Installation

    $ npm install @truepic/queryql

    Getting Started

    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.

    Let's consider an example to illustrate:

    /images?filter[id][in][]=2&filter[id][in][]=3&filter[status]=open&sort=name&page[size]=10
    
    {
      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:

    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:

    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')), and applies the following Knex chain when querier.run() is called:

    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.

    Development

    Prerequisites

    The only prerequisite is a compatible version of Node.js (see engines.node in package.json).

    Dependencies

    Install dependencies with npm:

    $ npm install

    Tests

    Jest is our testing framework of choice, with file-specific tests contained in the test/src directory. We strive for 100% code coverage.

    To run the tests:

    $ npm test

    During development, it's recommended to run the tests automatically on file change:

    $ npm test -- --watch [--notify]

    Code Style & Linting

    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:

    $ npm run lint

    Releasing

    After development is done in the development branch and is ready for release, it should be merged into the master branch, where the latest release code lives. Release It! is then used to interactively orchestrate the release process:

    $ npm run release

    Install

    npm i @truepic/queryql

    DownloadsWeekly Downloads

    216

    Version

    0.9.0

    License

    MIT

    Unpacked Size

    143 kB

    Total Files

    60

    Last publish

    Collaborators

    • avatar