diftw 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e2ca2e3bab186790bc0cb1330edf1060a0beed6f
-  data.tar.gz: 90572c316d59095be4846b9894fac598a9d2138e
+  metadata.gz: 3d520a70920cae29c12a9439e049b090bdc2d23f
+  data.tar.gz: e6c858bbdae7bc242650f6e00497229716590108
 SHA512:
-  metadata.gz: 524edb6efd5b288c937e4de007ab255922e44cb92ee07211bacbbb20ca4473497fdb12b564f2ed07b8114520ab7bad81ab86a7a407eeed06565a5f1944c6df79
-  data.tar.gz: 7cc3dace40aadf417ed602d6e376ab8b8198689bba652591581faa0b7bf58d1bdceeb3b7640ace5169b4ce0e5c68446ae5b7a42260ab2cb6e700617a55a1ea48
+  metadata.gz: 111bddaae6e8b85ad20e83d9f6cf79462c9c6c13de250ed15bb6e47c982d88f702190190bf01668c4945ed033c242dd7bf9df66479a69367d6544fdea54e854b
+  data.tar.gz: 23d75ade4800dd9c22a436c55044f1e3b8577ddb64b37351626d9c857d968137f9a3e620e8e9ee4bee366a9a257db1d21646fa7b8ac46677687cfd3e92c712fa

data/README.md

@@ -1,86 +1,176 @@
 # DiFtw
 
-Dependency Injection For The Win! A small gem for simple, yet flexible, dependency injection in Ruby.
+Dependency Injection For The Win! A small, yet surprisingly powerful, dependency injection library for Ruby.
 
-Some say you don't need DI in Ruby. Perhaps. Others say you don't need a DI *library* in Ruby. Probably true, but only in the pedantic sense that you don't need a DI library for *any* language. But I'll take a nice, idiomatic DI library over "just manually pass in every dependency to all your constructors!" any day. I couldn't find one, so I wrote this.
+**NOTE** This library is pre-1.0 and under active development. It's perfectly usable, but expect breaking API or behavior changes until 1.0.
 
-## Basic Use
+### Why DI in Ruby?
 
-    # Create your injector
-    Injector = DiFtw::Injector.new do
-      # Register some dependencies
+If your only concern is testing, mocks/stubs and `webmock` might be all you need. But if you're working on a large project that hooks into all kinds of enterprisey services, and those services aren't always available in dev/testing/staging, a dash of DI might be just the thing.
+
+### Features
+
+* Dead-simple registration API
+* Lazy injection (by default)
+* Inject into all instances, a single instance, a class, or a module
+* Injects singletons (by default)
+* Uses parent-child injectors for max flexibility
+* Threadsafe, except for registration
+
+## Dead-simple registration API
+
+    # Create your root injector
+    DI = DiFtw::Injector.new do
+      # Register some dependencies in here
       register :foo do
         OpenStruct.new(message: "Foo")
       end
     end
 
-    # Or register them like this
-    Injector.register :bar do
+    # Or register them out here
+    DI.register :bar do
       OpenStruct.new(message: "Bar")
     end
 
-    # Or with a lambda
-    Injector[:baz] = -> { OpenStruct.new(message: "Baz") }
+    # Or register them with procs
+    DI[:baz] = -> { OpenStruct.new(message: "Baz") }
+
+## Lazy injection (by default)
+
+    class Widget
+      include DI.inject :foo, :bar
+    end
+    
+    widget = Widget.new
+    # foo isn't actually injected until it's first called
+    puts widget.foo.message
+    => "Foo"
+
+Lazy injection is usually fine. But if it isn't, use `inject!`:
 
-    # Inject some dependencies into your class
     class Widget
-      include Injector.inject(:foo, :bar)
+      include DI.inject :foo, :bar
       
-      def initialize(random_arg)
-        # Unlike most DI, it doesn't hijack your initializer! Because Ruby!!1!
-        @random_arg = random_arg
+      def initialize
+        inject!
       end
     end
-
-    # Now they're instance methods!
+    
+    # foo and bar are immediately injected
     widget = Widget.new
