diana 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a01d25056de39c12dc7b080474f96d2e3645294f77fc199e1ea486d9db4045c
+  data.tar.gz: 89722a0df0f1d63a265fd84e46afc37198ec6311f468ac93b4ef5fec9f0bce0d
+SHA512:
+  metadata.gz: 6f45f231f1e32a68559cd6bf8ded95c997e8c58bf346611b3d33a46dc547cc9426af536771104ee798dbce70da2804f1672253146e1a70a6d8a42c430f9a28ba
+  data.tar.gz: 8e6cfd282fb550df593cd46a04a4e6bc582181dc564e76999c9d41cb9008a5f6bb3c1d0d0c1f453835eb2776a4f913d42816699f30b47a6e3c8e5d15c97a21cf

data/README.md

@@ -0,0 +1,169 @@
+# Diana - Lazy Dependency Injection
+
+This module offers a DSL designed for the lazy resolution of dependency injections.
+
+It facilitates efficient and deferred initialization of dependencies,
+ensuring that resources are only allocated when necessary.
+
+This approach optimizes performance of application.
+
+## Features
+
+- **Lazy Initialization**: Dependencies are lazily initialized, ensuring
+  they are only loaded when you need them, optimizing performance
+- **Transparent Behavior**: No hidden or undocumented behaviors, providing a
+  clear and predictable experience
+- **Flexible Integration**: No dependencies, no mandatory DI container, but you
+  can seamlessly integrate with any container of your choice.
+- **Broad Compatibility**: Supports a wide range of Ruby versions,
+  including 2.6 to 3.3, head, JRuby-9.4, and TruffleRuby-24.
+
+These features are designed to make your development process smoother and more efficient!
+
+## Installation
+
+```bash
+bundle add diana
+```
+
+## Usage
+
+The Diana gem provides a streamlined way to define and manage dependencies in
+your Ruby application.
+
+### Defining Dependencies
+
+Use the `.dependencies` method to define your dependencies. You can also use the
+`.dependency` alias if you prefer.
+
+```ruby
+class SomeClass
+  include Diana.dependencies(
+    foo: proc { Foo.new },
+    bar: proc { Bar.new }
+  )
+
+  def some_method
+    foo # => Foo.new
+    bar # => Bar.new
+  end
+end
+```
+
+### Lazy Initialization
+
+Dependencies are lazily initialized, meaning they are only loaded when accessed
+for the first time.
+
+### Methods Visibility
+
+By default, dependency methods are **private**. You can change this behavior by
+configuring the Diana module:
+
+```ruby
+Diana.methods_visibility = :public
+```
+
+Using public methods can be more convenient in tests, allowing you to access the
+real dependency and stub its methods, rather than overwriting the dependency
+entirely. This approach helps ensure you are testing the correct dependency.
+
+## How it works
+
+- **Dependency Storage**: The `@_diana_dependencies` class variable holds the
+  provided dependencies.
+- **Initialization**: An `#initialize` method is added to handle dependency
+  injection.
+- **Reader Methods**: Private (by default) reader methods for dependencies are
+  created.
+- **Lazy Resolution**: Dependencies are resolved upon first access using a
+  configurable resolver.
+
+Here is an example of dependency injection and the final pseudo-code generated
+by the gem:
+
+```ruby
+class SomeClass
+  include Diana.dependencies(
+    foo: proc { Foo.new },
+    bar: proc { Bar.new }
+  )
+end
+
+# Generated pseudo-code:
+class SomeClass
+  @_diana_dependencies = {
+    foo: proc { Foo.new },
+    bar: proc { Bar.new }
+  }
+
+  def initialize(foo: nil, bar: nil)
+    @foo = foo if foo
+    @bar = bar if bar
+  end
+
+  private
+
+  def foo
+    @foo ||= Diana.resolve(self.class.instance_variable_get(:@_diana_dependencies)[:foo])
+  end
+
+  def bar
+    @bar ||= Diana.resolve(self.class.instance_variable_get(:@_diana_dependencies)[:bar])
+  end
+end
+```
+
+This structure ensures efficient and flexible dependency management.
+
+## Custom Resolvers
+
+The default resolver handles only procs, functioning as follows:
+
+```ruby
+DEFAULT_RESOLVER = proc do |dependency|
+  dependency.is_a?(Proc) ? dependency.call : dependency
+end
+```
+
+You can customize the resolver to fit your needs. For instance, to resolve
+strings to a DI container, you can modify the resolver like this:
+
+```ruby
+Diana.resolver = proc do |dependency|
+  case dependency
+  when String then DI_CONTAINER[dependency]
+  when Proc then dependency.call
+  else dependency
+  end
+end
+
+SomeClass.include Diana.dependencies(foo: 'utils.foo') # => DI_CONTAINER['utils.foo']
+```
+
+## Important Notes
+
+- This gem is intended for use with classes that have no manually defined
+  `#initialize` method. This design choice prevents  conflicts or unpredictable
+  behavior with custom #initialize methods. If you do add a custom `#initialize`
+  method, it will take precedence. In such cases, ensure you include a
+  `super(**deps)` call to override dependencies if needed.
+
+- We do not perform any argument modifications and we do not call `super`
+  in dependencies `#initialize` method. This approach is chosen to ensure
+  optimal performance.
+
+- Dependencies defined in a parent class are not accessible in nested classes.
+  You should define dependencies within each class where they are required.
+
+These limitations ensure that the gem remains predictable and performant,
+avoiding any hidden complexities or unexpected behaviors.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/aglushkov/diana>.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/diana/config.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Diana
+  module Config
+    # The default resolver for dependencies.
+    DEFAULT_RESOLVER = proc { |dependency| dependency.is_a?(Proc) ? dependency.call : dependency }
+
+    # The default visibility for generated dependency methods.
+    DEFAULT_METHODS_VISIBILITY = :private
+
+    private_constant :DEFAULT_RESOLVER
+    private_constant :DEFAULT_METHODS_VISIBILITY
+
+    # Returns the current resolver.
+    #
+    # @api private
+    # @return [#call] The current resolver.
+    def resolver
+      @resolver || DEFAULT_RESOLVER
+    end
+
+    # Sets a new resolver.
+    #
+    # @example Setting a resolver that can resolve strings to a DI container.
+    #   Diana.resolver = proc do |value|
+    #     case value
+    #     when Proc then value.call
+    #     when String then MyContainer[value].call
+    #     else value
+    #     end
+    #   end
+    #
+    # @param new_resolver [#call] The new resolver to set.
+    # @return [#call] The new resolver.
+    def resolver=(new_resolver)
+      @resolver = new_resolver
+    end
+
+    # Resolves a given value using the current resolver.
+    #
+    # @api private
+    # @param value [Object] The value to resolve.
+    # @return [Object] The resolved value.
+    def resolve(value)
+      resolver.call(value)
+    end
+
+    # Returns the current visibility of dependency methods.
+    #
+    # @api private
+    # @return [Symbol] The current visibility of dependency methods.
+    def methods_visibility
+      @methods_visibility || DEFAULT_METHODS_VISIBILITY
+    end
+
+    # Sets the visibility of dependency methods.
+    #
+    # @example Setting the default visibility of dependency methods to public.
+    #   Diana.methods_visibility = :public
+    #
+    # @param visibility [Symbol] The new visibility for dependency methods (:private or :public).
+    # @return [Symbol] The new default visibility for dependency methods.
+    # @raise [ArgumentError] If the visibility is not :private or :public.
+    #
+    def methods_visibility=(visibility)
+      if (visibility != :private) && (visibility != :public)
+        raise ArgumentError, "methods_visibility value must be :private or :public"
+      end
+
+      @methods_visibility = visibility
+    end
+  end
+end

