@qualisero/openapi-endpoint 0.2.3

package/dist/openapi-mutation.d.ts

@@ -0,0 +1,112 @@
+import { type ComputedRef, type Ref, type MaybeRefOrGetter } from 'vue';
+import { type GetPathParameters, type MutationVars, type GetResponseData, type MutationOptions, Operations } from './types';
+import { getHelpers } from './openapi-helpers';
+export type EndpointMutationReturn<Ops extends Operations<Ops>, Op extends keyof Ops> = ReturnType<typeof useEndpointMutation<Ops, Op>>;
+/**
+ * Composable for performing a strictly typed OpenAPI mutation operation using Vue Query.
+ * Ensures the operation is a mutation (POST/PUT/PATCH/DELETE) at runtime.
+ * Returns a reactive mutation object, including helpers for query key and enabled state.
+ *
+ * NOTE: By default, the mutation will automatically update cache with returned data and reload
+ * any matching GET queries for the same path.
+ *
+ * @template T OperationId type representing the OpenAPI operation.
+ * @param operationId The OpenAPI operation ID to mutate.
+ * @param pathParams Optional path parameters for the endpoint, can be reactive.
+ * @param options Optional mutation options, including Vue Query options and custom axios options:
+ *   - 'dontUpdateCache': If true, will not update cache with returned data (default: false)
+ *   - 'dontInvalidate': If true, will not invalidate matching GET queries (default: false)
+ *  - 'invalidateOperations': List of additional OperationIds to invalidate after mutation (can also be a map of OperationId to path parameters)
+ * - 'refetchEndpoints': List of additional EndpointQueryReturn objects to refetch after mutation
+ *   - `axiosOptions`: Custom axios request options (e.g., headers, params)
+ *   - All properties from {@link UseMutationOptions} (from @tanstack/vue-query)
+ * @throws Error if the operation is not a mutation operation.
+ * @returns Mutation object with
+ *   - `data`: ComputedRef of response data.
+ *   - `isEnabled`: ComputedRef indicating if mutation can be executed (path resolved).
+ *   - `extraPathParams`: Ref to set of additional path parameters when calling mutate.
+ *   - `mutate` and `mutateAsync`: Functions to trigger the mutation, taking an object with:
+ *     - `data`: The request body data for the mutation.
+ *     - `pathParams`: Optional additional path parameters for the mutation.
+ *    - `dontUpdateCache`, `dontInvalidate`, `invalidateOperations`, `refetchEndpoints`: Same as options, but can be set per-mutation.
+ *   - All other properties and methods from the underlying Vue Query mutation object.
+ */
+export declare function useEndpointMutation<Ops extends Operations<Ops>, Op extends keyof Ops>(operationId: Op, h: ReturnType<typeof getHelpers<Ops, Op>>, // helpers
+pathParamsOrOptions?: MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined> | MutationOptions<Ops, Op>, optionsOrNull?: MutationOptions<Ops, Op>): {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    extraPathParams: Ref<GetPathParameters<Ops, Op>, GetPathParameters<Ops, Op>>;
+    error: Ref<null, null>;
+    isError: Ref<false, false>;
+    isPending: Ref<false, false>;
+    isSuccess: Ref<false, false>;
+    status: Ref<"idle", "idle">;
+    failureCount: Ref<number, number>;
+    failureReason: Ref<Error | null, Error | null>;
+    isPaused: Ref<boolean, boolean>;
+    variables: Ref<undefined, undefined>;
+    isIdle: Ref<true, true>;
+    context: Ref<unknown, unknown>;
+    submittedAt: Ref<number, number>;
+    mutate: (variables: MutationVars<Ops, Op>, options?: import("@tanstack/query-core").MutateOptions<GetResponseData<Ops, Op>, Error, MutationVars<Ops, Op>, unknown> | undefined) => void;
+    mutateAsync: import("@tanstack/query-core").MutateFunction<GetResponseData<Ops, Op>, Error, MutationVars<Ops, Op>, unknown>;
+    reset: import("@tanstack/query-core").MutationObserverResult<TData, TError, TVariables, TOnMutateResult>["reset"];
+} | {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    extraPathParams: Ref<GetPathParameters<Ops, Op>, GetPathParameters<Ops, Op>>;
+    error: Ref<null, null>;
+    isError: Ref<false, false>;
+    isPending: Ref<true, true>;
+    isSuccess: Ref<false, false>;
+    status: Ref<"pending", "pending">;
+    failureCount: Ref<number, number>;
+    failureReason: Ref<Error | null, Error | null>;
+    isPaused: Ref<boolean, boolean>;
+    variables: Ref<MutationVars<Ops, Op>, MutationVars<Ops, Op>>;
+    isIdle: Ref<false, false>;
+    context: Ref<unknown, unknown>;
+    submittedAt: Ref<number, number>;
+    mutate: (variables: MutationVars<Ops, Op>, options?: import("@tanstack/query-core").MutateOptions<GetResponseData<Ops, Op>, Error, MutationVars<Ops, Op>, unknown> | undefined) => void;
+    mutateAsync: import("@tanstack/query-core").MutateFunction<GetResponseData<Ops, Op>, Error, MutationVars<Ops, Op>, unknown>;
+    reset: import("@tanstack/query-core").MutationObserverResult<TData, TError, TVariables, TOnMutateResult>["reset"];
+} | {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    extraPathParams: Ref<GetPathParameters<Ops, Op>, GetPathParameters<Ops, Op>>;
+    error: Ref<Error, Error>;
+    isError: Ref<true, true>;
+    isPending: Ref<false, false>;
+    isSuccess: Ref<false, false>;
+    status: Ref<"error", "error">;
+    failureCount: Ref<number, number>;
+    failureReason: Ref<Error | null, Error | null>;
+    isPaused: Ref<boolean, boolean>;
+    variables: Ref<MutationVars<Ops, Op>, MutationVars<Ops, Op>>;
+    isIdle: Ref<false, false>;
+    context: Ref<unknown, unknown>;
+    submittedAt: Ref<number, number>;
+    mutate: (variables: MutationVars<Ops, Op>, options?: import("@tanstack/query-core").MutateOptions<GetResponseData<Ops, Op>, Error, MutationVars<Ops, Op>, unknown> | undefined) => void;
+    mutateAsync: import("@tanstack/query-core").MutateFunction<GetResponseData<Ops, Op>, Error, MutationVars<Ops, Op>, unknown>;
+    reset: import("@tanstack/query-core").MutationObserverResult<TData, TError, TVariables, TOnMutateResult>["reset"];
+} | {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    extraPathParams: Ref<GetPathParameters<Ops, Op>, GetPathParameters<Ops, Op>>;
+    error: Ref<null, null>;
+    isError: Ref<false, false>;
+    isPending: Ref<false, false>;
+    isSuccess: Ref<true, true>;
+    status: Ref<"success", "success">;
+    failureCount: Ref<number, number>;
+    failureReason: Ref<Error | null, Error | null>;
+    isPaused: Ref<boolean, boolean>;
+    variables: Ref<MutationVars<Ops, Op>, MutationVars<Ops, Op>>;
+    isIdle: Ref<false, false>;
+    context: Ref<unknown, unknown>;
+    submittedAt: Ref<number, number>;
+    mutate: (variables: MutationVars<Ops, Op>, options?: import("@tanstack/query-core").MutateOptions<GetResponseData<Ops, Op>, Error, MutationVars<Ops, Op>, unknown> | undefined) => void;
+    mutateAsync: import("@tanstack/query-core").MutateFunction<GetResponseData<Ops, Op>, Error, MutationVars<Ops, Op>, unknown>;
+    reset: import("@tanstack/query-core").MutationObserverResult<TData, TError, TVariables, TOnMutateResult>["reset"];
+};
+//# sourceMappingURL=openapi-mutation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-mutation.d.ts","sourceRoot":"","sources":["../src/openapi-mutation.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,WAAW,EAAE,KAAK,GAAG,EAAE,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAG/F,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EAEpB,UAAU,EACX,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE9C,MAAM,MAAM,sBAAsB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,IAAI,UAAU,CAChG,OAAO,mBAAmB,CAAC,GAAG,EAAE,EAAE,CAAC,CACpC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,MAAM,GAAG,EACnF,WAAW,EAAE,EAAE,EACf,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU;AACrD,mBAAmB,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,EAChH,aAAa,CAAC,EAAE,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC;UAmIf,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;UAAjD,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;UAAjD,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;UAAjD,WAAW,CAAC,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;EAI3E"}

