typeorm-query-params-parser

TypeORM Query Params Parser

A simple and flexible query parameter parser for TypeORM's QueryBuilder.

Features

• Select specific fields and relations
• Join relations easily
• Sort, limit, and paginate results
• Cache queries with custom options
• Soft delete support (withDeleted)
• Advanced filtering with logical and comparison operators

Installation

npm install typeorm-query-params-parser
# or
yarn add typeorm-query-params-parser

Quick Start

import { TypeORMQueryParser } from "typeorm-query-params-parser";

const query = request.query;
const queryBuilder = createQueryBuilder(Entity, "entity");
const queryParser = new TypeORMQueryParser(queryBuilder);

queryParser.parse(query);

// Continue using `queryBuilder` as needed
const results = await queryBuilder.getMany();

Documentation

Supported Query Parameters

• select
• relations
• sort
• limit
• page
• paginate
• cache
• withDeleted
• filter

select

Specify which fields to return. Use dot notation for nested fields.

Examples:

Select id, name, and profile.id:

{ "select": ["id", "name", "profile.id"] }

Select all fields of profile:

{ "select": ["id", "name", "profile.*"] }

relations

Left join relations. Use dot notation for nested relations.

Example:

Join profile and its photo:

{ "relations": ["profile", "profile.photo"] }

sort

Sort by one or more fields. Prefix with - for descending order.

Example:

Sort by id ascending and name descending:

{ "sort": ["id", "-name"] }

limit

Set the maximum number of items returned (default: 20).

Example:

{ "limit": 100 }

page

Specify the page number for pagination (default: 1).

Example:

{ "page": 2 }

paginate

Enable or disable pagination (default: true).

Example:

{ "paginate": false }

cache

Enable/disable cache, set cache duration (ms), or provide cache ID.

Examples:

Enable cache:

{ "cache": true }

Set cache duration:

{ "cache": 1000 }

Set cache ID and duration:

{ "cache": ["my-cache-id", 1000] }

withDeleted

Include soft-deleted entities.

Example:

{ "withDeleted": true }

filter

Advanced filtering using comparison and logical operators.

Syntax

{
  "filter": {
    "<field>": { "<operator>": "<value>" }
  }
}

Supported Operators

Operator	Description
_eq	Equal to
_neq	Not equal to
_lt	Less than
_lte	Less than or equal to
_gt	Greater than
_gte	Greater than or equal to
_in	Value is in array
_null	Is null (true) or not null (false)
_contains	Contains substring
_starts_with	Starts with substring
_ends_with	Ends with substring
_between	Value is between two values
_empty	Is empty (true) or not empty (false)

Examples

Filter by name:

{
  "filter": {
    "name": { "_eq": "Erick" }
  }
}

Filter by categories:

{
  "filter": {
    "categories": { "_in": ["vegetables", "fruit"] }
  }
}

Logical Operators

Combine multiple conditions with _and or _or:

{
  "filter": {
    "_and": [
      {
        "title": { "_eq": "Readme" }
      },
      {
        "status": { "_eq": "published" }
      }
    ],
    "_or": [
      {
        "title": { "_eq": "Readme" }
      },
      {
        "status": { "_eq": "published" }
      }
    ]
  }
}

Tips

• Use the qs package to parse nested objects into query strings.