nitro-graphql 1.1.2 → 1.2.0

package/dist/routes/graphql-yoga.d.ts

@@ -1,6 +1,6 @@
-import * as h31 from "h3";
+import * as h30 from "h3";
 
 //#region src/routes/graphql-yoga.d.ts
-declare const _default: h31.EventHandler<h31.EventHandlerRequest, Promise<Response>>;
+declare const _default: h30.EventHandler<h30.EventHandlerRequest, Promise<Response>>;
 //#endregion
 export { _default as default };

package/dist/types/index.d.ts

@@ -57,6 +57,33 @@ declare module 'nitropack' {
     graphql?: NitroGraphQLOptions;
   }
 }
+interface ExternalGraphQLService {
+  /** Unique name for this service (used for file naming and type generation) */
+  name: string;
+  /** Schema source - can be URL(s) for remote schemas or file path(s) for local schemas */
+  schema: string | string[];
+  /** GraphQL endpoint for this service */
+  endpoint: string;
+  /** Optional headers for schema introspection and client requests */
+  headers?: Record<string, string> | (() => Record<string, string>);
+  /** Optional: specific document patterns for this service */
+  documents?: string[];
+  /**
+   * Optional: Download and cache schema locally for offline usage
+   * - true or 'once': Download if file doesn't exist, then use cached version (offline-friendly)
+   * - 'always': Check for updates on every build (current behavior)
+   * - 'manual': Never download automatically, user manages schema files manually
+   * - false: Disable schema downloading
+   */
+  downloadSchema?: boolean | 'once' | 'always' | 'manual';
+  /** Optional: Custom path to save downloaded schema (default: .nitro/graphql/schemas/[serviceName].graphql) */
+  downloadPath?: string;
+  /** Optional: service-specific codegen configuration */
+  codegen?: {
+    client?: CodegenClientConfig;
+    clientSDK?: GenericSdkConfig;
+  };
+}
 interface NitroGraphQLOptions {
   framework: 'graphql-yoga' | 'apollo-server';
   endpoint?: {
@@ -76,6 +103,8 @@ interface NitroGraphQLOptions {
     client?: CodegenClientConfig;
     clientSDK?: GenericSdkConfig;
   };
+  /** External GraphQL services to generate types and SDKs for */
+  externalServices?: ExternalGraphQLService[];
 }
 //#endregion
-export { CodegenClientConfig, CodegenServerConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions };
+export { CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, GenImport, GenericSdkConfig, NitroGraphQLOptions };

package/dist/utils/client-codegen.d.ts

@@ -1,4 +1,4 @@
-import { CodegenClientConfig, GenericSdkConfig } from "../types/index.js";
+import { CodegenClientConfig, ExternalGraphQLService, GenericSdkConfig } from "../types/index.js";
 import { GraphQLSchema } from "graphql";
 import { Source } from "@graphql-tools/utils";
 import { LoadSchemaOptions, UnnormalizedTypeDefPointer } from "@graphql-tools/load";
@@ -14,10 +14,25 @@ type GraphQLTypeDefPointer = UnnormalizedTypeDefPointer | UnnormalizedTypeDefPoi
  */
 type GraphQLLoadSchemaOptions = Partial<LoadSchemaOptions>;
 declare function graphQLLoadSchemaSync(schemaPointers: GraphQLTypeDefPointer, data?: GraphQLLoadSchemaOptions): Promise<GraphQLSchema | undefined>;
+/**
+ * Load schema from external GraphQL service
+ */
+declare function loadExternalSchema(service: ExternalGraphQLService, buildDir?: string): Promise<GraphQLSchema | undefined>;
+/**
+ * Download and save schema from external service
+ */
+declare function downloadAndSaveSchema(service: ExternalGraphQLService, buildDir: string): Promise<string | undefined>;
 declare function loadGraphQLDocuments(patterns: string | string[]): Promise<Source[]>;
-declare function generateClientTypes(schema: GraphQLSchema, docs: Source[], config?: CodegenClientConfig, sdkConfig?: GenericSdkConfig, outputPath?: string): Promise<false | {
+declare function generateClientTypes(schema: GraphQLSchema, docs: Source[], config?: CodegenClientConfig, sdkConfig?: GenericSdkConfig, outputPath?: string, serviceName?: string): Promise<false | {
   types: string;
   sdk: string;
 }>;
+/**
+ * Generate client types for external GraphQL service
+ */
+declare function generateExternalClientTypes(service: ExternalGraphQLService, schema: GraphQLSchema, docs: Source[]): Promise<{
+  types: string;
+  sdk: string;
+} | false>;
 //#endregion
-export { GraphQLLoadSchemaOptions, GraphQLTypeDefPointer, generateClientTypes, graphQLLoadSchemaSync, loadGraphQLDocuments };
+export { GraphQLLoadSchemaOptions, GraphQLTypeDefPointer, downloadAndSaveSchema, generateClientTypes, generateExternalClientTypes, graphQLLoadSchemaSync, loadExternalSchema, loadGraphQLDocuments };

package/dist/utils/client-codegen.js

@@ -1,14 +1,18 @@
 import { preset } from "../node_modules/.pnpm/@graphql-codegen_import-types-preset@3.0.1_graphql@16.11.0/node_modules/@graphql-codegen/import-types-preset/esm/index.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { consola as consola$1 } from "consola";
 import { defu as defu$1 } from "defu";
+import { dirname, resolve } from "pathe";
 import { parse } from "graphql";
 import { printSchemaWithDirectives } from "@graphql-tools/utils";
+import { createHash } from "node:crypto";
 import { codegen } from "@graphql-codegen/core";
 import { plugin } from "@graphql-codegen/typescript";
 import { plugin as plugin$1 } from "@graphql-codegen/typescript-generic-sdk";
 import { plugin as plugin$2 } from "@graphql-codegen/typescript-operations";
 import { GraphQLFileLoader } from "@graphql-tools/graphql-file-loader";
 import { loadDocuments, loadSchemaSync } from "@graphql-tools/load";
+import { UrlLoader } from "@graphql-tools/url-loader";
 import { CurrencyResolver, DateTimeISOResolver, DateTimeResolver, JSONObjectResolver, JSONResolver, NonEmptyStringResolver, UUIDResolver } from "graphql-scalars";
 
 //#region src/utils/client-codegen.ts
@@ -31,7 +35,11 @@ async function graphQLLoadSchemaSync(schemaPointers, data = {}) {
 	try {
 		result = loadSchemaSync(filteredPointers, {
 			...data,
-			loaders: [new GraphQLFileLoader(), ...data.loaders || []]
+			loaders: [
+				new GraphQLFileLoader(),
+				new UrlLoader(),
+				...data.loaders || []
+			]
 		});
 	} catch (e) {
 		if ((e.message || "").includes("Unable to find any GraphQL type definitions for the following pointers:")) consola$1.info("No server GraphQL files found. If you need server-side GraphQL, add .graphql files to your server directory.");
@@ -39,6 +47,92 @@ async function graphQLLoadSchemaSync(schemaPointers, data = {}) {
 	}
 	return result;
 }
+/**
+* Load schema from external GraphQL service
+*/
+async function loadExternalSchema(service, buildDir) {
+	try {
+		const headers = typeof service.headers === "function" ? service.headers() : service.headers || {};
+		const schemas = Array.isArray(service.schema) ? service.schema : [service.schema];
+		if (service.downloadSchema && buildDir) {
+			const defaultPath = resolve(buildDir, "graphql", "schemas", `${service.name}.graphql`);
+			const schemaFilePath = service.downloadPath ? resolve(service.downloadPath) : defaultPath;
+			if (existsSync(schemaFilePath)) {
+				consola$1.info(`[graphql:${service.name}] Loading schema from local file: ${schemaFilePath}`);
+				try {
+					const result$1 = loadSchemaSync([schemaFilePath], { loaders: [new GraphQLFileLoader()] });
+					consola$1.info(`[graphql:${service.name}] External schema loaded successfully from local file`);
+					return result$1;
+				} catch (localError) {
+					consola$1.warn(`[graphql:${service.name}] Failed to load local schema, falling back to remote:`, localError);
+				}
+			}
+		}
+		consola$1.info(`[graphql:${service.name}] Loading external schema from: ${schemas.join(", ")}`);
+		const result = loadSchemaSync(schemas, {
+			loaders: [new GraphQLFileLoader(), new UrlLoader()],
+			...Object.keys(headers).length > 0 && { headers }
+		});
+		consola$1.info(`[graphql:${service.name}] External schema loaded successfully`);
+		return result;
+	} catch (error) {
+		consola$1.error(`[graphql:${service.name}] Failed to load external schema:`, error);
+		return void 0;
+	}
+}
+/**
+* Download and save schema from external service
+*/
+async function downloadAndSaveSchema(service, buildDir) {
+	const downloadMode = service.downloadSchema;
+	if (!downloadMode || downloadMode === "manual") return void 0;
+	const defaultPath = resolve(buildDir, "graphql", "schemas", `${service.name}.graphql`);
+	const schemaFilePath = service.downloadPath ? resolve(service.downloadPath) : defaultPath;
+	try {
+		const headers = typeof service.headers === "function" ? service.headers() : service.headers || {};
+		const schemas = Array.isArray(service.schema) ? service.schema : [service.schema];
+		let shouldDownload = false;
+		const fileExists = existsSync(schemaFilePath);
+		if (downloadMode === "always") {
+			shouldDownload = true;
+			if (fileExists) try {
+				const remoteSchema = loadSchemaSync(schemas, {
+					loaders: [new UrlLoader()],
+					...Object.keys(headers).length > 0 && { headers }
+				});
+				const remoteSchemaString = printSchemaWithDirectives(remoteSchema);
+				const remoteHash = createHash("md5").update(remoteSchemaString).digest("hex");
+				const localSchemaString = readFileSync(schemaFilePath, "utf-8");
+				const localHash = createHash("md5").update(localSchemaString).digest("hex");
+				if (remoteHash === localHash) {
+					shouldDownload = false;
+					consola$1.info(`[graphql:${service.name}] Schema is up-to-date, using cached version`);
+				}
+			} catch {
+				consola$1.warn(`[graphql:${service.name}] Unable to compare with remote schema, updating local cache`);
+				shouldDownload = true;
+			}
+		} else if (downloadMode === true || downloadMode === "once") {
+			shouldDownload = !fileExists;
+			if (fileExists) consola$1.info(`[graphql:${service.name}] Using cached schema from: ${schemaFilePath}`);
+		}
+		if (shouldDownload) {
+			consola$1.info(`[graphql:${service.name}] Downloading schema to: ${schemaFilePath}`);
+			const schema = loadSchemaSync(schemas, {
+				loaders: [new UrlLoader()],
+				...Object.keys(headers).length > 0 && { headers }
+			});
+			const schemaString = printSchemaWithDirectives(schema);
+			mkdirSync(dirname(schemaFilePath), { recursive: true });
+			writeFileSync(schemaFilePath, schemaString, "utf-8");
+			consola$1.success(`[graphql:${service.name}] Schema downloaded and saved successfully`);
+		}
+		return schemaFilePath;
+	} catch (error) {
+		consola$1.error(`[graphql:${service.name}] Failed to download schema:`, error);
+		return void 0;
+	}
+}
 async function loadGraphQLDocuments(patterns) {
 	try {
 		const result = await loadDocuments(patterns, { loaders: [new GraphQLFileLoader()] });
@@ -48,12 +142,14 @@ async function loadGraphQLDocuments(patterns) {
 		else throw e;
 	}
 }
-async function generateClientTypes(schema, docs, config = {}, sdkConfig = {}, outputPath) {
+async function generateClientTypes(schema, docs, config = {}, sdkConfig = {}, outputPath, serviceName) {
 	if (docs.length === 0) {
-		consola$1.info("[graphql] No client GraphQL files found. Skipping client type generation.");
+		const serviceLabel$1 = serviceName ? `:${serviceName}` : "";
+		consola$1.info(`[graphql${serviceLabel$1}] No client GraphQL files found. Skipping client type generation.`);
 		return false;
 	}
-	consola$1.info(`[graphql] Found ${docs.length} client GraphQL documents`);
+	const serviceLabel = serviceName ? `:${serviceName}` : "";
+	consola$1.info(`[graphql${serviceLabel}] Found ${docs.length} client GraphQL documents`);
 	const defaultConfig = {
 		emitLegacyCommonJSImports: false,
 		useTypeImports: true,
@@ -98,12 +194,13 @@ async function generateClientTypes(schema, docs, config = {}, sdkConfig = {}, ou
 				typescriptOperations: { plugin: plugin$2 }
 			}
 		});
+		const typesPath = serviceName ? `#graphql/client/${serviceName}` : "#graphql/client";
 		const sdkOutput = await preset.buildGeneratesSection({
 			baseOutputDir: outputPath || "client-types.generated.ts",
 			schema: parse(printSchemaWithDirectives(schema)),
 			documents: [...docs],
 			config: mergedSdkConfig,
-			presetConfig: { typesPath: "#graphql/client" },
+			presetConfig: { typesPath },
 			plugins: [{ pluginContent: {} }, { typescriptGenericSdk: {} }],
 			pluginMap: {
 				pluginContent: { plugin: pluginContent },
@@ -116,15 +213,24 @@ async function generateClientTypes(schema, docs, config = {}, sdkConfig = {}, ou
 				content: await codegen(config$1)
 			};
 		}));
+		const sdkContent = results[0]?.content || "";
 		return {
 			types: output,
-			sdk: results[0]?.content || ""
+			sdk: sdkContent
 		};
 	} catch (error) {
-		consola$1.warn("[graphql] Client type generation failed:", error);
+		consola$1.warn(`[graphql${serviceLabel}] Client type generation failed:`, error);
 		return false;
 	}
 }
+/**
+* Generate client types for external GraphQL service
+*/
+async function generateExternalClientTypes(service, schema, docs) {
+	const config = service.codegen?.client || {};
+	const sdkConfig = service.codegen?.clientSDK || {};
+	return generateClientTypes(schema, docs, config, sdkConfig, void 0, service.name);
+}
 
 //#endregion
-export { generateClientTypes, graphQLLoadSchemaSync, loadGraphQLDocuments };
+export { downloadAndSaveSchema, generateClientTypes, generateExternalClientTypes, graphQLLoadSchemaSync, loadExternalSchema, loadGraphQLDocuments };

package/dist/utils/directive-parser.d.ts

@@ -0,0 +1,80 @@
+//#region src/utils/directive-parser.d.ts
+interface ParsedDirective {
+  name: string;
+  locations: string[];
+  args?: Record<string, {
+    type: string;
+    defaultValue?: any;
+  }>;
+  description?: string;
+  isRepeatable?: boolean;
+}
+/**
+ * Clean AST-based directive parser using oxc-parser
+ */
+declare class DirectiveParser {
+  private oxc;
+  init(): Promise<void>;
+  /**
+   * Parse directives from a TypeScript/JavaScript file
+   */
+  parseDirectives(fileContent: string, filePath: string): Promise<ParsedDirective[]>;
+  /**
+   * Extract directive definitions from AST
+   */
+  private extractDirectiveDefinitions;
+  /**
+   * Traverse AST nodes recursively
+   */
+  private traverse;
+  /**
+   * Check if node is a defineDirective call
+   */
+  private isDefineDirectiveCall;
+  /**
+   * Extract directive configuration from defineDirective call
+   */
+  private extractDirectiveFromCall;
+  /**
+   * Extract directive properties from object expression
+   */
+  private extractDirectiveFromObject;
+  /**
+   * Extract string literal value
+   */
+  private extractStringLiteral;
+  /**
+   * Extract boolean literal value
+   */
+  private extractBooleanLiteral;
+  /**
+   * Extract array of strings
+   */
+  private extractStringArray;
+  /**
+   * Extract arguments object
+   */
+  private extractArgsObject;
+  /**
+   * Extract argument configuration
+   */
+  private extractArgConfig;
+  /**
+   * Extract literal value (string, number, boolean)
+   */
+  private extractLiteralValue;
+}
+/**
+ * Generate GraphQL directive schema from parsed directive
+ */
+declare function generateDirectiveSchema(directive: ParsedDirective): string;
+/**
+ * Generate directive schemas file from scanned directives
+ */
+declare function generateDirectiveSchemas(nitro: any, directives: any[]): Promise<void>;
+/**
+ * Singleton instance for reuse
+ */
+declare const directiveParser: DirectiveParser;
+//#endregion
+export { DirectiveParser, ParsedDirective, directiveParser, generateDirectiveSchema, generateDirectiveSchemas };

package/dist/utils/directive-parser.js

@@ -0,0 +1,235 @@
+//#region src/utils/directive-parser.ts
+/**
+* Clean AST-based directive parser using oxc-parser
+*/
+var DirectiveParser = class {
+	oxc;
+	async init() {
+		if (!this.oxc) this.oxc = await import("oxc-parser");
+	}
+	/**
+	* Parse directives from a TypeScript/JavaScript file
+	*/
+	async parseDirectives(fileContent, filePath) {
+		await this.init();
+		try {
+			const result = this.oxc.parseSync(filePath, fileContent, {
+				lang: filePath.endsWith(".ts") ? "ts" : "js",
+				sourceType: "module",
+				astType: "ts"
+			});
+			if (result.errors.length > 0) {
+				console.warn(`Parse errors in ${filePath}:`, result.errors.map((e) => e.message));
+				return [];
+			}
+			return this.extractDirectiveDefinitions(result.program);
+		} catch (error) {
+			console.warn(`Failed to parse ${filePath} with oxc:`, error);
+			return [];
+		}
+	}
+	/**
+	* Extract directive definitions from AST
+	*/
+	extractDirectiveDefinitions(program) {
+		const directives = [];
+		this.traverse(program, (node) => {
+			if (this.isDefineDirectiveCall(node)) {
+				const directive = this.extractDirectiveFromCall(node);
+				if (directive) directives.push(directive);
+			}
+		});
+		return directives;
+	}
+	/**
+	* Traverse AST nodes recursively
+	*/
+	traverse(node, visitor) {
+		if (!node || typeof node !== "object") return;
+		visitor(node);
+		for (const key in node) {
+			const child = node[key];
+			if (Array.isArray(child)) child.forEach((item) => this.traverse(item, visitor));
+			else if (child && typeof child === "object") this.traverse(child, visitor);
+		}
+	}
+	/**
+	* Check if node is a defineDirective call
+	*/
+	isDefineDirectiveCall(node) {
+		return node.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "defineDirective" && node.arguments?.length > 0;
+	}
+	/**
+	* Extract directive configuration from defineDirective call
+	*/
+	extractDirectiveFromCall(node) {
+		const arg = node.arguments[0];
+		if (arg?.type !== "ObjectExpression") return null;
+		return this.extractDirectiveFromObject(arg);
+	}
+	/**
+	* Extract directive properties from object expression
+	*/
+	extractDirectiveFromObject(objNode) {
+		let name = "";
+		let locations = [];
+		let args = {};
+		let description;
+		let isRepeatable;
+		for (const prop of objNode.properties || []) {
+			if (prop.type !== "Property" || prop.key?.type !== "Identifier") continue;
+			switch (prop.key.name) {
+				case "name":
+					name = this.extractStringLiteral(prop.value) || "";
+					break;
+				case "locations":
+					locations = this.extractStringArray(prop.value);
+					break;
+				case "args":
+					args = this.extractArgsObject(prop.value);
+					break;
+				case "description":
+					description = this.extractStringLiteral(prop.value);
+					break;
+				case "isRepeatable":
+					isRepeatable = this.extractBooleanLiteral(prop.value);
+					break;
+			}
+		}
+		return name && locations.length > 0 ? {
+			name,
+			locations,
+			args,
+			description,
+			isRepeatable
+		} : null;
+	}
+	/**
+	* Extract string literal value
+	*/
+	extractStringLiteral(node) {
+		if (node?.type === "Literal" && typeof node.value === "string") return node.value;
+		return void 0;
+	}
+	/**
+	* Extract boolean literal value
+	*/
+	extractBooleanLiteral(node) {
+		if (node?.type === "Literal" && typeof node.value === "boolean") return node.value;
+		return void 0;
+	}
+	/**
+	* Extract array of strings
+	*/
+	extractStringArray(node) {
+		if (node?.type !== "ArrayExpression") return [];
+		return (node.elements || []).filter((el) => el?.type === "Literal" && typeof el.value === "string").map((el) => el.value);
+	}
+	/**
+	* Extract arguments object
+	*/
+	extractArgsObject(node) {
+		if (node?.type !== "ObjectExpression") return {};
+		const args = {};
+		for (const prop of node.properties || []) {
+			if (prop.type !== "Property" || prop.key?.type !== "Identifier") continue;
+			const argName = prop.key.name;
+			const argConfig = this.extractArgConfig(prop.value);
+			if (argConfig) args[argName] = argConfig;
+		}
+		return args;
+	}
+	/**
+	* Extract argument configuration
+	*/
+	extractArgConfig(node) {
+		if (node?.type !== "ObjectExpression") return null;
+		let type = "String";
+		let defaultValue;
+		for (const prop of node.properties || []) {
+			if (prop.type !== "Property" || prop.key?.type !== "Identifier") continue;
+			switch (prop.key.name) {
+				case "type": {
+					const typeValue = this.extractStringLiteral(prop.value);
+					if (typeValue) type = typeValue;
+					break;
+				}
+				case "defaultValue":
+					defaultValue = this.extractLiteralValue(prop.value);
+					break;
+			}
+		}
+		return {
+			type,
+			...defaultValue !== void 0 && { defaultValue }
+		};
+	}
+	/**
+	* Extract literal value (string, number, boolean)
+	*/
+	extractLiteralValue(node) {
+		if (node?.type === "Literal") return node.value;
+		return void 0;
+	}
+};
+/**
+* Generate GraphQL directive schema from parsed directive
+*/
+function generateDirectiveSchema(directive) {
+	let args = "";
+	if (directive.args && Object.keys(directive.args).length > 0) {
+		const argDefs = Object.entries(directive.args).map(([name, arg]) => {
+			let defaultValue = "";
+			if (arg.defaultValue !== void 0) if (typeof arg.defaultValue === "string") defaultValue = ` = "${arg.defaultValue}"`;
+			else defaultValue = ` = ${arg.defaultValue}`;
+			return `${name}: ${arg.type}${defaultValue}`;
+		});
+		args = `(${argDefs.join(", ")})`;
+	}
+	const locations = directive.locations.join(" | ");
+	return `directive @${directive.name}${args} on ${locations}`;
+}
+/**
+* Generate directive schemas file from scanned directives
+*/
+async function generateDirectiveSchemas(nitro, directives) {
+	if (directives.length === 0) return;
+	const { existsSync, readFileSync, writeFileSync } = await import("node:fs");
+	const { readFile } = await import("node:fs/promises");
+	const { resolve } = await import("pathe");
+	const directiveSchemas = [];
+	const seenDirectives = /* @__PURE__ */ new Set();
+	const parser = new DirectiveParser();
+	for (const dir of directives) for (const _imp of dir.imports) {
+		const fileContent = await readFile(dir.specifier, "utf-8");
+		const directiveDefs = await parser.parseDirectives(fileContent, dir.specifier);
+		for (const def of directiveDefs) {
+			if (seenDirectives.has(def.name)) continue;
+			seenDirectives.add(def.name);
+			const schema = generateDirectiveSchema(def);
+			directiveSchemas.push(schema);
+		}
+	}
+	if (directiveSchemas.length > 0) {
+		const directivesPath = resolve(nitro.graphql.serverDir, "_directives.graphql");
+		const content = `# WARNING: This file is auto-generated by nitro-graphql
+# Do not modify this file directly. It will be overwritten.
+# To define custom directives, create .directive.ts files using defineDirective()
+
+${directiveSchemas.join("\n\n")}`;
+		let shouldWrite = true;
+		if (existsSync(directivesPath)) {
+			const existingContent = readFileSync(directivesPath, "utf-8");
+			shouldWrite = existingContent !== content;
+		}
+		if (shouldWrite) writeFileSync(directivesPath, content, "utf-8");
+		if (!nitro.scanSchemas.includes(directivesPath)) nitro.scanSchemas.push(directivesPath);
+	}
+}
+/**
+* Singleton instance for reuse
+*/
+const directiveParser = new DirectiveParser();
+
+//#endregion
+export { DirectiveParser, directiveParser, generateDirectiveSchema, generateDirectiveSchemas };

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
 import { GenImport } from "../types/index.js";
+import { directiveParser, generateDirectiveSchema, generateDirectiveSchemas } from "./directive-parser.js";
 import { Nitro } from "nitropack";
 
 //#region src/utils/index.d.ts
@@ -11,5 +12,13 @@ declare function scanDirectives(nitro: Nitro): Promise<GenImport[]>;
 declare function scanTypeDefs(nitro: Nitro): Promise<string[]>;
 declare function scanSchemas(nitro: Nitro): Promise<string[]>;
 declare function scanDocs(nitro: Nitro): Promise<string[]>;
+/**
+ * Scan documents for a specific external service
+ */
+declare function scanExternalServiceDocs(nitro: Nitro, serviceName: string, patterns: string[]): Promise<string[]>;
+/**
+ * Validate external GraphQL service configuration
+ */
+declare function validateExternalServices(services: any[]): string[];
 //#endregion
-export { GLOB_SCAN_PATTERN, getImportId, relativeWithDot, scanDirectives, scanDocs, scanGraphql, scanResolvers, scanSchemas, scanTypeDefs };
+export { GLOB_SCAN_PATTERN, directiveParser, generateDirectiveSchema, generateDirectiveSchemas, getImportId, relativeWithDot, scanDirectives, scanDocs, scanExternalServiceDocs, scanGraphql, scanResolvers, scanSchemas, scanTypeDefs, validateExternalServices };

package/dist/utils/index.js

@@ -1,5 +1,6 @@
-import { readFile } from "node:fs/promises";
+import { directiveParser, generateDirectiveSchema, generateDirectiveSchemas } from "./directive-parser.js";
 import { join, relative } from "pathe";
+import { readFile } from "node:fs/promises";
 import { hash } from "ohash";
 import { parseAsync } from "oxc-parser";
 import { glob } from "tinyglobby";
@@ -103,7 +104,48 @@ async function scanSchemas(nitro) {
 }
 async function scanDocs(nitro) {
 	const files = await scanDir(nitro, nitro.options.rootDir, nitro.graphql.dir.client, "**/*.graphql");
-	return files.map((f) => f.fullPath);
+	return files.filter((f) => !f.path.startsWith("external/")).map((f) => f.fullPath);
+}
+/**
+* Scan documents for a specific external service
+*/
+async function scanExternalServiceDocs(nitro, serviceName, patterns) {
+	if (!patterns.length) return [];
+	const files = [];
+	for (const pattern of patterns) try {
+		const serviceFiles = await glob(pattern, {
+			cwd: nitro.options.rootDir,
+			dot: true,
+			ignore: nitro.options.ignore,
+			absolute: true
+		});
+		files.push(...serviceFiles);
+	} catch (error) {
+		nitro.logger.warn(`[graphql:${serviceName}] Error scanning documents with pattern "${pattern}":`, error);
+	}
+	return files.filter((file, index, self) => self.indexOf(file) === index);
+}
+/**
+* Validate external GraphQL service configuration
+*/
+function validateExternalServices(services) {
+	const errors = [];
+	const serviceNames = /* @__PURE__ */ new Set();
+	for (const [index, service] of services.entries()) {
+		const prefix = `externalServices[${index}]`;
+		if (!service.name || typeof service.name !== "string") errors.push(`${prefix}.name is required and must be a string`);
+		else if (serviceNames.has(service.name)) errors.push(`${prefix}.name "${service.name}" must be unique`);
+		else serviceNames.add(service.name);
+		if (!service.schema) errors.push(`${prefix}.schema is required`);
+		if (!service.endpoint || typeof service.endpoint !== "string") errors.push(`${prefix}.endpoint is required and must be a string`);
+		else try {
+			const url = new URL(service.endpoint);
+		} catch {
+			errors.push(`${prefix}.endpoint "${service.endpoint}" must be a valid URL`);
+		}
+		if (service.name && !/^[a-z]\w*$/i.test(service.name)) errors.push(`${prefix}.name "${service.name}" must be a valid identifier (letters, numbers, underscore, starting with letter)`);
+	}
+	return errors;
 }
 async function scanFiles(nitro, name, globPattern = GLOB_SCAN_PATTERN) {
 	const files = await Promise.all(nitro.options.scanDirs.map((dir) => scanDir(nitro, dir, name, globPattern))).then((r) => r.flat());
@@ -131,4 +173,4 @@ async function scanDir(nitro, dir, name, globPattern = GLOB_SCAN_PATTERN) {
 }
 
 //#endregion
-export { GLOB_SCAN_PATTERN, getImportId, relativeWithDot, scanDirectives, scanDocs, scanGraphql, scanResolvers, scanSchemas, scanTypeDefs };
+export { GLOB_SCAN_PATTERN, directiveParser, generateDirectiveSchema, generateDirectiveSchemas, getImportId, relativeWithDot, scanDirectives, scanDocs, scanExternalServiceDocs, scanGraphql, scanResolvers, scanSchemas, scanTypeDefs, validateExternalServices };