@wisemen/vue-core-api-utils 1.0.0-beta.1 → 1.0.0

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 import { Result } from "neverthrow";
-import { QueryClient } from "@tanstack/vue-query";
-import * as vue0 from "vue";
-import { ComputedRef, MaybeRef, Ref, UnwrapRef } from "vue";
+import { QueryClient as QueryClient$1, QueryClient as TanstackQueryClient, QueryClientConfig } from "@tanstack/vue-query";
+import { App, ComputedRef, MaybeRef, Ref } from "vue";
 
 //#region src/async-result/asyncResult.d.ts
 /**
@@ -112,10 +111,8 @@ declare const AsyncResult: {
 };
 //#endregion
 //#region src/types/apiError.type.d.ts
-interface ApiErrorCodes {}
-type ApiErrorCode = ApiErrorCodes[keyof ApiErrorCodes];
-interface ApiKnownErrorObject {
-  code: ApiErrorCode;
+interface ApiKnownErrorObject<TCode extends string = string> {
+  code: TCode;
   detail: string;
   source?: {
     pointer: string;
@@ -130,82 +127,17 @@ interface ApiUnknownErrorObject {
   };
   status: string;
 }
-type ApiErrorObject = ApiKnownErrorObject | ApiUnknownErrorObject;
-interface ApiExpectedError {
-  errors: ApiErrorObject[];
+type ApiErrorObject<TCode extends string = string> = ApiKnownErrorObject<TCode> | ApiUnknownErrorObject;
+interface ApiExpectedError<TCode extends string = string> {
+  errors: ApiErrorObject<TCode>[];
 }
 type ApiUnexpectedError = Error;
-type ApiError = ApiExpectedError | ApiUnexpectedError;
-type ApiResult<T> = Result<T, ApiError>;
-//#endregion
-//#region src/types/queryKeys.type.d.ts
-/**
- * Base interface for defining query keys with their associated entities
- *
- * @example
- * ```typescript
- * declare module '@wisemen/vue-core-api-utils' {
- *   interface QueryKeys {
- *     userDetail: {
- *       params: { userUuid: ComputedRef<UserUuid> }
- *       entity: User
- *     }
- *     productList: {
- *       params: { category: ComputedRef<string> }
- *       entity: Product[]
- *     }
- *   }
- * }
- * ```
- */
-interface QueryKeys {}
-/**
- * Generic helper types for libraries/factories that want to infer query key typing
- * from a user-provided config object (instead of relying on module augmentation).
- */
-/**
- * Extract the entity type from a query-keys config for a specific key.
- */
-type QueryKeyEntityFromConfig<TQueryKeys extends object, TKey extends PropertyKey> = TKey extends keyof TQueryKeys ? TQueryKeys[TKey] extends {
-  entity: infer E;
-} ? E : never : never;
-/**
- * Extract the params type from a query-keys config for a specific key.
- */
-type QueryKeyParamsFromConfig<TQueryKeys extends object, TKey extends PropertyKey> = TKey extends keyof TQueryKeys ? TQueryKeys[TKey] extends {
-  params: infer P;
-} ? P : Record<string, never> : never;
-/**
- * Get all keys that have an associated entity in a query-keys config.
- */
-type QueryKeysWithEntityFromConfig<TQueryKeys extends object> = ({ [K in keyof TQueryKeys]: TQueryKeys[K] extends {
-  entity: any;
-} ? K : never }[keyof TQueryKeys]) & string;
-/**
- * Extract the parameters object from a query key definition
- */
-type QueryKeyParams<TKey extends keyof QueryKeys> = QueryKeys[TKey] extends {
-  params: infer P;
-} ? P : QueryKeys[TKey];
-/**
- * Extract the entity type from a query key definition
- */
-type QueryKeyEntity<TKey extends keyof QueryKeys> = QueryKeys[TKey] extends {
-  entity: infer E;
-} ? E : never;
-/**
- * Check if a query key has an associated entity
- */
-type HasEntity<TKey extends keyof QueryKeys> = QueryKeys[TKey] extends {
-  entity: any;
-} ? TKey : never;
-/**
- * Get all query keys that have an associated entity
- */
-type QueryKeysWithEntity = { [K in keyof QueryKeys]: HasEntity<K> }[keyof QueryKeys];
+type ApiError<TCode extends string = string> = ApiExpectedError<TCode> | ApiUnexpectedError;
+type ApiResult<T, TCode extends string = string> = Result<T, ApiError<TCode>>;
+type AsyncApiResult<T, TCode extends string = string> = AsyncResult<T, ApiError<TCode>>;
 //#endregion
 //#region src/composables/mutation/mutation.composable.d.ts