package/dist/openapi-mutation.js

@@ -0,0 +1,135 @@
+import { computed, ref, toValue } from 'vue';
+import { useMutation } from '@tanstack/vue-query';
+import { HttpMethod, } from './types';
+import { resolvePath, generateQueryKey, isPathResolved, getParamsOptionsFrom } from './openapi-utils';
+import { queryClient } from './index';
+/**
+ * Composable for performing a strictly typed OpenAPI mutation operation using Vue Query.
+ * Ensures the operation is a mutation (POST/PUT/PATCH/DELETE) at runtime.
+ * Returns a reactive mutation object, including helpers for query key and enabled state.
+ *
+ * NOTE: By default, the mutation will automatically update cache with returned data and reload
+ * any matching GET queries for the same path.
+ *
+ * @template T OperationId type representing the OpenAPI operation.
+ * @param operationId The OpenAPI operation ID to mutate.
+ * @param pathParams Optional path parameters for the endpoint, can be reactive.
+ * @param options Optional mutation options, including Vue Query options and custom axios options:
+ *   - 'dontUpdateCache': If true, will not update cache with returned data (default: false)
+ *   - 'dontInvalidate': If true, will not invalidate matching GET queries (default: false)
+ *  - 'invalidateOperations': List of additional OperationIds to invalidate after mutation (can also be a map of OperationId to path parameters)
+ * - 'refetchEndpoints': List of additional EndpointQueryReturn objects to refetch after mutation
+ *   - `axiosOptions`: Custom axios request options (e.g., headers, params)
+ *   - All properties from {@link UseMutationOptions} (from @tanstack/vue-query)
+ * @throws Error if the operation is not a mutation operation.
+ * @returns Mutation object with
+ *   - `data`: ComputedRef of response data.
+ *   - `isEnabled`: ComputedRef indicating if mutation can be executed (path resolved).
+ *   - `extraPathParams`: Ref to set of additional path parameters when calling mutate.
+ *   - `mutate` and `mutateAsync`: Functions to trigger the mutation, taking an object with:
+ *     - `data`: The request body data for the mutation.
+ *     - `pathParams`: Optional additional path parameters for the mutation.
+ *    - `dontUpdateCache`, `dontInvalidate`, `invalidateOperations`, `refetchEndpoints`: Same as options, but can be set per-mutation.
+ *   - All other properties and methods from the underlying Vue Query mutation object.
+ */
+export function useEndpointMutation(operationId, h, // helpers
+pathParamsOrOptions, optionsOrNull) {
+    // Runtime check to ensure this is actually a mutation operation
+    if (!h.isMutationOperation(operationId)) {
+        throw new Error(`Operation ${String(operationId)} is not a mutation operation (POST/PUT/PATCH/DELETE)`);
+    }
+    const { path, method } = h.getOperationInfo(operationId);
+    const { pathParams, options } = getParamsOptionsFrom(pathParamsOrOptions, optionsOrNull);
+    const { axiosOptions, dontInvalidate, dontUpdateCache, invalidateOperations, refetchEndpoints, ...useMutationOptions } = options;
+    const extraPathParams = ref({});
+    // Compute the resolved path
+    const allPathParams = computed(() => ({
+        ...toValue(pathParams),
+        ...extraPathParams.value,
+    }));
+    const resolvedPath = computed(() => resolvePath(path, allPathParams.value));
+    const queryKey = computed(() => generateQueryKey(resolvedPath.value));
+    const mutation = useMutation({
+        mutationFn: async (vars) => {
+            const { data, pathParams: pathParamsFromMutate } = vars;
+            extraPathParams.value = pathParamsFromMutate || {};
+            // TODO: use typing to ensure all required path params are provided
+            if (!isPathResolved(resolvedPath.value)) {
+                return Promise.reject(new Error(`Mutation for '${String(operationId)}' cannot be used, as path is not resolved: ${resolvedPath.value} (params: ${JSON.stringify(allPathParams.value)})`));
+            }
+            // Cancel any ongoing queries for this path (prevent race conditions with refresh)
+            await queryClient.cancelQueries({ queryKey: queryKey.value, exact: false });
+            const response = await h.axios({
+                method: method.toLowerCase(),
+                url: resolvedPath.value,
+                data: data,
+                ...(axiosOptions || {}),
+            });
+            return response.data;
+        },
+        onSuccess: async (data, vars, _context) => {
+            const { dontInvalidate: dontInvalidateMutate, dontUpdateCache: dontUpdateCacheMutate, invalidateOperations: invalidateOperationsMutate, refetchEndpoints: refetchEndpointsMutate, } = vars;
+            // Optimistically update cache with returned data for PUT/PATCH requests
+            if (
+            // dontUpdateCacheMutate supersedes dontUpdateCache from options
+            (dontInvalidateMutate !== undefined ? !dontInvalidateMutate : !dontInvalidate) &&
+                data &&
+                [HttpMethod.PUT, HttpMethod.PATCH].includes(method)) {
+                await queryClient.setQueryData(queryKey.value, data);
+            }
+            // Invalidate queries for this path, and any additional specified operations
+            if (dontUpdateCacheMutate !== undefined ? !dontUpdateCacheMutate : !dontUpdateCache) {
+                // Invalidate all queries for this path (exact for POST, prefix for others):
+                await queryClient.invalidateQueries({ queryKey: queryKey.value, exact: method !== HttpMethod.POST });
+                const listPath = h.getListOperationPath(operationId);
+                if (listPath) {
+                    const listResolvedPath = resolvePath(listPath, pathParams);
+                    if (isPathResolved(listResolvedPath)) {
+                        const listQueryKey = generateQueryKey(listResolvedPath);
+                        await queryClient.invalidateQueries({ queryKey: listQueryKey, exact: true });
+                    }
+                }
+            }
+            const operationsWithPathParams = [];
+            Array.from([invalidateOperations, invalidateOperationsMutate]).forEach((ops) => {
+                operationsWithPathParams.push(...(typeof ops === 'object' && !Array.isArray(ops)
+                    ? Object.entries(ops)
+                    : ops?.map((opId) => [opId, {}]) || []));
+            });
+            if (operationsWithPathParams.length > 0) {
+                const promises = operationsWithPathParams.map(([opId, opParams]) => {
+                    const opInfo = h.getOperationInfo(opId);
+                    const opPath = resolvePath(opInfo.path, {
+                        ...allPathParams.value,
+                        ...opParams,
+                    });
+                    if (isPathResolved(opPath)) {
+                        const opQueryKey = generateQueryKey(opPath);
+                        return queryClient.invalidateQueries({ queryKey: opQueryKey, exact: true });
+                    }
+                    else {
+                        console.warn(`Cannot invalidate operation '${String(opId)}', path not resolved: ${opPath} (params: ${JSON.stringify({ ...allPathParams.value, ...opParams })})`);
+                        return Promise.reject();
+                    }
+                });
+                await Promise.all(promises);
+            }
+            if (refetchEndpoints && refetchEndpoints.length > 0) {
+                await Promise.all(refetchEndpoints.map((endpoint) => endpoint.refetch()));
+            }
+            if (refetchEndpointsMutate && refetchEndpointsMutate.length > 0) {
+                await Promise.all(refetchEndpointsMutate.map((endpoint) => endpoint.refetch()));
+            }
+        },
+        onSettled: () => {
+            extraPathParams.value = {};
+        },
+        ...useMutationOptions,
+    });
+    return {
+        ...mutation,
+        data: mutation.data,
+        isEnabled: computed(() => isPathResolved(resolvedPath.value)),
+        extraPathParams,
+    };
+}

