hexx 1.1.1 → 2.0.0

data/lib/hexx/settings.rb

@@ -1,47 +0,0 @@
-require "active_support"
-
-module Hexx
-
-  # Storage for dependencies.
-  #
-  # Include it to your domain module and declare necessary dependencies.
-  #
-  #   module MyProject
-  #     include Hexx::Settigns
-  #     class << self
-  #
-  #       depends_on :some_class
-  #     end
-  #   end
-  #
-  # Then you can add a setting:
-  #
-  #   # config/initializers/my_project.rb
-  #   MyProject.configure do |c|
-  #     c.some_class_name = "ExternalModule::SomeClass"
-  #   end
-  #
-  # And use it in a code:
-  #
-  #   MyProject.some_class # => ExternalModule::SomeClass
-  #
-  module Settings
-    extend ActiveSupport::Concern
-
-    # Settings helpers
-    module ClassMethods
-
-      def configure(&block)
-        block.call(self) if block_given?
-      end
-
-      def depends_on(name)
-        cattr_accessor "#{ name }_name"
-        define_singleton_method name do
-          const = send "#{ name }_name"
-          const ? Kernel.const_get(const) : nil
-        end
-      end
-    end
-  end
-end

data/lib/hexx/use_case.rb

@@ -1,256 +0,0 @@
-require "active_model"
-require "wisper"
-
-module Hexx
-
-  # = About
-  #
-  # Use cases are a core part of a domain. They implement case-specific business
-  # rules (unlike Entities) and named as an imperative (_Add_Doc_, _Get_Doc_).
-  #
-  # Typical use case provides 5 methods:
-  #
-  # +new+:: class method that initializes use case instance.
-  # +subscribe+:: subscribes listeners for the use case notifications.
-  # +run+:: implements the use case.
-  # +run!+:: raises exceptions in case of errors.
-  # +errors+:: collects use case errors.
-  #
-  # The +run+ method returns a corresponding Value object, and notifies
-  # subscribers about the results (following The Observer Pattern).
-  #
-  # = Usage
-  #
-  # Inherit a use case from the <tt>Hexx::UseCase</tt> class:
-  #
-  #   # app/my_domain/use_cases/do_something.rb
-  #   require "hexx"
-  #
-  #   module MyDomain
-  #     class DoSomething < Hexx::UseCase
-  #     end
-  #   end
-  #
-  # Then add a <tt>run!</tt> instance method to the Use Case.
-  #
-  #   class DoSomething < Hexx::UseCase
-  #
-  #     def run!
-  #       validate!
-  #       # do something
-  #     end
-  #   end
-  #
-  # The +run+ (without a bang) method is defined by default (see below). If
-  # you need catching some exceptions specifically, do it in your <tt>run!</tt>
-  # method.
-  #
-  # Unless the <tt>run!</tt> method defined, calling the +run+ raises
-  # the <tt>NotImplementedError</tt>.
-  #
-  # == Allow params
-  #
-  # Use case constructor takes one argument with a parameters hash.
-  #
-  #   use_case = DoSomething.new id: 1, name: "name"
-  #
-  # This sets the private argument +params+ to be blank hash.
-  #
-  #   use_case.send :params # => {}
-  #
-  # For options to be assigned to +params+, their keys should be whitelisted:
-  #
-  #   class DoSomething < Hexx::UseCase
-  #
-  #     allow_params :id, :name
-  #   end
-  #
-  # This will allow assigning values. Note that all the keys are stringified:
-  #
-  #   use_case = DoSomething.new id: 1, name: "name", wrong_key: :value
-  #   use_case.send :params # => { "id" => 1, "name" => "name" }
-  #
-  # == Validations
-  #
-  # You can use ActiveRecord validations.
-  #
-  # Be careful! Both the <tt>valid?</tt>, and <tt>invalid?</tt> are private.
-  # It is expected validations to be used implicitly in a course of use case
-  # running.
-  #
-  # To do this a private method <tt>validate!</tt> is available. It raises the
-  # <tt>Hexx::UseCaseInvalid</tt> exception in case of validation fails.
-  #
-  # Note the <tt>validate!</tt> private method call from the <tt>run!</tt>
-  # method in the example above.
-  #
-  # == Running a use case
-  #
-  # The <tt>run</tt> method is defined in a base class. This method
-  # catches some exceptions and publishes corresponding notifications:
-  #
-  # <tt>Hexx::NotFoundError</tt>:: publishes the <tt>not_found(messages)</tt>;
-  # <tt>Hexx::UseCaseInvalid</tt>:: publishes the <tt>error(messages)</tt>;
-  # <tt>Hexx::EntityInvalid</tt>:: publishes the <tt>error(messages)</tt>;
-  # <tt>StandardError</tt>:: any other runtume exception.
-  #
-  # == Notifications publishing
-  #
-  # A use case is expected to publish notifications for its subscribers.
-  #
-  #   class DoSomething < Hexx::UseCase
-  #
-  #     def run!
-  #       validate!
-  #       # do something (raise in case of any error)
-  #       publish :done, result
-  #       return result
-  #     end
-  #   end
-  #
-  # This will call a +done+ method of any subscriber. For details see the
-  # {wisper gem documentation}[https://github.com/krisleech/wisper].
-  #
-  # == Calling a use case
-  #
-  # Use cases can be called in two styles:
-  #
-  # === Observer Pattern style (main usage)
-  #
-  # From a controller you can call a use case:
-  #
-  #   # app/controllers/my_controller.rb
-  #   class MyController < ActionController::Base
-  #
-  #     def my_action
-  #       # initialize a use case
-  #       use_case = DoSomething.new params
-  #       # subscribe both controller (in a presenter role) and other services
-  #       # such as mailers etc. to receive notifications.
-  #       use_case.subscribe self
-  #       use_case.subscribe MyMailer.new
-  #       # run a use_case
-  #       use_case.run
-  #     end
-  #
-  #     # the method will be called by <tt>use_case.run</tt> in case of
-  #     # success (see the Notification publishing example above).
-  #     def done(result)
-  #       # return a response 200 to the user
-  #     end
-  #
-  #     # the method will be called by <tt>use_case.run</tt> in case of
-  #     # NotFoundError raised.
-  #     def not_found(options = {})
-  #       # return a response 404 to the user
-  #     end
-  #
-  #     # this method will be called by use_case in case of any error
-  #     def error(messages = [])
-  #       # return a response 400 to the user
-  #     end
-  #   end
-  #
-  # === Procedural style
-  #
-  # When you use a case from another case it can be useful to get value directly
-  # without a subscription.
-  #
-  #   use_case = DoSomething.new params
-  #   result = use_case.run
-  #
-  # The +run+ method returns nil in case of any error.
-  #
-  # = Dependencies notes
-  #
-  # Use cases depends on:
-  #
-  # * *Entities* and their *Repositories*;
-  # * *Values* as an interfaces to external services (controllers, mailers etc.)
-  #
-  # Use cases should not depend from external services outside of the domain
-  # model: controllers, mailers, databases etc.
-  #
-  class UseCase
-    include ActiveModel::Validations, Wisper::Publisher
-
-    class << self
-
-      def allow_params(*keys)
-        @params = keys.map(&:to_s)
-      end
-
-      private
-
-      def params
-        @params ||= []
-      end
-    end
-
-    def initialize(options = {})
-      if options.is_a? Hash
-        @params = options.stringify_keys.slice(*self.class.send(:params))
-      else
-        @params = {}
-      end
-    end
-
-    # Runs a case and raises an exceptions.
-    #
-    # Expected to be called from another use cases. For example, in the case
-    # below calling a <tt>GetItem#run!</tt> will raise an exception if item
-    # not found. Further on the exception will be catched in
-    # <tt>DeleteItem#run</tt> method as its own.
-    #
-    #   class DeleteItem < Hexx::UseCase
-    #
-    #     allow_params :id
-    #
-    #     def run!
-    #       item = GetItem.new(params).run!
-    #       item.delete!
-    #     end
-    #   end
-    #
-    def run!
-      fail(NotImplementedError.new "#{ self.class.name }#run! not implemented")
-    end
-
-    # Runs a case and works out exceptions with sending corresponding
-    # notifications to listeners.
-    #
-    # Expected to be called from a controller action.
-    #
-    def run
-      run!
-    rescue Hexx::NotFoundError => error
-      finish_with :not_found, error.messages
-    rescue Hexx::RuntimeError => error
-      finish_with :error, error.messages
-    rescue StandardError => error
-      finish_with :error, [error.message]
-    end
-
-    private :valid?, :invalid?
-
-    private
-
-    attr_reader :params
-
-    def validate!
-      return if valid?
-      fail UseCaseInvalid.new(self)
-    end
-
-    def finish_with(name, errors)
-      publish name, errors.map { |text| Message.new type: :error, text: text }
-      nil
-    end
-
-    def t(key, options = {})
-      return key unless key.is_a? Symbol
-      scope = %w(activemodel messages models) << self.class.name.underscore
-      I18n.t key, options.merge(scope: scope)
-    end
-  end
-end

