payload 0.1.0

data/lib/payload/decorator_chain.rb

@@ -0,0 +1,23 @@
+module Payload
+  # Collects a list of decorators to apply to a component within the context of
+  # a container.
+  #
+  # Used internally by {Container}. Use {Container#decorate}.
+  #
+  # @api private
+  class DecoratorChain
+    def initialize(decorators = [])
+      @decorators = decorators
+    end
+
+    def add(decorator)
+      self.class.new @decorators + [decorator]
+    end
+
+    def decorate(base, container)
+      @decorators.inject(base) do |component, decorator|
+        decorator.call(component, container)
+      end
+    end
+  end
+end

data/lib/payload/definition_list.rb

@@ -0,0 +1,41 @@
+require 'payload/exported_definition'
+require 'payload/undefined_dependency_error'
+
+module Payload
+  # Immutable list of definitions.
+  #
+  # Used internally by {Container} to define and look up definitions.
+  #
+  # @api private
+  class DefinitionList
+    def initialize(definitions = {})
+      @definitions = definitions
+    end
+
+    def add(name, definition)
+      self.class.new(definitions.merge(name => definition))
+    end
+
+    def find(name)
+      definitions.fetch(name) do
+        raise(UndefinedDependencyError, "No definition for dependency: #{name}")
+      end
+    end
+
+    def export(names)
+      exported_definitions = names.inject({}) do |result, name|
+        result.merge! name => ExportedDefinition.new(find(name), self)
+      end
+
+      self.class.new exported_definitions
+    end
+
+    def import(imports)
+      self.class.new definitions.merge(imports.definitions)
+    end
+
+    protected
+
+    attr_reader :definitions
+  end
+end

data/lib/payload/exported_definition.rb

@@ -0,0 +1,19 @@
+module Payload
+  # Decorates a base definition such as {ServiceDefinition} to provide access to
+  # private dependencies in the {Container} from which the definition was
+  # exported.
+  #
+  # Used internally by {DefinitionList}. Use {Container#export}.
+  #
+  # @api private
+  class ExportedDefinition
+    def initialize(definition, private_definitions)
+      @definition = definition
+      @private_definitions = private_definitions
+    end
+
+    def resolve(container)
+      @definition.resolve(container.import(@private_definitions))
+    end
+  end
+end

data/lib/payload/factory.rb

@@ -0,0 +1,33 @@
+module Payload
+  # Returned by {Container#[]} for {Container#factory} definitions.
+  #
+  # Used to add definitions from {#new} to the {Container} and then run the
+  # factory definition block to obtain an instance.
+  #
+  # @see Container#factory Container#factory for defining and using factories.
+  class Factory
+    # Used internally by {FactoryDefinition}.
+    #
+    # @api private
+    def initialize(container, block, decorators)
+      @container = container
+      @block = block
+      @decorators = decorators
+    end
+
+    # @param [Hash] arguments additional dependencies and arguments to resolve
+    #   before invoking the factory definition block.
+    # @return the instance defined by the factory definition block.
+    # @see Container#factory Container#factory for defining and using factories.
+    def new(arguments = {})
+      resolved =
+        arguments.inject(@container) do |container, (argument, value)|
+          container.service(argument) { value }
+        end
+
+      base = @block.call(resolved)
+
+      @decorators.decorate(base, resolved)
+    end
+  end
+end

data/lib/payload/factory_definition.rb

@@ -0,0 +1,24 @@
+require 'payload/decorator_chain'
+require 'payload/factory'
+
+module Payload
+  # Encapsulates logic for resolving factory definitions.
+  #
+  # Used internally by {Container}. Use {Container#factory}.
+  #
+  # @api private
+  class FactoryDefinition
+    def initialize(block, decorators = DecoratorChain.new)
+      @block = block
+      @decorators = decorators
+    end
+
+    def resolve(container)
+      Factory.new(container, @block, @decorators)
+    end
+
+    def decorate(block)
+      self.class.new(@block, @decorators.add(block))
+    end
+  end
+end

data/lib/payload/mutable_container.rb

