substation 0.0.1 → 0.0.2

data/Changelog.md

@@ -0,0 +1,12 @@
+# v0.0.2 2013-05-15
+
+* [BREAKING CHANGE] Creating a dispatcher requires an application env (snusnu)
+
+  * Changes `Substation::Dispatcher.coerce(config)` to `Substation::Dispatcher.coerce(config, env)`
+  * Changes `Substation::Dispatcher#call(name, input, env)` to `Substation::Dispatcher#call(name, input)`
+
+[Compare v0.0.1..v0.0.2](https://github.com/snusnu/substation/compare/v0.0.1...v0.0.2)
+
+# v0.0.1 2013-05-14
+
+First public release

data/README.md

@@ -4,11 +4,13 @@
 [![Build Status](https://secure.travis-ci.org/snusnu/substation.png?branch=master)][travis]
 [![Dependency Status](https://gemnasium.com/snusnu/substation.png)][gemnasium]
 [![Code Climate](https://codeclimate.com/github/snusnu/substation.png)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/snusnu/substation/badge.png?branch=master)][coveralls]
 
 [gem]: https://rubygems.org/gems/substation
 [travis]: https://travis-ci.org/snusnu/substation
 [gemnasium]: https://gemnasium.com/snusnu/substation
 [codeclimate]: https://codeclimate.com/github/snusnu/substation
+[coveralls]: https://coveralls.io/r/snusnu/substation
 
 `substation` can be thought of as a domain level request router. It assumes
 that every usecase in your application has a name and is implemented in a dedicated
@@ -29,9 +31,9 @@ addition to that, `response.success?` is available and will indicate
 wether invoking the action was successful or not.
 
 `Substation::Dispatcher` stores a mapping of action names to the actual
-objects implementing the action. Clients can use
-`Substation::Dispatcher#call(name, input, env)` to dispatch to any
-registered action. For example, a web application could map an http
+objects implementing the action, as well as the application environment.
+Clients can use `Substation::Dispatcher#call(name, input)` to dispatch to
+any registered action. For example, a web application could map an http
 route to a specific action name and pass relevant http params on to the
 action.
 
@@ -191,14 +193,16 @@ For this purpose, we can instantiate a `Substation::Dispatcher` and hand
 it a configuration hash that describes the various actions by giving
 them a name, a class that's responsible for implementing the actual
 usecase, and a list of `0..n` observers that should be invoked depending
-on the action response.
+on the action response. In addition to that, we must pass an instance of
+the application's environment. More about application environments can
+be found in the next paragraph.
 
 An example configuration for an action without any observers:
 
 ```ruby
 dispatcher = Substation::Dispatcher.coerce({
   'some_use_case' => { 'action' => 'App::SomeUseCase' }
-})
+}, env)
 ```
 
 An example configuration for an action with one observer:
@@ -209,7 +213,7 @@ dispatcher = Substation::Dispatcher.coerce({
     'action'   => 'App::SomeUseCase',
     'observer' => 'App::SomeUseCaseObserver'
   }
-})
+}, env)
 ```
 
 An example configuration for an action with multiple observers:
@@ -223,7 +227,7 @@ dispatcher = Substation::Dispatcher.coerce({
       'App::AnotherObserver'
     ]
   }
-})
+}, env)
 ```
 
 The above configuration examples are tailored towards being read from a
@@ -240,7 +244,7 @@ dispatcher = Substation::Dispatcher.coerce({
     :action   => App::SomeUseCase,
     :observer => App::SomeUseCaseObserver
   }
-})
+}, env)
 ```
 
 An example configuration using symbol keys and procs for handlers:
@@ -251,7 +255,7 @@ dispatcher = Substation::Dispatcher.coerce({
     :action   => Proc.new { |request| request.success(:foo) },
     :observer => Proc.new { |response| do_something }
   }
-})
+}, env)
 ```
 
 
@@ -262,8 +266,8 @@ the course of performing a usecase (like a logger or a storage engine
 abstraction), you can encapsulate these objects within an application
 specific environment object, and send that along to every action.
 
-Here's a simple example with an environment that encapsulates a logger,
-an artificial storage abstraction object and the dispatcher itself.
+Here's a simple example with an environment that encapsulates a logger
+and an artificial storage abstraction object.
 
 The example builds on top of the application specific action baseclass
 shown above:
@@ -272,13 +276,10 @@ shown above:
 module App
   class Environment
     attr_reader :storage
-    attr_reader :dispatcher
     attr_reader :logger
 
-    def initialize(storage, dispatcher, logger)
-      @storage    = storage
-      @dispatcher = dispatcher
-      @logger     = logger
+    def initialize(storage, logger)
+      @storage, @logger = storage, logger
     end
   end
 
@@ -309,12 +310,12 @@ module App
   end
 end
 
+storage = App::Storage.new # some storage abstraction
+env     = App::Environment.new(storage, Logger.new($stdout))
+
 dispatcher = Substation::Dispatcher.coerce({
   'some_use_case' => { 'action' => 'App::SomeUseCase' }
-})
-
-storage = App::Storage.new # some storage abstraction
-env     = App::Environment.new(storage, dispatcher, Logger.new($stdout))
+}, env)
 
 # :some_input is no person, db.save_person will fail
 response = dispatcher.call(:some_use_case, :some_input, env)

