@idirdev/formguard 1.0.0

package/src/react.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * React hook for real-time form validation with FormGuard.
+ *
+ * Usage:
+ *   import { useFormGuard } from '@idirdev/formguard/react';
+ *
+ *   function LoginForm() {
+ *     const { values, errors, touched, handleChange, handleBlur, handleSubmit, isValid, reset } =
+ *       useFormGuard({
+ *         initialValues: { email: '', password: '' },
+ *         rules: {
+ *           email: ['required', 'email'],
+ *           password: ['required', { rule: 'minLength', param: 8 }]
+ *         },
+ *         onSubmit: (data) => { console.log(data); }
+ *       });
+ *
+ *     return (
+ *       <form onSubmit={handleSubmit}>
+ *         <input name="email" value={values.email} onChange={handleChange} onBlur={handleBlur} />
+ *         {touched.email && errors.email && <span>{errors.email[0]}</span>}
+ *         ...
+ *       </form>
+ *     );
+ *   }
+ */
+
+let React;
+try {
+  React = require('react');
+} catch (e) {
+  // React not available; exports will throw clear errors when called
+}
+
+const { validate } = require('./validator');
+
+/**
+ * @param {Object} config
+ * @param {Object} config.initialValues - Initial form values
+ * @param {Object} config.rules - Validation rules
+ * @param {Function} [config.onSubmit] - Submission handler (receives validated data)
+ * @param {string} [config.locale='en'] - Locale for messages
+ * @param {Object} [config.messages] - Custom messages
+ * @param {Object} [config.labels] - Human-readable field labels
+ * @param {boolean} [config.validateOnChange=false] - Validate on every change
+ * @param {boolean} [config.validateOnBlur=true] - Validate on blur
+ */
+function useFormGuard(config) {
+  if (!React) {
+    throw new Error('FormGuard: React is required for useFormGuard. Install react as a dependency.');
+  }
+
+  const { useState, useCallback, useRef, useMemo } = React;
+
+  const {
+    initialValues = {},
+    rules: validationRules = {},
+    onSubmit,
+    locale = 'en',
+    messages: customMessages,
+    labels,
+    validateOnChange = false,
+    validateOnBlur = true
+  } = config;
+
+  const [values, setValues] = useState({ ...initialValues });
+  const [errors, setErrors] = useState({});
+  const [touched, setTouched] = useState({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [submitCount, setSubmitCount] = useState(0);
+
+  const rulesRef = useRef(validationRules);
+  rulesRef.current = validationRules;
+
+  const validateOptions = useMemo(() => ({
+    locale,
+    messages: customMessages,
+    labels
+  }), [locale, customMessages, labels]);
+
+  /**
+   * Validate a single field.
+   */
+  const validateField = useCallback((fieldName, fieldValue, allValues) => {
+    if (!rulesRef.current[fieldName]) return [];
+
+    const result = validate(
+      { ...allValues, [fieldName]: fieldValue },
+      { [fieldName]: rulesRef.current[fieldName] },
+      validateOptions
+    );
+
+    return result.errors[fieldName] || [];
+  }, [validateOptions]);
+
+  /**
+   * Validate all fields.
+   */
+  const validateAll = useCallback((data) => {
+    return validate(data || values, rulesRef.current, validateOptions);
+  }, [values, validateOptions]);
+
+  /**
+   * Handle input change events.
+   */
+  const handleChange = useCallback((e) => {
+    const { name, value, type, checked } = e.target;
+    const newValue = type === 'checkbox' ? checked : value;
+
+    setValues(prev => {
+      const next = { ...prev, [name]: newValue };
+
+      if (validateOnChange || submitCount > 0) {
+        const fieldErrors = validateField(name, newValue, next);
+        setErrors(prevErrors => {
+          const updated = { ...prevErrors };
+          if (fieldErrors.length > 0) {
+            updated[name] = fieldErrors;
+          } else {
+            delete updated[name];
+          }
+          return updated;
+        });
+      }
+
+      return next;
+    });
+  }, [validateOnChange, validateField, submitCount]);
+
+  /**
+   * Handle blur events (triggers field validation).
+   */
+  const handleBlur = useCallback((e) => {
+    const { name } = e.target;
+
+    setTouched(prev => ({ ...prev, [name]: true }));
+
+    if (validateOnBlur) {
+      const fieldErrors = validateField(name, values[name], values);
+      setErrors(prev => {
+        const updated = { ...prev };
+        if (fieldErrors.length > 0) {
+          updated[name] = fieldErrors;
+        } else {
+          delete updated[name];
+        }
+        return updated;
+      });
+    }
+  }, [validateOnBlur, validateField, values]);
+
+  /**
+   * Set a single field value programmatically.
+   */
+  const setFieldValue = useCallback((name, value) => {
+    setValues(prev => ({ ...prev, [name]: value }));
+  }, []);
+
+  /**
+   * Set a field error programmatically.
+   */
+  const setFieldError = useCallback((name, error) => {
+    setErrors(prev => ({
+      ...prev,
+      [name]: Array.isArray(error) ? error : [error]
+    }));
+  }, []);
+
+  /**
+   * Handle form submission.
+   */
+  const handleSubmit = useCallback((e) => {
+    if (e && e.preventDefault) e.preventDefault();
+
+    setSubmitCount(c => c + 1);
+
+    // Mark all fields as touched
+    const allTouched = {};
+    for (const key of Object.keys(rulesRef.current)) {
+      allTouched[key] = true;
+    }
+    setTouched(prev => ({ ...prev, ...allTouched }));
+
+    const result = validateAll(values);
+    setErrors(result.errors);
+
+    if (!result.valid) return;
+
+    if (onSubmit) {
+      setIsSubmitting(true);
+      const maybePromise = onSubmit(values);
+      if (maybePromise && typeof maybePromise.then === 'function') {
+        maybePromise
+          .catch(() => {})
+          .finally(() => setIsSubmitting(false));
+      } else {
+        setIsSubmitting(false);
+      }
+    }
+  }, [values, validateAll, onSubmit]);
+
+  /**
+   * Reset form to initial state.
+   */
+  const reset = useCallback((newValues) => {
+    setValues(newValues || { ...initialValues });
+    setErrors({});
+    setTouched({});
+    setIsSubmitting(false);
+    setSubmitCount(0);
+  }, [initialValues]);
+
+  const isValid = useMemo(() => Object.keys(errors).length === 0, [errors]);
+
+  const isDirty = useMemo(() => {
+    return Object.keys(values).some(key => values[key] !== initialValues[key]);
+  }, [values, initialValues]);
+
+  return {
+    values,
+    errors,
+    touched,
+    isValid,
+    isDirty,
+    isSubmitting,
+    submitCount,
+    handleChange,
+    handleBlur,
+    handleSubmit,
+    setFieldValue,
+    setFieldError,
+    setValues,
+    setErrors,
+    validateAll,
+    validateField,
+    reset
+  };
+}
+
+module.exports = { useFormGuard };

package/src/sanitizers.js

@@ -0,0 +1,14 @@
+'use strict';
+const ENT = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#x27;', '/': '&#x2F;' };
+function escapeHtml(s) { return String(s).replace(/[&<>"'/]/g, c => ENT[c]); }
+function stripTags(s, a = []) { if (!a.length) return String(s).replace(/<[^>]*>/g, ''); const t = a.map(x => x.toLowerCase()); return String(s).replace(/<\/?([a-zA-Z][a-zA-Z0-9]*)\b[^>]*>/g, (m, x) => t.includes(x.toLowerCase()) ? m : ''); }
+function slugify(s) { return String(s).toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); }
+function normalizeEmail(e) { const [l, d] = String(e).trim().toLowerCase().split('@'); if (!l || !d) return e; let n = l.replace(/\+.*$/, ''); if (['gmail.com','googlemail.com'].includes(d)) n = n.replace(/\./g, ''); return n + '@' + d; }
+function trim(s) { return String(s).trim(); }
+function toLowerCase(s) { return String(s).toLowerCase(); }
+function toNumber(s) { const n = Number(s); return isNaN(n) ? 0 : n; }
+function toBoolean(s) { return ['true','1','yes','on'].includes(String(s).toLowerCase()); }
+function truncate(s, l = 100) { s = String(s); return s.length > l ? s.slice(0, l) + '...' : s; }
+const SANITIZERS = { escapeHtml, stripTags, slugify, normalizeEmail, trim, toLowerCase, toNumber, toBoolean, truncate };
+function sanitize(data, rules) { const r = { ...data }; for (const [f, fns] of Object.entries(rules)) { if (r[f] === undefined) continue; const list = typeof fns === 'string' ? fns.split('|') : fns; for (const fn of list) { const s = typeof fn === 'function' ? fn : SANITIZERS[typeof fn === 'string' ? fn.trim() : fn]; if (s) r[f] = s(r[f]); } } return r; }
+module.exports = { sanitize, escapeHtml, stripTags, slugify, normalizeEmail, trim, toLowerCase, toNumber, toBoolean, truncate, SANITIZERS };

package/src/schema.js

@@ -0,0 +1,16 @@
+'use strict';
+const { validate: run } = require('./validators');
+class Schema {
+  constructor() { this._f = {}; this._c = null; }
+  field(n) { this._c = n; this._f[n] = []; return this; }
+  required() { this._f[this._c].push({ name: 'required', params: [] }); return this; }
+  email() { this._f[this._c].push({ name: 'email', params: [] }); return this; }
+  minLength(n) { this._f[this._c].push({ name: 'minLength', params: [n] }); return this; }
+  maxLength(n) { this._f[this._c].push({ name: 'maxLength', params: [n] }); return this; }
+  min(n) { this._f[this._c].push({ name: 'min', params: [n] }); return this; }
+  max(n) { this._f[this._c].push({ name: 'max', params: [n] }); return this; }
+  integer() { this._f[this._c].push({ name: 'integer', params: [] }); return this; }
+  strongPassword() { this._f[this._c].push({ name: 'strongPassword', params: [] }); return this; }
+  validate(data, opts) { return run(data, this._f, opts); }
+}
+module.exports = { createSchema: () => new Schema(), Schema };

package/src/validator.js

@@ -0,0 +1,218 @@
+'use strict';
+
+const builtInRules = require('./rules');
+const { getMessage } = require('./messages');
+
+/**
+ * Parse a rule definition into a normalized structure.
+ * Supports multiple formats:
+ *   - String:   'required'
+ *   - String with params: 'minLength:6'
+ *   - Function: (value) => boolean
+ *   - Object:   { rule: 'email', message: 'Bad email' }
+ *   - Array:    ['required', 'email', { rule: 'minLength', param: 6 }]
+ */
+function parseRuleDefinition(def) {
+  if (typeof def === 'string') {
+    const [name, ...paramParts] = def.split(':');
+    const param = paramParts.length > 0 ? paramParts.join(':') : undefined;
+    return [{ name, param }];
+  }
+
+  if (typeof def === 'function') {
+    return [{ name: 'custom', fn: def }];
+  }
+
+  if (Array.isArray(def)) {
+    const results = [];
+    for (const item of def) {
+      results.push(...parseRuleDefinition(item));
+    }
+    return results;
+  }
+
+  if (typeof def === 'object' && def !== null) {
+    return [{
+      name: def.rule || 'custom',
+      param: def.param,
+      message: def.message,
+      fn: def.fn || def.validate
+    }];
+  }
+
+  return [];
+}
+
+/**
+ * Resolve a parsed rule definition into an executable validation function.
+ */
+function resolveRule(parsed) {
+  if (parsed.fn) {
+    const fn = typeof parsed.fn === 'function' ? parsed.fn : null;
+    return { validate: fn, name: parsed.name, param: parsed.param, message: parsed.message, needsData: true };
+  }
+
+  const rule = builtInRules[parsed.name];
+  if (!rule) {
+    throw new Error(`FormGuard: Unknown rule "${parsed.name}". Register it or use a custom function.`);
+  }
+
+  // Rules that take parameters return a function
+  const parameterizedRules = ['min', 'max', 'minLength', 'maxLength', 'pattern', 'before', 'after', 'in', 'enum', 'notIn', 'equals', 'confirmed', 'custom'];
+
+  if (parameterizedRules.includes(parsed.name) && typeof rule === 'function') {
+    let param = parsed.param;
+    // Auto-parse numeric params for min/max/minLength/maxLength
+    if (['min', 'max', 'minLength', 'maxLength'].includes(parsed.name) && typeof param === 'string') {
+      param = Number(param);
+    }
+    // Parse array params for in/notIn/enum
+    if (['in', 'notIn', 'enum'].includes(parsed.name) && typeof param === 'string') {
+      param = param.split(',').map(s => s.trim());
+    }
+
+    const validatorFn = rule(param);
+    return {
+      validate: validatorFn,
+      name: parsed.name,
+      param: param,
+      message: parsed.message,
+      needsData: validatorFn._needsData || false
+    };
+  }
+
+  return {
+    validate: rule,
+    name: parsed.name,
+    param: parsed.param,
+    message: parsed.message,
+    needsData: rule._needsData || false
+  };
+}
+
+/**
+ * Validate a data object against a set of rules.
+ *
+ * @param {Object} data - The data object to validate
+ * @param {Object} rules - Validation rules keyed by field name
+ * @param {Object} [options] - Options
+ * @param {string} [options.locale='en'] - Locale for error messages ('en' or 'fr')
+ * @param {Object} [options.messages] - Custom error message overrides
+ * @param {boolean} [options.abortEarly=false] - Stop on first error
+ * @param {Object} [options.labels] - Human-readable field labels { fieldName: 'Label' }
+ * @returns {{ valid: boolean, errors: Object<string, string[]> }}
+ */
+function validate(data, rules, options = {}) {
+  const {
+    locale = 'en',
+    messages: customMessages = {},
+    abortEarly = false,
+    labels = {}
+  } = options;
+
+  const errors = {};
+  const dataObj = data || {};
+
+  for (const [field, ruleDefs] of Object.entries(rules)) {
+    const fieldLabel = labels[field] || field;
+    const value = getNestedValue(dataObj, field);
+    const parsedRules = parseRuleDefinition(ruleDefs);
+    const fieldErrors = [];
+
+    for (const parsed of parsedRules) {
+      const resolved = resolveRule(parsed);
+
+      if (!resolved.validate) continue;
+
+      let isValid;
+      if (resolved.needsData) {
+        isValid = resolved.validate(value, field, dataObj);
+      } else {
+        isValid = resolved.validate(value);
+      }
+
+      if (!isValid) {
+        const msg = resolved.message ||
+          getMessage(resolved.name, fieldLabel, resolved.param, locale, customMessages);
+        fieldErrors.push(msg);
+
+        if (abortEarly) break;
+      }
+    }
+
+    if (fieldErrors.length > 0) {
+      errors[field] = fieldErrors;
+      if (abortEarly) break;
+    }
+  }
+
+  return {
+    valid: Object.keys(errors).length === 0,
+    errors
+  };
+}
+
+/**
+ * Get a nested value from an object using dot notation.
+ * Supports array indexing: 'items.0.name'
+ */
+function getNestedValue(obj, path) {
+  if (!path.includes('.')) return obj[path];
+  return path.split('.').reduce((current, key) => {
+    if (current === undefined || current === null) return undefined;
+    return current[key];
+  }, obj);
+}
+
+/**
+ * Async version of validate for rules that return promises.
+ */
+async function validateAsync(data, rules, options = {}) {
+  const {
+    locale = 'en',
+    messages: customMessages = {},
+    abortEarly = false,
+    labels = {}
+  } = options;
+
+  const errors = {};
+  const dataObj = data || {};
+
+  for (const [field, ruleDefs] of Object.entries(rules)) {
+    const fieldLabel = labels[field] || field;
+    const value = getNestedValue(dataObj, field);
+    const parsedRules = parseRuleDefinition(ruleDefs);
+    const fieldErrors = [];
+
+    for (const parsed of parsedRules) {
+      const resolved = resolveRule(parsed);
+      if (!resolved.validate) continue;
+
+      let isValid;
+      if (resolved.needsData) {
+        isValid = await resolved.validate(value, field, dataObj);
+      } else {
+        isValid = await resolved.validate(value);
+      }
+
+      if (!isValid) {
+        const msg = resolved.message ||
+          getMessage(resolved.name, fieldLabel, resolved.param, locale, customMessages);
+        fieldErrors.push(msg);
+        if (abortEarly) break;
+      }
+    }
+
+    if (fieldErrors.length > 0) {
+      errors[field] = fieldErrors;
+      if (abortEarly) break;
+    }
+  }
+
+  return {
+    valid: Object.keys(errors).length === 0,
+    errors
+  };
+}
+
+module.exports = { validate, validateAsync, parseRuleDefinition, resolveRule, getNestedValue };

package/src/validators.js

@@ -0,0 +1,61 @@
+'use strict';
+const { getMessage } = require('./messages');
+const RULES = {
+  required: (v) => v !== undefined && v !== null && v !== '',
+  email: (v) => /^[^@s]+@[^@s]+.[^@s]+$/.test(v),
+  url: (v) => { try { new URL(v); return true; } catch { return false; } },
+  minLength: (v, n) => typeof v === 'string' && v.length >= n,
+  maxLength: (v, n) => typeof v === 'string' && v.length <= n,
+  min: (v, n) => Number(v) >= n,
+  max: (v, n) => Number(v) <= n,
+  integer: (v) => Number.isInteger(Number(v)) && !isNaN(v),
+  numeric: (v) => !isNaN(v) && !isNaN(parseFloat(v)),
+  alpha: (v) => /^[a-zA-Z]+$/.test(v),
+  alphanumeric: (v) => /^[a-zA-Z0-9]+$/.test(v),
+  phone: (v) => /^\+?[0-9\s\-().]{7,20}$/.test(v),
+  creditCard: (v) => {
+    const d = String(v).replace(/\D/g, '');
+    if (d.length < 13 || d.length > 19) return false;
+    let sum = 0, alt = false;
+    for (let i = d.length - 1; i >= 0; i--) {
+      let n = parseInt(d[i], 10);
+      if (alt) { n *= 2; if (n > 9) n -= 9; }
+      sum += n; alt = !alt;
+    }
+    return sum % 10 === 0;
+  },
+  uuid: (v) => /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(v),
+  ip: (v) => /^(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)$/.test(v),
+  date: (v) => !isNaN(Date.parse(v)),
+  slug: (v) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v),
+  hex: (v) => /^[0-9a-fA-F]+$/.test(v),
+  json: (v) => { try { JSON.parse(v); return true; } catch { return false; } },
+  equals: (v, expected) => v === expected,
+  oneOf: (v, list) => (Array.isArray(list) ? list : list.split(',')).includes(v),
+  matches: (v, pattern) => new RegExp(pattern).test(v),
+  strongPassword: (v) => typeof v === 'string' && v.length >= 8 && /[a-z]/.test(v) && /[A-Z]/.test(v) && /[0-9]/.test(v) && /[^a-zA-Z0-9]/.test(v),
+};
+function validate(data, rules, opts = {}) {
+  const errors = {};
+  for (const [field, fr] of Object.entries(rules)) {
+    const value = field.split('.').reduce((o, k) => o && o[k], data);
+    const rl = typeof fr === 'string' ? fr.split('|').map(parseRule) : fr;
+    const fe = validateField(value, rl, { ...opts, field });
+    if (fe.length > 0) { errors[field] = fe; if (opts.abortEarly) break; }
+  }
+  return { valid: Object.keys(errors).length === 0, errors };
+}
+function validateField(value, rules, opts = {}) {
+  const errors = [];
+  const rl = typeof rules === 'string' ? rules.split('|').map(parseRule) : rules;
+  for (const rule of rl) {
+    const { name, params } = typeof rule === 'string' ? parseRule(rule) : rule;
+    if (name === 'required') { if (!RULES.required(value)) errors.push(getMessage(name, opts.field, params)); continue; }
+    if (value === undefined || value === null || value === '') continue;
+    const v = RULES[name];
+    if (v && !v(value, ...params)) errors.push(getMessage(name, opts.field, params));
+  }
+  return errors;
+}
+function parseRule(s) { const [n, p] = s.split(':'); return { name: n.trim(), params: p ? p.split(',').map(x => isNaN(x) ? x.trim() : Number(x.trim())) : [] }; }
+module.exports = { validate, validateField, RULES };