@qualisero/openapi-endpoint 0.12.1 → 0.13.2

package/README.md

@@ -4,6 +4,7 @@
 [![CI](https://github.com/qualisero/openapi-endpoint/workflows/CI/badge.svg)](https://github.com/qualisero/openapi-endpoint/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@qualisero/openapi-endpoint)](https://bundlephobia.com/package/@qualisero/openapi-endpoint)
+[![Documentation](https://img.shields.io/badge/docs-online-brightgreen.svg)](https://qualisero.github.io/openapi-endpoint/)
 
 Turns your `openapi.json` into typesafe API composables using Vue Query (TanStack Query): guaranteeing that your frontend and backend share the same contract.
 
@@ -12,9 +13,9 @@ Turns your `openapi.json` into typesafe API composables using Vue Query (TanStac
 Let's you get TanStack Vue Query composables that enforce consistency (name of endpoints, typing) with your API's `openapi.json` file:
 
 ```typescript
-const { data, isLoading } = api.useQuery(OperationId.getPet, { petId: '123' })
+const { data, isLoading } = api.useQuery(QueryOperationId.getPet, { petId: '123' })
 
-const createPetMutation = api.useMutation(OperationId.createPet)
+const createPetMutation = api.useMutation(MutationOperationId.createPet)
 createPetMutation.mutate({ data: { name: 'Fluffy', species: 'cat' } })
 ```
 
@@ -51,7 +52,12 @@ import { useOpenApi } from '@qualisero/openapi-endpoint'
 import axios from 'axios'
 
 // Import your auto-generated operations (includes both metadata and types)
-import { OperationId, openApiOperations, type OpenApiOperations } from './generated/api-operations'
+import {
+  QueryOperationId,
+  MutationOperationId,
+  openApiOperations,
+  type OpenApiOperations,
+} from './generated/api-operations'
 
 // Create axios instance
 const axiosInstance = axios.create({
@@ -65,21 +71,21 @@ const api = useOpenApi<OpenApiOperations>({
 })
 
 // Export for use in other parts of your application
-export { api, OperationId }
+export { api, QueryOperationId, MutationOperationId, OperationId }
 ```
 
 ### 2. Use the API in your components
 
 ```typescript
 // In your Vue components
-import { api, OperationId } from './api/init'
+import { api, QueryOperationId, MutationOperationId } from './api/init'
 
 // Use queries for GET operations
-const { data: pets, isLoading } = api.useQuery(OperationId.listPets)
-const { data: pet } = api.useQuery(OperationId.getPet, { petId: '123' })
+const { data: pets, isLoading } = api.useQuery(QueryOperationId.listPets)
+const { data: pet } = api.useQuery(QueryOperationId.getPet, { petId: '123' })
 
 // Use mutations for POST/PUT/PATCH/DELETE operations
-const createPetMutation = api.useMutation(OperationId.createPet)
+const createPetMutation = api.useMutation(MutationOperationId.createPet)
 
 // Execute mutations
 await createPetMutation.mutateAsync({
@@ -95,10 +101,10 @@ The library supports type-safe, reactive query parameters that automatically tri
 
 ```typescript
 import { ref, computed } from 'vue'
-import { api, OperationId } from './api/init'
+import { api, QueryOperationId } from './api/init'
 
 // Static query parameters
-const { data: pets } = api.useQuery(OperationId.listPets, {
+const { data: pets } = api.useQuery(QueryOperationId.listPets, {
   queryParams: { limit: 10 },
 })
 // Results in: GET /pets?limit=10
@@ -107,7 +113,7 @@ const { data: pets } = api.useQuery(OperationId.listPets, {
 const limit = ref(10)
 const status = ref<'available' | 'pending' | 'sold'>('available')
 
-const petsQuery = api.useQuery(OperationId.listPets, {
+const petsQuery = api.useQuery(QueryOperationId.listPets, {
   queryParams: computed(() => ({
     limit: limit.value,
     status: status.value,
@@ -121,7 +127,7 @@ status.value = 'pending'
 
 // Combine with path parameters
 const userPetsQuery = api.useQuery(
-  OperationId.listUserPets,
+  QueryOperationId.listUserPets,
   computed(() => ({ userId: userId.value })),
   {
     queryParams: computed(() => ({
@@ -139,27 +145,6 @@ const userPetsQuery = api.useQuery(
 - **Automatic refetch**: Changes to query params trigger automatic refetch via TanStack Query's key mechanism
 - **Backward compatible**: Works alongside existing `axiosOptions.params`
 
-### Automatic Operation Type Detection with `api.useEndpoint`
-
-The `api.useEndpoint` method automatically detects whether an operation is a query (GET/HEAD/OPTIONS) or mutation (POST/PUT/PATCH/DELETE) based on the HTTP method defined in your OpenAPI specification:
-
-```typescript
-import { ref, computed } from 'vue'
-import { api, OperationId } from './api/init'
-
-// Automatically becomes a query for GET operations
-const listEndpoint = api.useEndpoint(OperationId.listPets)
-// TypeScript knows this has query properties like .data, .isLoading, .refetch()
-
-// Automatically becomes a mutation for POST operations
-const createEndpoint = api.useEndpoint(OperationId.createPet)
-// TypeScript knows this has mutation properties like .mutate(), .mutateAsync()
-
-// Use the endpoints according to their detected type
-const petData = listEndpoint.data // Query data
-await createEndpoint.mutateAsync({ data: { name: 'Fluffy' } }) // Mutation execution
-```
-
 ### Automatic Cache Management and Refetching
 
 By default, mutations automatically:
@@ -170,19 +155,19 @@ By default, mutations automatically:
 
 ```typescript
 // Default behavior: automatic cache management
-const createPet = api.useMutation(OperationId.createPet)
+const createPet = api.useMutation(MutationOperationId.createPet)
 // No additional configuration needed - cache management is automatic
 
 // Manual control over cache invalidation
-const updatePet = api.useMutation(OperationId.updatePet, {
+const updatePet = api.useMutation(MutationOperationId.updatePet, {
   dontInvalidate: true, // Disable automatic invalidation
   dontUpdateCache: true, // Disable automatic cache updates
-  invalidateOperations: [OperationId.listPets], // Manually specify operations to invalidate
+  invalidateOperations: [QueryOperationId.listPets], // Manually specify operations to invalidate
 })
 
 // Refetch specific endpoints after mutation
-const petListQuery = api.useQuery(OperationId.listPets)
-const createPetWithRefetch = api.useMutation(OperationId.createPet, {
+const petListQuery = api.useQuery(QueryOperationId.listPets)
+const createPetWithRefetch = api.useMutation(MutationOperationId.createPet, {
   refetchEndpoints: [petListQuery], // Manually refetch these endpoints
 })
 ```
@@ -197,7 +182,7 @@ async function uploadPetPicture(petId: string, file: File) {
   const formData = new FormData()
   formData.append('file', file)
 
-  const uploadMutation = api.useMutation(OperationId.uploadPetPic, { petId })
+  const uploadMutation = api.useMutation(MutationOperationId.uploadPetPic, { petId })
 
   return uploadMutation.mutateAsync({
     data: formData,
@@ -211,7 +196,7 @@ async function uploadPetPicture(petId: string, file: File) {
 
 // Alternative: using the object structure (if your API supports binary strings)
 async function uploadPetPictureAsString(petId: string, binaryData: string) {
-  const uploadMutation = api.useMutation(OperationId.uploadPetPic, { petId })
+  const uploadMutation = api.useMutation(MutationOperationId.uploadPetPic, { petId })
 
   return uploadMutation.mutateAsync({
     data: {
@@ -230,10 +215,10 @@ async function handleFileUpload(event: Event, petId: string) {
   formData.append('file', file)
 
   const uploadMutation = api.useMutation(
-    OperationId.uploadPetPic,
+    MutationOperationId.uploadPetPic,
     { petId },
     {
-      invalidateOperations: [OperationId.getPet, OperationId.listPets],
+      invalidateOperations: [QueryOperationId.getPet, QueryOperationId.listPets],
       onSuccess: (data) => {
         console.log('Upload successful:', data)
       },
@@ -253,17 +238,17 @@ async function handleFileUpload(event: Event, petId: string) {
 
 ### Reactive Enabling/Disabling Based on Path Parameters
 
-One powerful feature is chaining queries where one query provides the parameters for another:
+You can chain queries where one query provides the parameters for another:
 
 ```typescript
 import { ref, computed } from 'vue'
 
 // First query to get user information
-const userQuery = api.useQuery(OperationId.getUser, { userId: 123 })
+const userQuery = api.useQuery(QueryOperationId.getUser, { userId: 123 })
 
 // Second query that depends on the first query's result
 const userPetsQuery = api.useQuery(
-  OperationId.listUserPets,
+  QueryOperationId.listUserPets,
   computed(() => ({
     userId: userQuery.data.value?.id, // Chain: use ID from first query
   })),
@@ -274,7 +259,7 @@ const selectedPetId = ref<string | undefined>(undefined)
 
 // Query automatically enables/disables based on parameter availability
 const petQuery = api.useQuery(
-  OperationId.getPet,
+  QueryOperationId.getPet,
   computed(() => ({ petId: selectedPetId.value })),
 )
 
@@ -290,7 +275,7 @@ const userId = ref<string>('user1')
 const shouldFetchPets = ref(true)
 
 const userPetsQuery = api.useQuery(
-  OperationId.listUserPets,
+  QueryOperationId.listUserPets,
   computed(() => ({ userId: userId.value })),
   {
     enabled: computed(
@@ -307,7 +292,7 @@ import { ref } from 'vue'
 
 // Use reactive query parameters
 const limit = ref(10)
-const petsQuery = api.useQuery(OperationId.listPets, {
+const petsQuery = api.useQuery(QueryOperationId.listPets, {
   queryParams: { limit: limit.value },
 })