-type RequestParams<TReqData, TParams> = TReqData extends void ? TParams extends void ? void : {
+type RequestParams$1<TReqData, TParams> = TReqData extends void ? TParams extends void ? void : {
   params: TParams;
 } : TParams extends void ? {
   body: TReqData;
@@ -213,25 +145,10 @@ type RequestParams<TReqData, TParams> = TReqData extends void ? TParams extends
   body: TReqData;
   params: TParams;
 };
-interface UseMutationOptions<TReqData, TResData, TParams = void> {
-  /**
-   * Whether to enable debug mode
-   */
-  isDebug?: boolean;
-  /**
-   * Function that will be called to perform the mutation
-   * @param options - Parameters and body for the mutation
-   * @returns Promise with ApiResult containing either the response data or an error
-   */
-  queryFn: (options: RequestParams<TReqData, TParams>) => Promise<ApiResult<TResData>>;
-  /**
-   * Array of query keys which should be invalidated after mutation is successful
-   */
-  queryKeysToInvalidate: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof QueryKeys[TQueryKey]]: (params: TParams, data: TResData) => UnwrapRef<QueryKeys[TQueryKey][TQueryKeyParam]> } };
-}
-interface UseMutationReturnType<TReqData, TResData, TParams = void> {
+interface UseMutationReturnType<TReqData, TResData, TParams = void, TErrorCode extends string = string> {
   /**
    * Whether mutation is loading
+   * @deprecated - use `result.value.isLoading()` instead
    */
   isLoading: ComputedRef<boolean>;
   /**
@@ -244,7 +161,7 @@ interface UseMutationReturnType<TReqData, TResData, TParams = void> {
    * @param data - Parameters and body for the mutation
    * @returns Promise with ApiResult containing either the response data or an error
    */
-  execute: (data: RequestParams<TReqData, TParams>) => Promise<ApiResult<TResData>>;
+  execute: (data: RequestParams$1<TReqData, TParams>) => Promise<ApiResult<TResData, TErrorCode>>;
   /**
    * Computed result of the mutation
    * Returns an AsyncResult with three states:
@@ -252,31 +169,36 @@ interface UseMutationReturnType<TReqData, TResData, TParams = void> {
    * - ok: use `result.value.isOk()` and `result.value.getValue()`
    * - err: use `result.value.isErr()` and `result.value.getError()`
    */
-  result: ComputedRef<AsyncResult<TResData, ApiError>>;
+  result: ComputedRef<AsyncResult<TResData, ApiError<TErrorCode>>>;
 }
-declare function useMutation<TReqData = void, TResData = void, TParams = void>(options: UseMutationOptions<TReqData, TResData, TParams>): UseMutationReturnType<TReqData, TResData, TParams>;
 //#endregion
 //#region src/types/sort.type.d.ts
-type SortDirection = 'asc' | 'desc';
-interface Sort<TKey extends string = string> {
+declare enum SortDirection {
+  ASC = "asc",
+  DESC = "desc",
+}
+interface Sort<TKey$1 extends string = string> {
   direction: SortDirection;
-  key: TKey;
+  key: TKey$1;
 }
 //#endregion
-//#region src/types/query.type.d.ts
+//#region src/types/queryOptions.d.ts
 interface QueryParams {
   filters?: Record<string, any>;
   search?: string;
   sort?: Sort[];
 }
 interface WithSearchQuery {
-  search: string;
+  search?: string | undefined;
 }
 interface WithSortQuery<TKeys extends string> {
   sort: Sort<TKeys>[];
 }
 interface WithFilterQuery<TFilters extends Record<string, any>> {
-  filters: TFilters;
+  filters?: TFilters;
+}
+interface WithStaticFilterQuery<TFilters extends Record<string, any>> {
+  staticFilters: TFilters;
 }
 interface InfiniteQueryOptions<TParams> {
   params: { [K in keyof TParams]: Ref<TParams[K]> };
@@ -311,8 +233,8 @@ interface KeysetPaginationResponse<TData> {
     next: unknown;
   };
 }
-type OffsetPaginationResult<TData> = ApiResult<OffsetPaginationResponse<TData>>;
-type KeysetPaginationResult<TData> = ApiResult<KeysetPaginationResponse<TData>>;
+type OffsetPaginationResult<TData, TErrorCode extends string = string> = ApiResult<OffsetPaginationResponse<TData>, TErrorCode>;
+type KeysetPaginationResult<TData, TErrorCode extends string = string> = ApiResult<KeysetPaginationResponse<TData>, TErrorCode>;
 interface PaginatedDataDto<TSchema> {
   items: TSchema[];
   meta: {
@@ -323,11 +245,7 @@ interface PaginatedDataDto<TSchema> {
 }
 //#endregion
 //#region src/composables/query/keysetInfiniteQuery.composable.d.ts
-type NonOptionalKeys$2<T> = { [K in keyof T]-?: T[K] };
-type ExtractParams$2<T> = T extends {
-  params: infer P;
-} ? P : T;
-interface KeysetInfiniteQueryOptions<TData> {
+interface KeysetInfiniteQueryOptions<TData, TErrorCode extends string = string> {
   /**
    * The time in milliseconds after which the query will be considered stale
    * After this time, the query will be refetched automatically in the background when it is rendered or accessed
@@ -349,30 +267,63 @@ interface KeysetInfiniteQueryOptions<TData> {
    * Function that will be called when query is executed
    * @returns Promise with response data
    */
-  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<TData>>;
+  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<TData, TErrorCode>>;
   /**
    * Query key associated with the query
    */
-  queryKey: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof NonOptionalKeys$2<ExtractParams$2<QueryKeys[TQueryKey]>>]: MaybeRef<ExtractParams$2<QueryKeys[TQueryKey]>[TQueryKeyParam]> } };
+  queryKey: Record<string, unknown>;
 }
-declare function useKeysetInfiniteQuery<TData>(options: KeysetInfiniteQueryOptions<TData>): {
-  hasNextPage: vue0.ComputedRef<boolean>;
-  isError: vue0.ComputedRef<boolean>;
-  isFetching: vue0.ComputedRef<boolean>;
-  isFetchingNextPage: vue0.ComputedRef<boolean>;
-  isLoading: vue0.ComputedRef<boolean>;
-  isSuccess: vue0.ComputedRef<boolean>;
+interface UseKeysetInfiniteQueryReturnType<TData, TErrorCode extends string = string> {
+  /**
+   * Whether there is a next page available to fetch
+   */
+  hasNextPage: ComputedRef<boolean>;
+  /**
+   * Whether query has errored at least once
+   * @deprecated - use `result.value.isErr()` instead
+   */
+  isError: ComputedRef<boolean>;
+  /**
+   * Whether query is currently fetching data, regardless of cache status
+   */
+  isFetching: ComputedRef<boolean>;
+  /**
+   * Whether query is currently fetching the next page
+   */
+  isFetchingNextPage: ComputedRef<boolean>;
+  /**
+   * Whether query is initially loading
+   * @deprecated - use `result.value.isLoading()` instead
+   */
+  isLoading: ComputedRef<boolean>;
+  /**
+   * Whether query has been executed successfully
+   * @deprecated - use `result.value.isOk()` instead
+   */
+  isSuccess: ComputedRef<boolean>;
+  /**
+   * Fetch the next page of results using the keyset cursor
+   */
   fetchNextPage: () => Promise<void>;
+  /**
+   * Refetch the query
+   */
   refetch: () => Promise<void>;
-  result: vue0.ComputedRef<AsyncResult<KeysetPaginationResponse<TData>, ApiError>>;
-};
+  /**
+   * Computed result of the query containing all accumulated pages
+   * Returns an AsyncResult with three states:
+   * - loading: use `result.value.isLoading()`
+   * - ok: use `result.value.isOk()` and `result.value.getValue()`
+   * - err: use `result.value.isErr()` and `result.value.getError()`
+   *
+   * Use `result.value.match({ loading, ok, err })` for exhaustive handling
+   */
+  result: ComputedRef<AsyncResult<KeysetPaginationResponse<TData>, ApiError<TErrorCode>>>;
+}
+declare function useKeysetInfiniteQuery<TData, TErrorCode extends string = string>(options: KeysetInfiniteQueryOptions<TData, TErrorCode>): UseKeysetInfiniteQueryReturnType<TData, TErrorCode>;
 //#endregion
 //#region src/composables/query/offsetInfiniteQuery.composable.d.ts
-type NonOptionalKeys$1<T> = { [K in keyof T]-?: T[K] };
-type ExtractParams$1<T> = T extends {
-  params: infer P;
-} ? P : T;
-interface OffsetInfiniteQueryOptions<TData> {
+interface OffsetInfiniteQueryOptions<TData, TErrorCode extends string = string> {
   /**
    * The time in milliseconds after which the query will be considered stale
    * After this time, the query will be refetched automatically in the background when it is rendered or accessed
@@ -394,30 +345,63 @@ interface OffsetInfiniteQueryOptions<TData> {
    * Function that will be called when query is executed
    * @returns Promise with response data
    */
-  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<TData>>;
+  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<TData, TErrorCode>>;
   /**
    * Query key associated with the query
    */
-  queryKey: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof NonOptionalKeys$1<ExtractParams$1<QueryKeys[TQueryKey]>>]: MaybeRef<ExtractParams$1<QueryKeys[TQueryKey]>[TQueryKeyParam]> } };
+  queryKey: Record<string, unknown>;
 }
