Write interface contracts using pure Ruby.
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::Interface to 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::Proxy to 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-process that 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'
Solid::Adapters::InterfaceThis 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
end
Let's break down the example above.
User::Repository module includes Solid::Adapters::Interface.Methods module. It is mandatory, as these will be the methods to be implemented.create method is defined inside the Methods' module.
name and email.=> pattern matching operator.super is called to invoke the create method of the superclass. Which will be the class/object that includes/extends the User::Repository module.super output is checked using pattern matching under the tap method.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
end
And 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
end
What happend when an interface module is included/extended?
User::Repository.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) # true
Why 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
# ...
end
Access 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: 'john@email.com')
.and_return(::User::Data.new(id: 1, name: 'John', email: 'john@email.com'))
repository = User::Repository[mock_repository]
Solid::Adapters::ProxyThis 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
end
How 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 .configuration
In 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.
Solid::Adapters::Proxy::AlwaysEnabled class User::Repository
include ::Solid::Adapters::Interface::AlwaysEnabled
module Methods
# ...
end
end
Solid::Adapters::Interface::AlwaysEnabled class User::Repository < Solid::Adapters::Proxy::AlwaysEnabled
# ...
end
By 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?
end
You can access or change (if the configuration is not frozen) the configuration by using the Solid::Adapters.config method.
Solid::Adapters::Interface versus Solid::Adapters::ProxyThe 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.
Solid::Adapters::ConfigurableThe 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
end
Then 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
end
So 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
end
First, 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 .configuration
Access 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.
FAQs
Unknown package
We found that solid-adapters demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.