inoculate 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b26bc8e397a1e50bb29e716bd1c4abb531f9267765960b936ce03ba8449ab7e5
-  data.tar.gz: e09a3d2235a100c7723596614845a4faba198261bbecfe979ebdf3b209b7d325
+  metadata.gz: 2649bf406a68234451cc147c069a8b9d58ce91d2a1538e728a532ff4abda2180
+  data.tar.gz: 3bf808d9e35467647432ed7d74cab98e669a41f7e887e889735c8d583844eaf7
 SHA512:
-  metadata.gz: d6a281590288dec453e6adf338f5b9461160d07ea35c8bdb3914a464630dd76d46ecfe3c2d16099d936e0f8c04159c0e1200cd0f7c65cf426e74a844492be8c1
-  data.tar.gz: 27c2596ce1a7e2e0c24bdcaf8cb83272a71f0f5e5a3addf8caac8aa082f5b13448f0af66226c45162deb96a6a43cc61d3addf052253aac84ec250002f827ef7d
+  metadata.gz: ff27ab41b2f2da2cc6ebf22e434c88b626b9b0c2bf6dab505a9baa1a777faf82c60512a44bb258e19bf0ceb71315b0f0123ab724d6dcb65dfb0468d3d9cf7b35
+  data.tar.gz: 23212f8eeb9dc79c159651ebebc93d4ca13ad7623aa2d85622fe8de7b64f993880db5837e51a072f9116bffc169f02030b0676247f1befb254e86023443436ed

data/CHANGELOG.md

@@ -1,8 +1,17 @@
-## v0.1.0 — 2022-10-10
+## v0.3.0 \[2022-10-11]
+
+* Add instance dependency registration.
+* Only allow blocks (and Procs) as dependency factories.
+
+## v0.2.0 \[2022-10-11]
+
+* Build modules at initialization time so that usage is always thread-safe.
+
+## v0.1.0 \[2022-10-10]
 
 * Add transient dependency registration.
 * Add initialization process for gem.
 
-## v0.0.0 — 2022-10-05
+## v0.0.0 \[2022-10-05]
 
 * Initial gem setup.

data/README.md

@@ -3,6 +3,8 @@
 Inoculate is a small, thread-safe dependency injection library configured entirely with Ruby.
 It provides several life-cycles and provides dependency access through private accessors.
 
