README.md

Dynamic Query Builder Client

Dynamic query builder is able to build http query string for filtering, sorting, pagination operations. It works with DynamicQueryBuilder library.

NOTE: QueryBuilder is not able to perform http requests. It is only responsible to build query string.

NOTE: To perform http requests with query string, the builded query must be url encoded

Getting Started

All query building operations are done by QueryBuilder class. To create a new instance. Here's the constructor parameters;

export interface QueryBuilderParams {
  filters: Array<Filter>;
  sortBy?: Array<SortField>;
  pagination?: Pagination;
}

A full example would be the following;

import { QueryBuilder } from "@dynamic-query-builder";

export interface User {
  name: string;
  age: number;
}

const builder = new QueryBuilder({
  filters: [
    new NumericFilter({
      property: "age",
      value: 25,
      op: NumericFilterOperation.GreaterThan,
      logicalOperator: LogicalOperator.OrElse,
    }),
    new StringFilter({
      property: "name",
      value: "Y",
      op: StringFilterOperation.StartsWith,
    }),
  ],
  pagination: new Pagination({
    offset: 0,
    count: 10,
  }),
  sortBy: [
    new SortField({
      property: "name",
      by: SortDirection.DESC,
    }),
  ],
});

const query = builder.build();
// Query will hold the following string
// o=GreaterThan|OrElse&p=age&v=25&o=StartsWith&p=name&v=Y&offset=0&count=10&s=name,desc

// Give me 10 users sorted by name descending from offset 0
// whose age is greater than 25 AND
// whose names starts with Y

Filters

The possible filters in dynamic query builder is the following;

StringFilter

String Filter is able to make string filtering;

Possible Operations

export enum StringFilterOperation {
  In = "In",
  Equals = "Equals",
  Contains = "Contains",
  NotEqual = "NotEqual",
  EndsWith = "EndsWith",
  StartsWith = "StartsWith",
}

// example
const filter = new StringFilter({
  property: "name",
  op: StringFilterOperation.StartsWith,
  value: "s",
});

Numeric Filter

Numeric Filter is able to make numeric filtering;

Possible Operations

export enum NumericFilterOperation {
  In = "In",
  Equals = "Equals",
  NotEqual = "NotEqual",
  LessThan = "LessThan",
  LessThanOrEqual = "LessThanOrEqual",
  GreaterThan = "GreaterThan",
  GreaterThanOrEqual = "GreaterThanOrEqual",
}

// example
const filter = new NumericFilter({
  property: "age",
  op: NumericFilterOperation.GreaterThan,
  value: 25,
});

Boolean Filter

Boolean Filter is able to make boolean/option filtering;

Possible Operations

export enum BooleanFilterOperation {
  Equals = "Equals",
  NotEqual = "NotEqual",
}

// example
const filter = new BooleanFilter({
  property: "isPremium",
  op: BooleanFilterOperation.Equals,
  value: true,
});

Date Filter

Date Filter is able to make date filtering;

Possible Operations

export enum DateFilterOperation {
  Equals = "Equals",
  NotEqual = "NotEqual",
  GreaterThan = "GreaterThan",
  GreaterThanOrEqual = "GreaterThanOrEqual",
  LessThan = "LessThan",
  LessThanOrEqual = "LessThanOrEqual",
}

// example
const filter = new DateFilter({
  property: "birthDate",
  op: DateFilterOperation.GreaterThan,
  value: moment("12/25/1995", "MM-DD-YYYY"),
});

// NOTE: Moment library is required for dynamic query builder

Sorting

Sorting can be done by creating SortField instance;

const field = new SortField({
  property: "age",
  by: SortDirection.DESC,
});
// The default by parameter is Ascending

Pagination

Pagination can be done by creating Pagination instance;

const pagination = new Pagination({
  offset: 10, // default value is 0
  count: 25, // default value is 25
});

Best Practices

• Always use QueryBuilder instance build() function for building query string.
• Do not use filter.build(), sortfield.build() or pagination.build() separately