vite-plugin-server-actions 1.0.1 → 1.2.0

package/src/dev-validator.js

@@ -0,0 +1,272 @@
+/**
+ * Development-time validation and feedback system
+ * Provides real-time feedback to developers about their server actions
+ */
+
+import { createDevelopmentWarning, generateHelpfulSuggestions } from "./error-enhancer.js";
+
+/**
+ * Validate function parameters and provide feedback
+ * @param {Object} func - Function information from AST
+ * @param {string} filePath - File path for context
+ * @returns {Array<string>} - Array of validation warnings
+ */
+export function validateFunctionSignature(func, filePath) {
+	const warnings = [];
+
+	// Check for proper parameter typing
+	if (func.params && func.params.length > 0) {
+		const untypedParams = func.params.filter((param) => !param.type);
+
+		if (untypedParams.length > 0) {
+			warnings.push(
+				createDevelopmentWarning(
+					"Missing Type Annotations",
+					`Parameters ${untypedParams.map((p) => p.name).join(", ")} in '${func.name}' lack type annotations`,
+					{
+						filePath,
+						suggestion: "Add TypeScript types for better development experience and type safety",
+					},
+				),
+			);
+		}
+	}
+
+	// Check for proper return type annotation
+	if (!func.returnType && func.isAsync) {
+		warnings.push(
+			createDevelopmentWarning(
+				"Missing Return Type",
+				`Async function '${func.name}' should have a return type annotation`,
+				{
+					filePath,
+					suggestion: "Add return type like: Promise<MyReturnType>",
+				},
+			),
+		);
+	}
+
+	// Check for JSDoc documentation
+	if (!func.jsdoc) {
+		warnings.push(
+			createDevelopmentWarning("Missing Documentation", `Function '${func.name}' lacks JSDoc documentation`, {
+				filePath,
+				suggestion: "Add JSDoc comments to document what this function does",
+			}),
+		);
+	}
+
+	// Check for complex parameter patterns that might be hard to serialize
+	if (func.params) {
+		const complexParams = func.params.filter((param) => param.name.includes("{") || param.name.includes("["));
+
+		if (complexParams.length > 0) {
+			warnings.push(
+				createDevelopmentWarning(
+					"Complex Parameter Destructuring",
+					`Function '${func.name}' uses complex destructuring that might be hard to serialize`,
+					{
+						filePath,
+						suggestion: "Consider using simple parameters and destructure inside the function",
+					},
+				),
+			);
+		}
+	}
+
+	return warnings;
+}
+
+/**
+ * Validate server action file structure
+ * @param {Array} functionDetails - Array of function details
+ * @param {string} filePath - File path for context
+ * @returns {Array<string>} - Array of validation warnings
+ */
+export function validateFileStructure(functionDetails, filePath) {
+	const warnings = [];
+
+	// Check if file has any functions
+	if (functionDetails.length === 0) {
+		warnings.push(
+			createDevelopmentWarning("No Functions Found", "No exported functions found in server action file", {
+				filePath,
+				suggestion: "Make sure to export your functions: export async function myFunction() {}",
+			}),
+		);
+		return warnings;
+	}
+
+	// Check for too many functions in one file
+	if (functionDetails.length > 10) {
+		warnings.push(
+			createDevelopmentWarning(
+				"Large File",
+				`File contains ${functionDetails.length} functions. Consider splitting into smaller modules`,
+				{
+					filePath,
+					suggestion: "Group related functions and split into multiple .server.js files",
+				},
+			),
+		);
+	}
+
+	// Check for naming consistency
+	const functionNames = functionDetails.map((fn) => fn.name);
+	const hasInconsistentNaming = checkNamingConsistency(functionNames);
+
+	if (hasInconsistentNaming) {
+		warnings.push(
+			createDevelopmentWarning("Inconsistent Naming", "Function names use inconsistent naming patterns", {
+				filePath,
+				suggestion: "Use consistent naming: camelCase (getUserById) or snake_case (get_user_by_id)",
+			}),
+		);
+	}
+
+	return warnings;
+}
+
+/**
+ * Validate function arguments at runtime (development only)
+ * @param {string} functionName - Name of the function being called
+ * @param {Array} args - Arguments being passed
+ * @param {Object} functionInfo - Function metadata
+ * @returns {Array<string>} - Array of validation warnings
+ */
+export function validateRuntimeArguments(functionName, args, functionInfo) {
+	const warnings = [];
+
+	if (process.env.NODE_ENV !== "development") {
+		return warnings; // Only validate in development
+	}
+
+	// Check argument count
+	if (functionInfo && functionInfo.params) {
+		const requiredParams = functionInfo.params.filter((p) => !p.isOptional && !p.isRest);
+		const maxParams = functionInfo.params.filter((p) => !p.isRest).length;
+
+		if (args.length < requiredParams.length) {
+			warnings.push(
+				`Function '${functionName}' expects at least ${requiredParams.length} arguments, got ${args.length}`,
+			);
+		}
+
+		if (args.length > maxParams && !functionInfo.params.some((p) => p.isRest)) {
+			warnings.push(`Function '${functionName}' expects at most ${maxParams} arguments, got ${args.length}`);
+		}
+	}
+
+	// Check for non-serializable arguments
+	args.forEach((arg, index) => {
+		if (typeof arg === "function") {
+			warnings.push(`Argument ${index + 1} is a function and cannot be serialized`);
+		} else if (arg instanceof Date) {
+			warnings.push(`Argument ${index + 1} is a Date object. Consider passing as ISO string`);
+		} else if (arg instanceof RegExp) {
+			warnings.push(`Argument ${index + 1} is a RegExp and cannot be serialized`);
+		} else if (arg && typeof arg === "object" && arg.constructor !== Object && !Array.isArray(arg)) {
+			warnings.push(`Argument ${index + 1} is a custom object instance that may not serialize properly`);
+		}
+	});
+
+	return warnings;
+}
+
+/**
+ * Generate development-time type information
+ * @param {Object} functionInfo - Function information
+ * @returns {string} - TypeScript-like type definition
+ */
+export function generateTypeInfo(functionInfo) {
+	const { name, params, returnType, isAsync } = functionInfo;
+
+	const paramStrings = params.map((param) => {
+		let paramStr = param.name;
+		if (param.type) {
+			paramStr += `: ${param.type}`;
+		}
+		if (param.defaultValue) {
+			paramStr += ` = ${param.defaultValue}`;
+		}
+		return paramStr;
+	});
+
+	const returnTypeStr = returnType || "any";
+	const finalReturnType = isAsync ? `Promise<${returnTypeStr}>` : returnTypeStr;
+
+	return `function ${name}(${paramStrings.join(", ")}): ${finalReturnType}`;
+}
+
+/**
+ * Check naming consistency across functions
+ * @param {Array<string>} functionNames - Array of function names
+ * @returns {boolean} - True if naming is inconsistent
+ */
+function checkNamingConsistency(functionNames) {
+	if (functionNames.length < 2) return false;
+
+	const camelCaseCount = functionNames.filter((name) => /^[a-z][a-zA-Z0-9]*$/.test(name)).length;
+	const snakeCaseCount = functionNames.filter((name) => /^[a-z][a-z0-9_]*$/.test(name) && name.includes("_")).length;
+	const pascalCaseCount = functionNames.filter((name) => /^[A-Z][a-zA-Z0-9]*$/.test(name)).length;
+
+	// If multiple naming styles are used significantly, it's inconsistent
+	const styles = [camelCaseCount, snakeCaseCount, pascalCaseCount].filter((count) => count > 0);
+	return styles.length > 1 && Math.max(...styles) < functionNames.length * 0.8;
+}
+
+/**
+ * Create development feedback for the console
+ * @param {Object} serverFunctions - Map of server functions
+ * @returns {string} - Formatted feedback message
+ */
+export function createDevelopmentFeedback(serverFunctions) {
+	let feedback = "\n[Vite Server Actions] 📋 Development Feedback:\n";
+
+	const totalFunctions = Array.from(serverFunctions.values()).reduce(
+		(sum, module) => sum + (module.functions?.length || 0),
+		0,
+	);
+
+	feedback += `  📊 Found ${totalFunctions} server actions across ${serverFunctions.size} modules\n`;
+
+	// List modules and their functions
+	for (const [moduleName, moduleInfo] of serverFunctions) {
+		const { functions, filePath } = moduleInfo;
+		feedback += `  📁 ${filePath}: ${functions.join(", ")}\n`;
+	}
+
+	feedback += "\n  💡 Tips:\n";
+	feedback += "    • Add TypeScript types for better IntelliSense\n";
+	feedback += "    • Use Zod schemas for runtime validation\n";
+	feedback += "    • Keep functions focused and well-documented\n";
+
+	return feedback;
+}
+
+/**
+ * Validate Zod schema attachment
+ * @param {Object} moduleExports - Exported module
+ * @param {Array} functionNames - Array of function names
+ * @param {string} filePath - File path for context
+ * @returns {Array<string>} - Array of validation suggestions
+ */
+export function validateSchemaAttachment(moduleExports, functionNames, filePath) {
+	const suggestions = [];
+
+	functionNames.forEach((funcName) => {
+		const func = moduleExports[funcName];
+		if (func && typeof func === "function") {
+			if (!func.schema) {
+				suggestions.push(
+					createDevelopmentWarning("Missing Validation Schema", `Function '${funcName}' has no attached Zod schema`, {
+						filePath,
+						suggestion: `Add: ${funcName}.schema = z.object({ /* your schema */ });`,
+					}),
+				);
+			}
+		}
+	});
+
+	return suggestions;
+}

