@nitronjs/framework 0.1.0

package/lib/Validation/Validator.js

@@ -0,0 +1,691 @@
+import { MIME_TYPES } from "./MimeTypes.js";
+
+/**
+ * Laravel-style Validator for NitronJS
+ * 
+ * BEHAVIOR:
+ * - All rules are OPTIONAL by default (skip validation for absent values)
+ * - Use "required" to make a field mandatory
+ * - Use "nullable" to explicitly allow null (skips ALL validation)
+ * 
+ * SECURITY WARNING:
+ * File validation (mimes, mime_types) checks MIME headers only.
+ * This is NOT secure - attackers can spoof MIME types.
+ * Always verify file signatures (magic bytes) server-side before storage.
+ * 
+ * UNITS:
+ * - min/max for files: BYTES (e.g., max:2097152 = 2MB)
+ * - min/max for strings: characters
+ * - min/max for arrays: item count
+ * - min/max for numbers: numeric value
+ */
+class Validator {
+    #data;
+    #rules;
+    #customMessages;
+    #errors = {};
+
+    static #MIME_TYPES = MIME_TYPES;
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PUBLIC API
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Create validator and run validation
+     * 
+     * @param {Object} data - Request data to validate
+     * @param {Object} rules - Validation rules per field
+     * @param {Object} customMessages - Optional custom error messages
+     */
+    static make(data, rules, customMessages = {}) {
+        const validator = new Validator();
+
+        validator.#data = this.#normalizeBracketNotation(data);
+        validator.#rules = rules;
+        validator.#customMessages = customMessages;
+        validator.#runValidation();
+
+        return validator;
+    }
+
+    /**
+     * Convert bracket notation keys to nested object structure
+     * Example: { "users[0][name]": "John" } → { users: [{ name: "John" }] }
+     */
+    static #normalizeBracketNotation(data) {
+        if (!data || typeof data !== "object") {
+            return data;
+        }
+
+        const hasBrackets = Object.keys(data).some(key => key.includes("["));
+        if (!hasBrackets) {
+            return data;
+        }
+
+        const result = {};
+
+        for (const [key, value] of Object.entries(data)) {
+            if (!key.includes("[")) {
+                result[key] = value;
+                continue;
+            }
+
+            const parts = key.replace(/\]/g, "").split("[");
+            let current = result;
+
+            for (let i = 0; i < parts.length - 1; i++) {
+                const part = parts[i];
+                const nextPart = parts[i + 1];
+                const isNextIndex = /^\d+$/.test(nextPart);
+
+                if (current[part] === undefined) {
+                    current[part] = isNextIndex ? [] : {};
+                }
+
+                current = current[part];
+            }
+
+            const lastPart = parts[parts.length - 1];
+            current[lastPart] = value;
+        }
+
+        return result;
+    }
+
+    /** Check if validation failed */
+    fails() {
+        return Object.keys(this.#errors).length > 0;
+    }
+
+    /** Check if validation passed */
+    passes() {
+        return !this.fails();
+    }
+
+    /** Get all errors (returns immutable copy) */
+    errors() {
+        return JSON.parse(JSON.stringify(this.#errors));
+    }
+
+    /** Get first error for a specific field */
+    first(field) {
+        return this.#errors[field]?.[0] || null;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // HELPER METHODS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Check if value is absent (undefined, null, or empty string)
+     * Used to skip optional field validation
+     */
+    #isAbsent(value) {
+        return value === undefined || value === null || value === "";
+    }
+
+    /**
+     * Extract file information from Frontend File/Blob or Backend Multipart
+     * Returns null if not a valid file object
+     * 
+     * @returns {{ mime: string, size: number | null } | null}
+     */
+    #getFileInfo(value) {
+        if (!value || typeof value !== "object") {
+            return null;
+        }
+
+        // Backend Multipart (Fastify @fastify/multipart)
+        if (typeof value.mimetype === "string" && typeof value.toBuffer === "function") {
+            return {
+                mime: value.mimetype.toLowerCase(),
+                size: value._buf?.length ?? null
+            };
+        }
+
+        // Frontend File/Blob (Browser API)
+        if (typeof value.type === "string" && value.type.includes("/") && typeof value.size === "number") {
+            return {
+                mime: value.type.toLowerCase(),
+                size: value.size
+            };
+        }
+
+        return null;
+    }
+
+    /**
+     * Format bytes to human-readable string
+     */
+    #formatBytes(bytes) {
+        if (bytes < 1024) return `${bytes} bytes`;
+        if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+        return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CORE VALIDATION ENGINE
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Run all validations
+     * Handles both regular fields and wildcard patterns
+     */
+    #runValidation() {
+        for (const [pattern, rulesString] of Object.entries(this.#rules)) {
+            if (pattern.includes("*")) {
+                this.#validateWildcard(pattern, rulesString);
+            } else {
+                this.#validateField(pattern, this.#data[pattern], rulesString);
+            }
+        }
+    }
+
+    /**
+     * Validate a single field against its rules
+     * Short-circuits on first failure for better UX
+     */
+    #validateField(field, value, rulesString) {
+        const rules = rulesString.split("|").map(r => r.trim());
+
+        // Nullable + null = skip ALL validation (including required)
+        if (rules.includes("nullable") && value === null) {
+            return;
+        }
+
+        for (const rule of rules) {
+            const result = this.#applyRule(field, value, rule);
+
+            if (!result.passes) {
+                // Initialize error array if needed
+                if (!this.#errors[field]) {
+                    this.#errors[field] = [];
+                }
+
+                this.#errors[field].push(result.message);
+
+                // Short-circuit: stop on first failure
+                break;
+            }
+        }
+    }
+
+    /**
+     * Validate wildcard patterns (e.g., users.*.email)
+     * Expands pattern to actual paths and validates each
+     */
+    #validateWildcard(pattern, rulesString) {
+        const paths = this.#expandWildcard(pattern);
+
+        for (const path of paths) {
+            const value = this.#getNestedValue(path);
+
+            // Format error key: users.0.email → users[0].email
+            const errorKey = path.replace(/\.(\d+)/g, '[$1]');
+
+            this.#validateField(errorKey, value, rulesString);
+        }
+    }
+
+    /**
+     * Expand wildcard pattern to actual array indices
+     * Example: users.*.email → [users.0.email, users.1.email, ...]
+     */
+    #expandWildcard(pattern) {
+        const parts = pattern.split(".");
+        let paths = [""];
+
+        for (const part of parts) {
+            const newPaths = [];
+
+            for (const current of paths) {
+                if (part === "*") {
+                    const arr = current ? this.#getNestedValue(current) : this.#data;
+
+                    if (Array.isArray(arr)) {
+                        for (let i = 0; i < arr.length; i++) {
+                            const newPath = current ? `${current}.${i}` : String(i);
+                            newPaths.push(newPath);
+                        }
+                    }
+                } else {
+                    const newPath = current ? `${current}.${part}` : part;
+                    newPaths.push(newPath);
+                }
+            }
+
+            paths = newPaths;
+        }
+
+        return paths;
+    }
+
+    /**
+     * Get value from nested object path
+     * Example: "users.0.email" → data.users[0].email
+     */
+    #getNestedValue(path) {
+        return path.split(".").reduce((obj, key) => obj?.[key], this.#data);
+    }
+
+    /**
+     * Apply a single validation rule
+     * Handles rule parsing, execution, and custom messages
+     */
+    #applyRule(field, value, rule) {
+        // Parse rule: "min:3" → name="min", params=["3"]
+        const [name, ...paramParts] = rule.split(":");
+        const params = paramParts.length ? paramParts.join(":").split(",") : [];
+
+        const handler = this.#ruleHandlers[name];
+
+        // Unknown rule = developer error, fail fast
+        if (!handler) {
+            throw new Error(`Unknown validation rule: "${name}". Check your rule definitions.`);
+        }
+
+        const result = handler.call(this, value, params, field);
+
+        // Apply custom messages (field-specific > global > default)
+        if (!result.passes) {
+            const fieldSpecificKey = `${field}.${name}`;
+
+            if (this.#customMessages[fieldSpecificKey]) {
+                result.message = this.#customMessages[fieldSpecificKey];
+            } else if (this.#customMessages[name]) {
+                result.message = this.#customMessages[name];
+            }
+        }
+
+        return result;
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // VALIDATION RULES
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    #ruleHandlers = {
+
+        // ─── Presence Rules ──────────────────────────────────────────────────
+
+        /** Field must exist and not be empty/whitespace */
+        required: (value, params, field) => {
+            const isEmpty = value === null || 
+                           value === undefined || 
+                           value === "" || 
+                           (typeof value === "string" && value.trim() === "");
+
+            return {
+                passes: !isEmpty,
+                message: `The ${field} field is required.`
+            };
+        },
+
+        /** Allow null to skip all validation */
+        nullable: () => {
+            return { passes: true, message: "" };
+        },
+
+        // ─── Type Rules ──────────────────────────────────────────────────────
+
+        /** Must be a string */
+        string: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            return {
+                passes: typeof value === "string",
+                message: `The ${field} field must be a string.`
+            };
+        },
+
+        /** Must be an array or object */
+        array: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            const isArrayOrObject = Array.isArray(value) || 
+                                    (value !== null && typeof value === "object");
+
+            return {
+                passes: isArrayOrObject,
+                message: `The ${field} field must be an array.`
+            };
+        },
+
+        /** Must be numeric (integer or decimal) */
+        numeric: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            const passes = /^-?\d+(\.\d+)?$/.test(String(value).trim());
+
+            return {
+                passes,
+                message: `The ${field} field must be numeric.`
+            };
+        },
+
+        /** Must be an integer */
+        integer: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            const passes = /^-?\d+$/.test(String(value).trim());
+
+            return {
+                passes,
+                message: `The ${field} field must be an integer.`
+            };
+        },
+
+        /** Must be boolean-like (true/false/1/0/"on"/"off") */
+        boolean: (value, params, field) => {
+            const booleanValues = [true, false, "true", "false", 1, 0, "1", "0", "on", "off"];
+
+            return {
+                passes: booleanValues.includes(value),
+                message: `The ${field} field must be true or false.`
+            };
+        },
+
+        // ─── Format Rules ────────────────────────────────────────────────────
+
+        /** Must be valid email format */
+        email: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            const passes = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+
+            return {
+                passes,
+                message: `The ${field} field must be a valid email address.`
+            };
+        },
+
+        /** Must be valid URL */
+        url: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            try {
+                new URL(value);
+                return { passes: true, message: "" };
+            } catch {
+                return {
+                    passes: false,
+                    message: `The ${field} field must be a valid URL.`
+                };
+            }
+        },
+
+        /** Only letters (a-z, A-Z) */
+        alpha: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            return {
+                passes: /^[a-zA-Z]+$/.test(value),
+                message: `The ${field} field must contain only letters.`
+            };
+        },
+
+        /** Only letters and numbers */
+        alpha_num: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            return {
+                passes: /^[a-zA-Z0-9]+$/.test(value),
+                message: `The ${field} field must contain only letters and numbers.`
+            };
+        },
+
+        /** Letters, numbers, dashes, underscores (good for slugs/usernames) */
+        alpha_dash: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            return {
+                passes: /^[a-zA-Z0-9_-]+$/.test(value),
+                message: `The ${field} field must contain only letters, numbers, dashes and underscores.`
+            };
+        },
+
+        // ─── Comparison Rules ────────────────────────────────────────────────
+
+        /** Must be in allowed list. Usage: in:admin,user,guest */
+        in: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            return {
+                passes: params.includes(String(value)),
+                message: `The ${field} field must be one of: ${params.join(", ")}.`
+            };
+        },
+
+        /** Must match {field}_confirmation */
+        confirmed: (value, params, field) => {
+            const confirmationField = `${field}_confirmation`;
+            const passes = value === this.#data[confirmationField];
+
+            return {
+                passes,
+                message: `The ${field} confirmation does not match.`
+            };
+        },
+
+        // ─── Size Rules ──────────────────────────────────────────────────────
+
+        /**
+         * Minimum size/length/value
+         * - Arrays: minimum item count
+         * - Strings: minimum character count
+         * - Files: minimum size in BYTES
+         * - Numbers: minimum value
+         */
+        min: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            const min = parseFloat(params[0]);
+
+            // Array: item count
+            if (Array.isArray(value)) {
+                return {
+                    passes: value.length >= min,
+                    message: `The ${field} must have at least ${min} items.`
+                };
+            }
+
+            // Object: property count
+            if (value !== null && typeof value === "object") {
+                const keyCount = Object.keys(value).length;
+                return {
+                    passes: keyCount >= min,
+                    message: `The ${field} must have at least ${min} items.`
+                };
+            }
+
+            // File: size in bytes
+            const file = this.#getFileInfo(value);
+            if (file && file.size !== null) {
+                return {
+                    passes: file.size >= min,
+                    message: `The ${field} file must be at least ${this.#formatBytes(min)}.`
+                };
+            }
+
+            // String: character count
+            if (typeof value === "string") {
+                return {
+                    passes: value.length >= min,
+                    message: `The ${field} field must be at least ${min} characters.`
+                };
+            }
+
+            // Number: numeric value
+            if (!isNaN(value)) {
+                return {
+                    passes: parseFloat(value) >= min,
+                    message: `The ${field} field must be at least ${min}.`
+                };
+            }
+
+            return {
+                passes: false,
+                message: `The ${field} field cannot be validated with min rule.`
+            };
+        },
+
+        /**
+         * Maximum size/length/value
+         * - Arrays: maximum item count
+         * - Strings: maximum character count
+         * - Files: maximum size in BYTES
+         * - Numbers: maximum value
+         */
+        max: (value, params, field) => {
+            if (this.#isAbsent(value)) {
+                return { passes: true, message: "" };
+            }
+
+            const max = parseFloat(params[0]);
+
+            // Array: item count
+            if (Array.isArray(value)) {
+                return {
+                    passes: value.length <= max,
+                    message: `The ${field} must not have more than ${max} items.`
+                };
+            }
+
+            // Object: property count
+            if (value !== null && typeof value === "object") {
+                const keyCount = Object.keys(value).length;
+                return {
+                    passes: keyCount <= max,
+                    message: `The ${field} must not have more than ${max} items.`
+                };
+            }
+
+            // File: size in bytes
+            const file = this.#getFileInfo(value);
+            if (file && file.size !== null) {
+                return {
+                    passes: file.size <= max,
+                    message: `The ${field} file must not exceed ${this.#formatBytes(max)}.`
+                };
+            }
+
+            // String: character count
+            if (typeof value === "string") {
+                return {
+                    passes: value.length <= max,
+                    message: `The ${field} field must not exceed ${max} characters.`
+                };
+            }
+
+            // Number: numeric value
+            if (!isNaN(value)) {
+                return {
+                    passes: parseFloat(value) <= max,
+                    message: `The ${field} field must not exceed ${max}.`
+                };
+            }
+
+            return {
+                passes: false,
+                message: `The ${field} field cannot be validated with max rule.`
+            };
+        },
+
+        // ─── File Rules ──────────────────────────────────────────────────────
+        // ⚠️ WARNING: These rules check MIME headers only, which can be spoofed.
+        // Always verify file signatures (magic bytes) server-side!
+
+        /** Must be a valid file object */
+        file: (value, params, field) => {
+            if (value === undefined || value === null) {
+                return { passes: true, message: "" };
+            }
+
+            return {
+                passes: this.#getFileInfo(value) !== null,
+                message: `The ${field} must be a file.`
+            };
+        },
+
+        /** File must have allowed MIME type. Usage: mime_types:image/jpeg,image/png */
+        mime_types: (value, params, field) => {
+            if (value === undefined || value === null) {
+                return { passes: true, message: "" };
+            }
+
+            const file = this.#getFileInfo(value);
+
+            if (!file) {
+                return {
+                    passes: false,
+                    message: `The ${field} must be a valid file.`
+                };
+            }
+
+            const allowed = params.map(m => m.trim().toLowerCase());
+
+            return {
+                passes: allowed.includes(file.mime),
+                message: `The ${field} file must be one of the following types: ${allowed.join(", ")}.`
+            };
+        },
+
+        /** File must have allowed extension. Usage: mimes:png,jpg,pdf */
+        mimes: (value, params, field) => {
+            if (value === undefined || value === null) {
+                return { passes: true, message: "" };
+            }
+
+            const file = this.#getFileInfo(value);
+
+            if (!file) {
+                return {
+                    passes: false,
+                    message: `The ${field} must be a valid file.`
+                };
+            }
+
+            // Convert extensions to MIME types
+            const allowed = params
+                .map(ext => Validator.#MIME_TYPES[ext.trim().toLowerCase()])
+                .filter(Boolean);
+
+            if (allowed.length === 0) {
+                return {
+                    passes: false,
+                    message: `Invalid file extensions provided for ${field}.`
+                };
+            }
+
+            return {
+                passes: allowed.includes(file.mime),
+                message: `The ${field} file must be one of: ${params.join(", ")}.`
+            };
+        }
+    };
+}
+
+export default Validator;