@qualisero/openapi-endpoint 0.12.3 → 0.13.2

package/dist/openapi-query.d.ts

@@ -1,214 +1,79 @@
-import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
-import { Operations, type GetPathParameters, type GetResponseData, type QQueryOptions } from './types';
+import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
+import { Operations, type ApiPathParams, type ApiPathParamsInput, type ApiResponse, type QQueryOptions } from './types';
 import { type OpenApiHelpers } from './openapi-helpers';
-export type EndpointQueryReturn<Ops extends Operations<Ops>, Op extends keyof Ops> = ReturnType<typeof useEndpointQuery<Ops, Op>> & {
-    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
-};
 /**
- * Composable for performing a strictly typed OpenAPI query operation using Vue Query.
- * Ensures the operation is a query (GET/HEAD/OPTIONS) at runtime.
- * Returns a reactive query object, including helpers for query key, enabled state, and an `onLoad` callback.
+ * Return type of `useQuery` (created via `useOpenApi`).
  *
- * @template T OperationId type representing the OpenAPI operation.
- * @param operationId The OpenAPI operation ID to query.
- * @param pathParams Optional path parameters for the endpoint, can be reactive.
- * @param options Optional query options, including:
- *   - All properties from {@link UseQueryOptions} (from @tanstack/vue-query)
- *   - `enabled`: Whether the query should automatically run (boolean or reactive).
- *   - `onLoad`: Callback invoked once when data is loaded (immediately or after fetch).
- *   - `axiosOptions`: Custom axios request options (e.g., headers, params).
- * @throws Error if the operation is not a query operation.
- * @returns Query object with strict typing and helpers:
- *   - `data`: ComputedRef of response data.
- *   - `isEnabled`: ComputedRef indicating if query is enabled.
- *   - `queryKey`: ComputedRef of the query key.
- *   - `onLoad`: Method to register a callback for when data is loaded.
+ * Reactive query result with automatic caching, error handling, and helpers.
+ *
+ * All properties are reactive (ComputedRef) and auto-unwrap in Vue templates.
+ *
+ * @template Ops - The operations type from your OpenAPI specification
+ * @template Op - The operation key from your operations type
+ *
+ * @example
+ * ```typescript
+ * const query = api.useQuery('listPets', { queryParams: { limit: 10 } })
+ *
+ * // Reactive properties
+ * if (query.isPending.value) console.log('Loading...')
+ * if (query.isError.value) console.log('Error:', query.error.value)
+ * if (query.isSuccess.value) console.log('Data:', query.data.value)
+ *
+ * // Helpers
+ * query.refetch()  // Manual refetch
+ * query.onLoad((data) => console.log('First load:', data))
+ * ```
+ *
+ * @group Types
  */