data/lib/diana/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Diana
+  # Returns the version of the Diana gem.
+  #
+  # @return [String] The version of the gem in Semantic Versioning (SemVer) format.
+  #
+  VERSION = File.read(File.join(File.dirname(__FILE__), "../../VERSION")).strip
+end

data/lib/diana.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "diana/version"
+require_relative "diana/config"
+
+#
+# Dependency Injection DSL
+#
+# This module offers a DSL designed for the lazy resolution of dependency
+# injections. It facilitates efficient and deferred initialization of
+# dependencies ensuring that resources are only allocated when necessary.
+#
+# This approach optimizes performance of application.
+#
+# @example
+#   class MyClass
+#     include Diana.dependencies(
+#       foo: proc { Foo.new },
+#       bar: proc { Bar.new }
+#     )
+#   end
+#
+#
+module Diana
+  extend Config
+
+  class << self
+    # Define dependencies for a class.
+    #
+    # @example
+    #   class MyClass
+    #     include Diana.dependencies(
+    #       foo: proc { MyFoo.new }
+    #       bar: proc { MyBar.new }
+    #     )
+    #   end
+    #
+    # param deps [Hash] A hash where keys are the names of the dependencies and
+    #   values are the dependencies themselves, resolved lazily.
+    #
+    # @return [Module] A module to be included in your class, providing the
+    #   defined dependencies.
+    #
+    def dependencies(deps)
+      Module.new do
+        def self.inspect
+          "<Diana.dependencies:#{object_id.to_s(16)}>"
+        end
+
+        define_singleton_method(:included) do |base|
+          merged_deps =
+            if base.instance_variable_defined?(:@_diana_dependencies)
+              base.instance_variable_get(:@_diana_dependencies).merge!(deps)
+            else
+              base.instance_variable_set(:@_diana_dependencies, deps.dup)
+            end
+
+          class_eval(<<~INITIALIZE, __FILE__, __LINE__ + 1)
+            def initialize(#{merged_deps.each_key.map { |dependency| "#{dependency}: nil" }.join(", ")})
+            #{merged_deps.each_key.map { |dependency| "  @#{dependency} = #{dependency} if #{dependency}" }.join("\n")}
+            end
+          INITIALIZE
+        end
+
+        deps.each_key do |dependency|
+          class_eval(<<~ATTR_READER, __FILE__, __LINE__ + 1)
+            def #{dependency}
+              @#{dependency} ||= Diana.resolve(self.class.instance_variable_get(:@_diana_dependencies)[:#{dependency}])
+            end
+
+            private :#{dependency} if Diana.methods_visibility == :private
+          ATTR_READER
+        end
+      end
+    end
+
+    alias_method :dependency, :dependencies
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: diana
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrey Glushkov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-17 00:00:00.000000000 Z
+dependencies: []
+description: |
+  This module offers a DSL designed for the lazy resolution of dependency injections.
+
+  It facilitates efficient and deferred initialization of dependencies,
+  ensuring that resources are only allocated when necessary.
+
+  This approach optimizes performance of application.
+email:
+- aglushkov@shakuro.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- VERSION
+- lib/diana.rb
+- lib/diana/config.rb
+- lib/diana/version.rb
+homepage: https://github.com/aglushkov/diana
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aglushkov/diana
+  changelog_uri: https://github.com/aglushkov/diana/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Lazy Dependency Injection
+test_files: []