hexx 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 44ade515af4a4044dce3725cf4a30ed2aef4da8e
-  data.tar.gz: 1c456b7fb78fe55d509019f03c0fbbce27a8f777
+  metadata.gz: 74a2ccdca4564ce9cef52e8eb3b3a1304f4ec783
+  data.tar.gz: 6906b51c7a50fec6aa501d123d9d9a1d6831b1f8
 SHA512:
-  metadata.gz: 255b6f79bd8726ffae49218d4f66ea397766ae79d265a2cdd353306217b5beedb73286e3c620f8ee45f2e42e94bf8ebf353452d9e504bdb35340009d1ac9a629
-  data.tar.gz: acdc38e43842a7be485378975c1b3dacc7e99b4ee0c53c500f2f35c369f70da4a60242712067d7bea8bb9dd9e692641adbce06659dc6736db7555423852c5c84
+  metadata.gz: 260e196ac0060995a5dc03e821fb14872013dfe689680973bad2e027e92a7c7c1e836241b83433a366fa3c8f55607031ea19e9226d0c0394256fd3fa40b13e41
+  data.tar.gz: 1cd7bdb303092c0cad0ab2d75c18c4f7fcd387ac0ac1556aaf21cfe328c08306bb69e885457eab8a0f799e4d495cc1238bc4bb50ee9f2047ba0ea87b49d4518a

data/README.rdoc

@@ -70,7 +70,7 @@ A typical service object is shown below:
     end
   end
 
-Usage of the service (with a Rails controller):
+Usage of the service (in a Rails controller):
 
   class ItemsController < ActionController::Base
 
@@ -141,6 +141,7 @@ preparation:
 == Relevant Links
 
 * Matt Wynne's talk {Hexagonal Rails}[http://www.confreaks.com/videos/977-goruco2012-hexagonal-rails]
