mobx-tanstack-query-api 0.41.1 → 0.42.0

package/index.d.ts

@@ -1,8 +1,8 @@
 import * as _tanstack_query_core from '@tanstack/query-core';
-import { InvalidateOptions, DefaultError, RefetchOptions, QueryObserverResult, QueryFunctionContext, InvalidateQueryFilters, InfiniteData, QueryKey } from '@tanstack/query-core';
+import { InvalidateOptions, DefaultError, RefetchOptions, QueryObserverResult, QueryFunctionContext, InvalidateQueryFilters, InfiniteData, InfiniteQueryObserverResult, QueryKey } from '@tanstack/query-core';
 export * from '@tanstack/query-core';
 import { HttpStatusCode, HttpSuccessStatusCode } from 'http-status-code-types';
-import { QueryClient, QueryClientConfig, Query, QueryUpdateOptionsAllVariants, QueryConfig, InfiniteQueryConfig, InfiniteQueryOptions, InfiniteQueryUpdateOptions, InfiniteQueryDynamicOptions, InfiniteQuery, MutationInvalidateQueriesOptions, MutationConfig, Mutation, IQueryClientCore } from 'mobx-tanstack-query';
+import { QueryClient, QueryClientConfig, Query, QueryUpdateOptionsAllVariants, QueryConfig, InfiniteQueryConfig, IQueryClientCore, InfiniteQueryOptions, InfiniteQueryUpdateOptions, InfiniteQueryDynamicOptions, InfiniteQuery, InfiniteQueryUpdateOptionsAllVariants, MutationInvalidateQueriesOptions, MutationConfig, Mutation } from 'mobx-tanstack-query';
 import { MaybeFalsy, AnyObject, Maybe, MaybeFn, ValueOf, Defined, IsPartial } from 'yummies/types';
 import { IStringifyOptions, BooleanOptional } from 'qs';
 
@@ -283,10 +283,20 @@ type ToEndpoint<T> = T extends AnyEndpoint ? T : AnyEndpoint;
 
 type ShortInfiniteQueryConfig<TQueryFnData, TError = DefaultError, TPageParam = unknown, TData = InfiniteData<TQueryFnData, TPageParam>> = Omit<InfiniteQueryConfig<TQueryFnData, TError, TPageParam, TData, any[]>, ExcludedQueryKeys> & {
     enabled?: boolean;
+    queryClient?: EndpointQueryClient;
+};
+type EndpointInfiniteQueryContext<TPageParam = unknown> = Omit<QueryFunctionContext<any, TPageParam>, 'client'> & {
+    client: IQueryClientCore;
 };