data/spec/hexx/exceptions/not_found_error_spec.rb

@@ -1,21 +0,0 @@
-require "spec_helper"
-require "support/exception_matchers"
-
-module Hexx
-  describe NotFoundError do
-
-    subject { NotFoundError }
-
-    it "inherits RuntimeError" do
-      expect(subject).to inherit Hexx::RuntimeError
-    end
-
-    it "has customized message" do
-      use_case = Hexx::UseCase.new
-      allow(use_case)
-        .to receive_message_chain(:errors, :messages, :values)
-        .and_return %w(one two)
-      expect(subject.new(use_case).message).to eq "Not found: one; two"
-    end
-  end
-end

data/spec/hexx/exceptions/runtime_error_spec.rb

@@ -1,43 +0,0 @@
-require "spec_helper"
-require "support/exception_matchers"
-
-module Hexx
-  describe RuntimeError do
-
-    subject        { RuntimeError }
-    let(:use_case) { Hexx::UseCase.new }
-
-    it "inherits core RuntimeError" do
-      expect(subject).to inherit ::RuntimeError
-    end
-
-    describe ".new" do
-
-      it "requires Hexx::UseCase as an argument" do
-        expect { subject.new use_case }.not_to raise_error
-        expect { subject.new "" }.to raise_error
-        expect { subject.new }.to raise_error
-      end
-    end
-
-    describe "#messages" do
-
-      it "returns use case's error messages" do
-        allow(use_case)
-          .to receive_message_chain(:errors, :messages)
-          .and_return(argument: [:error])
-        expect(subject.new(use_case).messages).to eq [:error]
-      end
-    end
-
-    describe "#message" do
-
-      let!(:error) { subject.new use_case }
-      before { allow(error).to receive(:messages).and_return %w(one two) }
-
-      it "returns a proper text" do
-        expect(error.message).to eq "Runtime error: one; two"
-      end
-    end
-  end
-end

