@limoncello-framework/json-api-client
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.5 • Public • Published

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

    Install

    npm i @limoncello-framework/json-api-client

    DownloadsWeekly Downloads

    0

    Version

    0.1.5

    License

    Apache-2.0

    Unpacked Size

    240 kB

    Total Files

    73

    Last publish

    Collaborators

    • neomerx