RequestQueryBuilder Methods

Complete reference of all RequestQueryBuilder methods with signatures and examples

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

---

search()

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();