Organ

Forms with integrated validations and attribute coercing.

Introduction

Organ is a small library for manipulating form-based data with validations
attributes coercion.

These forms are very useful for handling HTTP requests where we receive certain
parameters and need to coerce them, validate them and then do something with
them. They are made so that the system has 1 form per service, so the form
names should usually be very explicit of the service they are providing
(CreateUser, DeleteUser, SendTweet, NotifyAdmin).

You should reuse forms behaviour (including validations) through inheritance
or modules (like having CreateUser inherit from UpdateUser). They can be
extended to handle worker jobs, to act as presenters, etc.

They do not handle HTML rendering of forms or do any HTTP manipulation.

The name Organ was inspired by the fact that organs beheave in a module manner
so that they do one thing only.

Usage

A form is simply a class which inherits from Organ::Form. You can specify
the attributes the form will have with the attributes class method.

The attributes class method takes the attribute name and any options that
attribute has.

The options can be:

• :type - The type for which that attribute will be coerced.
• :skip - If true it won’t include the attribute when calling the
  #attributes method on the instance.
• :skip_reader - If true, it won’t create the attribute reader for that
  attribute.

Example:

class CreateCustomer < Organ::Form
  attribute(:name, :type => :string, :trim => true)
  attribute(:address, :type => :string, :trim => true)
  def validate
    validate_presence(:name)
    validate_length(:name, :min => 4, :max => 255)
    validate_length(:address, :max => 255)
    validate_uniqueness(:address) do |addr|
      Customer.where(:address => addr).empty?
    end
  end
  def perform
    Customer.create(attributes)
  end
end
# Sinatra example
post "/customer" do
  form = CreateCustomer.new(params[:customer])
  content_type(:json)
  if form.valid?
    form.perform
    status(204)
  else
    status(422)
    JSON.generate("errors" => form.errors)
  end
end

Default types

The default types you can use are:

:string

Coerces the value into a string or nil if no value given. If the :trim option
is given it also strips the preceding/trailing whitespaces and newlines.

:boolean

Coerces the value into false (if no value given) or true otherwise.

:array

Coerces the value into an Array. If it can’t be coerced into an Array, it
returns an empty Array. An additional :element_type option with another type
can be specifed to coerce all the elements of the array into it.

If a Hash is passed instead of an array, it takes the Hash values.

:float

Coerce the value into a Float, or nil of the value can’t be coerced into a
float.

:hash

Coerces the value into a Hash. If it can’t be coerced into a Hash, it returns
an empty Hash. An additional :key_type and/or :value_type can be specified
to coerce the keys/values of the hash respectively.

:integer

Coerces the value into a Fixnum. If it can’t be coerced it returns nil.

:date

Coerces the value into a date. If the value doesn’t have the %Y-%m-%d format
it returns nil.

Default validations

validate_presence

If the value is falsy or an empty string it appends a :blank error to the
attribute.

validate_uniqueness

If the value is present and the block passed returns false, it appends a
:taken error to the attribute. Example:

validate_uniqueness(:username) do |username|
  User.where(:username => username).empty?
end

validate_email_format

If the value is present and doesn’t match an emails format, it appends an
:invalid error to the attribute.

validate_format

If the value is present and doesn’t match the specified format, it appends an
:invalid error to the attribute.

validate_length

If the value is present and shorter than the :min option, it appends a
:too_short error to the attribute. If it’s longer than the :max option, it
appends a :too_long error to the attribute. Example:

validate_length(:username, :min => 3, :max => 255)
validate_length(:first_name, :max => 255)

validate_inclusion

If the value is present and not included on the given list it appends a
:not_included error to the attribute.

validate_range

If the value is present and less than the :min option, it appends a
:less_than error to the attribute. If it’s greater than the :max option, it
appends a :greater_than error to the attribute. Example:

validate_range(:age, :min => 18)

validation_block

This is a helper method that only calls the given block if the form doesn’t have
any errors. This is particularly useful when some of the validations are costly
to make and unnecessary if the form already has errors.

validate_length(:username, :min => 7)
validation_block do # Will only get called if previous validation passed
  validate_uniqueness(:username) do |username|
    User.where(:username => username).empty?
  end
end

Extensions

These forms were meant to be extended when necessary. These are a few examples
of how they can be extended.

Extensions::Paginate

An extension to paginate results with Sequel Datasets.

module Extensions
  module Presenter
    DEFAULT_PER_PAGE = 30
    MAX_PER_PAGE = 100
    def self.included(base)
      base.attribute(:page, :type => :integer, :skip_reader => true)
      base.attribute(:per_page, :type => :integer, :skip_reader => true)
    end
    def each(&block)
      results.each(&block)
    end
    def total_pages
      @total_pages ||= (1.0 * dataset.count / per_page).ceil
    end
    def any?
      total_pages > 0
    end
    def results
      @results ||= begin
        start = (page - 1) * per_page
        _dataset = dataset.limit(per_page, start)
        _dataset.all
      end
    end
    def per_page
      if @per_page && @per_page >= 1 && per_page <= MAX_PER_PAGE
        @per_page
      else
        DEFAULT_PER_PAGE
      end
    end
    def page
      @page && @page > 1 ? @page : 1
    end
  end
end
module Presenters
  class UserPets < Organ::Form
    include Extensions::Paginate
    attribute(:user_id, :type => :integer)
    def dataset
      Pet.where(:user_id => user_id)
    end
  end
end
# Sinatra app
get "/pets" do
  presenter = Presenter::UserPets.new({
    :user_id => session[:user_id],
    :page => params[:page],
    :per_page => params[:per_page]
  })
  erb(:"pets/index", :locals => { :pets => presenter })
end

Extensions::Worker

An extension to create worker job handlers using
Ost.

module Extensions
  module Worker
    def self.queue_job(attributes)
      queue << JSON.generate(attributes)
    end
    def self.stop
      queue.stop
    end
    def self.watch_queue
      queue.each do |json_str|
        attributes = JSON.parse(json_str)
        new(attributes).perform
      end
    end
    private
    def self.queue
      Ost[self.name]
    end
  end
end
module Workers
  class EmailNotifier < Organ::Form
    include Extensions::Worker
    attribute(:email)
    attribute(:message)
    def perform
      # send message to email...
    end
  end
end
# Sinatra app
get "/queue_email" do
  Workers::EmailNotifier.queue_job(params[:notification])
  status(204)
end

Aknowledgements

This library was inspired mainly by @soveran
Scrivener and was made with the help ofn
@grilix.