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

package/dist/index.d.mts

@@ -1,52 +1,115 @@
+import { Result } from "neverthrow";
+import { QueryClient } from "@tanstack/vue-query";
 import * as vue0 from "vue";
 import { ComputedRef, MaybeRef, Ref, UnwrapRef } from "vue";
-import { Result } from "neverthrow";
 
-//#region src/types/queryKeys.type.d.ts
-interface 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<TParams, TReqData, TResData> {
+//#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);
   /**
-   * Whether to enable debug mode
+   * Check if the result is an error (type predicate for narrowing)
    */
-  isDebug?: boolean;
+  isErr(): this is AsyncResultErr<T, E>;
   /**
-   * Function that will be called to perform the mutation
-   * @param options - Parameters and body for the mutation
-   * @returns Promise with the response data
+   * Check if the result is in loading state (type predicate for narrowing)
    */
-  queryFn: (options: RequestParams<TReqData, TParams>) => Promise<TResData>;
+  isLoading(): this is AsyncResultLoading<T, E>;
   /**
-   * Array of query keys which should be invalidated after mutation is successful
+   * Check if the result is a success (type predicate for narrowing)
    */
-  queryKeysToInvalidate: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof QueryKeys[TQueryKey]]: (params: TParams, data: TResData) => UnwrapRef<QueryKeys[TQueryKey][TQueryKeyParam]> } };
-}
-interface UseMutationReturnType<TReqData, TResData, TParams = void> {
+  isOk(): this is AsyncResultOk<T, E>;
   /**
-   * Whether mutation is loading
+   * Map the success value to a new value
    */
-  isLoading: ComputedRef<boolean>;
+  map<U>(fn: (value: T) => U): AsyncResult<U, E>;
   /**
-   * Response data from the mutation
+   * Map the error to a new error
    */
-  data: ComputedRef<TResData extends unknown[] ? TResData[] : TResData | null>;
+  mapErr<F>(fn: (error: E) => F): AsyncResult<T, F>;
   /**
-   * Function to execute the mutation
-   * @param data - Parameters and body for the mutation
-   * @returns Promise with the response data
+   * 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.
    */
-  execute: (data: RequestParams<TReqData, TParams>) => Promise<TResData>;
+  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;
 }