-declare function useOffsetInfiniteQuery<TData>(options: OffsetInfiniteQueryOptions<TData>): {
-  hasNextPage: vue0.ComputedRef<boolean>;
-  isError: vue0.ComputedRef<boolean>;
-  isFetching: vue0.ComputedRef<boolean>;
-  isFetchingNextPage: vue0.ComputedRef<boolean>;
-  isLoading: vue0.ComputedRef<boolean>;
-  isSuccess: vue0.ComputedRef<boolean>;
+interface UseOffsetInfiniteQueryReturnType<TData, TErrorCode extends string = string> {
+  /**
+   * Whether there is a next page available to fetch
+   */
+  hasNextPage: ComputedRef<boolean>;
+  /**
+   * Whether query has errored at least once
+   * @deprecated - use `result.value.isErr()` instead
+   */
+  isError: ComputedRef<boolean>;
+  /**
+   * Whether query is currently fetching data, regardless of cache status
+   */
+  isFetching: ComputedRef<boolean>;
+  /**
+   * Whether query is currently fetching the next page
+   */
+  isFetchingNextPage: ComputedRef<boolean>;
+  /**
+   * Whether query is initially loading
+   * @deprecated - use `result.value.isLoading()` instead
+   */
+  isLoading: ComputedRef<boolean>;
+  /**
+   * Whether query has been executed successfully
+   * @deprecated - use `result.value.isOk()` instead
+   */
+  isSuccess: ComputedRef<boolean>;
+  /**
+   * Fetch the next page of results using offset-based pagination
+   */
   fetchNextPage: () => Promise<void>;
+  /**
+   * Refetch the query
+   */
   refetch: () => Promise<void>;
-  result: vue0.ComputedRef<AsyncResult<OffsetPaginationResponse<TData>, ApiError>>;
-};
+  /**
+   * Computed result of the query containing all accumulated pages
+   * Returns an AsyncResult with three states:
+   * - loading: use `result.value.isLoading()`
+   * - ok: use `result.value.isOk()` and `result.value.getValue()`
+   * - err: use `result.value.isErr()` and `result.value.getError()`
+   *
+   * Use `result.value.match({ loading, ok, err })` for exhaustive handling
+   */
+  result: ComputedRef<AsyncResult<OffsetPaginationResponse<TData>, ApiError<TErrorCode>>>;
+}
+declare function useOffsetInfiniteQuery<TData, TErrorCode extends string = string>(options: OffsetInfiniteQueryOptions<TData, TErrorCode>): UseOffsetInfiniteQueryReturnType<TData, TErrorCode>;
 //#endregion
 //#region src/composables/query/query.composable.d.ts
-type NonOptionalKeys<T> = { [K in keyof T]-?: T[K] };
-type ExtractParams<T> = T extends {
-  params: infer P;
-} ? P : T;
-interface UseQueryOptions<TResData> {
+interface UseQueryOptions<TResData, TErrorCode extends string = string> {
   /**
    * The time in milliseconds after which the query will be considered stale
    * After this time, the query will be refetched automatically in the background when it is rendered or accessed
@@ -440,13 +424,13 @@ interface UseQueryOptions<TResData> {
    * Function that will be called when query is executed
    * @returns Promise with response data
    */
-  queryFn: () => Promise<ApiResult<TResData>>;
+  queryFn: () => Promise<ApiResult<TResData, TErrorCode>>;
   /**
    * Query key associated with the query
    */
-  queryKey: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof NonOptionalKeys<ExtractParams<QueryKeys[TQueryKey]>>]: MaybeRef<ExtractParams<QueryKeys[TQueryKey]>[TQueryKeyParam]> } };
+  queryKey: Record<string, unknown>;
 }
