nuxt-graphql-middleware 5.2.3 → 5.3.1

package/docs/composables/useAsyncGraphqlQuery.md

@@ -0,0 +1,313 @@
+# useAsyncGraphqlQuery
+
+This composable is a wrapper around Nuxt's
+[useAsyncData](https://nuxt.com/docs/api/composables/use-async-data) that
+executes a GraphQL query via the middleware. It provides SSR-compatible,
+reactive data fetching with automatic refetching when variables change.
+
+## Basic Usage
+
+```typescript
+const { data } = await useAsyncGraphqlQuery('users')
+```
+
+This is equivalent to:
+
+```typescript
+const { data } = await useAsyncData(() => useGraphqlQuery('users'))
+```
+
+## With Variables
+
+Pass variables as the second argument:
+
+```typescript
+const { data } = await useAsyncGraphqlQuery('filmById', { id: '123' })
+```
+
+## Reactive Variables
+
+When variables are wrapped in a `computed` ref, the query automatically
+refetches when variables change:
+
+```typescript
+import type { UserByIdQueryVariables } from '#graphql-operations'
+
+const route = useRoute()
+
+const variables = computed<UserByIdQueryVariables>(() => {
+  return {
+    id: route.params.id.toString(),
+  }
+})
+
+const { data } = await useAsyncGraphqlQuery('userById', variables)
+```
+
+The composable automatically adds reactive variables to the `watch` option of
+`useAsyncData`, triggering a refetch whenever the variables change.
+
+## Options
+
+The third argument accepts options that extend
+[AsyncDataOptions](https://nuxt.com/docs/api/composables/use-async-data#params)
+with additional GraphQL-specific settings:
+
+```typescript
+const { data } = await useAsyncGraphqlQuery('users', null, {
+  // All useAsyncData options are supported
+  transform: (response) => response.data.users,
+  default: () => [],
+  immediate: true,
+  server: true,
+
+  // GraphQL-specific options
+  graphqlCaching: { client: true },
+  fetchOptions: { headers: { 'x-custom': 'value' } },
+  clientContext: { language: 'en' },
+})
+```
+
+### transform
+
+Transform the response before storing it in `data`. This is useful to extract
+nested data or modify the response structure:
+
+```typescript
+const { data: users } = await useAsyncGraphqlQuery('users', null, {
+  transform: (response) => {
+    // response.data is UsersQuery
+    return response.data.users
+  },
+})
+
+// users.value is now the users array directly
+```
+
+### graphqlCaching
+
+Enable client-side caching for this query. Requires `clientCache.enabled: true`
+in module options. See [Caching](/features/caching) for more details.
+
+```typescript
+const { data } = await useAsyncGraphqlQuery('users', null, {
+  graphqlCaching: {
+    client: true,
+  },
+})
+```
+
+When enabled:
+
+- Results are cached in memory using an LRU cache
+- Subsequent calls with the same variables return cached data
+- Cache survives client-side navigation
+- SSR payload data is preserved during hydration
+
+### fetchOptions
+
+Pass options to the underlying `$fetch` call to the middleware endpoint:
+
+```typescript
+const { data } = await useAsyncGraphqlQuery('users', null, {
+  fetchOptions: {
+    headers: {
+      authorization: `Bearer ${token}`,
+    },
+    timeout: 5000,
+  },
+})
+```
+
+### clientContext
+
+Override or extend the global client context for this specific request. Values
+here take precedence over those defined in
+[defineGraphqlClientOptions](/configuration/client-options):
+
+```typescript
+const { data } = await useAsyncGraphqlQuery('users', null, {
+  clientContext: {
+    language: 'de', // Override the global language for this request
+  },
+})
+```
+
+## Return Value
+
+Returns the same object as
+[useAsyncData](https://nuxt.com/docs/api/composables/use-async-data#return-values):
+
+```typescript
+const {
+  data, // Ref<T | undefined> - The response data
+  pending, // Ref<boolean> - Loading state
+  error, // Ref<Error | undefined> - Error if request failed
+  status, // Ref<'idle' | 'pending' | 'success' | 'error'>
+  refresh, // () => Promise<void> - Manually refetch data
+  execute, // () => Promise<void> - Same as refresh
+  clear, // () => void - Clear data and error
+} = await useAsyncGraphqlQuery('users')
+```
+
+## Type Safety
+
+The composable is fully typed based on your GraphQL operations:
+
+```typescript
+// Variables are type-checked
+const { data } = await useAsyncGraphqlQuery('userById', {
+  id: '123', // ✅ Correct type
+  // id: 123  // ❌ Type error: expected string
+})
+
+// Response data is typed
+if (data.value) {
+  console.log(data.value.data.userById?.name) // ✅ Autocomplete works
+}
+```
+
+Operations that require variables will show a type error if variables are
+omitted:
+
+```typescript
+// ❌ Type error: variables required
+const { data } = await useAsyncGraphqlQuery('userById')
+
+// ✅ Correct
+const { data } = await useAsyncGraphqlQuery('userById', { id: '123' })
+```
+
+## Hot Module Reloading
+
+During development, the composable automatically refetches data when the
+underlying GraphQL document or any used fragments change. This provides instant
+feedback when modifying queries.
+
+## Important Considerations
+
+### Execution Context
+
+Like `useAsyncData`, this composable must be called in specific contexts:
+
+- **Component setup function** - At the root level, not inside callbacks
+- **Plugin setup** - During plugin initialization
+- **Route middleware** - During navigation
+- **Other composables** - When called from a composable that follows these rules
+
+```typescript
+// ✅ Correct - at root of setup
+const { data } = await useAsyncGraphqlQuery('users')
+
+// ❌ Wrong - inside a callback
+const onClick = async () => {
+  // This won't work correctly with SSR
+  const { data } = await useAsyncGraphqlQuery('users')
+}
+```
+
+For fetching data inside event handlers or callbacks, use
+[useGraphqlQuery](/composables/useGraphqlQuery) instead.
+
+### Unique Keys
+
+The composable automatically generates a unique key for `useAsyncData` based on:
+
+- The operation name
+- A hash of the variables
+
+This ensures that different variable combinations are cached separately and
+multiple instances don't conflict.
+
+## Examples
+
+### Pagination
+
+```typescript
+import type { UsersPaginatedQueryVariables } from '#graphql-operations'
+
+const page = ref(1)
+const limit = 10
+
+const variables = computed<UsersPaginatedQueryVariables>(() => ({
+  offset: (page.value - 1) * limit,
+  limit,
+}))
+
+const { data, pending } = await useAsyncGraphqlQuery(
+  'usersPaginated',
+  variables,
+  {
+    transform: (response) => response.data.users,
+  },
+)
+
+function nextPage() {
+  page.value++
+  // Query automatically refetches due to reactive variables
+}
+```
+
+### Conditional Fetching
+
+```typescript
+const userId = ref<string | null>(null)
+
+const variables = computed(() => (userId.value ? { id: userId.value } : null))
+
+const { data } = await useAsyncGraphqlQuery('userById', variables, {
+  // Don't fetch until we have a userId
+  immediate: false,
+})
+
+// Later, when userId is set:
+userId.value = '123'
+// The query will now execute
+```
+
+### Error Handling
+
+```typescript
+const { data, error, refresh } = await useAsyncGraphqlQuery('users')
+
+// Check for errors
+if (error.value) {
+  console.error('Query failed:', error.value.message)
+}
+
+// Retry on error
+async function retry() {
+  await refresh()
+}
+```
+
+### With Default Value
+
+```typescript
+interface User {
+  id: string
+  name: string
+}
+
+const { data } = await useAsyncGraphqlQuery('users', null, {
+  transform: (response) => response.data.users ?? [],
+  default: () => [] as User[],
+})
+
+// data.value is never undefined, defaults to empty array
+```
+
+## Comparison with useGraphqlQuery
+
+| Feature            | useAsyncGraphqlQuery | useGraphqlQuery                 |
+| ------------------ | -------------------- | ------------------------------- |
+| SSR Support        | ✅ Built-in          | ✅ When wrapped in useAsyncData |
+| Reactive Variables | ✅ Automatic refetch | ❌ Manual handling required     |
+| Returns            | AsyncData object     | Promise with response           |
+| Use in Callbacks   | ❌ Not recommended   | ✅ Works anywhere               |
+| Caching            | ✅ With useAsyncData | ✅ With graphqlCaching option   |
+| HMR Refresh        | ✅ Automatic         | ❌ Manual                       |
+
+Choose `useAsyncGraphqlQuery` for page-level data fetching with SSR support.
+Choose `useGraphqlQuery` for imperative fetching in event handlers, plugins, or
+when you need more control.

package/docs/composables/useGraphqlMutation.md

@@ -0,0 +1,29 @@
+# useGraphqlMutation
+
+Same usage like useGraphqlQuery, but for mutations:
+
+```typescript
+const { data } = await useGraphqlMutation('trackVisit')
+```
+
+```typescript
+const { data } = await useGraphqlMutation('addToCart', { id: '456' })
+```
+
+## Custom Fetch Options
+
+In addition to the fetch options set when using
+[/composables/useGraphqlState](useGraphqlState), you can also set fetch options
+here (which will override properties set by the useGraphqlState composable):
+
+```typescript
+const { data } = await useGraphqlMutation(
+  'addToCart',
+  { id: '456' },
+  {
+    onRequest(options) {
+      options.headers['Custom-Special-Header'] = 'Foobar'
+    },
+  },
+)
+```

package/docs/composables/useGraphqlQuery.md

@@ -0,0 +1,73 @@
+# useGraphqlQuery
+
+Executes a query using $fetch and returns the response.
+
+```typescript
+const { data } = await useGraphqlQuery('films')
+```
+
+Variables can be passed as the second argument:
+
+```typescript
+const { data } = await useGraphqlQuery('filmById', { id: '123' })
+```
+
+Arguments are properly type checked:
+
+```typescript
+// ✅ Everyting correct.
+const { data } = await useGraphqlQuery('filmById', { id: '123' })
+
+// ❌ Wrong variable type.
+const { data } = await useGraphqlQuery('filmById', { id: 123 })
+
+// ❌ Missing variables.
+const { data } = await useGraphqlQuery('filmById')
+
+// ❌ Wrong query name.
+const { data } = await useGraphqlQuery('getFilmById', { id: '123' })
+```
+
+The return value is also properly typed based on the query response:
+
+```typescript
+const { data } = await useGraphqlQuery('filmById', { id: '123' })
+
+// ❌ Property does not exist.
+console.log(data.films)
+
+// ❌ Object is possibly null.
+console.log(data.allFilms.films)
+
+// ✅ Everyting correct.
+console.log(data.allFilms?.films)
+```
+
+## Object Syntax
+
+You can also provide a single argument which is an object. One use case might be
+to have different query names depending on some context.
+
+```typescript
+const { data } = await useGraphqlQuery({
+  name: 'filmById',
+  variables: { id: '123' },
+})
+```
+
+## Fetch Options
+
+You can also pass an object instead, which allows you to additionally provide
+fetch options for the request:
+
+```typescript
+const { data } = await useGraphqlQuery({
+  name: 'filmById',
+  variables: { id: '123' },
+  fetchOptions: {
+    headers: {
+      authorization: 'foobar',
+    },
+  },
+})
+```

package/docs/composables/useGraphqlState.md

@@ -0,0 +1,58 @@
+# useGraphqlState
+
+This composable allows you to set fetch options for the useGraphqlQuery,
+useAsyncGraphqlQuery and useGraphqlMutation composables. One common use case is
+to pass custom request headers to the GraphQL middleware request.
+
+::: warning
+
+The state is only used for requests made from within a Nuxt app context (e.g.
+pages, route middleware, etc.). Usually this is used to "pass" information from
+the client/browser context to the middleware.
+
+:::
+
+::: code-group
+
+```typescript [plugins/graphqlState.ts]
+export default defineNuxtPlugin({
+  name: 'my-state-plugin',
+  // Makes sure that your plugin is executed after this plugin.
+  // If it were to run before, then `state` would be null.
+  dependsOn: ['nuxt-graphql-middleware-provide-state'],
+  setup() {
+    const state = useGraphqlState()
+
+    // This is nullable because it's injected by a plugin.
+    if (!state) {
+      return
+    }
+
+    const token = useToken()
+
+    // Set fetch options for all GraphQL queries and mutations.
+    state.fetchOptions = {
+      // Static header that should be the same for all requests.
+      headers: {
+        CustomHeader: 'foobar',
+      },
+
+      // Header value is evaluated on every request.
+      onRequest({ options, request }) {
+        options.headers.set('x-auth-token', token.value)
+      },
+
+      // Handle headers sent from the middleware to the Nuxt app (client or server side).
+      onResponse(result) {
+        const headers = result.response?.headers
+        const newToken = headers.get('x-auth-token')
+        if (newToken) {
+          token.value = newToken
+        }
+      },
+    }
+  },
+})
+```
+
+:::

package/docs/composables/useGraphqlUploadMutation.md

@@ -0,0 +1,57 @@
+# useGraphqlUploadMutation
+
+This composable is only available when setting `enableFileUploads` to `true` in
+the module's configuration. It allows to upload files inside a mutation. The
+implementation follows the
+[GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec),
+which is supported by a lot of GraphQL servers.
+
+## Basic Usage
+
+The composable handles the FormData part, so files can be directly provided
+inside the mutation variables:
+
+```typescript
+async function upload(image: File) {
+  const data = await useGraphqlUploadMutation('uploadImage', {
+    image,
+  })
+}
+```
+
+Multiple files are also supported, both in the same field or in deeply nested
+fields:
+
+```typescript
+const files = ref<File[]>([])
+
+const data = await useGraphqlUploadMutation('uploadFiles', {
+  elements: files.value.map((file) => {
+    return {
+      name: file.name,
+      file: file,
+    }
+  }),
+})
+```
+
+## Server Route
+
+To support file uploads, when the feature is enabled, an additional server route
+is added:
+
+```
+/api/graphql_middleware/upload/[name_of_mutation]
+```
+
+This route expects a `multipart/form-data` request. The
+`useGraphqlUploadMutation` composable makes sure the data is sent in the correct
+format.
+
+The server route does not perform any validations on the provided data, for
+example there is no file size limitation. This should be handled separately, for
+example on the web server or by implementing a custom Nitro middleware.
+
+In addition, the route does not save any of the files. It only validates that a
+valid, existing mutation is used. It also makes sure that it's not possible to
+send arbitrary operations.

package/docs/configuration/client-options.md

@@ -0,0 +1,121 @@
+# Client Options
+
+`nuxt-graphql-middleware` will look for a file called
+`graphqlMiddleware.clientOptions.ts` in your app dir. This file can export so
+called "client options" which are used when _making a request to the GraphQL
+middleware_.
+
+::: warning
+
+Note that the client options are only used in a **Nuxt app context** - they are
+not used when using `useGraphqlQuery` or other utils in a **Nitro context** such
+as event handlers.
+
+:::
+
+## Defining Client Options
+
+When using a composable such as `useGraphqlQuery`, behind the scenes it will use
+`$fetch` to make a request to the GraphQL middleware server route. Sometimes
+it's useful to pass some additional context with this request that can then be
+used on the server.
+
+Similar to [serverOptions](/configuration/server-options), you can create a file
+called `graphqlMiddleware.clientOptions.ts` in your `app` directory (usually
+`<rootDir>/app`).
+
+::: code-group
+
+```typescript [~/app/graphqlMiddleware.clientOptions.ts]
+import { defineGraphqlClientOptions } from 'nuxt-graphql-middleware/client-options'
+
+export default defineGraphqlClientOptions({})
+```
+
+:::
+
+## Defining Client Context
+
+Implement the `buildClientContext()` method to return an object with string
+values.
+
+::: code-group
+
+```typescript [~/app/graphqlMiddleware.clientOptions.ts]
+import { defineGraphqlClientOptions } from 'nuxt-graphql-middleware/client-options'
+
+export default defineGraphqlClientOptions<{
+  language: string
+  country: string
+}>({
+  buildClientContext() {
+    const language = useCurrentLanguage()
+    const country = useCurrentCountry()
+    return {
+      language: language.value,
+      country: country.value,
+    }
+  },
+})
+```
+
+:::
+
+::: info
+
+By passing a generic in `defineGraphqlClientOptions` you can define the type of
+your context object.
+
+:::
+
+Now everytime a request to the middleware is made with a composable such as
+`useGraphqlQuery`, the composable will call the `buildClientContext` method to
+get the current context. It then maps each property of the returned object to a
+query parameter while prefixing the property to prevent collisions with
+potential query parameters from GraphQL variables.
+
+So for example, when making a GraphQL query like so:
+
+```typescript
+const data = await useGraphqlQuery('loadProduct', {
+  id: '123',
+})
+```
+
+The composable will make a fetch request to this URL.
+
+`/api/graphql_middleware/loadProduct?id=123&__gqlc_language=en&__gqlc_country=US`
+
+Both the `language` and `country` properties we returned in the object in
+`buildClientContext()` are appended as prefixed query parameters.
+
+## Using Client Context
+
+On the server you can then access this client context from within all
+[serverOptions](/configuration/server-options) methods:
+
+::: code-group
+
+```typescript [~/server/graphqlMiddleware.serverOptions.ts]
+import { defineGraphqlServerOptions } from 'nuxt-graphql-middleware/server-options'
+
+export default defineGraphqlServerOptions({
+  graphqlEndpoint(event, operation, operationName, context) {
+    // Use the language from the client context.
+    const language = context?.client?.language || 'en'
+    return `http://backend_server/${language}/graphql`
+  },
+
+  serverFetchOptions: function (event, _operation, operationName, context) {
+    // Pass the current country as a header when making a request to the
+    // GraphQL server.
+    return {
+      headers: {
+        'x-current-country': context.client?.country || 'US',
+      },
+    }
+  },
+})
+```
+
+:::