little_boxes 0.1.0 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 86e6644930011e5254977f6ab0809cafa6a22696
-  data.tar.gz: bc84eb541accd46a4f35a3eb3e13d51913f489ca
+  metadata.gz: 8d707db9ba1fe89421ed9075a15f9c0de9da1d45
+  data.tar.gz: f70cd242054f28c5aa232d2c0303efb04d7efd40
 SHA512:
-  metadata.gz: efe43b09428af99ed51374d404f2d590ab135cba431fc7d53317d93d304befdb00db1ddb38f65aace6460d0bd684932d88d8cd26e0950e72ee551543eca5d531
-  data.tar.gz: 3fe8e90d9769f77b80b795eb939b5fc4b4779e4c61db4bc7ac6d84861c32824e1cfbc6650b3061f5dc009e415ae2eac4fbcbd8d266b1b521afd83dc243967379
+  metadata.gz: 3eae4e0071fbaa498d6be5b03b08712b78cc99b5e301177034d32166c6f46b6e262f32bd24b706f04f3fe40c43944cdef10aa7228820f0afe5e4b43242496574
+  data.tar.gz: a5f83ed8ee3ded14d79180e49a78d04fcb9b373620860831fc8ab7d807c960b35ec565cdc4c8aaaa446671174b7208a93d2bf2060091c875ed095347dda471cc

data/.gitignore

@@ -1 +1,3 @@
 Gemfile.lock