-interface UseQueryReturnType<TResData> {
+interface UseQueryReturnType<TResData, TErrorCode extends string = string> {
   /**
    * Whether query has errored at least once
    * @deprecated - use `result.value.isErr()` instead
@@ -479,153 +463,232 @@ interface UseQueryReturnType<TResData> {
    *
    * Use `result.value.match({ loading, ok, err })` for exhaustive handling
    */
-  result: ComputedRef<AsyncResult<TResData, ApiError>>;
+  result: ComputedRef<AsyncResult<TResData, ApiError<TErrorCode>>>;
 }
-declare function useQuery<TResData>(options: UseQueryOptions<TResData>): UseQueryReturnType<TResData>;
-//#endregion
-//#region src/composables/query/prefetchQuery.composable.d.ts
-declare function usePrefetchQuery<TResData>(query: UseQueryOptions<TResData>): {
-  execute: () => Promise<void>;
-};
 //#endregion
 //#region src/config/config.d.ts
+/**
+ * Initialize the API utilities with a QueryClient.
+ * Call this once during app setup (e.g. in a plugin or main.ts).
+ *
+ * After calling this, `createApiUtils()` can be called without options.
+ *
+ * @example
+ * ```typescript
+ * import { initializeApiUtils } from '@wisemen/vue-core-api-utils'
+ *
+ * const queryClient = new QueryClient()
+ * initializeApiUtils(queryClient)
+ *
+ * // Then in your api lib:
+ * export const { useQuery, useMutation, ... } = createApiUtils<MyQueryKeys>()
+ * ```
+ */
+declare function initializeApiUtils(queryClient: QueryClient$1): void;
+/**
+ * @internal
+ */
+declare function getQueryClient(): QueryClient$1;
 interface QueryConfig {
   prefetchStaleTime: number;
   limit: number;
 }
 declare function setQueryConfig(config: Partial<QueryConfig>): void;
 //#endregion
+//#region src/types/queryKeys.type.d.ts
+/**
+ * Generic helper types for libraries/factories that want to infer query key typing
+ * from a user-provided config object (instead of relying on module augmentation).
+ */
+/**
+ * Extract the entity type from a query-keys config for a specific key.
+ */
+type QueryKeyEntityFromConfig<TQueryKeys extends object, TKey$1 extends PropertyKey> = TKey$1 extends keyof TQueryKeys ? TQueryKeys[TKey$1] extends {
+  entity: infer E;
+} ? E : never : never;
+/**
+ * Extract the params type from a query-keys config for a specific key.
+ * Automatically wraps each param in Ref for reactivity.
+ */
+type QueryKeyParamsFromConfig<TQueryKeys extends object, TKey$1 extends PropertyKey> = TKey$1 extends keyof TQueryKeys ? TQueryKeys[TKey$1] extends {
+  params: infer P;
+} ? { [K in keyof P]: Ref<P[K]> } : void : never;
+/**
+ * Extract the raw params type from a query-keys config for a specific key (unwrapped from Computed).
+ * Used for optimistic updates which accept plain values.
+ */
+type QueryKeyRawParamsFromConfig<TQueryKeys extends object, TKey$1 extends PropertyKey> = TKey$1 extends keyof TQueryKeys ? TQueryKeys[TKey$1] extends {
+  params: infer P;
+} ? P : void : never;
+/**
+ * Get all keys that have an associated entity in a query-keys config.
+ */
+type QueryKeysWithEntityFromConfig<TQueryKeys extends object> = ({ [K in keyof TQueryKeys]: TQueryKeys[K] extends {
+  entity: any;
+} ? K : never }[keyof TQueryKeys]) & string;
+//#endregion
 //#region src/factory/createApiUtils.types.d.ts
-interface CreateApiUtilsOptions {
-  queryClient: QueryClient;
-}
+/**
+ * Helper type to build the invalidation config for a specific query key
+ * Maps the query key's params to optional parameter extractors
+ */
+type QueryKeyInvalidationConfig<TQueryKeys extends object, TKey$1 extends keyof TQueryKeys, TParams, TResData> = QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1 & string> extends void ? {} : QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1 & string> extends object ? { [ParamKey in keyof QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1 & string>]?: (params: TParams, data: TResData) => QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1 & string>[ParamKey] } : {};
 type QueryKeysWithArrayEntityFromConfig<TQueryKeys extends object> = ({ [K in keyof TQueryKeys]: TQueryKeys[K] extends {
   entity: any[];
 } ? K : never }[keyof TQueryKeys]) & string;
-type QueryKeyArrayItemFromConfig<TQueryKeys extends object, TKey extends PropertyKey> = QueryKeyEntityFromConfig<TQueryKeys, TKey> extends (infer TItem)[] ? TItem : never;
-type ApiUseQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>> = {
+type QueryKeyArrayItemFromConfig<TQueryKeys extends object, TKey$1 extends PropertyKey> = QueryKeyEntityFromConfig<TQueryKeys, TKey$1> extends (infer TItem)[] ? TItem : never;
+type ApiUseQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>, TErrorCode extends string = string> = {
   staleTime?: number;
   isDebug?: boolean;
   isEnabled?: MaybeRef<boolean>;
-  queryFn: () => Promise<ApiResult<QueryKeyEntityFromConfig<TQueryKeys, TKey>>>;
-} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
-  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  queryFn: () => Promise<ApiResult<QueryKeyEntityFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 } : {
-  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 });
-type ApiUsePrefetchQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>> = {
+type ApiUsePrefetchQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>, TErrorCode extends string = string> = {
   staleTime?: number;
-  queryFn: () => Promise<ApiResult<QueryKeyEntityFromConfig<TQueryKeys, TKey>>>;
-} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
-  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  queryFn: () => Promise<ApiResult<QueryKeyEntityFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 } : {
-  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 });
-type ApiUseOffsetInfiniteQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+type ApiUseOffsetInfiniteQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>, TErrorCode extends string = string> = {
   staleTime?: number;
   isEnabled?: MaybeRef<boolean>;
   limit?: number;
-  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>>;
-} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
-  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 } : {
-  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 });
-type ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+type ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>, TErrorCode extends string = string> = {
   staleTime?: number;
   limit?: number;
-  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>>;
-} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
-  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 } : {
-  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 });
-type ApiUseKeysetInfiniteQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+type ApiUseKeysetInfiniteQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>, TErrorCode extends string = string> = {
   staleTime?: number;
   isEnabled?: MaybeRef<boolean>;
   limit?: number;
-  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>>;
-} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
-  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 } : {
-  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 });
-type ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+type ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>, TErrorCode extends string = string> = {
   staleTime?: number;
   limit?: number;
-  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>>;
-} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
-  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 } : {
-  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
 });
