nuxt-graphql-middleware 5.0.0-alpha.9 → 5.1.0

package/dist/module.mjs

@@ -1,8 +1,8 @@
 import { fileURLToPath } from 'url';
-import { useLogger, addTemplate, addServerTemplate, addTypeTemplate, resolveAlias, createResolver, resolveFiles, addPlugin, addServerHandler, addImports, addServerImports, useNitro, defineNuxtModule } from '@nuxt/kit';
+import { useLogger, addTemplate, addServerTemplate, addTypeTemplate, createResolver, resolveAlias, resolveFiles, addPlugin, addServerHandler, addImports, addServerImports, useNitro, defineNuxtModule } from '@nuxt/kit';
 import { existsSync, promises } from 'node:fs';
-import { relative } from 'pathe';
 import { basename } from 'node:path';
+import { relative, join } from 'pathe';
 import { printSourceLocation, parse, Source, OperationTypeNode } from 'graphql';
 import { Generator, FieldNotFoundError, TypeNotFoundError, FragmentNotFoundError } from 'graphql-typescript-deluxe';
 import color from 'picocolors';
@@ -12,16 +12,17 @@ import { generate } from '@graphql-codegen/cli';
 import * as PluginSchemaAst from '@graphql-codegen/schema-ast';
 import { loadSchema } from '@graphql-tools/load';
 import { defu } from 'defu';
-import * as micromatch from 'micromatch';
+import micromatch from 'micromatch';
 import { ConfirmPrompt } from '@clack/core';
 import isUnicodeSupported from 'is-unicode-supported';
+import { hash } from 'ohash';
 import { existsSync as existsSync$1 } from 'fs';
 import { onDevToolsInitialized, extendServerRpc } from '@nuxt/devtools-kit';
 
 const name = "nuxt-graphql-middleware";
-const version = "5.0.0-alpha.9";
+const version = "5.1.0";
 
