API/PostgrestRequestStrategy

PostgrestRequestStrategy

src/strategies/postgrest-request.strategy.ts7 public methodsclass

Request strategy for the PostgREST driver

PostgREST auto-generates REST APIs from PostgreSQL schemas and is the backbone of Supabase’s data API. This strategy produces URIs in PostgREST’s native query-string format:

Filters: col=eq.val (single value) / col=in.(v1,v2,v3) (multi-value)
Order: order=col1.asc,col2.desc
Select: select=col1,col2
Pagination: limit=N&offset=M (offset derived from state.page)

The order and offset query-parameter names are PostgREST conventions and are intentionally not configurable via QueryBuilderOptions (see issue #50 MVP scope). limit, select, and filters (per-column name) honour the existing option keys.

Constructor

new PostgrestRequestStrategy(paginationMode: PaginationModeEnum)

Parameter	Type	Description
`paginationMode`	`PaginationModeEnum`	Wire-level pagination mechanism. Defaults to `PaginationModeEnum.QUERY`; `createQubee()` passes its `pagination` option through `DriverDefinition.createRequestStrategy()`.

Properties

Property	Type	Description
`capabilities`	`StrategyCapabilities`	Filters, operator filters (incl. FTS), sorts, flat select — no per-model fields, no JSON:API/Spatie-style includes, no global search (per-column FTS via the operator family covers it)

Methods

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

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)

buildPaginationHeaders()

buildPaginationHeaders(state: QueryBuilderState): Record<string, string> | null

Compute Range-Unit / Range HTTP headers for RANGE pagination mode

In QUERY mode this returns null so QueryBuilder.paginationHeaders() conveys “no headers needed” to the consumer. In RANGE mode the method converts the 1-indexed state.page + state.limit into PostgREST’s 0-indexed inclusive range (from = (page - 1) * limit, to = from + limit - 1) and returns both header values.

Parameter	Type	Description
`state`	`QueryBuilderState`	The current query builder state

Returns — { 'Range-Unit': 'items', 'Range': 'from-to' } or null

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

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

parts(state: QueryBuilderState, options: QueryBuilderOptions): string[]

Emit PostgREST-format query-string segments in canonical order: filters → operator filters → order → select → (limit + offset in QUERY mode only — RANGE mode passes pagination via headers instead)

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

Returns — Ordered query-string fragments

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