@trapi/query 🌈


---
Important NOTE

This package has been replaced by another package, called: rapiq.

---

This is a library to build efficient and JSON:API like REST-APIs.

It extends the specification format between request- & response-handling based on the following parameters:
- fields
- Description: Return only specific fields or extend the default selection.
- URL-Parameter: fields
- filters
- Description: Filter the data set, according to specific criteria.
- URL-Parameter: filter
- relations
- Description: Include related resources of the primary data.
- URL-Parameter: include
- pagination
- Description: Limit the number of resources returned from the entire collection.
- URL-Parameter: page
- sort
- Description: Sort the resources according to one or more keys in asc/desc direction.
- URL-Parameter: sort

Table of Contents

- Installation
- Usage
- Build
- Parsing
- Functions
- buildQuery
- parseQuery
- parseQueryParameter
- Types
- Build
- Options
- Input
- Parse
- Options
- Input
- Output
- Parameter
- Fields
- [Filter[s]](#filters)
- Pagination/Page
- Relations/Include
- Sort

Installation

``bash
npm install @trapi/query --save
`

Usage

$3

The general idea is to construct a BuildInput object and convert it to a string
representation with the buildQuery method on the frontend side.
The result should then be provided as a URL query string to the backend application.
The backend application is then able to process the request, by parsing and interpreting the query string.

The following example should give an insight on how to use this library on the frontend side.
Therefore, a type which will represent a User and a method getAPIUsers are defined.
The method should perform a request to the resource API to receive a collection of entities.

`typescript
import axios from "axios";
import {
buildQuery,
BuildInput
} from "@trapi/query";

type Profile = {
id: number;
avatar: string;
cover: string;
}

type User = {
id: number;
name: string;
age?: number;
profile: Profile;
}

type ResponsePayload = {
data: User[],
meta: {
limit: number,
offset: number,
total: number
}
}

export async function getAPIUsers(
record: BuildInput
): Promise {
const response = await axios.get('users' + buildQuery(record));

return response.data;
}

(async () => {
const record: BuildInput = {
pagination: {
limit: 20,
offset: 10
},
filters: {
id: 1 // some possible values:
// 1 | [1,2,3] | '!1' | '~1' | ['!1',2,3] | {profile: {avatar: 'xxx.jpg'}}
},
fields: ['id', 'name'], // some possible values:
// 'id' | ['id', 'name'] | '+id' | {user: ['id', 'name'], profile: ['avatar']}
sort: '-id', // some possible values:
// 'id' | ['id', 'name'] | '-id' | {id: 'DESC', profile: {avatar: 'ASC'}}
relations: {
profile: true
}
};

const query = buildQuery(record);

// console.log(query);
// ?filter[id]=1&fields=id,name&page[limit]=20&page[offset]=10&sort=-id&include=profile

let response = await getAPIUsers(record);

// do something with the response :)
})();
`

The next section will describe, on how to parse and interpret the query string on the backend side.

$3

For explanation purposes, two simple entities with a basic relation between them are declared to demonstrate the usage on the backend side:

entities.ts
`typescript
import {
Entity,
PrimaryGeneratedColumn,
Column,
OneToOne,
JoinColumn
} from "typeorm";

@Entity()
export class User {
@PrimaryGeneratedColumn({unsigned: true})
id: number;

@Column({type: 'varchar', length: 30})
@Index({unique: true})
name: string;

@Column({type: 'varchar', length: 255, default: null, nullable: true})
email: string;

@OneToOne(() => Profile)
profile: Profile;
}

@Entity()
export class Profile {
@PrimaryGeneratedColumn({unsigned: true})
id: number;

@Column({type: 'varchar', length: 255, default: null, nullable: true})
avatar: string;

@Column({type: 'varchar', length: 255, default: null, nullable: true})
cover: string;

@OneToOne(() => User)
@JoinColumn()
user: User;
}
`

#### Parse - Detailed

In the following code snippet, all query parameter parse functions (parseQueryFields, parseQueryFilters, ...)
will be imported separately, to show the usage in detail.

`typescript
import {Request, Response} from 'express';

import {
parseQueryFields,
parseQueryFilters,
parseQueryRelations,
parseQueryPagination,
parseQuerySort,
Parameter
} from "@trapi/query";

import {
applyQueryParseOutput,
useDataSource
} from 'typeorm-extension';

import { User } from './entities';

/**
* Get many users.
*
* Request example
* - url: /users?page[limit]=10&page[offset]=0&include=profile&filter[id]=1&fields[user]=id,name
*
* Return Example:
* {
* data: [
* {id: 1, name: 'tada5hi', profile: {avatar: 'avatar.jpg', cover: 'cover.jpg'}}
* ],
* meta: {
* total: 1,
* limit: 20,
* offset: 0
* }
* }
* @param req
* @param res
*/
export async function getUsers(req: Request, res: Response) {
const {fields, filter, include, page, sort} = req.query;

const dataSource = await useDataSource();
const repository = dataSource.getRepository(User);
const query = repository.createQueryBuilder('user');

// -----------------------------------------------------

const relationsParsed = parseQueryRelations(include, {
allowed: 'profile'
});

const fieldsParsed = parseQueryFields(fields, {
defaultAlias: 'user',
// profile.id can only be used as sorting key, if the relation 'profile' is included.
allowed: ['id', 'name', 'profile.id', 'profile.avatar'],
relations: relationsParsed
});

const filterParsed = parseQueryFilters(filter, {
defaultAlias: 'user',
// profile.id can only be used as sorting key, if the relation 'profile' is included.
allowed: ['id', 'name', 'profile.id'],
relations: relationsParsed
});

const pageParsed = parseQueryPagination(page, {
maxLimit: 20
});

const sortParsed = parseQuerySort(sort, {
defaultAlias: 'user',
// profile.id can only be used as sorting key, if the relation 'profile' is included.
allowed: ['id', 'name', 'profile.id'],
relations: relationsParsed
});

// -----------------------------------------------------

// group back parsed parameter back,
// so they can applied on the db query.
const parsed = applyQueryParseOutput(query, {
fields: fieldsParsed,
// only allow filtering users by id & name
filters: filterParsed,
relations: relationsParsed,
// only allow to select 20 items at maximum.
pagination: pageParsed,
sort: sortParsed
});

// -----------------------------------------------------

const [entities, total] = await query.getManyAndCount();

return res.json({
data: {
data: entities,
meta: {
total,
...parsed.pagination
}
}
});
}
`

#### Parse - Short
Another way is to directly import the parseQuery method, which will handle a group of query parameter values & options.
The ParseInput argument of the parseQuery method accepts multiple (alias-) property keys.

`typescript
import { Request, Response } from 'express';

import {
parseQuery,
Parameter,
ParseOutput
} from '@trapi/query';

import {
applyQueryParseOutput,
useDataSource
} from 'typeorm-extension';

/**
* Get many users.
*
* ...
*
* @param req
* @param res
*/
export async function getUsers(req: Request, res: Response) {
// const {fields, filter, include, page, sort} = req.query;

const output: ParseOutput = parseQuery(req.query, {
fields: {
defaultAlias: 'user',
allowed: ['id', 'name', 'profile.id', 'profile.avatar']
},
filters: {
defaultAlias: 'user',
allowed: ['id', 'name', 'profile.id']
},
relations: {
allowed: ['profile']
},
pagination: {
maxLimit: 20
},
sort: {
defaultAlias: 'user',
allowed: ['id', 'name', 'profile.id']
}
});

const dataSource = await useDataSource();
const repository = dataSource.getRepository(User);
const query = repository.createQueryBuilder('user');

// -----------------------------------------------------

// apply parsed data on the db query.
const parsed = applyQueryParseOutput(query, output);

// -----------------------------------------------------

const [entities, total] = await query.getManyAndCount();

return res.json({
data: {
data: entities,
meta: {
total,
...output.pagination
}
}
});
}
`

#### Parse - Third Party Library

It can even be much simpler to parse the query key-value pairs with the typeorm-extension library, because it
uses this library under the hood ⚡.
This is much shorter than the previous example and has less explicit dependencies 😁.

read more

Functions

buildQuery

▸ function buildQuery<T>(record: BuildInput, options?: BuildOptions): string

Build a query string from a provided BuildInput.

#### Example
Simple

`typescript
import {
buildQuery,
Parameter
} from "@trapi/query";

type User = {
id: number,
name: string,
age?: number
}

const query: string = buildQuery({
fields: ['+age'],
relations: {
name: '~pe'
}
});

console.log(query);
// ?fields=+age&filter[name]=~pe
`

#### Type parameters

| Name | Description |
|:-------|:----------------------------------------------------------------|
| T | A type, interface, or class which represent the data structure. |


#### Parameters

| Name | Type | Description |
|:----------|:------------------|:--------------------------------------------------|
| input | BuildInput<T> | Input specification more. |
| options | BuildOptions | Options for building fields, filter, include, ... |

#### Returns

string

The function returns a string, which can be parsed with the parseQuery function.

I.e. /users?page[limit]=10&page[offset]=0&include=profile&filter[id]=1&fields[user]=id,name

parseQuery

▸ function parseQuery(input: ParseInput, options?: ParseOptions): ParseOutput

Parse a query string to an efficient data structure ⚡. The output will
be an object with each possible value of the Parameter enum as property key and the
parsed data as value.

#### Example
Simple

`typescript
import {
FieldOperator,
FilterOperator,
parseQuery,
ParseOutput,
URLParameter
} from "@trapi/query";

const output: ParseOutput = parseQuery({
fields: ['+age'],
filters: {
name: '~pe'
}
});

console.log(output);
//{
// fields: [
// {key: 'age', operator: FieldOperator.INCLUDE}
// ],
// filters: [
// {key: 'name', value: 'pe', operator: FilterOperator.LIKE}
// ]
//}
`

#### Type parameters

| Name | Description |
|:------|:------------|


#### Parameters

| Name | Type | Description |
|:----------|:---------------|:-----------------------------------------------------------------------|
| input | ParseInput | Query input data passed e.g. via URL more. |
| options | ParseOptions | Options for parsing fields, filter, include, ... more |

#### Returns

ParseOutput

The function returns an object.

parseQueryParameter

▸ function parseQueryParameter<T extends Parameter>(
key: T,
input: unknown,
options?: ParseParameterOptions
): ParseParameterOutput

Parse a specific query Parameter value to an efficient data structure ⚡.

#### Example
fields

`typescript
import {
FieldOperator,
FieldsParseOutput,
Parameter,
parseQueryParameter,
URLParameter
} from "@trapi/query";

const output: FieldsParseOutput = parseQueryParameter(
// 'fields' ||
// Parameter.FIELDS | URLParameter.FIELDS
'fields',
['+name'],
{
allowed: ['id', 'name'],
defaultAlias: 'user'
}
);

console.log(output);
// [{key: 'id', value: FieldOperator.INCLUDE}] ||
// [{key: 'id', value: '+'}]
`

filters

`typescript
import {
FiltersParseOutput,
Parameter,
parseQueryParameter,
URLParameter
} from "@trapi/query";

const output: FiltersParseOutput = parseQueryParameter(
// 'filters' | 'filter' |
// Parameter.FILTERS | URLParameter.FILTERS
'filters',
{id: 1},
{
allowed: ['id', 'name'],
defaultAlias: 'user'
}
);

console.log(output);
// [{alias: 'user', key: 'id', value: 1, }]
`

pagination

`typescript
import {
PaginationParseOutput,
Parameter,
parseQueryParameter,
URLParameter
} from "@trapi/query";

const output: PaginationParseOutput = parseQueryParameter(
// 'pagination' | 'page' |
// Parameter.PAGINATION | URLParameter.PAGINATION
'pagination',
{limit: 100},
{
maxLimit: 50
}
);

console.log(output);
// {limit: 50}
`

relations

`typescript
import {
RelationsParseOutput,
Parameter,
parseQueryParameter,
URLParameter
} from "@trapi/query";

const output: RelationsParseOutput = parseQueryParameter(
// 'relations' || 'include' ||
// Parameter.RELATIONS | URLParameter.RELATIONS
'relations',
['roles'],
{
allowed: ['roles', 'photos'],
defaultAlias: 'user'
}
);

console.log(output);
// [{key: 'user.roles', value: 'roles'}]
`

sort

`typescript
import {
SortParseOutput,
Parameter,
parseQueryParameter,
URLParameter
} from "@trapi/query";

const output: SortParseOutput = parseQueryParameter(
// 'sort' ||
// Parameter.SORT || URLParameter.SORT
'sort',
['-name'],
{
allowed: ['id', 'name'],
defaultAlias: 'user'
}
);

console.log(output);
// [{alias: 'user', key: 'name', value: 'DESC'}]
`
#### Type parameters

| Name | Description |
|:------|:------------|


#### Parameters

| Name | Type | Description |
|:----------|:-----------------------------------|:-----------------------------------------------------------------------|
| input | unknown | Query input data passed e.g. via URL more. |
| options | ParseParameterOptions | Options for parsing fields, filter, include, ... more |

#### Returns

ParseOutput

The function returns an object.


Types

$3


#### BuildOptions
`typescript
export type BuildOptions = {
// empty type for now :)
}
`
#### BuildInput
`typescript
export type BuildInput<
V extends Record
> = {
[T in Parameter | URLParameter]?: BuildParameterInput
}
`

$3

#### ParseOptions

`typescript
export type ParseOptions = {
/**
* On default all query keys are enabled.
*/
[K in Parameter]?: ParseParameterOptions | boolean
}
`
ParseParameterOptions

#### ParseInput

``typescript
export type ParseInput = {
[K in Parameter | URLParameter]?: any
}
``
Parameter/URLParameter

#### ParseOutput

`typescript
export type ParseOutput = {
[K in Parameter]?: ParseParameterOutput
}
`
ParseParameterOutput

#### ParseParameter
- ParseParameterOptions
is a generic type and returns the available options for a given parameter type, e.g.
- FieldsParseOptions,
- FiltersParseOptions
- ...
- ParseParameterOutput
is a generic type and returns the parsed output data for a given parameter type, e.g.
- FieldsParseOutput
- FiltersParseOutput
- ...




$3

Parameter
`typescript
export enum Parameter {
FILTERS = 'filters',
FIELDS = 'fields',
PAGINATION = 'pagination',
RELATIONS = 'relations',
SORT = 'sort'
}

export type ParameterType = ${Parameter};
`

URLParameter
`typescript
export enum URLParameter {
FILTERS = 'filter',
FIELDS = 'fields',
PAGINATION = 'page',
RELATIONS = 'include',
SORT = 'sort'
}

export type URLParameterType = ${Parameter};
`

#### Fields

FieldsParseOptions
`typescript
export type FieldsParseOptions =
ParseOptionsBase | string[]>;
`
The type structure looks like this:
`text
{
aliasMapping?: Record,
allowed?: Record | string[],
relations?: RelationsParseOutput,
defaultAlias?: string
}
`

FieldsParseOutput
`typescript
export enum FieldOperator {
INCLUDE = '+',
EXCLUDE = '-'
}

export type FieldsParseOutputElement =
ParseOutputElementBase;
export type FieldsParseOutput =
FieldsParseOutputElement[];
`
The type structure looks like this:
`text
{
// relation/resource alias
alias?: string,

// field name
key: string,

// '+' | '-'
value?: FieldOperator
}
`

#### Filters

FiltersParseOptions
`typescript
export type FiltersParseOptions =
ParseOptionsBase
`
The type structure looks like this:
`text
{
aliasMapping?: Record,
allowed?: string[],
relations?: RelationsParseOutput,
defaultAlias?: string
}
`

FiltersParseOutput
`typescript
export enum FilterOperatorLabel {
NEGATION = 'negation',
LIKE = 'like',
IN = 'in'
}

export type FiltersParseOutputElement =
ParseOutputElementBase<
Parameter.FILTERS,
FilterValue
> & {
operator?: {
[K in FilterOperatorLabel]?: boolean
}
};
export type FiltersParseOutput = FiltersParseOutputElement[];
`
`text
{
// relation/resource alias
alias?: string,

// filter name
key: string,

// {in: ..., ...}
operator?: {
[K in FilterOperatorLabel]?: boolean
},

value: FilterValue
}
`
#### Pagination

PaginationParseOptions
`typescript
export type PaginationParseOptions =
ParseOptionsBase & {
maxLimit?: number
};
`
The type structure looks like this:
`text
{
maxLimit?: number
}
`

PaginationParseOutput
`typescript
export type PaginationParseOutput = {
limit?: number,
offset?: number
};
`

#### Relations

RelationsParseOptions

`typescript
export type RelationsParseOptions =
ParseOptionsBase;
`
The type structure looks like this:
`text
{
aliasMapping?: Record,
allowed?: string[],
defaultAlias?: string,
includeParents?: boolean | string[] | string
}
`

RelationsParseOutput
`typescript
export type RelationsParseOutputElement =
ParseOutputElementBase;
export type RelationsParseOutput = RelationsParseOutputElement[];
`
The type structure looks like this:
`text
{
// relation relative depth path
key: string,

// relation alias
value: string
}
`

#### Sort
SortParseOptions
`typescript
export type SortParseOptions = ParseOptionsBase;
`

The type structure looks like this:
`text
{
aliasMapping?: Record,
allowed?: string[] | string[][],
defaultAlias?: string
relations?: RelationsParseOutput
}
`

SortParseOutput
`typescript
export enum SortDirection {
ASC = 'ASC',
DESC = 'DESC'
}

export type SortParseOutputElement =
ParseOutputElementBase;
export type SortParseOutput = SortParseOutputElement[];
`
The type structure looks like this:
`text
{
// resource/relation alias
alias?: string,

// field name
key: string,

// 'ASC' | 'DESC'
value: SortDirection
}
``