Skip to main content

Builder API

Base Builder API​

A builder is created like new HttpQueryBuilder(). The builder instance has a fluent API, meaning you can chain methods together to create a new instance with the desired configuration.

You must configure the builder before using it. Therefore, it's important to know the available methods that can be used to configure the builder.

withClient​

withClient(client: QueryClient, options): this

Sets the query client for this builder. This is required in order to enable client and tags interfaces. Imperative operations done through those interfaces will be done with the provided query client. This method also enables the ability to sync tag invalidation with other browser tabs.

withConfig​

withConfig(config): this

Creates a new query builder with additional config. This is generally used internally and should not be used directly.

withPreprocessor​

withPreprocessor(preprocessor): this

Adds a preprocessor function to the query. The preprocessor function is called before the query function is called.

withPostprocessor​

withPostprocessor(postprocessor): this

Adds a postprocessor function to the query. The preprocessor function is called after the query function is called successfully. The postprocessor function can be used to modify the output data or the error. Note that this is a specific case of the middleware function and middleware functions can be used to handle more advanced use cases.

withMiddleware​

withMiddleware(middleware): this

Adds a middleware function to the query. The middleware function wraps the query function and can be used to modify the input variables, the output data, or the error.

A middleware has many use cases, such as:

  • Logging
  • Caching
  • Error handling
  • Retrying
  • Transforming the data
  • Adding authentication
  • Side effects

If input variables are modified, preprocessors should be preferred over middleware functions.

withTags​

withTags(tags): this

Adds a tag to the query. The tag is used to invalidate or update the query when the tag is updated. To learn more about tags, see the tag based invalidation section of the documentation.

withTagTypes​

withTagTypes<T>(): this

Declares the type of tags of the query. This is used to strongly type the tags which can be helpful when using withUpdates.

withUpdates​

withUpdates(updates): this

Adds a declarative update to the mutation. This is used to invalidate or update the queries that were marked with withTags. To learn more about tags, see the tag based invalidation section of the documentation.

withPagination​

withPagination(paginationOptions): this

Adds infinite query support to the query. Requires getNextPageParam to be passed in options. This is required in order to enable the hooks like useInfiniteQuery. Additional options can also be provided which are passed to the underlying hook.

withData​

withData<T>(): this

Declares the type of returned data of the query.

withError​

withError<T>(): this

Declares the type of error of the query.

withVars​

withVars<T>(defaults?: Partial<T>, resetVars: boolean = false): this

Declares the type of variables of the query. Optionally, you can pass the first argument to set the default variables, which will be merged with the variables passed to the query.

This method is generally used internally. If you are using a HttpQueryBuilder, you should use its specific methods such as withSearch.

asBound​

asBound(): this

Binds all query methods to this class instance, so that they can be called after object destructuring such as const { useQuery } = builder.asBound().

asFrozen​

asFrozen(): this

Returns a frozen version of this builder. The frozen version cannot be modified using with* methods, so those methods will not be available. The methods in the Query API will still be available.

client​

get client(): QueryBuilderClient

Exposes some methods to perform imperative operations on the query client, such as prefetch, invalidate, refetch, remove and more. See Client API Reference to learn more.

Note that this API is only available if withClient was called.

tags​

get tags(): QueryBuilderTagsManager

Exposes some methods to perform imperative tag operations. See Tags API Reference to learn more.

Note that this API is only available if withClient was called.

HTTP Builder API​

A HttpQueryBuilder is a subclass of the QueryBuilder and is used to create HTTP queries. The queries created by this builder will make HTTP requests with the specified configuration.

withBaseUrl​

withBaseUrl(url: string): this

Sets the base URL for the HTTP request. The base URL will be prepended to relative URLs.

withPath​

withPath(path: string): this

Sets the path for the HTTP request. The path can contain path parameters which are defined with the format /path/:param1/:param2. The path parameters are automatically extracted and typed strongly as if declared with withParams.

withMethod​

withMethod(method: HttpMethod): this

Sets the HTTP method for the request. The method can be one of the following: get, post, put, patch, delete, options, head. The default method is get.

withBody​

withBody<T>(body?: Partial<T>): this

Defines the type of body of the request. Optionally, you can pass the first argument to set the default body.

withParams​

withParams<T>(params?: Partial<T>): this

Defines the type of path parameters of the request. Optionally, you can pass the first argument to set the default parameters. Note that when withPath is used, the path parameters are automatically extracted. This method doesn't have to be used in that case.

withSearch​

withSearch<T>(search?: Partial<T>): this

Defines the type of search parameters of the request. Optionally, you can pass the first argument to set the default search parameters.

withHeaders​

withHeaders<T>(headers?: Partial<T>): this

Defines the type of headers of the request. Optionally, you can pass the first argument to set the default headers.

withMeta​

withMeta<T>(meta?: Partial<T>): this

Defines the type of metadata of the request. Optionally, you can pass the first argument to set the default metadata.

This can be used to pass additional parameters that are not part of the request. Metadata is usually used in middleware functions for advanced use cases.