js-formx

Zero-config form validation for javascript and typeScript that just works. Built for modern web applications.

Features

• Simple API - Array-based validation rules
• Type Safe - Built with TypeScript for excellent type inference
• Zero Config - Works out of the box with any JS/TS project
• No Dependencies - Tiny footprint, no external dependencies
• Framework Agnostic - Use with React, Vue, Svelte, or vanilla JS

Install

npm install js-formx

Usage

import { validateForm } from 'js-formx'

// Your form values
const form = {
  username: 'alex',
  email: 'not-an-email',
  password: 'weak'
}

// Define validation rules
const rules = {
  username: ['required', 'min:3', 'max:50'],
  email: ['required', 'email'],
  password: [
    'required',
    'min:8',
    'min_uppercase:1',
    'min_lowercase:1',
    'min_special:1',
    'min_numeric:1'
  ]
}

// Validate form
const result = validateForm(form, rules)

if (!result.valid) {
  console.log(result.errors)
  // {
  //   email: 'Invalid email address',
  //   password: 'Must contain at least 1 uppercase letter'
  // }

Available Rules

Rule	Description	Example	Error Message
required	Field must not be empty	['required']	'This field is required'
email	Must be a valid email	['email']	'Invalid email address'
url	Must be a valid URL	['url']	'Must be a valid URL'
numeric	Must contain only numbers	['numeric']	'Must be a number'
min:n	Min length	['min:5']	'Must be at least 5 characters'
max:n	Max length	['max:50']	'Must not exceed 50 characters'
min_uppercase:n	Min uppercase letters	['min_uppercase:1']	'Must contain at least 1 uppercase letter'
min_lowercase:n	Min lowercase letters	['min_lowercase:1']	'Must contain at least 1 lowercase letter'
min_special:n	Min special chars	['min_special:1']	'Must contain at least 1 special character'
min_numeric:n	Min numbers	['min_numeric:1']	'Must contain at least 1 number'

Examples

User Registration

const rules = {
  username: ['required', 'min:3', 'max:50'],
  email: ['required', 'email'],
  password: [
    'required',
    'min:8',
    'min_uppercase:1',
    'min_lowercase:1', 
    'min_special:1',
    'min_numeric:1'
  ]
}

Profile Form

const rules = {
  displayName: ['required', 'min:2'],
  website: ['url'],
  bio: ['max:500']
}

Login Form

const rules = {
  email: ['required', 'email'],
  password: ['required']
}

Error Handling

The validation result will be one of two types:

Success Case

When all validations pass, you get:

{
  valid: true,
  values: {
    username: "johndoe",
    email: "john@example.com",
    password: "SecureP@ss123"
  }
}

Error Case

When validation fails, you get detailed error messages for each field:

{
  valid: false,
  errors: {
    email: "Invalid email address",
    password: "Must contain at least 1 uppercase letter",
    username: "Must be at least 3 characters"
  }
}

Working with Errors

You can easily handle validation errors in your forms:

const result = validateForm(formData, rules)

if (!result.valid) {
  // Handle validation errors
  Object.entries(result.errors).forEach(([field, error]) => {
    console.log(`${field}: ${error}`)
    // Update your form UI to show errors
  })
} else {
  // All good! Process the valid data
  submitForm(result.values)
}

Development

# Clone the repo
git clone https://github.com/1JOAT/js-formx.git

# Install dependencies
npm install

# Run tests
npm test

# Build package
npm run build

Contributing

Pull requests are welcome! Please make sure to:

1. Add tests for new features
2. Update documentation for API changes
3. Run tests before submitting

License

MIT © JOAT