Lite::Commands

Lite::Commands provides an API for building command based service objects. It provides mixins for handling errors and memoization to improve your object workflow productivity.

Installation

Add this line to your application's Gemfile:

gem 'lite-commands'

And then execute:

$ bundle

Or install it yourself as:

$ gem install lite-commands

Table of Contents

• Setup
• Base
• Errors
• Memoize

Setup

Setting up the command based object is very easy using a very simple API for setting up and executing commands.

class SearchMovies < Lite::Commands::Base

  def initialize(name)
    @name = name
  end

  # NOTE: This method is required
  def command
    { generate_fingerprint => movies_by_name }
  end

  private

  def movies_by_name
    HTTP.get("http://movies.com?title=#{title}")
  end

  def generate_fingerprint
    Digest::MD5.hexdigest(movies_by_name)
  end

end

Caller

commands = SearchMovies.new('Toy Story')
commands.called? #=> false
commands.call    #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
commands.called? #=> true

# - or -

commands = SearchMovies.call('Toy Story')
commands.called? #=> true
commands.call    #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }

# - or -

# Useful when you are not using the Errors mixin as its a one time access call.
SearchMovies.run('Toy Story') #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }

Result

commands = SearchMovies.new('Toy Story')
commands.result  #=> nil

commands.call    #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
commands.result  #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }

commands.recall! #=> Clears the call, cache, errors, and then re-performs the call
commands.result  #=> { 'fingerprint_2' => [ 'Toy Story 2', ... ] }

Errors (optional)

Learn more about using Lite::Errors

class SearchMovies < Lite::Commands::Base
  include Lite::Commands::Errors

  # ... ommited ...

  private

  # Add a fingerprint error to the error pool
  def generate_fingerprint
    Digest::MD5.hexdigest(movies_by_name)
  rescue
    errors.add(:fingerprint, 'invalid md5 request value')
  end

end

Caller

# Useful for controllers or actions that depend on states.
SearchMovies.perform('Toy Story') do |result, success, failure|
  success.call { redirect_to(movie_path, notice: "Movie can be found at: #{result}") }
  failure.call { redirect_to(root_path, notice: "Movie cannot be found at: #{result}") }
end

Methods

commands = SearchMovies.call('Toy Story')
commands.errors    #=> Lite::Errors::Messages object

commands.validate! #=> Raises Lite::Commands::ValidationError if it has any errors
commands.valid?    #=> Alias for validate!

commands.errored?  #=> false
commands.success?  #=> true
commands.failure?  #=> Checks that it has been called and has errors
commands.status    #=> :failure

commands.result!   #=> Raises Lite::Commands::ValidationError if it has any errors, if not it returns the result

Memoize (optional)

Learn more about using Lite::Memoize

class SearchMovies < Lite::Commands::Base
  include Lite::Commands::Memoize

  # ... ommited ...

  private

  # Sets the value in the cache
  # Subsequent method calls gets the cached value
  # This saves you the extra external HTTP.get call
  def movies_by_name
    cache.memoize { HTTP.get("http://movies.com?title=#{title}") }
  end

  # Gets the value in the cache
  def generate_fingerprint
    Digest::MD5.hexdigest(movies_by_name)
  end

end

Methods

commands = SearchMovies.call('Toy Story')
commands.cache #=> Lite::Memoize::Instance object

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 https://github.com/[USERNAME]/lite-commands. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant 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 Lite::Commands project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.