easy_command 1.0.0.pre.rc1

data/easy_command.gemspec

@@ -0,0 +1,26 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'easy_command/version'
+
+Gem::Specification.new do |s|
+  s.required_ruby_version = '>= 2.7'
+  s.name          = 'easy_command'
+  s.version       = EasyCommand::VERSION
+  s.authors       = ['Swile']
+  s.email         = ['ruby-maintainers@swile.co']
+  s.summary       = 'Easy way to build and manage commands (service objects)'
+  s.description   = 'Easy way to build and manage commands (service objects)'
+  s.homepage      = 'http://github.com/Swile/easy-command'
+  s.license       = 'MIT'
+
+  s.metadata['rubygems_mfa_required'] = 'true'
+
+  s.metadata["source_code_uri"] = "https://github.com/Swile/easy-command"
+  s.metadata["github_repo"] = "ssh://github.com/Swile/easy-command"
+
+  s.files         = `git ls-files -z`.split("\x0")
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_development_dependency 'bundler', '~> 2.0' # rubocop:disable Gemspec/DevelopmentDependencies
+end

data/lib/easy_command/chainable.rb

@@ -0,0 +1,16 @@
+module EasyCommand
+  module Chainable
+    def then(other)
+      if success?
+        other.call(result)
+      else
+        self
+      end
+    end
+    alias_method :|, :then
+
+    def self.included(klass)
+      klass.define_method(:call) { self } unless klass.instance_methods.include? :call
+    end
+  end
+end

data/lib/easy_command/errors.rb

@@ -0,0 +1,85 @@
+module EasyCommand
+  class NotImplementedError < ::StandardError; end
+
+  class Errors < Hash
+    attr_reader :source
+
+    def initialize(source: nil)
+      @source = source
+      super()
+    end
+
+    def exists?(attribute, code)
+      fetch(attribute, []).any? { |e| e[:code] == code }
+    end
+    alias_method :has_error?, :exists?
+
+    def add(attribute, code, message_or_key = nil, **options)
+      code = code.to_sym
+      message_or_key ||= code
+
+      if defined?(I18n)
+        # Can't use `I18n.exists?` because it doesn't accept a scope: kwarg
+        message =
+          begin
+            I18n.t!(message_or_key, scope: source&.i18n_scope, **options)
+          rescue I18n::MissingTranslationData
+            nil
+          end
+      end
+      message ||= message_or_key
+
+      self[attribute] ||= []
+      self[attribute] << { code: code, message: message }
+      self[attribute].uniq!
+    end
+
+    def merge_from(object)
+      raise ArgumentError unless object.respond_to?(:errors)
+      errors =
+        if object.errors.respond_to?(:messages)
+          object.errors.messages.each_with_object({}) do |(attribute, messages), object_errors|
+            object_errors[attribute] = messages.
+              zip(object.errors.details[attribute]).
+              map { |message, detail| [detail[:error], message] }
+          end
+        else
+          object.errors
+        end
+
+      add_multiple_errors(errors)
+    end
+
+    def add_multiple_errors(errors_hash)
+      errors_hash.each do |key, values|
+        values.each do |value|
+          if value.is_a?(Hash)
+            code = value[:code]
+            message_or_key = value[:message]
+          else
+            code = value.first
+            message_or_key = value.last || value.first
+          end
+          add(key, code, message_or_key)
+        end
+      end
+    end
+
+    # For SimpleCommand gem compatibility, to ease migration.
+    def full_messages
+      messages = []
+      each do |attribute, errors|
+        errors.each do |error|
+          messages << full_message(attribute, error[:message])
+        end
+      end
+      messages
+    end
+
+    def full_message(attribute, message)
+      return message if attribute == :base
+      attr_name = attribute.to_s.tr('.', '_').capitalize
+      format("%s %s", attr_name, message)
+    end
+  end
+end

data/lib/easy_command/result.rb

@@ -0,0 +1,53 @@
+require 'easy_command/chainable'
+
+module EasyCommand
+  class Result
+    include Chainable
+
+    def initialize(content)
+      @content = content
+    end
+
+    def result
+      @content
+    end
+
+    def errors
+      EasyCommand::Errors.new
+    end
+
+    def failure?; false; end
+    def success?; true; end
+
+    def on_success
+      yield(result) if success?
+      self
+    end
+
+    def on_failure
+      yield(errors) if failure?
+      self
+    end
+  end
+
+  class Success < Result; end
+
+  class Params < Result; end
+
+  class Failure < Result
+    def success?; false; end
+    def failure?; true; end
+
+    def with_errors(errors)
+      @_errors = errors
+      self
+    end
+
+    def errors
+      @_errors ||=
+        EasyCommand::Errors.new.tap do |errors|
+          errors.add(:result, :failure)
+        end
+    end
+  end
+end

