Requests

Description

Nestjsx/crud provides a full range of path and query parameters parsing/validation to help you build rich RESTful APIs. @nestjsx/crud-request is responsible for that.

Table of Contents

• Query params
  • select
  • filter
  • filter conditions
  • or
  • sort
  • join
  • limit
  • offset
  • page
  • cache
• Frontend usage
  • Customize
  • Usage

Query params

By default, we support these param names:

fields, select - get selected fields in GET result

filter[], filter - filter GET result by AND type of condition

or[], or - filter GET result by OR type of condition

join[], join - receive joined relational resources in GET result (with all or selected fields)

sort[], sort - sort GET result by some field in ASC | DESC order

per_page, limit - limit the amount of received resources

offset - offset some amount of received resources

page - receive a portion of limited amount of resources

cache - reset cache (if was enabled) and receive resources directly from the DB

Notice: You can easily map your own query params names and chose another string delimiters by applying global options.

Here is the description of each of those using default params names:

select

Selects fields that should be returned in the reponse body.

Syntax:

?fields=field1,field2,...

Example:

?fields=email,name

filter

Adds fields request condition (multiple conditions) to your request.

Syntax:

?filter=field||condition||value

?join=relation&filter=relation.field||condition||value

Notice: Using nested filter shall join relation first.

Examples:

?filter=name||eq||batman

?filter=isVillain||eq||false&filter=city||eq||Arkham (multiple filters are treated as a combination of AND type of conditions)

?filter=shots||in||12,26 (some conditions accept multiple values separated by commas)

?filter=power||isnull (some conditions don't accept value)

filter conditions

• eq (=, equal)
• ne (!=, not equal)
• gt (>, greater than)
• lt (<, lower that)
• gte (>=, greater than or equal)
• lte (<=, lower than or equal)
• starts (LIKE val%, starts with)
• ends (LIKE %val, ends with)
• cont (LIKE %val%, contains)
• excl (NOT LIKE %val%, not contains)
• in (IN, in range, accepts multiple values)
• notin (NOT IN, not in range, accepts multiple values)
• isnull (IS NULL, is NULL, doesn't accept value)
• notnull (IS NOT NULL, not NULL, doesn't accept value)
• between (BETWEEN, between, accepts two values)

or

Adds OR conditions to the request.

Syntax:

?or=field||condition||value

It uses the same filter conditions.

Rules and examples:

• If there is only one or present (without filter) then it will be interpreted as simple filter:

?or=name||eq||batman

• If there are multiple or present (without filter) then it will be interpreted as a compination of OR conditions, as follows:
  WHERE {or} OR {or} OR ...

?or=name||eq||batman&or=name||eq||joker

• If there are one or and one filter then it will be interpreted as OR condition, as follows:
  WHERE {filter} OR {or}

?filter=name||eq||batman&or=name||eq||joker

• If present both or and filter in any amount (one or miltiple each) then both interpreted as a combitation of AND conditions and compared with each other by OR condition, as follows:
  WHERE ({filter} AND {filter} AND ...) OR ({or} AND {or} AND ...)

?filter=type||eq||hero&filter=status||eq||alive&or=type||eq||villain&or=status||eq||dead

sort

Adds sort by field (by multiple fields) and order to query result.

Syntax:

?sort=field,ASC|DESC

Examples:

?sort=name,ASC

?sort=name,ASC&sort=id,DESC

join

Receive joined relational objects in GET result (with all or selected fields). You can join as many relations as allowed in your CrudOptions.

Syntax:

?join=relation

?join=relation||field1,field2,...

?join=relation1||field11,field12,...&join=relation1.nested||field21,field22,...&join=...

Examples:

?join=profile

?join=profile||firstName,email

?join=profile||firstName,email&join=notifications||content&join=tasks

?join=relation1&join=relation1.nested&join=relation1.nested.deepnested

Notice: primary field/column always persists in relational objects. To use nested relations, the parent level MUST be set before the child level like example above.

limit

Receive N amount of entities.

Syntax:

?limit=number

Example:

?limit=10

offset

Limit the amount of received resources

Syntax:

?offset=number

Example:

?offset=10

page

Receive a portion of limited amount of resources.

Syntax:

?page=number

Example:

?page=2

cache

Reset cache (if was enabled) and receive resources directly from the DB.

Usage:

?cache=0

Frontend usage

@nestjsx/crud-request is a framework agnostic package that has been designed for both backend and frontend usage. It's also used by @nestjsx/crud package in CrudRequestInterceptor.

It has RequestQueryBuilder class that helps building a query string and customizing your query params names and delimiters.

Customize

It has a static method setOptions that alows you to set different params names (defaults are shown):

import { RequestQueryBuilder } from '@nestjsx/crud-request';

RequestQueryBuilder.setOptions({
  delim: '||',
  delimStr: ',',
  paramNamesMap: {
    fields: ['fields', 'select'],
    filter: ['filter[]', 'filter'],
    or: ['or[]', 'or'],
    join: ['join[]', 'join'],
    sort: ['sort[]', 'sort'],
    limit: ['per_page', 'limit'],
    offset: ['offset'],
    page: ['page'],
    cache: ['cache'],
  },
});

Usage

import { RequestQueryBuilder, CondOperator } from '@nestjsx/crud-request';

const queryString = RequestQueryBuilder
  .create()
  .select(['foo', 'bar'])
  .setFilter({ field: 'foo', operator: CondOperator.NOT_NULL })
  .setOr({ field: 'bar', operator: CondOperator.NOT_EQUALS, value: 'test' })
  .setJoin({ field: 'company' })
  .setJoin({ field: 'profile', select: ['name', 'email'] })
  .sortBy({ field: 'bar', order: 'DECS' })
  .setLimit(20)
  .setPage(3)
  .resetCache()
  .query();