smart_container 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e536932a27a4bcf2ded83ea750978459e8dbf6a34ea35dfac8ef7008db3240d
-  data.tar.gz: 2566b21ef936d31bab5ff8eb6d6d51cd6510db97acf62d9dc55992915094a962
+  metadata.gz: 6670714cdeb503df6debb42135ee26283aef48a012fcf2469487668390a675f3
+  data.tar.gz: ba0ad291f05bdebb5d5af7fc46554c30c0748753243e04ac6277abf74886acb6
 SHA512:
-  metadata.gz: d1c443404d20ac8c6f61ea8bf6d37db0acd4e1131626ca00c75bf26f695262f275ee6814aab3ecd4b0a4c17b4d3f50ae449abb6932e658f0cc325e3e87cba8ea
-  data.tar.gz: 587dac41ae390e811802ca6c5a6a4610d81d4b7cecd1d5de224a409b1724edf180c98d78acc1a81cd9bc06010343d5a42f769acd219d12d395bef06c4f9420c6
+  metadata.gz: 29b1566aaff6a6227ed13a03a0b65110ce319c4b08bccc50b8c346793cb258174ee611fa19e3950e339049ab50b5819fc31ae6164b2e6d715c8a51d72a29a44f
+  data.tar.gz: cd38836e86ef48c860e58e55af5a30b8f3babdb7724658f96dee7a42ee953a122667688b29bdbb50aeccb94fc4026c1dc17d922524f21a32b20ab67ad7f3ca58

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.8.0] - 2020-07-08
+### Added
+- An ability to observe dependency re-registrations:
+  - `#observe(path, &observer) # => observer object` - listen specific dependency path;
+  - `#unobserve(observer)` - unsubscribe concrete observer object;
+  - `#clear_observers(path = nil)` - unsubscribe specific listenr or all listeners (`nil` parameter);
+
 ## [0.7.0] - 2020-06-20
 ### Added
 - `SmartCore::Container.define {}` - an ability to avoid explicit class definition that allows

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smart_container (0.6.0)
+    smart_container (0.8.0)
       smart_engine (~> 0.5)
 
 GEM
@@ -75,7 +75,7 @@ GEM
       docile (~> 1.1)
       simplecov-html (~> 0.11)
     simplecov-html (0.12.2)
-    smart_engine (0.5.0)
+    smart_engine (0.7.0)
     thread_safe (0.3.6)
     tzinfo (1.2.7)
       thread_safe (~> 0.1)

data/README.md

@@ -22,9 +22,27 @@ require 'smart_core/container'
 
 ---
 
