voltjs-framework 1.0.0

package/src/utils/string.js

@@ -0,0 +1,236 @@
+/**
+ * VoltJS StringHelper
+ * 
+ * String manipulation utilities.
+ * 
+ * @example
+ * const { StringHelper } = require('voltjs');
+ * 
+ * StringHelper.slug('Hello World!'); // 'hello-world'
+ * StringHelper.camelCase('user_first_name'); // 'userFirstName'
+ * StringHelper.truncate('Long text...', 10); // 'Long te...'
+ * StringHelper.random(16); // 'a8f3k2m9p1q4r7...'
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+class StringHelper {
+  /** Convert to URL-friendly slug */
+  static slug(str, separator = '-') {
+    return str
+      .toString()
+      .toLowerCase()
+      .normalize('NFD')
+      .replace(/[\u0300-\u036f]/g, '') // Remove accents
+      .replace(/[^a-z0-9\s-]/g, '')    // Remove non-alphanumeric
+      .replace(/[\s_]+/g, separator)    // Replace spaces/underscores
+      .replace(new RegExp(`${separator}+`, 'g'), separator) // Collapse separators
+      .replace(new RegExp(`^${separator}|${separator}$`, 'g'), ''); // Trim edges
+  }
+
+  /** camelCase */
+  static camelCase(str) {
+    return str
+      .replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : '')
+      .replace(/^./, c => c.toLowerCase());
+  }
+
+  /** PascalCase */
+  static pascalCase(str) {
+    const camel = StringHelper.camelCase(str);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+  }
+
+  /** snake_case */
+  static snakeCase(str) {
+    return str
+      .replace(/([a-z])([A-Z])/g, '$1_$2')
+      .replace(/[-\s]+/g, '_')
+      .toLowerCase();
+  }
+
+  /** kebab-case */
+  static kebabCase(str) {
+    return str
+      .replace(/([a-z])([A-Z])/g, '$1-$2')
+      .replace(/[_\s]+/g, '-')
+      .toLowerCase();
+  }
+
+  /** Title Case */
+  static titleCase(str) {
+    return str.replace(/\b\w/g, c => c.toUpperCase());
+  }
+
+  /** sentence case */
+  static sentenceCase(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+  }
+
+  /** Truncate with ellipsis */
+  static truncate(str, length = 100, suffix = '...') {
+    if (str.length <= length) return str;
+    return str.substring(0, length - suffix.length) + suffix;
+  }
+
+  /** Truncate words */
+  static truncateWords(str, count = 10, suffix = '...') {
+    const words = str.split(/\s+/);
+    if (words.length <= count) return str;
+    return words.slice(0, count).join(' ') + suffix;
+  }
+
+  /** Pad left */
+  static padLeft(str, length, char = ' ') {
+    return String(str).padStart(length, char);
+  }
+
+  /** Pad right */
+  static padRight(str, length, char = ' ') {
+    return String(str).padEnd(length, char);
+  }
+
+  /** Check if string contains substring (case-insensitive) */
+  static contains(str, substr) {
+    return str.toLowerCase().includes(substr.toLowerCase());
+  }
+
+  /** Check if string starts with (case-insensitive) */
+  static startsWith(str, prefix) {
+    return str.toLowerCase().startsWith(prefix.toLowerCase());
+  }
+
+  /** Check if string ends with (case-insensitive) */
+  static endsWith(str, suffix) {
+    return str.toLowerCase().endsWith(suffix.toLowerCase());
+  }
+
+  /** Count words */
+  static wordCount(str) {
+    return str.trim().split(/\s+/).filter(Boolean).length;
+  }
+
+  /** Count characters (excluding spaces) */
+  static charCount(str, excludeSpaces = false) {
+    return excludeSpaces ? str.replace(/\s/g, '').length : str.length;
+  }
+
+  /** Strip HTML tags */
+  static stripTags(html) {
+    return html.replace(/<[^>]*>/g, '');
+  }
+
+  /** Escape HTML entities */
+  static escapeHtml(str) {
+    const map = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#039;' };
+    return str.replace(/[&<>"']/g, c => map[c]);
+  }
+
+  /** Unescape HTML entities */
+  static unescapeHtml(str) {
+    const map = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#039;': "'" };
+    return str.replace(/&(amp|lt|gt|quot|#039);/g, m => map[m]);
+  }
+
+  /** Generate random string */
+  static random(length = 16, charset = 'alphanumeric') {
+    const charsets = {
+      alpha: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ',
+      numeric: '0123456789',
+      alphanumeric: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789',
+      hex: '0123456789abcdef',
+      all: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*',
+    };
+    const chars = charsets[charset] || charset;
+    const bytes = crypto.randomBytes(length);
+    let result = '';
+    for (let i = 0; i < length; i++) {
+      result += chars[bytes[i] % chars.length];
+    }
+    return result;
+  }
+
+  /** Reverse a string */
+  static reverse(str) {
+    return [...str].reverse().join('');
+  }
+
+  /** Repeat a string */
+  static repeat(str, count) {
+    return str.repeat(count);
+  }
+
+  /** Replace all occurrences */
+  static replaceAll(str, search, replacement) {
+    return str.split(search).join(replacement);
+  }
+
+  /** Extract between delimiters */
+  static between(str, start, end) {
+    const startIdx = str.indexOf(start);
+    if (startIdx === -1) return '';
+    const endIdx = str.indexOf(end, startIdx + start.length);
+    if (endIdx === -1) return '';
+    return str.substring(startIdx + start.length, endIdx);
+  }
+
+  /** Mask a string (for sensitive data) */
+  static mask(str, visibleStart = 0, visibleEnd = 4, maskChar = '*') {
+    if (str.length <= visibleStart + visibleEnd) return str;
+    const start = str.substring(0, visibleStart);
+    const end = str.substring(str.length - visibleEnd);
+    const middle = maskChar.repeat(str.length - visibleStart - visibleEnd);
+    return start + middle + end;
+  }
+
+  /** Convert bytes to human-readable size */
+  static fileSize(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let i = 0;
+    let size = bytes;
+    while (size >= 1024 && i < units.length - 1) {
+      size /= 1024;
+      i++;
+    }
+    return `${size.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+  }
+
+  /** Convert number to ordinal: 1 -> "1st" */
+  static ordinal(n) {
+    const s = ['th', 'st', 'nd', 'rd'];
+    const v = n % 100;
+    return n + (s[(v - 20) % 10] || s[v] || s[0]);
+  }
+
+  /** Pluralize a word (simple English rules) */
+  static pluralize(word, count) {
+    if (count === 1) return word;
+    if (word.endsWith('y') && !/[aeiou]y$/i.test(word)) return word.slice(0, -1) + 'ies';
+    if (/(?:s|x|z|ch|sh)$/i.test(word)) return word + 'es';
+    return word + 's';
+  }
+
+  /** Convert to boolean */
+  static toBoolean(str) {
+    return ['true', '1', 'yes', 'on', 'y'].includes(String(str).toLowerCase().trim());
+  }
+
+  /** Extract initials */
+  static initials(str, count = 2) {
+    return str
+      .split(/\s+/)
+      .slice(0, count)
+      .map(w => w[0])
+      .join('')
+      .toUpperCase();
+  }
+
+  /** Template interpolation: "Hello {{name}}" */
+  static template(str, data) {
+    return str.replace(/\{\{(\w+)\}\}/g, (_, key) => data[key] ?? '');
+  }
+}
+
+module.exports = { StringHelper };

package/src/utils/validation.js

@@ -0,0 +1,318 @@
+/**
+ * VoltJS Validator
+ * 
+ * Comprehensive, chainable validation for any data.
+ * 
+ * @example
+ * const { Validator } = require('voltjs');
+ * 
+ * const result = Validator.validate(req.body, {
+ *   name: 'required|string|min:2|max:50',
+ *   email: 'required|email',
+ *   age: 'required|integer|min:18|max:120',
+ *   password: 'required|min:8|strongPassword',
+ *   website: 'url',
+ *   role: 'in:admin,user,editor',
+ * });
+ * 
+ * if (!result.valid) {
+ *   console.log(result.errors); // { email: ['Invalid email format'] }
+ * }
+ */
+
+'use strict';
+
+class Validator {
+  /** Validate data against rules */
+  static validate(data, rules) {
+    const errors = {};
+    let valid = true;
+
+    for (const [field, ruleString] of Object.entries(rules)) {
+      const fieldRules = typeof ruleString === 'string' ? ruleString.split('|') : ruleString;
+      const value = data[field];
+      const fieldErrors = [];
+
+      for (const rule of fieldRules) {
+        const [ruleName, ...ruleParams] = rule.split(':');
+        const params = ruleParams.join(':').split(',');
+
+        const error = Validator._checkRule(ruleName, value, params, field, data);
+        if (error) fieldErrors.push(error);
+      }
+
+      if (fieldErrors.length > 0) {
+        errors[field] = fieldErrors;
+        valid = false;
+      }
+    }
+
+    return { valid, errors, data: valid ? data : null };
+  }
+
+  /** Middleware: Validate request body */
+  static body(rules) {
+    return (req, res) => {
+      const result = Validator.validate(req.body || {}, rules);
+      if (!result.valid) {
+        res.json({ error: 'Validation failed', errors: result.errors }, 422);
+        return false;
+      }
+      req.validated = result.data;
+    };
+  }
+
+  /** Middleware: Validate query parameters */
+  static query(rules) {
+    return (req, res) => {
+      const result = Validator.validate(req.query || {}, rules);
+      if (!result.valid) {
+        res.json({ error: 'Validation failed', errors: result.errors }, 422);
+        return false;
+      }
+      req.validatedQuery = result.data;
+    };
+  }
+
+  /** Middleware: Validate URL parameters */
+  static params(rules) {
+    return (req, res) => {
+      const result = Validator.validate(req.params || {}, rules);
+      if (!result.valid) {
+        res.json({ error: 'Validation failed', errors: result.errors }, 422);
+        return false;
+      }
+    };
+  }
+
+  /** Individual validators */
+  static isEmail(value) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value));
+  }
+
+  static isURL(value) {
+    try { new URL(value); return true; } catch { return false; }
+  }
+
+  static isIP(value) {
+    return /^(\d{1,3}\.){3}\d{1,3}$/.test(value) || /^([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$/i.test(value);
+  }
+
+  static isUUID(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+  }
+
+  static isHex(value) {
+    return /^#?[0-9a-f]+$/i.test(value);
+  }
+
+  static isJSON(value) {
+    try { JSON.parse(value); return true; } catch { return false; }
+  }
+
+  static isAlpha(value) {
+    return /^[a-zA-Z]+$/.test(value);
+  }
+
+  static isAlphanumeric(value) {
+    return /^[a-zA-Z0-9]+$/.test(value);
+  }
+
+  static isNumeric(value) {
+    return !isNaN(value) && !isNaN(parseFloat(value));
+  }
+
+  static isSlug(value) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+  }
+
+  static isCreditCard(value) {
+    const cleaned = String(value).replace(/[\s-]/g, '');
+    if (!/^\d{13,19}$/.test(cleaned)) return false;
+    // Luhn algorithm
+    let sum = 0;
+    let alternate = false;
+    for (let i = cleaned.length - 1; i >= 0; i--) {
+      let n = parseInt(cleaned[i], 10);
+      if (alternate) {
+        n *= 2;
+        if (n > 9) n -= 9;
+      }
+      sum += n;
+      alternate = !alternate;
+    }
+    return sum % 10 === 0;
+  }
+
+  static isPhone(value) {
+    return /^\+?[\d\s()-]{7,15}$/.test(value);
+  }
+
+  static isStrongPassword(value) {
+    // At least 8 chars, 1 uppercase, 1 lowercase, 1 number, 1 special char
+    return /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]).{8,}$/.test(value);
+  }
+
+  static isDate(value) {
+    return !isNaN(Date.parse(value));
+  }
+
+  // ===== INTERNAL =====
+
+  static _checkRule(ruleName, value, params, field, data) {
+    // Required check
+    if (ruleName === 'required') {
+      if (value === undefined || value === null || value === '') {
+        return `${field} is required`;
+      }
+      return null;
+    }
+
+    // Skip other validations if value is empty and not required
+    if (value === undefined || value === null || value === '') return null;
+
+    switch (ruleName) {
+      case 'string':
+        if (typeof value !== 'string') return `${field} must be a string`;
+        break;
+      case 'number':
+      case 'numeric':
+        if (isNaN(value)) return `${field} must be a number`;
+        break;
+      case 'integer':
+      case 'int':
+        if (!Number.isInteger(Number(value))) return `${field} must be an integer`;
+        break;
+      case 'float':
+        if (isNaN(parseFloat(value))) return `${field} must be a decimal number`;
+        break;
+      case 'boolean':
+      case 'bool':
+        if (typeof value !== 'boolean' && !['true', 'false', '0', '1'].includes(String(value))) {
+          return `${field} must be a boolean`;
+        }
+        break;
+      case 'array':
+        if (!Array.isArray(value)) return `${field} must be an array`;
+        break;
+      case 'object':
+        if (typeof value !== 'object' || Array.isArray(value)) return `${field} must be an object`;
+        break;
+      case 'email':
+        if (!Validator.isEmail(value)) return `${field} must be a valid email`;
+        break;
+      case 'url':
+        if (!Validator.isURL(value)) return `${field} must be a valid URL`;
+        break;
+      case 'ip':
+        if (!Validator.isIP(value)) return `${field} must be a valid IP address`;
+        break;
+      case 'uuid':
+        if (!Validator.isUUID(value)) return `${field} must be a valid UUID`;
+        break;
+      case 'date':
+        if (!Validator.isDate(value)) return `${field} must be a valid date`;
+        break;
+      case 'alpha':
+        if (!Validator.isAlpha(value)) return `${field} must contain only letters`;
+        break;
+      case 'alphanumeric':
+      case 'alphanum':
+        if (!Validator.isAlphanumeric(value)) return `${field} must be alphanumeric`;
+        break;
+      case 'slug':
+        if (!Validator.isSlug(value)) return `${field} must be a valid slug`;
+        break;
+      case 'phone':
+        if (!Validator.isPhone(value)) return `${field} must be a valid phone number`;
+        break;
+      case 'creditCard':
+      case 'credit_card':
+        if (!Validator.isCreditCard(value)) return `${field} must be a valid credit card number`;
+        break;
+      case 'strongPassword':
+      case 'strong_password':
+        if (!Validator.isStrongPassword(value)) {
+          return `${field} must have 8+ chars with uppercase, lowercase, number, and special character`;
+        }
+        break;
+      case 'json':
+        if (!Validator.isJSON(value)) return `${field} must be valid JSON`;
+        break;
+      case 'hex':
+        if (!Validator.isHex(value)) return `${field} must be a hex value`;
+        break;
+      case 'min':
+        if (typeof value === 'string' && value.length < parseInt(params[0])) {
+          return `${field} must be at least ${params[0]} characters`;
+        }
+        if (typeof value === 'number' && value < parseFloat(params[0])) {
+          return `${field} must be at least ${params[0]}`;
+        }
+        break;
+      case 'max':
+        if (typeof value === 'string' && value.length > parseInt(params[0])) {
+          return `${field} must be at most ${params[0]} characters`;
+        }
+        if (typeof value === 'number' && value > parseFloat(params[0])) {
+          return `${field} must be at most ${params[0]}`;
+        }
+        break;
+      case 'length':
+      case 'size':
+        if (String(value).length !== parseInt(params[0])) {
+          return `${field} must be exactly ${params[0]} characters`;
+        }
+        break;
+      case 'in':
+        if (!params.includes(String(value))) {
+          return `${field} must be one of: ${params.join(', ')}`;
+        }
+        break;
+      case 'notIn':
+      case 'not_in':
+        if (params.includes(String(value))) {
+          return `${field} must not be one of: ${params.join(', ')}`;
+        }
+        break;
+      case 'regex':
+      case 'pattern':
+        if (!new RegExp(params[0]).test(value)) {
+          return `${field} format is invalid`;
+        }
+        break;
+      case 'confirmed':
+        if (value !== data[`${field}_confirmation`]) {
+          return `${field} confirmation does not match`;
+        }
+        break;
+      case 'same':
+        if (value !== data[params[0]]) {
+          return `${field} must match ${params[0]}`;
+        }
+        break;
+      case 'different':
+        if (value === data[params[0]]) {
+          return `${field} must be different from ${params[0]}`;
+        }
+        break;
+      case 'before':
+        if (new Date(value) >= new Date(params[0])) {
+          return `${field} must be before ${params[0]}`;
+        }
+        break;
+      case 'after':
+        if (new Date(value) <= new Date(params[0])) {
+          return `${field} must be after ${params[0]}`;
+        }
+        break;
+      default:
+        // Unknown rule — skip
+        break;
+    }
+
+    return null;
+  }
+}
+
+module.exports = { Validator };