Wondering what’s next for npm?Check out our public roadmap! »

    drupal-jsonapi-params
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.0 • Public • Published

    Drupal JSON-API Params

    Build Status codecov npm npm bundle size npm type definitions npm downloads Known Vulnerabilities

    The JSON:API is now part of Drupal Core.

    The JSON:API specifications defines standard query parameters to be used to do filtering, sorting, restricting fields that are returned, pagination and so on.

    This module provides a helper Class to create the required query. While doing so, it also tries to optimise the query by using the short form, whenever possible.

    Installation

    Install the package via npm:

    $ npm i drupal-jsonapi-params

    Usage

    import

    Import DrupalJsonApiParams from drupal-jsonapi-params

    import {DrupalJsonApiParams} from 'drupal-jsonapi-params';
    
    const apiParams = new DrupalJsonApiParams();

    require

    var drupalJsonapiParams = require("drupal-jsonapi-params")
    
    const apiParams = new drupalJsonapiParams.DrupalJsonApiParams();
    apiParams
      // Add Group within Groups.
      .addGroup('publish_status', 'OR', 'parent_group')
      .addGroup('child_group_B', 'AND', 'parent_group')
      .addGroup('parent_group', 'AND')
      // Add Filters.
      .addFilter('status', '1')
      // Add Filter to Group.
      .addFilter('status', '2', '!=', 'publish_status')
      // Add Page Limit.
      .addPageLimit(5)
      // Add Fields.
      .addFields('node--article', ['field_a.id', 'field_b.uid', 'field_c.tid'])
      // Add Includes.
      .addInclude(['field_a.id', 'field_b.uid', 'field_c.tid'])
      // Add multiple sort criterion.
      .addSort('id', 'DESC')
      .addSort('uid')
      .addSort('status');
    
    const urlencodedQueryString = apiParams.getQueryString();
    const queryString = apiParams.getQueryString({ encode: false });

    API

    getQueryString [options?]

    Returns query string which can be used in api calls. By default the output is URI encoded. Options can be passed to control the qs.stringifying internally used.

    addFilter

    Used to restrict items returned in a listing.

    Params Type Description
    path string A 'path' identifies a field on a resource
    value string string[]
    operator string (Optional) An 'operator' is a method of comparison
    group string (Optional) Name of the group, the filter belongs to

    Following values can be used for the operator. If none is provided, it assumes "=" by default.

      '=', '<>',
      '>', '>=', '<', '<=',
      'STARTS_WITH', 'CONTAINS', 'ENDS_WITH',
      'IN', 'NOT IN',
      'BETWEEN', 'NOT BETWEEN',
      'IS NULL', 'IS NOT NULL'
    

    NOTE: Make sure you match the value supplied based on the operators used as per the table below

    Value Type Operator Description
    string =, <>, >, >=, <, <=, STARTS_WITH, CONTAINS, ENDS_WITH
    string[] IN, NOT IN
    string[] size 2 BETWEEN, NOT BETWEEN The first item is used for min (start of the range), and the second item is used for max (end of the range).
    null IS NULL, IS NOT NULL Must use null

    Read more about filter in Drupal.org Documentation

    addGroup

    Used to group Filters. Groups can be nested too.

    Params Type Description
    name string Name of the group
    conjunction string (Optional) All groups have conjunctions and a conjunction is either AND or OR.
    memberOf string (Optional) Name of the group, this group belongs to

    addInclude

    Used to add referenced resources inside same request. Thereby preventing additional api calls.

    Params Type Description
    fields string[] Array of field names

    Read more about Includes in Drupal.org Documentation

    addSort

    Used to return the list of items in specific order.

    Params Type Description
    path string A 'path' identifies a field on a resource
    direction string Sort direction ASC or DESC

    Read more about Sort in Drupal.org Documentation

    addPageLimit

    Use to restrict max amount of items returned in the listing. Using this for pagination is tricky, and make sure you read the following document on Drupal.org to implement it correctly.

    Params Type Description
    limit number Number of items to limit to

    Read more about Pagination in Drupal.org Documentation

    addFields

    The name of this method might be miss leading. Use this to explicitely request for specific fields on an entity.

    Params Type Description
    type string Resource type
    fields string[] Array of field names in the given resource type

    addCustomParam

    Use to add custom parameter to the query.

    Params Type Description
    input object The parameter object

    E.g. usage

    apiParams
      // To add `foo=bar` to the query.
      .addCustomParam({foo: 'bar'})
      // To add `foo[bar]=baz` to the query.
      .addCustomParam({ foo: {bar: 'baz'}})
      // To add `bar[0]=a&bar[1]=b&bar[2]=c` to the query.
      .addCustomParam({ bar: ['a', 'b', 'c']})

    Helper methods

    clear

    Clears all query parameter constructed so far.

    getQueryObject

    Get object representation of the query object generated so far.

    initialize

    Re-initialize with a query string/object or another instance of DrupalJsonApiParams

    initializeWithQueryObject

    Re-initialize with previously stored data from getQueryObject

    initializeWithQueryString

    Re-initialize with previously stored data from getQueryString

    Install

    npm i drupal-jsonapi-params

    DownloadsWeekly Downloads

    436

    Version

    1.2.0

    License

    ISC

    Unpacked Size

    15.8 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar