voltjs-framework 1.0.0

package/src/utils/form.js

@@ -0,0 +1,547 @@
+/**
+ * VoltJS Form Handler
+ * 
+ * Comprehensive form state management — like React Hook Form + Zod combined.
+ * Tracks dirty/touched/pristine fields, per-field errors, nested objects, arrays,
+ * schema validation, and handles submission.
+ * 
+ * @example
+ * const { Form } = require('voltjs');
+ * 
+ * const form = new Form({
+ *   defaults: { name: '', email: '', age: 0 },
+ *   rules: {
+ *     name: 'required|string|min:2',
+ *     email: 'required|email',
+ *     age: 'required|integer|min:18',
+ *   },
+ *   onSubmit: async (data) => await User.create(data),
+ * });
+ * 
+ * form.set('name', 'John');
+ * form.set('email', 'john@example.com');
+ * form.set('age', 25);
+ * 
+ * const result = await form.submit();
+ */
+
+'use strict';
+
+class Form {
+  constructor(config = {}) {
+    this._defaults = JSON.parse(JSON.stringify(config.defaults || {}));
+    this._values = JSON.parse(JSON.stringify(this._defaults));
+    this._rules = config.rules || {};
+    this._schema = config.schema || null; // VoltSchema instance
+    this._onSubmit = config.onSubmit || null;
+    this._onError = config.onError || null;
+    this._transform = config.transform || null;
+
+    // Field state
+    this._dirty = new Set();
+    this._touched = new Set();
+    this._errors = {};
+    this._submitted = false;
+    this._submitting = false;
+    this._submitCount = 0;
+    this._valid = true;
+
+    // Watchers
+    this._watchers = {};
+    this._globalWatchers = [];
+
+    // Validate mode
+    this._validateOn = config.validateOn || 'submit'; // 'change' | 'blur' | 'submit'
+  }
+
+  // ===== GETTERS =====
+
+  /** Get a field value (supports dot notation: "address.city") */
+  get(field) {
+    return Form._getPath(this._values, field);
+  }
+
+  /** Get all form values */
+  get values() {
+    return JSON.parse(JSON.stringify(this._values));
+  }
+
+  /** Get all errors */
+  get errors() {
+    return { ...this._errors };
+  }
+
+  /** Get error for a specific field */
+  error(field) {
+    return this._errors[field] || null;
+  }
+
+  /** Check if form is valid */
+  get isValid() {
+    return this._valid && Object.keys(this._errors).length === 0;
+  }
+
+  /** Check if form has been modified */
+  get isDirty() {
+    return this._dirty.size > 0;
+  }
+
+  /** Check if a specific field is dirty */
+  isFieldDirty(field) {
+    return this._dirty.has(field);
+  }
+
+  /** Check if a specific field has been touched (focused then blurred) */
+  isFieldTouched(field) {
+    return this._touched.has(field);
+  }
+
+  /** Check if form is currently submitting */
+  get isSubmitting() {
+    return this._submitting;
+  }
+
+  /** Number of times form was submitted */
+  get submitCount() {
+    return this._submitCount;
+  }
+
+  /** Check if form has been submitted at least once */
+  get isSubmitted() {
+    return this._submitted;
+  }
+
+  /** Get list of dirty fields */
+  get dirtyFields() {
+    return [...this._dirty];
+  }
+
+  /** Get list of touched fields */
+  get touchedFields() {
+    return [...this._touched];
+  }
+
+  /** Get only the changed values (dirty fields) */
+  get dirtyValues() {
+    const result = {};
+    for (const field of this._dirty) {
+      result[field] = this.get(field);
+    }
+    return result;
+  }
+
+  // ===== SETTERS =====
+
+  /** Set a field value (supports dot notation) */
+  set(field, value) {
+    const oldValue = this.get(field);
+    Form._setPath(this._values, field, value);
+
+    // Track dirty
+    const defaultVal = Form._getPath(this._defaults, field);
+    if (!Form._isEqual(value, defaultVal)) {
+      this._dirty.add(field);
+    } else {
+      this._dirty.delete(field);
+    }
+
+    // Notify watchers
+    this._notifyWatchers(field, value, oldValue);
+
+    // Validate on change if configured
+    if (this._validateOn === 'change') {
+      this.validateField(field);
+    }
+
+    return this;
+  }
+
+  /** Set multiple fields at once */
+  setValues(data) {
+    for (const [field, value] of Object.entries(data)) {
+      this.set(field, value);
+    }
+    return this;
+  }
+
+  /** Mark a field as touched */
+  touch(field) {
+    this._touched.add(field);
+    if (this._validateOn === 'blur') {
+      this.validateField(field);
+    }
+    return this;
+  }
+
+  /** Mark all fields as touched */
+  touchAll() {
+    const allFields = Form._flattenKeys(this._values);
+    for (const field of allFields) {
+      this._touched.add(field);
+    }
+    return this;
+  }
+
+  // ===== VALIDATION =====
+
+  /** Validate the entire form */
+  validate() {
+    this._errors = {};
+    this._valid = true;
+
+    // Use schema if provided
+    if (this._schema && typeof this._schema.validate === 'function') {
+      const result = this._schema.validate(this._values);
+      if (!result.valid) {
+        this._errors = result.errors || {};
+        this._valid = false;
+        return false;
+      }
+      return true;
+    }
+
+    // Use rules (string-based validation like Validator)
+    if (Object.keys(this._rules).length > 0) {
+      try {
+        const { Validator } = require('./validation');
+        const result = Validator.validate(this._values, this._rules);
+        if (!result.valid) {
+          this._errors = result.errors;
+          this._valid = false;
+          return false;
+        }
+      } catch {
+        // Validator not available, skip
+      }
+    }
+
+    // Custom validators
+    if (this._customValidators) {
+      for (const [field, fn] of Object.entries(this._customValidators)) {
+        const error = fn(this.get(field), this._values);
+        if (error) {
+          this._errors[field] = Array.isArray(error) ? error : [error];
+          this._valid = false;
+        }
+      }
+    }
+
+    return this._valid;
+  }
+
+  /** Validate a single field */
+  validateField(field) {
+    // Use schema if provided
+    if (this._schema && typeof this._schema.validateField === 'function') {
+      const result = this._schema.validateField(field, this.get(field));
+      if (!result.valid) {
+        this._errors[field] = result.errors;
+      } else {
+        delete this._errors[field];
+      }
+      this._valid = Object.keys(this._errors).length === 0;
+      return !this._errors[field];
+    }
+
+    // Use rules
+    if (this._rules[field]) {
+      try {
+        const { Validator } = require('./validation');
+        const result = Validator.validate({ [field]: this.get(field) }, { [field]: this._rules[field] });
+        if (!result.valid) {
+          this._errors[field] = result.errors[field];
+        } else {
+          delete this._errors[field];
+        }
+      } catch { /* skip */ }
+    }
+
+    // Custom validator
+    if (this._customValidators?.[field]) {
+      const error = this._customValidators[field](this.get(field), this._values);
+      if (error) {
+        this._errors[field] = Array.isArray(error) ? error : [error];
+      } else {
+        delete this._errors[field];
+      }
+    }
+
+    this._valid = Object.keys(this._errors).length === 0;
+    return !this._errors[field];
+  }
+
+  /** Add a custom field validator */
+  addValidator(field, fn) {
+    if (!this._customValidators) this._customValidators = {};
+    this._customValidators[field] = fn;
+    return this;
+  }
+
+  /** Set a custom error on a field */
+  setError(field, message) {
+    this._errors[field] = Array.isArray(message) ? message : [message];
+    this._valid = false;
+    return this;
+  }
+
+  /** Clear error(s) */
+  clearError(field) {
+    if (field) {
+      delete this._errors[field];
+    } else {
+      this._errors = {};
+    }
+    this._valid = Object.keys(this._errors).length === 0;
+    return this;
+  }
+
+  // ===== SUBMISSION =====
+
+  /** Submit the form */
+  async submit(handler) {
+    this._submitCount++;
+    this._submitted = true;
+    this.touchAll();
+
+    // Validate
+    const valid = this.validate();
+    if (!valid) {
+      if (this._onError) await this._onError(this._errors, this._values);
+      return { success: false, errors: this._errors };
+    }
+
+    // Transform data
+    let data = this.values;
+    if (this._transform) {
+      data = this._transform(data);
+    }
+
+    // Submit
+    const submitFn = handler || this._onSubmit;
+    if (!submitFn) return { success: true, data };
+
+    this._submitting = true;
+    try {
+      const result = await submitFn(data);
+      this._submitting = false;
+      return { success: true, data, result };
+    } catch (err) {
+      this._submitting = false;
+
+      // If server returns field errors, apply them
+      if (err.errors && typeof err.errors === 'object') {
+        for (const [field, msg] of Object.entries(err.errors)) {
+          this._errors[field] = Array.isArray(msg) ? msg : [msg];
+        }
+        this._valid = false;
+      }
+
+      if (this._onError) await this._onError(this._errors, err);
+      return { success: false, errors: this._errors, error: err };
+    }
+  }
+
+  // ===== RESET & UTILITIES =====
+
+  /** Reset form to defaults */
+  reset(newDefaults) {
+    if (newDefaults) {
+      this._defaults = JSON.parse(JSON.stringify(newDefaults));
+    }
+    this._values = JSON.parse(JSON.stringify(this._defaults));
+    this._dirty.clear();
+    this._touched.clear();
+    this._errors = {};
+    this._valid = true;
+    this._submitted = false;
+    this._submitting = false;
+    return this;
+  }
+
+  /** Reset a single field to its default */
+  resetField(field) {
+    const defaultVal = Form._getPath(this._defaults, field);
+    Form._setPath(this._values, field, JSON.parse(JSON.stringify(defaultVal)));
+    this._dirty.delete(field);
+    this._touched.delete(field);
+    delete this._errors[field];
+    return this;
+  }
+
+  /** Watch a field for changes */
+  watch(field, fn) {
+    if (typeof field === 'function') {
+      // Watch all changes
+      this._globalWatchers.push(field);
+      return () => {
+        this._globalWatchers = this._globalWatchers.filter(w => w !== field);
+      };
+    }
+    if (!this._watchers[field]) this._watchers[field] = [];
+    this._watchers[field].push(fn);
+    return () => {
+      this._watchers[field] = this._watchers[field].filter(w => w !== fn);
+    };
+  }
+
+  /** Get form state summary */
+  getState() {
+    return {
+      values: this.values,
+      errors: this.errors,
+      isDirty: this.isDirty,
+      isValid: this.isValid,
+      isSubmitting: this.isSubmitting,
+      isSubmitted: this.isSubmitted,
+      submitCount: this.submitCount,
+      dirtyFields: this.dirtyFields,
+      touchedFields: this.touchedFields,
+    };
+  }
+
+  // ===== ARRAY FIELDS =====
+
+  /** Append an item to an array field */
+  append(field, value) {
+    const arr = this.get(field) || [];
+    if (!Array.isArray(arr)) throw new Error(`${field} is not an array`);
+    this.set(field, [...arr, value]);
+    return this;
+  }
+
+  /** Prepend an item to an array field */
+  prepend(field, value) {
+    const arr = this.get(field) || [];
+    if (!Array.isArray(arr)) throw new Error(`${field} is not an array`);
+    this.set(field, [value, ...arr]);
+    return this;
+  }
+
+  /** Remove an item from an array field by index */
+  remove(field, index) {
+    const arr = this.get(field) || [];
+    if (!Array.isArray(arr)) throw new Error(`${field} is not an array`);
+    this.set(field, arr.filter((_, i) => i !== index));
+    return this;
+  }
+
+  /** Move an array item */
+  move(field, from, to) {
+    const arr = [...(this.get(field) || [])];
+    const [item] = arr.splice(from, 1);
+    arr.splice(to, 0, item);
+    this.set(field, arr);
+    return this;
+  }
+
+  /** Swap two array items */
+  swap(field, indexA, indexB) {
+    const arr = [...(this.get(field) || [])];
+    [arr[indexA], arr[indexB]] = [arr[indexB], arr[indexA]];
+    this.set(field, arr);
+    return this;
+  }
+
+  // ===== MIDDLEWARE (Express/Volt) =====
+
+  /**
+   * Express/Volt middleware that parses and validates a form from request body
+   * 
+   * @example
+   * app.post('/register', Form.handle({
+   *   rules: { name: 'required', email: 'required|email' },
+   *   onSubmit: async (data) => User.create(data),
+   * }), (req, res) => {
+   *   res.json(req.formResult);
+   * });
+   */
+  static handle(config) {
+    return async (req, res) => {
+      const form = new Form({
+        ...config,
+        defaults: config.defaults || {},
+      });
+
+      form.setValues(req.body || {});
+
+      const result = await form.submit();
+      req.form = form;
+      req.formResult = result;
+
+      if (!result.success) {
+        res.json({ error: 'Validation failed', errors: result.errors }, 422);
+        return false;
+      }
+    };
+  }
+
+  // ===== INTERNAL HELPERS =====
+
+  _notifyWatchers(field, newValue, oldValue) {
+    if (this._watchers[field]) {
+      for (const fn of this._watchers[field]) fn(newValue, oldValue);
+    }
+    for (const fn of this._globalWatchers) fn(field, newValue, oldValue);
+  }
+
+  static _getPath(obj, path) {
+    return path.split('.').reduce((curr, key) => {
+      if (curr === undefined || curr === null) return undefined;
+      // Handle array notation: "items.0.name"
+      const idx = parseInt(key);
+      if (!isNaN(idx) && Array.isArray(curr)) return curr[idx];
+      return curr[key];
+    }, obj);
+  }
+
+  static _setPath(obj, path, value) {
+    const keys = path.split('.');
+    let curr = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+      const key = keys[i];
+      const nextKey = keys[i + 1];
+      const idx = parseInt(key);
+
+      if (!isNaN(idx) && Array.isArray(curr)) {
+        if (curr[idx] === undefined) curr[idx] = isNaN(parseInt(nextKey)) ? {} : [];
+        curr = curr[idx];
+      } else {
+        if (curr[key] === undefined) curr[key] = isNaN(parseInt(nextKey)) ? {} : [];
+        curr = curr[key];
+      }
+    }
+
+    const lastKey = keys[keys.length - 1];
+    const lastIdx = parseInt(lastKey);
+    if (!isNaN(lastIdx) && Array.isArray(curr)) {
+      curr[lastIdx] = value;
+    } else {
+      curr[lastKey] = value;
+    }
+  }
+
+  static _flattenKeys(obj, prefix = '') {
+    const keys = [];
+    for (const [key, value] of Object.entries(obj)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        keys.push(...Form._flattenKeys(value, fullKey));
+      } else {
+        keys.push(fullKey);
+      }
+    }
+    return keys;
+  }
+
+  static _isEqual(a, b) {
+    if (a === b) return true;
+    if (a === null || b === null) return false;
+    if (typeof a !== typeof b) return false;
+    if (typeof a === 'object') {
+      return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return false;
+  }
+}
+
+module.exports = { Form };

