@wisemen/vue-core-api-utils 2.0.2 → 2.0.4

package/dist/index.d.mts

@@ -0,0 +1,851 @@
+import { Result } from "neverthrow";
+import { QueryClient as QueryClient$1, QueryClient as TanstackQueryClient, QueryClientConfig } from "@tanstack/vue-query";
+import { App, ComputedRef, MaybeRef, MaybeRefOrGetter, Ref } from "vue";
+import z from "zod";
+
+//#region src/async-result/asyncResult.d.ts
+/**
+ * Base class for AsyncResult - internal use only.
+ * Use AsyncResult<T, E> as the public type.
+ */
+declare abstract class AsyncResultBase<T, E$1> {
+  protected readonly _error: E$1 | undefined;
+  protected readonly _status: 'err' | 'loading' | 'ok';
+  protected readonly _value: T | undefined;
+  protected constructor(status: 'err' | 'loading' | 'ok', value?: T, error?: E$1);
+  /**
+   * Check if the result is an error (type predicate for narrowing)
+   */
+  isErr(): this is AsyncResultErr<T, E$1>;
+  /**
+   * Check if the result is in loading state (type predicate for narrowing)
+   */
+  isLoading(): this is AsyncResultLoading<T, E$1>;
+  /**
+   * Check if the result is a success (type predicate for narrowing)
+   */
+  isOk(): this is AsyncResultOk<T, E$1>;
+  /**
+   * Map the success value to a new value
+   */
+  map<U>(fn: (value: T) => U): AsyncResult<U, E$1>;
+  /**
+   * Map the error to a new error
+   */
+  mapErr<F>(fn: (error: E$1) => F): AsyncResult<T, F>;
+  /**
+   * Pattern match on all three states
+   */
+  match<U>(handlers: {
+    err: (error: E$1) => U;
+    loading: () => U;
+    ok: (value: T) => U;
+  }): U;
+  /**
+   * Get the success value, or return null if loading or error.
+   * Returns T | null when null is passed as the default value.
+   */
+  unwrapOr(defaultValue: null): T | null;
+  /**
+   * Get the success value, or return the default value of type T if loading or error.
+   * Returns T when a value of type T is passed as the default value.
+   */
+  unwrapOr(defaultValue: T): T;
+}
+/**
+ * AsyncResult representing an error state
+ */
+declare class AsyncResultErr<T, E$1> extends AsyncResultBase<T, E$1> {
+  private constructor();
+  /** @internal */
+  static _create<T, E$1>(error: E$1): AsyncResultErr<T, E$1>;
+  /** Get the error value - only available after isErr() check */
+  getError(): E$1;
+  getResult(): Result<T, E$1>;
+}
+/**
+ * AsyncResult representing a loading state
+ */
+declare class AsyncResultLoading<T, E$1> extends AsyncResultBase<T, E$1> {
+  private constructor();
+  /** @internal */
+  static _create<T, E$1>(): AsyncResultLoading<T, E$1>;
+  getResult(): null;
+}
+/**
+ * AsyncResult representing a success state
+ */
+declare class AsyncResultOk<T, E$1> extends AsyncResultBase<T, E$1> {
+  private constructor();
+  /** @internal */
+  static _create<T, E$1>(value: T): AsyncResultOk<T, E$1>;
+  getResult(): Result<T, E$1>;
+  /** Get the success value - only available after isOk() check */
+  getValue(): T;
+}
+/**
+ * Union type of all AsyncResult states.
+ * Use isOk(), isErr(), or isLoading() to narrow to specific state.
+ */
+type AsyncResult<T, E$1> = AsyncResultErr<T, E$1> | AsyncResultLoading<T, E$1> | AsyncResultOk<T, E$1>;
+/**
+ * Static factory methods for creating AsyncResult instances.
+ * This pattern (same name for type and value) is intentional for ergonomic API.
+ */
+declare const AsyncResult: {
+  /**
+   * Create a failed AsyncResult with error
+   */
+  readonly err: <T, E$1>(error: E$1) => AsyncResultErr<T, E$1>;
+  /**
+   * Create an AsyncResult from an existing neverthrow Result
+   */
+  readonly fromResult: <T, E$1>(result: Result<T, E$1>) => AsyncResult<T, E$1>;
+  /**
+   * Create a loading AsyncResult
+   */
+  readonly loading: <T, E$1>() => AsyncResultLoading<T, E$1>;
+  /**
+   * Create a successful AsyncResult with data
+   */
+  readonly ok: <T, E$1>(value: T) => AsyncResultOk<T, E$1>;
+};
+//#endregion
+//#region src/register.d.ts
+interface Register {}
+type RegisteredQueryKeys = Register extends {
+  queryKeys: infer T;
+} ? T extends object ? T : object : object;
+type RegisteredErrorCodes = Register extends {
+  errorCodes: infer T;
+} ? T extends string ? T : string : string;
+type RegisteredApiUseMutationOptions<TReqData, TResData, TParams = void> = UseMutationOptions<TReqData, TResData, TParams, RegisteredErrorCodes>;
+type RegisteredQueryKeyInput = { [K in keyof RegisteredQueryKeys]?: RegisteredQueryKeys[K] extends {
+  params: infer P;
+} ? P : unknown };
+type RegisteredQueryKeyConfig<TKey extends PropertyKey> = RegisteredQueryKeys extends Record<TKey, infer V> ? V : unknown;
+type RegisteredQueryKeyEntity<TKey extends PropertyKey> = RegisteredQueryKeyConfig<TKey> extends {
+  entity: infer E;
+} ? E : unknown;
+type RegisteredQueryKeyParams<TKey extends PropertyKey> = RegisteredQueryKeyConfig<TKey> extends {
+  params: infer P;
+} ? P : undefined;
+//#endregion
+//#region src/types/apiError.type.d.ts
+interface ApiKnownErrorObject<TCode extends string = string> {
+  code: TCode;
+  detail: string;
+  source?: {
+    pointer: string;
+  };
+  status: string;
+}
+interface ApiUnknownErrorObject {
+  code: string;
+  detail: string;
+  source?: {
+    pointer: string;
+  };
+  status: string;
+}
+type ApiErrorObject<TCode extends string = string> = ApiKnownErrorObject<TCode> | ApiUnknownErrorObject;
+interface ApiExpectedError<TCode extends string = string> {
+  errors: ApiErrorObject<TCode>[];
+}
+type ApiUnexpectedError = Error;
+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 : {
+  params: TParams;
+} : TParams extends void ? {
+  body: TReqData;
+} : {
+  body: TReqData;
+  params: TParams;
+};
+interface UseMutationOptions<TReqData, TResData, TParams = void, TErrorCode extends string = RegisteredErrorCodes> {
+  /**
+   * 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>>;
+  /**
+   * Object where each key is a query key to invalidate after mutation succeeds.
+   * Each query key can optionally have nested parameter extractors.
+   * @example
+   * ```typescript
+   * queryKeysToInvalidate: {
+   *   contactDetail: {
+   *     contactUuid: (params, result) => params.contactUuid,
+   *   },
+   *   contactIndex: {},
+   * }
+   * ```
+   */
+  queryKeysToInvalidate?: { [K in keyof RegisteredQueryKeyInput]?: Record<string, (params: TParams, data: TResData) => any> };
+}
+interface UseMutationReturnType<TReqData, TResData, TParams = void, TErrorCode extends string = RegisteredErrorCodes> {
+  /**
+   * Whether mutation is loading
+   * @deprecated - use `result.value.isLoading()` instead
+   */
+  isLoading: ComputedRef<boolean>;
+  /**
+   * Response data from the mutation
+   * @deprecated - use `result.value.getValue()` instead
+   */
+  data: ComputedRef<TResData | null>;
+  /**
+   * Function to execute the mutation
+   * @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, TErrorCode>>;
+  /**
+   * Computed result of the mutation
+   * 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()`
+   */
+  result: ComputedRef<AsyncResult<TResData, ApiError<TErrorCode>>>;
+}
+declare function useMutation<TReqData = void, TResData = void, TParams = void, TErrorCode extends string = RegisteredErrorCodes>(options: UseMutationOptions<TReqData, TResData, TParams, TErrorCode>): UseMutationReturnType<TReqData, TResData, TParams, TErrorCode>;
+//#endregion
+//#region src/types/sort.type.d.ts
+type SortDirection = 'asc' | 'desc';
+interface Sort<TKey extends string = string> {
+  direction: SortDirection;
+  key: TKey;
+}
+//#endregion
+//#region src/types/queryOptions.d.ts
+interface QueryParams {
+  filters?: Record<string, any>;
+  search?: string;
+  sort?: Sort[];
+}
+interface WithSearchQuery {
+  search?: string | undefined;
+}
+interface WithSortQuery<TKeys extends string> {
+  sort: Sort<TKeys>[];
+}
+interface WithFilterQuery<TFilters extends Record<string, any>> {
+  filters?: TFilters;
+}
+interface WithStaticFilterQuery<TFilters extends Record<string, any>> {
+  staticFilters: TFilters;
+}
+interface InfiniteQueryOptions<TParams> {
+  params: { [K in keyof TParams]: Ref<TParams[K]> };
+}
+//#endregion
+//#region src/types/pagination.type.d.ts
+interface OffsetPaginationParams {
+  limit: number;
+  offset: number;
+}
+type OffsetPagination<T extends QueryParams = Record<string, never>> = {
+  pagination: OffsetPaginationParams;
+} & T;
+interface KeysetPaginationParams {
+  key?: any;
+  limit: number;
+}
+type KeysetPagination<T extends QueryParams> = {
+  pagination: KeysetPaginationParams;
+} & T;
+interface OffsetPaginationResponse<TData> {
+  data: TData[];
+  meta: {
+    limit: number;
+    offset: number;
+    total: number;
+  };
+}
+interface KeysetPaginationResponse<TData> {
+  data: TData[];
+  meta: {
+    next: unknown;
+  };
+}
+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: {
+    limit: number;
+    offset: number;
+    total: number;
+  };
+}
+//#endregion
+//#region src/composables/query/keysetInfiniteQuery.composable.d.ts
+type NestedMaybeRefOrGetter$2<T> = { [K in keyof T]: MaybeRefOrGetter<T[K]> };
+type ArrayItemOf$1<E$1> = E$1 extends (infer I)[] ? I : E$1;
+type EntityItemOf$1<TKey extends PropertyKey> = RegisteredQueryKeyConfig<TKey> extends {
+  entity: infer E;
+} ? ArrayItemOf$1<E> : unknown;
+type WithParams$5<TKey extends PropertyKey> = RegisteredQueryKeyParams<TKey> extends undefined ? {
+  params?: undefined;
+} : {
+  params: NestedMaybeRefOrGetter$2<RegisteredQueryKeyParams<TKey>>;
+};
+type KeysetInfiniteQueryOptions<TKey extends keyof RegisteredQueryKeys, TData, TErrorCode extends string = RegisteredErrorCodes> = {
+  /**
+   * The time in milliseconds after which the query will be considered stale
+   * @default 0
+   */
+  staleTime?: number;
+  /**
+   * Whether the query is enabled
+   * @default true
+   */
+  isEnabled?: MaybeRef<boolean>;
+  /**
+   * Maximum number of items to fetch per page
+   * @default 20
+   */
+  limit?: number;
+  /**
+   * Function that will be called when query is executed
+   */
+  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<TData, TErrorCode>>;
+} & WithParams$5<TKey>;
+interface UseKeysetInfiniteQueryReturnType<TData, TErrorCode extends string = RegisteredErrorCodes> {
+  /**
+   * 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>;
+  /**
+   * 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<TKey extends keyof RegisteredQueryKeys, TData = EntityItemOf$1<TKey>, TErrorCode extends string = RegisteredErrorCodes>(key: TKey, options: KeysetInfiniteQueryOptions<TKey, TData, TErrorCode>): UseKeysetInfiniteQueryReturnType<TData, TErrorCode>;
+//#endregion
+//#region src/composables/query/offsetInfiniteQuery.composable.d.ts
+type NestedMaybeRefOrGetter$1<T> = { [K in keyof T]: MaybeRefOrGetter<T[K]> };
+type ArrayItemOf<E$1> = E$1 extends (infer I)[] ? I : E$1;
+type EntityItemOf<TKey extends PropertyKey> = RegisteredQueryKeyConfig<TKey> extends {
+  entity: infer E;
+} ? ArrayItemOf<E> : unknown;
+type WithParams$4<TKey extends PropertyKey> = RegisteredQueryKeyParams<TKey> extends undefined ? {
+  params?: undefined;
+} : {
+  params: NestedMaybeRefOrGetter$1<RegisteredQueryKeyParams<TKey>>;
+};
+type OffsetInfiniteQueryOptions<TKey extends keyof RegisteredQueryKeys, TData, TErrorCode extends string = RegisteredErrorCodes> = {
+  /**
+   * The time in milliseconds after which the query will be considered stale
+   * @default 0
+   */
+  staleTime?: number;
+  /**
+   * Whether the query is enabled
+   * @default true
+   */
+  isEnabled?: MaybeRef<boolean>;
+  /**
+   * Maximum number of items to fetch per page
+   * @default 20
+   */
+  limit?: number;
+  /**
+   * Function that will be called when query is executed
+   */
+  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<TData, TErrorCode>>;
+} & WithParams$4<TKey>;
+interface UseOffsetInfiniteQueryReturnType<TData, TErrorCode extends string = RegisteredErrorCodes> {
+  /**
+   * 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>;
+  /**
+   * 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<TKey extends keyof RegisteredQueryKeys, TData = EntityItemOf<TKey>, TErrorCode extends string = RegisteredErrorCodes>(key: TKey, options: OffsetInfiniteQueryOptions<TKey, TData, TErrorCode>): UseOffsetInfiniteQueryReturnType<TData, TErrorCode>;
+//#endregion
+//#region src/composables/query/prefetchKeysetInfiniteQuery.composable.d.ts
+type WithParams$3<TKey extends PropertyKey> = RegisteredQueryKeyParams<TKey> extends undefined ? {
+  params?: undefined;
+} : {
+  params: RegisteredQueryKeyParams<TKey>;
+};
+type PrefetchKeysetInfiniteQueryOptions<TKey extends keyof RegisteredQueryKeys, TData, TErrorCode extends string = RegisteredErrorCodes> = {
+  /**
+   * The time in milliseconds after which the prefetched query will be considered stale
+   * @default config.prefetchStaleTime
+   */
+  staleTime?: number;
+  /**
+   * Maximum number of items to fetch per page
+   * @default 20
+   */
+  limit?: number;
+  /**
+   * Function that will be called when query is executed
+   */
+  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<TData, TErrorCode>>;
+} & WithParams$3<TKey>;
+declare function usePrefetchKeysetInfiniteQuery<TKey extends keyof RegisteredQueryKeys, TData = unknown, TErrorCode extends string = RegisteredErrorCodes>(key: TKey, options: PrefetchKeysetInfiniteQueryOptions<TKey, TData, TErrorCode>): {
+  execute: () => Promise<void>;
+};
+//#endregion
+//#region src/composables/query/prefetchOffsetInfiniteQuery.composable.d.ts
+type WithParams$2<TKey extends PropertyKey> = RegisteredQueryKeyParams<TKey> extends undefined ? {
+  params?: undefined;
+} : {
+  params: RegisteredQueryKeyParams<TKey>;
+};
+type PrefetchOffsetInfiniteQueryOptions<TKey extends keyof RegisteredQueryKeys, TData, TErrorCode extends string = RegisteredErrorCodes> = {
+  /**
+   * The time in milliseconds after which the prefetched query will be considered stale
+   * @default config.prefetchStaleTime
+   */
+  staleTime?: number;
+  /**
+   * Maximum number of items to fetch per page
+   * @default 20
+   */
+  limit?: number;
+  /**
+   * Function that will be called when query is executed
+   */
+  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<TData, TErrorCode>>;
+} & WithParams$2<TKey>;
+declare function usePrefetchOffsetInfiniteQuery<TKey extends keyof RegisteredQueryKeys, TData = unknown, TErrorCode extends string = RegisteredErrorCodes>(key: TKey, options: PrefetchOffsetInfiniteQueryOptions<TKey, TData, TErrorCode>): {
+  execute: () => Promise<void>;
+};
+//#endregion
+//#region src/composables/query/prefetchQuery.composable.d.ts
+type WithParams$1<TKey extends PropertyKey> = RegisteredQueryKeyParams<TKey> extends undefined ? {
+  params?: undefined;
+} : {
+  params: RegisteredQueryKeyParams<TKey>;
+};
+type UsePrefetchQueryOptions<TKey extends keyof RegisteredQueryKeys, TData, TErrorCode extends string = RegisteredErrorCodes> = {
+  /**
+   * The time in milliseconds after which the prefetched query will be considered stale
+   * @default config.prefetchStaleTime
+   */
+  staleTime?: number;
+  /**
+   * Function that will be called when query is executed
+   */
+  queryFn: () => Promise<ApiResult<TData, TErrorCode>>;
+} & WithParams$1<TKey>;
+declare function usePrefetchQuery<TKey extends keyof RegisteredQueryKeys, TData = unknown, TErrorCode extends string = RegisteredErrorCodes>(key: TKey, options: UsePrefetchQueryOptions<TKey, TData, TErrorCode>): {
+  execute: () => Promise<void>;
+};
+//#endregion
+//#region src/composables/query/query.composable.d.ts
+type NestedMaybeRefOrGetter<T> = { [K in keyof T]: MaybeRefOrGetter<T[K]> };
+type WithParams<TKey extends PropertyKey> = RegisteredQueryKeyParams<TKey> extends undefined ? {
+  params?: undefined;
+} : {
+  params: NestedMaybeRefOrGetter<RegisteredQueryKeyParams<TKey>>;
+};
+type UseQueryOptions<TKey extends keyof RegisteredQueryKeys, TData, TErrorCode extends string = RegisteredErrorCodes> = {
+  /**
+   * The time in milliseconds after which the query will be considered stale
+   * @default 0
+   */
+  staleTime?: number;
+  /**
+   * Whether to enable debug mode
+   * @default false
+   */
+  isDebug?: boolean;
+  /**
+   * Whether the query is enabled
+   * @default true
+   */
+  isEnabled?: MaybeRef<boolean>;
+  /**
+   * Function that will be called when query is executed
+   */
+  queryFn: () => Promise<ApiResult<TData, TErrorCode>>;
+} & WithParams<TKey>;
+interface UseQueryReturnType<TResData, TErrorCode extends string = RegisteredErrorCodes> {
+  /**
+   * 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 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>;
+  /**
+   * Refetch the query
+   */
+  refetch: () => Promise<void>;
+  /**
+   * Computed result of the query
+   * 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<TResData, ApiError<TErrorCode>>>;
+}
+declare function useQuery<TKey extends keyof RegisteredQueryKeys, TData = RegisteredQueryKeyEntity<TKey>, TErrorCode extends string = RegisteredErrorCodes>(key: TKey, options: UseQueryOptions<TKey, TData, TErrorCode>): UseQueryReturnType<TData, TErrorCode>;
+//#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/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/api/api.util.d.ts
+declare class ApiUtil {
+  static fromPromise<T>(promise: PromiseLike<T>, message?: string): Promise<ApiResult<T, RegisteredErrorCodes>>;
+  static getKeysetPaginationNextOffset(keysetPaginationMeta: KeysetPaginationResponse<any>['meta']): number | null;
+  static getResultError(result: AsyncResult<unknown, ApiError> | Result<unknown, ApiError> | null): ApiError<RegisteredErrorCodes> | null;
+  private static isAsyncResult;
+  static void<T, TApiResult extends ApiResult<void>>(result: ApiResult<T>): TApiResult;
+}
+//#endregion
+//#region src/utils/api-error/apiError.util.d.ts
+declare class ApiErrorUtil {
+  static getApiErrorCode(error: ApiExpectedError): string | null;
+  static getApiErrorMessage(error: ApiExpectedError): string | null;
+  static getMessage(error: ApiExpectedError): string | null;
+  static handleApiError({
+    error,
+    message
+  }: {
+    error: unknown;
+    message?: string;
+  }): ApiError<RegisteredErrorCodes>;
+  static isExpectedApiError(error: unknown): error is ApiExpectedError<RegisteredErrorCodes>;
+  static isZodError(error: unknown): error is z.ZodError;
+}
+//#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 extends PropertyKey> = TKey extends keyof TQueryKeys ? TQueryKeys[TKey] extends {
+  entity: infer E;
+} ? E : never : 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 extends PropertyKey> = TKey extends keyof TQueryKeys ? TQueryKeys[TKey] 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/utils/query-client/queryClient.d.ts
+/**
+ * Helper type to extract the item type from an entity (array item or entity itself)
+ */
+type EntityItem<TEntity> = TEntity extends any[] ? TEntity[number] : TEntity;
+/**
+ * Options for type-safe query client update
+ */
+interface QueryClientUpdateOptions<TEntity> {
+  /**
+   * Predicate function that receives the current item and returns true if it should be updated
+   */
+  by: (item: EntityItem<TEntity>) => boolean;
+  /**
+   * Function that receives the current item and returns the updated item
+   */
+  value: (item: EntityItem<TEntity>) => EntityItem<TEntity>;
+}
+/**
+ * Result of an update operation, providing a rollback function
+ */
+interface QueryClientUpdateResult {
+  /**
+   * Reverts the cache entries affected by this update to their state before the update was applied.
+   * Safe to call multiple times (subsequent calls are no-ops).
+   */
+  rollback: () => void;
+}
+/**
+ * QueryClient utility class for type-safe query operations
+ */
+declare class QueryClient<TQueryKeys extends object> {
+  private readonly 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
+   */
+  private shouldUpdateItem;
+  /**
+   * Internal method to update entity based on the "by" option
+   */
+  private updateEntity;
+  private updateInfinitePageValue;
+  /**
+   * Wrap a raw entity in an AsyncResult (preserving ok state)
+   */
+  private wrapEntityInAsyncResult;
+  /**
+   * Get raw entity data from the query cache
+   * Automatically extracts the entity from AsyncResult wrapper
+   *
+   * When using just a key string:
+   * - By default (isExact=false), returns ALL queries with that key as first element
+   * - With isExact=true, returns only the query stored as [key]
+   *
+   * @example
+   * ```typescript
+   * // Get all userDetail queries (returns array)
+   * const allUsers = queryClient.get('userDetail')
+   *
+   * // Get exact query stored as ['userDetail']
+   * const exactUser = queryClient.get('userDetail', { isExact: true })
+   *
+   * // Get specific userDetail query with params
+   * const user = queryClient.get(['userDetail', { userUuid: '123' }] as const)
+   * ```
+   */
+  get<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey, options?: {
+    isExact?: false;
+  }): QueryKeyEntityFromConfig<TQueryKeys, TKey>[];
+  get<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey, options: {
+    isExact: true;
+  }): QueryKeyEntityFromConfig<TQueryKeys, TKey> | null;
+  get<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: readonly [TKey, Partial<QueryKeyRawParamsFromConfig<TQueryKeys, TKey>>]): QueryKeyEntityFromConfig<TQueryKeys, TKey> | null;
+  /**
+   * Invalidate queries to trigger a refetch
+   *
+   * When using just the key, invalidates ALL queries with that key
+   * When using key + params tuple, invalidates SPECIFIC query
+   *
+   * @example
+   * ```typescript
+   * // Invalidate all userDetail queries
+   * await queryClient.invalidate('userDetail')
+   *
+   * // Invalidate specific query
+   * 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<QueryKeyRawParamsFromConfig<TQueryKeys, TKey>>]): Promise<void>;
+  /**
+   * Set raw entity data in the query cache for a specific query
+   * Automatically wraps the entity in AsyncResult
+   *
+   * Both formats set a single query - just with different key representations:
+   * - 'userDetail' sets the query with key ['userDetail']
+   * - ['userDetail', { userUuid: '123' }] sets the query with that exact key
+   *
+   * @example
+   * ```typescript
+   * // Set query with just the key
+   * queryClient.set('userDetail', userData)
+   *
+   * // Set query with key + params
+   * 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<QueryKeyRawParamsFromConfig<TQueryKeys, TKey>>], entity: QueryKeyEntityFromConfig<TQueryKeys, TKey>): void;
+  /**
+   * 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 a specific user by id
+   * const { rollback } = queryClient.update('userDetail', {
+   *   by: (user) => user.id === '123',
+   *   value: (user) => ({ ...user, name: 'John Doe' })
+   * })
+   *
+   * // Revert if the mutation fails
+   * rollback()
+   *
+   * // 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: QueryClientUpdateOptions<TEntity>): QueryClientUpdateResult;
+  update<TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey> = QueryKeyEntityFromConfig<TQueryKeys, TKey>>(keyTuple: readonly [TKey, Partial<QueryKeyRawParamsFromConfig<TQueryKeys, TKey>>], options: QueryClientUpdateOptions<TEntity>): QueryClientUpdateResult;
+}
+//#endregion
+//#region src/utils/sort/sort.utils.d.ts
+declare enum SortDirectionDto {
+  ASC = "asc",
+  DESC = "desc",
+}
+declare class SortUtil {
+  static toDto<SortKey extends string, QueryKey>(sort: Sort<SortKey>[], sortKeyMap: Record<SortKey, QueryKey>): {
+    key: QueryKey;
+    order: SortDirectionDto;
+  }[];
+}
+//#endregion
+export { type ApiError, type ApiErrorObject, ApiErrorUtil, type ApiExpectedError, type ApiKnownErrorObject, type ApiResult, type ApiUnexpectedError, type ApiUnknownErrorObject, ApiUtil, type AsyncApiResult, AsyncResult, AsyncResultErr, AsyncResultLoading, AsyncResultOk, type InfiniteQueryOptions, type KeysetInfiniteQueryOptions, type KeysetPagination, type KeysetPaginationParams, type KeysetPaginationResponse, type KeysetPaginationResult, type OffsetInfiniteQueryOptions, type OffsetPagination, type OffsetPaginationParams, type OffsetPaginationResponse, type OffsetPaginationResult, type PaginatedDataDto, type PrefetchKeysetInfiniteQueryOptions, type PrefetchOffsetInfiniteQueryOptions, QueryClient, type QueryClientUpdateOptions, type QueryClientUpdateResult, type QueryConfig, type QueryParams, type Register, type RegisteredApiUseMutationOptions, type RegisteredErrorCodes, type RegisteredQueryKeyInput, type RegisteredQueryKeys, type Sort, type SortDirection, SortUtil, type TanstackQueryClient, type UseKeysetInfiniteQueryReturnType, type UseMutationOptions, type UseMutationReturnType, type UseOffsetInfiniteQueryReturnType, type UseQueryOptions, type UseQueryReturnType, type WithFilterQuery, type WithSearchQuery, type WithSortQuery, type WithStaticFilterQuery, apiUtilsPlugin, getQueryClient as getTanstackQueryClient, initializeApiUtils, setQueryConfig, useKeysetInfiniteQuery, useMutation, useOffsetInfiniteQuery, usePrefetchKeysetInfiniteQuery, usePrefetchOffsetInfiniteQuery, usePrefetchQuery, useQuery };