-    puts widget.bar.message
-    => "Bar"
 
-## Singletons By Default
+## Inject into all instances, a single instance, a class, or a module
+
+    # Inject :baz into all Widget instance objects
+    class Widget
+      include DI.inject :baz
+    end
+    puts Widget.new.baz.message
+    => 'Baz'
+    
+    # Inject :baz into one specific instance
+    x = SomeClass.new
+    DI.inject_instance x, :baz
+    puts x.baz.message
+    => 'Baz'
+    
+    # Inject :baz as a class method
+    class SomeClass
+      DI.inject_instance self, :baz
+    end
+    puts SomeClass.baz.message
+    => 'Baz'
 
-By default the injector injects singletons. Observe:
+    # Inject :baz as a module method 
+    module SomeModule
+      DI.inject_instance self, :baz
+    end
+    puts SomeModule.baz.message
+    => 'Baz'
 
-    widget1, widget2 = Widget.new, Widget.new
-    widget1.bar.object_id == widget1.bar.object_id
-    => true
-    widget1.bar.object_id == widget2.bar.object_id
+## Injects singletons (by default)
+
+    Widget.new.bar.object_id == Widget.new.bar.object_id
     => true
 
-If you *don't* want your injector to return singletons (i.e. get a new copy each time you inject), initialize your injector like this:
+If you *don't* want your injector to return singletons (i.e. get a new copy each time you inject something), initialize your injector like this:
 
-    Injector = DiFtw::Injector.new(singleton: false)
-    Injector[:bar] = -> { OpenStruct.new(message: 'Bar') }
+    DI = DiFtw::Injector.new(singleton: false)
+    DI[:bar] = -> { OpenStruct.new(message: 'Bar') }
     ...
-    widget1, widget2 = Widget.new, Widget.new
-    widget1.bar.object_id == widget1.bar.object_id
-    => true
-    widget1.bar.object_id == widget2.bar.object_id
+    Widget.new.bar.object_id == Widget.new.bar.object_id
     => false
 
 Accessing injected singletons **is thread safe**. However, registering them is not.
 
-## Lazy, Nested Dependencies
+## Parent-Child injectors
+
+This is **maybe the coolest part**. Each time you call `inject` (or `inject_instance`) you're creating a fresh, empty child `DiFtw::Injector`. It will recursively look up dependencies through the parent chain until it finds the nearest registration of that dependency.
 
-    # Define your class and tell it to inject :ab into instances
+This means you can re-register a dependency on your child injector, and *it* will be injected instead of whatever is registered above it in the chain. Objects using sibling or parent injectors will remain unchanged, as they won't know about this registration override. Perhaps some examples are best.
+
+    # Create your root injector and register :foo
+    DI = DiFtw::Injector.new
+    DI[:foo] = -> { 'Foo' }
+    
+    class Widget
+      include DI.inject :foo
+    end
+    
     class Spline
-      include Injector.inject(:ab)
+      include DI.inject :foo
     end
     
-    # Init a Spline instance. Doesn't matter that :ab isn't registered; just don't call spline.ab yet.
-    spline = Spline.new
-
-    # Register :ab, which uses :a and :b. The order you register them in doesn't matter.
-    Injector[:ab] = -> { Injector[:a] + Injector[:b] }
-    Injector[:a] = -> { 'A' }
-    Injector[:b] = -> { 'B' }
-
-    # The :ab dependency isn't actually injected until .ab is called!
-    puts spline.ab
-    => 'AB'
-
-## DI in tests
+    # Widget and Spline each get a new injector instance
+    Widget.injector.object_id != DI.object_id
+    => true
+    Widget.injector.object_id != Spline.injector.object_id
+    => true
+    
+    # Each Widget instance gets a new injector instance. Same for Spline.
+    w1 = Widget.new
+    w1.injector.object_id != Widget.injector.object_id
+    => true
+    
+    w2 = Widget.new
+    w1.injector.object_id != w2.injector.object_id
+    => true
 
