Write interface contracts using pure Ruby.
- Supported Ruby
- Examples
- Installation
- Usage
- Configuration
- About
- Development
- Contributing
- License
- Code of Conduct
This library is tested against:
| Coverage | 2.7 | 3.0 | 3.1 | 3.2 | 3.3 | Head |
|---|---|---|---|---|---|---|
| 100% | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Check the examples directory to see different applications of solid-adapters.
Attention: Each example has its own README with more details.
-
Ports and Adapters - Implements the Ports and Adapters pattern. It uses
Solid::Adapters::Interfaceto provide an interface from the application's core to other layers. -
Anti-Corruption Layer - Implements the Anti-Corruption Layer pattern. It uses the
Solid::Adapters::Proxyto define an interface for a set of adapters, which will translate an external interface (vendors) to the application's core interface. -
Solid::Rails::App - A Rails application (Web and REST API) made with
solid-adapters+solid-processthat uses the Ports and Adapters (Hexagonal) architectural pattern to decouple the application's core from the framework.
Install the gem and add to the application's Gemfile by executing:
$ bundle add solid-adapters
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install solid-adapters
And require it in your code:
require 'solid/adapters'
This feature allows the creation of a module that will be used as an interface.
It will check if the class that includes it or the object that extends it implements all the expected methods.
module User::Repository
include ::Solid::Adapters::Interface
module Methods
def create(name:, email:)
name => String
email => String
super.tap { _1 => ::User::Data[id: Integer, name: String, email: String] }
end
end
endLet's break down the example above.
- The
User::Repositorymodule includesSolid::Adapters::Interface. - Defines the
Methodsmodule. It is mandatory, as these will be the methods to be implemented. - The
createmethod is defined inside theMethods' module.- This method receives two arguments:
nameandemail. - The arguments are checked using the
=>pattern matching operator. superis called to invoke thecreatemethod of the superclass. Which will be the class/object that includes/extends theUser::Repositorymodule.- The
superoutput is checked using pattern matching under thetapmethod.
- This method receives two arguments:
Now, let's see how to use it in a class.
class User::Record::Repository
include User::Repository
def create(name:, email:)
record = Record.create(name:, email:)
::User::Data.new(id: record.id, name: record.name, email: record.email)
end
endAnd how to use it in a module with singleton methods.
module User::Record::Repository
extend User::Repository
def self.create(name:, email:)
record = Record.create(name:, email:)
::User::Data.new(id: record.id, name: record.name, email: record.email)
end
endWhat happend when an interface module is included/extended?
- An instance of the class will be a
User::Repository. - The module, class, object, that extended the interface will be a
User::Repository.
class User::Record::Repository
include User::Repository
end
module UserTest::RepositoryInMemory
extend User::Repository
# ...
end
User::Record::Repository.new.is_a?(User::Repository) # true
UserTest::RepositoryInMemory.is_a?(User::Repository) # trueWhy this is useful?
You can use => pattern matching or is_a? to ensure that the class/object implements the expected methods as it includes/extends the interface.
class User::Creation
def initialize(repository)
repository => User::Repository
@repository = repository
end
# ...
endAccess the Ports and Adapters example to see, test, and run something that uses the
Solid::Adapters::Interface
The Solid::Adapters::Interface can be used to create dynamic proxies. To do this, you must use the .[] method to wrap an object in a proxy that will check if the object implements the interface methods.
The advantage of dynamic proxies is that you can create a proxy for any object. Therefore, you don't need to include/extend the interface module to perform the checkings.
class User::Repository
include ::Solid::Adapters::Interface
module Methods
def create(name:, email:)
name => String
email => String
super.tap { _1 => ::User::Data[id: Integer, name: String, email: String] }
end
end
end
## Real object example
class User::Record::Repository
def create(name:, email:)
::User::Data.new(id: 1, name: name, email: email)
end
end
repository = User::Repository[User::Record::Repository.new]
## Mock example
mock_repository = double
allow(mock_repository)
.to receive(:create)
.with(name: 'John', email: '[email protected]')
.and_return(::User::Data.new(id: 1, name: 'John', email: '[email protected]'))
repository = User::Repository[mock_repository]This feature allows the creation of a class that will be used as a proxy for another objects.
The idea is to define an interface for the object that will be proxied.
Let's implement the example from the previous section using a proxy.
class User::Repository < Solid::Adapters::Proxy
def create(name:, email:)
name => String
email => String
object.create(name:, email:).tap do
_1 => ::User::Data[id: Integer, name: String, email: String]
end
end
endHow to use it?
Inside the proxy you will use object to access the proxied object. This means the proxy must be initialized with an object. And the object must implement the methods defined in the proxy.
class User::Record::Repository
# ...
end
module UserTest::RepositoryInMemory
extend self
# ...
end
# The proxy must be initialized with an object that implements the expected methods
memory_repository = User::Repository.new(UserTest::RepositoryInMemory)
record_repository = User::Repository.new(User::Record::Repository.new)Access the Anti-Corruption Layer to see, test, and run something that uses the
Solid::Adapters::Proxy
By default, the Solid::Adapters enables all its features. You can disable them by setting the configuration.
Solid::Adapters.configuration do |config|
dev_or_test = ::Rails.env.local?
config.proxy_enabled = dev_or_test
config.interface_enabled = dev_or_test
end
# PS: You can use .configure is an alias for .configurationIn the example above, the Solid::Adapters::Proxy, Solid::Adapters::Interface will be disabled in production.
The following variants are always enabled. You cannot disable them through the configuration.
class User::Repository
include ::Solid::Adapters::Interface::AlwaysEnabled
module Methods
# ...
end
endclass User::Repository < Solid::Adapters::Proxy::AlwaysEnabled
# ...
endBy default, the configuration is frozen after the block is executed. This means you cannot change the configuration after the application boot. If you need to change the configuration after the application boot, you can set the freeze option to false.
Solid::Adapters.configuration(freeze: false) do |config|
config.proxy_enabled = false
config.interface_enabled = ::Rails.env.local?
endYou can access or change (if the configuration is not frozen) the configuration by using the Solid::Adapters.config method.
The main difference between the interface and the proxy is when the settings take effect.
Solid::Adapters::Interface modules are applied with the application boot. So, you must ensure that the Solid::Adapters.configuration runs before loading the code. On the other hand, proxies dynamically check the configuration every time a proxy instance is generated, allowing for the possibility of turning Solid::Adapters::Proxy post-application boot.
I recommend using interfaces, as they can be included/extended directly and because they dynamically produce proxies. In other words, they are more versatile. But please remember you have different feature toggles in the configuration for using both adapters based on your application needs.
The Solid::Adapters::Configurable module can be included in a class to provide a configuration block. This is useful when you want to inject/define dependencies into a namespace dynamically.
First you need to include the module in the class. And define the configurations that you want to expose.
module User::Adapters
extend Solid::Adapters::Configurable
config.repository = nil
endThen you can use the configure method to set the configurations. Lets use a Rails initializer to set the repository.
# config/initializers/user_adapters.rb
User::Adapters.configuration do |config|
config.repository = User::Record::Repository.new
endSo you can access the repository in some place like this:
class User::Creation
def initialize
@repository = User::Adapters.config.repository
end
def create(name:, email:)
@repository.create(name: name, email: email)
end
endFirst, the Solid::Adapters.configuration does not affect the Solid::Adapters::Configurable configurations. This means you can use both features together.
Second, as the Solid::Adapters.configuration method, the Solid::Adapters::Configurable configurations are frozen by default. You can change this behavior by setting the freeze option to false.
# config/initializers/user_adapters.rb
User::Adapters.configuration(freeze: false) do |config|
config.repository = User::Record::Repository.new
end
# PS: You can use .configure is an alias for .configurationAccess the Solid::Rails::App versions 3 and 4 to see, test, and run something that uses the
Solid::Adapters::Configurable.
Rodrigo Serradura created this project. He is the Solid Process creator and has already made similar gems like the u-case and kind. This gem can be used independently, but it also contains essential features that facilitate the adoption of Solid Process (the method) in code.
After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/solid-process/solid-adapters. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Solid::Adapters project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.