+type RequestParams<TReqData, TParams> = TReqData extends void ? TParams extends void ? void : {
+  params: TParams;
+} : TParams extends void ? {
+  body: TReqData;
+} : {
+  body: TReqData;
+  params: TParams;
+};
+interface ApiUseMutationOptions<TQueryKeys extends object, TReqData, TResData, TParams = void, TErrorCode extends string = string> {
+  /**
+   * Whether to enable debug mode
+   */
+  isDebug?: boolean;
+  /**
+   * Function that will be called to perform the mutation
+   * @param options - Parameters and body for the mutation
+   * @returns Promise with ApiResult containing either the response data or an error
+   */
+  queryFn: (options: RequestParams<TReqData, TParams>) => Promise<ApiResult<TResData, TErrorCode>>;
+  /**
+   * Query keys which should be invalidated after mutation is successful
+   * Each key is optional and maps to the query key's specific parameters
+   * @example
+   * ```typescript
+   * queryKeysToInvalidate: {
+   *   userDetail: {
+   *     userUuid: (params, result) => params.userUuid,
+   *   },
+   *   userList: {},
+   * }
+   * ```
+   */
+  queryKeysToInvalidate?: { [TKey in keyof TQueryKeys]?: QueryKeyInvalidationConfig<TQueryKeys, TKey, TParams, TResData> };
+}
+interface CreateApiMutationUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
+  useMutation: <TReqData = void, TResData = void, TParams = void>(options: ApiUseMutationOptions<TQueryKeys, TReqData, TResData, TParams, TErrorCode>) => UseMutationReturnType<TReqData, TResData, TParams>;
+}
 //#endregion
 //#region src/factory/createApiInfiniteQueryUtils.d.ts
-declare function createApiInfiniteQueryUtils<TQueryKeys extends object>(): {
-  useKeysetInfiniteQuery: <TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseKeysetInfiniteQueryOptions<TQueryKeys, TKey>) => {
-    hasNextPage: vue0.ComputedRef<boolean>;
-    isError: vue0.ComputedRef<boolean>;
-    isFetching: vue0.ComputedRef<boolean>;
-    isFetchingNextPage: vue0.ComputedRef<boolean>;
-    isLoading: vue0.ComputedRef<boolean>;
-    isSuccess: vue0.ComputedRef<boolean>;
-    fetchNextPage: () => Promise<void>;
-    refetch: () => Promise<void>;
-    result: vue0.ComputedRef<AsyncResult<KeysetPaginationResponse<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>, ApiError>>;
+interface CreateApiInfiniteQueryUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
+  useKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => ReturnType<typeof useKeysetInfiniteQuery<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
+  useOffsetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseOffsetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => ReturnType<typeof useOffsetInfiniteQuery<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
+}
+declare function createApiInfiniteQueryUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiInfiniteQueryUtilsReturnType<TQueryKeys, TErrorCode>;
+//#endregion
+//#region src/factory/createApiMutationUtils.d.ts
+declare function createApiMutationUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiMutationUtilsReturnType<TQueryKeys, TErrorCode>;
+//#endregion
+//#region src/factory/createApiPrefetchInfiniteQueryUtils.d.ts
+interface CreateApiPrefetchInfiniteQueryUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
+  usePrefetchKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => {
+    execute: () => Promise<void>;
   };
-  useOffsetInfiniteQuery: <TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseOffsetInfiniteQueryOptions<TQueryKeys, TKey>) => {
-    hasNextPage: vue0.ComputedRef<boolean>;
-    isError: vue0.ComputedRef<boolean>;
-    isFetching: vue0.ComputedRef<boolean>;
-    isFetchingNextPage: vue0.ComputedRef<boolean>;
-    isLoading: vue0.ComputedRef<boolean>;
-    isSuccess: vue0.ComputedRef<boolean>;
-    fetchNextPage: () => Promise<void>;
-    refetch: () => Promise<void>;
-    result: vue0.ComputedRef<AsyncResult<OffsetPaginationResponse<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>, ApiError>>;
+  usePrefetchOffsetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => {
+    execute: () => Promise<void>;
   };
-};
+}
+declare function createApiPrefetchInfiniteQueryUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiPrefetchInfiniteQueryUtilsReturnType<TQueryKeys, TErrorCode>;
 //#endregion
-//#region src/utils/optimisticUpdates.d.ts
-/**
- * Predicate function type that takes an entity and returns boolean
- */
-type PredicateFn<TEntity> = TEntity extends any[] ? (item: TEntity[number]) => boolean : (item: TEntity) => boolean;
+//#region src/factory/createApiPrefetchQueryUtils.d.ts
+interface CreateApiPrefetchQueryUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
+  usePrefetchQuery: <TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUsePrefetchQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => {
+    execute: () => Promise<void>;
+  };
+}
+declare function createApiPrefetchQueryUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiPrefetchQueryUtilsReturnType<TQueryKeys, TErrorCode>;
+//#endregion
+//#region src/utils/query-client/queryClient.d.ts
 /**
- * Type for matching by key-value pair
+ * Helper type to extract the item type from an entity (array item or entity itself)
  */
 type EntityItem<TEntity> = TEntity extends any[] ? TEntity[number] : TEntity;
-type MatchByKeyValue<TEntity> = Partial<{ [K in keyof EntityItem<TEntity>]: MaybeRef<UnwrapRef<EntityItem<TEntity>[K]>> }>;
 /**
- * Options for the "by" parameter - can be a predicate function or key-value object
+ * Options for type-safe query client update
  */