-    # Presumably your injector is already initialized.
-    # Simply re-register the dependencies you need for your tests.
-    Injector[:foo] = -> { OpenStruct.new(message: 'Test Foo') }
+    # But all those child injectors are empty. They'll all resolve :foo
+    # to whatever is in DI[:foo]
+    Widget.new.foo
+    => 'Foo'
+    Spline.new.foo
+    => 'Foo'
+    Widget.new.foo.object_id == Spline.new.foo.object_id
+    => true
+    
+    # But we could re-register/override :foo in Spline.injector, and all new
+    # Spline instances would resolve :foo differently.
+    Spline.injector[:foo] = -> { 'Bar' }
+    Spline.new.foo
+    => 'Bar'
+    # But DI and Widget.injector would be unchanged
+    Widget.new.foo
+    => 'Foo'
+    
+    # We can go even further and override :foo in just one specific instance of Spline
+    # NOTE This only works if you're using lazy injection (the default) AND if you haven't called #foo yet
+    s = Spline.new
+    s.injector[:foo] = -> { 'Baz' }
+    s.foo
+    => 'Baz'
+    # Other Spline instances will still get their override from Spline.injector
+    Spline.new.foo
+    => 'Bar'
+    # While Widget instances will all still get the original value from DI
+    Widget.new.foo
+    => 'Foo'
+
+## DI in testing/local dev/staging/etc.
+
+To inject different dependencies in these environments, you have several options. You can simply re-register dependencies in your root injector:
+
+    DI[:foo] = -> { OpenStruct.new(message: 'Test Foo') }
+    
+And you can use the parent-child injector features described above.

data/lib/diftw.rb

@@ -1,2 +1,3 @@
 require 'diftw/injector'
+require 'diftw/builder'
 require 'diftw/version'

data/lib/diftw/builder.rb

@@ -0,0 +1,54 @@
+module DiFtw
+  #
+  # Module for building various things, like other modules.
+  #
+  module Builder
+    #
+    # Builds a new module that, when included in a class, defines instance methods for each dependecy.
+    #
+    # @param parent_injector [DiFtw::Injector] The parent injector
+    # @param dependencies [Symbol] All dependency names you want to inject
+    # @return [Module] A module with accessor methods defined for each dependency
+    #
+    def self.injector_module(parent_injector, dependencies)
+      Module.new {
+        class << self
+          attr_accessor :injector, :_diftw_dependencies
+        end
+
+        def self.included(base)
+          di_mod = self
+          base.class_eval do
+            # Set the injector for the whole class
+            class << self; attr_reader :injector; end
+            @injector = di_mod.injector
+
+            # Create a new injector for each instance
+            define_method :injector do
+              @injector ||= Injector.new(parent: di_mod.injector)
+            end
+
+            # Define a method to eager-inject all dependencies
+            define_method :inject! do
+              di_mod._diftw_dependencies.each do |dep|
+                send dep
+              end
+              nil
+            end
+
+            # Define instance accessor methods
+            di_mod._diftw_dependencies.each do |dep|
+              define_method dep do
+                var = "@_diftw_#{dep}"
+                instance_variable_get(var) || instance_variable_set(var, self.injector[dep])
+              end
+            end
+          end
+        end
+      }.tap { |mod|
+        mod.injector = Injector.new(parent: parent_injector)
+        mod._diftw_dependencies = dependencies
+      }
+    end
+  end
+end

data/lib/diftw/injector.rb

@@ -26,6 +26,8 @@ module DiFtw
   #   end
   #
   class Injector
+    # @return [DiFtw::Injector] The parent injector, if any
+    attr_reader :parent
     # @return [Boolean] If true, the Injector injects singleton objects
     attr_reader :singleton
     # @return [Hash] A Hash containing all registered depencies (as procs) keyed by Symbols
@@ -33,7 +35,8 @@ module DiFtw
     # @return [Hash] A Hash containing a Mutex for each dependency (only if singleton == true)
     attr_reader :mutexes
 
-    private :registry, :mutexes
+    protected :registry, :mutexes
+    private :parent
 
     #
     # Instantiate a new Injector.