-## Synopsis (demo)
+## Table of cotnents
+
+- [Functionality](#functionality)
+  - [container class creation](#container-class-creation)
+  - [mixin](#mixin)
+  - [container instantiation and dependency resolving](#container-instantiation-and-dependency-resolving)
+  - [runtime-level dependency/namespace registration](#runtime-level-dependencynamespace-registration)
+  - [container keys (dependency names)](#container-keys-dependency-names)
+  - [key predicates](#key-predicates)
+  - [state freeze](#state-freeze)
+  - [reloading](#reloading)
+  - [hash tree](#hash-tree)
+  - [explicit class definition](#explicit-class-definition)
+  - [dependency changement observing](#dependency-changement-observing)
+- [Roadmap](#roadmap)
 
-- container class creation:
+---
+
+## Functionality
+
+#### container class creation
 
 ```ruby
 class Container < SmartCore::Container
@@ -45,7 +63,9 @@ class Container < SmartCore::Container
 end
 ```
 
-- mixin:
+---
+
+#### mixin
 
 ```ruby
 # full documentaiton is coming;
@@ -65,7 +85,9 @@ Application.container
 Application.new.container # NOTE: the same instance as Application.container
 ```
 
-- container instantiation and dependency resolving:
+---
+
+#### container instantiation and dependency resolving
 
 ```ruby
 container = Container.new # create container instance
@@ -90,7 +112,9 @@ container.fetch('database') # => SmartCore::Container (nested container)
 container.fetch('database.resolver') # => #<SomeDatabaseResolver:0x00007f0f0f1d6332>
 ```
 
-- runtime-level dependency/namespace registration:
+---
+
+#### runtime-level dependency/namespace registration
 
 ```ruby
 container.namespace(:api) do
@@ -103,7 +127,9 @@ container['api.provider'] # => GoogleProvider
 container['game_api'] # => 'overwatch'
 ```
 
-- container keys (dependency names):
+---
+
+#### container keys (dependency names):
 
 ```ruby
 # get dependnecy keys (only dependencies)
@@ -132,12 +158,15 @@ container.keys(all_variants: true)
 ]
 ```
 
-- key predicates:
-  - `key?(key)` - has dependency or namespace?
-  - `namespace?(path)` - has namespace?
-  - `dependency?(path)` - has dependency?
-  - `dependency?(path, memoized: true)` - has memoized dependency?
-  - `dependency?(path, memoized: false)` - has non-memoized dependency?
+---
+
+#### key predicates
+
+- `key?(key)` - has dependency or namespace?
+- `namespace?(path)` - has namespace?
+- `dependency?(path)` - has dependency?
+- `dependency?(path, memoized: true)` - has memoized dependency?
+- `dependency?(path, memoized: false)` - has non-memoized dependency?
 
 ```ruby
 container.key?('database') # => true
@@ -156,24 +185,40 @@ container.dependency?('random', memoized: true) # => false
 container.dependency?('random', memoized: false) # => true
 ```
 
+---
+
+#### state freeze
+
 - state freeze (`#freeze!`, `.#frozen?`):
 
 ```ruby
 # documentation is coming;
 ```
 
-- reloading (`#reload!):
+---
+
+#### reloading
+
+- reloading (`#reload!`):
 
 ```ruby
 # documentation is coming;
 ```
 
+---
+
+#### hash tree
+
 - hash tree (`#hash_tree`, `#hash_tree(resolve_dependencies: true)`):
 
 ```ruby
-# documentation is coming`;
+# documentation is coming;
 ```
 
+---
+
+#### explicit class definition
+
 - `SmartCore::Container.define` - avoid explicit class definition (allows to create container instance from an anonymous container class immidietly):
 
 ```ruby
@@ -212,8 +257,61 @@ AppContainer['db_driver'] # => Sequel (AppContainer dependency)
 
 ---
 
+#### dependency changement observing
+
+- features and limitations:
+  - you can subscribe only on container instances (on container instance changements);
+  - at this moment only the full entity path patterns are supported (pattern-based pathes are not supported yet);
+  - you can subscribe on namespace changements (when the full namespace is re-registered) and dependency changement (when some dependency has been changed);
+  - `#observe(path, &observer) => observer` - subscribe a custom block to dependency changement events (your proc will be invoked with `|path, container|` attributes);
+  - `#unobserve(observer)` - unsubscribe concrete observer from dependency observing (returns `true` (unsubscribed) or `false` (nothing to unsubscribe));
+  - `#clear_observers(entity_path = nil)` - unsubscribe all observers from concrete path or from all pathes (`nil` parameters);
+- aliases:
+  - `#observe` => `#subscribe`;
+  - `#unobserve` => `#unsubscribe`;
+  - `#clear_observers` => `#clear_listeners`;
+
+```ruby
+container = SmartCore::Container.define do
+  namespace(:database) do
+    register(:stats) { 'stat_db' }
+  end
+end
+```
+
+```ruby
+# observe entity change
+entity_observer = container.observe('database.stats') do |dependency_path, container|
+  puts "changed => '#{container[dependency_path]}'"
+end
+
+# observe namespace change
+namespace_observer = container.observe('database') do |namespace_path, container|
+  puts "changed => '#{namespace_path}'"
+end
+```
+
+```ruby
+container.register('database.stats') { 'kek' } # => invokes entity_observer and outputs "changed! => 'kek'"
+container.namespace('database') {} # => invoks namespace_observer and outputs "changed => 'database'"
+
+container.unobserve(observer) # unsubscribe entity_observer from dependency changement observing;
+container.clear_observers # unsubscribe all observers
+
+container.register('database.stats') { 'kek' } # no one to listen this changement... :)
+container.namespace('database') {} # no one to listen this changement... :)
+```
+
+---
+
 ## Roadmap
 
+- pattern-based pathes in dependency changement observing;
+
+```ruby
+container.observe('path.*') { puts 'kek!' } # subscribe to all changements in `path` namespace;
+```
+
 - support for instant dependency registration:
 
 ```ruby
@@ -232,6 +330,8 @@ resolve('logger', :allocate) # Draft
 
 - container composition;
 
+- support for fallback block in `.resolve` operation (similar to `Hash#fetch` works);
+
 ---
 
 ## Contributing

data/lib/smart_core/container.rb

@@ -7,10 +7,10 @@ require 'smart_core'
 module SmartCore
   # @api public
   # @since 0.1.0
-  class Container
+  class Container # rubocop:disable Metrics/ClassLength
     require_relative 'container/version'
     require_relative 'container/errors'
-    require_relative 'container/arbitary_lock'
+    require_relative 'container/arbitrary_lock'
     require_relative 'container/key_guard'
     require_relative 'container/entities'
     require_relative 'container/definition_dsl'
@@ -18,6 +18,7 @@ module SmartCore
     require_relative 'container/registry'
     require_relative 'container/registry_builder'
     require_relative 'container/dependency_resolver'
+    require_relative 'container/dependency_watcher'
     require_relative 'container/mixin'
 
     class << self
@@ -56,7 +57,7 @@ module SmartCore
     # @since 0.1.0
     def initialize
       build_registry!
-      @access_lock = ArbitaryLock.new
+      @access_lock = ArbitraryLock.new
     end
 
     # @param dependency_name [String, Symbol]
@@ -65,6 +66,7 @@ module SmartCore
     #
     # @api public
     # @sicne 0.1.0
+    # @version 0.8.0
     def register(
       dependency_name,
       memoize: SmartCore::Container::Registry::DEFAULT_MEMOIZATION_BEHAVIOR,
@@ -72,6 +74,7 @@ module SmartCore
     )
       thread_safe do
         registry.register_dependency(dependency_name, memoize: memoize, &dependency_definition)
+        watcher.notify(dependency_name)
       end
     end
 
@@ -81,8 +84,12 @@ module SmartCore
     #
     # @api public
     # @since 0.1.0
+    # @version 0.8.0
     def namespace(namespace_name, &dependencies_definition)
-      thread_safe { registry.register_namespace(namespace_name, &dependencies_definition) }
+      thread_safe do
+        registry.register_namespace(namespace_name, &dependencies_definition)
+        watcher.notify(namespace_name)
+      end
     end
 
     # @param dependency_path [String, Symbol]
@@ -195,14 +202,56 @@ module SmartCore
     alias_method :to_h, :hash_tree
     alias_method :to_hash, :hash_tree
 
+    # @param entity_path [String]
+    # @param observer [Block]
+    # @yield [entity_path, container]
+    # @yieldparam entity_path [String]
+    # @yieldparam container [SmartCore::Container]
+    # @return [SmartCore::Container::DependencyWatcher::Observer]
+    #
+    # @api public
+    # @since 0.8.0
+    def observe(entity_path, &observer) # TODO: support for pattern-based pathes
+      thread_safe { watcher.watch(entity_path, &observer) }
+    end
+    alias_method :subscribe, :observe
+
+    # @param observer [SmartCore::Container::DependencyWatcher::Observer]
+    # @return [Boolean]
+    #
+    # @api public
+    # @since 0.8.0
+    def unobserve(observer)
+      thread_safe { watcher.unwatch(observer) }
+    end
+    alias_method :unsubscribe, :unobserve
+
+    # @param entity_path [String, Symbol, NilClass]
+    # @return [void]
+    #
+    # @api public
+    # @since 0.8.0
+    def clear_observers(entity_path = nil) # TODO: support for pattern-based pathes
+      thread_safe { watcher.clear_listeners(entity_path) }
+    end
+    alias_method :clear_listeners, :clear_observers
+
     private
 
+    # @return [SmartCore::Container::DependencyWatcher]
+    #
+    # @api private
+    # @since 0.8.0
+    attr_reader :watcher
+
     # @return [void]
     #
     # @api private
     # @since 0.1.0
+    # @version 0.8.0
     def build_registry!
       @registry = RegistryBuilder.build(self)
+      @watcher = SmartCore::Container::DependencyWatcher.new(self)
     end
 
     # @param block [Block]

data/lib/smart_core/container/{arbitary_lock.rb → arbitrary_lock.rb}

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 0.1.0
-class SmartCore::Container::ArbitaryLock
+class SmartCore::Container::ArbitraryLock
   # @return [void]
   #
   # @api private

data/lib/smart_core/container/definition_dsl.rb

@@ -17,7 +17,7 @@ class SmartCore::Container
       def included(base_klass)
         base_klass.instance_variable_set(:@__container_definition_commands__, CommandSet.new)
         base_klass.instance_variable_set(:@__container_instantiation_commands__, CommandSet.new)
-        base_klass.instance_variable_set(:@__container_definition_lock__, ArbitaryLock.new)
+        base_klass.instance_variable_set(:@__container_definition_lock__, ArbitraryLock.new)
         base_klass.singleton_class.send(:attr_reader, :__container_definition_commands__)
         base_klass.singleton_class.send(:attr_reader, :__container_instantiation_commands__)
         base_klass.extend(ClassMethods)
@@ -36,7 +36,7 @@ class SmartCore::Container
       def inherited(child_klass)
         child_klass.instance_variable_set(:@__container_definition_commands__, CommandSet.new)
         child_klass.instance_variable_set(:@__container_instantiation_commands__, CommandSet.new)
-        child_klass.instance_variable_set(:@__container_definition_lock__, ArbitaryLock.new)
+        child_klass.instance_variable_set(:@__container_definition_lock__, ArbitraryLock.new)
         SmartCore::Container::DefinitionDSL::Inheritance.inherit(base: self, child: child_klass)
         child_klass.singleton_class.prepend(ClassInheritance)
         super

data/lib/smart_core/container/definition_dsl/command_set.rb

@@ -18,7 +18,7 @@ class SmartCore::Container::DefinitionDSL::CommandSet
   # @since 0.1.0
   def initialize
     @commands = []
-    @access_lock = SmartCore::Container::ArbitaryLock.new
+    @access_lock = SmartCore::Container::ArbitraryLock.new
   end
 
   # @param [SmartCore::Container::DefinitionDSL::Commands::Base]

data/lib/smart_core/container/dependency_watcher.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.8.0
+class SmartCore::Container::DependencyWatcher
+  require_relative 'dependency_watcher/observer'
+
+  # @param container [SmartCore::Container]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.8.0
+  def initialize(container)
+    @container = container
+    @observers = Hash.new { |k, v| k[v] = [] }
+    @access_lock = SmartCore::Container::ArbitraryLock.new
+  end
+
+  # @param entity_path [String, Symbol]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.8.0
+  def notify(entity_path)
+    thread_safe { notify_listeners(entity_path) }
+  end
+
+  # @param entity_path [String, Symbol]
+  # @param observer [Block]
+  # @return [SmartCore::Container::DependencyWatcher::Observer]
+  #
+  # @api private
+  # @since 0.8.0
+  def watch(entity_path, &observer) # TODO: support for pattern-based pathes
+    thread_safe { listen(entity_path, observer) }
+  end
+
+  # @param observer [SmartCore::Container::DependencyWatcher::Observer]
+  # @return [Boolean]
+  #
+  # @api private
+  # @since 0.8.0
+  def unwatch(observer)
+    thread_safe { remove_listener(observer) }
+  end
+
+  # @param entity_path [String, Symbol, NilClass]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.8.0
+  def clear_listeners(entity_path = nil) # TODO: support for pattern-based pathes
+    thread_safe { remove_listeners(entity_path) }
+  end
+
+  private
+
+  # @return [SmartCore::Container]
+  #
+  # @api private
+  # @since 0.8.0
+  attr_reader :container
+
+  # @return [Hash<String,SmartCore::Container::DependencyWatcher::Observer>]
+  #
+  # @api private
+  # @since 0.8.0
+  attr_reader :observers
+
+  # @param entity_path [String, Symbol]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.8.0
+  def notify_listeners(entity_path)
+    entity_path = indifferently_accessable_path(entity_path)
+    observers.fetch(entity_path).each(&:notify!) if observers.key?(entity_path)
+  end
+
+  # @param entity_path [String, Symbol]
+  # @param observer [Proc]
+  # @return [SmartCore::Container::DependencyWatcher::Observer]
+  #
+  # @api private
+  # @since 0.8.0
+  def listen(entity_path, observer) # TODO: support for pattern-based pathes
+    raise(SmartCore::Container::ArgumentError, <<~ERROR_MESSAGE) unless observer.is_a?(Proc)
+      Observer is missing: you should provide an observer proc object (block).
+    ERROR_MESSAGE
+
+    entity_path = indifferently_accessable_path(entity_path)
+    Observer.new(container, entity_path, observer).tap { |obs| observers[entity_path] << obs }
+  end
+
+  # @param observer [SmartCore::Container::DependencyWatcher::Observer]
+  # @return [Boolean]
+  #
+  # @api private
+  # @since 0.8.0
+  def remove_listener(observer)
+    unless observer.is_a?(SmartCore::Container::DependencyWatcher::Observer)
+      raise(SmartCore::Container::ArgumentError, <<~ERROR_MESSAGE)
+        You should provide an observer object for unsubscribion
+        (an instance of SmartCore::Container::DependencyWatcher::Observer).
+      ERROR_MESSAGE
+    end
+
+    unsubscribed = false
+    observers.each_value do |observer_list|
+      if observer_list.delete(observer)
+        unsubscribed = true
+        break
+      end
+    end
+    unsubscribed
+  end
+
+  # @param entity_path [String, Symbol]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.8.0
+  def remove_listeners(entity_path) # TODO: support for pattern-based pathes
+    if entity_path.nil?
+      observers.each_value(&:clear)
+    else
+      entity_path = indifferently_accessable_path(entity_path)
+      observers[entity_path].clear if observers.key?(entity_path)
+    end
+  end
+
+  # @param entity_path [String, Symbol]
+  # @return [String]
+  #
+  # @api private
+  # @since 0.8.0
+  def indifferently_accessable_path(entity_path)
+    SmartCore::Container::KeyGuard.indifferently_accessable_key(entity_path)
+  end
+
+  # @param block [Block]
+  # @return [Any]
+  #
+  # @api private
+  # @since 0.8.0
+  def thread_safe(&block)
+    @access_lock.thread_safe(&block)
+  end
+end

data/lib/smart_core/container/dependency_watcher/observer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.8.0
+class SmartCore::Container::DependencyWatcher::Observer
+  # @param container [SmartCore::Container]
+  # @param dependency_path [String]
+  # @param callback [Proc]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.8.0
+  def initialize(container, dependency_path, callback)
+    @container = container
+    @dependency_path = dependency_path
+    @callback = callback
+  end
+
+  # @return [void]
+  #
+  # @api private
+  # @since 0.8.0
+  def notify!
+    callback.call(dependency_path, container)
+  end
+
+  private
+
+  # @return [SmartCore::Container]
+  #
+  # @api private
+  # @since 0.8.0
+  attr_reader :container
+
+  # @return [String]
+  #
+  # @api private
+  # @since 0.8.0
+  attr_reader :dependency_path
+
+  # @return [Proc]
+  #
+  # @api private
+  # @since 0.8.0
+  attr_reader :callback
+end

data/lib/smart_core/container/entities/memoized_dependency.rb

@@ -12,7 +12,7 @@ module SmartCore::Container::Entities
     # @since 0.2.0
     def initialize(dependency_name, dependency_definition)
       super(dependency_name, dependency_definition)
-      @lock = SmartCore::Container::ArbitaryLock.new
+      @lock = SmartCore::Container::ArbitraryLock.new
     end
 
     # @return [Any]

data/lib/smart_core/container/entities/namespace.rb

@@ -18,7 +18,7 @@ class SmartCore::Container::Entities::Namespace < SmartCore::Container::Entities
     super(namespace_name)
     @container_klass = Class.new(SmartCore::Container)
     @container_instance = nil
-    @lock = SmartCore::Container::ArbitaryLock.new
+    @lock = SmartCore::Container::ArbitraryLock.new
   end
 
   # @return [SmartCore::Container]

data/lib/smart_core/container/mixin.rb

@@ -11,7 +11,7 @@ module SmartCore::Container::Mixin
     # @since 0.1.0
     def included(base_klass)
       # rubocop:disable Layout/LineLength
-      base_klass.instance_variable_set(:@__smart_core_container_access_lock__, SmartCore::Container::ArbitaryLock.new)
+      base_klass.instance_variable_set(:@__smart_core_container_access_lock__, SmartCore::Container::ArbitraryLock.new)
       base_klass.instance_variable_set(:@__smart_core_container_klass__, Class.new(SmartCore::Container))
       base_klass.instance_variable_set(:@__smart_core_container__, nil)
       # rubocop:enable Layout/LineLength
@@ -34,7 +34,7 @@ module SmartCore::Container::Mixin
       inherited_container_klass = Class.new(@__smart_core_container_klass__)
 
       # rubocop:disable Layout/LineLength
-      child_klass.instance_variable_set(:@__smart_core_container_access_lock__, SmartCore::Container::ArbitaryLock.new)
+      child_klass.instance_variable_set(:@__smart_core_container_access_lock__, SmartCore::Container::ArbitraryLock.new)
       child_klass.instance_variable_set(:@__smart_core_container_klass__, inherited_container_klass)
       child_klass.instance_variable_set(:@__smart_core_container__, nil)
       # rubocop:enable Layout/LineLength

data/lib/smart_core/container/registry.rb

@@ -37,7 +37,7 @@ class SmartCore::Container::Registry
   # @since 0.1.0
   def initialize
     @registry = {}
-    @access_lock = SmartCore::Container::ArbitaryLock.new
+    @access_lock = SmartCore::Container::ArbitraryLock.new
   end
 
   # @param entity_path [String, Symbol]

data/lib/smart_core/container/version.rb

@@ -4,7 +4,7 @@ module SmartCore
   class Container
     # @api public
     # @since 0.1.0
-    # @version 0.7.0
-    VERSION = '0.7.0'
+    # @version 0.8.0
+    VERSION = '0.8.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smart_container
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-20 00:00:00.000000000 Z
+date: 2020-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: smart_engine
@@ -129,7 +129,7 @@ files:
 - bin/console
 - bin/setup
 - lib/smart_core/container.rb
-- lib/smart_core/container/arbitary_lock.rb
+- lib/smart_core/container/arbitrary_lock.rb
 - lib/smart_core/container/definition_dsl.rb
 - lib/smart_core/container/definition_dsl/command_set.rb
 - lib/smart_core/container/definition_dsl/commands.rb
@@ -149,6 +149,8 @@ files:
 - lib/smart_core/container/dependency_resolver.rb
 - lib/smart_core/container/dependency_resolver/route.rb
 - lib/smart_core/container/dependency_resolver/route/cursor.rb
+- lib/smart_core/container/dependency_watcher.rb
+- lib/smart_core/container/dependency_watcher/observer.rb
 - lib/smart_core/container/entities.rb
 - lib/smart_core/container/entities/base.rb
 - lib/smart_core/container/entities/dependency.rb