README.md in lite-service-1.0.1 vs README.md in lite-service-1.0.2
- old
+ new
@@ -1,11 +1,12 @@
# Lite::Service
[](http://badge.fury.io/rb/lite-service)
[](https://travis-ci.org/drexed/lite-service)
-Lite::Service provides an API for building service objects.
+Lite::Service provides an API for building command based service objects.
+It also has mixins for handling errors and memoization.
## Installation
Add this line to your application's Gemfile:
@@ -22,97 +23,141 @@
$ gem install lite-service
## Table of Contents
* [Setup](#setup)
-* [Usage](#usage)
+* [Base](#base)
+* [Errors](#errors)
+* [Memoize](#memoize)
## Setup
Setting up the service object is very easy and provides a high level API for memoizing pre-resulted
values and for surfacing errors.
-Learn more about using memoization subclass in [Lite::Memoize](https://github.com/drexed/lite-memoize)
-and errors subclass [Lite::Errors](https://github.com/drexed/lite-errors).
-
```ruby
-class SearchMovies < Lite::Service::Command
+class SearchMovies < Lite::Service::Base
def initialize(name)
@name = name
end
- # NOTE: This method is required to call the command
- def run
+ # NOTE: This method is required
+ def command
{ generate_fingerprint => movies_by_name }
end
private
def movies_by_name
- cache.memoize { HTTP.get("http://movies.com?title=#{title}") }
+ HTTP.get("http://movies.com?title=#{title}")
end
def generate_fingerprint
- Digest::MD5.hexdigest(find_by_name)
- rescue
- errors.add(:fingerprint, 'invalid movie name')
+ Digest::MD5.hexdigest(movies_by_name)
end
end
```
-## Usage
-
**Caller**
```ruby
service = SearchMovies.new('Toy Story')
service.called? #=> false
service.call #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
service.called? #=> true
-service.run #=> Returns a fresh uncached value
# or
service = SearchMovies.call('Toy Story')
service.called? #=> true
+service.call #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
+```
+
+**Result**
+
+```ruby
+service = SearchMovies.new('Toy Story')
+service.result #=> nil
+
+service.call #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
service.result #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
+
+service.recall! #=> Clears the call, cache, errors, and then re-performs the call
+service.result #=> { 'fingerprint_2' => [ 'Toy Story 2', ... ] }
```
-**Cache**
+## Errors (optional)
+Learn more about using [Lite::Errors](https://github.com/drexed/lite-errors)
+
```ruby
-service = SearchMovies.call('Toy Story')
-service.cache #=> Lite::Memoize::Instance object
+class SearchMovies < Lite::Service::Base
+ include Lite::Service::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
```
-**Errors**
+**Methods**
```ruby
service = SearchMovies.call('Toy Story')
+service.errors #=> Lite::Errors::Messages object
+
service.validate! #=> Raises Lite::Service::ValidationError if it has any errors
service.valid? #=> Alias for validate!
-service.errors #=> Lite::Errors::Messages object
service.errored? #=> false
service.success? #=> true
service.failure? #=> Checks that it has been called and has errors
+
+service.result! #=> Raises Lite::Service::ValidationError if it has any errors, if not it returns the result
```
-**Result**
+## Memoize (optional)
+Learn more about using [Lite::Memoize](https://github.com/drexed/lite-memoize)
+
```ruby
-service = SearchMovies.new('Toy Story')
-service.result #=> nil
+class SearchMovies < Lite::Service::Base
+ include Lite::Service::Memoize
-service.call #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
-service.result #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
+ # ... ommited ...
-service.recall! #=> Clears the call, cache, errors, and then re-performs the call
-service.result #=> { 'fingerprint_2' => [ 'Toy Story 2', ... ] }
+ private
-service.result! #=> Raises Lite::Service::ValidationError if it has any errors
+ # 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**
+
+```ruby
+service = SearchMovies.call('Toy Story')
+service.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.