@@ -0,0 +1,57 @@
+module Payload
+  # Mutable builder for defining dependencies.
+  #
+  # Allows defining dependencies without fear of breaking the chain while still
+  # encapsulating mutation in one location.
+  #
+  # Decorates a {Container} and delegates definition calls.
+  class MutableContainer
+    # Used internally by {RailsLoader} to parse dependency definition files.
+    #
+    # @api private
+    def initialize(container)
+      @container = container
+      @exported_names = []
+    end
+
+    # Delegates to {Container} and uses the returned result as the new
+    # container.
+    # @!method decorate
+    # @!method factory
+    # @!method service
+    def method_missing(*args, &block)
+      @container = @container.send(*args, &block)
+      self
+    end
+
+    # Used internally by {RailsLoader} to return the configured container.
+    #
+    # @api private
+    # @return Container the fully-configured, immutable container.
+    def build
+      @container
+    end
+
+    # Exports dependencies so that they are available in other containers.
+    #
+    # @param names [Array<Symbol>] dependencies to export.
+    def export(*names)
+      @exported_names += names
+    end
+
+    # Returns dependencies specified by previous {#export} invocations.
+    #
+    # Used internally by {RailsLoader}.
+    #
+    # @api private
+    def exports
+      @container.export(*@exported_names)
+    end
+
+    private
+
+    def respond_to_missing?(*args)
+      @container.respond_to?(*args)
+    end
+  end
+end

data/lib/payload/rack_container.rb

@@ -0,0 +1,23 @@
+module Payload
+  # Uses a dependency loader to load dependencies and inject them into the Rack
+  # environment.
+  #
+  # Accepts a Rack application and a block for loading dependencies as a
+  # {Container}. The container will be injected into each Rack request as
+  # +:dependencies+ in the Rack environment.
+  #
+  # Used internally by {Railtie}.
+  #
+  # @api private
+  class RackContainer
+    def initialize(app, &loader)
+      @app = app
+      @loader = loader
+    end
+
+    def call(env)
+      env[:dependencies] = @loader.call.service(:rack_env) { |container| env }
+      @app.call(env)
+    end
+  end
+end

data/lib/payload/rails_loader.rb

@@ -0,0 +1,58 @@
+require 'payload/definition_list'
+require 'payload/container'
+require 'payload/mutable_container'
+
+module Payload
+  # Loads dependencies from config/dependencies.rb in Rails applications.
+  #
+  # Used by {Railtie} to provide a Rails dependency loader to {RackContainer}.
+  class RailsLoader
+    # @api private
+    def self.to_proc
+      lambda { load }
+    end
+
+    # Load dependencies from outside a Rails request.
+    # @example
+    #   RailsLoader.load[:example_service]
+    # @return [Container] dependencies from config/dependencies.rb
+    def self.load
+      new.load
+    end
+
+    # @api private
+    def load
+      namespace_containers.inject(root_container) do |target, source|
+        target.import(source.exports)
+      end
+    end
+
+    private
+
+    def namespace_containers
+      namespace_config_paths.map { |path| load_from(path) }
+    end
+
+    def root_container
+      load_from(root_config_path).build
+    end
+
+    def load_from(path)
+      container = MutableContainer.new(Container.new(DefinitionList.new))
+      container.instance_eval(IO.read(path), path)
+      container
+    end
+
+    def root_config_path
+      config_path.join('dependencies.rb').to_s
+    end
+
+    def namespace_config_paths
+      Dir.glob config_path.join('payload/*.rb').to_s
+    end
+
+    def config_path
+      Rails.root.join('config')
+    end
+  end
+end

data/lib/payload/railtie.rb

@@ -0,0 +1,20 @@
+require 'payload/rack_container'
+require 'payload/rails_loader'
+require 'payload/controller'
+
+module Payload
+  # Automatically loads and injects dependencies into the Rack environment for
+  # Rails applications.
+  #
+  # Requiring this file is enough to:
+  #
+  # * Load dependency definitions from config/dependencies.rb using
+  #   {RailsLoader} and {MutableContainer}.
+  # * Provide a {Container} in each Rack request.
+  class Railtie < ::Rails::Railtie
+    config.app_middleware.use(
+      Payload::RackContainer,
+      &Payload::RailsLoader
+    )
+  end
+end

data/lib/payload/service_definition.rb

@@ -0,0 +1,24 @@
+require 'payload/decorator_chain'
+
+module Payload
+  # Encapsulates logic for resolving service definitions.
+  #
+  # Used internally by {Container}. Use {Container#service}.
+  #
+  # @api private
+  class ServiceDefinition
+    def initialize(block, decorators = DecoratorChain.new)
+      @block = block
+      @decorators = decorators
+    end
+
+    def resolve(container)
+      base = @block.call(container)
+      @decorators.decorate(base, container)
+    end
+
+    def decorate(block)
+      self.class.new(@block, @decorators.add(block))
+    end
+  end
+end