+type EndpointInfiniteQueryMergePageParam<TEndpoint extends AnyEndpoint, TPageParam = unknown> = 'params' | 'body' | 'query' | 'headers' | ((params: NoInfer<TEndpoint['__params']>, pageParam: NoInfer<TPageParam>, context: EndpointInfiniteQueryContext<TPageParam>) => MaybeFalsy<TEndpoint['__params']>);
 type EndpointInfiniteQueryFlattenOptions<TEndpoint extends AnyEndpoint, TQueryFnData = TEndpoint['__response']['data'], TError = DefaultError, TPageParam = unknown, TData = InfiniteData<TQueryFnData, TPageParam>> = ShortInfiniteQueryConfig<NoInfer<TQueryFnData>, TError, TPageParam, TData> & {
     uniqKey?: EndpointQueryUniqKey;
-    params: (pageParam: NoInfer<TPageParam>) => MaybeFalsy<TEndpoint['__params']>;
+    params?: MaybeFalsy<TEndpoint['__params']>;
+    /**
+     * Merge `pageParam` into endpoint params before request.
+     * Use string shortcuts for common cases or pass a function for custom shaping.
+     */
+    mergePageParam?: EndpointInfiniteQueryMergePageParam<TEndpoint, NoInfer<TPageParam>>;
     /**
      * Transform response to QueryFnData
      */
@@ -294,7 +304,12 @@ type EndpointInfiniteQueryFlattenOptions<TEndpoint extends AnyEndpoint, TQueryFn
 };
 type EndpointInfiniteQueryOptions<TEndpoint extends AnyEndpoint, TQueryFnData = TEndpoint['__response']['data'], TError = DefaultError, TPageParam = unknown, TData = InfiniteData<TQueryFnData, TPageParam>> = ShortInfiniteQueryConfig<NoInfer<TQueryFnData>, TError, TPageParam, TData> & {
     uniqKey?: EndpointQueryUniqKey;
-    params: (pageParam: NoInfer<TPageParam>) => MaybeFalsy<TEndpoint['__params']>;
+    params?: MaybeFn<MaybeFalsy<TEndpoint['__params']>, []>;
+    /**
+     * Merge `pageParam` into endpoint params before request.
+     * Use string shortcuts for common cases or pass a function for custom shaping.
+     */
+    mergePageParam?: EndpointInfiniteQueryMergePageParam<TEndpoint, NoInfer<TPageParam>>;
     /**
      * Transform response to QueryFnData
      */
@@ -304,16 +319,45 @@ type EnhanceUpdatOptionVariant<TEndpoint extends AnyEndpoint, TVariant extends A
     params?: MaybeFalsy<TEndpoint['__params']>;
 };
 type EndpointInfiniteQueryUpdateOptionsAllVariants<TEndpoint extends AnyEndpoint, TQueryFnData = TEndpoint['__response']['data'], TError = DefaultError, TPageParam = unknown, TData = InfiniteData<TQueryFnData, TPageParam>> = EnhanceUpdatOptionVariant<TEndpoint, Partial<InfiniteQueryOptions<TQueryFnData, TError, TPageParam, TData, any[]>>> | EnhanceUpdatOptionVariant<TEndpoint, InfiniteQueryUpdateOptions<TQueryFnData, TError, TPageParam, TData, any[]>> | EnhanceUpdatOptionVariant<TEndpoint, InfiniteQueryDynamicOptions<TQueryFnData, TError, TPageParam, TData, any[]>>;
+type ToEndpointInfiniteQuery<T extends AnyEndpoint, TQueryFnData = ToEndpoint<T>['__response']['data'], TPageParam = unknown, TData = InfiniteData<TQueryFnData, TPageParam>> = T extends Endpoint<infer TResponse, any, any> ? EndpointInfiniteQuery<T, TResponse['data'], DefaultError, TPageParam, TData> : ToEndpointInfiniteQuery<AnyEndpoint>;
 
+/** biome-ignore-all lint/correctness/noUnusedVariables: generic type imports are intentional */
+
+/**
+ * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoint-queries/)
+ */
 declare class EndpointInfiniteQuery<TEndpoint extends AnyEndpoint, TQueryFnData = TEndpoint['__response']['data'], TError = DefaultError, TPageParam = unknown, TData = InfiniteData<TQueryFnData, TPageParam>> extends InfiniteQuery<TQueryFnData, TError, TPageParam, TData, any[]> {
     private endpoint;
-    response: TEndpoint['__response'] | null;
-    params: TEndpoint['__params'] | null;
-    private uniqKey?;
-    constructor(endpoint: AnyEndpoint, queryClient: EndpointQueryClient, queryOptionsInput: EndpointInfiniteQueryOptions<TEndpoint, TQueryFnData, TError, TPageParam, TData> | (() => EndpointInfiniteQueryFlattenOptions<TEndpoint, TQueryFnData, TError, TPageParam, TData>));
-    update({ params, ...options }: EndpointInfiniteQueryUpdateOptionsAllVariants<TEndpoint, TQueryFnData, TError, TPageParam, TData>): void;
-    start(params: MaybeFalsy<TEndpoint['__params']>): Promise<QueryObserverResult<TData, TError>>;
+    private _observableData;
+    /**
+     * Creates `EndpointInfiniteQuery` instance.
+     */
+    constructor(endpoint: AnyEndpoint, inputQueryClient: EndpointQueryClient, queryOptionsInput: EndpointInfiniteQueryOptions<TEndpoint, TQueryFnData, TError, TPageParam, TData> | (() => EndpointInfiniteQueryFlattenOptions<TEndpoint, TQueryFnData, TError, TPageParam, TData>));
+    /**
+     * Current base endpoint params used for `queryKey`.
+     */
+    get params(): MaybeFalsy<TEndpoint["__params"]>;
+    /**
+     * Last raw HTTP response returned by endpoint.
+     */
+    get response(): TEndpoint["__response"] | null;
+    /**
+     * Updates query options and optionally base params.
+     */
+    update(updateParams: Omit<InfiniteQueryUpdateOptionsAllVariants<TQueryFnData, TError, TPageParam, TData, any[]>, 'queryKey'> & {
+        params?: MaybeFalsy<TEndpoint['__params']>;
+    }): void;
+    /**
+     * Sets base params and starts the infinite query execution.
+     */
+    start(params: MaybeFalsy<TEndpoint['__params']>): Promise<InfiniteQueryObserverResult<TData, TError>>;
+    protected handleDestroy(): void;
 }