data/lib/easy_command/ruby-2-7-specific.rb

@@ -0,0 +1,49 @@
+# rubocop:disable Naming/FileName
+# rubocop:enable Naming/FileName
+# frozen_string_literal: true
+
+module EasyCommand
+  class Result
+    module ClassMethods
+      ruby2_keywords def [](*args)
+        new(*args)
+      end
+    end
+    extend ClassMethods
+  end
+
+  module ClassMethods
+    ruby2_keywords def call(*args)
+      new(*args).call
+    end
+  end
+
+  ruby2_keywords def abort(*args)
+    errors.add(*args)
+    raise ExitError
+  end
+
+  module LegacyErrorHandling
+    # Convenience/retrocompatibility aliases
+    def self.errors_legacy_alias(method, errors_method)
+      ruby2_keywords define_method(method) { |*args|
+        warn "/!\\ #{method} is deprecated, please use errors.#{errors_method} instead."
+        errors.__send__ errors_method, *args
+      }
+    end
+  end
+
+  ruby2_keywords def assert_subcommand(klass, *args)
+    command_instance = klass.new(*args).as_sub_command
+    (@sub_commands ||= []) << command_instance
+    command = command_instance.call
+    return command.result if command.success?
+    errors.merge_from(command)
+    raise ExitError.new(result: command.result)
+  end
+
+  def assert_sub(...)
+    warn "/!\\ 'assert_sub' is deprecated, please use 'assert_subcommand' instead."
+    assert_subcommand(...)
+  end
+end

data/lib/easy_command/ruby-2-specific.rb

@@ -0,0 +1,53 @@
+# rubocop:disable Naming/FileName
+# rubocop:enable Naming/FileName
+# frozen_string_literal: true
+
+module EasyCommand
+  class Result
+    module ClassMethods
+      def [](*args)
+        new(*args)
+      end
+    end
+    extend ClassMethods
+  end
+
+  module ClassMethods
+    def call(*args)
+      new(*args).call
+    end
+  end
+
+  def abort(*args)
+    errors.add(*args)
+    raise ExitError
+  end
+
+  def assert(*_args)
+    raise ExitError if errors.any?
+  end
+
+  module LegacyErrorHandling
+    # Convenience/retrocompatibility aliases
+    def self.errors_legacy_alias(method, errors_method)
+      define_method method do |*args|
+        warn "/!\\ #{method} is deprecated, please use errors.#{errors_method} instead."
+        errors.__send__ errors_method, *args
+      end
+    end
+  end
+
+  def assert_subcommand(klass, *args)
+    command_instance = klass.new(*args).as_sub_command
+    (@sub_commands ||= []) << command_instance
+    command = command_instance.call
+    return command.result if command.success?
+    errors.merge_from(command)
+    raise ExitError.new(result: command.result)
+  end
+
+  def assert_sub(klass, *args)
+    warn "/!\\ 'assert_sub' is deprecated, please use 'assert_subcommand' instead."
+    assert_subcommand(klass, *args)
+  end
+end

data/lib/easy_command/ruby-3-specific.rb

@@ -0,0 +1,49 @@
+# rubocop:disable Naming/FileName
+# rubocop:enable Naming/FileName
+# frozen_string_literal: true
+
+module EasyCommand
+  class Result
+    module ClassMethods
+      def [](*args, **kwargs)
+        new(*args, **kwargs)
+      end
+    end
+    extend ClassMethods
+  end
+
+  module ClassMethods
+    def call(*args, **kwargs)
+      new(*args, **kwargs).call
+    end
+  end
+
+  def abort(*args, **kwargs)
+    errors.add(*args, **kwargs)
+    raise ExitError
+  end
+
+  module LegacyErrorHandling
+    # Convenience/retrocompatibility aliases
+    def self.errors_legacy_alias(method, errors_method)
+      define_method method do |*args, **kwargs|
+        warn "/!\\ #{method} is deprecated, please use errors.#{errors_method} instead."
+        errors.__send__ errors_method, *args, **kwargs
+      end
+    end
+  end
+
+  def assert_subcommand(klass, *args, **kwargs)
+    command_instance = klass.new(*args, **kwargs).as_sub_command
+    (@sub_commands ||= []) << command_instance
+    command = command_instance.call
+    return command.result if command.success?
+    errors.merge_from(command)
+    raise ExitError.new(result: command.result)
+  end
+
+  def assert_sub(...)
+    warn "/!\\ 'assert_sub' is deprecated, please use 'assert_subcommand' instead."
+    assert_subcommand(...)
+  end
+end