-const logger = useLogger(name);
+const logger = useLogger("nuxt-graphql-middleware");
 const defaultOptions = {
   downloadSchema: true,
   schemaPath: "~~/schema.graphql",
@@ -32,7 +33,14 @@ const defaultOptions = {
   documents: [],
   devtools: true,
   errorOverlay: true,
-  graphqlConfigFilePath: "./graphql.config.ts"
+  graphqlConfigFilePath: "./graphql.config.ts",
+  experimental: {
+    improvedQueryParamEncoding: false
+  },
+  clientCache: {
+    enabled: false,
+    maxSize: 100
+  }
 };
 function validateOptions(options) {
   if (!options.graphqlEndpoint) {
@@ -119,6 +127,9 @@ class CollectedFile {
   }
   static async fromFilePath(filePath) {
     const content = (await promises.readFile(filePath)).toString();
+    if (!content) {
+      return null;
+    }
     return new CollectedFile(filePath, content, true);
   }
   /**
@@ -148,7 +159,10 @@ class Collector {
     }
     if (!mappedOptions.output.buildTypeDocFilePath) {
       mappedOptions.output.buildTypeDocFilePath = (filePath) => {
-        return this.filePathToBuildRelative(filePath);
+        if (filePath.startsWith("/")) {
+          return this.filePathToBuildRelative(filePath);
+        }
+        return filePath;
       };
     }
     this.generator = new Generator(schema, mappedOptions);
@@ -157,6 +171,14 @@ class Collector {
    * All collected files.
    */
   files = /* @__PURE__ */ new Map();
+  /**
+   * All documents provided by hooks.
+   */
+  hookDocuments = /* @__PURE__ */ new Map();
+  /**
+   * All file paths provided by hooks.
+   */
+  hookFiles = /* @__PURE__ */ new Set();
   /**
    * The code generator.
    */
@@ -177,6 +199,7 @@ class Collector {
    * The generated template contents.
    */
   templateResult = /* @__PURE__ */ new Map();
+  isInitialised = false;
   async reset() {
     this.files.clear();
     this.generator.reset();
@@ -190,10 +213,13 @@ class Collector {
     await this.initDocuments();
   }
   filePathToBuildRelative(filePath) {
-    return "./" + this.helper.toBuildRelative(filePath);
+    return "./" + this.helper.toModuleBuildRelative(filePath);
   }
   filePathToSourceRelative(filePath) {
-    return "./" + relative(process.cwd(), filePath);
+    if (filePath.startsWith("/")) {
+      return "./" + relative(process.cwd(), filePath);
+    }
+    return filePath;
   }
   operationToLogEntry(operation, errors) {
     return {
@@ -203,8 +229,8 @@ class Collector {
       errors
     };
   }
-  getTemplate(template) {
-    const content = this.templateResult.get(template);
+  getTemplate(template, type) {
+    const content = this.templateResult.get(template + "-" + type);
     if (content === void 0) {
       throw new Error(`Missing template content: ${template}`);
     }
@@ -213,23 +239,28 @@ class Collector {
   /**
    * Executes code gen and performs validation for operations.
    */
-  buildState() {
+  async buildState() {
     const output = this.generator.build();
     const operations = output.getCollectedOperations();
     const generatedCode = output.getGeneratedCode();
     this.templates.forEach((template) => {
+      const path = template.options.path;
       if (template.build) {
-        const filename = template.options.path + ".js";
         this.templateResult.set(
-          filename,
-          template.build(output, this.helper).trim()
+          path + "-default",
+          this.helper.processTemplate(
+            template.options.path,
+            template.build(output, this.helper, this)
+          )
         );
       }
       if (template.buildTypes) {
-        const filename = template.options.path + ".d.ts";
         this.templateResult.set(
-          filename,
-          template.buildTypes(output, this.helper).trim()
+          template.options.path + "-types",
+          this.helper.processTemplate(
+            template.options.path,
+            template.buildTypes(output, this.helper, this)
+          )
         );
       }
     });
@@ -266,10 +297,15 @@ class Collector {
         logEntries.push(this.operationToLogEntry(operation, errors));
       }
     }
-    logAllEntries(logEntries);
+    logAllEntries(
+      logEntries.sort((a, b) => {
+        return a.type.localeCompare(b.type) || a.name.localeCompare(b.name);
+      })
+    );
     if (hasErrors) {
       throw new Error("GraphQL errors");
     }
+    await this.helper.nuxt.callHook("nuxt-graphql-middleware:build", { output });
     if (this.helper.isDev) {
       for (const code of generatedCode) {
         const id = `${code.identifier}_${code.graphqlName}`;
@@ -332,12 +368,32 @@ class Collector {
         );
         if (shouldRevalidate === "yes") {
           await this.reset();
-          return this.init();
+          await this.init();
+          this.isInitialised = true;
+          return;
         }
       }
       throw new Error("Graphql document validation failed.");
     }
   }
+  addHookDocument(identifier, source) {
+    this.hookDocuments.set("hook:" + identifier, source);
+  }
+  async addOrUpdateHookDocument(identifier, source) {
+    const fullIdentifier = "hook:" + identifier;
+    const exists = this.hookDocuments.has(fullIdentifier);
+    this.hookDocuments.set(fullIdentifier, source);
+    if (exists && this.isInitialised) {
+      this.generator.update({
+        filePath: fullIdentifier,
+        document: source
+      });
+      await this.buildState();
+    }
+  }
+  addHookFile(filePath) {
+    this.hookFiles.add(filePath);
+  }
   /**
    * Initialise the collector.
    */
@@ -357,7 +413,19 @@ class Collector {
           documentNode: file.parsed
         });
       }
-      this.buildState();
+      const hookDocuments = [...this.hookDocuments.entries()];
+      hookDocuments.forEach(([identifier, source]) => {
+        const file = new CollectedFile(identifier, source, false);
+        this.files.set(identifier, file);
+        this.generator.add({
+          filePath: identifier,
+          documentNode: file.parsed
+        });
+      });
+      for (const filePath of this.hookFiles) {
+        await this.addFile(filePath);
+      }
+      await this.buildState();
       logger.success("All GraphQL documents are valid.");
     } catch (e) {
       this.logError(e);
@@ -369,7 +437,7 @@ class Collector {
    */
   async addFile(filePath) {
     const file = await CollectedFile.fromFilePath(filePath);
-    if (!file.fileContents) {
+    if (!file?.fileContents) {
       return null;
     }
     this.files.set(filePath, file);
@@ -379,15 +447,18 @@ class Collector {
     });
     return file;
   }
+  matchesPatternOrExists(filePath) {
+    return this.files.has(filePath) || this.hookFiles.has(filePath) || this.hookDocuments.has(filePath) || this.helper.matchesImportPattern(filePath);
+  }
   async handleAdd(filePath) {
-    if (!this.helper.matchesImportPattern(filePath)) {
+    if (!this.matchesPatternOrExists(filePath)) {
       return false;
     }
     const result = await this.addFile(filePath);
     return !!result;
   }
   async handleChange(filePath) {
-    if (!this.helper.matchesImportPattern(filePath)) {
+    if (!this.matchesPatternOrExists(filePath)) {
       return false;
     }
     const file = this.files.get(filePath);
@@ -446,7 +517,7 @@ class Collector {
         hasChanged = this.handleUnlinkDir(filePath);
       }
       if (hasChanged) {
-        this.buildState();
+        await this.buildState();
       }
     } catch (e) {
       this.generator.resetCaches();
@@ -478,7 +549,7 @@ class Collector {
    */
   addVirtualTemplate(template) {
     const filename = template.options.path + ".js";
-    const getContents = () => this.getTemplate(filename);
+    const getContents = () => this.getTemplate(template.options.path, "default");
     addTemplate({
       filename,
       getContents
@@ -503,21 +574,23 @@ class Collector {
       if (template.options.virtual) {
         this.addVirtualTemplate(template);
       } else {
-        const filename = template.options.path + ".js";
+        const path = template.options.path;
+        const filename = template.options.isFullPath ? path : path + ".js";
         addTemplate({
           filename,
           write: true,
-          getContents: () => this.getTemplate(filename)
+          getContents: () => this.getTemplate(path, "default")
         });
       }
     }
     if (template.buildTypes) {
+      const path = template.options.path;
       const filename = template.options.path + ".d.ts";
       addTypeTemplate(
         {
           filename,
           write: true,
-          getContents: () => this.getTemplate(filename)
+          getContents: () => this.getTemplate(path, "types")
         },
         {
           nuxt: true,
@@ -526,6 +599,23 @@ class Collector {
       );
     }
   }
+  /**
+   * Get the hook documents.
+   */
+  getHookDocuments() {
+    return [...this.hookDocuments.entries()].map(([identifier, source]) => {
+      return {
+        identifier,
+        source
+      };
+    });
+  }
+  /**
+   * Get the hook documents.
+   */
+  getHookFiles() {
+    return [...this.hookFiles.values()];
+  }
 }
 
 class SchemaProvider {
@@ -730,25 +820,36 @@ ${color.cyan(S_BAR_END)}
 class ModuleHelper {
   constructor(nuxt, moduleUrl, options) {
     this.nuxt = nuxt;
-    const isModuleBuild = process.env.MODULE_BUILD === "true" && nuxt.options._prepare;
     const mergedOptions = defu({}, options, defaultOptions);
     if (!mergedOptions.autoImportPatterns) {
       mergedOptions.autoImportPatterns = [
         "~~/**/*.{gql,graphql}",
+        "~/**/*.{gql,graphql}",
         "!node_modules"
       ];
     }
-    if (isModuleBuild) {
-      mergedOptions.graphqlEndpoint = "http://localhost";
-      mergedOptions.downloadSchema = false;
-      mergedOptions.schemaPath = "~~/schema.graphql";
-      mergedOptions.autoImportPatterns = [
-        "~~/playground/**/*.{gql,graphql}",
-        "!node_modules"
-      ];
-    }
-    mergedOptions.autoImportPatterns = (mergedOptions.autoImportPatterns || []).map((pattern) => {
-      return resolveAlias(pattern);
+    const layerAliases = nuxt.options._layers.map((layer) => {
+      return {
+        "~~": layer.config.rootDir,
+        "@@": layer.config.rootDir,
+        "~": layer.config.srcDir,
+        "@": layer.config.srcDir,
+        // Merge any additional aliases defined by the layer.
+        // Must be last so that the layer may override the "default" aliases.
+        ...layer.config.alias || {}
+      };
+    });
+    const srcResolver = createResolver(nuxt.options.srcDir);
+    const rootResolver = createResolver(nuxt.options.rootDir);
+    mergedOptions.autoImportPatterns = (mergedOptions.autoImportPatterns || []).flatMap((pattern) => {
+      if (pattern.startsWith("!") || pattern.startsWith("/")) {
+        return pattern;
+      } else if (pattern.startsWith("~") || pattern.startsWith("@")) {
+        return layerAliases.map((aliases) => resolveAlias(pattern, aliases));
+      }
+      return rootResolver.resolve(pattern);
+    }).map((pattern) => {
+      return pattern.replace(".{graphql}", ".graphql").replace(".{gql}", ".gql");
     });
     this.options = mergedOptions;
     if (!nuxt.options._prepare) {
@@ -758,9 +859,9 @@ class ModuleHelper {
     this.resolvers = {
       module: createResolver(moduleUrl),
       server: createResolver(nuxt.options.serverDir),
-      src: createResolver(nuxt.options.srcDir),
+      src: srcResolver,
       app: createResolver(nuxt.options.dir.app),
-      root: createResolver(nuxt.options.rootDir)
+      root: rootResolver
     };
     this.paths = {
       runtimeTypes: "",
@@ -786,6 +887,7 @@ class ModuleHelper {
   options;
   prompt = new ConsolePrompt();
   nitroExternals = [];
+  tsPaths = {};
   /**
    * Find the path to the graphqlMiddleware.serverOptions.ts file.
    */
@@ -849,35 +951,17 @@ class ModuleHelper {
   async getImportPatternFiles() {
     return resolveFiles(
       this.nuxt.options.srcDir,
-      this.options.autoImportPatterns,
-      {
-        followSymbolicLinks: false
-      }
+      this.options.autoImportPatterns
     );
   }
   matchesImportPattern(filePath) {
-    return micromatch.isMatch(filePath, this.options.autoImportPatterns);
+    return micromatch.isMatch(filePath, this.options.autoImportPatterns) || this.options.autoImportPatterns.includes(filePath);
   }
   addAlias(name, path) {
     this.nuxt.options.alias[name] = path;
     const pathFromName = `./${name.substring(1)}`;
-    this.nuxt.options.nitro.typescript ||= {};
-    this.nuxt.options.nitro.typescript.tsConfig ||= {};
-    this.nuxt.options.nitro.typescript.tsConfig.compilerOptions ||= {};
-    this.nuxt.options.nitro.typescript.tsConfig.compilerOptions.paths ||= {};
-    this.nuxt.options.nitro.typescript.tsConfig.compilerOptions.paths[name] = [
-      pathFromName
-    ];
-    this.nuxt.options.nitro.typescript.tsConfig.compilerOptions.paths[name + "/*"] = [pathFromName + "/*"];
-    this.nuxt.options.typescript.tsConfig ||= {};
-    this.nuxt.options.typescript.tsConfig.compilerOptions ||= {};
-    this.nuxt.options.typescript.tsConfig.compilerOptions.paths ||= {};
-    this.nuxt.options.typescript.tsConfig.compilerOptions.paths[name] = [
-      pathFromName
-    ];
-    this.nuxt.options.typescript.tsConfig.compilerOptions.paths[name + "/*"] = [
-      pathFromName + "/*"
-    ];
+    this.tsPaths[name] = pathFromName;
+    this.tsPaths[name + "/*"] = pathFromName + "/*";
     this.inlineNitroExternals(name);
   }
   inlineNitroExternals(arg) {
@@ -892,10 +976,34 @@ class ModuleHelper {
     this.nuxt.options.nitro.externals ||= {};
     this.nuxt.options.nitro.externals.inline ||= [];
     this.nuxt.options.nitro.externals.inline.push(...this.nitroExternals);
+    this.nuxt.options.nitro.typescript ||= {};
+    this.nuxt.options.nitro.typescript.tsConfig ||= {};
+    this.nuxt.options.nitro.typescript.tsConfig.compilerOptions ||= {};
+    this.nuxt.options.nitro.typescript.tsConfig.compilerOptions.paths ||= {};
+    this.nuxt.options.typescript.tsConfig ||= {};
+    this.nuxt.options.typescript.tsConfig.compilerOptions ||= {};
+    this.nuxt.options.typescript.tsConfig.compilerOptions.paths ||= {};
+    for (const [name, path] of Object.entries(this.tsPaths)) {
+      this.nuxt.options.nitro.typescript.tsConfig.compilerOptions.paths[name] = [path];
+      this.nuxt.options.typescript.tsConfig.compilerOptions.paths[name] = [path];
+    }
+  }
+  processTemplate(path, content) {
+    if (path.includes("graphql-operations/") || path.endsWith(".graphql")) {
+      return content.trim();
+    }
+    const name = path.split("/")[1];
+    return `/*
+ * @see [Documentation](https://nuxt-graphql-middleware.dulnan.net/advanced/templates#${name})
+ */
+${content.trim()}`;
   }
   addTemplate(template) {
     if (template.build) {
-      const content = template.build(this).trim();
+      const content = this.processTemplate(
+        template.options.path,
+        template.build(this)
+      );
       addTemplate({
         filename: template.options.path + ".js",
         write: true,
@@ -903,7 +1011,10 @@ class ModuleHelper {
       });
     }
     if (template.buildTypes) {
-      const content = template.buildTypes(this).trim();
+      const content = this.processTemplate(
+        template.options.path,
+        template.buildTypes(this)
+      );
       const filename = template.options.path + ".d.ts";
       addTypeTemplate({
         filename,
@@ -912,8 +1023,8 @@ class ModuleHelper {
       });
     }
   }
-  addPlugin(path) {
-    addPlugin(this.resolvers.module.resolve(path), {
+  addPlugin(name) {
+    addPlugin(this.resolvers.module.resolve("./runtime/plugins/" + name), {
       append: false
     });
   }
@@ -968,7 +1079,7 @@ const ClientOptions = defineStaticTemplate(
 export { clientOptions }
 `;
     }
-    return `export const clientOptions = {}`;
+    return `export const clientOptions = undefined`;
   },
   (helper) => {
     if (helper.paths.clientOptions) {
@@ -976,21 +1087,43 @@ export { clientOptions }
         helper.paths.clientOptions
       );
       return `import type { GraphqlClientOptions } from '${helper.paths.runtimeTypes}'
-import { clientOptions } from '${pathRelative}'
-
-export type GraphqlClientContext = typeof clientOptions extends GraphqlClientOptions<infer R> ? R : {}
+import clientOptionsImport from '${pathRelative}'
 
-export { clientOptions }`;
+declare export const clientOptions: GraphqlClientOptions|undefined
+export type GraphqlClientContext = typeof clientOptionsImport extends GraphqlClientOptions<infer R> ? R : {}
+`;
     }
     return `
 import type { GraphqlClientOptions } from '${helper.paths.runtimeTypes}'
-export const clientOptions: GraphqlClientOptions
 
+declare export const clientOptions: GraphqlClientOptions|undefined
 export type GraphqlClientContext = {}
 `;
   }
 );
 
+const Config = defineStaticTemplate(
+  { path: "nuxt-graphql-middleware/config" },
+  (helper) => {
+    const experimentalQueryParamEncoding = !!helper.options.experimental.improvedQueryParamEncoding;
+    const clientCacheEnabledAtBuild = !!helper.options.clientCache.enabled;
+    return `
+export const experimentalQueryParamEncoding = ${JSON.stringify(experimentalQueryParamEncoding)}
+export const clientCacheEnabledAtBuild = ${JSON.stringify(clientCacheEnabledAtBuild)}
+export const importMetaServer = import.meta.server
+export const importMetaClient = import.meta.client
+`;
+  },
+  () => {
+    return `
+declare export const experimentalQueryParamEncoding: boolean
+declare export const clientCacheEnabledAtBuild: boolean
+declare export const importMetaServer: boolean
+declare export const importMetaClient: boolean
+`;
+  }
+);
+
 const Documents = defineGeneratorTemplate(
   { path: "nuxt-graphql-middleware/documents", virtual: true },
   (output, helper) => {
@@ -1027,13 +1160,25 @@ const GraphqlConfig = defineStaticTemplate(
     const documents = patterns.filter((v) => !v.includes("!")).map((pattern) => {
       return "./" + relative(configPath, helper.resolvers.root.resolve(pattern));
     });
-    return `const schema = ${JSON.stringify(schemaPath)}
+    documents.push(
+      "./" + relative(
+        configPath,
+        join(helper.paths.moduleBuildDir, "hook-documents.graphql")
+      )
+    );
+    return `
+import { hookFiles } from './hook-files'
+
+const schema = ${JSON.stringify(schemaPath)}
 
 const documents = ${JSON.stringify(documents, null, 2)};
 
 const config = {
   schema,
-  documents,
+  documents: [
+    ...documents,
+    ...hookFiles
+  ]
 }
 
 export default config
@@ -1067,6 +1212,43 @@ export function getEndpoint(operation: string, operationName: string): string`;
   }
 );
 
+const HookDocuments = defineGeneratorTemplate(
+  {
+    path: "nuxt-graphql-middleware/hook-documents.graphql",
+    virtual: false,
+    isFullPath: true
+  },
+  (_output, _helper, collector) => {
+    return collector.getHookDocuments().map((v) => {
+      return `
+# ${v.identifier}
+${v.source}
+`;
+    }).join("\n\n");
+  },
+  null
+);
+
+const HookFiles = defineGeneratorTemplate(
+  {
+    path: "nuxt-graphql-middleware/hook-files",
+    virtual: false
+  },
+  (_output, helper, collector) => {
+    const configPath = helper.resolvers.root.resolve(
+      (helper.options.graphqlConfigFilePath || "").replace(
+        "/graphql.config.ts",
+        ""
+      )
+    );
+    const files = collector.getHookFiles().map((filePath) => {
+      return "./" + relative(configPath, filePath);
+    });
+    return `export const hookFiles = ${JSON.stringify(files, null, 2)}`;
+  },
+  null
+);
+
 const NitroTypes = defineGeneratorTemplate(
   { path: "nuxt-graphql-middleware/nitro" },
   null,
@@ -1097,6 +1279,46 @@ ${endpoints.sort().join("\n")}
   }
 );
 
+const OperationHashes = defineGeneratorTemplate(
+  { path: "nuxt-graphql-middleware/operation-hashes", virtual: true },
+  (output, helper) => {
+    if (helper.isDev) {
+      return `export const operationHashes = {}`;
+    }
+    const fragmentHashMap = {};
+    const generatedCode = output.getGeneratedCode();
+    generatedCode.forEach((code) => {
+      if (code.type === "fragment") {
+        const fragmentHash = hash(code.source);
+        if (code.graphqlName) {
+          fragmentHashMap[code.graphqlName] = fragmentHash;
+        }
+      }
+    });
+    const lines = [];
+    generatedCode.forEach((code) => {
+      if (code.type === "operation" && code.graphqlName && code.source) {
+        const source = code.source;
+        const fragments = code.getGraphQLFragmentDependencies().map((fragmentName) => {
+          return fragmentHashMap[fragmentName];
+        }).join("");
+        const sourceHash = hash(source + fragments);
+        lines.push(`"${code.graphqlName}": "${sourceHash.substring(0, 10)}"`);
+      }
+    });
+    return `export const operationHashes = {
+  ${lines.sort().join(",\n  ")}
+}`;
+  },
+  () => {
+    return `
+declare module '#nuxt-graphql-middleware/operation-hashes' {
+  export const operationHashes: Record<string, string>;
+}
+`;
+  }
+);
+
 const OperationTypesAll = defineGeneratorTemplate(
   { path: "nuxt-graphql-middleware/operation-types" },
   () => `export {}`,
@@ -1119,6 +1341,27 @@ const Operations = defineGeneratorTemplate(
   }
 );
 
+const OperationVariables = defineGeneratorTemplate(
+  { path: "nuxt-graphql-middleware/operation-variables" },
+  (output) => {
+    const operations = output.getCollectedOperations().reduce((acc, collectedOperation) => {
+      const node = collectedOperation.node;
+      const operationName = collectedOperation.graphqlName;
+      const variables = (node.variableDefinitions || []).map(
+        (v) => v.variable.name.value
+      );
+      acc[operationName] = variables;
+      return acc;
+    }, {});
+    return `export const operationVariables = ${JSON.stringify(operations, null, 2)}`;
+  },
+  () => {
+    return `
+declare export const operationVariables: Record<string, string[]>
+`;
+  }
+);
+
 const Response = defineGeneratorTemplate(
   { path: "nuxt-graphql-middleware/response" },
   null,
@@ -1133,7 +1376,7 @@ import type { GraphqlServerResponse } from '${helper.paths.runtimeTypes}'
 
 declare module '#nuxt-graphql-middleware/response' {
   export type GraphqlMiddlewareResponseUnion =
-    | ${allTypes.join("\n  | ") || "never"}
+    | ${allTypes.join("\n    | ") || "never"}
 
   export type GraphqlResponse<T> = GraphqlServerResponse<T> & GraphqlResponseAdditions
   export type GraphqlResponseTyped = GraphqlResponse<GraphqlMiddlewareResponseUnion>
@@ -1152,16 +1395,27 @@ export { serverOptions }
 `;
   },
   (helper) => {
-    const resolvedPathRelative = helper.paths.serverOptions ? helper.toModuleBuildRelative(helper.paths.serverOptions) : null;
-    const serverOptionsLineTypes = resolvedPathRelative ? `import serverOptions from '${resolvedPathRelative}'` : `const serverOptions: GraphqlMiddlewareServerOptions = {}`;
-    return `
+    if (helper.paths.serverOptions) {
+      const resolvedPathRelative = helper.toModuleBuildRelative(
+        helper.paths.serverOptions
+      );
+      return `
 import type { GraphqlMiddlewareServerOptions } from '${helper.paths.runtimeTypes}'
-${serverOptionsLineTypes}
+import serverOptionsImport from '${resolvedPathRelative}'
 
 export type GraphqlResponseAdditions =
-  typeof serverOptions extends GraphqlMiddlewareServerOptions<infer R, any, any> ? R : {}
+  typeof serverOptionsImport extends GraphqlMiddlewareServerOptions<infer R, any, any> ? R : {}
 
-export { serverOptions }`;
+declare export const serverOptions: GraphqlMiddlewareServerOptions
+`;
+    }
+    return `
+import type { GraphqlMiddlewareServerOptions } from '${helper.paths.runtimeTypes}'
+
+declare export const serverOptions: GraphqlMiddlewareServerOptions
+
+export type GraphqlResponseAdditions = object
+`;
   }
 );
 
@@ -1172,7 +1426,7 @@ const Sources = defineGeneratorTemplate(
     const srcDir = helper.paths.root;
     const lines = [];
     for (const operation of operations) {
-      const filePath = relative(srcDir, operation.filePath);
+      const filePath = operation.filePath.startsWith("/") ? relative(srcDir, operation.filePath) : operation.filePath;
       lines.push(
         `${operation.operationType}_${operation.graphqlName}: '${filePath}',`
       );
@@ -1190,12 +1444,17 @@ export const operationSources = {
 
 const TEMPLATES = [
   ClientOptions,
+  Config,
   Documents,
   GraphqlConfig,
   Helpers,
+  HookDocuments,
+  HookFiles,
   NitroTypes,
+  OperationHashes,
   OperationTypesAll,
   Operations,
+  OperationVariables,
   Response,
   ServerOptions,
   Sources
@@ -1284,11 +1543,12 @@ class DevModeHandler {
     this.nitro = useNitro();
     this.nitro.hooks.hook("compiled", this.onNitroCompiled.bind(this));
   }
-  async onBuilderWatch(event, pathAbsolute) {
-    if (pathAbsolute === this.helper.paths.schema) {
+  async onBuilderWatch(event, providedFilePath) {
+    if (!providedFilePath.endsWith(".graphql") && !providedFilePath.endsWith(".gql")) {
       return;
     }
-    if (!pathAbsolute.match(/\.(gql|graphql)$/)) {
+    const pathAbsolute = providedFilePath.startsWith("/") ? providedFilePath : this.helper.resolvers.src.resolve(providedFilePath);
+    if (pathAbsolute === this.helper.paths.schema) {
       return;
     }
     this.helper.prompt.abort();
@@ -1363,13 +1623,91 @@ class DevModeHandler {
   }
 }
 
+class ModuleContext {
+  constructor(schemaProvider, collector) {
+    this.schemaProvider = schemaProvider;
+    this.collector = collector;
+  }
+  /**
+   * Return the GraphQL schema.
+   *
+   * Note that the schema may be updated during development, so it can become
+   * stale. Prefer using methods like `schemaHasType()` to query the schema.
+   *
+   * @returns The GraphQL schema.
+   */
+  getSchema() {
+    return this.schemaProvider.getSchema();
+  }
+  /**
+   * Check if the given GraphQL type (interface, concrete type, enum, input type)
+   * exists in the schema.
+   *
+   * @param name - The name of the type.
+   *
+   * @returns True if the type exists in the schema.
+   */
+  schemaHasType(name) {
+    return !!this.schemaProvider.getSchema().getType(name);
+  }
+  /**
+   * Get a type from the schema.
+   *
+   * @param name - The name of the type.
+   *
+   * @returns The type.
+   */
+  schemaGetType(name) {
+    return this.schemaProvider.getSchema().getType(name);
+  }
+  /**
+   * Add an additional static document.
+   *
+   * @param identifier - The unique identifier for your document.
+   * @param source - The document source.
+   */
+  addDocument(identifier, source) {
+    this.collector.addHookDocument(identifier, source);
+    return this;
+  }
+  /**
+   * Add or update an additional static document.
+   *
+   * @param identifier - The unique identifier for your document.
+   * @param source - The document source.
+   */
+  async addOrUpdateDocument(identifier, source) {
+    await this.collector.addOrUpdateHookDocument(identifier, source);
+    return this;
+  }
+  /**
+   * Add an additional GraphQL file to import.
+   *
+   * @param filePath - The absolute path to the file.
+   */
+  addImportFile(filePath) {
+    if (!filePath.startsWith("/")) {
+      throw new Error(
+        `The provided file path "${filePath}" must be an absolute path.`
+      );
+    }
+    if (!filePath.endsWith(".graphql") && !filePath.endsWith(".gql")) {
+      throw new Error(
+        `The provided file path "${filePath}" should have a .graphql or .gql extension.`
+      );
+    }
+    this.collector.addHookFile(filePath);
+    return this;
+  }
+}
+
 const module = defineNuxtModule({
   meta: {
     name,
     configKey: "graphqlMiddleware",
     version,
     compatibility: {
-      nuxt: ">=3.15.0"
+      nuxt: ">=3.17.0"
     }
   },
   defaults: defaultOptions,
@@ -1378,6 +1716,8 @@ const module = defineNuxtModule({
     const schemaProvider = new SchemaProvider(helper);
     await schemaProvider.init();
     const collector = new Collector(schemaProvider.getSchema(), helper);
+    const moduleContext = new ModuleContext(schemaProvider, collector);
+    nuxt._nuxt_graphql_middleware = moduleContext;
     nuxt.options.appConfig.graphqlMiddleware = {
       clientCacheEnabled: !!helper.options.clientCache?.enabled,
       clientCacheMaxSize: helper.options.clientCache?.maxSize ?? 100
@@ -1391,9 +1731,9 @@ const module = defineNuxtModule({
     helper.inlineNitroExternals(helper.paths.moduleTypesDir);
     helper.addAlias("#nuxt-graphql-middleware", helper.paths.moduleBuildDir);
     helper.addAlias("#graphql-operations", helper.paths.moduleTypesDir);
-    helper.addPlugin("./runtime/plugins/provideState");
+    helper.addPlugin("provideState");
     if (helper.isDev && helper.options.errorOverlay) {
-      helper.addPlugin("./runtime/plugins/devMode");
+      helper.addPlugin("devMode");
     }
     helper.addServerHandler("query", "/query/:name", "get");
     helper.addServerHandler("mutation", "/mutation/:name", "post");
@@ -1423,7 +1763,10 @@ const module = defineNuxtModule({
       }
     });
     helper.applyBuildConfig();
-    await collector.init();
+    nuxt.hooks.hookOnce("modules:done", async () => {
+      await nuxt.hooks.callHook("nuxt-graphql-middleware:init", moduleContext);
+      await collector.init();
+    });
     if (!helper.isDev) {
       return;
     }