+declare function mergeInfiniteQueryPageParam<TEndpoint extends AnyEndpoint, TPageParam>(params: TEndpoint['__params'] & AnyObject, pageParam: TPageParam | undefined, ctx: any, mergePageParam?: EndpointInfiniteQueryMergePageParam<TEndpoint, TPageParam>): AnyObject;
+declare const buildInfiniteOptionsFromParams: (endpoint: AnyEndpoint, params: MaybeFalsy<AnyObject>, uniqKey: Maybe<EndpointQueryUniqKey>) => {
+    enabled: boolean;
+    queryKey: any[];
+};
 
 interface EndpointMutationInvalidateQueriesOptions extends MutationInvalidateQueriesOptions {
 }
@@ -369,32 +413,127 @@ interface Endpoint<TResponse extends AnyResponse, TParams extends AnyObject, TMe
  * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/)
  */
 declare class Endpoint<TResponse extends AnyResponse, TParams extends AnyObject, TMetaData extends AnyObject = AnyObject> {
-    configuration: EndpointConfiguration<NoInfer<TParams>, TMetaData>;
-    queryClient: EndpointQueryClient;
-    httpClient: HttpClient;
+    /**
+     * Unique runtime identifier of the endpoint instance.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#endpointid)
+     */
     endpointId: string;
+    /**
+     * Mutable presets used by helper factory methods like `toMutation()`.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#presets)
+     */
     presets: {
         mutations: EndpointMutationPresets;
     };
+    /**
+     * Type-only helper that exposes endpoint params shape.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#__params)
+     */
     __params: TParams;
+    /**
+     * Type-only helper that exposes endpoint response shape.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#__response)
+     */
     __response: TResponse;
+    /**
+     * Custom metadata attached to the endpoint configuration.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#meta)
+     */
     meta: TMetaData;
+    /**
+     * Endpoint configuration generated from the contract/codegen layer.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#configuration)
+     */
+    configuration: EndpointConfiguration<NoInfer<TParams>, TMetaData>;
+    /**
+     * Query client used by query and mutation helpers.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#queryclient)
+     */
+    queryClient: EndpointQueryClient;
+    /**
+     * HTTP client used to build URLs and execute requests.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#httpclient)
+     */
+    httpClient: HttpClient;
     protected validateParams: boolean;
     protected validateData: boolean;
     protected throwParams: boolean;
     protected throwData: boolean;
+    /**
+     * Creates a callable `Endpoint` instance.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#constructor)
+     */
     constructor(configuration: EndpointConfiguration<NoInfer<TParams>, TMetaData>, queryClient: EndpointQueryClient, httpClient: HttpClient);
+    /**
+     * Returns a fully resolved request URL for the provided params.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#getfullurl)
+     */
     getFullUrl(...args: IsPartial<TParams> extends true ? [params?: Maybe<TParams>] : [params: TParams]): string;
+    /**
+     * Returns the resolved request path without the base URL.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#getpath)
+     */
     getPath(...args: IsPartial<TParams> extends true ? [params?: Maybe<TParams>] : [params: TParams]): string;
+    /**
+     * Extracts endpoint params from TanStack Query function context.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#getparamsfromcontext)
+     */
     getParamsFromContext<TQueryKey extends QueryKey = QueryKey, TPageParam = never>(ctx: Omit<QueryFunctionContext<TQueryKey, TPageParam>, 'client'> & {
         client: IQueryClientCore;
     }): TParams;
+    /**
+     * Tags declared for the endpoint.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#tags)
+     */
     get tags(): string[];
+    /**
+     * Path segments declared for the endpoint.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#path)
+     */
     get path(): string[];
+    /**
+     * Slash-joined path declaration for the endpoint.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#pathdeclaration)
+     */
     get pathDeclaration(): string;
+    /**
+     * Operation identifier from the endpoint configuration.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#operationid)
+     */
     get operationId(): string;
+    /**
+     * Optional endpoint group.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#group)
+     */
     get group(): string | undefined;
+    /**
+     * Optional endpoint namespace.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#namespace)
+     */
     get namespace(): string | undefined;
+    /**
+     * Narrows unknown values to endpoint HTTP responses.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#checkresponse)
+     */
     checkResponse<TStatus extends HttpStatusCode>(response: unknown, status: TStatus): response is Extract<TResponse, {
         status: TStatus;
     }>;
@@ -404,7 +543,17 @@ declare class Endpoint<TResponse extends AnyResponse, TParams extends AnyObject,
     } | undefined, payload: unknown, options?: {
         throw?: boolean;
     }): Promise<unknown>;
