Skip to main content

​
Static Methods

​
create()

Creates a new instance of RequestQueryBuilder. 
static create(params?: CreateQueryParams): RequestQueryBuilder
​
params
CreateQueryParams
Optional parameters to initialize the query builder
Example: 
// Empty builder
const qb = RequestQueryBuilder.create();

// With initial parameters
const qb = RequestQueryBuilder.create({
  fields: ['id', 'name'],
  limit: 10
});

​
setOptions()

Sets global configuration options for all RequestQueryBuilder instances. 
static setOptions(options: RequestQueryBuilderOptions): void
​
options
RequestQueryBuilderOptions
required
Configuration options including delimiters and parameter name mappings
Example: 
RequestQueryBuilder.setOptions({
  delim: '||',
  delimStr: ',',
  paramNamesMap: {
    fields: 'select',
    limit: 'per_page'
  }
});

​
getOptions()

Returns the current global configuration options. 
static getOptions(): RequestQueryBuilderOptions
Example: 
const currentOptions = RequestQueryBuilder.getOptions();
console.log(currentOptions.delim); // '||'

​
Instance Methods

​
query()

Generates the final query string from the built query object. 
query(encode?: boolean): string
​
encode
boolean
default:true
Whether to URL-encode the query string
Returns: The generated query string Example: 
const qb = RequestQueryBuilder.create()
  .select(['id', 'name'])
  .setLimit(10);

const encoded = qb.query();        // fields=id%2Cname&limit=10
const raw = qb.query(false);       // fields=id,name&limit=10
If search() has been called, the filter and or parameters will be removed from the query object before generating the string.

​
select()

Specifies which fields to include in the response. 
select(fields: QueryFields): this
​
fields
string[]
required
Array of field names to select
Returns: The builder instance for chaining Example: 
RequestQueryBuilder.create()
  .select(['id', 'name', 'email', 'createdAt'])
  .query();

// Result: fields=id,name,email,createdAt
Sets a complex search condition with support for nested AND/OR logic. 
search(s: SCondition): this
​
s
SCondition
required
Search condition object with field operators and logical combinations
Returns: The builder instance for chaining Example: 
RequestQueryBuilder.create()
  .search({
    name: { $cont: 'John' },
    age: { $gte: 18 },
    $or: [
      { status: 'active' },
      { verified: true }
    ]
  })
  .query();
When search() is used, it overrides any filter or or conditions. These will not be included in the final query string.

​
setFilter()

Adds filter conditions (all must match - AND logic). 
setFilter(f: QueryFilter | QueryFilterArr | Array<QueryFilter | QueryFilterArr>): this
​
f
QueryFilter | QueryFilterArr | Array
Single filter, filter array, or array of filters
Returns: The builder instance for chaining Types:
  • QueryFilter: { field: string, operator: ComparisonOperator, value?: any }
  • QueryFilterArr: [string, ComparisonOperator, any?]
Example: 
// Object notation
RequestQueryBuilder.create()
  .setFilter({ field: 'status', operator: '$eq', value: 'active' })
  .query();

// Array notation
RequestQueryBuilder.create()
  .setFilter(['status', '$eq', 'active'])
  .query();

// Multiple filters
RequestQueryBuilder.create()
  .setFilter([
    { field: 'status', operator: '$eq', value: 'active' },
    { field: 'verified', operator: '$eq', value: true }
  ])
  .query();

// Result: filter=status||$eq||active&filter=verified||$eq||true

​
setOr()

Adds OR filter conditions (at least one must match). 
setOr(f: QueryFilter | QueryFilterArr | Array<QueryFilter | QueryFilterArr>): this
​
f
QueryFilter | QueryFilterArr | Array
Single filter, filter array, or array of filters
Returns: The builder instance for chaining Example: 
RequestQueryBuilder.create()
  .setOr([
    { field: 'priority', operator: '$eq', value: 'high' },
    { field: 'priority', operator: '$eq', value: 'urgent' }
  ])
  .query();

// Result: or=priority||$eq||high&or=priority||$eq||urgent

​
setJoin()

Joins related entities and optionally selects specific fields from them. 
setJoin(j: QueryJoin | QueryJoinArr | Array<QueryJoin | QueryJoinArr>): this
​
j
QueryJoin | QueryJoinArr | Array
Join configuration(s)
Returns: The builder instance for chaining Types:
  • QueryJoin: { field: string, select?: string[] }
  • QueryJoinArr: [string, string[]?]
