QueryBuilder

src/services/query-builder.ts35 public methodsclass

Constructor

new QueryBuilder(store: QubeeStore, requestStrategy: IRequestStrategy, options: QueryBuilderOptions, driver?: 'api-platform' | 'directus' | 'drf' | 'feathers' | 'json-api' | 'json-server' | 'laravel' | 'nestjs' | 'nestjsx-crud' | 'odata' | 'payload' | 'pocketbase' | 'postgrest' | 'sieve' | 'spatie' | 'spring' | 'strapi' | 'wordpress')

Parameter	Type	Description
`store`	`QubeeStore`	State container holding the query being built
`requestStrategy`	`IRequestStrategy`	Driver strategy that turns state into a URI
`options`	`QueryBuilderOptions`	Query parameter key names for the active driver
`driver`	`'api-platform' \| 'directus' \| 'drf' \| 'feathers' \| 'json-api' \| 'json-server' \| 'laravel' \| 'nestjs' \| 'nestjsx-crud' \| 'odata' \| 'payload' \| 'pocketbase' \| 'postgrest' \| 'sieve' \| 'spatie' \| 'spring' \| 'strapi' \| 'wordpress'`	Active driver id, used to name it in capability errors

Methods

addEmbedded()

addEmbedded(relation: string, columns: string[]): this

Add an embedded resource to the select statement (PostgREST only)

Splices relation(col1,col2) into the single select= query parameter alongside flat columns from addSelect. Omit the columns to project all of them (relation(*)):

qb.addEmbedded('author', 'id', 'name')
  .addEmbedded('comments')
  .addSelect('title');
// → select=title,author(id,name),comments(*)

Calling repeatedly with the same relation merge-dedups the columns. Does not reset the page (column shape change, not record-set change).

Parameter	Type	Description
`relation`	`string`	The related table / foreign-key name as PostgREST sees it
`columns`	`string[]`	Optional column projection; omit for `relation(*)`

addFields()

addFields(model: string, fields: string[]): this

Add fields to the select statement for the given model (JSON:API and Spatie only)

Parameter	Type	Description
`model`	`string`	Model that holds the fields
`fields`	`string[]`	Fields to select

addFilter()

addFilter(field: string, values: (string | number | boolean)[]): this

Add a filter with the given value(s) (JSON:API, NestJS, PostgREST, and Spatie)

Produces: filter[field]=value (JSON:API / Spatie) or filter.field=value (NestJS)

Parameter	Type	Description
`field`	`string`	Name of the field to filter
`values`	`(string \| number \| boolean)[]`	The needle(s)

addFilterOperator()

addFilterOperator(field: string, operator: FilterOperatorEnum, values: (string | number | boolean)[]): this

Add a filter with an explicit operator (NestJS and PostgREST)

Produces: filter.field=$operator:value

Parameter	Type	Description
`field`	`string`	Name of the field to filter
`operator`	`FilterOperatorEnum`	The filter operator to apply
`values`	`(string \| number \| boolean)[]`	The value(s) for the filter

addIncludes()

addIncludes(models: string[]): this

Add related entities to include in the request (JSON:API and Spatie only)

Parameter	Type	Description
`models`	`string[]`	Models to include

addSelect()

addSelect(fields: string[]): this

Add flat field selection (NestJS and PostgREST)

Produces: select=col1,col2

Parameter	Type	Description
`fields`	`string[]`	Fields to select

addSort()

addSort(field: string, order: SortEnum): this

Add a field with a sort criteria (JSON:API, NestJS, PostgREST, and Spatie)

Parameter	Type	Description
`field`	`string`	Field to use for sorting
`order`	`SortEnum`	A value from the SortEnum enumeration

currentPage()

currentPage(): number

Get the current page number

Returns — The current page number

deleteEmbedded()

deleteEmbedded(relations: string[]): this

Remove embedded resources from the current query builder state (PostgREST only)

Removes the whole relation entry, columns included.

Parameter	Type	Description
`relations`	`string[]`	Relation names to remove

deleteFields()

deleteFields(fields: Fields): this

Delete selected fields for the given models in the current query builder state (JSON:API and Spatie only)

ngQubeeService.deleteFields({
  users: ['email', 'password'],
  address: ['zipcode']
});

Parameter	Type	Description
`fields`	`Fields`	Object mapping model names to field arrays to remove

deleteFieldsByModel()

deleteFieldsByModel(model: string, fields: string[]): this

Delete selected fields for the given model in the current query builder state (JSON:API and Spatie only)

ngQubeeService.deleteFieldsByModel('users', 'email', 'password');