+    /**
+     * Performs the HTTP request and optionally validates contracts.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#request)
+     */
     request(...args: IsPartial<TParams> extends true ? [params?: Maybe<TParams>] : [params: TParams]): Promise<TResponse>;
+    /**
+     * Builds query metadata payload enriched with endpoint fields.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#toquerymeta)
+     */
     toQueryMeta: (meta?: AnyObject) => {
         tags: string[];
         operationId: string;
@@ -413,8 +562,23 @@ declare class Endpoint<TResponse extends AnyResponse, TParams extends AnyObject,
         endpointId: string;
         endpointQuery: true;
     };
+    /**
+     * Builds a stable TanStack Query key for a regular query.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#toquerykey)
+     */
     toQueryKey(params?: Maybe<TParams>, uniqKey?: EndpointQueryUniqKey): any;
+    /**
+     * Builds a stable TanStack Query key for an infinite query.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#toinfinitequerykey)
+     */
     toInfiniteQueryKey(params?: Maybe<TParams>, uniqKey?: EndpointQueryUniqKey): any;
+    /**
+     * Invalidates the exact query produced by this endpoint.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#invalidatequery)
+     */
     invalidateQuery(...args: IsPartial<TParams> extends true ? [
         params?: Maybe<TParams>,
         filters?: InvalidateQueryFilters & {
@@ -428,10 +592,25 @@ declare class Endpoint<TResponse extends AnyResponse, TParams extends AnyObject,
         },
         options?: InvalidateOptions
     ]): void;
+    /**
+     * Creates an `EndpointMutation` bound to this endpoint.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#tomutation)
+     */
     toMutation<TData = TResponse['data'], TMutationMeta extends AnyObject | void = void, TContext = unknown>(options: EndpointMutationOptions<this, TData, TParams, TMutationMeta, TContext>): EndpointMutation<this, TData, TParams, TMutationMeta, TContext>;
+    /**
+     * Creates an `EndpointQuery` bound to this endpoint.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#toquery)
+     */
     toQuery<TQueryFnData = TResponse['data'], TError = DefaultError | Defined<TResponse['error']>, TData = TQueryFnData, TQueryData = TQueryFnData>(options: EndpointQueryOptions<this, TQueryFnData, TError, TData, TQueryData> | (() => EndpointQueryFlattenOptions<this, TQueryFnData, TError, TData, TQueryData>)): EndpointQuery<this, TQueryFnData, TError, TData, TQueryData>;
