Query helpers

TanStack Query helper functions for fetching API data, managing mutations, and configuring the query client. These utilities streamline integration with the MDK Gateway API.

Package

@tetherto/mdk-ui-foundation

Query Helpers

Import the public APIs on this page from @tetherto/mdk-ui-foundation.

appendQuery

Append query params to a URL. undefined / null values and empty arrays are skipped; array values serialize comma-separated ({ ids: ['a', 'b'] } → ?ids=a,b), the qs arrayFormat: 'comma' convention the Gateway expects, without th…

(url: string, params: Record<string, unknown>) => string

buildUrl

Join a base URL and a path, tolerating a trailing slash on the base and a missing leading slash on the path.

(base: string, path: string) => string

createBearerFetcher

Build a Fetcher that injects Authorization: Bearer <token> from the supplied token getter (defaults to authStore). Non-2xx responses throw an MdkFetchError carrying the HTTP status and parsed body.

(options: { /** Override the token source — defaults to `authStore.getState().token`. */ getToken?: () => string | null /** Override `fetch` — pass a stub in tests. */ fetchImpl?: typeof fetch } = {}…

createGetQueryFn

Build a signal-aware GET queryFn. This is the single place the AbortSignal is threaded into the fetcher: TanStack cancels a query (firing the signal) when its last observer unmounts on navigation, or when an invalidation supersedes a r…

(fetcher: Fetcher, url: string | (() => string)) => ({ signal }?: QueryFnContext) => Promise<T>

createMdkQueryClient

Build a TanStack QueryClient carrying the data-source runtime.

(options: CreateMdkQueryClientOptions = {}) => QueryClient

createResourceMutation

Build a write factory: (client, ...) => { mutationKey, mutationFn, invalidates }.

(config: ResourceMutationConfig<TBody>) => (client: QueryClient, fetcher?: Fetcher) => { mutationKey: ResourceKey; invalidates: ResourceKey[]; mutationFn: (payload: TBody) => Promise<TResponse>; }

createResourceQuery

Build a read factory: (client, input) => { queryKey, queryFn }.

(config: ResourceQueryConfig<TInput>) => (client: QueryClient, input: TInput, fetcher?: Fetcher) => { queryKey: ResourceKey; queryFn: ({ signal }?: QueryFnContext) => Promise<TResponse>; }

endpointUrl

Resolve a named endpoint against the client's map into an absolute URL.

(client: QueryClient, name: EndpointName, pathParams?: Record<string, string | number>) => string

getApiBaseUrl

Read the configured base URL back from a QueryClient. Falls back to the default when the client was not produced by createMdkQueryClient.

(client: QueryClient) => string

getEndpoints

Read the injected endpoint map, or undefined when the client carries none. The mining factories fall back to the bundled mining preset.

(client: QueryClient) => EndpointMap | undefined

getFetcher

Read the injected transport, or undefined when the client carries none — which is the case for a hand-built QueryClient. Callers decide the fallback; the mining factories fall back to the bundled bearer fetcher.

(client: QueryClient) => Fetcher | undefined

getMdkRuntime

Read the whole runtime at once. baseUrl is always resolved; fetcher and endpoints are undefined unless injected.

(client: QueryClient) => MdkRuntime

mdkFetch

Module-level singleton bearer fetcher reading from the global authStore. Used as the default by the mining query factories (tailLogQuery, etc.).

Fetcher

resolveApiBaseUrl

Resolves the API base URL:

(override?: string) => string

resolvePath

Substitute :name segments in a path template, URL-encoding each value.

(template: string, params: Record<string, string | number> = {}) => string

resourceKey

(name: string, params?: unknown, scope: readonly string[] = []) => ResourceKey

runtimeEndpoints

Endpoint map for a factory call: whatever the client carries, else mining.

(client: QueryClient) => EndpointMap

runtimeFetcher

Transport for a factory call: whatever the client carries, else the bundled bearer fetcher.

(client: QueryClient) => Fetcher