Skip to content
🧱 An easy way to build a query string compatible with "spatie/laravel-query-builder".
Branch: master
Clone or download
Latest commit 00da8d7 Feb 12, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src append Feb 11, 2019
tests
.babelrc
.gitignore
.prettierignore minor changes Feb 10, 2019
.prettierrc
CONTRIBUTING.md contributing Feb 11, 2019
LICENSE.md license Feb 11, 2019
README.md
package.json

README.md

JavaScript Query Builder

JavaScript Query Builder provides an easy way to build a query string compatible with spatie/laravel-query-builder.

Install

You can install package using yarn (or npm):

yarn add js-query-builder

Usage

Usage of this package is quite convenient.

General example

Here is a simple example of query building:

import { query } from 'js-query-builder';

const url = query('/users')
    .filter('age', 20)
    .sort('-created_at', 'name')
    .include('posts', 'comments')
    .append('fullname', 'ranking')
    .fields({
        posts: ['id', 'name'],
        comments: ['id', 'content'],
    })
    .param('custom_param', 'value')
    .page(1)
    .build();

console.log(url);
// /users?append=fullname%2Cranking&custom_param=value&fields%5Bcomments%5D=id%2Ccontent&fields%5Bposts%5D=id%2Cname&filter%5Bage%5D=20&include=posts%2Ccomments&page=1&sort=-created_at%2Cname

console.log(decodeURIComponent(url));
// /users?append=fullname,ranking&custom_param=value&fields[comments]=id,content&fields[posts]=id,name&filter[age]=20&include=posts,comments&page=1&sort=-created_at,name

Making requests

This package does not provide ability to make requests because there is no need. You are not limited to any particular HTTP client. Use can use the one use want.

Here is an example with axios:

import axios from 'axios';
import { query } from 'js-query-builder';

const activeUsers = axios.get(
    query('/users')
        .filter('status', 'active')
        .sort('-id')
        .page(1)
        .build()
);

Conditions

Let's imagine that you need to filter by username only if its length is more that 3 symbols.

Yeah, you can do it like this:

import { query } from 'js-query-builder';

const username = 'hi';

const q = query('/users');

if (username.length > 3) {
    q.filter('name', username);
}

const url = q.build();

But in such case it would be better to chain .when() method:

import { query } from 'js-query-builder';

const username = 'hi';

const url = query('/users')
    .when(
        username.length > 3,
        q => q.filter('name', username)
    )
    .build();

Looks much more clear, does not it?

Tapping

Sometimes you may want to tap the builder. .tap() method is almost the same as .when() but does not require condition.

import { query } from 'js-query-builder';

const url = query('/users')
    .sort('id')
    .tap(q => {
        console.log(q.build());
    })
    .include('comments')
    .build();

Forgetting

You need to forget some filters, sorts, includes etc.?

Here you are:

import { query } from 'js-query-builder';

const url = query('/users')
    .include('comments', 'posts')
    .sort('name')
    .forgetInclude('comments')
    .build();

Customizing parameter names

There may be cases when you need to customize parameter names.

You can define custom parameter names globally this way:

import { query, QueryBuilder } from 'js-query-builder';

// you may make such call is application bootstrapping file
QueryBuilder.defineCustomParameterNames({
    page: 'p',
    sort: 's',
});

const url = query('/users')
    .sort('name')
    .page(5)
    .tap(q => console.log(decodeURIComponent(q.build())));

// /users?p=5&s=name

Testing

yarn run test

Contributing

Please see CONTRIBUTING for details.

Credits

Inspired by robsontenorio/vue-api-query.

License

The MIT License (MIT). Please see License File for more information.

You can’t perform that action at this time.