data/config/flay.yml

@@ -1,3 +1,3 @@
 ---
 threshold: 6
-total_score: 51
+total_score: 46

data/lib/substation/dispatcher.rb

@@ -60,11 +60,37 @@ module Substation
 
     # Coerce the given +config+ to a {Dispatcher} instance
     #
+    # @example setup code for all the other examples
+    #
+    #   module App
+    #     class Environment
+    #       def initialize(storage, logger)
+    #         @storage, @logger = storage, logger
+    #       end
+    #     end
+    #
+    #     class SomeUseCase
+    #       def self.call(request)
+    #         data = perform_work
+    #         request.success(data)
+    #       end
+    #     end
+    #
+    #     class SomeObserver
+    #       def self.call(response)
+    #         # do something
+    #       end
+    #     end
+    #   end
+    #
+    #   storage = SomeStorageAbstraction.new
+    #   env     = App::Environment.new(storage, Logger.new($stdout))
+    #
     # @example without observers
     #
     #   dispatcher = Substation::Dispatcher.coerce({
     #     'some_use_case' => { 'action' => 'SomeUseCase' }
-    #   })
+    #   }, env)
     #
     # @example with a single observer
     #
@@ -73,7 +99,7 @@ module Substation
     #       'action' => 'SomeUseCase',
     #       'observer' => 'SomeObserver'
     #     }
-    #   })
+    #   }, env)
     #
     # @example with multiple observers
     #
@@ -85,31 +111,16 @@ module Substation
     #         'AnotherObserver'
     #       ]
     #     }
-    #   })
+    #   }, env)
     #
     # @example with Symbol keys and const handlers
     #
-    #   module App
-    #     class SomeUseCase
-    #       def self.call(request)
-    #         data = perform_work
-    #         request.success(data)
-    #       end
-    #     end
-    #
-    #     class SomeObserver
-    #       def self.call(response)
-    #         # do something
-    #       end
-    #     end
-    #   end
-    #
     #   dispatcher = Substation::Dispatcher.coerce({
     #     :some_use_case => {
     #       :action   => App::SomeUseCase,
     #       :observer => App::SomeObserver
     #     }
-    #   })
+    #   }, env)
     #
     # @example with Symbol keys and proc handlers
     #
@@ -118,11 +129,14 @@ module Substation
     #       :action   => Proc.new { |request| request.success(:foo) },
     #       :observer => Proc.new { |response| do_something }
     #     }
-    #   })
+    #   }, env)
     #
     # @param [Hash<#to_sym, Object>] config
     #   the action configuration
     #
+    # @param [Object] env
+    #   the application environment
+    #
     # @return [Dispatcher]
     #   the coerced instance
     #
@@ -133,8 +147,8 @@ module Substation
     #   if action or observer handlers are not coercible
     #
     # @api public
-    def self.coerce(config)
-      new(normalize_config(config))
+    def self.coerce(config, env)
+      new(normalize_config(config), env)
     end
 
     # Normalize the given +config+
@@ -160,7 +174,7 @@ module Substation
 
     private_class_method :normalize_config
 
-    include Concord.new(:actions)
+    include Concord.new(:actions, :env)
     include Adamantium
 
     # Invoke the action identified by +name+
@@ -169,8 +183,8 @@ module Substation
     #
     #   module App
     #     class Environment
-    #       def initialize(dispatcher, logger)
-    #         @dispatcher, @logger = dispatcher, logger
+    #       def initialize(storage, logger)
+    #         @storage, @logger = storage, logger
     #       end
     #     end
     #
@@ -182,11 +196,10 @@ module Substation
     #     end
     #   end
     #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     :some_use_case => { :action => App::SomeUseCase }