-    toInfiniteQuery<TData = TResponse['data'], TError = DefaultError, TPageParam = unknown>(options: EndpointInfiniteQueryOptions<this, TData, TError, TPageParam> | (() => EndpointInfiniteQueryFlattenOptions<this, TData, TError, TPageParam>)): EndpointInfiniteQuery<this, TData, TError, TPageParam, _tanstack_query_core.InfiniteData<TData, TPageParam>>;
+    /**
+     * Creates an `EndpointInfiniteQuery` bound to this endpoint.
+     *
+     * [**Documentation**](https://js2me.github.io/mobx-tanstack-query-api/endpoints/#toinfinitequery)
+     */
+    toInfiniteQuery<TQueryFnData = TResponse['data'], TError = DefaultError | Defined<TResponse['error']>, TPageParam = unknown, TData = _tanstack_query_core.InfiniteData<TQueryFnData, TPageParam>>(options: EndpointInfiniteQueryOptions<this, TQueryFnData, TError, TPageParam, TData> | (() => EndpointInfiniteQueryFlattenOptions<this, TQueryFnData, TError, TPageParam, TData>)): EndpointInfiniteQuery<this, TQueryFnData, TError, TPageParam, TData>;
 }
 
-export { ContentType, Endpoint, EndpointMutation, EndpointQuery, EndpointQueryClient, HttpClient, HttpResponse, buildOptionsFromParams, emptyStatusCodesSet, getParamsFromContext, isHttpBadResponse, isHttpResponse };
-export type { AnyEndpoint, AnyHttpMultistatusResponse, AnyHttpResponse, AnyResponse, EndpointConfiguration, EndpointContract, EndpointMutationInvalidateQueriesOptions, EndpointMutationOptions, EndpointMutationParams, EndpointMutationPresets, EndpointQueryFlattenOptions, EndpointQueryMeta, EndpointQueryOptions, EndpointQueryUniqKey, EndpointStringFilter, ExcludedQueryKeys, FullRequestParams, GetHttpResponse, HttpBadResponse, HttpClientConfig, HttpMultistatusResponse, InferEndpointData, InferEndpointInput, InferEndpointMetaData, InferEndpointResponse, InvalidateEndpointsFilters, QueryParamsType, RequestInfo, RequestParams, ResponseFormat, SafeParseAsyncSchema, ToEndpoint, ToEndpointMutation, ToEndpointQuery };
+export { ContentType, Endpoint, EndpointInfiniteQuery, EndpointMutation, EndpointQuery, EndpointQueryClient, HttpClient, HttpResponse, buildInfiniteOptionsFromParams, buildOptionsFromParams, emptyStatusCodesSet, getParamsFromContext, isHttpBadResponse, isHttpResponse, mergeInfiniteQueryPageParam };
+export type { AnyEndpoint, AnyHttpMultistatusResponse, AnyHttpResponse, AnyResponse, EndpointConfiguration, EndpointContract, EndpointInfiniteQueryContext, EndpointInfiniteQueryFlattenOptions, EndpointInfiniteQueryMergePageParam, EndpointInfiniteQueryOptions, EndpointInfiniteQueryUpdateOptionsAllVariants, EndpointMutationInvalidateQueriesOptions, EndpointMutationOptions, EndpointMutationParams, EndpointMutationPresets, EndpointQueryFlattenOptions, EndpointQueryMeta, EndpointQueryOptions, EndpointQueryUniqKey, EndpointStringFilter, ExcludedQueryKeys, FullRequestParams, GetHttpResponse, HttpBadResponse, HttpClientConfig, HttpMultistatusResponse, InferEndpointData, InferEndpointInput, InferEndpointMetaData, InferEndpointResponse, InvalidateEndpointsFilters, QueryParamsType, RequestInfo, RequestParams, ResponseFormat, SafeParseAsyncSchema, ToEndpoint, ToEndpointInfiniteQuery, ToEndpointMutation, ToEndpointQuery };