package/dist/openapi-query.d.ts

@@ -0,0 +1,209 @@
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+import { Operations, type GetPathParameters, type GetResponseData, type QueryOptions } from './types';
+import type { AxiosError } from 'axios';
+import { getHelpers } 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.
+ *
+ * @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.
+ */
+export declare function useEndpointQuery<Ops extends Operations<Ops>, Op extends keyof Ops>(operationId: Op, h: ReturnType<typeof getHelpers<Ops, Op>>, pathParamsOrOptions?: MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined> | QueryOptions<Ops, Op>, optionsOrNull?: QueryOptions<Ops, Op>): {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    queryKey: ComputedRef<string[]>;
+    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
+    error: import("vue").Ref<AxiosError<unknown, any>, AxiosError<unknown, any>>;
+    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<AxiosError<unknown, any> | null, AxiosError<unknown, any> | 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>, AxiosError<unknown, any>>>;
+    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>, AxiosError<unknown, any>>>;
+} | {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    queryKey: ComputedRef<string[]>;
+    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
+    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<AxiosError<unknown, any> | null, AxiosError<unknown, any> | 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>, AxiosError<unknown, any>>>;
+    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>, AxiosError<unknown, any>>>;
+} | {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    queryKey: ComputedRef<string[]>;
+    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
+    error: import("vue").Ref<AxiosError<unknown, any>, AxiosError<unknown, any>>;
+    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<AxiosError<unknown, any> | null, AxiosError<unknown, any> | 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>, AxiosError<unknown, any>>>;
+    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>, AxiosError<unknown, any>>>;
+} | {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    queryKey: ComputedRef<string[]>;
+    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
+    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<AxiosError<unknown, any> | null, AxiosError<unknown, any> | 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>, AxiosError<unknown, any>>>;
+    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>, AxiosError<unknown, any>>>;
+} | {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    queryKey: ComputedRef<string[]>;
+    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
+    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<AxiosError<unknown, any> | null, AxiosError<unknown, any> | 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>, AxiosError<unknown, any>>>;
+    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>, AxiosError<unknown, any>>>;
+} | {
+    data: ComputedRef<GetResponseData<Ops, Op> | undefined>;
+    isEnabled: ComputedRef<boolean>;
+    queryKey: ComputedRef<string[]>;
+    onLoad: (callback: (data: GetResponseData<Ops, Op>) => void) => void;
+    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<AxiosError<unknown, any> | null, AxiosError<unknown, any> | 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>, AxiosError<unknown, any>>>;
+    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>, AxiosError<unknown, any>>>;
+};
+//# sourceMappingURL=openapi-query.d.ts.map

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

