operate 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e4ae06d376016ee482b1fe2c0fb7d15304f96f77
-  data.tar.gz: '01248b745836660db7dedb802bf25de16d7c77a8'
+SHA256:
+  metadata.gz: 32ca1e5fe8ebab826d9bffa0fffa21bc6d6dcba61de304839b4b8d66fdff6e5b
+  data.tar.gz: a5ff2c95affdf3e82edff5d42a27c1c6a4683bbcb372d88c09069bbe5ded741e
 SHA512:
-  metadata.gz: 4b503d5be289f23dce63009daf120dedad7081ad42993d6934314d051f0dc2b9f0c8e68d21da81fe458fc2335e61384fa100b4cdfaa7e06309882de0970906fb
-  data.tar.gz: 8f3c185e0a3b2f92e0d1a8384d8f91363f5562ad6028a6337cbe979fe73d9fdcfdf381a7777d7be8c8f34a85e0ab23624163cf5b8b91c2e4cc03eb7aad00c342
+  metadata.gz: 79df511bc9ae931762d3dee5e8c7a7a256ffb4c2fc02999fc041c8dc32e917000f168378a364caba174894308764e8aa8295dd5974090ec88033b80e05749262
+  data.tar.gz: a2f0b35a8153cf465099d13148c34b6a9d8d16592d80555620f590dd42c48e162092e831c999a0b04c85ab4fe589ab0af542d9296109da7c3ac3e956e949feef

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Operate Changelog
 
+## [0.2.0] - February 23, 2019
+
+- `expose` a value within a handler block to the caller
+
 
 ## [0.1.1] - October 27, 2017
 

data/README.md

@@ -8,7 +8,7 @@ Use Operate to __remove business logic from your controller and model__, subsumi
 "service" object that represents your processes. Examples might be: a user addition, a post addition, 
 or adding a comment.  
 
-Service objects can out factor behavior that would bloat models or controllers, and is a useful step to patterns
+Service objects can factor out behavior that would bloat models or controllers, and is a useful step to patterns
 like Strategy and Command.
 
 Service objects are not a new concept, and extracting controller bloat to service objects is a common 
@@ -22,9 +22,7 @@ exposed via `Operate::Command`, however, is solid and no breaking changes there
 
 ## Dependencies
 
-Operate requires only `ActiveSupport` 4.2 or greater.
-
-Additionally, if ActiveRecord is available, transactions are supported. There is no explicit support for other ORMs.
+If ActiveRecord is available, transactions are supported. There is no explicit support for other ORMs.
 
 It's not required, but a form object library like [Reform] is recommended. Reform is used in the examples below.
 
@@ -57,9 +55,10 @@ Methods used in your service class:
 
 Methods used by clients (normally a controller) of your service class:
 * `#on(*events, &block)` that subscribe to an event or events, and provide a block to handle that event
+* `#expose(hash)` called within a block passed to `#on` will set the hash as instance variables on the caller (typically a controller)
 
 
-An example service:
+### A basic service
 
 ```ruby
 # put in app/services, app/commands, or something like that
@@ -114,11 +113,84 @@ end
 Note: this example does not use [Strong Parameters] as [Reform] provides an explicit form property layout.
 
 
+### Passing parameters
+
+You can pass parameters to the handling block by supplying the parameters as arguments to `broadcast`.
+
+```ruby
+# Your service
+class UserAddition
+  include Operate::Command
+  def call
+    # ...
+    broadcast(:ok, user)
+  end
+end
+
+
+# Your client (a controller):
+def create
+  UserAddition.call(@form) do
+    on(:ok) {|user| logger.info "#{user.name} created" }
+  end
+end
+```
+
+### Exposing values
+
+You can expose a value from within a handler block to the calling controller. Pass the values to expose as a hash.
+
+```ruby
+def new
+  UserBuild.call(@form) do
+    on(:ok) do |user|
+	  expose(user: user)
+	  render :new  # new.html.erb can access @user
+	end
+  end
+end
+```
+
+## Testing
+
+A straight-forward way to test the events broadcast by an `Operate::Command` implementor:
+
+```ruby
+class UserAddition
+  include Operate::Command
+  # ...
+  def call
+    return broadcast(:invalid) if form.invalid?
+    # ...
+    broadcast(:ok) 
+  end
+end
+```
+
+```ruby
+describe UserAddition do
+  it 'broadcasts ok when creating user' do
+    is_ok = false
+    UserAddition.call(attributes_for(:new_user)) do
+      on(:ok) { is_ok = true }
+    end
+    expect(is_ok).to eq true
+  end
+  it 'broadcasts invalid when user validation fails' do
+    is_invalid = false
+    UserAddition.call(attributes_for(:invalid_user)) do
+      on(:invalid) { is_invalid = true }
+    end
+    expect(is_invalid).to eq true
+  end
+end
+```
+
 ## Credit
 
 The core of Operate is based on [rectify] and [wisper], and would not exist without these fine projects.
 Both rectify and wisper are excellent gems, they just provide more functionality than I require, and with
-some philosophical differences in execution (rectify requires you extend their base class, operate provides mixins).
+some philosophical differences in execution (rectify requires you to extend their base class, while operate provides mixins).
 
 
 ## Contributing

data/lib/operate/command.rb

@@ -6,6 +6,7 @@ module Operate
   # `register` handlers with on().
   # `broadcast` results with broadcast().
   # `transaction` wraps ActiveRecord transactions.
+  # `expose` to set a value from the handler block to the caller
   #
   module Command
     include Operate::Pubsub::Publisher
@@ -17,12 +18,19 @@ module Operate
     end
 
     module ClassMethods
+      attr_reader :command_presenter
+      
       # Call will initialize the class with *args and invoke instance method `call` with no arguments
       def call(*args, &block)
         command = new(*args)
         command.evaluate(&block) if block_given?
         command.call
       end
+      
+      # def presenter presenter
+      #   @command_presenter = presenter
+      #   self
+      # end
     end
 
     def transaction(&block)
@@ -51,5 +59,23 @@ module Operate
     def respond_to_missing?(method_name, include_private = false)
       @caller.respond_to?(method_name, include_private)
     end
+    
+    #
+    # Expose a value within a handler block to the caller.
+    # Sets attribute directly if available, or as an instance variable.
+    #
+    # RegisterAccount.call(@form) do
+    #   on(:ok) { |user| expose(:user => user) }
+    # end
+    #
+    def expose(presentation_data)
+      presentation_data.each do |attribute, value|
+        if @caller.respond_to?("#{attribute}=")
+          @caller.public_send("#{attribute}=", value)
+        else
+          @caller.instance_variable_set("@#{attribute}", value)
+        end
+      end
+    end
   end
 end

data/lib/operate/version.rb

@@ -1,3 +1,3 @@
 module Operate
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/operate.gemspec

@@ -14,14 +14,6 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/tomichj/operate'
   spec.license       = 'MIT'
 
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
-  # if spec.respond_to?(:metadata)
-  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
-  # else
-  #   raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
-  # end
-
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: operate
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Justin Tomich
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-04 00:00:00.000000000 Z
+date: 2019-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -124,8 +124,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 3.0.2
 signing_key: 
 specification_version: 4
 summary: Create service objects with Operate.