nuxt-graphql-middleware 5.2.2 → 5.3.0

package/dist/shared/{nuxt-graphql-middleware.ct2xvPoD.d.mts → nuxt-graphql-middleware.COufMnWs.d.mts}

@@ -230,6 +230,21 @@ interface ModuleOptions {
          */
         improvedQueryParamEncoding?: boolean;
     };
+    /**
+     * Configuration for the @nuxtjs/mcp-toolkit integration.
+     */
+    mcp?: {
+        /**
+         * Whether the MCP integration should be enabled.
+         */
+        enabled: boolean;
+        /**
+         * The route of the MCP server.
+         *
+         * @default /mcp/nuxt-graphql-middleware
+         */
+        route?: string;
+    };
 }
 
 declare const defaultOptions: ModuleOptions;
@@ -242,6 +257,7 @@ declare class ConsolePrompt {
 
 type TemplateOptions = {
     path: string;
+    context: 'nuxt' | 'nitro' | 'both';
     virtual?: boolean;
     isFullPath?: boolean;
 };
@@ -262,6 +278,27 @@ type StaticTemplate = {
     virtual?: boolean;
 };
 
+type BuildImport = {
+    name: string;
+    description: string;
+    docsUrl: string;
+    context: 'nuxt' | 'nitro';
+};
+declare const COMPOSABLES: {
+    useGraphqlQuery: BuildImport;
+    useGraphqlMutation: BuildImport;
+    useAsyncGraphqlQuery: BuildImport;
+    useGraphqlUploadMutation: BuildImport;
+    useGraphqlState: BuildImport;
+};
+type ComposableName = keyof typeof COMPOSABLES;
+declare const SERVER_UTILS: {
+    useGraphqlQuery: BuildImport;
+    useGraphqlMutation: BuildImport;
+    doGraphqlRequest: BuildImport;
+};
+type ServerUtilName = keyof typeof SERVER_UTILS;
+
 type WithRequired<T, K extends keyof T> = T & {
     [P in K]-?: T[P];
 };
@@ -306,6 +343,7 @@ declare class ModuleHelper {
     readonly resolvers: ModuleHelperResolvers;
     readonly paths: ModuleHelperPaths;
     readonly isDev: boolean;
+    readonly isPrepare: boolean;
     readonly options: RequiredModuleOptions;
     readonly prompt: ConsolePrompt;
     private nitroExternals;
@@ -343,12 +381,67 @@ declare class ModuleHelper {
     applyBuildConfig(): void;
     processTemplate(path: string, content: string): string;
     addTemplate(template: StaticTemplate): void;
+    /**
+     * Register a type template without adding to globalTypeFiles.
+     *
+     * Uses addTemplate instead of addTypeTemplate to avoid Vue compiler-sfc
+     * issue where exported types from globalTypeFiles cannot be resolved.
+     * @see https://github.com/nuxt/nuxt/issues/33694
+     */
+    registerTypeTemplate(filename: `${string}.d.ts`, getContents: () => string, context: 'nuxt' | 'nitro' | 'both'): void;
     addPlugin(name: string): void;
     addServerHandler(name: string, path: string, method: RouterMethod): void;
-    addComposable(name: string): void;
-    addServerUtil(name: string): void;
+    addComposable(name: ComposableName): void;
+    addServerUtil(name: ServerUtilName): void;
 }
 
+/**
+ * Represents a collected GraphQL operation with metadata.
+ * Used internally by the Collector - decoupled from MCP tool schemas.
+ */
+type CollectorOperation = {
+    /** The GraphQL operation name */
+    name: string;
+    /** The type of operation */
+    type: 'query' | 'mutation';
+    /** Absolute path to the file containing the operation */
+    filePath: string;
+    /** Path to the file relative to the project root */
+    relativeFilePath: string;
+    /** Whether the operation has any variables */
+    hasVariables: boolean;
+    /** Whether the operation requires variables (has non-null variables) */
+    needsVariables: boolean;
+    /** TypeScript type name for the operation variables */
+    variablesTypeName: string;
+    /** TypeScript type name for the operation response */
+    responseTypeName: string;
+    /** The GraphQL source code of just this operation (no fragments) */
+    source: string;
+    /** The full GraphQL source including all fragment dependencies */
+    sourceFull: string;
+};
+/**
+ * Represents a collected GraphQL fragment with metadata.
+ * Used internally by the Collector - decoupled from MCP tool schemas.
+ */
+type CollectorFragment = {
+    /** The fragment name */
+    name: string;
+    /** The GraphQL type this fragment is defined on */
+    typeName: string;
+    /** Absolute path to the file containing the fragment */
+    filePath: string;
+    /** Path to the file relative to the project root */
+    relativeFilePath: string;
+    /** The GraphQL source code of just this fragment (no dependencies) */
+    source: string;
+    /** The full GraphQL source including all fragment dependencies */
+    sourceFull: string;
+    /** Names of other fragments this fragment depends on */
+    dependencies: string[];
+};
+
 type CollectorWatchEventResult = {
     hasChanged: boolean;
     affectedOperations: string[];
@@ -391,6 +484,14 @@ declare class Collector {
      * The generated template contents.
      */
     private templateResult;
+    /**
+     * Operations with full metadata for MCP tools.
+     */
+    private operations;
+    /**
+     * Fragments with full metadata for MCP tools.
+     */
+    private fragments;
     private isInitialised;
     constructor(schema: GraphQLSchema, helper: ModuleHelper);
     reset(): Promise<void>;
@@ -457,6 +558,22 @@ declare class Collector {
      * Get the hook documents.
      */
     getHookFiles(): string[];
+    /**
+     * Get all operations with metadata (for MCP tools).
+     */
+    getOperations(): CollectorOperation[];
+    /**
+     * Get all fragments for a specific GraphQL type (for MCP tools).
+     */
+    getFragmentsForType(typeName: string): CollectorFragment[];
+    /**
+     * Get all fragments (for MCP tools).
+     */
+    getFragments(): CollectorFragment[];
+    /**
+     * Get a fragment by name (for MCP tools).
+     */
+    getFragment(name: string): CollectorFragment | undefined;
 }
 
 /**

package/dist/utils.d.mts

@@ -1,4 +1,4 @@
-import { M as ModuleContext } from './shared/nuxt-graphql-middleware.ct2xvPoD.mjs';
+import { M as ModuleContext } from './shared/nuxt-graphql-middleware.COufMnWs.mjs';
 import 'graphql';
 import 'nuxt/schema';
 import '@nuxt/kit';

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.