+*.gem
+tmp/*

data/Gemfile

@@ -3,6 +3,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test, :development do
+  gem 'ruby-prof'
   gem 'rspec'
   gem 'pry'
   gem 'rerun'

data/README.md

@@ -1,6 +1,192 @@
 # LittleBoxes
 
-Dependancy injection framework in Ruby.
+Dependency injection library in Ruby.
+
+## Intro
+
+LittleBoxes allows you to create a _box_ which is capable of providing already
+configured objects that depend among each other.
+
+```ruby
+module MyApp
+  class MainBox
+    include LittleBoxes::Box
+
+    let(:port) { 80 }
+    letc(:server) { Server.new }
+  end
+
+  class Server
+    include LittleBoxes::Configurable
+
+    dependency :port
+  end
+end
+
+box = MyApp::MainBox.new
+# => #<MyApp::MainBox :port, :server>
+
+box.server.port
+# => 80
+```
+
+The `let` keyword provides lazy evaluated dependencies:
+
+```ruby
+class MainBox
+  include LittleBoxes::Box
+
+  let(:redis) do
+    require 'redis'
+    Redis.new
+  end
+end
+
+box = MyApp::MainBox.new
+box.redis
+# => #<MyApp::Redis:0x0055acd05b6350>
+```
+
+Notice that in this situation `require 'redis'` will not evaluated until we
+call `box.redis`. This approach, in opposition to initializers brings two
+benefits:
+
+* Libraries are only loaded when needed. Unused libraries are not loaded.
+I. e. when running only a subset of the tests.
+* There is no need to manually set the order of the initializers, it will be
+resolved at run-time.
+
+Dependencies can rely on other dependencies:
+
+```ruby
+class Publisher
+  attr_accessor :redis
+
+  def initialize(redis: redis)
+    @redis = redis
+  end
+end
+
+class MyApp::MainBox
+  include LittleBoxes::Box
+
+  let(:redis) do
+    require 'redis'
+    Redis.new
+  end
+
+  let(:publisher) do |box|
+    Publisher.new redis: box.redis
+  end
+end
+
+box = MyApp::MainBox.new
+box.publisher
+# => #<MyApp::Publisher:0x0055df32201ae0 @redis=#<MyApp::Redis:0x0055df32201b30>>
+```
+
+However, what kind of dependency injection library would this be if dependencies
+wouldn't be automatically resolved. We can use the `letc` method for that:
+
+
+```ruby
+class Publisher
+  include LittleBoxes::Configurable
+  dependency :redis
+end
+
+class MainBox
+  # ...
+
+  letc(:publisher) { Publisher.new }
+end
+```
+
+Configurable objects accept default values passed as a lambda, which receives
+the box as an argument:
+
+```ruby
+class Server
+  include LittleBoxes::Configurable
+  dependency(:port) { 80 }
+  dependency(:log) { |box| box.logger }
+end
+```
+
+
+If classes instead of instances are your thing, not that I recommend it, the
+`class_depency` will do:
+
+```ruby
+class UsersApi
+  include LittleBoxes::Configurable
+  class_dependency :logger
+end
+
+class MainBox
+  # ...
+  letc(:users_api) { UsersApi }
+end
+```
+
+Working with classes you might find the problem that they tend to be accessed
+directly through the constant, not injected. This totally skips the lazy
+configuration we discussed before.
+
+For those cases we can force the Box to eager-configure such dependency:
+
+```ruby
+class MainBox
+  # ...
+  eager_letc(:users_api) { UsersApi }
+end
+```
+
+Now the class will be configured as soon as you do `MainBox.new`.
+
+Sometimes we don't want the box to memoize our dependencies and we want it
+to execute the lambda each time. This were `get` and `getc` have a role:
+
+
+```ruby
+class MainBox
+  # ...
+  get(:config) { { port: 80 } }
+  getc(:new_server) { Server.new }
+end
+```
+
+Boxes can be nested, allowing to create a better arranged tree of dependencies.
+Very useful as your application grows:
+
+```ruby
+class MainBox
+  box(:users) do
+    letc(:users_api) { UsersApi }
+    let(:logger) { Logger.new('/tmp/users.log') }
+  end
+
+  let(:logger) { Logger.new('/tmp/app.log') }
+end
+```
+
+Notice how in this case, any object inside the `users` box will log to
+`users.log`. Dependencies are resolved recursively up to the root box.
+Throwing a `LittleBoxes::DependencyNotFound` when missing at root level.
+
+To avoid defining a huge single Box file, you can import boxes defined elsewhere:
+
+```ruby
+class UsersBox
+  letc(:users_api) { UsersApi }
+end
+
+class MainBox
+  import UsersBox
+
+  let(:logger) { Logger.new('/tmp/app.log') }
+end
+```
 
 
 ## Contributing
@@ -20,7 +206,6 @@ $ gem bump --version minor       # Bump the gem version to the next minor level
 $ gem bump --version patch       # Bump the gem version to the next patch level (e.g. 0.0.1 to 0.0.2)
 ```
 
-
 ## License
 
 Released under the MIT License.

data/Rakefile

@@ -8,3 +8,7 @@ desc 'Run all specs'
 RSpec::Core::RakeTask.new('spec') do |spec|
   spec.rspec_opts = %w{}
 end
+
+
+require 'little_boxes'
+Dir.glob(LittleBoxes.root_path + 'tasks/*').each { |p| load p }

data/lib/little_boxes.rb

@@ -1,7 +1,13 @@
 module LittleBoxes
-  require 'little_boxes/registry'
-  require 'little_boxes/dependant_registry'
-  Dir.glob(File.dirname(__FILE__) + '/little_boxes/*').each{|p| require p }
+  def self.root_path
+    Pathname.new(__FILE__) + '../..'
+  end
 
-  class MissingDependency < RuntimeError; end
+  def self.lib_path
+    root_path + 'lib'
+  end
+
+  Dir.glob(lib_path + 'little_boxes/*').each{|p| require p }
+
+  DependencyNotFound = Class.new(StandardError)
 end

data/lib/little_boxes/box.rb

@@ -1,19 +1,120 @@
 module LittleBoxes
-  class Box
-    include Registry
+  module Box
+    module ClassMethods
+      def entry_definitions
+        @entry_definitions ||= {}
+      end
 
-    def get
-      self
+      def inspect
+        "#{name}(#{entry_definitions.keys.map(&:inspect).join(", ")})"
+      end
+
+      private
+
+      def import(klass)
+        importable_definitions = klass.entry_definitions
+        entry_definitions.merge!(importable_definitions)
+        importable_definitions.each_key do |name|
+          define_method(name) do
+            @entries[name].value
+          end
+        end
+      end
+
+      def box(name, klass = nil, &block)
+        if klass
+          box_from_klass(name, klass)
+        elsif block_given?
+          inline_box(name, &block)
+        else
+          fail ArgumentError,
+            'Either class or block should be passed as argument'
+        end
+      end
+
+      def box_from_klass(name, klass)
+        eager(name) { |box| klass.new(parent: box) }
+      end
+
+      def inline_box(name, &block)
+        eager(name) do |box|
+          Class.new do
+            include ::LittleBoxes::Box
+
+            instance_eval(&block)
+          end.new(parent: box)
+        end
+      end
+
+      def get(name, options={}, &block)
+        entry_definitions[name] = EntryDefinition.new(name, options, &block)
+          .tap do |entry|
+          define_method(name) do
+            @entries[name].value
+          end
+        end
+      end
+
+      def getc(name, options={}, &block)
+        get(name, options.merge(configure: true), &block)
+      end
+
+      def let(name, options={}, &block)
+        get(name, options.merge(memo: true), &block)
+      end
+
+      def letc(name, options={}, &block)
+        let(name, options.merge(configure: true), &block)
+      end
+
+      def eager(name, options={}, &block)
+        let(name, options.merge(eager: true), &block)
+      end
+
+      def eagerc(name, options={}, &block)
+        eager(name, options.merge(configure: true), &block)
+      end
     end
 
-    def customize name, &block
-      ForwardingDsl.run self[name], &block
+    attr_reader :parent, :entries
+
+    def self.included(klass)
+      klass.extend ClassMethods
+    end
+
+    def [] name
+      entry = @entries[name] ||= (@parent && @parent.entries[name])
+      entry ? entry.value : (parent && parent[name])
+    end
+
+    def inspect
+      "#<#{self.class.name} #{entries.keys.map(&:inspect).join(", ")}>"
+    end
+
+    def method_missing(name, *args, &block)
+      if respond_to?(name)
+        self[name.to_sym]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @parent.respond_to?(name, include_private)
+    end
+
+    private
+
+    def initialize(parent: nil)
+      @parent = parent
+      @entries = entry_definitions.each_with_object({}) do |(k,v), acc|
+        acc[k] = v.for(self)
+      end
+      @entries.values.select(&:eager).each { |e| send(e.name) }
     end
 
-    def box name, &block
-      s = self.class.new parent: self, name: name
-      self[name] = s
-      ForwardingDsl.run s, &block
+    def entry_definitions
+      self.class.entry_definitions
     end
   end
 end

data/lib/little_boxes/configurable.rb

@@ -0,0 +1,66 @@
+module LittleBoxes
+  module Configurable
+    attr_accessor :config
+
+    def initialize(options = {})
+      @config = {}
+
+      options.keys.each do |k|
+        config[k] = options[k]
+      end
+    end
+
+    def configure(&block)
+      yield @config
+      self
+    end
+
+    private
+
+    def self.included(klass)
+      klass.extend ClassMethods
+
+      klass.class_eval do
+        class << self
+          attr_accessor :config
+          instance_variable_set :@config, {}
+        end
+      end
+    end
+
+    module ClassMethods
+      def dependency name, &default_block
+        default_block ||= Proc.new do
+          fail(DependencyNotFound, "Dependency #{name} not found")
+        end
+
+        private
+
+        define_method name do
+          @config[name] ||= default_block.call(@config[:box])
+        end
+      end
+
+      def class_dependency name, &default_block
+        default_block ||= Proc.new do
+          fail(DependencyNotFound, "Dependency #{name} not found")
+        end
+
+        private
+
+        define_singleton_method name do
+          @config[name] ||= default_block.call(@config[:box])
+        end
+
+        define_method name do
+          self.class.config[name] ||= default_block.call(self.class.config[:box])
+        end
+      end
+
+      def configure(&block)
+        yield @config
+        self
+      end
+    end
+  end
+end