Summary
JSON API client side library.
The library helps to build queries to a JSON API server.
Supported features
It can build queries for reading resource collections, individual resources by identifier and resource relationships.
Usage sample
import { QueryBuilder } from '@limoncello-framework/json-api-client';
const query = (new QueryBuilder('comments'))
.onlyFields({
type: 'comments',
fields: 'text'
})
.withFilters({
field: 'id',
operation: 'greater-than',
parameters: '10'
})
.combineFiltersWithAnd() // default and could be omitted
.withSorts({
field: 'title',
isAscending: false
})
.withIncludes('post')
.withPagination(50, 25)
.index();
console.debug(query);
Output
/comments?fields[comments]=text&filter[id][greater-than]=10&sort=-title&include=post&page[offset]=50&page[limit]=25
Installation
$ npm install --save-dev @limoncello-framework/json-api-client
or
$ yarn add --dev @limoncello-framework/json-api-client
Features
QueryBuilder
has the following interface.
interface QueryBuilderInterface {
onlyFields(...fields: FieldParameterInterface[]): QueryBuilderInterface;
withFilters(...filters: FilterParameterInterface[]): QueryBuilderInterface;
combineFiltersWithAnd(): QueryBuilderInterface;
combineFiltersWithOr(): QueryBuilderInterface;
withSorts(...sorts: SortParameterInterface[]): QueryBuilderInterface;
withIncludes(...relationships: RelationshipName[]): QueryBuilderInterface;
withPagination(offset: number, limit: number): QueryBuilderInterface;
enableEncodeUri(): QueryBuilderInterface;
disableEncodeUri(): QueryBuilderInterface;
read(index: ResourceIdentity, relationship?: RelationshipName): string;
index(): string;
}
Methods onlyFields
, withFilters
, withSorts
and withPagination
are fully shown in the example above and can accept 1 or more input parameters.
Methods combineFiltersWithAnd
/ combineFiltersWithOr
switch combining filter arguments either with AND
(default) / OR
clauses.
Methods enableEncodeUri
/ disableEncodeUri
enable and disable encoding query parameters after ?
mark in accordance with RFC 3986. By default query parameters will be encoded.
builder
.onlyFields({ ... }, { ... }, ...)
.withFilters({ ... }, { ... }, ...)
.withSorts({ ... }, { ... }, ...)
.withIncludes('...', '...', ...)
.index();
Parameter operation
in withFilters
method should have one the following values equals
, not-equals
, less-than
, less-or-equals
, greater-than
, greater-or-equals
, like
, not-like
, in
, not-in
, is-null
or not-null
.
Method index
returns multiple resource requests such as
/articles
and method read
returns individual resource requests for resources themselves or their relationships
/articles/1
/articles/1/author
More usage samples could be found in test
folder.
Testing
- Clone the repository.
- Install dependencies with
npm install
oryarn install
. - Run tests with
npm run test
oryarn test
.
Questions
Feel free to open an issue marked as 'Question' in its title.