-type ByOption<TEntity> = MatchByKeyValue<TEntity> | PredicateFn<TEntity> | null | undefined;
-/**
- * Options for optimistic update
- */
-interface OptimisticUpdateOptions<TEntity> {
+interface QueryClientUpdateOptions<TEntity> {
   /**
-   * How to match the entity to update:
-   * - function: a predicate that returns true for the entity to update
-   * - object: key-value pairs to match (e.g., { id: '123' } or { uuid: 'abc' })
-   * - undefined: defaults to matching by 'id' from the value
+   * Predicate function that receives the current item and returns true if it should be updated
    */
-  by?: ByOption<TEntity>;
+  by: (item: EntityItem<TEntity>) => boolean;
   /**
-   * The new value to set (for single entities) or merge (for arrays)
+   * Function that receives the current item and returns the updated item
    */
-  value: TEntity extends any[] ? Partial<TEntity[number]> : Partial<TEntity>;
+  value: (item: EntityItem<TEntity>) => EntityItem<TEntity>;
 }
 /**
- * OptimisticUpdates utility class for type-safe optimistic updates
+ * QueryClient utility class for type-safe query operations
  */
-declare class OptimisticUpdates<TQueryKeys extends object = QueryKeys> {
+declare class QueryClient<TQueryKeys extends object> {
   private readonly queryClient;
-  constructor(queryClient: QueryClient);
+  constructor(queryClient: QueryClient$1);
   /**
    * Extract the raw entity from AsyncResult data
    */
   private extractEntityFromAsyncResult;
+  private hasDataArray;
   private isInfiniteDataLike;
   /**
    * Determine if an item should be updated
@@ -635,6 +698,7 @@ declare class OptimisticUpdates<TQueryKeys extends object = QueryKeys> {
    * Internal method to update entity based on the "by" option
    */
   private updateEntity;
+  private updateInfinitePageValue;
   /**
    * Wrap a raw entity in an AsyncResult (preserving ok state)
    */
@@ -650,22 +714,22 @@ declare class OptimisticUpdates<TQueryKeys extends object = QueryKeys> {
    * @example
    * ```typescript
    * // Get all userDetail queries (returns array)
-   * const allUsers = optimisticUpdates.get('userDetail')
+   * const allUsers = queryClient.get('userDetail')
    *
    * // Get exact query stored as ['userDetail']
-   * const exactUser = optimisticUpdates.get('userDetail', { isExact: true })
+   * const exactUser = queryClient.get('userDetail', { isExact: true })
    *
    * // Get specific userDetail query with params
-   * const user = optimisticUpdates.get(['userDetail', { userUuid: '123' }] as const)
+   * const user = queryClient.get(['userDetail', { userUuid: '123' }] as const)
    * ```
    */
-  get<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey, options?: {
+  get<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey$1, options?: {
     isExact?: false;
-  }): QueryKeyEntityFromConfig<TQueryKeys, TKey>[];
-  get<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey, options: {
+  }): QueryKeyEntityFromConfig<TQueryKeys, TKey$1>[];
+  get<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey$1, options: {
     isExact: true;
-  }): QueryKeyEntityFromConfig<TQueryKeys, TKey> | null;
-  get<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: readonly [TKey, Partial<QueryKeyParamsFromConfig<TQueryKeys, TKey>>]): QueryKeyEntityFromConfig<TQueryKeys, TKey> | null;
+  }): QueryKeyEntityFromConfig<TQueryKeys, TKey$1> | null;
+  get<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: readonly [TKey$1, Partial<QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1>>]): QueryKeyEntityFromConfig<TQueryKeys, TKey$1> | null;
   /**
    * Invalidate queries to trigger a refetch
    *
@@ -675,14 +739,14 @@ declare class OptimisticUpdates<TQueryKeys extends object = QueryKeys> {
    * @example
    * ```typescript
    * // Invalidate all userDetail queries
-   * await optimisticUpdates.invalidate('userDetail')
+   * await queryClient.invalidate('userDetail')
    *
    * // Invalidate specific query
-   * await optimisticUpdates.invalidate(['userDetail', { userUuid: '123' }] as const)
+   * await queryClient.invalidate(['userDetail', { userUuid: '123' }] as const)
    * ```
    */
-  invalidate<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey): Promise<void>;
-  invalidate<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(keyTuple: readonly [TKey, Partial<QueryKeyParamsFromConfig<TQueryKeys, TKey>>]): Promise<void>;
+  invalidate<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey$1): Promise<void>;
+  invalidate<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(keyTuple: readonly [TKey$1, Partial<QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1>>]): Promise<void>;
   /**
    * Set raw entity data in the query cache for a specific query
    * Automatically wraps the entity in AsyncResult
@@ -694,113 +758,113 @@ declare class OptimisticUpdates<TQueryKeys extends object = QueryKeys> {
    * @example
    * ```typescript
    * // Set query with just the key
-   * optimisticUpdates.set('userDetail', userData)
+   * queryClient.set('userDetail', userData)
    *
    * // Set query with key + params
-   * optimisticUpdates.set(['userDetail', { userUuid: '123' }] as const, userData)
+   * queryClient.set(['userDetail', { userUuid: '123' }] as const, userData)
    * ```
    */
-  set<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey, entity: QueryKeyEntityFromConfig<TQueryKeys, TKey>): void;
-  set<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: readonly [TKey, Partial<QueryKeyParamsFromConfig<TQueryKeys, TKey>>], entity: QueryKeyEntityFromConfig<TQueryKeys, TKey>): void;
+  set<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey$1, entity: QueryKeyEntityFromConfig<TQueryKeys, TKey$1>): void;
+  set<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: readonly [TKey$1, Partial<QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1>>], entity: QueryKeyEntityFromConfig<TQueryKeys, TKey$1>): void;
   /**
-   * Update entity data in the query cache optimistically
+   * Update entity data in the query cache
    *
    * When using just the key, updates ALL queries with that key
    * When using key + params tuple, updates SPECIFIC query
    *
    * @example
    * ```typescript
-   * // Update all userDetail queries by id
-   * optimisticUpdates.update('userDetail', {
-   *   value: { id: '123', name: 'John Doe' }
-   * })
-   *
-   * // Update specific query by key + params
-   * optimisticUpdates.update(['userDetail', { userUuid: '123' }] as const, {
-   *   value: { name: 'John Doe' }
+   * // Update a specific user by id
+   * queryClient.update('userDetail', {
+   *   by: (user) => user.id === '123',
+   *   value: (user) => ({ ...user, name: 'John Doe' })
    * })
    *
-   * // Update using predicates
-   * optimisticUpdates.update('userList', {
-   *   value: { isActive: false },
-   *   by: (user) => user.email === 'john@example.com'
+   * // Update all electronics products to out of stock
+   * queryClient.update('productList', {
+   *   by: (product) => product.category === 'electronics',
+   *   value: (product) => ({ ...product, inStock: false })
    * })
    * ```
    */
