@limoncello-framework/json-api-client

Summary

JSON API client side library.

The library helps to build queries to a JSON API server.

Supported features

• Sparse Fieldsets
• Filtering
• Sorting
• Inclusion of Related Resources
• Pagination

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 or yarn install.
• Run tests with npm run test or yarn test.

Questions

Feel free to open an issue marked as 'Question' in its title.