package/src/utils/hash.js

@@ -0,0 +1,121 @@
+/**
+ * VoltJS Hash
+ * 
+ * Common hashing utilities wrapping Node crypto.
+ * 
+ * @example
+ * const { Hash } = require('voltjs');
+ * 
+ * const hashed = await Hash.make('password123');
+ * const valid = await Hash.verify('password123', hashed);
+ * 
+ * const sha = Hash.sha256('data');
+ * const md5 = Hash.md5('data');
+ * const token = Hash.random(32);
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+class Hash {
+  /** Hash a password using PBKDF2 */
+  static async make(password, options = {}) {
+    const salt = options.salt || crypto.randomBytes(32).toString('hex');
+    const iterations = options.iterations || 100000;
+    const keyLen = options.keyLen || 64;
+    const digest = options.digest || 'sha512';
+
+    return new Promise((resolve, reject) => {
+      crypto.pbkdf2(password, salt, iterations, keyLen, digest, (err, key) => {
+        if (err) return reject(err);
+        resolve(`${digest}:${iterations}:${salt}:${key.toString('hex')}`);
+      });
+    });
+  }
+
+  /** Verify a password against a hash */
+  static async verify(password, hash) {
+    const [digest, iterations, salt, key] = hash.split(':');
+
+    return new Promise((resolve, reject) => {
+      crypto.pbkdf2(password, salt, parseInt(iterations), Buffer.from(key, 'hex').length, digest, (err, derivedKey) => {
+        if (err) return reject(err);
+        resolve(crypto.timingSafeEqual(Buffer.from(key, 'hex'), derivedKey));
+      });
+    });
+  }
+
+  /** SHA-256 hash */
+  static sha256(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
+  }
+
+  /** SHA-512 hash */
+  static sha512(data) {
+    return crypto.createHash('sha512').update(data).digest('hex');
+  }
+
+  /** MD5 hash (not secure, for checksums only) */
+  static md5(data) {
+    return crypto.createHash('md5').update(data).digest('hex');
+  }
+
+  /** HMAC-SHA256 */
+  static hmac(data, secret, algorithm = 'sha256') {
+    return crypto.createHmac(algorithm, secret).update(data).digest('hex');
+  }
+
+  /** Generate random hex string */
+  static random(length = 32) {
+    return crypto.randomBytes(length).toString('hex');
+  }
+
+  /** Generate random base64 string */
+  static randomBase64(length = 32) {
+    return crypto.randomBytes(length).toString('base64url');
+  }
+
+  /** Generate random integer in range */
+  static randomInt(min, max) {
+    return crypto.randomInt(min, max + 1);
+  }
+
+  /** Generate UUID v4 */
+  static uuid() {
+    return crypto.randomUUID();
+  }
+
+  /** CRC32 checksum */
+  static crc32(data) {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < buf.length; i++) {
+      crc ^= buf[i];
+      for (let j = 0; j < 8; j++) {
+        crc = (crc >>> 1) ^ (crc & 1 ? 0xEDB88320 : 0);
+      }
+    }
+    return ((crc ^ 0xFFFFFFFF) >>> 0).toString(16).padStart(8, '0');
+  }
+
+  /** Base64 encode */
+  static base64Encode(data) {
+    return Buffer.from(data).toString('base64');
+  }
+
+  /** Base64 decode */
+  static base64Decode(data) {
+    return Buffer.from(data, 'base64').toString('utf-8');
+  }
+
+  /** Timing-safe comparison */
+  static equals(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) return false;
+    return crypto.timingSafeEqual(bufA, bufB);
+  }
+}
+
+module.exports = { Hash };