-  update<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey> = QueryKeyEntityFromConfig<TQueryKeys, TKey>>(key: TKey, options: OptimisticUpdateOptions<TEntity>): void;
-  update<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey> = QueryKeyEntityFromConfig<TQueryKeys, TKey>>(keyTuple: readonly [TKey, Partial<QueryKeyParamsFromConfig<TQueryKeys, TKey>>], options: OptimisticUpdateOptions<TEntity>): void;
+  update<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey$1> = QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>(key: TKey$1, options: QueryClientUpdateOptions<TEntity>): void;
+  update<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey$1> = QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>(keyTuple: readonly [TKey$1, Partial<QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1>>], options: QueryClientUpdateOptions<TEntity>): void;
 }
-/**
- * Create an OptimisticUpdates instance
- */
-declare function createOptimisticUpdates(queryClient: QueryClient): OptimisticUpdates;
-//#endregion
-//#region src/factory/createApiOptimisticUpdatesUtils.d.ts
-declare function createApiOptimisticUpdatesUtils<TQueryKeys extends object>(options: CreateApiUtilsOptions): {
-  useOptimisticUpdates: () => OptimisticUpdates<TQueryKeys>;
-};
 //#endregion
-//#region src/factory/createApiPrefetchInfiniteQueryUtils.d.ts
-declare function createApiPrefetchInfiniteQueryUtils<TQueryKeys extends object>(options: CreateApiUtilsOptions): {
-  usePrefetchKeysetInfiniteQuery: <TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys, TKey>) => {
-    execute: () => Promise<void>;
-  };
-  usePrefetchOffsetInfiniteQuery: <TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys, TKey>) => {
-    execute: () => Promise<void>;
-  };
-};
-//#endregion
-//#region src/factory/createApiPrefetchQueryUtils.d.ts
-declare function createApiPrefetchQueryUtils<TQueryKeys extends object>(options: CreateApiUtilsOptions): {
-  usePrefetchQuery: <TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUsePrefetchQueryOptions<TQueryKeys, TKey>) => {
-    execute: () => Promise<void>;
-  };
-};
+//#region src/factory/createApiQueryClientUtils.d.ts
+interface CreateApiQueryClientUtilsReturnType<TQueryKeys extends object> {
+  useQueryClient: () => QueryClient<TQueryKeys>;
+}
+declare function createApiQueryClientUtils<TQueryKeys extends object>(): CreateApiQueryClientUtilsReturnType<TQueryKeys>;
 //#endregion
 //#region src/factory/createApiQueryUtils.d.ts
-declare function createApiQueryUtils<TQueryKeys extends object>(): {
-  useQuery: <TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseQueryOptions<TQueryKeys, TKey>) => UseQueryReturnType<QueryKeyEntityFromConfig<TQueryKeys, TKey>>;
-};
+interface CreateApiQueryUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
+  useQuery: <TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => UseQueryReturnType<QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>;
+}
+declare function createApiQueryUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiQueryUtilsReturnType<TQueryKeys, TErrorCode>;
 //#endregion
 //#region src/factory/createApiUtils.d.ts
 /**
  * Factory that creates typed composables based on a user-provided query-keys config.
- * This is an alternative to module augmentation of `QueryKeys`.
+ *
+ * Requires `initializeApiUtils(queryClient)` to be called first.
+ *
+ * @example
+ * ```typescript
+ * // In app setup (plugin or main.ts):
+ * initializeApiUtils(queryClient)
+ *
+ * // In your api lib:
+ * export const { useQuery, useMutation, useQueryClient } = createApiUtils<MyQueryKeys>()
+ * ```
  */
-declare function createApiUtils<TQueryKeys extends object>(options: CreateApiUtilsOptions): {
-  useOptimisticUpdates: () => OptimisticUpdates<TQueryKeys>;
-  useKeysetInfiniteQuery: <TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseKeysetInfiniteQueryOptions<TQueryKeys, TKey>) => {
-    hasNextPage: vue0.ComputedRef<boolean>;
-    isError: vue0.ComputedRef<boolean>;
-    isFetching: vue0.ComputedRef<boolean>;
-    isFetchingNextPage: vue0.ComputedRef<boolean>;
-    isLoading: vue0.ComputedRef<boolean>;
-    isSuccess: vue0.ComputedRef<boolean>;
-    fetchNextPage: () => Promise<void>;
-    refetch: () => Promise<void>;
-    result: vue0.ComputedRef<AsyncResult<KeysetPaginationResponse<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>, ApiError>>;
-  };
-  useOffsetInfiniteQuery: <TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseOffsetInfiniteQueryOptions<TQueryKeys, TKey>) => {
-    hasNextPage: vue0.ComputedRef<boolean>;
-    isError: vue0.ComputedRef<boolean>;
-    isFetching: vue0.ComputedRef<boolean>;
-    isFetchingNextPage: vue0.ComputedRef<boolean>;
-    isLoading: vue0.ComputedRef<boolean>;
-    isSuccess: vue0.ComputedRef<boolean>;
-    fetchNextPage: () => Promise<void>;
-    refetch: () => Promise<void>;
-    result: vue0.ComputedRef<AsyncResult<OffsetPaginationResponse<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>, ApiError>>;
-  };
-  usePrefetchKeysetInfiniteQuery: <TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys, TKey>) => {
+declare function createApiUtils<TQueryKeys extends object, TErrorCode extends string = string>(): {
+  useQueryClient: () => QueryClient<TQueryKeys>;
+  useMutation: <TReqData = void, TResData = void, TParams = void>(options: ApiUseMutationOptions<TQueryKeys, TReqData, TResData, TParams, TErrorCode>) => UseMutationReturnType<TReqData, TResData, TParams, string>;
+  useKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => UseKeysetInfiniteQueryReturnType<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>;
+  useOffsetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseOffsetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => UseOffsetInfiniteQueryReturnType<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>;
+  usePrefetchKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => {
     execute: () => Promise<void>;
   };
-  usePrefetchOffsetInfiniteQuery: <TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys, TKey>) => {
+  usePrefetchOffsetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => {
     execute: () => Promise<void>;
   };
-  usePrefetchQuery: <TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUsePrefetchQueryOptions<TQueryKeys, TKey>) => {
+  usePrefetchQuery: <TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUsePrefetchQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => {
     execute: () => Promise<void>;
   };
-  useQuery: <TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseQueryOptions<TQueryKeys, TKey>) => UseQueryReturnType<QueryKeyEntityFromConfig<TQueryKeys, TKey>>;
+  useQuery: <TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => UseQueryReturnType<QueryKeyEntityFromConfig<TQueryKeys, TKey$1>, string>;
 };
 //#endregion
