hexx 0.0.1

data/lib/generators/use_case/templates/use_case_spec.erb

@@ -0,0 +1,77 @@
+require "spec_helper"
+
+module <%= module_name %>
+  describe <%= class_name %> do
+
+    # ==========================================================================
+    # Prepare environment
+    # ==========================================================================
+
+    # before { Timecop.freeze }
+    # after  { Timecop.return }
+
+    # ==========================================================================
+    # Prepare variables
+    # ==========================================================================
+
+    # let!(:params)          { { key: value } }
+    # let!(:expected_result) { { something.to_struct.inspect } }
+    # let!(:listener)        { double "listener" }
+
+    # def prepare_case(params)
+    #   use_case = <%= class_name %>.new params
+    #   use_case.subscribe(listener)
+    #   use_case
+    # end
+
+    # ==========================================================================
+    # Run tests
+    # ==========================================================================
+
+    describe "#run" do
+
+      # context "with proper params" do
+
+      #   let!(:use_case) { prepare_case params }
+
+      #   it "does something" do
+      #     expect { use_case.run }.to change { something }
+      #       .from(something).to(something)
+      #   end
+
+      #   it "returns something" do
+      #     expect(use_case.run.inspect).to eq expected_result
+      #   end
+
+      #   it "sends 'something' to subscribers" do
+      #     expect(listener).to receive :something do |result|
+      #       expect(result.inspect).to eq expected_result
+      #     end
+      #     use_case.run
+      #   end
+      # end
+
+      # context "with some improper params" do
+
+      #   before { params[:something] = something }
+      #   let!(:use_case) { prepare_case params }
+
+      #   it "doesn't do something" do
+      #     expect { use_case.run }.not_to change { something }
+      #       .from something
+      #   end
+
+      #   it "returns nil" do
+      #     expect(use_case.run).to be_nil
+      #   end
+
+      #   it "sends 'error' to subscribers" do
+      #     expect(listener).to receive :error do |messages|
+      #       expect(messages).not_to be_blank
+      #     end
+      #     use_case.run
+      #   end
+      # end
+    end
+  end
+end

data/lib/generators/use_case/use_case.rb

@@ -0,0 +1,31 @@
+require_relative "../base"
+
+module Hexx
+  module Generators
+
+    # Use case scaffolder.
+    class UseCase < Base
+
+      def self.source_root
+        super __FILE__
+      end
+
+      def add_use_case
+        template "use_case.erb", "app/#{ use_cases_path }/#{ file_name }.rb"
+      end
+
+      def add_use_case_spec
+        template(
+          "use_case_spec.erb",
+          "spec/#{ use_cases_path }/#{ file_name }_spec.rb"
+        )
+      end
+
+      private
+
+      def use_cases_path
+        "use_cases/#{ gem_name }"
+      end
+    end
+  end
+end

data/lib/hexx.rb

@@ -0,0 +1,2 @@
+lib = File.dirname(__FILE__)
+Dir[File.join(lib, "hexx/**/*.rb")].each { |file| require file }

data/lib/hexx/exceptions/not_found_error.rb

@@ -0,0 +1,12 @@
+require_relative "runtime_error"
+
+module Hexx
+
+  # An exception to be raised in case some record not found
+  class NotFoundError < RuntimeError
+
+    def message
+      "Not found: #{ errors.inspect }"
+    end
+  end
+end

data/lib/hexx/exceptions/record_invalid.rb

@@ -0,0 +1,12 @@
+require_relative "runtime_error"
+
+module Hexx
+
+  # An exception to be raised by the <tt>Hexx::Models#validate!</tt> method.
+  class RecordInvalid < RuntimeError
+
+    def message
+      "Invalid use case: #{ errors.inspect }"
+    end
+  end
+end

data/lib/hexx/exceptions/runtime_error.rb

@@ -0,0 +1,24 @@
+module Hexx
+
+  # An exception to be raised by some method with given object.
+  #
+  # It is expected, that the object stores error messages in its <tt>errors</tt>
+  # collection.
+  #
+  class RuntimeError < ::RuntimeError
+
+    attr_reader :object
+
+    def initialize(object)
+      @object = object
+    end
+
+    def errors
+      object.errors if object
+    end
+
+    def message
+      "Runtime error: #{ errors.inspect }"
+    end
+  end
+end

data/lib/hexx/exceptions/use_case_invalid.rb

@@ -0,0 +1,12 @@
+require_relative "runtime_error"
+
+module Hexx
+
+  # An exception to be raised by the <tt>UseCase#validate!</tt> method.
+  class UseCaseInvalid < RuntimeError
+
+    def message
+      "Invalid use case: #{ errors.inspect }"
+    end
+  end
+end

data/lib/hexx/models.rb

@@ -0,0 +1,82 @@
+require "active_support"
+
+module Hexx
+
+  # Module defines:
+  #
+  # * <tt>validate!</tt> public instance method
+  # * +attr_coerced+ public class methods.
+  #
+  # Include the module into the Rails model:
+  #
+  #   require "hexx"
+  #   require_relative "attributes/string"
+  #
+  #   class User < ActiveRecord::Base
+  #     include Hexx::Models
+  #
+  #     # coerces attributes
+  #     attr_coerced :name, login, type: Attributes::String
+  #   end
+  #
+  module Models
+    extend ActiveSupport::Concern
+
+    def validate!
+      return true if valid?
+      fail RecordInvalid.new self
+    end
+
+    # Model class helpers for attributes coercion.
+    module ClassMethods
+
+      def attr_coerced(*names, type:)
+        names.each { |name| _attr_coerced(name, type) }
+      end
+
+      private
+
+      def _attr_coerced(name, type)
+        if ancestors.map(&:name).include? "ActiveRecord::Base"
+          coerce_activerecord_reader name, type
+          coerce_activerecord_writer name, type
+        else
+          coerce_simple_reader name, type
+          coerce_simple_writer name, type
+        end
+      end
+
+      def coerce_simple_reader(name, type)
+        class_eval(
+          "def #{ name };
+            #{ type.name }.new(@#{ name });
+          end"
+        )
+      end
+
+      def coerce_simple_writer(name, type)
+        class_eval(
+          "def #{ name }=(value);
+            @#{ name } = #{ type.name }.new(value);
+          end"
+        )
+      end
+
+      def coerce_activerecord_reader(name, type)
+        class_eval(
+          "def #{ name };
+            #{ type.name }.new read_attribute(:#{ name });
+          end"
+        )
+      end
+
+      def coerce_activerecord_writer(name, type)
+        class_eval(
+          "def #{ name }=(value);
+            write_attribute :#{ name }, #{ type.name }.new(value);
+          end"
+        )
+      end
+    end
+  end
+end

data/lib/hexx/settings.rb

@@ -0,0 +1,47 @@
+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

@@ -0,0 +1,228 @@
+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 422 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
+
+    def run!
+      fail(NotImplementedError.new "#{ self.class.name }#run! not implemented")
+    end
+
+    def run
+      run!
+    rescue Hexx::NotFoundError => error
+      finish_with :not_found, error.errors.values
+    rescue Hexx::RuntimeError => error
+      finish_with :error, error.errors.values
+    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, arg)
+      publish name, arg
+      nil
+    end
+  end
+end