EasyParams

Maintainability Code Coverage Gem Version

Provides an easy way to define structure, validation rules, type coercion, and default values for any hash-like structure. It's built on top of ActiveModel.

Types

Available types: integer, decimal, float, bool, string, array, date, datetime, time

Registering Custom Types

You can register custom types using EasyParams.register_type:

# Register a weight type that converts between units
EasyParams.register_type :weight do |value|
  case value.to_s.downcase
  when /^(\d+(?:\.\d+)?)\s*kg$/i
    $1.to_f
  when /^(\d+(?:\.\d+)?)\s*lbs?$/i
    $1.to_f * 0.453592  # Convert pounds to kg
  when /^(\d+(?:\.\d+)?)\s*g$/i
    $1.to_f / 1000.0  # Convert grams to kg
  else
    value.to_f
  end
end

# Now you can use the weight type in your params classes
class PersonParams < EasyParams::Base
  weight :mass, presence: true
  weight :target_weight, default: 70.0
  array :weights, of: :weight, default: [65.0, 70.0]
end

# Usage
person = PersonParams.new(mass: '75.5 kg', target_weight: '165 lbs')
# person.mass = 75.5
# person.target_weight ≈ 74.84 (converted from lbs to kg)

Custom types work with all EasyParams features including validation, arrays, nested structures, and inheritance.

Installation

Add this line to your application's Gemfile:

gem 'easy_params'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install easy_params

Usage

To define attribute we have a set of methods which match types list. Ex.

integer(param_name, default: nil, normalize: nil, **validations)
  • :default provides a value to return if we get nil as input or there were errors during coercion.
  • :normalize is a Proc or lambda that accepts a single argument and transforms it. It gets called before coercion.
  • validations mimic ActiveModel validations; can be any supported validation, e.g., presence: true, numericality: { only_integer: true, greater_than: 0 }

In addition, there is a special option for the array type:

  • :of accepts :integer, :decimal, :float, :bool, :string, :date, :datetime, :time (:array is not supported)

There are two special types:

type method to define default
:struct has nil
:array_of_structs each []

Defaults for nested types

  • has (struct): default: must be a Hash. When the input is nil, the nested struct is instantiated with that hash; otherwise the provided input is used. If no default: is given and the input is nil, the value will be nil.
  has :shipping_address, default: { country: 'US' } do
    string :country, default: 'US'
    string :city
  end
  • each (array_of_structs): default: should be an Array (typically an array of hashes). When the input is nil, the collection defaults to an empty array []. If you provide a default array, each element will be coerced into the nested struct.
  each :items, default: [{ qty: 1 }] do
    integer :qty, default: 1
  end
  • Override precedence: Container-level defaults override attribute-level defaults for the same keys. Attribute defaults apply only when the key is absent (or nil) in the provided default/input.
  has :user, default: { role: 'admin' } do
    string :role, default: 'guest'
    string :name, default: 'Anonymous'
  end
  # input: nil => role: 'admin', name: 'Anonymous'

  each :items, default: [{ qty: 2 }, {}] do
    integer :qty, default: 1
  end
  # input: nil => items.map(&:qty) == [2, 1]

Schema Extension

You can dynamically extend nested schema definitions using the #{param_name}_schema method. This creates a subclass of the original schema that replaces the parent class in the schema, allowing you to add validations, methods, or modify attributes at runtime.

class PostParams < EasyParams::Base
  has :post, default: {} do
    integer :id
    string :title
    string :content
    date :published_at, default: Date.today
  end
end

# Extend with additional validations and methods
PostParams.post_schema do
  validates :title, :content, presence: true, if: :published?

  def published?
    published_at.present?
  end
end

# Now the validation will run conditionally
params = PostParams.new(id: 1)
params.valid? # => false (because published_at has default value, so published? returns true)

You can also extend collection schemas:

class CommentParams < EasyParams::Base
  each :comments, default: [{}, {}] do
    integer :post_id
    string :author
    string :text
  end
end

# Extend with additional attributes and validations
CommentParams.comments_schema do
  string :author, default: 'Anonymous'
  date :created_at, default: Date.today
  validates :post_id, presence: true
end

# Default values are preserved and merged with input
params = CommentParams.new({})
params.comments.size # => 2
params.comments.first.author # => 'Anonymous'
params.comments.first.created_at # => Date.today

Key Features:

  • Preserves defaults: Original default values are maintained when extending schemas
  • Runtime flexibility: Add validations and methods by creating subclasses dynamically
  • Replaces parent: The new subclass completely replaces the original schema class
  • Collection support: Works with both has (struct) and each (collection) parameters

Validation errors

# app/params/api/v2/icqa/move_params.rb
class Api::V1::Carts::MoveParams < EasyParams::Base
  integer :receive_cart_id, presence: { message: "can't be blank" }
  bool :i_am_sure
  string :location_code, default: '', presence: { message: "can't be blank" }
  has :section do
    string :from
    string :to
  end
  array :variant_ids, of: :integer
  each :options do
    integer :option_type_count, presence: { message: "can't be blank" }
    integer :option_type_value, presence: { message: "can't be blank" }
  end
end

Validation messages for nested attributes a set on top level and each nested object has errors set. Errors will look like this.

{
  :"sections[0].id"=>an_instance_of(Array),
  :"sections[0].post.id"=>an_instance_of(Array),
  :"post.id"=>an_instance_of(Array),
  :"post.sections[0].id"=>an_instance_of(Array)
 }

More examples here params_spec.rb

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at github.com/andriy-baran/easy_params. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the EasyParams project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.