nitro-graphql 2.0.0-beta.4 → 2.0.0-beta.41

package/dist/{utils/directive-parser.js → core/utils/directive-parser.mjs}

@@ -1,4 +1,4 @@
-//#region src/utils/directive-parser.ts
+//#region src/core/utils/directive-parser.ts
 /**
 * Clean AST-based directive parser using oxc-parser
 */
@@ -180,45 +180,36 @@ function generateDirectiveSchema(directive) {
 	return `directive @${directive.name}${args} on ${locations}`;
 }
 /**
-* Generate directive schemas file from scanned directives
+* Get the file path from a directive reference
 */
-async function generateDirectiveSchemas(nitro, directives) {
-	if (directives.length === 0) return;
-	const { existsSync, readFileSync, writeFileSync, mkdirSync } = await import("node:fs");
-	const { readFile } = await import("node:fs/promises");
-	const { resolve, dirname } = 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.buildDir, "_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")}`;
-		const targetDir = dirname(directivesPath);
-		if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
-		let shouldWrite = true;
-		if (existsSync(directivesPath)) shouldWrite = readFileSync(directivesPath, "utf-8") !== content;
-		if (shouldWrite) writeFileSync(directivesPath, content, "utf-8");
-		if (!nitro.scanSchemas.includes(directivesPath)) nitro.scanSchemas.push(directivesPath);
-	}
+function getFilePath(ref) {
+	return "fullPath" in ref ? ref.fullPath : ref.specifier;
 }
 /**
 * Singleton instance for reuse
 */
 const directiveParser = new DirectiveParser();
+/**
+* Generate GraphQL schemas from an array of parsed directives
+*/
+async function generateDirectiveSchemas(nitro, directives) {
+	if (directives.length === 0) return null;
+	const fs = await import("node:fs");
+	const path = await import("pathe");
+	const allParsedDirectives = [];
+	for (const directive of directives) try {
+		const filePath = getFilePath(directive);
+		const content = fs.readFileSync(filePath, "utf-8");
+		const parsed = await directiveParser.parseDirectives(content, filePath);
+		allParsedDirectives.push(...parsed);
+	} catch {}
+	if (allParsedDirectives.length === 0) return null;
+	const schemaContent = allParsedDirectives.map((d) => generateDirectiveSchema(d)).join("\n\n");
+	const directivesPath = path.join(nitro.graphql.buildDir, "_directives.graphql");
+	fs.mkdirSync(path.dirname(directivesPath), { recursive: true });
+	fs.writeFileSync(directivesPath, schemaContent, "utf-8");
+	return directivesPath;
+}
 
 //#endregion
 export { DirectiveParser, directiveParser, generateDirectiveSchema, generateDirectiveSchemas };

package/dist/core/utils/errors.d.mts

@@ -0,0 +1,77 @@
+//#region src/core/utils/errors.d.ts
+/**
+ * Error handling utilities for GraphQL
+ * Framework-agnostic error masking and handling
+ */
+interface MaskErrorOptions {
+  /**
+   * Default HTTP status code for validation errors (ZodError)
+   * @default 400
+   */
+  validationStatusCode?: number;
+  /**
+   * Default HTTP status code for HTTP errors when status is not provided
+   * @default 500
+   */
+  defaultHttpStatusCode?: number;
+}
+/**
+ * Default error masking function for GraphQL Yoga
+ * Handles common error types like ZodError and HTTPError
+ *
+ * @param options - Configuration options for error handling
+ *
+ * @example Basic usage
+ * ```ts
+ * import { defineGraphQLConfig } from 'nitro-graphql/define'
+ * import { createDefaultMaskError } from 'nitro-graphql/core'
+ *
+ * export default defineGraphQLConfig({
+ *   maskedErrors: {
+ *     maskError: createDefaultMaskError()
+ *   }
+ * })
+ * ```
+ *
+ * @example Custom status codes
+ * ```ts
+ * import { defineGraphQLConfig } from 'nitro-graphql/define'
+ * import { createDefaultMaskError } from 'nitro-graphql/core'
+ *
+ * export default defineGraphQLConfig({
+ *   maskedErrors: {
+ *     maskError: createDefaultMaskError({
+ *       validationStatusCode: 422,  // Use 422 for validation errors
+ *       defaultHttpStatusCode: 500  // Use 500 for unknown HTTP errors
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * @example Custom error handling with fallback to default
+ * ```ts
+ * import { defineGraphQLConfig } from 'nitro-graphql/define'
+ * import { createDefaultMaskError } from 'nitro-graphql/core'
+ *
+ * const defaultMaskError = createDefaultMaskError()
+ *
+ * export default defineGraphQLConfig({
+ *   maskedErrors: {
+ *     maskError: (error: unknown) => {
+ *       // Handle custom errors first
+ *       if (error instanceof MyCustomError) {
+ *         return new GraphQLError(error.message, {
+ *           extensions: { code: 'CUSTOM_ERROR' }
+ *         })
+ *       }
+ *
+ *       // Fall back to default handling
+ *       return defaultMaskError(error)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function createDefaultMaskError(options?: MaskErrorOptions): (error: unknown) => Error;
+//#endregion
+export { MaskErrorOptions, createDefaultMaskError };

package/dist/core/utils/errors.mjs

@@ -0,0 +1,93 @@
+import { GraphQLError } from "graphql";
+
+//#region src/core/utils/errors.ts
+/**
+* Error handling utilities for GraphQL
+* Framework-agnostic error masking and handling
+*/
+/**
+* Default error masking function for GraphQL Yoga
+* Handles common error types like ZodError and HTTPError
+*
+* @param options - Configuration options for error handling
+*
+* @example Basic usage
+* ```ts
+* import { defineGraphQLConfig } from 'nitro-graphql/define'
+* import { createDefaultMaskError } from 'nitro-graphql/core'
+*
+* export default defineGraphQLConfig({
+*   maskedErrors: {
+*     maskError: createDefaultMaskError()
+*   }
+* })
+* ```
+*
+* @example Custom status codes
+* ```ts
+* import { defineGraphQLConfig } from 'nitro-graphql/define'
+* import { createDefaultMaskError } from 'nitro-graphql/core'
+*
+* export default defineGraphQLConfig({
+*   maskedErrors: {
+*     maskError: createDefaultMaskError({
+*       validationStatusCode: 422,  // Use 422 for validation errors
+*       defaultHttpStatusCode: 500  // Use 500 for unknown HTTP errors
+*     })
+*   }
+* })
+* ```
+*
+* @example Custom error handling with fallback to default
+* ```ts
+* import { defineGraphQLConfig } from 'nitro-graphql/define'
+* import { createDefaultMaskError } from 'nitro-graphql/core'
+*
+* const defaultMaskError = createDefaultMaskError()
+*
+* export default defineGraphQLConfig({
+*   maskedErrors: {
+*     maskError: (error: unknown) => {
+*       // Handle custom errors first
+*       if (error instanceof MyCustomError) {
+*         return new GraphQLError(error.message, {
+*           extensions: { code: 'CUSTOM_ERROR' }
+*         })
+*       }
+*
+*       // Fall back to default handling
+*       return defaultMaskError(error)
+*     }
+*   }
+* })
+* ```
+*/
+function createDefaultMaskError(options) {
+	const validationStatusCode = options?.validationStatusCode ?? 400;
+	const defaultHttpStatusCode = options?.defaultHttpStatusCode ?? 500;
+	return (error) => {
+		if (error && typeof error === "object" && "originalError" in error) {
+			const graphqlError = error;
+			if (graphqlError.originalError && typeof graphqlError.originalError === "object" && "issues" in graphqlError.originalError && Array.isArray(graphqlError.originalError.issues)) return new GraphQLError("Validation failed", { extensions: {
+				code: "BAD_USER_INPUT",
+				validationErrors: graphqlError.originalError.issues.map((issue) => ({
+					field: issue.path.join("."),
+					message: issue.message
+				})),
+				http: { status: validationStatusCode }
+			} });
+			if (graphqlError.originalError && typeof graphqlError.originalError === "object" && "statusCode" in graphqlError.originalError && "statusMessage" in graphqlError.originalError) {
+				const httpError = graphqlError.originalError;
+				const statusCode = httpError.statusCode ?? defaultHttpStatusCode;
+				return new GraphQLError(httpError.statusMessage || httpError.message || "Internal Server Error", { extensions: {
+					code: statusCode,
+					http: { status: statusCode }
+				} });
+			}
+		}
+		return error instanceof Error ? error : new Error(String(error));
+	};
+}
+
+//#endregion
+export { createDefaultMaskError };

package/dist/core/utils/file-io.d.mts

@@ -0,0 +1,24 @@
+//#region src/core/utils/file-io.d.ts
+/**
+ * Unified file I/O utilities
+ * Centralizes file writing patterns used across the codebase
+ */
+/**
+ * Write file with automatic directory creation
+ */
+declare function writeFile(path: string, content: string): void;
+/**
+ * Write file only if content changed (for dev mode optimization)
+ * Returns true if file was written, false if unchanged
+ */
+declare function writeFileIfChanged(path: string, content: string): boolean;
+/**
+ * Ensure directory exists
+ */
+declare function ensureDir(path: string): void;
+/**
+ * Read file safely, returns undefined if file doesn't exist
+ */
+declare function readFileSafe(path: string): string | undefined;
+//#endregion
+export { ensureDir, readFileSafe, writeFile, writeFileIfChanged };

package/dist/core/utils/file-io.mjs

@@ -0,0 +1,47 @@
+import { dirname } from "pathe";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+
+//#region src/core/utils/file-io.ts
+/**
+* Unified file I/O utilities
+* Centralizes file writing patterns used across the codebase
+*/
+/**
+* Write file with automatic directory creation
+*/
+function writeFile(path, content) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, content, "utf-8");
+}
+/**
+* Write file only if content changed (for dev mode optimization)
+* Returns true if file was written, false if unchanged
+*/
+function writeFileIfChanged(path, content) {
+	try {
+		if (existsSync(path)) {
+			if (readFileSync(path, "utf-8") === content) return false;
+		}
+	} catch {}
+	writeFile(path, content);
+	return true;
+}
+/**
+* Ensure directory exists
+*/
+function ensureDir(path) {
+	mkdirSync(path, { recursive: true });
+}
+/**
+* Read file safely, returns undefined if file doesn't exist
+*/
+function readFileSafe(path) {
+	try {
+		return readFileSync(path, "utf-8");
+	} catch {
+		return;
+	}
+}
+
+//#endregion
+export { ensureDir, readFileSafe, writeFile, writeFileIfChanged };

package/dist/core/utils/imports.d.mts

@@ -0,0 +1,15 @@
+//#region src/core/utils/imports.d.ts
+/**
+ * Import utilities
+ * Helpers for generating import IDs and relative paths
+ */
+/**
+ * Generate a unique import ID for a file path
+ */
+declare function getImportId(p: string, lazy?: boolean): string;
+/**
+ * Get relative path with a leading dot for module resolution
+ */
+declare function relativeWithDot(from: string, to: string): string;
+//#endregion
+export { getImportId, relativeWithDot };

package/dist/core/utils/imports.mjs

@@ -0,0 +1,25 @@
+import { relative } from "pathe";
+import { hash } from "ohash";
+
+//#region src/core/utils/imports.ts
+/**
+* Import utilities
+* Helpers for generating import IDs and relative paths
+*/
+/**
+* Generate a unique import ID for a file path
+*/
+function getImportId(p, lazy) {
+	return (lazy ? "_lazy_" : "_") + hash(p).replace(/-/g, "").slice(0, 6);
+}
+const RELATIVE_RE = /^\.{1,2}\//;
+/**
+* Get relative path with a leading dot for module resolution
+*/
+function relativeWithDot(from, to) {
+	const rel = relative(from, to);
+	return RELATIVE_RE.test(rel) ? rel : `./${rel}`;
+}
+
+//#endregion
+export { getImportId, relativeWithDot };

package/dist/core/utils/index.d.mts

@@ -0,0 +1,7 @@
+import { DirectiveFileRef, DirectiveParser, ParsedDirective, directiveParser, generateDirectiveSchema, generateDirectiveSchemas } from "./directive-parser.mjs";
+import { MaskErrorOptions, createDefaultMaskError } from "./errors.mjs";
+import { ensureDir, readFileSafe, writeFile, writeFileIfChanged } from "./file-io.mjs";
+import { getImportId, relativeWithDot } from "./imports.mjs";
+import { createLogger, createSilentLogger, defaultLogger } from "./logger.mjs";
+import { OfetchTemplateOptions, generateOfetchTemplate } from "./ofetch-templates.mjs";
+export { DirectiveFileRef, DirectiveParser, MaskErrorOptions, OfetchTemplateOptions, ParsedDirective, createDefaultMaskError, createLogger, createSilentLogger, defaultLogger, directiveParser, ensureDir, generateDirectiveSchema, generateDirectiveSchemas, generateOfetchTemplate, getImportId, readFileSafe, relativeWithDot, writeFile, writeFileIfChanged };

package/dist/core/utils/index.mjs

@@ -0,0 +1,8 @@
+import { ensureDir, readFileSafe, writeFile, writeFileIfChanged } from "./file-io.mjs";
+import { createLogger, createSilentLogger, defaultLogger } from "./logger.mjs";
+import { DirectiveParser, directiveParser, generateDirectiveSchema, generateDirectiveSchemas } from "./directive-parser.mjs";
+import { createDefaultMaskError } from "./errors.mjs";
+import { getImportId, relativeWithDot } from "./imports.mjs";
+import { generateOfetchTemplate } from "./ofetch-templates.mjs";
+
+export { DirectiveParser, createDefaultMaskError, createLogger, createSilentLogger, defaultLogger, directiveParser, ensureDir, generateDirectiveSchema, generateDirectiveSchemas, generateOfetchTemplate, getImportId, readFileSafe, relativeWithDot, writeFile, writeFileIfChanged };

package/dist/core/utils/logger.d.mts

@@ -0,0 +1,19 @@
+import { CoreLogger } from "../types/config.mjs";
+
+//#region src/core/utils/logger.d.ts
+
+/**
+ * Create a logger instance with the nitro-graphql tag
+ */
+declare function createLogger(tag?: string): CoreLogger;
+/**
+ * Default logger instance
+ */
+declare const defaultLogger: CoreLogger;
+/**
+ * Create a silent logger (no output)
+ * Useful for testing or when logging should be suppressed
+ */
+declare function createSilentLogger(): CoreLogger;
+//#endregion
+export { createLogger, createSilentLogger, defaultLogger };

package/dist/core/utils/logger.mjs

@@ -0,0 +1,38 @@
+import { LOG_TAG } from "../constants.mjs";
+import { consola as consola$1 } from "consola";
+
+//#region src/core/utils/logger.ts
+/**
+* Create a logger instance with the nitro-graphql tag
+*/
+function createLogger(tag = LOG_TAG) {
+	const logger = consola$1.withTag(tag);
+	return {
+		info: (message, ...args) => logger.info(message, ...args),
+		warn: (message, ...args) => logger.warn(message, ...args),
+		error: (message, ...args) => logger.error(message, ...args),
+		success: (message, ...args) => logger.success(message, ...args),
+		debug: (message, ...args) => logger.debug(message, ...args)
+	};
+}
+/**
+* Default logger instance
+*/
+const defaultLogger = createLogger();
+/**
+* Create a silent logger (no output)
+* Useful for testing or when logging should be suppressed
+*/
+function createSilentLogger() {
+	const noop = () => {};
+	return {
+		info: noop,
+		warn: noop,
+		error: noop,
+		success: noop,
+		debug: noop
+	};
+}
+
+//#endregion
+export { createLogger, createSilentLogger, defaultLogger };

package/dist/core/utils/ofetch-templates.d.mts

@@ -0,0 +1,30 @@
+//#region src/core/utils/ofetch-templates.d.ts
+/**
+ * Shared ofetch template generation utilities
+ * Used by both main client and external service code generation
+ */
+interface OfetchTemplateOptions {
+  /** Service name (e.g., 'default', 'github') */
+  serviceName: string;
+  /** Whether to use Nuxt composables ($fetch, useRequestHeaders) */
+  isNuxt: boolean;
+  /** Endpoint URL for the GraphQL service */
+  endpoint: string;
+  /** Whether this is an external service (affects naming convention) */
+  isExternal?: boolean;
+}
+/**
+ * Generate ofetch client template content
+ *
+ * For main (default) service:
+ * - SDK exported as `$sdk`
+ * - Client function is `createGraphQLClient`
+ *
+ * For external services:
+ * - SDK exported as `$${serviceName}Sdk`
+ * - Client function is `create${ServiceName}GraphQLClient`
+ * - Endpoint has default value
+ */
+declare function generateOfetchTemplate(options: OfetchTemplateOptions): string;
+//#endregion
+export { OfetchTemplateOptions, generateOfetchTemplate };

package/dist/core/utils/ofetch-templates.mjs

@@ -0,0 +1,135 @@
+//#region src/core/utils/ofetch-templates.ts
+/**
+* Capitalize first letter of a string
+*/
+function capitalize(str) {
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+* Generate ofetch client template content
+*
+* For main (default) service:
+* - SDK exported as `$sdk`
+* - Client function is `createGraphQLClient`
+*
+* For external services:
+* - SDK exported as `$${serviceName}Sdk`
+* - Client function is `create${ServiceName}GraphQLClient`
+* - Endpoint has default value
+*/
+function generateOfetchTemplate(options) {
+	const { serviceName, isNuxt, endpoint, isExternal = false } = options;
+	if (isExternal) return generateExternalOfetchTemplate({
+		serviceName,
+		isNuxt,
+		endpoint
+	});
+	return generateMainOfetchTemplate({
+		isNuxt,
+		endpoint
+	});
+}
+/**
+* Generate ofetch template for main (default) GraphQL service
+*/
+function generateMainOfetchTemplate(options) {
+	const { isNuxt, endpoint } = options;
+	if (isNuxt) return `// This file is auto-generated once by nitro-graphql for quick start
+// You can modify this file according to your needs
+import type { Requester } from './sdk'
+import { getSdk } from './sdk'
+
+export function createGraphQLClient(endpoint: string): Requester {
+  return async <R>(doc: string, vars?: any): Promise<R> => {
+    const headers = import.meta.server ? useRequestHeaders() : undefined
+
+    const result = await $fetch(endpoint, {
+      method: 'POST',
+      body: { query: doc, variables: vars },
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers,
+      },
+    })
+
+    return result as R
+  }
+}
+
+export const $sdk = getSdk(createGraphQLClient('${endpoint}'))`;
+	return `// This file is auto-generated once by nitro-graphql for quick start
+// You can modify this file according to your needs
+import type { Requester } from './sdk'
+import { ofetch } from 'ofetch'
+import { getSdk } from './sdk'
+
+export function createGraphQLClient(endpoint: string): Requester {
+  return async <R>(doc: string, vars?: any): Promise<R> => {
+    const result = await ofetch(endpoint, {
+      method: 'POST',
+      body: { query: doc, variables: vars },
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    })
+
+    return result as R
+  }
+}
+
+export const $sdk = getSdk(createGraphQLClient('${endpoint}'))`;
+}
+/**
+* Generate ofetch template for external GraphQL service
+*/
+function generateExternalOfetchTemplate(options) {
+	const { serviceName, isNuxt, endpoint } = options;
+	const capitalizedName = capitalize(serviceName);
+	if (isNuxt) return `// This file is auto-generated once by nitro-graphql for quick start
+// You can modify this file according to your needs
+import type { Sdk, Requester } from './sdk'
+import { getSdk } from './sdk'
+
+export function create${capitalizedName}GraphQLClient(endpoint: string = '${endpoint}'): Requester {
+  return async <R>(doc: string, vars?: any): Promise<R> => {
+    const headers = import.meta.server ? useRequestHeaders() : undefined
+
+    const result = await $fetch(endpoint, {
+      method: 'POST',
+      body: { query: doc, variables: vars },
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers,
+      },
+    })
+
+    return result as R
+  }
+}
+
+export const $${serviceName}Sdk: Sdk = getSdk(create${capitalizedName}GraphQLClient())`;
+	return `// This file is auto-generated once by nitro-graphql for quick start
+// You can modify this file according to your needs
+import type { Sdk, Requester } from './sdk'
+import { ofetch } from 'ofetch'
+import { getSdk } from './sdk'
+
+export function create${capitalizedName}GraphQLClient(endpoint: string = '${endpoint}'): Requester {
+  return async <R>(doc: string, vars?: any): Promise<R> => {
+    const result = await ofetch(endpoint, {
+      method: 'POST',
+      body: { query: doc, variables: vars },
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    })
+
+    return result as R
+  }
+}
+
+export const $${serviceName}Sdk: Sdk = getSdk(create${capitalizedName}GraphQLClient())`;
+}
+
+//#endregion
+export { generateOfetchTemplate };

package/dist/core/validation/external-services.d.mts

@@ -0,0 +1,11 @@
+//#region src/core/validation/external-services.d.ts
+/**
+ * External services validation utilities
+ * Framework-agnostic validation helpers
+ */
+/**
+ * Validate external GraphQL service configuration
+ */
+declare function validateExternalServices(services: unknown[]): string[];
+//#endregion
+export { validateExternalServices };

package/dist/core/validation/external-services.mjs

@@ -0,0 +1,34 @@
+//#region src/core/validation/external-services.ts
+/**
+* External services validation utilities
+* Framework-agnostic validation helpers
+*/
+/**
+* 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 || typeof service !== "object") {
+			errors.push(`${prefix} must be an object`);
+			continue;
+		}
+		if (!("name" in service) || 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 (!("schema" in service) || !service.schema) errors.push(`${prefix}.schema is required`);
+		if (!("endpoint" in service) || typeof service.endpoint !== "string") errors.push(`${prefix}.endpoint is required and must be a string`);
+		else try {
+			new URL(service.endpoint);
+		} catch {
+			errors.push(`${prefix}.endpoint "${service.endpoint}" must be a valid URL`);
+		}
+		if ("name" in service && service.name && typeof service.name === "string" && !/^[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;
+}
+
+//#endregion
+export { validateExternalServices };

package/dist/core/validation/index.d.mts

@@ -0,0 +1,2 @@
+import { validateExternalServices } from "./external-services.mjs";
+export { validateExternalServices };

package/dist/core/validation/index.mjs

@@ -0,0 +1,3 @@
+import { validateExternalServices } from "./external-services.mjs";
+
+export { validateExternalServices };