@@ -42,9 +45,11 @@ module DiFtw
     #
     # @param singleton [Boolean] If true, each dependency will only be initialized once. When false, it will be initialized each time it's injected.
     #
-    def initialize(singleton: true, &registrator)
-      @registry, @mutexes = {}, {}
-      @singleton = singleton
+    def initialize(singleton: true, parent: nil, &registrator)
+      @registry, @parent = {}, parent
+      @singleton = parent ? parent.singleton : singleton
+      @mutexes = (parent ? parent.mutexes.keys : []).
+        inject({}) { |a, name| a[name] = Mutex.new; a }
       instance_eval &registrator if registrator
     end
 
@@ -62,9 +67,11 @@ module DiFtw
     # @return [Injector] returns the Injector object
     #
     def register(name, y = nil, &block)
-      instance_variable_set "@_singleton_#{name}", nil
       registry[name] = y || block
-      mutexes[name] = Mutex.new if singleton
+      if singleton
+        instance_variable_set "@_singleton_#{name}", nil
+        mutexes[name] ||= Mutex.new
+      end
       self
     end
 
@@ -92,10 +99,10 @@ module DiFtw
       if singleton
         var = "@_singleton_#{name}"
         instance_variable_get(var) || mutexes[name].synchronize {
-          instance_variable_get(var) || instance_variable_set(var, registry.fetch(name).call)
+          instance_variable_get(var) || instance_variable_set(var, resolve!(name))
         }
       else
-        registry.fetch(name).call
+        resolve! name
       end
     end
 
@@ -110,10 +117,7 @@ module DiFtw
     # @param dependencies [Symbol] All dependency names you want to inject.
     #
     def inject(*dependencies)
-      injector_module.tap do |mod|
-        mod._diftw_injector = self
-        mod._diftw_dependencies = dependencies
-      end
+      DiFtw::Builder.injector_module self, dependencies
     end
 
     #
@@ -125,41 +129,25 @@ module DiFtw
     # @param dependencies [Symbol] All dependency names you want to inject.
     #
 	def inject_instance(instance, *dependencies)
-	  injector = self
-	  instance.instance_eval do
-		dependencies.each do |dep|
-		  define_singleton_method dep do
-			var = "@_diftw_#{dep}"
-			instance_variable_get(var) || instance_variable_set(var, injector[dep])
-		  end
-		end
-	  end
+      mod = DiFtw::Builder.injector_module self, dependencies
+      instance.singleton_class.send :include, mod
 	end
 
-    private
+    protected
 
     #
-    # Builds a new module that, when included in a class, defines instance methods for each dependecy.
+    # Recursively look up a dependency
     #
-    # @return a new module
+    # @param dependency [Symbol] name of dependency
+    # @return [Proc]
     #
-    def injector_module
-      Module.new do
-        class << self
-          attr_accessor :_diftw_injector, :_diftw_dependencies
-        end
-
-        def self.included(base)
-          di_mod = self
-          base.class_eval do
-            di_mod._diftw_dependencies.each do |dep|
-              define_method dep do
-                var = "@_diftw_#{dep}"
-                instance_variable_get(var) || instance_variable_set(var, di_mod._diftw_injector[dep])
-              end
-            end
-          end
-        end
+    def resolve!(dependency)
+      if parent.nil?
+        registry.fetch(dependency).call
+      elsif registry.has_key? dependency
+        registry[dependency].call
+      else
+        parent[dependency]
       end
     end
   end

data/lib/diftw/version.rb

@@ -1,4 +1,4 @@
 module DiFtw
   # Library version
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: diftw
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-05 00:00:00.000000000 Z
+date: 2016-07-11 00:00:00.000000000 Z
 dependencies: []
 description: A small dependency injection library for Ruby
 email: jordan.hollinger@gmail.com
@@ -19,6 +19,7 @@ files:
 - LICENSE
 - README.md
 - lib/diftw.rb
+- lib/diftw/builder.rb
 - lib/diftw/injector.rb
 - lib/diftw/version.rb
 homepage: https://github.com/jhollinger/ruby-diftw