-export declare function useEndpointQuery<Ops extends Operations<Ops>, Op extends keyof Ops>(operationId: Op, h: OpenApiHelpers<Ops, Op>, pathParamsOrOptions?: MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined> | QQueryOptions<Ops, Op>, optionsOrNull?: QQueryOptions<Ops, Op>): {
-    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
-    isEnabled: ComputedRef<boolean>;
-    queryKey: ComputedRef<(string | import("./types").GetQueryParameters<Ops, Op>)[]>;
-    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op> | null | undefined>;
-    error: import("vue").Ref<Error, Error>;
-    isError: import("vue").Ref<true, true>;
-    isPending: import("vue").Ref<false, false>;
-    isLoading: import("vue").Ref<false, false>;
-    isLoadingError: import("vue").Ref<false, false>;
-    isRefetchError: import("vue").Ref<true, true>;
-    isSuccess: import("vue").Ref<false, false>;
-    isPlaceholderData: import("vue").Ref<false, false>;
-    status: import("vue").Ref<"error", "error">;
-    dataUpdatedAt: import("vue").Ref<number, number>;
-    errorUpdatedAt: import("vue").Ref<number, number>;
-    failureCount: import("vue").Ref<number, number>;
-    failureReason: import("vue").Ref<Error | null, Error | null>;
-    errorUpdateCount: import("vue").Ref<number, number>;
-    isFetched: import("vue").Ref<boolean, boolean>;
-    isFetchedAfterMount: import("vue").Ref<boolean, boolean>;
-    isFetching: import("vue").Ref<boolean, boolean>;
-    isInitialLoading: import("vue").Ref<boolean, boolean>;
-    isPaused: import("vue").Ref<boolean, boolean>;
-    isRefetching: import("vue").Ref<boolean, boolean>;
-    isStale: import("vue").Ref<boolean, boolean>;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-    fetchStatus: import("vue").Ref<import("@tanstack/query-core").FetchStatus, import("@tanstack/query-core").FetchStatus>;
-    promise: import("vue").Ref<Promise<GetResponseData<Ops, Op>>, Promise<GetResponseData<Ops, Op>>>;
-    suspense: () => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-} | {
-    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
-    isEnabled: ComputedRef<boolean>;
-    queryKey: ComputedRef<(string | import("./types").GetQueryParameters<Ops, Op>)[]>;
-    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op> | null | undefined>;
-    error: import("vue").Ref<null, null>;
-    isError: import("vue").Ref<false, false>;
-    isPending: import("vue").Ref<false, false>;
-    isLoading: import("vue").Ref<false, false>;
-    isLoadingError: import("vue").Ref<false, false>;
-    isRefetchError: import("vue").Ref<false, false>;
-    isSuccess: import("vue").Ref<true, true>;
-    isPlaceholderData: import("vue").Ref<false, false>;
-    status: import("vue").Ref<"success", "success">;
-    dataUpdatedAt: import("vue").Ref<number, number>;
-    errorUpdatedAt: import("vue").Ref<number, number>;
-    failureCount: import("vue").Ref<number, number>;
-    failureReason: import("vue").Ref<Error | null, Error | null>;
-    errorUpdateCount: import("vue").Ref<number, number>;
-    isFetched: import("vue").Ref<boolean, boolean>;
-    isFetchedAfterMount: import("vue").Ref<boolean, boolean>;
-    isFetching: import("vue").Ref<boolean, boolean>;
-    isInitialLoading: import("vue").Ref<boolean, boolean>;
-    isPaused: import("vue").Ref<boolean, boolean>;
-    isRefetching: import("vue").Ref<boolean, boolean>;
-    isStale: import("vue").Ref<boolean, boolean>;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-    fetchStatus: import("vue").Ref<import("@tanstack/query-core").FetchStatus, import("@tanstack/query-core").FetchStatus>;
-    promise: import("vue").Ref<Promise<GetResponseData<Ops, Op>>, Promise<GetResponseData<Ops, Op>>>;
-    suspense: () => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-} | {
-    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+export interface EndpointQueryReturn<Ops extends Operations<Ops>, Op extends keyof Ops> {
+    /** The response data (undefined until loaded). */
+    data: ComputedRef<ApiResponse<Ops, Op> | undefined>;
+    /** The error if the query failed. */
+    error: Ref<Error | null>;
+    /** True while the query is loading. */
+    isPending: Ref<boolean>;
+    /** True while loading (same as isPending, for compatibility). */
+    isLoading: Ref<boolean>;
+    /** True when the query succeeded. */
+    isSuccess: Ref<boolean>;
+    /** True when the query failed. */
+    isError: Ref<boolean>;
+    /** Manually trigger a refetch. */
+    refetch: () => Promise<void>;
+    /** Whether the query is currently enabled. */
     isEnabled: ComputedRef<boolean>;
-    queryKey: ComputedRef<(string | import("./types").GetQueryParameters<Ops, Op>)[]>;
-    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op> | null | undefined>;
-    error: import("vue").Ref<Error, Error>;
-    isError: import("vue").Ref<true, true>;
-    isPending: import("vue").Ref<false, false>;
-    isLoading: import("vue").Ref<false, false>;
-    isLoadingError: import("vue").Ref<true, true>;
-    isRefetchError: import("vue").Ref<false, false>;
-    isSuccess: import("vue").Ref<false, false>;
-    isPlaceholderData: import("vue").Ref<false, false>;
-    status: import("vue").Ref<"error", "error">;
-    dataUpdatedAt: import("vue").Ref<number, number>;
-    errorUpdatedAt: import("vue").Ref<number, number>;
-    failureCount: import("vue").Ref<number, number>;
-    failureReason: import("vue").Ref<Error | null, Error | null>;
-    errorUpdateCount: import("vue").Ref<number, number>;
-    isFetched: import("vue").Ref<boolean, boolean>;
-    isFetchedAfterMount: import("vue").Ref<boolean, boolean>;
-    isFetching: import("vue").Ref<boolean, boolean>;
-    isInitialLoading: import("vue").Ref<boolean, boolean>;
-    isPaused: import("vue").Ref<boolean, boolean>;
-    isRefetching: import("vue").Ref<boolean, boolean>;
-    isStale: import("vue").Ref<boolean, boolean>;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-    fetchStatus: import("vue").Ref<import("@tanstack/query-core").FetchStatus, import("@tanstack/query-core").FetchStatus>;
-    promise: import("vue").Ref<Promise<GetResponseData<Ops, Op>>, Promise<GetResponseData<Ops, Op>>>;
-    suspense: () => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-} | {
-    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
-    isEnabled: ComputedRef<boolean>;
-    queryKey: ComputedRef<(string | import("./types").GetQueryParameters<Ops, Op>)[]>;
-    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op> | null | undefined>;
-    error: import("vue").Ref<null, null>;
-    isError: import("vue").Ref<false, false>;
-    isPending: import("vue").Ref<true, true>;
-    isLoading: import("vue").Ref<true, true>;
-    isLoadingError: import("vue").Ref<false, false>;
-    isRefetchError: import("vue").Ref<false, false>;
-    isSuccess: import("vue").Ref<false, false>;
-    isPlaceholderData: import("vue").Ref<false, false>;
-    status: import("vue").Ref<"pending", "pending">;
-    dataUpdatedAt: import("vue").Ref<number, number>;
-    errorUpdatedAt: import("vue").Ref<number, number>;
-    failureCount: import("vue").Ref<number, number>;
-    failureReason: import("vue").Ref<Error | null, Error | null>;
-    errorUpdateCount: import("vue").Ref<number, number>;
-    isFetched: import("vue").Ref<boolean, boolean>;
-    isFetchedAfterMount: import("vue").Ref<boolean, boolean>;
-    isFetching: import("vue").Ref<boolean, boolean>;
-    isInitialLoading: import("vue").Ref<boolean, boolean>;
-    isPaused: import("vue").Ref<boolean, boolean>;
-    isRefetching: import("vue").Ref<boolean, boolean>;
-    isStale: import("vue").Ref<boolean, boolean>;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-    fetchStatus: import("vue").Ref<import("@tanstack/query-core").FetchStatus, import("@tanstack/query-core").FetchStatus>;
-    promise: import("vue").Ref<Promise<GetResponseData<Ops, Op>>, Promise<GetResponseData<Ops, Op>>>;
-    suspense: () => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-} | {
-    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
-    isEnabled: ComputedRef<boolean>;
-    queryKey: ComputedRef<(string | import("./types").GetQueryParameters<Ops, Op>)[]>;
-    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op> | null | undefined>;
-    error: import("vue").Ref<null, null>;
-    isError: import("vue").Ref<false, false>;
-    isPending: import("vue").Ref<true, true>;
-    isLoadingError: import("vue").Ref<false, false>;
-    isRefetchError: import("vue").Ref<false, false>;
-    isSuccess: import("vue").Ref<false, false>;
-    isPlaceholderData: import("vue").Ref<false, false>;
-    status: import("vue").Ref<"pending", "pending">;
-    dataUpdatedAt: import("vue").Ref<number, number>;
-    errorUpdatedAt: import("vue").Ref<number, number>;
-    failureCount: import("vue").Ref<number, number>;
-    failureReason: import("vue").Ref<Error | null, Error | null>;
-    errorUpdateCount: import("vue").Ref<number, number>;
-    isFetched: import("vue").Ref<boolean, boolean>;
-    isFetchedAfterMount: import("vue").Ref<boolean, boolean>;
-    isFetching: import("vue").Ref<boolean, boolean>;
-    isLoading: import("vue").Ref<boolean, boolean>;
-    isInitialLoading: import("vue").Ref<boolean, boolean>;
-    isPaused: import("vue").Ref<boolean, boolean>;
-    isRefetching: import("vue").Ref<boolean, boolean>;
-    isStale: import("vue").Ref<boolean, boolean>;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-    fetchStatus: import("vue").Ref<import("@tanstack/query-core").FetchStatus, import("@tanstack/query-core").FetchStatus>;
-    promise: import("vue").Ref<Promise<GetResponseData<Ops, Op>>, Promise<GetResponseData<Ops, Op>>>;
-    suspense: () => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-} | {
-    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
-    isEnabled: ComputedRef<boolean>;
-    queryKey: ComputedRef<(string | import("./types").GetQueryParameters<Ops, Op>)[]>;
-    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
-    pathParams: ComputedRef<GetPathParameters<Ops, Op> | null | undefined>;
-    isError: import("vue").Ref<false, false>;
-    error: import("vue").Ref<null, null>;
-    isPending: import("vue").Ref<false, false>;
-    isLoading: import("vue").Ref<false, false>;
-    isLoadingError: import("vue").Ref<false, false>;
-    isRefetchError: import("vue").Ref<false, false>;
-    isSuccess: import("vue").Ref<true, true>;
-    isPlaceholderData: import("vue").Ref<true, true>;
-    status: import("vue").Ref<"success", "success">;
-    dataUpdatedAt: import("vue").Ref<number, number>;
-    errorUpdatedAt: import("vue").Ref<number, number>;
-    failureCount: import("vue").Ref<number, number>;
-    failureReason: import("vue").Ref<Error | null, Error | null>;
-    errorUpdateCount: import("vue").Ref<number, number>;
-    isFetched: import("vue").Ref<boolean, boolean>;
-    isFetchedAfterMount: import("vue").Ref<boolean, boolean>;
-    isFetching: import("vue").Ref<boolean, boolean>;
-    isInitialLoading: import("vue").Ref<boolean, boolean>;
-    isPaused: import("vue").Ref<boolean, boolean>;
-    isRefetching: import("vue").Ref<boolean, boolean>;
-    isStale: import("vue").Ref<boolean, boolean>;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-    fetchStatus: import("vue").Ref<import("@tanstack/query-core").FetchStatus, import("@tanstack/query-core").FetchStatus>;
-    promise: import("vue").Ref<Promise<GetResponseData<Ops, Op>>, Promise<GetResponseData<Ops, Op>>>;
-    suspense: () => Promise<import("@tanstack/query-core").QueryObserverResult<GetResponseData<Ops, Op>, Error>>;
-};
+    /** The resolved query key for manual cache access. */
+    queryKey: ComputedRef<string[] | (string | unknown)[]>;
+    /** The resolved path parameters. */
+    pathParams: ComputedRef<ApiPathParams<Ops, Op>>;
+    /** Register a callback for when data loads successfully for the first time. */
+    onLoad: (callback: (data: ApiResponse<Ops, Op>) => void) => void;
+}
+/**
+ * Execute a type-safe query (GET/HEAD/OPTIONS) with automatic caching.
+ *
+ * Ensures the operation is a query at runtime and returns a reactive query object,
+ * including helpers for query key, enabled state, and an `onLoad` callback.
+ *
+ * @template Ops - The operations type from your OpenAPI specification
+ * @template Op - The operation key from your operations type
+ * @param operationId - The OpenAPI operation ID to query
+ * @param h - OpenAPI helpers (internal), provided by useOpenApi
+ * @param pathParams - Path parameters (can be reactive). Omit for operations without path params.
+ * @param options - Query options (enabled, staleTime, queryParams, etc.)
+ *   - `enabled`: Whether the query should auto-run (boolean or reactive)
+ *   - `queryParams`: Query string parameters (operation-specific)
+ *   - `onLoad`: Callback invoked once when data is loaded
+ *   - `axiosOptions`: Custom axios request options (headers, params, etc.)
+ *   - Plus all {@link UseQueryOptions} from @tanstack/vue-query
+ * @throws Error if the operation is not a query operation
+ * @returns Query object with strict typing and helpers:
+ *   - `data`: ComputedRef of response data
+ *   - `isEnabled`: ComputedRef indicating if query is enabled
+ *   - `queryKey`: ComputedRef of the query key
+ *   - `onLoad(callback)`: Register a callback for when data is loaded
+ */
+export declare function useEndpointQuery<Ops extends Operations<Ops>, Op extends keyof Ops>(operationId: Op, h: OpenApiHelpers<Ops, Op>, pathParams?: MaybeRefOrGetter<ApiPathParamsInput<Ops, Op> | null | undefined>, options?: QQueryOptions<Ops, Op>): EndpointQueryReturn<Ops, Op>;
 //# sourceMappingURL=openapi-query.d.ts.map

