bcdd-contract 0.1.0

data/examples/design_by_contract/lib/shopping_cart.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class ShoppingCart
+  module Item
+    module Contract
+      cannot_be_nan = ->(val) { val.respond_to?(:nan?) and val.nan? and '%p cannot be nan' }
+      cannot_be_inf = ->(val) { val.respond_to?(:infinite?) and val.infinite? and '%p cannot be infinite' }
+      must_be_positive = ->(label) { ->(val) { val.positive? or "#{label} (%p) must be positive" } }
+
+      PricePerUnit = ::BCDD::Contract[::Numeric] & cannot_be_nan & cannot_be_inf & must_be_positive['price per unit']
+      Quantity     = ::BCDD::Contract[::Integer] & must_be_positive['quantity']
+      Name         = ::BCDD::Contract[::String]  & ->(val) { val.empty? and 'item name must be filled' }
+
+      NameAndData = ::BCDD::Contract.pairs(Name => { quantity: Quantity, price_per_unit: PricePerUnit })
+    end
+  end
+
+  module Items
+    module Contract
+      extend ::BCDD::Contract[::Hash] & ->(items, errors) do
+        return if items.empty?
+
+        Item::Contract::NameAndData[items].then { |it| it.valid? or errors.concat(it.errors) }
+      end
+    end
+  end
+
+  def initialize(items = {})
+    @items = +Items::Contract[items]
+  end
+
+  def add_item(item_name, quantity, price_per_unit)
+    Items::Contract.invariant(@items) do |items|
+      item_name = +Item::Contract::Name[item_name]
+
+      item = items[item_name] ||= { quantity: 0, price_per_unit: 0 }
+
+      item[:price_per_unit] = +Item::Contract::PricePerUnit[price_per_unit]
+      item[:quantity]      += +Item::Contract::Quantity[quantity]
+    end
+  end
+
+  def remove_item(item_name, quantity)
+    Items::Contract.invariant(@items) do |items|
+      item_name = +Item::Contract::Name[item_name]
+      quantity  = +Item::Contract::Quantity[quantity]
+
+      item = items[item_name]
+
+      ::BCDD::Contract.assert!(item_name, 'item (%p) not found')
+      ::BCDD::Contract.refute!(item_name, 'item (%p) not enough quantity to remove') { quantity > item[:quantity] }
+
+      item[:quantity] -= quantity
+
+      item[:quantity].tap { |number| items.delete(item_name) if number.zero? }
+    end
+  end
+
+  def total_price
+    (+Items::Contract[@items]).sum { |_name, data| data[:quantity] * data[:price_per_unit] }
+  end
+end

data/examples/ports_and_adapters/README.md

