@limoncello-framework/json-api-client NPM

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?fieldscomments=text&filterid=10&sort=-title&include=post&pageoffset=50&pagelimit=25

Installation

$ npm install --save-dev @limoncello-framework/json-api-client

$ 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.