+[![Gem Version](https://badge.fury.io/rb/inoculate.svg)](https://badge.fury.io/rb/inoculate)
+
 ---
 
 ## What's in the box?
@@ -22,6 +24,7 @@ It provides several life-cycles and provides dependency access through private a
 2. [Usage](#usage)
    1. [Dependency Life Cycles](#dependency-life-cycles)
       1. [Transient](#transient)
+      2. [Instance](#instance)
    2. [Renaming the Declaration API](#renaming-the-declaration-api)
    3. [Hide Your Dependency on Inoculate](#hide-your-dependency-on-inoculate)
 3. [Installation](#installation)
@@ -107,6 +110,54 @@ Count is: 0
 => nil    
 ```
 
+#### Instance
+Instance dependencies are constructed once for each instance of a dependent class.
+
+```ruby
+class Counter
+   attr_reader :count
+
+   def initialize
+      @count = 0
+   end
+   
+   def inc
+      @count += 1
+   end
+end
+
+Inoculate.initialize do |config|
+   config.instance(:counter) { Counter.new }
+end
+
+class Example
+   include Inoculate::Porter
+   inoculate_with :counter
+   
+   def initialize(name)
+      @name = name
+   end
+   
+   def to_s
+      counter.inc
+      "[#{@name}] Count is: #{counter.count}"
+   end
+end
+
+a = Example.new("a")
+b = Example.new("b")
+puts a, a, b
+```
+
+This results in:
+
+```
+[a] Count is: 1
+[a] Count is: 2
+[b] Count is: 1
+=> nil  
+```
+
 ### Renaming the Declaration API
 The `inoculate_with` API is named to avoid immediate collisions with other modules
 and code you may have. You can use it as-is, or rename it to something you see fit

data/lib/inoculate/configurer.rb

@@ -13,8 +13,18 @@ module Inoculate
     # @see Manufacturer#transient
     #
     # @since 0.1.0
-    def transient(name, builder = nil, &block)
-      manufacturer.transient(name, builder, &block)
+    def transient(name, &block)
+      manufacturer.transient(name, &block)
+      nil
+    end
+
+    # Register an instance dependency.
+    # @see Manufacturer#instance
+    #
+    # @since 0.3.0
+    def instance(name, &block)
+      manufacturer.instance(name, &block)
+      nil
     end
 
     private

data/lib/inoculate/initialization.rb

@@ -7,8 +7,6 @@
 module Inoculate
   # The main configuration entrypoint for Inoculate. Use this to set up named dependencies.
   #
-  # @note This method is not thread safe.
-  #
   # @example A simple dependency configuration
   #   Inoculate.initialize do |config|
   #     config.transient(:http) { Faraday }

data/lib/inoculate/manufacturer.rb

@@ -4,7 +4,6 @@ require "digest"
 
 module Inoculate
   # Registers and builds dependency injection modules.
-  # @todo building needs to be thread-safe
   # @todo singleton life cycle
   # @todo instance life cycle
   # @todo thread singleton life cycle
@@ -29,58 +28,94 @@ module Inoculate
     #   manufacturer.transient(:sha1_hasher) { Digest::SHA1.new }
     #
     # @example With a Proc
-    #   manufacturer.transient(:sha1_hasher, -> { Digest::SHA1.new })
-    #
-    # @example With anything Callable
-    #   class HashingBuilder
-    #     def call = Digest::SHA1.new
-    #   end
-    #   manufacturer.transient(:sha1_hasher, HashingBuilder.new)
+    #   manufacturer.transient(:sha1_hasher, &-> { Digest::SHA1.new })
     #
     # @param name [Symbol, #to_sym] the dependency name which will be used to access it
-    # @param builder [#call] the callable to build the dependency
-    # @param block [Proc, nil] an alternative builder callable
+    # @param block [Block, Proc] a factory method to build the dependency
     #
-    # @raise [Errors::RequiresCallable] if no builder or block is provided
+    # @raise [Errors::RequiresCallable] if no block is provided
     # @raise [Errors::InvalidName] if the name is not a symbol, cannot be converted to a symbol,
     #                              or is not a valid attribute name
     # @raise [Errors::AlreadyRegistered] if the name has been registered previously
     #
     # @since 0.1.0
-    def transient(name, builder = nil, &block)
-      validate_builder_name name
+    def transient(name, &block)
+      validate_dependency_name name
       raise Errors::AlreadyRegistered if @registered_blueprints.has_key? name
-      raise Errors::RequiresCallable unless builder.respond_to?(:call) || block
+      raise Errors::RequiresCallable if block.nil?
 
-      @registered_blueprints[name.to_sym] = {lifecycle: :transient, builder: builder || block, accessor_module: nil}
+      blueprint_name = name.to_sym
+      @registered_blueprints[blueprint_name] = {
+        lifecycle: :transient,
+        factory: block,
+        accessor_module: build_module(blueprint_name, :transient, block)
+      }
     end
 
-    # Build the accessor module associated with a dependency name.
+    # Register an instance dependency.
+    #
+    # An instance dependency gets created once for each instance of a dependent class.
     #
-    # @param name [Symbol] the dependency name to build an accessor module for
+    # @example With a block
+    #   manufacturer.instance(:sha1_hasher) { Digest::SHA1.new }
     #
-    # @raise [Errors::UnknownName] if the dependency name is not registered
+    # @example With a Proc
+    #   manufacturer.instance(:sha1_hasher, &-> { Digest::SHA1.new })
     #
-    # @return [Module] the accessor module for accessing instances of the dependency
+    # @param name [Symbol, #to_sym] the dependency name which will be used to access it
+    # @param block [Block, Proc] a factory method to build the dependency
     #
-    # @since 0.1.0
-    def build(name)
-      blueprint = @registered_blueprints[name]
-      raise Errors::UnknownName if blueprint.nil?
-      return blueprint[:accessor_module] unless blueprint[:accessor_module].nil?
+    # @raise [Errors::RequiresCallable] if no block is provided
+    # @raise [Errors::InvalidName] if the name is not a symbol, cannot be converted to a symbol,
+    #                              or is not a valid attribute name
+    # @raise [Errors::AlreadyRegistered] if the name has been registered previously
+    #
+    # @since 0.3.0
+    def instance(name, &block)
+      validate_dependency_name name
+      raise Errors::AlreadyRegistered if @registered_blueprints.has_key? name
+      raise Errors::RequiresCallable if block.nil?
 
+      blueprint_name = name.to_sym
+      @registered_blueprints[blueprint_name] = {
+        lifecycle: :instance,
+        factory: block,
+        accessor_module: build_module(blueprint_name, :instance, block)
+      }
+    end
+
+    private
+
+    def build_module(name, lifecycle, factory)
       module_name = "I#{Digest::SHA1.hexdigest(name.to_s)}"
-      builder = blueprint[:builder]
-      blueprint[:accessor_module] = Providers.module_eval do
-        const_set(module_name, Module.new do
-          private define_method(name) { builder.call }
-        end)
+      module_body =
+        case lifecycle
+        when :transient then build_transient(name, factory)
+        when :instance then build_instance(name, factory)
+        else raise ArgumentError, "Life cycle #{lifecycle} is not valid. Something has gone very wrong."
+        end
+
+      Providers.module_eval { const_set(module_name, module_body) }
+    end
+
+    def build_transient(name, factory)
+      Module.new do
+        private define_method(name) { factory.call }
       end
     end
 
-    private
+    def build_instance(name, factory)
+      cache_variable_name = "@icache_#{Digest::SHA1.hexdigest(name.to_s)}"
+      Module.new do
+        define_method(name) do
+          instance_variable_set(cache_variable_name, factory.call) unless instance_variable_defined?(cache_variable_name)
+          instance_variable_get(cache_variable_name)
+        end
+        private name
+      end
+    end
 
-    def validate_builder_name(name)
+    def validate_dependency_name(name)
       raise Errors::InvalidName, "name must be a symbol or convert to one" unless name.respond_to? :to_sym
       begin
         Module.new { attr_reader name }

data/lib/inoculate/porter.rb

@@ -37,7 +37,10 @@ module Inoculate
       m = Module.new do
         define_method(method_name) do |*names|
           names.each do |name|
-            include(Inoculate.manufacturer.build(name))
+            mod = Inoculate.manufacturer.registered_blueprints.dig(name, :accessor_module)
+            raise Errors::UnknownName if mod.nil?
+
+            include(mod)
           end
         end
       end

data/lib/inoculate/version.rb

@@ -2,5 +2,5 @@
 
 module Inoculate
   # The library version.
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/sig/inoculate.rbs

@@ -6,9 +6,9 @@ module Inoculate
   end
 
   type callable = ^() -> untyped
-  type lifecycle_name = :transient
+  type lifecycle_name = :transient | :instance
   type builder_name = Symbol
-  type blueprint = { lifecycle: lifecycle_name, builder: callable, accessor_module: Module? }
+  type blueprint = { lifecycle: lifecycle_name, factory: callable, accessor_module: Module? }
 
   module Errors
     class Error < StandardError
@@ -32,18 +32,15 @@ module Inoculate
 
   class Manufacturer
     attr_reader registered_blueprints: Hash[builder_name, blueprint]
-    def transient: (builder_name | _ToSymbol, callable?) ?{ () -> void } -> void
-    def build: (builder_name) -> Module
-
-    private
-
-    def validate_builder_name: (builder_name) -> void
+    def transient: (builder_name | _ToSymbol) { () -> void } -> void
+    def instance: (builder_name | _ToSymbol) { () -> void } -> void
   end
 
   class Configurer
     def initialize: (Manufacturer) -> void
 
-    def transient: (builder_name | _ToSymbol, callable?) -> void
+    def transient: (builder_name | _ToSymbol) { () -> void } -> nil
+    def instance: (builder_name | _ToSymbol) { () -> void } -> nil
 
     private
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inoculate
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Stephan Tarulli
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-10 00:00:00.000000000 Z
+date: 2022-10-12 00:00:00.000000000 Z
 dependencies: []
 description: |
   Inoculate is a small, thread-safe dependency injection library configured entirely with Ruby.