package/src/error-enhancer.js

@@ -0,0 +1,283 @@
+/**
+ * Enhanced error handling with context and suggestions
+ * Provides developer-friendly error messages with actionable suggestions
+ */
+
+/**
+ * Create an enhanced error message with context and suggestions
+ * @param {string} errorType - Type of error
+ * @param {string} originalMessage - Original error message
+ * @param {Object} context - Error context information
+ * @returns {string}
+ */
+export function createEnhancedError(errorType, originalMessage, context = {}) {
+	const { filePath, functionName, availableFunctions, suggestion } = context;
+
+	let enhancedMessage = `[Vite Server Actions] ${errorType}: ${originalMessage}`;
+
+	if (filePath) {
+		enhancedMessage += `\n  📁 File: ${filePath}`;
+	}
+
+	if (functionName) {
+		enhancedMessage += `\n  🔧 Function: ${functionName}`;
+	}
+
+	if (availableFunctions && availableFunctions.length > 0) {
+		enhancedMessage += `\n  📋 Available functions: ${availableFunctions.join(", ")}`;
+	}
+
+	if (suggestion) {
+		enhancedMessage += `\n  💡 Suggestion: ${suggestion}`;
+	}
+
+	return enhancedMessage;
+}
+
+/**
+ * Enhance function not found errors
+ * @param {string} functionName - The function that wasn't found
+ * @param {string} moduleName - Module where function was expected
+ * @param {Array} availableFunctions - List of available functions
+ * @returns {Object}
+ */
+export function enhanceFunctionNotFoundError(functionName, moduleName, availableFunctions = []) {
+	const suggestions = [];
+
+	// Check for similar function names (typos)
+	const similarFunctions = availableFunctions.filter((fn) => levenshteinDistance(fn, functionName) <= 2);
+
+	if (similarFunctions.length > 0) {
+		suggestions.push(`Did you mean: ${similarFunctions.join(", ")}?`);
+	}
+
+	// Check for common naming patterns
+	const namingPatterns = [
+		{ pattern: /^get/, suggestion: "For data fetching, consider: fetch, load, or retrieve" },
+		{ pattern: /^create/, suggestion: "For creation, consider: add, insert, or save" },
+		{ pattern: /^update/, suggestion: "For updates, consider: edit, modify, or change" },
+		{ pattern: /^delete/, suggestion: "For deletion, consider: remove, destroy, or clear" },
+	];
+
+	const matchingPattern = namingPatterns.find((p) => p.pattern.test(functionName));
+	if (matchingPattern) {
+		suggestions.push(matchingPattern.suggestion);
+	}
+
+	if (availableFunctions.length === 0) {
+		suggestions.push("No functions are exported from this module. Make sure to export your functions.");
+	}
+
+	return {
+		message: createEnhancedError(
+			"Function Not Found",
+			`Function '${functionName}' not found in module '${moduleName}'`,
+			{
+				functionName,
+				availableFunctions,
+				suggestion: suggestions.join(" "),
+			},
+		),
+		code: "FUNCTION_NOT_FOUND",
+		suggestions,
+	};
+}
+
+/**
+ * Enhance AST parsing errors
+ * @param {string} filePath - File that failed to parse
+ * @param {Error} originalError - Original parsing error
+ * @returns {Object}
+ */
+export function enhanceParsingError(filePath, originalError) {
+	const suggestions = [];
+
+	if (originalError.message.includes("Unexpected token")) {
+		suggestions.push("Check for syntax errors in your server action file");
+		suggestions.push("Ensure all functions are properly exported");
+	}
+
+	if (originalError.message.includes("Identifier")) {
+		suggestions.push("Function names must be valid JavaScript identifiers");
+		suggestions.push("Function names cannot start with numbers or contain special characters");
+	}
+
+	if (originalError.message.includes("duplicate")) {
+		suggestions.push("Each function name must be unique within the same file");
+		suggestions.push("Consider renaming duplicate functions or using different export patterns");
+	}
+
+	return {
+		message: createEnhancedError("Parsing Error", `Failed to parse server action file: ${originalError.message}`, {
+			filePath,
+			suggestion: suggestions.join(" "),
+		}),
+		code: "PARSE_ERROR",
+		suggestions,
+	};
+}
+
+/**
+ * Enhance validation errors
+ * @param {Array} validationErrors - Array of validation errors
+ * @param {string} functionName - Function that failed validation
+ * @returns {Object}
+ */
+export function enhanceValidationError(validationErrors, functionName) {
+	const suggestions = [];
+
+	// Analyze common validation patterns
+	const hasTypeErrors = validationErrors.some(
+		(err) => err.message.includes("Expected") || err.message.includes("Invalid"),
+	);
+
+	if (hasTypeErrors) {
+		suggestions.push("Check the types of arguments you're passing to the function");
+	}
+
+	const hasRequiredErrors = validationErrors.some(
+		(err) => err.message.includes("required") || err.message.includes("missing"),
+	);
+
+	if (hasRequiredErrors) {
+		suggestions.push("Make sure all required parameters are provided");
+	}
+
+	const hasFormatErrors = validationErrors.some(
+		(err) => err.message.includes("format") || err.message.includes("pattern"),
+	);
+
+	if (hasFormatErrors) {
+		suggestions.push("Check the format of string inputs (email, URL, etc.)");
+	}
+
+	return {
+		message: createEnhancedError("Validation Error", `Validation failed for function '${functionName}'`, {
+			functionName,
+			suggestion: suggestions.join(" "),
+		}),
+		code: "VALIDATION_ERROR",
+		suggestions,
+	};
+}
+
+/**
+ * Enhance module loading errors
+ * @param {string} modulePath - Path to module that failed to load
+ * @param {Error} originalError - Original loading error
+ * @returns {Object}
+ */
+export function enhanceModuleLoadError(modulePath, originalError) {
+	const suggestions = [];
+
+	if (originalError.code === "ENOENT") {
+		suggestions.push("Make sure the file exists and the path is correct");
+		suggestions.push("Check that your build process hasn't moved or renamed the file");
+	}
+
+	if (originalError.message.includes("import")) {
+		suggestions.push("Verify all import statements in your server action file");
+		suggestions.push("Make sure imported modules are installed and available");
+	}
+
+	if (originalError.message.includes("export")) {
+		suggestions.push("Ensure your functions are properly exported");
+		suggestions.push("Use 'export function' or 'export const' for your server actions");
+	}
+
+	return {
+		message: createEnhancedError("Module Load Error", `Failed to load server action module: ${originalError.message}`, {
+			filePath: modulePath,
+			suggestion: suggestions.join(" "),
+		}),
+		code: "MODULE_LOAD_ERROR",
+		suggestions,
+	};
+}
+
+/**
+ * Enhance development warnings with helpful context
+ * @param {string} warningType - Type of warning
+ * @param {string} message - Warning message
+ * @param {Object} context - Additional context
+ * @returns {string}
+ */
+export function createDevelopmentWarning(warningType, message, context = {}) {
+	let warning = `[Vite Server Actions] ⚠️ ${warningType}: ${message}`;
+
+	if (context.filePath) {
+		warning += `\n  📁 File: ${context.filePath}`;
+	}
+
+	if (context.suggestion) {
+		warning += `\n  💡 Tip: ${context.suggestion}`;
+	}
+
+	return warning;
+}
+
+/**
+ * Calculate Levenshtein distance between two strings
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number}
+ */
+function levenshteinDistance(a, b) {
+	const matrix = [];
+
+	for (let i = 0; i <= b.length; i++) {
+		matrix[i] = [i];
+	}
+
+	for (let j = 0; j <= a.length; j++) {
+		matrix[0][j] = j;
+	}
+
+	for (let i = 1; i <= b.length; i++) {
+		for (let j = 1; j <= a.length; j++) {
+			if (b.charAt(i - 1) === a.charAt(j - 1)) {
+				matrix[i][j] = matrix[i - 1][j - 1];
+			} else {
+				matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+			}
+		}
+	}
+
+	return matrix[b.length][a.length];
+}
+
+/**
+ * Generate helpful suggestions based on common mistakes
+ * @param {string} errorContext - Context where error occurred
+ * @param {Object} additionalInfo - Additional information about the error
+ * @returns {Array<string>}
+ */
+export function generateHelpfulSuggestions(errorContext, additionalInfo = {}) {
+	const suggestions = [];
+
+	switch (errorContext) {
+		case "no-functions-found":
+			suggestions.push("Make sure your functions are exported: export async function myFunction() {}");
+			suggestions.push("Check that your file ends with .server.js or .server.ts");
+			suggestions.push("Verify the file is in a location matched by your include patterns");
+			break;
+
+		case "async-function-required":
+			suggestions.push("Server actions should be async functions");
+			suggestions.push("Change 'export function' to 'export async function'");
+			break;
+
+		case "invalid-arguments":
+			suggestions.push("All function arguments must be JSON-serializable");
+			suggestions.push("Functions, classes, and other complex objects cannot be passed");
+			suggestions.push("Consider passing plain objects, arrays, strings, and numbers only");
+			break;
+
+		case "type-safety":
+			suggestions.push("Add TypeScript types to your server actions for better development experience");
+			suggestions.push("Use Zod schemas for runtime validation");
+			break;
+	}
+
+	return suggestions;
+}