-declare function useMutation<TReqData = void, TResData = void, TParams = void>(options: UseMutationOptions<TParams, TReqData, TResData>): UseMutationReturnType<TReqData, TResData, TParams>;
+/**
+ * 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 {}
@@ -75,11 +138,73 @@ type ApiUnexpectedError = Error;
 type ApiError = ApiExpectedError | ApiUnexpectedError;
 type ApiResult<T> = Result<T, ApiError>;
 //#endregion
+//#region src/composables/mutation/mutation.composable.d.ts
+type RequestParams$1<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$1<TReqData, TParams>) => Promise<ApiResult<TResData>>;
+  /**
+   * 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?: Record<string, Record<string, (params: TParams, data: TResData) => any> | undefined>;
+}
+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$1<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> {
+interface Sort<TKey$1 extends string = string> {
   direction: SortDirection;
-  key: TKey;
+  key: TKey$1;
 }
 //#endregion
 //#region src/types/query.type.d.ts
@@ -141,8 +266,85 @@ interface PaginatedDataDto<TSchema> {
   };
 }
 //#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$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;
+/**
+ * Extract the parameters object from a query key definition
+ */
+type QueryKeyParams<TKey$1 extends keyof QueryKeys> = QueryKeys[TKey$1] extends {
+  params: infer P;
+} ? Ref<P> : QueryKeys[TKey$1];
+/**
+ * Extract the entity type from a query key definition
+ */
+type QueryKeyEntity<TKey$1 extends keyof QueryKeys> = QueryKeys[TKey$1] extends {
+  entity: infer E;
+} ? E : never;
+/**
+ * Check if a query key has an associated entity
+ */
+type HasEntity<TKey$1 extends keyof QueryKeys> = QueryKeys[TKey$1] extends {
+  entity: any;
+} ? TKey$1 : never;
+/**
+ * Get all query keys that have an associated entity
+ */
+type QueryKeysWithEntity = { [K in keyof QueryKeys]: HasEntity<K> }[keyof QueryKeys];
+//#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
@@ -169,7 +371,7 @@ interface KeysetInfiniteQueryOptions<TData> {
   /**
    * Query key associated with the query
    */
-  queryKey: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof NonOptionalKeys$2<QueryKeys[TQueryKey]>]: MaybeRef<QueryKeys[TQueryKey][TQueryKeyParam]> } };
+  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>;
@@ -180,11 +382,14 @@ declare function useKeysetInfiniteQuery<TData>(options: KeysetInfiniteQueryOptio
   isSuccess: vue0.ComputedRef<boolean>;
   fetchNextPage: () => Promise<void>;
   refetch: () => Promise<void>;
-  result: vue0.ComputedRef<KeysetPaginationResult<TData>>;
+  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
@@ -211,7 +416,7 @@ interface OffsetInfiniteQueryOptions<TData> {
   /**
    * Query key associated with the query
    */
-  queryKey: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof NonOptionalKeys$1<QueryKeys[TQueryKey]>]: MaybeRef<QueryKeys[TQueryKey][TQueryKeyParam]> } };
+  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>;
@@ -222,11 +427,14 @@ declare function useOffsetInfiniteQuery<TData>(options: OffsetInfiniteQueryOptio
   isSuccess: vue0.ComputedRef<boolean>;
   fetchNextPage: () => Promise<void>;
   refetch: () => Promise<void>;
-  result: vue0.ComputedRef<OffsetPaginationResult<TData>>;
+  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
@@ -254,28 +462,26 @@ interface UseQueryOptions<TResData> {
   /**
    * Query key associated with the query
    */
-  queryKey: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof NonOptionalKeys<QueryKeys[TQueryKey]>]: MaybeRef<QueryKeys[TQueryKey][TQueryKeyParam]> } };
+  queryKey: { [TQueryKey in keyof QueryKeys]?: { [TQueryKeyParam in keyof NonOptionalKeys<ExtractParams<QueryKeys[TQueryKey]>>]: MaybeRef<ExtractParams<QueryKeys[TQueryKey]>[TQueryKeyParam]> } };
 }
 interface UseQueryReturnType<TResData> {
-  /**
-   * Response data
-   */
   /**
    * Whether query has errored at least once
-   * @deprecated - use `result.isErr()` instead
+   * @deprecated - use `result.value.isErr()` instead
    */
   isError: ComputedRef<boolean>;
   /**
-   * Whether query is currently loading
+   * 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.isOk()` instead
+   * @deprecated - use `result.value.isOk()` instead
    */
   isSuccess: ComputedRef<boolean>;
   /**
@@ -284,10 +490,14 @@ interface UseQueryReturnType<TResData> {
   refetch: () => Promise<void>;
   /**
    * Computed result of the query
-   * It will return an instance of Result<TResData, ApiError>
-   * where TResData is the response data and ApiError is the error
+   * 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<ApiResult<TResData> | null>;
+  result: ComputedRef<AsyncResult<TResData, ApiError>>;
 }
 declare function useQuery<TResData>(options: UseQueryOptions<TResData>): UseQueryReturnType<TResData>;
 //#endregion
@@ -303,4 +513,309 @@ interface QueryConfig {
 }
 declare function setQueryConfig(config: Partial<QueryConfig>): void;
 //#endregion
-export { ApiError, ApiErrorCode, ApiErrorCodes, ApiErrorObject, ApiExpectedError, ApiKnownErrorObject, ApiResult, ApiUnexpectedError, ApiUnknownErrorObject, InfiniteQueryOptions, KeysetInfiniteQueryOptions, KeysetPagination, KeysetPaginationParams, KeysetPaginationResponse, KeysetPaginationResult, OffsetInfiniteQueryOptions, OffsetPagination, OffsetPaginationParams, OffsetPaginationResponse, OffsetPaginationResult, PaginatedDataDto, type QueryConfig, QueryKeys, QueryParams, Sort, SortDirection, UseMutationReturnType, UseQueryOptions, UseQueryReturnType, WithFilterQuery, WithSearchQuery, WithSortQuery, setQueryConfig, useKeysetInfiniteQuery, useMutation, useOffsetInfiniteQuery, usePrefetchQuery, useQuery };
+//#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$1 extends PropertyKey> = QueryKeyEntityFromConfig<TQueryKeys, TKey$1> extends (infer TItem)[] ? TItem : never;
+type ApiUseQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>> = {
+  staleTime?: number;
+  isDebug?: boolean;
+  isEnabled?: MaybeRef<boolean>;
+  queryFn: () => Promise<ApiResult<QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+});
+type ApiUsePrefetchQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>> = {
+  staleTime?: number;
+  queryFn: () => Promise<ApiResult<QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+});
+type ApiUseOffsetInfiniteQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+  staleTime?: number;
+  isEnabled?: MaybeRef<boolean>;
+  limit?: number;
+  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+});
+type ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+  staleTime?: number;
+  limit?: number;
+  queryFn: (paginationParams: OffsetPaginationParams) => Promise<OffsetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+});
+type ApiUseKeysetInfiniteQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+  staleTime?: number;
+  isEnabled?: MaybeRef<boolean>;
+  limit?: number;
+  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+} : {
+  params: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+});
+type ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>> = {
+  staleTime?: number;
+  limit?: number;
+  queryFn: (paginationParams: KeysetPaginationParams) => Promise<KeysetPaginationResult<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>>>;
+} & (QueryKeyParamsFromConfig<TQueryKeys, TKey$1> extends void ? {
+  params?: QueryKeyParamsFromConfig<TQueryKeys, TKey$1>;
+} : {
+  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> {
+  /**
+   * 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>>;
+  /**
+   * 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> {
+  useMutation: <TReqData = void, TResData = void, TParams = void>(options: ApiUseMutationOptions<TQueryKeys, TReqData, TResData, TParams>) => UseMutationReturnType<TReqData, TResData, TParams>;
+}
+//#endregion
+//#region src/factory/createApiInfiniteQueryUtils.d.ts
+interface CreateApiInfiniteQueryUtilsReturnType<TQueryKeys extends object> {
+  useKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfiniteQueryOptions<TQueryKeys, TKey$1>) => ReturnType<typeof useKeysetInfiniteQuery<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>>>;
+  useOffsetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseOffsetInfiniteQueryOptions<TQueryKeys, TKey$1>) => ReturnType<typeof useOffsetInfiniteQuery<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>>>;
+}
+declare function createApiInfiniteQueryUtils<TQueryKeys extends object>(): CreateApiInfiniteQueryUtilsReturnType<TQueryKeys>;
+//#endregion
+//#region src/factory/createApiMutationUtils.d.ts
+declare function createApiMutationUtils<TQueryKeys extends object>(): CreateApiMutationUtilsReturnType<TQueryKeys>;
+//#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$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey$1, options?: {
+    isExact?: false;
+  }): QueryKeyEntityFromConfig<TQueryKeys, TKey$1>[];
+  get<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(queryKey: TKey$1, options: {
+    isExact: true;
+  }): 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
+   *
+   * 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$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
+   *
+   * 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$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
+   *
+   * 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$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey$1> = QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>(key: TKey$1, options: OptimisticUpdateOptions<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: OptimisticUpdateOptions<TEntity>): void;
+}
+/**
+ * Create an OptimisticUpdates instance
+ */
+declare function createOptimisticUpdates(queryClient: QueryClient): OptimisticUpdates;
+//#endregion
+//#region src/factory/createApiOptimisticUpdatesUtils.d.ts
+interface CreateApiOptimisticUpdatesUtilsReturnType<TQueryKeys extends object> {
+  useOptimisticUpdates: () => OptimisticUpdates<TQueryKeys>;
+}
+declare function createApiOptimisticUpdatesUtils<TQueryKeys extends object>(options: CreateApiUtilsOptions): CreateApiOptimisticUpdatesUtilsReturnType<TQueryKeys>;
+//#endregion
+//#region src/factory/createApiPrefetchInfiniteQueryUtils.d.ts
+interface CreateApiPrefetchInfiniteQueryUtilsReturnType<TQueryKeys extends object> {
+  usePrefetchKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys, TKey$1>) => {
+    execute: () => Promise<void>;
+  };
+  usePrefetchOffsetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseOffsetInfinitePrefetchQueryOptions<TQueryKeys, TKey$1>) => {
+    execute: () => Promise<void>;
+  };
+}
+declare function createApiPrefetchInfiniteQueryUtils<TQueryKeys extends object>(options: CreateApiUtilsOptions): CreateApiPrefetchInfiniteQueryUtilsReturnType<TQueryKeys>;
+//#endregion
+//#region src/factory/createApiPrefetchQueryUtils.d.ts
+interface CreateApiPrefetchQueryUtilsReturnType<TQueryKeys extends object> {
+  usePrefetchQuery: <TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUsePrefetchQueryOptions<TQueryKeys, TKey$1>) => {
+    execute: () => Promise<void>;
+  };
+}
+declare function createApiPrefetchQueryUtils<TQueryKeys extends object>(options: CreateApiUtilsOptions): CreateApiPrefetchQueryUtilsReturnType<TQueryKeys>;
+//#endregion
+//#region src/factory/createApiQueryUtils.d.ts
+interface CreateApiQueryUtilsReturnType<TQueryKeys extends object> {
+  useQuery: <TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseQueryOptions<TQueryKeys, TKey$1>) => UseQueryReturnType<QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>;
+}
+declare function createApiQueryUtils<TQueryKeys extends object>(): CreateApiQueryUtilsReturnType<TQueryKeys>;
+//#endregion
+//#region src/factory/createApiUtils.d.ts
+type CreateApiUtilsReturnType<TQueryKeys extends object> = ReturnType<typeof createApiQueryUtils<TQueryKeys>> & ReturnType<typeof createApiPrefetchQueryUtils<TQueryKeys>> & ReturnType<typeof createApiInfiniteQueryUtils<TQueryKeys>> & ReturnType<typeof createApiPrefetchInfiniteQueryUtils<TQueryKeys>> & ReturnType<typeof createApiMutationUtils<TQueryKeys>> & ReturnType<typeof createApiOptimisticUpdatesUtils<TQueryKeys>>;
+/**
+ * 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): CreateApiUtilsReturnType<TQueryKeys>;
+//#endregion
+export { ApiError, ApiErrorCode, ApiErrorCodes, ApiErrorObject, ApiExpectedError, ApiKnownErrorObject, ApiResult, ApiUnexpectedError, ApiUnknownErrorObject, ApiUseKeysetInfinitePrefetchQueryOptions, ApiUseKeysetInfiniteQueryOptions, ApiUseMutationOptions, ApiUseOffsetInfinitePrefetchQueryOptions, ApiUseOffsetInfiniteQueryOptions, ApiUsePrefetchQueryOptions, ApiUseQueryOptions, AsyncResult, AsyncResultErr, AsyncResultLoading, AsyncResultOk, type CreateApiInfiniteQueryUtilsReturnType, type CreateApiMutationUtilsReturnType, type CreateApiOptimisticUpdatesUtilsReturnType, type CreateApiPrefetchInfiniteQueryUtilsReturnType, type CreateApiPrefetchQueryUtilsReturnType, type CreateApiQueryUtilsReturnType, type CreateApiUtilsOptions, CreateApiUtilsReturnType, HasEntity, InfiniteQueryOptions, KeysetInfiniteQueryOptions, KeysetPagination, KeysetPaginationParams, KeysetPaginationResponse, KeysetPaginationResult, OffsetInfiniteQueryOptions, OffsetPagination, OffsetPaginationParams, OffsetPaginationResponse, OffsetPaginationResult, OptimisticUpdateOptions, OptimisticUpdates, PaginatedDataDto, type QueryConfig, QueryKeyArrayItemFromConfig, QueryKeyEntity, QueryKeyEntityFromConfig, QueryKeyParams, QueryKeyParamsFromConfig, QueryKeyRawParamsFromConfig, QueryKeys, QueryKeysWithArrayEntityFromConfig, QueryKeysWithEntity, QueryKeysWithEntityFromConfig, QueryParams, Sort, SortDirection, UseMutationReturnType, UseQueryOptions, UseQueryReturnType, WithFilterQuery, WithSearchQuery, WithSortQuery, createApiInfiniteQueryUtils, createApiMutationUtils, createApiOptimisticUpdatesUtils, createApiPrefetchInfiniteQueryUtils, createApiPrefetchQueryUtils, createApiQueryUtils, createApiUtils, createOptimisticUpdates, setQueryConfig, useKeysetInfiniteQuery, useMutation, useOffsetInfiniteQuery, usePrefetchQuery, useQuery };

package/dist/index.mjs

@@ -1,15 +1,162 @@
-import { useInfiniteQuery, useMutation as useMutation$1, useQuery as useQuery$1, useQueryClient } from "@tanstack/vue-query";
-import { computed } from "vue";
 import { err, ok } from "neverthrow";
+import { useInfiniteQuery, useMutation as useMutation$1, useQuery as useQuery$1, useQueryClient } from "@tanstack/vue-query";
+import { computed, unref } from "vue";
+
+//#region src/async-result/asyncResult.ts
+/**
+* Base class for AsyncResult - internal use only.
+* Use AsyncResult<T, E> as the public type.
+*/
+var AsyncResultBase = class {
+	_error;
+	_status;
+	_value;
+	constructor(status, value, error) {
+		this._status = status;
+		this._value = value;
+		this._error = error;
+	}
+	/**
+	* Check if the result is an error (type predicate for narrowing)
+	*/
+	isErr() {
+		return this._status === "err";
+	}
+	/**
+	* Check if the result is in loading state (type predicate for narrowing)
+	*/
+	isLoading() {
+		return this._status === "loading";
+	}
+	/**
+	* Check if the result is a success (type predicate for narrowing)
+	*/
+	isOk() {
+		return this._status === "ok";
+	}
+	/**
+	* Map the success value to a new value
+	*/
+	map(fn) {
+		if (this._status === "loading") return AsyncResult.loading();
+		if (this._status === "ok") return AsyncResult.ok(fn(this._value));
+		return AsyncResult.err(this._error);
+	}
+	/**
+	* Map the error to a new error
+	*/
+	mapErr(fn) {
+		if (this._status === "loading") return AsyncResult.loading();
+		if (this._status === "err") return AsyncResult.err(fn(this._error));
+		return AsyncResult.ok(this._value);
+	}
+	/**
+	* Pattern match on all three states
+	*/
+	match(handlers) {
+		if (this._status === "loading") return handlers.loading();
+		if (this._status === "ok") return handlers.ok(this._value);
+		return handlers.err(this._error);
+	}
+	unwrapOr(defaultValue) {
+		if (this._status === "ok") return this._value;
+		return defaultValue;
+	}
+};
+/**
+* AsyncResult representing an error state
+*/
+var AsyncResultErr = class AsyncResultErr extends AsyncResultBase {
+	constructor(error) {
+		super("err", void 0, error);
+	}
+	/** @internal */
+	static _create(error) {
+		return new AsyncResultErr(error);
+	}
+	/** Get the error value - only available after isErr() check */
+	getError() {
+		return this._error;
+	}
+	getResult() {
+		return err(this._error);
+	}
+};
+/**
+* AsyncResult representing a loading state
+*/
+var AsyncResultLoading = class AsyncResultLoading extends AsyncResultBase {
+	constructor() {
+		super("loading");
+	}
+	/** @internal */
+	static _create() {
+		return new AsyncResultLoading();
+	}
+	getResult() {
+		return null;
+	}
+};
+/**
+* AsyncResult representing a success state
+*/
+var AsyncResultOk = class AsyncResultOk extends AsyncResultBase {
+	constructor(value) {
+		super("ok", value);
+	}
+	/** @internal */
+	static _create(value) {
+		return new AsyncResultOk(value);
+	}
+	getResult() {
+		return ok(this._value);
+	}
+	/** Get the success value - only available after isOk() check */
+	getValue() {
+		return this._value;
+	}
+};
+/**
+* Static factory methods for creating AsyncResult instances.
+* This pattern (same name for type and value) is intentional for ergonomic API.
+*/
+const AsyncResult = {
+	err(error) {
+		return AsyncResultErr._create(error);
+	},
+	fromResult(result) {
+		if (result.isOk()) return AsyncResult.ok(result.value);
+		return AsyncResult.err(result.error);
+	},
+	loading() {
+		return AsyncResultLoading._create();
+	},
+	ok(value) {
+		return AsyncResultOk._create(value);
+	}
+};
 