@@ -0,0 +1,246 @@
+- [🧩 Ports and Adapters Example](#-ports-and-adapters-example)
+  - [The Port](#the-port)
+  - [The Adapters](#the-adapters)
+- [⚖️ What is the benefit of doing this?](#️-what-is-the-benefit-of-doing-this)
+  - [How much to do this (create Ports and Adapters)?](#how-much-to-do-this-create-ports-and-adapters)
+  - [Is it worth the overhead of contract checking at runtime?](#is-it-worth-the-overhead-of-contract-checking-at-runtime)
+- [🏃‍♂️ How to run the application?](#️-how-to-run-the-application)
+- [💡 Why is `User::Creation` not validating the name and email?](#-why-is-usercreation-not-validating-the-name-and-email)
+
+## 🧩 Ports and Adapters Example
+
+Ports and Adapters is an architectural pattern that separates the application's core logic (Ports) from external dependencies (Adapters).
+
+This example shows how to implement a simple application using this pattern and the gem `bcdd-contract`.
+
+Let's start seeing the code structure:
+
+```
+├── Rakefile
+├── config.rb
+├── db
+├── app
+│  └── models
+│     └── user
+│        ├── record
+│        │  └── repository.rb
+│        └── record.rb
+├── lib
+│  └── user
+│     ├── creation.rb
+│     ├── data.rb
+│     └── repository.rb
+└── test
+   └── user_test
+      └── repository.rb
+```
+
+The files and directories are organized as follows:
+
+- `Rakefile` runs the application.
+- `config.rb` file contains the configuration of the application.
+- `db` directory contains the database. It is not part of the application, but it is used by the application.
+- `app` directory contains "Rails" components.
+- `lib` directory contains the core business logic.
+- `test` directory contains the tests.
+
+The application is a simple "user management system". It unique core functionality is to create users.
+
+Now we understand the code structure, let's see the how the pattern is implemented.
+
+### The Port
+
+In this application, there is only one business process: `User::Creation` (see `lib/user/creation.rb`), which relies on the `User::Repository` (see `lib/user/repository.rb`) to persist the user.
+
+The `User::Repository` is an example of **port**, because it is an interface/contract that defines how the core business logic will persist user records.
+
+```ruby
+module User::Repository
+  include ::BCDD::Contract::Interface
+
+  module Methods
+    module Input
+      is_string    = ::BCDD::Contract[String]
+      is_filled    = ->(val) { val.present? or '%p must be filled' }
+      email_format = ->(val) { val.match?(/\A[^@\s]+@[^@\s]+\z/) or '%p must be an email' }
+
+      Name  = is_string & is_filled
+      Email = is_string & is_filled & email_format
+    end
+
+    def create(name:, email:)
+      output = super(name: +Input::Name[name], email: +Input::Email[email])
+
+      output => ::User::Data[id: Integer, name: Input::Name, email: Input::Email]
+
+      output
+    end
+  end
+end
+```
+
+### The Adapters
+
+The `User::Repository` is implemented by two adapters:
+
+- `User::Record::Repository` (see `app/models/user/record/repository.rb`) is an adapter that persists user records in the database (through the `User::Record`, that is an `ActiveRecord` model).
+
+- `UserTest::Repository` (see `test/user_test/repository.rb`) is an adapter that persists user records in memory (through the `UserTest::Data`, that is a simple in-memory data structure).
+
+## ⚖️ What is the benefit of doing this?
+
+The benefit of doing this is that the core business logic is decoupled from the external dependencies, which makes it easier to test and promote changes in the code.
+
+For example, if we need to change the persistence layer (start to send the data to a REST API or a Redis DB), we just need to implement a new adapter and make the business processes (`User::Creation`) use it.
+
+### How much to do this (create Ports and Adapters)?
+
+Use this pattern when there is a real need to decouple the core business logic from external dependencies.
+
+You can start with a simple implementation (without Ports and Adapters) and refactor it to use this pattern when the need arises.
+
+### Is it worth the overhead of contract checking at runtime?
+
+You can eliminate the overhead by disabling the `BCDD::Contract::Interface`, which is enabled by default.
+
+When it is disabled, the `BCDD::Contract::Interface` won't prepend the interface methods module to the adapter, which means that the adapter won't be checked against the interface.
+
+To disable it, set the configuration to false:
+
+```ruby
+BCDD::Contract.configuration do |config|
+  config.interface_enabled = false
+end
+```
+
+## 🏃‍♂️ How to run the application?
+
+In the same directory as this `README`, run:
+
+```bash
+rake # or rake BCDD_CONTRACT_ENABLED=enabled
+
+# or
+
+rake BCDD_CONTRACT_ENABLED=false
+```
+
+**Proxy enabled**
+
+```bash
+rake # or rake BCDD_CONTRACT_ENABLED=enabled
+
+# Output sample:
+#
+# --  Valid input  --
+#
+# Created user: #<struct User::Data id=1, name="Jane", email="jane@foo.com">
+# Created user: #<struct User::Data id=1, name="John", email="john@bar.com">
+#
+# --  Invalid input  --
+#
+# rake aborted!
+# BCDD::Contract::Error: "jane" must be an email (BCDD::Contract::Error)
+# /.../lib/bcdd/contract/core/checking.rb:26:in `raise_validation_errors!'
+# /.../lib/bcdd/contract/core/checking.rb:30:in `value_or_raise_validation_errors!'
+# /.../examples/ports_and_adapters/lib/user/repository.rb:18:in `create'
+# /.../examples/ports_and_adapters/lib/user/creation.rb:12:in `call'
+# /.../examples/ports_and_adapters/Rakefile:33:in `block in <top (required)>'
+```
+
+**Proxy disabled**
+
+```bash
+rake BCDD_CONTRACT_ENABLED=false
+
+# Output sample:
+#
+# --  Valid input  --
+#
+# Created user: #<struct User::Data id=1, name="Jane", email="jane@foo.com">
+# Created user: #<struct User::Data id=1, name="John", email="john@bar.com">
+#
+# --  Invalid input  --
+#
+# Created user: #<struct User::Data id=2, name="Jane", email="jane">
+# Created user: #<struct User::Data id=3, name="", email=nil>
+```
+
+## 💡 Why is `User::Creation` not validating the name and email?
+
+The `User::Creation` process is not validating the name and email because if it did, it wouldn't be possible to see the error messages of the `User::Repository` contract.
+
+But in a real-world application, the `User::Creation` process would validate the name and email, as the validation is part of its business logic. The `User::Repository` contract could do the same or simpler checkings (like if the name and email are strings).
+
+This is an example of the `User::Creation` performing validations and the `User::Repository` checkings:
+
+```ruby
+# lib/user/name.rb
+module User
+  module Name
+    Contract = ::BCDD::Contract[String] & -> { _1.present? or '%p must be filled' }
+  end
+end
+
+# lib/user/email.rb
+module User
+  module Email
+    Contract = ::BCDD::Contract[String] & -> { _1.match?(/\A[^@\s]+@[^@\s]+\z/) or '%p must be an email' }
+  end
+end
+
+# lib/user/repository.rb
+module User::Repository
+  include ::BCDD::Contract::Interface
+
+  module Methods
+    def create(name:, email:)
+      output = super(name: +User::Name::Contract[name], email: +User::Email::Contract[email])
+
+      output => ::User::Data[id: Integer, name: User::Name::Contract, email: User::Email::Contract]
+
+      output
+    end
+  end
+end
+
+# lib/user/creation.rb
+module User
+  class Creation
+    def initialize(repository:)
+      repository => Repository
+
+      @repository = repository
+    end
+
+    def call(name:, email:)
+      name  = Name::Contract[name]
+      email = Email::Contract[email]
+
+      return [false, name.errors] if name.invalid?
+      return [false, email.errors] if email.invalid?
+
+      user_data = @repository.create(name: name.value, email: email.value)
+
+      puts "Created user: #{user_data.inspect}"
+
+      [true, user_data]
+    end
+  end
+end
+```
+
+Usage:
+
+```ruby
+memory_creation = User::Creation.new(repository: UserTest::Repository.new)
+
+memory_creation.call(name: 'Jane', email: 'jane@email.com')
+# => [true, #<struct User::Data id=1, name="Jane", email="jane@email.com">
+
+memory_creation.call(name: '', email: 'jane')
+# => [false, ["\"\" must be filled"]]
+
+memory_creation.call(name: 'Jane', email: 'jane')
+# => [false, ["\"jane\" must be an email"]]
+```

data/examples/ports_and_adapters/Rakefile

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+if RUBY_VERSION <= '3.1'
+  puts 'This example requires Ruby 3.1 or higher.'
+  exit! 1
+end
+
+require_relative 'config'
+
+require_relative 'test/user_test/repository'
+
+task :default do
+  puts
+  puts '------------------'
+  puts 'Ports and Adapters'
+  puts '------------------'
+
+  # -- User creation instances
+
+  db_creation = User::Creation.new(repository: User::Record::Repository)
+
+  memory_creation = User::Creation.new(repository: UserTest::Repository.new)
+
+  puts
+  puts '--  Valid input  --'
+  puts
+
+  db_creation.call(name: 'Jane', email: 'jane@foo.com')
+
+  memory_creation.call(name: 'John', email: 'john@bar.com')
+
+  puts
+  puts '--  Invalid input  --'
+  puts
+
+  db_creation.call(name: 'Jane', email: 'jane')
+
+  memory_creation.call(name: '', email: nil)
+end
+
+# Output sample: rake BCDD_CONTRACT_ENABLED=true
+#
+# --  Valid input  --
+#
+# Created user: #<struct User::Data id=1, name="Jane", email="jane@foo.com">
+# Created user: #<struct User::Data id=1, name="John", email="john@bar.com">
+#
+# --  Invalid input  --
+#
+# rake aborted!
+# BCDD::Contract::Error: "jane" must be an email (BCDD::Contract::Error)
+# lib/bcdd/contract/unit.rb:52:in `+@'
+# examples/ports_and_adapters/lib/user/repository.rb:20:in `create'
+# examples/ports_and_adapters/lib/user/creation.rb:10:in `call'
+# examples/ports_and_adapters/Rakefile:35:in `block in <top (required)>'
+
+# Output sample: rake BCDD_CONTRACT_ENABLED=false
+#
+#
+# --  Valid input  --
+#
+# Created user: #<struct User::Data id=1, name="Jane", email="jane@foo.com">
+# Created user: #<struct User::Data id=1, name="John", email="john@bar.com">
+#
+# --  Invalid input  --
+#
+# Created user: #<struct User::Data id=2, name="Jane", email="jane">
+# Created user: #<struct User::Data id=3, name="", email=nil>

data/examples/ports_and_adapters/app/models/user/record/repository.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module User
+  module 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
+end

data/examples/ports_and_adapters/app/models/user/record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module User
+  class Record < ActiveRecord::Base
+    self.table_name = 'users'
+  end
+end

data/examples/ports_and_adapters/config.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'bundler/inline'
+
+$LOAD_PATH.unshift(__dir__)
+
+gemfile do
+  source 'https://rubygems.org'
+
+  gem 'sqlite3', '~> 1.7'
+  gem 'activerecord', '~> 7.1', '>= 7.1.2', require: 'active_record'
+  gem 'bcdd-contract', path: '../../'
+end
+
+require 'active_support/all'
+
+require 'db/setup'
+
+::BCDD::Contract.config.interface_enabled = ENV.fetch('BCDD_CONTRACT_ENABLED', 'true') != 'false'
+
+module User
+  require 'lib/user/data'
+  require 'lib/user/repository'
+  require 'lib/user/creation'
+end
+
+require 'app/models/user/record'
+require 'app/models/user/record/repository'

data/examples/ports_and_adapters/db/setup.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'active_support/all'
+
+ActiveRecord::Base.establish_connection(
+  host: 'localhost',
+  adapter: 'sqlite3',
+  database: ':memory:'
+)
+
+ActiveRecord::Schema.define do
+  create_table :users do |t|
+    t.column :name, :string
+    t.column :email, :string
+  end
+end

data/examples/ports_and_adapters/lib/user/creation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module User
+  class Creation
+    def initialize(repository:)
+      repository => Repository
+
+      @repository = repository
+    end
+
+    def call(name:, email:)
+      user_data = @repository.create(name:, email:)
+
+      puts "Created user: #{user_data.inspect}"
+
+      user_data
+    end
+  end
+end

data/examples/ports_and_adapters/lib/user/data.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module User
+  Data = ::Struct.new(:id, :name, :email, keyword_init: true)
+end

data/examples/ports_and_adapters/lib/user/repository.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module User::Repository
+  include ::BCDD::Contract::Interface
+
+  module Methods
+    module Input
+      is_string    = ::BCDD::Contract[String]
+      is_filled    = ->(val) { val.present? or '%p must be filled' }
+      email_format = ->(val) { val.match?(/\A[^@\s]+@[^@\s]+\z/) or '%p must be an email' }
+
+      Name  = is_string & is_filled
+      Email = is_string & is_filled & email_format
+    end
+
+    def create(name:, email:)
+      output = super(name: +Input::Name[name], email: +Input::Email[email])
+
+      output => ::User::Data[id: Integer, name: Input::Name, email: Input::Email]
+
+      output
+    end
+  end
+end

data/examples/ports_and_adapters/test/user_test/repository.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module UserTest
+  class Repository
+    include ::User::Repository
+
+    attr_reader :records
+
+    def initialize
+      @records = []
+    end
+
+    def create(name:, email:)
+      id = @records.size + 1
+
+      @records[id] = { id:, name:, email: }
+
+      ::User::Data.new(id:, name:, email:)
+    end
+  end
+end

data/lib/bcdd/contract/assertions.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BCDD::Contract
+  module Assertions
+    def assert!(...)
+      ::BCDD::Contract.assert!(...)
+    end
+
+    def refute!(...)
+      ::BCDD::Contract.refute!(...)
+    end
+
+    def assert(...)
+      ::BCDD::Contract.assert(...)
+    end
+
+    def refute(...)
+      ::BCDD::Contract.refute(...)
+    end
+  end
+end

data/lib/bcdd/contract/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module BCDD::Contract
+  # A singleton class to store the configuration of the gem.
+  #
+  class Config
+    include ::Singleton
+
+    attr_accessor :proxy_enabled, :interface_enabled, :assertions_enabled
+
+    def initialize
+      self.proxy_enabled = true
+      self.interface_enabled = true
+      self.assertions_enabled = true
+    end
+
+    def options
+      {
+        proxy_enabled: proxy_enabled,
+        interface_enabled: interface_enabled,
+        assertions_enabled: assertions_enabled
+      }
+    end
+  end
+end

data/lib/bcdd/contract/core/checker.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BCDD::Contract
+  module Core::Checker
+    def [](value)
+      checking.new(strategy, value)
+    end
+
+    def ===(value)
+      self[value].valid?
+    end
+
+    def to_proc
+      ->(value) { self[value] }
+    end
+
+    def invariant(value)
+      self[value].raise_validation_errors!
+
+      output = yield(value)
+
+      self[value].raise_validation_errors!
+
+      output
+    end
+
+    protected
+
+    def checking
+      const_get(:CHECKING, false)
+    end
+
+    def strategy
+      const_get(:STRATEGY, false)
+    end
+  end
+end

data/lib/bcdd/contract/core/checking.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BCDD::Contract
+  module Core::Checking
+    attr_reader :value, :errors
+
+    def initialize(_checker, _value)
+      raise Error, 'not implemented'
+    end
+
+    def valid?
+      errors.empty?
+    end
+
+    def invalid?
+      !valid?
+    end
+
+    alias errors? invalid?
+
+    def errors_message
+      raise Error, 'not implemented'
+    end
+
+    def raise_validation_errors!
+      raise Error, errors_message if invalid?
+    end
+
+    def value_or_raise_validation_errors!
+      raise_validation_errors! || value
+    end
+
+    alias !@ value_or_raise_validation_errors!
+    alias +@ value_or_raise_validation_errors!
+    alias value! value_or_raise_validation_errors!
+    alias assert! value_or_raise_validation_errors!
+  end
+end

data/lib/bcdd/contract/core/factory.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module BCDD::Contract
+  module Core::Factory
+    module Callbacks
+      def included(_base)
+        raise Error, 'A contract checker cannot be included'
+      end
+
+      def extended(base)
+        if !base.is_a?(::Module) || base.is_a?(::Class)
+          raise Error, 'A contract checker can only be extended by a module'
+        end
+
+        mod = Module.new
+        mod.send(:include, Core::Checker)
+
+        base.const_set(:CHECKING, self::CHECKING)
+        base.const_set(:STRATEGY, self::STRATEGY)
+        base.extend(mod)
+      end
+    end
+
+    def self.new(checker, checking, strategy)
+      mod = ::Module.new
+      mod.const_set(:CHECKING, checking)
+      mod.const_set(:STRATEGY, strategy)
+      mod.extend(Callbacks)
+      mod.extend(checker)
+    end
+  end
+end