Parameter	Type	Description
`model`	`string`	Model that holds the fields
`fields`	`string[]`	Fields to delete from the state

deleteFilters()

deleteFilters(filters: string[]): this

Remove given filters from the query builder state (JSON:API, NestJS, PostgREST, and Spatie)

Parameter	Type	Description
`filters`	`string[]`	Filters to remove

deleteIncludes()

deleteIncludes(includes: string[]): this

Remove selected related models from the query builder state (JSON:API and Spatie only)

Parameter	Type	Description
`includes`	`string[]`	Models to remove

deleteOperatorFilters()

deleteOperatorFilters(fields: string[]): this

Remove operator filters by field name (NestJS and PostgREST)

Parameter	Type	Description
`fields`	`string[]`	Field names of operator filters to remove

deleteSearch()

deleteSearch(): this

Remove search term from the query builder state (NestJS only)

deleteSelect()

deleteSelect(fields: string[]): this

Remove flat field selections from the query builder state (NestJS and PostgREST)

Parameter	Type	Description
`fields`	`string[]`	Fields to remove from selection

deleteSorts()

deleteSorts(sorts: string[]): this

Remove sort rules from the query builder state (JSON:API, NestJS, PostgREST, and Spatie)

Parameter	Type	Description
`sorts`	`string[]`	Fields used for sorting to remove

firstPage()

firstPage(): this

Navigate to the first page (page 1)

generateUri()

generateUri(): string

Build the URI for the current state using the active driver.

Synchronous: URI construction performs no I/O. ng-qubee wrapped this in an Observable purely for Angular ergonomics, and converted the throw below into a stream error; adapters can re-wrap it however their framework prefers. Subscribe to the store to be told when the result would change.

Returns — The generated URI

goToPage()

goToPage(n: number): this

Navigate directly to the specified page

Validates integer/positive via the existing setPage path, and additionally rejects values that exceed state.lastPage when pagination bounds are known.

Parameter	Type	Description
`n`	`number`	Target page number

hasNextPage()

hasNextPage(): boolean

Check whether a next page exists

Returns — true if state.page < state.lastPage when bounds are known, or true when bounds are unknown

hasPreviousPage()

hasPreviousPage(): boolean

Check whether a previous page exists

Returns — true if state.page > 1

isFirstPage()

isFirstPage(): boolean

Check whether the current page is the first page

Returns — true if state.page === 1

isLastPage()

isLastPage(): boolean

Check whether the current page is the last page

Returns — true only when state.isLastPageKnown and state.page === state.lastPage

lastPage()

lastPage(): this

Navigate to the last page known from the most recent paginated response

nextPage()

nextPage(): this

Navigate to the next page

paginationHeaders()

paginationHeaders(): Record<string, string> | null

HTTP request headers the active driver wants the consumer to apply

Returns null for drivers that pass all pagination metadata on the URL (Laravel, Spatie, JSON:API, NestJS, and PostgREST in its default QUERY mode). Returns a map of header name → value when the active driver uses HTTP headers instead — today, only the PostgREST driver configured with PaginationModeEnum.RANGE, which yields { 'Range-Unit': 'items', 'Range': 'from-to' }.

Returns — Map of headers to apply to the HTTP request, or null when not needed

previousPage()

previousPage(): this

Navigate to the previous page

reset()

reset(): this

Clear the current state and reset the Query Builder to a fresh, clean condition

setBaseUrl()

setBaseUrl(baseUrl: string): this

Set the base URL to use for composing the address

Parameter	Type	Description
`baseUrl`	`string`	The base URL

setLimit()

setLimit(limit: number): this

Set the items per page number

Validation is delegated to the active request strategy because the accepted range is driver-specific: nestjs-paginate additionally accepts -1 as a “fetch all” sentinel, while Laravel, Spatie, and JSON:API require a positive integer.

Parameter	Type	Description
`limit`	`number`	Number of items per page (or `-1` to fetch all, NestJS only)

setPage()

setPage(page: number): this

Set the page that the backend will use to paginate the result set

Parameter	Type	Description
`page`	`number`	Page number

setResource()

setResource(resource: string): this

Set the API resource to run the query against

Parameter	Type	Description
`resource`	`string`	Resource name (e.g. ‘users’ produces /users)

setSearch()

setSearch(search: string): this

Set the search term for full-text search (NestJS only)

Produces: search=term

Parameter	Type	Description
`search`	`string`	The search term

totalPages()

totalPages(): number

Get the total number of pages reported by the most recent paginated response

Returns — The last page number