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

package/dist/index.d.mts

@@ -0,0 +1,806 @@
+import { Result } from "neverthrow";
+import { QueryClient } from "@tanstack/vue-query";
+import * as vue0 from "vue";
+import { ComputedRef, MaybeRef, Ref, UnwrapRef } from "vue";
+
+//#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> {
+  protected readonly _error: E | undefined;
+  protected readonly _status: 'err' | 'loading' | 'ok';
+  protected readonly _value: T | undefined;
+  protected constructor(status: 'err' | 'loading' | 'ok', value?: T, error?: E);
+  /**
+   * Check if the result is an error (type predicate for narrowing)
+   */
+  isErr(): this is AsyncResultErr<T, E>;
+  /**
+   * Check if the result is in loading state (type predicate for narrowing)
+   */
+  isLoading(): this is AsyncResultLoading<T, E>;
+  /**
+   * Check if the result is a success (type predicate for narrowing)
+   */
+  isOk(): this is AsyncResultOk<T, E>;
+  /**
+   * Map the success value to a new value
+   */
+  map<U>(fn: (value: T) => U): AsyncResult<U, E>;
+  /**
+   * Map the error to a new error
+   */
+  mapErr<F>(fn: (error: E) => F): AsyncResult<T, F>;
+  /**
+   * Pattern match on all three states
+   */
+  match<U>(handlers: {
+    err: (error: E) => 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> extends AsyncResultBase<T, E> {
+  private constructor();
+  /** @internal */
+  static _create<T, E>(error: E): AsyncResultErr<T, E>;
+  /** Get the error value - only available after isErr() check */
+  getError(): E;
+  getResult(): Result<T, E>;
+}
+/**
+ * AsyncResult representing a loading state
+ */
+declare class AsyncResultLoading<T, E> extends AsyncResultBase<T, E> {
+  private constructor();
+  /** @internal */
+  static _create<T, E>(): AsyncResultLoading<T, E>;
+  getResult(): null;
+}
+/**
+ * AsyncResult representing a success state
+ */
+declare class AsyncResultOk<T, E> extends AsyncResultBase<T, E> {
+  private constructor();
+  /** @internal */
+  static _create<T, E>(value: T): AsyncResultOk<T, E>;
+  getResult(): Result<T, E>;
+  /** 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> = AsyncResultErr<T, E> | AsyncResultLoading<T, E> | AsyncResultOk<T, E>;
+/**
+ * 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>(error: E) => AsyncResultErr<T, E>;
+  /**
+   * Create an AsyncResult from an existing neverthrow Result
+   */
+  readonly fromResult: <T, E>(result: Result<T, E>) => AsyncResult<T, E>;
+  /**
+   * Create a loading AsyncResult
+   */
+  readonly loading: <T, E>() => AsyncResultLoading<T, E>;
+  /**
+   * Create a successful AsyncResult with data
+   */
+  readonly ok: <T, E>(value: T) => AsyncResultOk<T, E>;
+};
+//#endregion
+//#region src/types/apiError.type.d.ts
+interface ApiErrorCodes {}
+type ApiErrorCode = ApiErrorCodes[keyof ApiErrorCodes];
+interface ApiKnownErrorObject {
+  code: ApiErrorCode;
+  detail: string;
+  source?: {
+    pointer: string;
+  };
+  status: string;
+}
+interface ApiUnknownErrorObject {
+  code: string;
+  detail: string;
+  source?: {
+    pointer: string;
+  };
+  status: string;
+}
+type ApiErrorObject = ApiKnownErrorObject | ApiUnknownErrorObject;
+interface ApiExpectedError {
+  errors: ApiErrorObject[];
+}
+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];
+//#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> {
+  /**
+   * 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> {
+  /**
+   * Whether mutation is loading
+   */
+  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>>;
+  /**
+   * 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>>;
+}
+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> {
+  direction: SortDirection;
+  key: TKey;
+}
+//#endregion
+//#region src/types/query.type.d.ts
+interface QueryParams {
+  filters?: Record<string, any>;
+  search?: string;
+  sort?: Sort[];
+}
+interface WithSearchQuery {
+  search: string;
+}
+interface WithSortQuery<TKeys extends string> {
+  sort: Sort<TKeys>[];
+}
+interface WithFilterQuery<TFilters extends Record<string, any>> {
+  filters: 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> = ApiResult<OffsetPaginationResponse<TData>>;
+type KeysetPaginationResult<TData> = ApiResult<KeysetPaginationResponse<TData>>;
+interface PaginatedDataDto<TSchema> {
+  items: TSchema[];
+  meta: {
+    limit: number;
+    offset: number;
+    total: number;
+  };
+}
+//#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> {
+  /**
+   * 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
+   * @default 0
+   */
+  staleTime?: number;
+  /**
+   * Whether the query is enabled
+   * If false, the query will not be executed
+   * @default true
+   */
+  isEnabled?: MaybeRef<boolean>;
+  /**
+   * Maximum number of items to fetch per page, default can be set in config
+   * @default 20
+   */
+  limit?: number;
+  /**
+   * Function that will be called when query is executed
+   * @returns Promise with response data
+   */
+  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<TData>>;
+  /**
+   * 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]> } };
+}
+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>;
+  fetchNextPage: () => Promise<void>;
+  refetch: () => Promise<void>;
+  result: vue0.ComputedRef<AsyncResult<KeysetPaginationResponse<TData>, ApiError>>;
+};
+//#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> {
+  /**
+   * 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
+   * @default 0
+   */
+  staleTime?: number;
+  /**
+   * Whether the query is enabled
+   * If false, the query will not be executed
+   * @default true
+   */
+  isEnabled?: MaybeRef<boolean>;
+  /**
+   * Maximum number of items to fetch per page, default can be set in config
+   * @default 20
+   */
+  limit?: number;
+  /**
+   * Function that will be called when query is executed
+   * @returns Promise with response data
+   */
+  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<TData>>;
+  /**
+   * 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]> } };
+}
+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>;
+  fetchNextPage: () => Promise<void>;
+  refetch: () => Promise<void>;
+  result: vue0.ComputedRef<AsyncResult<OffsetPaginationResponse<TData>, ApiError>>;
+};
+//#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> {
+  /**
+   * 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
+   * @default 0
+   */
+  staleTime?: number;
+  /**
+   * Whether to enable debug mode
+   * When enabled, the query key and parameters will be logged to the console
+   * @default false
+   */
+  isDebug?: boolean;
+  /**
+   * Whether the query is enabled
+   * If false, the query will not be executed
+   * @default true
+   */
+  isEnabled?: MaybeRef<boolean>;
+  /**
+   * Function that will be called when query is executed
+   * @returns Promise with response data
+   */
+  queryFn: () => Promise<ApiResult<TResData>>;
+  /**
+   * Query key associated with the query
+   */
+  queryKey: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof NonOptionalKeys<ExtractParams<QueryKeys[TQueryKey]>>]: MaybeRef<ExtractParams<QueryKeys[TQueryKey]>[TQueryKeyParam]> } };
+}
+interface UseQueryReturnType<TResData> {
+  /**
+   * 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>>;
+}
+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
+interface QueryConfig {
+  prefetchStaleTime: number;
+  limit: number;
+}
+declare function setQueryConfig(config: Partial<QueryConfig>): void;
+//#endregion
+//#region src/factory/createApiUtils.types.d.ts
+interface CreateApiUtilsOptions {
+  queryClient: QueryClient;
+}
+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>> = {
+  staleTime?: number;
+  isDebug?: boolean;
+  isEnabled?: MaybeRef<boolean>;
+  queryFn: () => Promise<ApiResult<QueryKeyEntityFromConfig<TQueryKeys, TKey>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+});
+type ApiUsePrefetchQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>> = {
+  staleTime?: number;
+  queryFn: () => Promise<ApiResult<QueryKeyEntityFromConfig<TQueryKeys, TKey>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+});
+type ApiUseOffsetInfiniteQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+  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>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+});
+type ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+  staleTime?: number;
+  limit?: number;
+  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+});
+type ApiUseKeysetInfiniteQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+  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>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+});
+type ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys extends object, TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+  staleTime?: number;
+  limit?: number;
+  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey> extends Record<string, never> ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey>;
+});
+//#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>>;
+  };
+  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>>;
+  };
+};
+//#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;
+/**
+ * Type for matching by key-value pair
+ */
+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
+ */
+type ByOption<TEntity> = MatchByKeyValue<TEntity> | PredicateFn<TEntity> | null | undefined;
+/**
+ * Options for optimistic update
+ */
+interface OptimisticUpdateOptions<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
+   */
+  by?: ByOption<TEntity>;
+  /**
+   * The new value to set (for single entities) or merge (for arrays)
+   */
+  value: TEntity extends any[] ? Partial<TEntity[number]> : Partial<TEntity>;
+}
+/**
+ * OptimisticUpdates utility class for type-safe optimistic updates
+ */
+declare class OptimisticUpdates<TQueryKeys extends object = QueryKeys> {
+  private readonly queryClient;
+  constructor(queryClient: QueryClient);
+  /**
+   * Extract the raw entity from AsyncResult data
+   */
+  private extractEntityFromAsyncResult;
+  private isInfiniteDataLike;
+  /**
+   * Determine if an item should be updated
+   */
+  private shouldUpdateItem;
+  /**
+   * Internal method to update entity based on the "by" option
+   */
+  private updateEntity;
+  /**
+   * 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 = optimisticUpdates.get('userDetail')
+   *
+   * // Get exact query stored as ['userDetail']
+   * const exactUser = optimisticUpdates.get('userDetail', { isExact: true })
+   *
+   * // Get specific userDetail query with params
+   * const user = optimisticUpdates.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<QueryKeyParamsFromConfig<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 optimisticUpdates.invalidate('userDetail')
+   *
+   * // Invalidate specific query
+   * await optimisticUpdates.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>;
+  /**
+   * 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
+   * optimisticUpdates.set('userDetail', userData)
+   *
+   * // Set query with key + params
+   * optimisticUpdates.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;
+  /**
+   * Update entity data in the query cache optimistically
+   *
+   * 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 using predicates
+   * optimisticUpdates.update('userList', {
+   *   value: { isActive: false },
+   *   by: (user) => user.email === 'john@example.com'
+   * })
+   * ```
+   */
+  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;
+}
+/**
+ * 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>;
+  };
+};
+//#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>>;
+};
+//#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`.
+ */
+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>) => {
+    execute: () => Promise<void>;
+  };
+  usePrefetchOffsetInfiniteQuery: <TKey extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys, TKey>) => {
+    execute: () => Promise<void>;
+  };
+  usePrefetchQuery: <TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUsePrefetchQueryOptions<TQueryKeys, TKey>) => {
+    execute: () => Promise<void>;
+  };
+  useQuery: <TKey extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey, queryOptions: ApiUseQueryOptions<TQueryKeys, TKey>) => UseQueryReturnType<QueryKeyEntityFromConfig<TQueryKeys, TKey>>;
+};
+//#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 };