package/dist/openapi-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-query.d.ts","sourceRoot":"","sources":["../src/openapi-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAEvF,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAA;AAGtG,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD,MAAM,MAAM,mBAAmB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,IAAI,UAAU,CAC7F,OAAO,gBAAgB,CAAC,GAAG,EAAE,EAAE,CAAC,CACjC,GAAG;IACF,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAAA;CACrE,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,EAChF,WAAW,EAAE,EAAE,EACf,CAAC,EAAE,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,EAC1B,mBAAmB,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,EAC9G,aAAa,CAAC,EAAE,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC;UAgIhB,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;uBAN7C,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAM5C,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;uBAN7C,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAM5C,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;uBAN7C,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAM5C,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;uBAN7C,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAM5C,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;uBAN7C,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAM5C,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;uBAN7C,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYnE"}
+{"version":3,"file":"openapi-query.d.ts","sourceRoot":"","sources":["../src/openapi-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,GAAG,EAAE,MAAM,KAAK,CAAA;AAEjG,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAA;AAGvH,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,mBAAmB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG;IACpF,kDAAkD;IAClD,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,CAAA;IAEnD,qCAAqC;IACrC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;IAExB,uCAAuC;IACvC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAEvB,iEAAiE;IACjE,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAEvB,qCAAqC;IACrC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAEvB,kCAAkC;IAClC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAErB,kCAAkC;IAClC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5B,8CAA8C;IAC9C,SAAS,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IAE/B,sDAAsD;IACtD,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC,CAAA;IAEtD,oCAAoC;IACpC,UAAU,EAAE,WAAW,CAAC,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAA;IAE/C,+EAA+E;IAC/E,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAAA;CACjE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,EAChF,WAAW,EAAE,EAAE,EACf,CAAC,EAAE,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,EAC1B,UAAU,CAAC,EAAE,gBAAgB,CAAC,kBAAkB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,EAC7E,OAAO,CAAC,EAAE,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,GA+HhB,mBAAmB,CAAC,GAAG,EAAE,EAAE,CAAC,CAC7C"}

package/dist/openapi-query.js

@@ -1,64 +1,50 @@
 import { computed, watch, toValue } from 'vue';
 import { useQuery } from '@tanstack/vue-query';
-import { resolvePath, generateQueryKey, isPathResolved, getParamsOptionsFrom } from './openapi-utils.js';
+import { normalizeParamsOptions, useResolvedOperation } from './openapi-utils.js';
 import { isAxiosError } from 'axios';
 /**
- * Composable for performing a strictly typed OpenAPI query operation using Vue Query.
- * Ensures the operation is a query (GET/HEAD/OPTIONS) at runtime.
- * Returns a reactive query object, including helpers for query key, enabled state, and an `onLoad` callback.
+ * Execute a type-safe query (GET/HEAD/OPTIONS) with automatic caching.
  *
- * @template T OperationId type representing the OpenAPI operation.
- * @param operationId The OpenAPI operation ID to query.
- * @param pathParams Optional path parameters for the endpoint, can be reactive.
- * @param options Optional query options, including:
- *   - All properties from {@link UseQueryOptions} (from @tanstack/vue-query)
- *   - `enabled`: Whether the query should automatically run (boolean or reactive).
- *   - `onLoad`: Callback invoked once when data is loaded (immediately or after fetch).
- *   - `axiosOptions`: Custom axios request options (e.g., headers, params).
- * @throws Error if the operation is not a query operation.
+ * Ensures the operation is a query at runtime and returns a reactive query object,
+ * including helpers for query key, enabled state, and an `onLoad` callback.
+ *
+ * @template Ops - The operations type from your OpenAPI specification
+ * @template Op - The operation key from your operations type
+ * @param operationId - The OpenAPI operation ID to query
+ * @param h - OpenAPI helpers (internal), provided by useOpenApi
+ * @param pathParams - Path parameters (can be reactive). Omit for operations without path params.
+ * @param options - Query options (enabled, staleTime, queryParams, etc.)
+ *   - `enabled`: Whether the query should auto-run (boolean or reactive)
+ *   - `queryParams`: Query string parameters (operation-specific)
+ *   - `onLoad`: Callback invoked once when data is loaded
+ *   - `axiosOptions`: Custom axios request options (headers, params, etc.)
+ *   - Plus all {@link UseQueryOptions} from @tanstack/vue-query
+ * @throws Error if the operation is not a query operation
  * @returns Query object with strict typing and helpers:
- *   - `data`: ComputedRef of response data.
- *   - `isEnabled`: ComputedRef indicating if query is enabled.
- *   - `queryKey`: ComputedRef of the query key.
- *   - `onLoad`: Method to register a callback for when data is loaded.
+ *   - `data`: ComputedRef of response data
+ *   - `isEnabled`: ComputedRef indicating if query is enabled
+ *   - `queryKey`: ComputedRef of the query key
+ *   - `onLoad(callback)`: Register a callback for when data is loaded
  */
-export function useEndpointQuery(operationId, h, pathParamsOrOptions, optionsOrNull) {
+export function useEndpointQuery(operationId, h, pathParams, options) {
     // Runtime check to ensure this is actually a query operation
     if (!h.isQueryOperation(operationId)) {
-        throw new Error(`Operation ${String(operationId)} is not a query operation (GET/HEAD/OPTIONS)`);
+        const { method } = h.getOperationInfo(operationId);
+        throw new Error(`Operation '${String(operationId)}' uses method ${method} and cannot be used with useQuery(). ` +
+            `Use useMutation() for POST/PUT/PATCH/DELETE operations.`);
     }
     const { path, method } = h.getOperationInfo(operationId);
-    const { pathParams, options } = getParamsOptionsFrom(path, pathParamsOrOptions, optionsOrNull);
-    const { enabled: enabledInit, onLoad: onLoadInit, axiosOptions, errorHandler, queryParams, ...useQueryOptions } = options;
-    // Make path parameters reactive by ensuring toValue is called inside computed
-    // This ensures that when pathParams is a function, it gets called within the computed
-    // so Vue can track dependencies of variables referenced inside the function
-    const allPathParams = computed(() => {
-        const result = toValue(pathParams);
-        return result;
-    });
-    const resolvedPath = computed(() => resolvePath(path, allPathParams.value));
-    // Make query parameters reactive
-    const allQueryParams = computed(() => {
-        const result = toValue(queryParams);
-        return result;
-    });
-    // Include query params in the query key so changes trigger refetch
-    const queryKey = computed(() => {
-        const baseKey = generateQueryKey(resolvedPath.value);
-        const qParams = allQueryParams.value;
-        if (qParams && Object.keys(qParams).length > 0) {
-            return [...baseKey, qParams];
-        }
-        return baseKey;
-    });
+    const { pathParams: resolvedPathParamsInput, options: resolvedOptions } = normalizeParamsOptions(pathParams, options);
+    const { enabled: enabledInit, onLoad: onLoadInit, axiosOptions, errorHandler, queryParams, ...useQueryOptions } = resolvedOptions;
+    // Use the consolidated operation resolver
+    const { resolvedPath, queryKey, isResolved, queryParams: resolvedQueryParams, pathParams: resolvedPathParams, } = useResolvedOperation(path, resolvedPathParamsInput, queryParams);
     // Check if path is fully resolved for enabling the query
     const isEnabled = computed(() => {
         const baseEnabled = enabledInit !== undefined ? toValue(enabledInit) : true;
-        return baseEnabled && isPathResolved(resolvedPath.value);
+        return baseEnabled && isResolved.value;
     });
-    const query = useQuery({
-        queryKey,
+    const queryOptions = {
+        queryKey: queryKey,
         queryFn: async () => {
             try {
                 const response = await h.axios({
@@ -67,7 +53,7 @@ export function useEndpointQuery(operationId, h, pathParamsOrOptions, optionsOrN
                     ...axiosOptions,
                     params: {
                         ...(axiosOptions?.params || {}),
-                        ...(allQueryParams.value || {}),
+                        ...(resolvedQueryParams.value || {}),
                     },
                 });
                 return response.data;
@@ -99,40 +85,49 @@ export function useEndpointQuery(operationId, h, pathParamsOrOptions, optionsOrN
             return _failureCount < 3;
         },
         ...useQueryOptions,
-    }, h.queryClient);
-    // onLoad callback is called once, as soon as data is available (immediately or when loading finishes)
-    // Shared onLoad handler setup
-    const setupOnLoadHandler = (callback) => {
-        // If data is already available, call immediately
+    };
+    const query = useQuery(queryOptions, h.queryClient);
+    // onLoad callback management using a Set for efficient tracking
+    const onLoadCallbacks = new Set();
+    // Add initial callback from options if provided
+    if (onLoadInit) {
+        onLoadCallbacks.add(onLoadInit);
+    }
+    // Single watch instance to handle all callbacks - stop after first successful data
+    if (query.data.value !== undefined) {
+        // Data already available - call all callbacks immediately
+        onLoadCallbacks.forEach((cb) => cb(query.data.value));
+        onLoadCallbacks.clear();
+    }
+    else {
+        // Watch for data to become available - stop after first successful load
+        const stopWatch = watch(query.data, (newData) => {
+            if (newData !== undefined && onLoadCallbacks.size > 0) {
+                // Call all pending callbacks
+                onLoadCallbacks.forEach((cb) => cb(newData));
+                onLoadCallbacks.clear();
+                stopWatch(); // Stop watching after first successful load
+            }
+        });
+    }
+    // Public onLoad method to register additional callbacks
+    const onLoad = (callback) => {
         if (query.data.value !== undefined) {
+            // Data already available - call immediately
             callback(query.data.value);
         }
         else {
-            // Watch for data to become available
-            let hasLoaded = false;
-            const stopWatch = watch(query.data, (newData) => {
-                if (newData !== undefined && !hasLoaded) {
-                    hasLoaded = true;
-                    callback(newData);
-                    stopWatch(); // Stop watching after first load
-                }
-            });
+            // Add to pending callbacks
+            onLoadCallbacks.add(callback);
         }
     };
-    // Handle onLoad callback from options
-    if (onLoadInit) {
-        setupOnLoadHandler(onLoadInit);
-    }
-    // Create onLoad method
-    const onLoad = (callback) => {
-        setupOnLoadHandler(callback);
-    };
+    // Return object spread with data wrapped as ComputedRef for Vue template unwrapping
     return {
         ...query,
-        data: query.data,
+        data: computed(() => query.data.value),
         isEnabled,
         queryKey,
         onLoad,
-        pathParams: allPathParams,
+        pathParams: resolvedPathParams,
     };
 }

package/dist/openapi-utils.d.ts

@@ -1,10 +1,36 @@
-import { type MaybeRefOrGetter } from 'vue';
-import { type GetPathParameters, type QMutationOptions, type QQueryOptions, Operations } from './types';
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
 export declare function resolvePath(path: string, pathParams?: MaybeRefOrGetter<Record<string, string | number | undefined> | null | undefined>): string;
 export declare function isPathResolved(path: string): boolean;
 export declare function generateQueryKey(resolvedPath: string): string[];
-export declare function getParamsOptionsFrom<Ops extends Operations<Ops>, Op extends keyof Ops, Options extends QMutationOptions<Ops, Op> | QQueryOptions<Ops, Op>>(path: string, pathParamsOrOptions?: MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined> | Options, optionsOrNull?: Options): {
-    pathParams: MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined>;
+/**
+ * Return type for useResolvedOperation composable
+ */
+export interface ResolvedOperation<PathParams, QueryParams> {
+    /** Computed path parameters (resolved from reactive source) */
+    pathParams: ComputedRef<PathParams>;
+    /** Computed resolved path with parameters substituted */
+    resolvedPath: ComputedRef<string>;
+    /** Computed query parameters (resolved from reactive source) */
+    queryParams: ComputedRef<QueryParams>;
+    /** Computed query key for TanStack Query */
+    queryKey: ComputedRef<string[] | (string | QueryParams)[]>;
+    /** Whether the path is fully resolved (all params provided) */
+    isResolved: ComputedRef<boolean>;
+}
+/**
+ * Composable for resolving operation paths and parameters.
+ * Consolidates the common pattern of computing resolved paths, query keys, and parameters.
+ *
+ * @param path - The OpenAPI path template (e.g., '/pets/{petId}')
+ * @param pathParams - Reactive path parameters
+ * @param queryParams - Optional reactive query parameters
+ * @param extraPathParams - Optional ref for additional path params (used by mutations)
+ */
+export declare function useResolvedOperation<PathParams extends Record<string, string | number | undefined> = Record<string, never>, QueryParams extends Record<string, unknown> = Record<string, never>>(path: string, pathParams: MaybeRefOrGetter<PathParams | null | undefined>, queryParams?: MaybeRefOrGetter<QueryParams | null | undefined>, extraPathParams?: {
+    value: Partial<PathParams>;
+}): ResolvedOperation<PathParams, QueryParams>;
+export declare function normalizeParamsOptions<PathParams extends Record<string, unknown>, Options>(pathParams?: MaybeRefOrGetter<PathParams | null | undefined>, options?: Options): {
+    pathParams: MaybeRefOrGetter<PathParams | null | undefined>;
     options: Options;
 };
 //# sourceMappingURL=openapi-utils.d.ts.map

package/dist/openapi-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-utils.d.ts","sourceRoot":"","sources":["../src/openapi-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAA;AACpD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AA2BvG,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAC5F,MAAM,CAaR;AAcD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAGD,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/D;AAED,wBAAgB,oBAAoB,CAClC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAC3B,EAAE,SAAS,MAAM,GAAG,EACpB,OAAO,SAAS,gBAAgB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,EAElE,IAAI,EAAE,MAAM,EACZ,mBAAmB,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,OAAO,EAC/F,aAAa,CAAC,EAAE,OAAO,GACtB;IACD,UAAU,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;IAC3E,OAAO,EAAE,OAAO,CAAA;CACjB,CA+BA"}
+{"version":3,"file":"openapi-utils.d.ts","sourceRoot":"","sources":["../src/openapi-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAGhF,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAC5F,MAAM,CAaR;AAGD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAGD,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/D;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,UAAU,EAAE,WAAW;IACxD,+DAA+D;IAC/D,UAAU,EAAE,WAAW,CAAC,UAAU,CAAC,CAAA;IACnC,yDAAyD;IACzD,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACjC,gEAAgE;IAChE,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,CAAA;IACrC,4CAA4C;IAC5C,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAA;IAC1D,+DAA+D;IAC/D,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CACjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACtF,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAEnE,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,gBAAgB,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,EAC3D,WAAW,CAAC,EAAE,gBAAgB,CAAC,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,EAC9D,eAAe,CAAC,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAA;CAAE,GAC/C,iBAAiB,CAAC,UAAU,EAAE,WAAW,CAAC,CAuC5C;AAED,wBAAgB,sBAAsB,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EACxF,UAAU,CAAC,EAAE,gBAAgB,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,EAC5D,OAAO,CAAC,EAAE,OAAO,GAChB;IACD,UAAU,EAAE,gBAAgB,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;IAC3D,OAAO,EAAE,OAAO,CAAA;CACjB,CAKA"}