Skip to content
qubeequbee
API/RansackRequestStrategy

RansackRequestStrategy

src/strategies/ransack-request.strategy.ts6 public methodsclass

Request strategy for the Ransack (Rails) driver

Generates URIs in Ransack’s search-matcher format, every condition nested under the q search key as q[<attribute>_<predicate>]:

  • Filters: q[field_eq]=value; several values become repeated q[field_in][]=a&q[field_in][]=b keys, because Ransack never splits a comma-separated string (q[field_in]=a,b matches the literal 'a,b')
  • Operator filters: q[field_<predicate>]=value, translated from FilterOperatorEnum — GTE→_gteq, LTE→_lteq, NOT→_not_eq / _not_in[], ILIKE→_i_cont, SW→_start, BTW→_gteq + _lteq, NULL→_null=1 / _not_null=1
  • Sorts: q[s][]=field+asc&q[s][]=field+desc, the array form Rails’ sort_link emits; a comma-joined q[s] string is not parsed as two sorts
  • Pagination: page + limit, the defaults of Pagy. Ransack itself does not paginate; for Kaminari set request: { limit: 'per_page' }

Ransack has no field selection, includes or global search. A search across columns is a combinator attribute name instead: title_or_body with ILIKE emits q[title_or_body_i_cont]=term.

CONTAINS maps to _cont, which Ransack 6.0 made case-sensitive on PostgreSQL; use ILIKE (_i_cont, built in since Ransack 2.4) to ignore case. An attribute with no predicate suffix is silently ignored by Ransack, which is why a simple filter always carries _eq.

Constructor

Section titled “Constructor”
new RansackRequestStrategy()

Properties

Section titled “Properties”
Property Type Description
capabilities StrategyCapabilities Filters, operator filters and sorts — no select, fields, includes, embedded resources or global search, none of which Ransack has

Methods

Section titled “Methods”

assertResource()

Section titled “assertResource()”
assertResource(state: QueryBuilderState): void

Throw if the resource is not set on the state

Centralises the message that was previously copy-pasted across four of the five concrete strategies.

Parameter Type Description
state QueryBuilderState The current query builder state

baseUri()

Section titled “baseUri()”
baseUri(state: QueryBuilderState): string

Compute the base path (no query string)

Exactly one slash joins the two: trailing slashes on the base URL and leading slashes on the resource are dropped, so /projects/42/tasks never becomes the protocol-relative //projects/42/tasks. A trailing slash on the resource is kept, for backends whose routes end in one. Nothing is encoded.

Parameter Type Description
state QueryBuilderState The current query builder state

Returns — The base URI without the query separator (e.g. /users or https://api.example.com/users)

buildUri()

Section titled “buildUri()”
buildUri(state: QueryBuilderState, options: QueryBuilderOptions): string

Compose the full request URI from the given state

Template method: validates the resource, computes the base path, delegates the per-driver query-string segments to parts(...), and joins them with the conventional ?/& separators.

parts(...) receives the state with filter values, operator-filter values and the search term already percent-encoded (see encodeValues), so no concrete strategy encodes on its own and none can forget to.

Parameter Type Description
state QueryBuilderState The current query builder state
options QueryBuilderOptions The query parameter key name configuration

Returns — The composed URI string

join()

Section titled “join()”
join(base: string, segments: string[]): string

Glue the base URI and the per-driver query-string segments

Returns the bare base when no segments were emitted (e.g. PostgREST in RANGE mode with no filters), otherwise joins with ? + &.

Parameter Type Description
base string The base URI from _baseUri
segments string[] The query-string fragments from parts(...)

Returns — The full URI

parts()

Section titled “parts()”
parts(state: QueryBuilderState, options: QueryBuilderOptions): string[]

Emit Ransack-format query-string segments in canonical order: filters → operator filters → sorts → page → limit

Parameter Type Description
state QueryBuilderState The current query builder state
options QueryBuilderOptions The query parameter key name configuration; only page and limit are read, since the q hash is fixed by Ransack

Returns — Ordered query-string fragments

validateLimit()

Section titled “validateLimit()”
validateLimit(limit: number): void

Validate that a limit value is acceptable for this driver

Default policy: positive integer. Drivers that recognise a sentinel (NestJS treats -1 as “fetch all”) override this method.

Parameter Type Description
limit number The limit value to validate