data/lib/easy_command/spec_helpers/command_matchers.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# TODO: Rewrite this as a pure module definition to remove dependency on RSpec
+require 'rspec/matchers'
+
+=begin
+it { expect(Extinguishers::PayloadValidator).to have_been_called_with_acp(payload) }
+it { is_expected.to be_failure }
+it { is_expected.to have_failed }
+it { is_expected.to have_failed.with_error(:date, :invalid) }
+it { is_expected.to have_failed.with_error(:date, :invalid, "The format must be iso8601") }
+it { is_expected.to have_error(:date, :invalid) }
+it { is_expected.to have_error(:date, :invalid, "The format must be iso8601") }
+=end
+module EasyCommand
+  module SpecHelpers
+    module CommandMatchers
+      extend RSpec::Matchers::DSL
+
+      matcher :have_been_called_with_action_controller_parameters do
+        match(notify_expectation_failures: true) do |command_class|
+          expect(command_class).to have_received(:call).
+            with(an_instance_of(ActionController::Parameters)) do |params|
+              expect(params.to_unsafe_h).to match(payload)
+            end
+        end
+      end
+      alias_matcher :have_been_called_with_ac_parameters, :have_been_called_with_action_controller_parameters
+      alias_matcher :have_been_called_with_acp, :have_been_called_with_action_controller_parameters
+
+      matcher :have_failed do
+        match(notify_expectation_failures: true) do |result|
+          expect(result).to have_error(@key, @code, @message) if @key.presence
+          result.failure?
+        rescue RSpec::Expectations::ExpectationNotMetError => e
+          @matcher_error_message = e.message
+          false
+        end
+
+        chain :with_error do |key, code, message = nil|
+          @key = key
+          @code = code
+          @message = message
+        end
+
+        failure_message do
+          @matcher_error_message
+        end
+      end
+
+      matcher :have_error do
+        match do |result|
+          if message.presence
+            result.errors[key]&.include?(code: code, message: message)
+          else
+            result.errors.exists?(key, code)
+          end
+        end
+
+        failure_message do
+          err = "expected #{command_name} to have errors on #{to_txt key} with code #{to_txt code}"
+          err += " and message #{to_txt message}" if message.present?
+          err += "\nactual error for #{to_txt key}: #{@actual.errors[key] || 'nil'}"
+          err
+        end
+
+        def command_name
+          actual.class.name
+        end
+
+        def key
+          expected.first
+        end
+
+        def code
+          expected.second
+        end
+
+        def message
+          expected.third
+        end
+
+        def to_txt(value)
+          value.is_a?(Symbol) ? ":#{value}" : "\"#{value}\""
+        end
+      end
+    end
+  end
+end

