Organ

Forms with integrated validations and attribute coercing.

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.

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

The default types you can use are:

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.

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

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.

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

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.

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

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

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

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

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

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

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)

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

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)

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

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

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

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

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