-    #   })
-    #
-    #   env = App::Environment.new(dispatcher, Logger.new($stdout))
+    #   storage    = SomeStorageAbstraction.new
+    #   env        = App::Environment.new(storage, Logger.new($stdout))
+    #   config     = { :some_use_case => { :action => App::SomeUseCase } }
+    #   dispatcher = Substation::Dispatcher.coerce(config, env)
     #
     #   response = dispatcher.call(:some_use_case, :some_input, env)
     #   response.success? # => true
@@ -197,9 +210,6 @@ module Substation
     # @param [Object] input
     #   the input model instance to pass to the action
     #
-    # @param [Object] env
-    #   the application environment
-    #
     # @return [Response]
     #   the response returned when calling the action
     #
@@ -207,7 +217,7 @@ module Substation
     #   if no action is registered for +name+
     #
     # @api public
-    def call(name, input, env)
+    def call(name, input)
       fetch(name).call(Request.new(env, input))
     end
 
@@ -216,6 +226,12 @@ module Substation
     # @example
     #
     #   module App
+    #     class Environment
+    #       def initialize(storage, logger)
+    #         @storage, @logger = storage, logger
+    #       end
+    #     end
+    #
     #     class SomeUseCase
     #       def self.call(request)
     #         data = perform_work
@@ -224,9 +240,10 @@ module Substation
     #     end
     #   end
     #
-    #   dispatcher = Substation::Dispatcher.coerce({
-    #     :some_use_case => { :action => App::SomeUseCase }
-    #   })
+    #   storage    = SomeStorageAbstraction.new
+    #   env        = App::Environment.new(storage, Logger.new($stdout))
+    #   config     = { :some_use_case => { :action => App::SomeUseCase } }
+    #   dispatcher = Substation::Dispatcher.coerce(config, env)
     #
     #   dispatcher.action_names # => #<Set: {:some_use_case}>
     #

data/lib/substation/version.rb

@@ -1,4 +1,4 @@
 module Substation
   # Gem version
-  VERSION = '0.0.1'.freeze
+  VERSION = '0.0.2'.freeze
 end

data/spec/spec_helper.rb

@@ -1,4 +1,3 @@
-require 'substation'
 require 'devtools/spec_helper'
 
 module Spec
@@ -28,6 +27,25 @@ module Spec
 
 end
 
+if ENV['COVERAGE'] == 'true'
+  require 'simplecov'
+  require 'coveralls'
+
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+    SimpleCov::Formatter::HTMLFormatter,
+    Coveralls::SimpleCov::Formatter
+  ]
+
+  SimpleCov.start do
+    command_name     'spec:unit'
+    add_filter       'config'
+    add_filter       'spec'
+    minimum_coverage 100
+  end
+end
+
+require 'substation'
+
 include Substation
 
 RSpec.configure do |config|

data/spec/unit/substation/dispatcher/action_names_spec.rb

@@ -6,8 +6,9 @@ describe Dispatcher, '#action_names' do
 
   subject { object.action_names }
 
-  let(:object) { described_class.new(config) }
+  let(:object) { described_class.new(config, env) }
   let(:config) { { :test => { :action => Spec::Action::Success } } }
+  let(:env)    { mock }
 
   it { should eql(Set[ :test ]) }
 end

data/spec/unit/substation/dispatcher/call_spec.rb

@@ -4,9 +4,9 @@ require 'spec_helper'
 
 describe Dispatcher, '#call' do
 
-  subject { object.call(action_name, input, env) }
+  subject { object.call(action_name, input) }
 
-  let(:object)  { described_class.coerce(config)                        }
+  let(:object)  { described_class.coerce(config, env) }
   let(:config)  { { 'test' => { 'action' => 'Spec::Action::Success' } } }
   let(:request) { Request.new(env, input) }
   let(:input)   { mock }

data/spec/unit/substation/dispatcher/class_methods/coerce_spec.rb

@@ -4,15 +4,17 @@ require 'spec_helper'
 
 describe Dispatcher, '.coerce' do
 
-  subject { described_class.coerce(config) }
+  subject { described_class.coerce(config, env) }
 
   let(:config) {{
     'test' => { 'action' => 'Spec::Action::Success' }
   }}
 
+  let(:env) { mock }
+
   let(:coerced) {{
     :test => described_class::Action.coerce(:action => 'Spec::Action::Success')
   }}
 
-  it { should eql(described_class.new(coerced)) }
+  it { should eql(described_class.new(coerced, env)) }
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: substation
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-14 00:00:00.000000000 Z
+date: 2013-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: adamantium
@@ -105,6 +105,7 @@ files:
 - .rspec
 - .rvmrc
 - .travis.yml
+- Changelog.md
 - Gemfile
 - Gemfile.devtools
 - Guardfile