data/lib/payload/testing.rb

@@ -0,0 +1,84 @@
+require 'payload/definition_list'
+require 'payload/container'
+
+module Payload
+  # Helper methods for stubbing and injecting dependencies into unit tests.
+  #
+  # These methods are intended for rspec controller tests and require
+  # rspec-mocks to work as expected. During capybara tests, all dependencies
+  # are available as defined in +config/dependencies.rb+.
+  module Testing
+    # Builds an empty {Container} in the fake Rack environment.
+    #
+    # @api private
+    def setup_controller_request_and_response
+      super
+      @request.env[:dependencies] = build_container
+    end
+
+    # Finds or injects a stubbed factory into the test {Container} and stubs an
+    # instance to be created with the given attributes.
+    #
+    # @param dependency [Symbol] the name of the factory to stub.
+    # @param attributes [Hash] the expected attributes to build the instance.
+    # @return [RSpec::Mocks::TestDouble] the result of the factory, which can
+    #   then have additional stubs or expectations applied to it.
+    def stub_factory_instance(dependency, attributes)
+      factory = stub_factory(dependency)
+      double(dependency.to_s).tap do |double|
+        factory.stub(:new).with(attributes).and_return(double)
+      end
+    end
+
+    # Injects a stubbed factory into the test {Container} and returns it.
+    #
+    # @param dependency [Symbol] the name of the factory to stub.
+    # @return [RSpec::Mocks::TestDouble] the stubbed factory, which can have
+    #   stubs for `new` applied to it.
+    def stub_factory(dependency)
+      dependencies[dependency]
+    rescue Payload::UndefinedDependencyError
+      double("#{dependency} factory").tap do |factory|
+        modify_dependencies do |dependencies|
+          dependencies.service(dependency) do |config|
+            factory
+          end
+        end
+      end
+    end
+
+    # Injects a stubbed service into the test {Container} and returns it.
+    #
+    # @param dependency [Symbol] the name of the service to stub.
+    # @return [RSpec::Mocks::TestDouble] the stubbed service, which can then
+    #   have additional stubs or expectations applied to it.
+    def stub_service(dependency)
+      double(dependency.to_s).tap do |double|
+        modify_dependencies do |dependencies|
+          dependencies.service(dependency) do |config|
+            double
+          end
+        end
+      end
+    end
+
+    # Convenience for injecting a modified container into the test rack session.
+    #
+    # @yield [Container] the container to be modified. The block should return
+    #   the new container.
+    def modify_dependencies
+      @request.env[:dependencies] = yield(dependencies)
+    end
+
+    # @return the current {Container} which will be injected into the test Rack
+    #   session.
+    def dependencies
+      @request.env[:dependencies]
+    end
+
+    # @api private
+    def build_container
+      Container.new
+    end
+  end
+end

data/lib/payload/undefined_dependency_error.rb

@@ -0,0 +1,5 @@
+module Payload
+  # Raised when attempting to resolve an undefined dependency.
+  class UndefinedDependencyError < StandardError
+  end
+end

data/lib/payload/version.rb

@@ -0,0 +1,3 @@
+module Payload
+  VERSION = '0.1.0'
+end

data/payload.gemspec

@@ -0,0 +1,24 @@
+$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+require 'payload/version'
+require 'date'
+
+Gem::Specification.new do |s|
+  s.authors = ['thoughtbot', 'Joe Ferris']
+  s.description = 'Dependency configuration and injection for Ruby and Rails.'
+  s.email = 'support@thoughtbot.com'
+  s.extra_rdoc_files = %w(LICENSE README.md CONTRIBUTING.md)
+  s.files = `git ls-files`.split("\n")
+  s.homepage = 'http://github.com/thoughtbot/payload'
+  s.license = 'MIT'
+  s.name = %q{payload}
+  s.rdoc_options = ['--charset=UTF-8']
+  s.require_paths = ['lib']
+  s.required_ruby_version = Gem::Requirement.new('>= 2.0.0')
+  s.summary = 'Dependency configuration and injection for Ruby and Rails.'
+  s.test_files = `git ls-files -- spec/*`.split("\n")
+  s.version = Payload::VERSION
+
+  s.add_development_dependency 'rack'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec', '~> 2.14.1'
+end