+* { wisper }[http://www.github.com/krisleech/wisper] gem by Kris Leech.
 
 == License
 

data/lib/hexx/service/callbacks.rb

@@ -0,0 +1,77 @@
+module Hexx
+  class Service
+
+    # Allows to expose private callbacks to notifiers.
+    module Callbacks
+
+      # Grants access to object methods with given prefix.
+      #
+      # @example
+      #     WithCallbacks.new(object, prefix: :on)
+      #
+      # Params:
+      # +object+:: (required) ...a service object to access to.
+      # <tt>prefix:</tt>:: (optional, symbol or string, default: +nil+)
+      #                    ...prefix for private methods to be accessible.
+      #
+      class WithCallbacks
+
+        def initialize(object, prefix: nil)
+          @object = object
+          @prefix = Regexp.new(prefix ? "^#{ prefix }_" : "")
+        end
+
+        # Redefines the +respond_to?+ to allow access to object's methods.
+        #
+        # @example
+        #     service = WithCallbacks(some_service, prefix: :on)
+        #     service.respond_to? :on_something # => true
+        #
+        # Params:
+        # +method+:: a method name to check access to.
+        #
+        def respond_to?(method, *)
+          object.respond_to?(method) || valid_callback?(method) || super
+        end
+
+        private
+
+        def method_missing(method, *args, &block)
+          valid_callback?(method) ? object.send(method, *args, &block) : super
+        end
+
+        def valid_callback?(method)
+          method.to_s[prefix] && object.respond_to?(method, include_all: true)
+        end
+
+        attr_reader :object, :prefix
+      end
+
+      # Makes private methods with given prefix public.
+      #
+      # @example
+      #     class MyService < Hexx::Service
+      #       def call
+      #         # ...
+      #         other_service = OtherService.new
+      #         other_service.subscribe(self.with_callbacks(prefix: :on))
+      #       end
+      #
+      #       private
+      #
+      #       # private, but is made publicly accessible
+      #       def on_success
+      #         # ...
+      #       end
+      #     end
+      #
+      # Params:
+      # <tt>prefix:</tt>:: (optional, symbol or string, default: +nil+)
+      #                    ...prefix of private methods to be accessible.
+      #
+      def with_callbacks(prefix: nil)
+        WithCallbacks.new(self, prefix: prefix)
+      end
+    end
+  end
+end

data/lib/hexx/service/message.rb

@@ -35,19 +35,36 @@ module Hexx
         end
       end
 
-      # Compares two messages by type and text.
+      # Distinguishes two messages by type and text.
+      #
+      # @example
+      #     a = Message.new(type: "a", text: "a")
+      #     b = Message.new(type: "a", text: "a")
+      #     c = Message.new(type: "b", text: "a")
+      #     d = Message.new(type: "a", text: "b")
+      #
+      #     a == b # => true
+      #     a == c # => false
+      #     a == d # => false
+      #
+      # Params:
+      # +other+:: other message to distinguish from.
+      #
       def ==(other)
         return false unless other.is_a? self.class
         [type, text] == [other.type, other.text]
       end
 
-      # Orders messages by type and text.
+      # Compares messages by type and text.
       #
       # @example
       #     ab = Message.new(type: "a", text: "b")
       #     ba = Message.new(type: "b", text: "a")
       #     ab < ba # => true
       #
+      # Params:
+      # +other+:: other message to compare with.
+      #
       def <=>(other)
         fail ArgumentError unless other.is_a? self.class
         [type, text] <=> [other.type, other.text]

data/lib/hexx/service/parameters.rb

@@ -8,12 +8,15 @@ module Hexx
       # Methods to declare and allow services params.
       module ClassMethods
 
-        private
-
+        # A list of allowed params for the service objects.
         def params
           @params ||= []
         end
 
+        private
+
+        # Sets a list of allowed parameters for the class constructor and
+        # adds corresponding attributes to instance methods.
         def allow_params(*keys)
           @params = keys.map(&:to_s)
           attr_accessor(*params)
@@ -30,7 +33,7 @@ module Hexx
       #
       def initialize(hash = {})
         extract_params_from hash
-        params.each { |key, value| send "#{ key }=", value }
+        params.each { |key, value| public_send "#{ key }=", value }
       end
 
       private
@@ -38,7 +41,7 @@ module Hexx
       attr_reader :params
 
       def extract_params_from(hash)
-        @params = hash.stringify_keys.slice(*(self.class.send :params))
+        @params = hash.stringify_keys.slice(*(self.class.params))
       end
     end
   end

data/lib/hexx/service/validations.rb

@@ -7,6 +7,10 @@ module Hexx
     module Validations
 
       # Includes the <tt>ActiveModel::Validations</tt> module to the service.
+      #
+      # Params
+      # +klass+:: a class that includes the module.
+      #
       def self.included(klass)
         klass.include ActiveModel::Validations
       end

data/lib/hexx/service.rb

@@ -1,3 +1,4 @@
+# Service modules the +Service+ class depends on.
 def service_modules
   Dir[File.expand_path("../service/*.rb", __FILE__)]
 end
@@ -8,7 +9,7 @@ module Hexx
 
   # Base class for service objects.
   class Service
-    include Messages, Parameters, Transactions, Validations
+    include Messages, Parameters, Transactions, Validations, Callbacks
 
     # Runs the service object.
     #

data/lib/hexx/version.rb

@@ -2,5 +2,5 @@
 module Hexx
 
   # Current release.
-  VERSION = "2.0.2"
+  VERSION = "2.1.0"
 end

data/lib/hexx.rb

@@ -1,6 +1,7 @@
 require "active_model"
 require "wisper"
 
+# Application files to be loaded.
 def files
   @files ||= Dir[File.expand_path("../hexx/**/*.rb", __FILE__)]
 end

data/spec/hexx/service/message_spec.rb

@@ -21,7 +21,7 @@ module Hexx
 
         subject       { Message }
         let(:service) { Service.new }
-        before        { service.send(:errors).add :base, :text }
+        before        { service.public_send(:errors).add :base, :text }
 
         it "extracts error messages from a record" do
           message = subject.from(service).first

data/spec/hexx/service_spec.rb

@@ -3,56 +3,81 @@ require "spec_helper"
 module Hexx
   describe Service do
 
-    describe "class methods" do
+    around :each do |example|
+      class Test < Service
+        private
+        attr_reader :on_something, :something
+      end
+      example.run
+      Hexx.send :remove_const, :Test
+    end
+
+    it "includes ActiveModel::Validations" do
+      expect(Service.ancestors).to be_include ActiveModel::Validations
+    end
 
-      around :each do |example|
-        class TestService < Service; end
-        example.run
-        Hexx.send :remove_const, :TestService
+    it "includes Whisper::Publisher" do
+      expect(Service.ancestors).to be_include Wisper::Publisher
+    end
+
+    describe ".params" do
+
+      it "returns an array" do
+        expect(Test.params).to be_kind_of Array
       end
+    end
+
+    describe ".new" do
 
-      subject { TestService }
+      let(:value) { "text" }
+      before      { Test.send :allow_params, :name }
+      subject     { Test.new(name: value, wrong: "wrong").with_callbacks }
 
-      it "includes ActiveModel::Validations" do
-        expect(subject.ancestors).to be_include ActiveModel::Validations
+      it "stringifies params' keys" do
+        expect(subject.params["name"]).to eq value
+        expect(subject.params[:name]).to be_nil
       end
 
-      it "includes Whisper::Publisher" do
-        expect(subject.ancestors).to be_include Wisper::Publisher
+      it "whitelists params" do
+        expect(subject.params["wrong"]).to be_nil
       end
 
-      describe ".allow_params" do
+      it "initializes attributes from params" do
+        expect(subject.name).to eq value
+      end
+    end
+
+    describe "#with_callbacks" do
+
+      context "without a prefix" do
 
-        let(:attribute) { :name }
-        before          { subject.send :allow_params, attribute }
+        subject { Test.new.with_callbacks }
 
-        it "defines attributes" do
-          expect(subject.instance_methods).to be_include attribute
+        it "makes all private methods public" do
+          expect(subject.respond_to? :something).to be_truthy
+          expect(subject.respond_to? :on_something).to be_truthy
+          expect { subject.something }.not_to raise_error
+          expect { subject.on_something }.not_to raise_error
         end
       end
 
-      describe ".new" do
+      context "with a prefix" do
 
-        let(:value)    { "text" }
-        before         { subject.send :allow_params, :name }
-        let!(:service) { subject.new name: value, wrong: "wrong" }
+        subject { Test.new.with_callbacks prefix: :on }
 
-        it "stringifies params' keys" do
-          expect(service.send(:params)["name"]).to eq value
-          expect(service.send(:params)[:name]).to be_nil
+        it "makes prefixed private methods public" do
+          expect(subject.respond_to? :on_something).to be_truthy
+          expect { subject.on_something }.not_to raise_error
         end
 
-        it "whitelistes params" do
-          expect(service.send(:params)["wrong"]).to be_nil
-        end
-
-        it "initializes attributes from params" do
-          expect(service.send :name).to eq value
+        it "doesn't make other private methods public" do
+          expect(subject.respond_to? :something).to be_falsey
+          expect { subject.something }.to raise_error
         end
       end
     end
 
-    describe "##validate!" do
+    describe "#validate!" do
 
       it "passes when object is valid" do
         expect { subject.validate! }.not_to raise_error
@@ -65,118 +90,136 @@ module Hexx
       end
     end
 
-    describe "##params" do
+    describe "#run" do
 
-      it "is defined" do
-        expect { subject.send :params }.not_to raise_error
+      it "fails with NotImplementedError" do
+        expect { subject.run }.to raise_error { NotImplementedError }
       end
     end
 
-    describe "##t" do
+    describe "private" do
 
-      let(:scope)      { %w(activemodel messages models hexx/service) }
-      let(:traslation) { I18n.t(:text, scope: scope, name: "name") }
+      subject { Service.new.with_callbacks }
 
-      it "translates symbols in the service scope" do
-        expect(subject.send :t, :text, name: "name").to eq traslation
-      end
+      describe ".allow_params" do
 
-      it "doesn't translate the string" do
-        expect(subject.send :t, "text").to eq "text"
+        before { Test.send :allow_params, :name }
+
+        it "sets class params" do
+          expect(Test.params).to eq %w(name)
+        end
+
+        it "defines instance attributes" do
+          expect(Test.instance_methods).to be_include :name
+        end
       end
-    end
 
-    describe "##messages" do
+      describe "#params" do
 
-      it "returns an array" do
-        expect(subject.send :messages).to be_kind_of Array
+        it "exists" do
+          expect { subject.params }.not_to raise_error
+        end
       end
-    end
 
-    describe "##add_message" do
+      describe "#t" do
 
-      before        { subject.send :add_message, :info, :text }
-      let(:message) { subject.send(:messages).first }
+        let(:scope)      { %w(activemodel messages models hexx/service) }
+        let(:traslation) { I18n.t(:text, scope: scope, name: "name") }
 
-      it "adds a new message" do
-        expect(message).to be_kind_of Service::Message
-        expect(message.type).to eq "info"
-      end
+        it "translates symbols in the service scope" do
+          expect(subject.t(:text, name: "name")).to eq traslation
+        end
 
-      it "translates a symbol" do
-        translation = subject.send :t, :text
-        expect(message.text).to eq translation
+        it "doesn't translate the string" do
+          expect(subject.t("text")).to eq "text"
+        end
       end
-    end
-
-    describe "##transaction" do
 
-      let(:listener) { double "listener" }
-      before { subject.subscribe listener }
+      describe "#messages" do
 
-      it "yields a block" do
-        value  = "Hello!"
-        result = subject.send(:transaction) { value }
-        expect(result).to eq value
+        it "returns an array" do
+          expect(subject.messages).to be_kind_of Array
+        end
       end
 
-      context "when a service invalid" do
+      describe "#add_message" do
 
-        before { allow(subject).to receive(:validate!) { fail } }
+        before        { subject.add_message :info, :text }
+        let(:message) { subject.messages.first }
 
-        it "doesn't yield a block" do
-          value  = "Hello!"
-          result = subject.send(:transaction) { value }
-          expect(result).not_to eq value
+        it "adds a new message" do
+          expect(message).to be_kind_of Service::Message
+          expect(message.type).to eq "info"
         end
 
-        it "publishes an :error" do
-          expect(listener).to receive(:error)
-          subject.send(:transaction)
+        it "translates a symbol" do
+          translation = subject.t :text
+          expect(message.text).to eq translation
         end
       end
 
-      context "when a block raises Service::Invalid error" do
+      describe "#transaction" do
 
-        before { subject.send(:errors).add :base, :text }
-        let(:run) do
-          subject.send(:transaction) { fail Service::Invalid.new(subject) }
-        end
+        let(:listener) { double "listener" }
+        before { subject.subscribe listener }
 
-        it "rescues" do
-          expect { run }.not_to raise_error
+        it "yields a block" do
+          value  = "Hello!"
+          result = subject.transaction { value }
+          expect(result).to eq value
         end
 
-        it "publishes an :error with service messages" do
-          expect(listener).to receive(:error) do |messages|
-            expect(messages).to eq Service::Message.from(subject)
+        context "when a service invalid" do
+
+          before do
+            allow_any_instance_of(Service).to receive(:validate!) { fail }
+          end
+
+          it "doesn't yield a block" do
+            value  = "Hello!"
+            result = subject.transaction { value }
+            expect(result).not_to eq value
+          end
+
+          it "publishes an :error" do
+            expect(listener).to receive(:error)
+            subject.transaction
           end
-          run
         end
-      end
 
-      context "when a block raises StandardError" do
+        context "when a block raises Service::Invalid error" do
 
-        let(:run) { subject.send(:transaction) { fail "text" } }
+          before { subject.errors.add :base, :text }
+          let(:run) do
+            subject.transaction { fail Service::Invalid.new(subject) }
+          end
 
-        it "rescues" do
-          expect { run }.not_to raise_error
-        end
+          it "rescues" do
+            expect { run }.not_to raise_error
+          end
 
-        it "publishes an :error with a message" do
-          expect(listener).to receive(:error) do |messages|
-            expect(messages)
-              .to eq [Service::Message.new(type: "error", text: "text")]
+          it "publishes an :error with service messages" do
+            expect(listener).to receive(:error)
+            run
           end
-          run
         end
-      end
-    end
 
-    describe "#run" do
+        context "when a block raises StandardError" do
 
-      it "fails with NotImplementedError" do
-        expect { subject.run }.to raise_error { NotImplementedError }
+          let(:run) { subject.transaction { fail "text" } }
+
+          it "rescues" do
+            expect { run }.not_to raise_error
+          end
+
+          it "publishes an :error with a message" do
+            expect(listener).to receive(:error) do |messages|
+              expect(messages)
+                .to eq [Service::Message.new(type: "error", text: "text")]
+            end
+            run
+          end
+        end
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hexx
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors:
 - Andrew Kozin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-04 00:00:00.000000000 Z
+date: 2014-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -138,6 +138,7 @@ files:
 - lib/hexx/models.rb
 - lib/hexx/models/base_coercer.rb
 - lib/hexx/service.rb
+- lib/hexx/service/callbacks.rb
 - lib/hexx/service/invalid.rb
 - lib/hexx/service/message.rb
 - lib/hexx/service/messages.rb