{"id":14968606,"url":"https://github.com/d34dman/drupal-jsonapi-params","last_synced_at":"2025-04-04T15:07:04.614Z","repository":{"id":42967775,"uuid":"241464154","full_name":"d34dman/drupal-jsonapi-params","owner":"d34dman","description":"A package to manage json-api params","archived":false,"fork":false,"pushed_at":"2024-10-18T10:32:28.000Z","size":910,"stargazers_count":59,"open_issues_count":3,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-30T03:40:09.742Z","etag":null,"topics":["drupal","drupal-10","drupal-11","drupal-8","drupal-9","json-api"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d34dman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-18T20:48:34.000Z","updated_at":"2024-10-18T10:32:32.000Z","dependencies_parsed_at":"2023-09-24T17:21:28.877Z","dependency_job_id":"38d1221e-2e42-4403-8fae-168c1a874664","html_url":"https://github.com/d34dman/drupal-jsonapi-params","commit_stats":{"total_commits":158,"total_committers":10,"mean_commits":15.8,"dds":0.379746835443038,"last_synced_commit":"0206203d283c1375e8626c075d7adb10d3e60f69"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d34dman%2Fdrupal-jsonapi-params","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d34dman%2Fdrupal-jsonapi-params/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d34dman%2Fdrupal-jsonapi-params/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d34dman%2Fdrupal-jsonapi-params/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d34dman","download_url":"https://codeload.github.com/d34dman/drupal-jsonapi-params/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198449,"owners_count":20900079,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["drupal","drupal-10","drupal-11","drupal-8","drupal-9","json-api"],"created_at":"2024-09-24T13:40:17.576Z","updated_at":"2025-04-04T15:07:04.578Z","avatar_url":"https://github.com/d34dman.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Drupal JSON-API Params\n\n![GitHub pages build status](https://img.shields.io/github/actions/workflow/status/d34dman/drupal-jsonapi-params/typedoc.yml?style=flat-square\u0026label=Build)\n![Codecov](https://img.shields.io/codecov/c/github/d34dman/drupal-jsonapi-params?style=flat-square\u0026logo=codecov)\n[![npm](https://img.shields.io/npm/v/drupal-jsonapi-params?style=flat-square)](https://www.npmjs.com/package/drupal-jsonapi-params)\n![npm package minimized gzipped size](https://img.shields.io/bundlejs/size/drupal-jsonapi-params?style=flat-square)\n![npm type definitions](https://img.shields.io/npm/types/drupal-jsonapi-params?style=flat-square)\n[![npm downloads](https://img.shields.io/npm/dt/drupal-jsonapi-params.svg?maxAge=2592000\u0026style=flat-square)](http://npmjs.com/package/drupal-jsonapi-params)\n\nThe [JSON:API](https://jsonapi.org/) is part of [Drupal](https://www.drupal.org/) Core.\n\nThe JSON:API specifications defines standard query parameters to be used to do filtering, sorting, restricting fields that are returned, pagination and so on.\n\nThis 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.\n\n  [![API Reference](https://img.shields.io/github/actions/workflow/status/d34dman/drupal-jsonapi-params/typedoc.yml?label=API%20Reference\u0026logo=GitHub\u0026style=for-the-badge)](https://d34dman.github.io/drupal-jsonapi-params/)\n## Installation\n\nInstall the package via `npm`:\n\n```sh\n$ npm i drupal-jsonapi-params\n```\n\n## Usage\n\n### import\n\nImport `DrupalJsonApiParams` from `drupal-jsonapi-params`\n```js\nimport {DrupalJsonApiParams} from 'drupal-jsonapi-params';\n\nconst apiParams = new DrupalJsonApiParams();\n```\n\n### require\n\n```js\nvar drupalJsonapiParams = require(\"drupal-jsonapi-params\")\n\nconst apiParams = new drupalJsonapiParams.DrupalJsonApiParams();\n```\n\n```js\napiParams\n  // Add Group within Groups.\n  .addGroup('publish_status', 'OR', 'parent_group')\n  .addGroup('child_group_B', 'AND', 'parent_group')\n  .addGroup('parent_group', 'AND')\n  // Add Filters.\n  .addFilter('status', '1')\n  // Add Filter to Group.\n  .addFilter('status', '2', '!=', 'publish_status')\n  // Add Page Limit.\n  .addPageLimit(5)\n  // Add Page Offset.\n  .addPageOffset(20)\n  // Add Fields.\n  .addFields('node--article', ['field_a.id', 'field_b.uid', 'field_c.tid'])\n  // Add Includes.\n  .addInclude(['field_a.id', 'field_b.uid', 'field_c.tid'])\n  // Add multiple sort criterion.\n  .addSort('id', 'DESC')\n  .addSort('uid')\n  .addSort('status');\n\nconst urlencodedQueryString = apiParams.getQueryString();\nconst queryString = apiParams.getQueryString({ encode: false });\n\n```\n\n## API\n\n### getQueryString [options?]\n\nReturns 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](https://github.com/ljharb/qs#stringifying) internally used.\n\n### addFilter\n\nUsed to restrict items returned in a listing.\n\n| Params | Type | Description |\n| ---   | ---  | ---         |\n| path     | `string` | A 'path' identifies a field on a resource\n| value    | `string` | string[] | null` | A 'value' is the thing you compare against. For operators like \"IN\" which supports multiple parameters, you can supply an array.\n| operator | `string` | (Optional) An 'operator' is a method of comparison \n| group    | `string` | (Optional) Name of the group, the filter belongs to\n\n\nFollowing values can be used for the operator. If none is provided, it assumes \"`=`\" by default.\n\n```\n  '=', '\u003c\u003e',\n  '\u003e', '\u003e=', '\u003c', '\u003c=',\n  'STARTS_WITH', 'CONTAINS', 'ENDS_WITH',\n  'IN', 'NOT IN',\n  'BETWEEN', 'NOT BETWEEN',\n  'IS NULL', 'IS NOT NULL'\n```\n\n**NOTE: Make sure you match the value supplied based on the operators used as per the table below**\n\n| Value Type | Operator | Description |\n| ---   | ---  | ---         |\n| `string`     | `=`, `\u003c\u003e`, `\u003e`, `\u003e=`, `\u003c`, `\u003c=`, `STARTS_WITH`, `CONTAINS`, `ENDS_WITH` | |\n| `string[]`    | `IN`, `NOT IN` | |\n| `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).\n| `null`    | `IS NULL`, `IS NOT NULL` | Must use `null`\n\n\n[Read more about filter in Drupal.org Documentation](https://www.drupal.org/docs/8/core/modules/jsonapi-module/filtering)\n\n### addGroup\n\nUsed to group Filters. Groups can be nested too.\n\n|Params | Type | Description |\n| ---   | ---  | ---         |\n| name        | `string` | Name of the group\n| conjunction | `string` | (Optional) All groups have conjunctions and a conjunction is either `AND` or `OR`.\n| memberOf    | `string` | (Optional) Name of the group, this group belongs to\n\n### addInclude\n\nUsed to add referenced resources inside same request. Thereby preventing additional api calls.\n\n|Params | Type | Description |\n| ---   | ---  | ---         |\n| fields | `string[]` | Array of field names\n\n[Read more about Includes in Drupal.org Documentation](https://www.drupal.org/docs/8/modules/jsonapi/includes)\n\n### addSort\n\nUsed to return the list of items in specific order.\n\n|Params | Type | Description |\n| ---   | ---  | ---         |\n| path      | `string` | A 'path' identifies a field on a resource\n| direction | `string` | Sort direction `ASC` or `DESC`\n\n[Read more about Sort in Drupal.org Documentation](https://www.drupal.org/docs/8/modules/jsonapi/sorting)\n\n### addPageLimit\n\nUse 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.\n\n|Params | Type | Description |\n| ---   | ---  | ---         |\n| limit | `number` | Number of items to limit to |\n\n[Read more about Pagination in Drupal.org Documentation](https://www.drupal.org/docs/8/core/modules/jsonapi-module/pagination)\n\n\n### addPageOffset\n\nUse to skip some items items from start of the listing. Please note that this is not the page number. To get the offset number for a page you can\nmultiply the number of pages you want to skip with items per page.\n\n|Params | Type | Description |\n| ---   | ---  | ---         |\n| offset | `number` | Number of items to skip to |\n\n[Read more about Pagination in Drupal.org Documentation](https://www.drupal.org/docs/8/core/modules/jsonapi-module/pagination)\n\n**NOTE**\n\nJSON:API response have pagination information build into the response. Based on the results in the response, you can get \"previous\" and \"next\" links which can be used\nto get further items when results overflows into multiple pages.\n\nIf you are looking for a practical guide, you can check out the example in this issue on GitHub https://github.com/d34dman/drupal-jsonapi-params/issues/40\n\n\n### addFields\n\nThe name of this method might be misleading. Use this to explicitely request for specific fields on an entity.\n\n|Params | Type | Description |\n| ---   | ---  | ---         |\n| type   | `string`   | Resource type\n| fields | ``string[]`` | Array of field names in the given resource type\n\n---\n### addCustomParam\n\nUse to add custom parameter to the query.\n\n|Params | Type | Description |\n| ---   | ---  | ---         |\n| input | `object` | The parameter object |\n\nE.g. usage\n\n```js\napiParams\n  // To add `foo=bar` to the query.\n  .addCustomParam({foo: 'bar'})\n  // To add `foo[bar]=baz` to the query.\n  .addCustomParam({ foo: {bar: 'baz'}})\n  // To add `bar[0]=a\u0026bar[1]=b\u0026bar[2]=c` to the query.\n  .addCustomParam({ bar: ['a', 'b', 'c']})\n```\n\n\n## Helper methods\n\n### clear\n\nClears all query parameter constructed so far.\n\n### getQueryObject\n\nGet object representation of the query object generated so far.\n\n### initialize\n\nRe-initialize with a query string/object or another instance of DrupalJsonApiParams\n\n### initializeWithQueryObject\n\nRe-initialize with previously stored data from `getQueryObject`\n\n### initializeWithQueryString\n\nRe-initialize with previously stored data from `getQueryString`.\nThis method accepts an optional parameter to pass options to `qs` library when parsing the given query.\n\nPlease refer to https://www.npmjs.com/package/qs for more info about available options.\n\nThis would override any options set using setQsOptions during the given call.\n\n### setQsOption\n\nSet options that is passed to `qs` library when parsing/serializing query paramters.\nPlease refer to https://www.npmjs.com/package/qs for more info about available options.\n\n### getQsOption\n\nGet options that is passed to qs library when parsing/serializing query paramters. The value should match whatever was previously set via `setQsOptions` method.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd34dman%2Fdrupal-jsonapi-params","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd34dman%2Fdrupal-jsonapi-params","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd34dman%2Fdrupal-jsonapi-params/lists"}