@@ -0,0 +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,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,YAAY,EAGlB,MAAM,SAAS,CAAA;AAEhB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAU9C,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,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EACzC,mBAAmB,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,YAAY,CAAC,GAAG,EAAE,EAAE,CAAC,EAC7G,aAAa,CAAC,EAAE,YAAY,CAAC,GAAG,EAAE,EAAE,CAAC;UAiFf,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;;;;;;;;;;;;;;;;;;;;;;;;;;EAWnE"}

package/dist/openapi-query.js

@@ -0,0 +1,97 @@
+import { computed, watch, toValue } from 'vue';
+import { useQuery } from '@tanstack/vue-query';
+import { resolvePath, generateQueryKey, isPathResolved, getParamsOptionsFrom } from './openapi-utils';
+import { queryClient } from './index';
+/**
+ * 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.
+ *
+ * @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.
+ */
+export function useEndpointQuery(operationId, h, pathParamsOrOptions, optionsOrNull) {
+    // 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 { path, method } = h.getOperationInfo(operationId);
+    const { pathParams, options } = getParamsOptionsFrom(pathParamsOrOptions, optionsOrNull);
+    const { enabled: enabledInit, onLoad: onLoadInit, axiosOptions, ...useQueryOptions } = options;
+    const resolvedPath = computed(() => resolvePath(path, pathParams));
+    const queryKey = computed(() => generateQueryKey(resolvedPath.value));
+    // Check if path is fully resolved for enabling the query
+    const isEnabled = computed(() => {
+        // can be explicitly disabled via options
+        const baseEnabled = enabledInit !== undefined ? toValue(enabledInit) : true;
+        return baseEnabled && isPathResolved(resolvedPath.value);
+    });
+    const query = useQuery({
+        queryKey: queryKey,
+        queryFn: async () => {
+            const response = await h.axios({
+                method: method.toLowerCase(),
+                url: resolvedPath.value,
+                ...(axiosOptions || {}),
+            });
+            return response.data;
+        },
+        enabled: isEnabled,
+        staleTime: 1000 * 60,
+        retry: (failureCount, error) => {
+            // Don't retry 4xx errors
+            if (error.response && error.response.status >= 400 && error.response.status < 500) {
+                return false;
+            }
+            // Retry up to 3 times for other errors
+            return failureCount < 3;
+        },
+        ...useQueryOptions,
+    }, 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
+        if (query.data.value !== undefined) {
+            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
+                }
+            });
+        }
+    };
+    // Handle onLoad callback from options
+    if (onLoadInit) {
+        setupOnLoadHandler(onLoadInit);
+    }
+    // Create onLoad method
+    const onLoad = (callback) => {
+        setupOnLoadHandler(callback);
+    };
+    return {
+        ...query,
+        data: query.data,
+        isEnabled,
+        queryKey,
+        onLoad,
+    };
+}

