payload 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c9e68c664efe4b32e13624aa82380db246b9774e
-  data.tar.gz: 4cf13b1014a69ec3d3faeb9d1e0fea439c33bb83
+  metadata.gz: 4b38f94a64e5378a8c51ffdccd8c4ac628328b12
+  data.tar.gz: 2280162582b264eb331e86d9f22807bfb28ae982
 SHA512:
-  metadata.gz: 6ca9dcd639d3c26d9f9e0598343dc0f83ed702ac303206788bbee9505240e5a4b357823a9395f1cb84ada129c4125117cfb0c3f89fd66238ca9999864d2c8876
-  data.tar.gz: 88b884efc4ebd0555b7eda0edaea9a2310d01f184ffa9a57c90a3803f9be557840926dbcb2c4b34579be973882d2853e5e3766eac3186b7f181f0d615605e0ba
+  metadata.gz: 4d5a63f30de48e69c265ad11e51567113532a5ed3f23d7548612d2afa3247c8a415e4bcc5c20667afdc86257f6cf0285312b371ca4d78942a9da398eafa17f9e
+  data.tar.gz: 67d2bacd4a2229145974e8cf41e88d0641514865666e2af27c24a074464349f10289a4f9b4c213a356eb90abb057e0892fabcbc03b908aff1a9899572a398b17

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    payload (0.1.0)
+    payload (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,10 +1,12 @@
 # Payload
 
 Payload is a lightweight framework for specifying, injecting, and using
-dependencies. It facilitates run-time assembly of dependencies and makes it
-plausible to use inversion of control beyond the controller level. It also
-attempts to remove boilerplate code for common patterns such as defining
-factories and applying decorators.
+dependencies in Ruby on Rails applications. It facilitates run-time assembly of
+dependencies and makes it plausible to use [inversion of control] beyond the
+controller level. It also attempts to remove boilerplate code for common
+patterns such as defining factories and applying decorators.
+
+[inversion of control]: http://martinfowler.com/articles/injection.html
 
 Overview
 --------
@@ -13,74 +15,95 @@ The framework makes it easy to define dependencies from application code without
 resorting to singletons, constants, or globals. It also won't cause any
 class-reloading issues during development.
 
+The central object in the framework is a "container." Dependencies are specified
+using Ruby configuration files. Configured dependencies are then available
+anywhere a reference to the container is available.
+
 Define simple dependencies in `config/dependencies.rb` using services:
 
-    service :payment_client do |container|
-      PaymentClient.new(ENV['PAYMENT_HOST'])
-    end
+```ruby
+service :payment_client do |container|
+  PaymentClient.new(ENV['PAYMENT_HOST'])
+end
+```
 
-You can inject dependencies into controllers.
+The configuration block receives a reference to the container, which will
+contain all configured dependencies. This makes it possible to define
+dependencies without knowing how or when their sub-dependencies will be defined.
+
+Controllers receive a reference named `dependencies`, so you can easily inject
+dependencies into controllers.
 
 For example, in `app/controllers/payments_controller.rb`:
 
-    class PaymentsController < ApplicationController
-      def create
-        payment = Payment.new(params[:payment], dependencies[:payment_client])
-        receipt = payment.process
-        redirect_to receipt
-      end
-    end
+```ruby
+class PaymentsController < ApplicationController
+  def create
+    payment = Payment.new(params[:payment], dependencies[:payment_client])
+    receipt = payment.process
+    redirect_to receipt
+  end
+end
+```
 
 You can easily test this dependency in a controller spec:
 
-    describe PaymentsController do
-      describe '#create' do
-        it 'processes a payment' do
-          payment_params = :product_id => '123', amount: '25'
-          client = stub_service(:payment_client)
-          payment = double('payment', process: true)
-          Payment.stub(:new).with(payment_params, client).and_return(payment)
+```ruby
+describe PaymentsController do
+  describe '#create' do
+    it 'processes a payment' do
+      payment_params = { product_id: '123', amount: '25' }
+      client = stub_service(:payment_client)
+      payment = double('payment', process: true)
+      Payment.stub(:new).with(payment_params, client).and_return(payment)
 
-          post :create, payment_params
+      post :create, payment_params
 
-          expect(payment).to have_received(:process)
-        end
-      end
+      expect(payment).to have_received(:process)
     end
+  end
+end
+```
 
 You can further invert control and use factories to hide low-level dependencies
 from controllers entirely.
 
 In `config/dependencies.rb`:
 
-    factory :payment do |container|
-      Payment.new(container[:attributes], container[:payment_client])
-    end
+```ruby
+factory :payment do |container|
+  Payment.new(container[:attributes], container[:payment_client])
+end
+```
 
 In `app/controllers/payments_controller.rb`:
 
-    class PaymentsController < ApplicationController
-      def create
-        payment = dependencies[:payment].new(attributes: params[:payment])
-        payment.process
-        redirect_to payment
-      end
-    end
+```ruby
+class PaymentsController < ApplicationController
+  def create
+    payment = dependencies[:payment].new(attributes: params[:payment])
+    payment.process
+    redirect_to payment
+  end
+end
+```
 
 You can also stub factories in tests:
 
-    describe PaymentsController do
-      describe '#create' do
-        it 'processes a payment' do
-          payment_params = :product_id => '123', amount: '25'
-          payment = stub_factory_instance(:payment, attributes: payment_params)
+```ruby
+describe PaymentsController do
+  describe '#create' do
+    it 'processes a payment' do
+      payment_params = { product_id: '123', amount: '25' }
+      payment = stub_factory_instance(:payment, attributes: payment_params)
 
-          post :create, payment_params
+      post :create, payment_params
 
-          expect(payment).to have_received(:process)
-        end
-      end
+      expect(payment).to have_received(:process)
     end
+  end
+end
+```
 
 The controller and its tests are now completely ignorant of `payment_client`,
 and deal only with the collaborator they need: `payment`.
@@ -90,13 +113,17 @@ Setup
 
 Add payload to your Gemfile:
 
-    gem 'payload'
+```ruby
+gem 'payload'
+```
 
 To access dependencies from controllers, include the `Controller` module:
 
-    class ApplicationController < ActionController::Base
-      include Payload::Controller
-    end
+```ruby
+class ApplicationController < ActionController::Base
+  include Payload::Controller
+end
+```
 
 Specifying Dependencies
 -----------------------
@@ -104,33 +131,41 @@ Specifying Dependencies
 Edit `config/dependencies.rb` to specify dependencies.
 
 Use the `service` method to define dependencies which can be fully instantiated
-during application bootup:
+when the application boots:
 
-    service :payment_client do |container|
-      PaymentClient.new(ENV['PAYMENT_HOST'])
-    end
+```ruby
+service :payment_client do |container|
+  PaymentClient.new(ENV['PAYMENT_HOST'])
+end
+```
 
 Other dependencies are accessible from the container:
 
-    service :payment_notifier do |container|
-      PaymentNotifier.new(container[:mailer])
-    end
+```ruby
+service :payment_notifier do |container|
+  PaymentNotifier.new(container[:mailer])
+end
+```
 
 Use the `factory` method to define dependencies which require dependencies from
 the container as well as runtime state which varies per-request:
 
-    factory :payment do |container|
-      Payment.new(container[:attributes], container[:payment_client])
-    end
+```ruby
+factory :payment do |container|
+  Payment.new(container[:attributes], container[:payment_client])
+end
+```
 
 The container for factory definitions contains all dependencies defined on the
 container as well as dependencies provided when instantiating the factory.
 
 Use the `decorate` method to extend or replace a previously defined dependency:
 
-    decorate :payment do |payment, container|
-      NotifyingPayment.new(payment, container[:payment_notifier])
-    end
+```ruby
+decorate :payment do |payment, container|
+  NotifyingPayment.new(payment, container[:payment_notifier])
+end
+```
 
 Decorated dependencies have access to other dependencies through the container,
 as well as the current definition for that dependency.
@@ -144,22 +179,26 @@ controllers and `env[:dependencies]` in the Rack stack.
 
 Use `[]` to access services:
 
-    class PaymentsController < ApplicationController
-      def create
-        dependencies[:payment_client].charge(params[:amount])
-        redirect_to payments_path
-      end
-    end
+```ruby
+class PaymentsController < ApplicationController
+  def create
+    dependencies[:payment_client].charge(params[:amount])
+    redirect_to payments_path
+  end
+end
+```
 
 Use `new` to instantiate dependencies from factories:
 
-    class PaymentsController < ApplicationController
-      def create
-        payment = dependencies[:payment].new(attributes: params[:payment])
-        payment.process
-        redirect_to payment
-      end
-    end
+```ruby
+class PaymentsController < ApplicationController
+  def create
+    payment = dependencies[:payment].new(attributes: params[:payment])
+    payment.process
+    redirect_to payment
+  end
+end
+```
 
 The `new` method accepts a `Hash`. Each element of the `Hash` will be accessible
 from the container in `factory` definitions.
@@ -174,23 +213,25 @@ layer.
 For example, you can specify payment dependencies in
 `config/dependencies/payments.rb`:
 
-    service :payment_client do |container|
-      PaymentClient.new(ENV['PAYMENT_HOST'])
-    end
+```ruby
+service :payment_client do |container|
+  PaymentClient.new(ENV['PAYMENT_HOST'])
+end
 
-    service :payment_notifier do |container|
-      PaymentNotifier.new(container[:mailer])
-    end
+service :payment_notifier do |container|
+  PaymentNotifier.new(container[:mailer])
+end
 
-    factory :payment do |container|
-      Payment.new(container[:attributes], container[:payment_client])
-    end
+factory :payment do |container|
+  Payment.new(container[:attributes], container[:payment_client])
+end
 
-    decorate :payment do |payment, container|
-      NotifyingPayment.new(payment, container[:payment_notifier])
-    end
+decorate :payment do |payment, container|
+  NotifyingPayment.new(payment, container[:payment_notifier])
+end
 
-    export :payment
+export :payment
+```
 
 In this example, the final, decorated `:payment` dependency will be available in
 controllers, but `:payment_client` and `:payment_notifier` will not.
@@ -203,11 +244,13 @@ Testing
 
 To activate testing support, require and mix in the `Testing` module:
 
-    require 'dependencies/testing'
+```ruby
+require 'payload/testing'
 
-    RSpec.configure do |config|
-      config.include Payload::Testing
-    end
+RSpec.configure do |config|
+  config.include Payload::Testing
+end
+```
 
 During integration tests, the fully configured container will be used. During
 controller tests, an empty container will be initialized for each test. Tests

data/lib/payload/container.rb

@@ -1,6 +1,6 @@
 require 'payload/definition_list'
-require 'payload/factory_definition'
-require 'payload/service_definition'
+require 'payload/factory_resolver'
+require 'payload/service_resolver'
 
 module Payload
   # Used for configuring and resolving dependencies.
@@ -25,8 +25,7 @@ module Payload
     # @yield [Container] the resolved container.
     # @yieldreturn the decorated instance.
     def decorate(dependency, &block)
-      decorated = @definitions.find(dependency).decorate(block)
-      define dependency, decorated
+      self.class.new(@definitions.decorate(dependency, block))
     end
 
     # Defines a factory which can be used to instantiate the dependency. Useful
@@ -42,7 +41,7 @@ module Payload
     #   added to the container.
     # @yieldreturn an instance of your dependency.
     def factory(dependency, &block)
-      define dependency, FactoryDefinition.new(block)
+      define dependency, FactoryResolver.new(block)
     end
 
     # Defines a service which can be fully resolved from the container.
@@ -51,7 +50,7 @@ module Payload
     # @yield [Container] the resolved container.
     # @yieldreturn the instantiated service.
     def service(dependency, &block)
-      define dependency, ServiceDefinition.new(block)
+      define dependency, ServiceResolver.new(block)
     end
 
     # Resolves and returns dependency.
@@ -86,11 +85,9 @@ module Payload
 
     private
 
-    # Duplicates this object with the definition at the end of the list.
-    #
     # @api private
-    def define(dependency, definition)
-      self.class.new(@definitions.add(dependency, definition))
+    def define(dependency, resolver)
+      self.class.new(@definitions.add(dependency, resolver))
     end
   end
 end

data/lib/payload/decorator_chain.rb

@@ -6,18 +6,32 @@ module Payload
   #
   # @api private
   class DecoratorChain
+    include Enumerable
+
     def initialize(decorators = [])
       @decorators = decorators
     end
 
     def add(decorator)
-      self.class.new @decorators + [decorator]
+      self.class.new decorators + [decorator]
     end
 
     def decorate(base, container)
-      @decorators.inject(base) do |component, decorator|
+      decorators.inject(base) do |component, decorator|
         decorator.call(component, container)
       end
     end
+
+    def each(&block)
+      decorators.each(&block)
+    end
+
+    def ==(other)
+      other.is_a?(DecoratorChain) && decorators == other.decorators
+    end
+
+    protected
+
+    attr_reader :decorators
   end
 end

data/lib/payload/definition.rb

@@ -0,0 +1,39 @@
+require 'payload/decorator_chain'
+require 'payload/dependency_already_defined_error'
+
+module Payload
+  # Definition for a dependency which can be resolved and decorated.
+  #
+  # Used internally by {DefinitionList}. Use {Container#service} or
+  # {Container#fatory}.
+  #
+  # @api private
+  class Definition
+    def initialize(resolver, decorators = DecoratorChain.new)
+      @resolver = resolver
+      @decorators = decorators
+    end
+
+    def resolve(container)
+      resolver.resolve(container, decorators)
+    end
+
+    def decorate(decorator)
+      self.class.new resolver, decorators.add(decorator)
+    end
+
+    def set(_)
+      raise DependencyAlreadyDefinedError
+    end
+
+    def ==(other)
+      other.is_a?(Definition) &&
+        resolver == other.resolver &&
+        decorators == other.decorators
+    end
+
+    protected
+
+    attr_reader :resolver, :decorators
+  end
+end