Example: 
// Join without field selection
RequestQueryBuilder.create()
  .setJoin({ field: 'profile' })
  .query();
// Result: join=profile

// Join with field selection
RequestQueryBuilder.create()
  .setJoin({ field: 'posts', select: ['id', 'title', 'createdAt'] })
  .query();
// Result: join=posts||id,title,createdAt

// Multiple joins
RequestQueryBuilder.create()
  .setJoin([
    { field: 'profile' },
    { field: 'posts', select: ['id', 'title'] },
    ['comments', ['id', 'text']]
  ])
  .query();

​
sortBy()

Sorts results by one or more fields. 
sortBy(s: QuerySort | QuerySortArr | Array<QuerySort | QuerySortArr>): this
​
s
QuerySort | QuerySortArr | Array
Sort configuration(s)
Returns: The builder instance for chaining Types:
  • QuerySort: { field: string, order: 'ASC' | 'DESC' }
  • QuerySortArr: [string, 'ASC' | 'DESC']
Example: 
// Single sort
RequestQueryBuilder.create()
  .sortBy({ field: 'createdAt', order: 'DESC' })
  .query();
// Result: sort=createdAt,DESC

// Array notation
RequestQueryBuilder.create()
  .sortBy(['name', 'ASC'])
  .query();

// Multiple sort fields
RequestQueryBuilder.create()
  .sortBy([
    { field: 'priority', order: 'DESC' },
    { field: 'createdAt', order: 'ASC' }
  ])
  .query();
// Result: sort=priority,DESC&sort=createdAt,ASC

​
setLimit()

Limits the number of results returned. 
setLimit(n: number): this
​
n
number
required
Maximum number of records to return
Returns: The builder instance for chaining Example: 
RequestQueryBuilder.create()
  .setLimit(25)
  .query();
// Result: limit=25

​
setOffset()

Sets the offset for pagination (number of records to skip). 
setOffset(n: number): this
​
n
number
required
Number of records to skip
Returns: The builder instance for chaining Example: 
RequestQueryBuilder.create()
  .setLimit(25)
  .setOffset(50)
  .query();
// Result: limit=25&offset=50

​
setPage()

Sets the page number for page-based pagination. 
setPage(n: number): this
​
n
number
required
Page number (1-based)
Returns: The builder instance for chaining Example: 
RequestQueryBuilder.create()
  .setLimit(25)
  .setPage(3)
  .query();
// Result: limit=25&page=3
Use either setOffset() or setPage() for pagination, not both. Page-based pagination is often more intuitive for users.

​
resetCache()

Resets the cache by setting the cache parameter to 0. 
resetCache(): this
Returns: The builder instance for chaining Example: 
RequestQueryBuilder.create()
  .resetCache()
  .query();
// Result: cache=0

​
setIncludeDeleted()

Includes soft-deleted records in the results. 
setIncludeDeleted(n: number): this
​
n
number
required
Value to set (typically 1 to include deleted records)
Returns: The builder instance for chaining Example: 
RequestQueryBuilder.create()
  .setIncludeDeleted(1)
  .query();
// Result: include_deleted=1

​
cond()

Converts a filter object to a condition string. This is mainly used internally but can be useful for custom implementations. 
cond(f: QueryFilter | QueryFilterArr, cond?: 'filter' | 'or' | 'search'): string
​
f
QueryFilter | QueryFilterArr
required
Filter to convert
​
cond
'filter' | 'or' | 'search'
default:"search"
Condition type for validation
Returns: Formatted condition string Example: 
const qb = RequestQueryBuilder.create();
const condStr = qb.cond({ field: 'status', operator: '$eq', value: 'active' });
// Result: 'status||$eq||active'

const condStr2 = qb.cond(['age', '$gte', 18]);
// Result: 'age||$gte||18'

​
Method Chaining

All instance methods (except query() and cond()) return this, allowing for fluent method chaining: 
const queryString = RequestQueryBuilder.create()
  .select(['id', 'name', 'email', 'status'])
  .setFilter({ field: 'isActive', operator: '$eq', value: true })
  .setJoin({ field: 'profile', select: ['avatar', 'bio'] })
  .sortBy({ field: 'createdAt', order: 'DESC' })
  .setLimit(20)
  .setPage(1)
  .query();

Build docs developers (and LLMs) love

Get started for freeTalk to us