data/lib/easy_command/spec_helpers/mock_command_helper.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module EasyCommand
+  module SpecHelpers
+    module MockCommandHelper
+      NO_PARAMS_PASSED = Object.new
+
+      def mock_successful_command(command, result:, params: NO_PARAMS_PASSED)
+        mock_command(command, success: true, result: result, params: params)
+      end
+
+=begin
+    Example :
+      mock_unsuccessful_command(ExtinguishDebtAndLetterIt, errors: {
+        entry: { not_found: "Couldn't find Entry with 'document_identifier'='foo'" }
+      })
+
+    is equivalent to
+      mock_command(ExtinguishDebtAndLetterIt,
+        success: false,
+        result: nil,
+        errors: {:entry=>[code: :not_found, message: "Couldn't find Entry with 'document_identifier'='foo'"]},
+      )
+=end
+      def mock_unsuccessful_command(command, errors:, params: NO_PARAMS_PASSED)
+        mock_command(command, success: false, errors: detailed_errors(errors), params: params)
+      end
+
+      def mock_command(command, success:, result: nil, errors: {}, params: NO_PARAMS_PASSED)
+        if Object.const_defined?('FakeCommandErrors')
+          klass = Object.const_get('FakeCommandErrors')
+        else
+          klass = Object.const_set 'FakeCommandErrors', Class.new
+          klass.prepend Command
+        end
+        fake_command = klass.new
+        if errors.any?
+          errors.each do |attr, details|
+            details.each do |detail|
+              fake_command.errors.add(attr, detail[:code], detail[:message])
+            end
+          end
+        end
+        double = instance_double(command)
+        allow(double).to receive(:as_sub_command).and_return(double)
+        allow(double).to receive(:errors).and_return(fake_command.errors)
+        monad =
+          if success
+            Command::Success.new(result)
+          else
+            Command::Failure.new(result).with_errors(fake_command.errors)
+          end
+        allow(double).to receive(:call).and_return(monad)
+        allow(double).to receive(:on_success).and_return(double)
+        if params == NO_PARAMS_PASSED
+          allow(command).to receive(:call).and_return(monad)
+          allow(command).to receive(:new).and_return(double)
+        else
+          mock_params, hash_params = extract_mock_params(params)
+          allow(command).to receive(:call).with(*mock_params, **hash_params).and_return(monad)
+          allow(command).to receive(:new).with(*mock_params, **hash_params).and_return(double)
+        end
+        double
+      end
+
+      private
+
+      def extract_mock_params(params)
+        if params.is_a? Array
+          kw_params =
+            if params.last.is_a? Hash
+              params.pop
+            else
+              {}
+            end
+          [params, kw_params]
+        else
+          [[params], {}]
+        end
+      end
+
+      def detailed_errors(errors)
+        errors.transform_values do |detail|
+          detail.map { |code, message| { code: code, message: message } }
+        end
+      end
+    end
+  end
+end

data/lib/easy_command/spec_helpers.rb

@@ -0,0 +1,2 @@
+require 'easy_command/spec_helpers/command_matchers'
+require 'easy_command/spec_helpers/mock_command_helper'

data/lib/easy_command/version.rb

@@ -0,0 +1,3 @@
+module EasyCommand
+  VERSION = '1.0.0-rc1'.freeze
+end

data/lib/easy_command.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'byebug'
+if RUBY_VERSION >= "3"
+  require "easy_command/ruby-3-specific"
+elsif RUBY_VERSION.start_with? "2.7"
+  require "easy_command/ruby-2-7-specific"
+else
+  require "easy_command/ruby-2-specific"
+end
+
+require 'easy_command/errors'
+require 'easy_command/result'
+require 'easy_command/version'
+
+module EasyCommand
+  class CommandError < RuntimeError
+    attr_reader :code
+
+    def initialize(message = nil, code = nil)
+      @code = code
+      super(message)
+    end
+  end
+
+  class ExitError < CommandError
+    attr_reader :result
+
+    def initialize(message = nil, code = nil, result: nil)
+      @result = result
+      super(message, code)
+    end
+  end
+
+  def self.prepended(base)
+    base.extend ClassMethods
+  end
+
+  attr_reader :result
+
+  module ClassMethods
+    def self.extended(base)
+      base.i18n_scope = "errors.messages"
+    end
+    attr_accessor :i18n_scope
+  end
+
+  def call
+    raise NotImplementedError unless defined?(super)
+
+    result = super
+    if errors.none?
+      on_success unless @as_sub_command
+      Success[result]
+    else
+      Failure[result].with_errors(errors)
+    end
+  rescue ExitError => e
+    Failure[@result || e.result].with_errors(errors)
+  end
+
+  def abort(*args, result: nil, **kwargs)
+    errors.add(*args, **kwargs)
+    raise ExitError.new(result: result)
+  end
+
+  def assert(*_args, result: nil)
+    raise ExitError.new(result: result) if errors.any?
+  end
+
+  def errors
+    @_errors ||= EasyCommand::Errors.new(source: self.class)
+  end
+
+  def on_success
+    (@sub_commands ||= []).each(&:on_success)
+
+    super if defined?(super)
+  end
+
+  module LegacyErrorHandling
+    errors_legacy_alias :clear_errors, :clear
+    errors_legacy_alias :add_error, :add
+    errors_legacy_alias :merge_errors_from, :merge_from
+    errors_legacy_alias :has_error?, :exists?
+    errors_legacy_alias :full_errors, :itself
+  end
+  include LegacyErrorHandling
+
+  def as_sub_command
+    @as_sub_command = true
+    self
+  end
+end

data/locales/en.yml

@@ -0,0 +1,2 @@
+en:
+  hello: 'hello'

data/release-please-config.json

@@ -0,0 +1,11 @@
+{
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "extra-files": [
+        "easy_command.gemspec"
+      ],
+      "version-file": "lib/easy_command/version.rb"
+    }
+  }
+}