package/dist/openapi-utils.d.ts

@@ -0,0 +1,10 @@
+import { type MaybeRefOrGetter } from 'vue';
+import { type GetPathParameters, type MutationOptions, type QueryOptions, Operations } from './types';
+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 MutationOptions<Ops, Op> | QueryOptions<Ops, Op>>(pathParamsOrOptions?: MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined> | Options, optionsOrNull?: Options): {
+    pathParams: MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined>;
+    options: Options;
+};
+//# sourceMappingURL=openapi-utils.d.ts.map

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

@@ -0,0 +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,eAAe,EAAE,KAAK,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAGrG,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,wBAAgB,oBAAoB,CAClC,GAAG,SAAS,UAAU,CAAC,GAAG,CAAC,EAC3B,EAAE,SAAS,MAAM,GAAG,EACpB,OAAO,SAAS,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,YAAY,CAAC,GAAG,EAAE,EAAE,CAAC,EAEhE,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,CAiBA"}

package/dist/openapi-utils.js

@@ -0,0 +1,43 @@
+import { toValue } from 'vue';
+// Helper to resolve path parameters in a URL path
+export function resolvePath(path, pathParams) {
+    if (pathParams === null || pathParams === undefined)
+        return path;
+    const pathParamsValue = toValue(pathParams);
+    if (!pathParamsValue)
+        return path;
+    let resolvedPath = path;
+    Object.entries(pathParamsValue).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+            resolvedPath = resolvedPath.replace(`{${key}}`, String(value));
+        }
+    });
+    return resolvedPath;
+}
+// Helper to check if all required path parameters are provided
+export function isPathResolved(path) {
+    return !/{[^}]+}/.test(path);
+}
+// Helper to generate query key from resolved path
+export function generateQueryKey(resolvedPath) {
+    return resolvedPath.split('/').filter((segment) => segment.length > 0);
+}
+export function getParamsOptionsFrom(pathParamsOrOptions, optionsOrNull) {
+    // Check if pathParamsOrOptions is MutationOptions or QueryOptions by checking if options is undefined
+    // and pathParamsOrOptions has MutationOptions properties
+    let pathParams;
+    let options;
+    if (optionsOrNull === undefined && pathParamsOrOptions && typeof pathParamsOrOptions === 'object') {
+        // Called as: useEndpointQuery(operationId, options)
+        options = pathParamsOrOptions;
+    }
+    else {
+        // Called as: useEndpointQuery(operationId, pathParams, options)
+        pathParams = pathParamsOrOptions;
+        options = optionsOrNull;
+    }
+    return {
+        pathParams: pathParams ?? {},
+        options: options ?? {},
+    };
+}