json-api-query-string
Feature overview
- Parse JSON API query strings to objects
- Stringify JSON API objects to query strings
- Minimal code, with permissive
query-string
peer dependency for maximum code re-use - Encodes the specified parts of the JSON API specification (i.e.
sort
, include
and fields
) and provides a declarative syntax for customising the parts of the specification that are only reserved to contain implementation-specific details (i.e. page
and filter
) - Can be used in the browser or Node.js 6 or later
- Includes a TypeScript
index.d.ts
file - Reasonable exhaustive test suite
Basic usage
import { configure, stringify, parse } from 'json-api-query-string';
configure({
formatOptions: { filter: { arrayFormat: 'comma' }}
});
const queryObject = parse('sort=foo,bar')
queryObject
stringify({ sort: [ ...queryObject.sort, 'baz'] });
Install & Setup
json-api-query-string
can be installed as a CommonJS module:
npm install json-api-query-string --save
# OR
yarn add json-api-query-string
Because query-string
is often already used in many code bases, it's only a peer dependency of json-api-query-string
, so if it's not already installed, you'll to add it:
npm install query-string --save
# OR
yarn add query-string
sort, include and fields
These values are full specified by the JSON API specification, so json-api-query-string
comes configured for the correct behaviour:
parse('sort=')
parse('sort=foo')
parse('sort=foo,bar')
parse('sort=foo,-bar')
parse('include=')
parse('include=foo')
parse('include=foo,baz')
parse('include=foo.bar')
parse('include=foo.bar,baz')
parse('include=foo,bar.baz')
parse('fields[foo]=')
parse('fields[foo]=bar')
parse('fields[foo]=bar&fields[baz]=barp')
parse('fields[foo]=bar,zoop&fields[baz]=barp')
filter, page and other custom fields
These parameters are reserved rather than being specified, so will vary depending on the particulars of your implementation.
You can configure json-api-query-string
to correctly handle the schema globally by passing the formatOpitons
option to the configure
function:
import { configure } from 'json-api-query-string';
configure({
formatOptions: { filter: { arrayFormat: 'comma' }}
});
The keys of this hash must match your parameter name (with any square brackets removed), and the values are option passed to query-string's parse
function.
You can also perform "one-off" configuration by passing format options as a second argument to parse
or stringify
:
parse('filter[foo]=bar,baz')
parse('filter[foo]=bar,baz', { filter: { arrayFormat: 'comma' } })
Similar packages
Thank you to query-to-json-api for the original inspiration and starting point for this package.