+//#endregion
 //#region src/composables/mutation/mutation.composable.ts
 function useMutation(options) {
 	const isDebug = options.isDebug ?? false;
 	const queryClient = useQueryClient();
 	async function onSuccess(responseData, params) {
+		if (!options.queryKeysToInvalidate) return;
 		await Promise.all(Object.entries(options.queryKeysToInvalidate).map(async ([queryKey, queryKeyParams]) => {
+			if (!queryKeyParams) {
+				if (isDebug) console.log(`[MUTATION] Invalidating ${queryKey}`);
+				await queryClient.invalidateQueries({ queryKey: [queryKey] });
+				return;
+			}
 			const qkp = queryKeyParams;
-			const paramsWithValues = Object.entries(qkp).reduce((acc, [key, value]) => {
+			const paramEntries = Object.entries(qkp);
+			if (paramEntries.length === 0) {
+				if (isDebug) console.log(`[MUTATION] Invalidating ${queryKey}`);
+				await queryClient.invalidateQueries({ queryKey: [queryKey] });
+				return;
+			}
+			const paramsWithValues = paramEntries.reduce((acc, [key, value]) => {
 				acc[key] = value(params, responseData);
 				return acc;
 			}, {});
@@ -22,7 +169,9 @@ function useMutation(options) {
 	}
 	const mutation = useMutation$1({
 		mutationFn: options.queryFn,
-		onSuccess: async (data, variables) => {
+		onSuccess: async (result$1, variables) => {
+			if (!result$1.isOk()) return;
+			const data = result$1.value;
 			if (variables !== void 0 && "params" in variables) {
 				await onSuccess(data, variables.params);
 				return;
@@ -33,20 +182,34 @@ function useMutation(options) {
 	async function execute(data) {
 		return await mutation.mutateAsync(data);
 	}
+	const result = computed(() => {
+		if (mutation.isPending.value) return AsyncResult.loading();
+		if (mutation.isError.value && mutation.error.value) return AsyncResult.err(mutation.error.value);
+		if (mutation.isSuccess.value && mutation.data.value !== void 0) {
+			const apiResult = mutation.data.value;
+			if (apiResult.isOk()) return AsyncResult.ok(apiResult.value);
+			if (apiResult.isErr()) return AsyncResult.err(apiResult.error);
+		}
+		return AsyncResult.loading();
+	});
 	return {
 		isLoading: computed(() => mutation.isPending.value),
-		data: computed(() => mutation.data.value),
-		execute
+		data: computed(() => {
+			if (mutation.data.value?.isOk()) return mutation.data.value.value;
+			return null;
+		}),
+		execute,
+		result
 	};
 }
 
 //#endregion
 //#region src/config/config.ts
-const DEFAULT_LIMIT$2 = 20;
+const DEFAULT_LIMIT$3 = 20;
 const DEFAULT_PREFETCH_STALE_TIME = 60;
 const QUERY_CONFIG = {
 	prefetchStaleTime: DEFAULT_PREFETCH_STALE_TIME,
-	limit: DEFAULT_LIMIT$2
+	limit: DEFAULT_LIMIT$3
 };
 function setQueryConfig(config) {
 	if (config.limit != null && config.limit > 0) QUERY_CONFIG.limit = config.limit;
@@ -55,7 +218,7 @@ function setQueryConfig(config) {
 
 //#endregion
 //#region src/composables/query/keysetInfiniteQuery.composable.ts
-const DEFAULT_LIMIT$1 = QUERY_CONFIG.limit;
+const DEFAULT_LIMIT$2 = QUERY_CONFIG.limit;
 function useKeysetInfiniteQuery(options) {
 	function getQueryKey() {
 		const [queryKey, params] = Object.entries(options.queryKey)[0];
@@ -72,7 +235,7 @@ function useKeysetInfiniteQuery(options) {
 		placeholderData: (data) => data,
 		queryFn: ({ pageParam }) => options.queryFn({
 			key: pageParam,
-			limit: options.limit ?? DEFAULT_LIMIT$1
+			limit: options.limit ?? DEFAULT_LIMIT$2
 		}),
 		queryKey: getQueryKey()
 	});
@@ -80,18 +243,17 @@ function useKeysetInfiniteQuery(options) {
 		return Boolean(infiniteQuery.data.value?.pages.find((page) => page.isErr()));
 	});
 	const result = computed(() => {
+		if (infiniteQuery.isLoading.value) return AsyncResult.loading();
 		const firstError = infiniteQuery.data.value?.pages.find((page) => page.isErr());
-		if (firstError) return err(firstError.error);
+		if (firstError) return AsyncResult.err(firstError.error);
 		const data = infiniteQuery.data.value?.pages.filter((page) => page.isOk()).flatMap((page) => page.value.data) ?? [];
 		const firstPage = infiniteQuery.data.value?.pages[0];
-		const meta = firstPage?.isOk() ? firstPage.value.meta : {
-			next: null,
-			total: data.length
-		};
-		return ok({
+		const meta = firstPage?.isOk() ? firstPage.value.meta : { next: null };
+		const response = {
 			data,
 			meta: { next: infiniteQuery.hasNextPage.value ? meta.next : null }
-		});
+		};
+		return AsyncResult.ok(response);
 	});
 	function fetchNextPage() {
 		if (!infiniteQuery.hasNextPage.value || infiniteQuery.isFetchingNextPage.value) return;
@@ -116,7 +278,7 @@ function useKeysetInfiniteQuery(options) {
 
 //#endregion
 //#region src/composables/query/offsetInfiniteQuery.composable.ts
-const DEFAULT_LIMIT = QUERY_CONFIG.limit;
+const DEFAULT_LIMIT$1 = QUERY_CONFIG.limit;
 function useOffsetInfiniteQuery(options) {
 	function getQueryKey() {
 		const [first] = Object.entries(options.queryKey);
@@ -136,7 +298,7 @@ function useOffsetInfiniteQuery(options) {
 		initialPageParam: 0,
 		placeholderData: (data) => data,
 		queryFn: ({ pageParam }) => options.queryFn({
-			limit: options.limit ?? DEFAULT_LIMIT,
+			limit: options.limit ?? DEFAULT_LIMIT$1,
 			offset: pageParam ?? 0
 		}),
 		queryKey: getQueryKey()
@@ -145,19 +307,21 @@ function useOffsetInfiniteQuery(options) {
 		return Boolean(infiniteQuery.data.value?.pages.find((page) => page.isErr()));
 	});
 	const result = computed(() => {
+		if (infiniteQuery.isLoading.value) return AsyncResult.loading();
 		const firstError = infiniteQuery.data.value?.pages.find((page) => page.isErr());
-		if (firstError) return err(firstError.error);
+		if (firstError) return AsyncResult.err(firstError.error);
 		const data = infiniteQuery.data.value?.pages.filter((page) => page.isOk()).flatMap((page) => page.value.data) ?? [];
 		const firstPage = infiniteQuery.data.value?.pages[0];
 		const meta = firstPage?.isOk() ? firstPage.value.meta : null;
-		return ok({
+		const response = {
 			data,
 			meta: {
 				limit: meta?.limit ?? 0,
 				offset: meta?.offset ?? 0,
 				total: meta?.total ?? data.length
 			}
-		});
+		};
+		return AsyncResult.ok(response);
 	});
 	function fetchNextPage() {
 		if (!infiniteQuery.hasNextPage.value || infiniteQuery.isFetchingNextPage.value) return;
@@ -208,7 +372,9 @@ function useQuery(options) {
 		staleTime: options.staleTime,
 		enabled: options.isEnabled,
 		placeholderData: (data) => data,
-		queryFn: options.queryFn,
+		queryFn: async () => {
+			return AsyncResult.fromResult(await options.queryFn());
+		},
 		queryKey: getQueryKey()
 	});
 	function getQueryKey() {
@@ -225,9 +391,319 @@ function useQuery(options) {
 		isLoading: computed(() => query.isLoading.value),
 		isSuccess: computed(() => query.data.value?.isOk() ?? false),
 		refetch,
-		result: computed(() => query.data.value ?? null)
+		result: computed(() => {
+			if (query.isLoading.value) return AsyncResult.loading();
+			if (query.data.value?.isOk()) return AsyncResult.ok(query.data.value.getValue());
+			if (query.data.value?.isErr()) return AsyncResult.err(query.data.value.getError());
+			return AsyncResult.loading();
+		})
+	};
+}
+
+//#endregion
+//#region src/factory/createApiInfiniteQueryUtils.ts
+function createApiInfiniteQueryUtils() {
+	function useOffsetInfiniteQuery$1(key, queryOptions) {
+		const params = queryOptions.params ?? {};
+		const queryKey = { [key]: params };
+		return useOffsetInfiniteQuery({
+			staleTime: queryOptions.staleTime,
+			isEnabled: queryOptions.isEnabled,
+			limit: queryOptions.limit,
+			queryFn: queryOptions.queryFn,
+			queryKey
+		});
+	}
+	function useKeysetInfiniteQuery$1(key, queryOptions) {
+		const params = queryOptions.params ?? {};
+		const queryKey = { [key]: params };
+		return useKeysetInfiniteQuery({
+			staleTime: queryOptions.staleTime,
+			isEnabled: queryOptions.isEnabled,
+			limit: queryOptions.limit,
+			queryFn: queryOptions.queryFn,
+			queryKey
+		});
+	}
+	return {
+		useKeysetInfiniteQuery: useKeysetInfiniteQuery$1,
+		useOffsetInfiniteQuery: useOffsetInfiniteQuery$1
+	};
+}
+
+//#endregion
+//#region src/factory/createApiMutationUtils.ts
+function createApiMutationUtils() {
+	function useMutation$2(options) {
+		return useMutation({
+			isDebug: options.isDebug,
+			queryFn: options.queryFn,
+			queryKeysToInvalidate: options.queryKeysToInvalidate ?? {}
+		});
+	}
+	return { useMutation: useMutation$2 };
+}
+
+//#endregion
+//#region src/utils/optimisticUpdates.ts
+/**
+* OptimisticUpdates utility class for type-safe optimistic updates
+*/
+var OptimisticUpdates = class {
+	constructor(queryClient) {
+		this.queryClient = queryClient;
+	}
+	/**
+	* Extract the raw entity from AsyncResult data
+	*/
+	extractEntityFromAsyncResult(data) {
+		if (data === void 0 || data === null) return null;
+		if (typeof data === "object" && "isOk" in data) {
+			const asyncResult = data;
+			if (asyncResult.isOk()) return asyncResult.getValue();
+			return null;
+		}
+		return data;
+	}
+	isInfiniteDataLike(data) {
+		return Boolean(data && typeof data === "object" && "pages" in data && Array.isArray(data.pages));
+	}
+	/**
+	* Determine if an item should be updated
+	*/
+	shouldUpdateItem(by, item, value) {
+		if (typeof by === "function") return by(item);
+		if (by && typeof by === "object") return Object.entries(by).every(([key, matchValue]) => {
+			const itemValue = item[key];
+			return unref(itemValue) === unref(matchValue);
+		});
+		const idFromValue = value.id;
+		const itemId = item["id"];
+		if (idFromValue !== void 0 && itemId !== void 0) return unref(itemId) === unref(idFromValue);
+		return false;
+	}
+	/**
+	* Internal method to update entity based on the "by" option
+	*/
+	updateEntity(by, currentData, value) {
+		if (Array.isArray(currentData)) return currentData.map((item) => {
+			return this.shouldUpdateItem(by, item, value) ? {
+				...item,
+				...value
+			} : item;
+		});
+		if (this.shouldUpdateItem(by, currentData, value)) return {
+			...currentData,
+			...value
+		};
+		return currentData;
+	}
+	/**
+	* Wrap a raw entity in an AsyncResult (preserving ok state)
+	*/
+	wrapEntityInAsyncResult(entity) {
+		return AsyncResult.ok(entity);
+	}
+	get(queryKey, options) {
+		if (Array.isArray(queryKey)) {
+			const data = this.queryClient.getQueryData(queryKey);
+			return this.extractEntityFromAsyncResult(data);
+		}
+		if (options?.isExact ?? false) {
+			const normalizedKey = [queryKey];
+			const data = this.queryClient.getQueryData(normalizedKey);
+			return this.extractEntityFromAsyncResult(data);
+		}
+		const allQueries = this.queryClient.getQueryCache().findAll({ predicate: (query) => {
+			return query.queryKey[0] === queryKey;
+		} });
+		const results = [];
+		for (const query of allQueries) {
+			const data = query.state.data;
+			const entity = this.extractEntityFromAsyncResult(data);
+			if (entity !== null) results.push(entity);
+		}
+		return results;
+	}
+	async invalidate(keyOrTuple) {
+		const isSpecific = Array.isArray(keyOrTuple);
+		const key = isSpecific ? keyOrTuple[0] : keyOrTuple;
+		const params = isSpecific ? keyOrTuple[1] : null;
+		await this.queryClient.invalidateQueries({ predicate: (query) => {
+			const queryKey = query.queryKey;
+			if (queryKey[0] !== key) return false;
+			if (isSpecific && params && queryKey[1]) return Object.entries(params).every(([paramKey, paramValue]) => {
+				return queryKey[1][paramKey] === paramValue;
+			});
+			return !isSpecific;
+		} });
+	}
+	set(queryKey, entity) {
+		const wrappedData = this.wrapEntityInAsyncResult(entity);
+		const normalizedKey = Array.isArray(queryKey) ? queryKey : [queryKey];
+		this.queryClient.setQueryData(normalizedKey, wrappedData);
+	}
+	update(keyOrTuple, options) {
+		const by = options.by ?? void 0;
+		const value = options.value;
+		const isSpecific = Array.isArray(keyOrTuple);
+		const key = isSpecific ? keyOrTuple[0] : keyOrTuple;
+		const params = isSpecific ? keyOrTuple[1] : null;
+		const queries = this.queryClient.getQueryCache().findAll({ predicate: (query) => {
+			const queryKey = query.queryKey;
+			if (queryKey[0] !== key) return false;
+			if (isSpecific && params && queryKey[1]) return Object.entries(params).every(([paramKey, paramValue]) => {
+				return queryKey[1][paramKey] === paramValue;
+			});
+			return !isSpecific;
+		} });
+		for (const query of queries) {
+			const currentData = query.state.data;
+			if (this.isInfiniteDataLike(currentData)) {
+				const updatedInfiniteData = {
+					...currentData,
+					pages: currentData.pages.map((page) => {
+						if (page && typeof page === "object" && "map" in page && typeof page.map === "function") return page.map((pageValue) => {
+							if (pageValue && typeof pageValue === "object" && Array.isArray(pageValue.data)) return {
+								...pageValue,
+								data: this.updateEntity(by, pageValue.data, value)
+							};
+							return pageValue;
+						});
+						return page;
+					})
+				};
+				this.queryClient.setQueryData(query.queryKey, updatedInfiniteData);
+				continue;
+			}
+			const rawEntity = this.extractEntityFromAsyncResult(currentData);
+			if (rawEntity === null) continue;
+			const updatedEntity = this.updateEntity(by, rawEntity, value);
+			const wrappedData = this.wrapEntityInAsyncResult(updatedEntity);
+			this.queryClient.setQueryData(query.queryKey, wrappedData);
+		}
+	}
+};
+/**
+* Create an OptimisticUpdates instance
+*/
+function createOptimisticUpdates(queryClient) {
+	return new OptimisticUpdates(queryClient);
+}
+
+//#endregion
+//#region src/factory/createApiOptimisticUpdatesUtils.ts
+function createApiOptimisticUpdatesUtils(options) {
+	function useOptimisticUpdates() {
+		return new OptimisticUpdates(options.queryClient);
+	}
+	return { useOptimisticUpdates };
+}
+
+//#endregion
+//#region src/factory/createApiPrefetchInfiniteQueryUtils.ts
+const DEFAULT_LIMIT = QUERY_CONFIG.limit;
+function createApiPrefetchInfiniteQueryUtils(options) {
+	function usePrefetchOffsetInfiniteQuery(key, queryOptions) {
+		const queryKey = [key, queryOptions.params ?? {}];
+		async function execute() {
+			await options.queryClient.prefetchInfiniteQuery({
+				staleTime: queryOptions.staleTime,
+				getNextPageParam: (lastPage) => {
+					if (lastPage.isErr()) return null;
+					const total = lastPage.value.meta.offset + lastPage.value.meta.limit;
+					if (total >= lastPage.value.meta.total) return null;
+					return total;
+				},
+				initialPageParam: 0,
+				queryFn: ({ pageParam }) => queryOptions.queryFn({
+					limit: queryOptions.limit ?? DEFAULT_LIMIT,
+					offset: pageParam ?? 0
+				}),
+				queryKey
+			});
+		}
+		return { execute };
+	}
+	function usePrefetchKeysetInfiniteQuery(key, queryOptions) {
+		const queryKey = [key, queryOptions.params ?? {}];
+		async function execute() {
+			await options.queryClient.prefetchInfiniteQuery({
+				staleTime: queryOptions.staleTime,
+				getNextPageParam: (lastPage) => {
+					if (lastPage.isErr()) return null;
+					const next = lastPage.value.meta.next;
+					if (next === null || next === void 0) return null;
+					return next;
+				},
+				initialPageParam: void 0,
+				queryFn: ({ pageParam }) => queryOptions.queryFn({
+					key: pageParam,
+					limit: queryOptions.limit ?? DEFAULT_LIMIT
+				}),
+				queryKey
+			});
+		}
+		return { execute };
+	}
+	return {
+		usePrefetchKeysetInfiniteQuery,
+		usePrefetchOffsetInfiniteQuery
+	};
+}
+
+//#endregion
+//#region src/factory/createApiPrefetchQueryUtils.ts
+function createApiPrefetchQueryUtils(options) {
+	function usePrefetchQuery$1(key, queryOptions) {
+		const queryKey = [key, queryOptions.params ?? {}];
+		async function execute() {
+			await options.queryClient.prefetchQuery({
+				staleTime: queryOptions.staleTime ?? QUERY_CONFIG.prefetchStaleTime,
+				queryFn: async () => {
+					return AsyncResult.fromResult(await queryOptions.queryFn());
+				},
+				queryKey
+			});
+		}
+		return { execute };
+	}
+	return { usePrefetchQuery: usePrefetchQuery$1 };
+}
+
+//#endregion
+//#region src/factory/createApiQueryUtils.ts
+function createApiQueryUtils() {
+	function useQuery$2(key, queryOptions) {
+		const params = queryOptions.params ?? {};
+		const queryKey = { [key]: params };
+		return useQuery({
+			staleTime: queryOptions.staleTime,
+			isDebug: queryOptions.isDebug,
+			isEnabled: queryOptions.isEnabled,
+			queryFn: queryOptions.queryFn,
+			queryKey
+		});
+	}
+	return { useQuery: useQuery$2 };
+}
+
+//#endregion
+//#region src/factory/createApiUtils.ts
+/**
+* Factory that creates typed composables based on a user-provided query-keys config.
+* This is an alternative to module augmentation of `QueryKeys`.
+*/
+function createApiUtils(options) {
+	return {
+		...createApiQueryUtils(),
+		...createApiPrefetchQueryUtils(options),
+		...createApiPrefetchInfiniteQueryUtils(options),
+		...createApiInfiniteQueryUtils(),
+		...createApiMutationUtils(),
+		...createApiOptimisticUpdatesUtils(options)
 	};
 }
 
 //#endregion
-export { setQueryConfig, useKeysetInfiniteQuery, useMutation, useOffsetInfiniteQuery, usePrefetchQuery, useQuery };
+export { AsyncResult, AsyncResultErr, AsyncResultLoading, AsyncResultOk, OptimisticUpdates, createApiInfiniteQueryUtils, createApiMutationUtils, createApiOptimisticUpdatesUtils, createApiPrefetchInfiniteQueryUtils, createApiPrefetchQueryUtils, createApiQueryUtils, createApiUtils, createOptimisticUpdates, setQueryConfig, useKeysetInfiniteQuery, useMutation, useOffsetInfiniteQuery, usePrefetchQuery, useQuery };

package/package.json

@@ -4,7 +4,7 @@
     "access": "public"
   },
   "type": "module",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "license": "MIT",
   "sideEffects": false,
   "exports": {