Valdi

View Source

Build Status Coverage Status Hex Version docs

A comprehensive Elixir data validation library with flexible, composable validators

Installation

The package can be installed by adding valdi to your list of dependencies in mix.exs:

def deps do
  [
    {:valdi, "~> 0.5.0"}
  ]
end

Document can be found at https://hexdocs.pm/valdi.

Features

  • ✅ Type validation - validate data types including numbers, strings, lists, maps, structs, and Decimal types
  • ✅ Constraint validation - validate ranges, lengths, formats, and inclusion/exclusion
  • ✅ Flattened validators - use convenient aliases like min, max, min_length without nesting
  • ✅ Pattern matching - efficient validation dispatch using Elixir's pattern matching
  • ✅ Composable - combine multiple validations in a single call
  • ✅ Backward compatible - works with existing validation patterns
  • ✅ Conditional type checking - skip type validation when not needed for better performance
  • ✅ List and map validation - validate collections and structured data
  • ✅ Custom validators - extend with your own validation functions
  • ✅ Flexible error handling - option to ignore unknown validators

Quick Start

Basic Validation

# Type validation
Valdi.validate("hello", type: :string)
#=> :ok

# Constraint validation without type checking (new!)
Valdi.validate("hello", min_length: 3, max_length: 10)
#=> :ok

# Combined validations
Valdi.validate(15, type: :integer, min: 10, max: 20, greater_than: 5)
#=> :ok

Flattened Validators (New!)

Instead of nested syntax:

# Old nested approach
Valdi.validate("test", type: :string, length: [min: 3, max: 10])
Valdi.validate(15, type: :integer, number: [min: 10, max: 20])

Use convenient flattened syntax:

# New flattened approach
Valdi.validate("test", type: :string, min_length: 3, max_length: 10)
Valdi.validate(15, type: :integer, min: 10, max: 20)

# Mix both styles
Valdi.validate(15, min: 10, number: [max: 20])

List Validation

# Validate each item in a list
Valdi.validate_list([1, 2, 3], type: :integer, min: 0)
#=> :ok

# With errors showing item indexes
Valdi.validate_list([1, 2, 3], type: :integer, min: 2)
#=> {:error, [[0, "must be greater than or equal to 2"]]}

Map Validation

# Define validation schema
schema = %{
  name: [type: :string, required: true, min_length: 2],
  age: [type: :integer, min: 0, max: 150],
  email: [type: :string, format: ~r/.+@.+/]
}

# Validate map data
Valdi.validate_map(%{name: "John", age: 30, email: "john@example.com"}, schema)
#=> :ok

Valdi.validate_map(%{name: "J", age: 30}, schema)
#=> {:error, %{name: "length must be greater than or equal to 2"}}

Individual Validators

Each validator can be used independently:

Valdi.validate_type("hello", :string)
#=> :ok

Valdi.validate_number(15, min: 10, max: 20)
#=> :ok

Valdi.validate_length("hello", min: 3, max: 10)
#=> :ok

Valdi.validate_inclusion("red", ["red", "green", "blue"])
#=> :ok

Available Validators

Core Validators

  • type - validate data type
  • required - ensure value is not nil
  • format/pattern - regex pattern matching
  • in/enum - value inclusion validation
  • not_in - value exclusion validation
  • func - custom validation function

Numeric Validators

  • number - numeric constraints (nested syntax)
  • min - minimum value (≥)
  • max - maximum value (≤)
  • greater_than - strictly greater than (>)
  • less_than - strictly less than (<)

Length Validators

  • length - length constraints (nested syntax)
  • min_length - minimum length
  • max_length - maximum length
  • min_items - minimum array items (alias for min_length)
  • max_items - maximum array items (alias for max_length)

Other Validators

  • each - validate each item in arrays
  • decimal - decimal validation (deprecated, use number instead)

Supported Data Types

Built-in types:

  • :boolean, :integer, :float, :number (int or float)
  • :string, :binary (string is binary alias)
  • :tuple, :array, :list, :atom, :function, :map
  • :date, :time, :datetime, :naive_datetime, :utc_datetime
  • :keyword, :decimal

Extended types:

  • {:array, type} - typed arrays (e.g., {:array, :string})
  • struct modules (e.g., User for %User{} structs)
# Type validation examples
Valdi.validate(["one", "two", "three"], type: {:array, :string})
#=> :ok

Valdi.validate(%User{name: "John"}, type: User)
#=> :ok

Valdi.validate(~D[2023-10-11], type: :date)
#=> :ok

Options

  • ignore_unknown: true - skip unknown validators instead of returning errors
Valdi.validate("test", [type: :string, unknown_validator: :value], ignore_unknown: true)
#=> :ok

Documentation

For detailed documentation, examples, and API reference, visit https://hexdocs.pm/valdi.