-export { ApiError, ApiErrorCode, ApiErrorCodes, ApiErrorObject, ApiExpectedError, ApiKnownErrorObject, ApiResult, ApiUnexpectedError, ApiUnknownErrorObject, AsyncResult, AsyncResultErr, AsyncResultLoading, AsyncResultOk, type CreateApiUtilsOptions, HasEntity, InfiniteQueryOptions, KeysetInfiniteQueryOptions, KeysetPagination, KeysetPaginationParams, KeysetPaginationResponse, KeysetPaginationResult, OffsetInfiniteQueryOptions, OffsetPagination, OffsetPaginationParams, OffsetPaginationResponse, OffsetPaginationResult, OptimisticUpdateOptions, OptimisticUpdates, PaginatedDataDto, type QueryConfig, QueryKeyEntity, QueryKeyEntityFromConfig, QueryKeyParams, QueryKeyParamsFromConfig, QueryKeys, QueryKeysWithEntity, QueryKeysWithEntityFromConfig, QueryParams, Sort, SortDirection, UseMutationReturnType, UseQueryOptions, UseQueryReturnType, WithFilterQuery, WithSearchQuery, WithSortQuery, createApiInfiniteQueryUtils, createApiOptimisticUpdatesUtils, createApiPrefetchInfiniteQueryUtils, createApiPrefetchQueryUtils, createApiQueryUtils, createApiUtils, createOptimisticUpdates, setQueryConfig, useKeysetInfiniteQuery, useMutation, useOffsetInfiniteQuery, usePrefetchQuery, useQuery };
+//#region src/plugin/apiUtilsPlugin.d.ts
+/**
+ * Create a Vue plugin that sets up TanStack Query and initializes API utilities.
+ *
+ * This plugin handles:
+ * - Creating a QueryClient with the provided config
+ * - Installing VueQueryPlugin on the app
+ * - Initializing the global QueryClient for api-utils
+ *
+ * @example
+ * ```typescript
+ * import { apiUtilsPlugin } from '@wisemen/vue-core-api-utils'
+ * import { vueQueryClientConfig } from '@wisemen/vue-core-configs'
+ *
+ * app.use(apiUtilsPlugin(vueQueryClientConfig()))
+ * ```
+ *
+ * @param config - QueryClient configuration
+ * @returns A Vue plugin that can be used with app.use()
+ */
+declare function apiUtilsPlugin(config: QueryClientConfig): {
+  install: (app: App<any>) => void;
+};
+//#endregion
+//#region src/utils/sort/sort.utils.d.ts
+declare class SortUtil {
+  static toDto<SortKey extends string, QueryKey>(sort: Sort<SortKey>[], sortKeyMap: Record<SortKey, QueryKey>): {
+    key: QueryKey;
+    order: SortDirection;
+  }[];
+}
+//#endregion
+export { ApiError, ApiErrorObject, ApiExpectedError, ApiKnownErrorObject, ApiResult, ApiUnexpectedError, ApiUnknownErrorObject, ApiUseKeysetInfinitePrefetchQueryOptions, ApiUseKeysetInfiniteQueryOptions, ApiUseMutationOptions, ApiUseOffsetInfinitePrefetchQueryOptions, ApiUseOffsetInfiniteQueryOptions, ApiUsePrefetchQueryOptions, ApiUseQueryOptions, AsyncApiResult, AsyncResult, AsyncResultErr, AsyncResultLoading, AsyncResultOk, type CreateApiInfiniteQueryUtilsReturnType, type CreateApiMutationUtilsReturnType, type CreateApiPrefetchInfiniteQueryUtilsReturnType, type CreateApiPrefetchQueryUtilsReturnType, type CreateApiQueryClientUtilsReturnType, type CreateApiQueryUtilsReturnType, type InfiniteQueryOptions, type KeysetInfiniteQueryOptions, KeysetPagination, KeysetPaginationParams, KeysetPaginationResponse, KeysetPaginationResult, type OffsetInfiniteQueryOptions, OffsetPagination, OffsetPaginationParams, OffsetPaginationResponse, OffsetPaginationResult, PaginatedDataDto, QueryClient, QueryClientUpdateOptions, type QueryConfig, QueryKeyArrayItemFromConfig, QueryKeysWithArrayEntityFromConfig, type QueryParams, Sort, SortDirection, SortUtil, type TanstackQueryClient, type UseMutationReturnType, type UseQueryOptions, type UseQueryReturnType, type WithFilterQuery, type WithSearchQuery, type WithSortQuery, type WithStaticFilterQuery, apiUtilsPlugin, createApiInfiniteQueryUtils, createApiMutationUtils, createApiPrefetchInfiniteQueryUtils, createApiPrefetchQueryUtils, createApiQueryClientUtils, createApiQueryUtils, createApiUtils, getQueryClient as getTanstackQueryClient, initializeApiUtils, setQueryConfig };