data/spec/hexx/exceptions/use_case_invalid_spec.rb

@@ -1,21 +0,0 @@
-require "spec_helper"
-require "support/exception_matchers"
-
-module Hexx
-  describe UseCaseInvalid do
-
-    subject { UseCaseInvalid }
-
-    it "inherits RuntimeError" do
-      expect(subject).to inherit Hexx::RuntimeError
-    end
-
-    it "has customized message" do
-      use_case = Hexx::UseCase.new
-      allow(use_case)
-        .to receive_message_chain(:errors, :messages, :values)
-        .and_return %w(one two)
-      expect(subject.new(use_case).message).to eq "Use case invalid: one; two"
-    end
-  end
-end

data/spec/hexx/message_spec.rb

@@ -1,31 +0,0 @@
-module Hexx
-  describe Message do
-
-    let!(:message) { Message.new type: "info", text: "" }
-
-    describe ".new" do
-
-      it "requires type" do
-        expect { Message.new text: "" }.to raise_error
-      end
-
-      it "requires text" do
-        expect { Message.new type: "" }.to raise_error
-      end
-    end
-
-    describe "#type=" do
-
-      it "sets the type" do
-        expect { message.type = :error }.to change { message.type }.to "error"
-      end
-    end
-
-    describe "#text=" do
-
-      it "sets the text" do
-        expect { message.text = "Text" }.to change { message.text }.to "Text"
-      end
-    end
-  end
-end

data/spec/hexx/settings_spec.rb

@@ -1,51 +0,0 @@
-require "spec_helper"
-
-module Hexx
-  describe Settings do
-
-    around do |example|
-      module TestModule; include Settings; end
-      class TestClass; end
-      example.run
-      Hexx.send :remove_const, :TestClass
-      Hexx.send :remove_const, :TestModule
-    end
-
-    subject { TestModule }
-
-    describe ".configure" do
-
-      it "is public" do
-        expect(subject).to respond_to(:configure).with(0).arguments
-      end
-
-      it "sends itself to a block" do
-        subject.configure do |config|
-          expect(config).to eq subject
-        end
-      end
-    end
-
-    describe ".depends_on" do
-
-      it "is public" do
-        expect(subject).to respond_to(:depends_on).with(1).argument
-      end
-
-      it "defines name settings accessor" do
-        subject.depends_on :test_class
-        expect(subject).to respond_to(:test_class_name).with(0).arguments
-        expect(subject).to respond_to(:test_class_name=).with(1).argument
-        expect { subject.test_class_name = "TestClass" }
-          .to change { subject.test_class_name }.from(nil).to "TestClass"
-      end
-
-      it "defines corresponding constant reader" do
-        subject.depends_on :test_class
-        expect(subject).to respond_to(:test_class).with(0).arguments
-        expect { subject.test_class_name = "Hexx::TestClass" }
-          .to change { subject.test_class }.from(nil).to TestClass
-      end
-    end
-  end
-end