service_actor 3.0.0 → 3.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ce3e96190aef06e630c4e930ad942876f27b8f0dc6a00b33c0ff2104d9be9be
-  data.tar.gz: 7badaaa07f340dfd66924417d214f070fc50346ec3d9805c4d115757b2845e22
+  metadata.gz: 40bbf17640409642508a6cb2dc7bd7197a49266ae9639c4a97c5cf52a3696ddd
+  data.tar.gz: 6b2627086780fcbead6e4ce3feff3565eab1bc5e3181a743296e8a7099e22480
 SHA512:
-  metadata.gz: f186543f09b78804ea899b57bc8c78e174de83fa205d0a36d74b3089a17b1e6e71f2ddc6c285ae673b5e796b69ab76f327879b57ff6d97a95c4473aa62d1f763
-  data.tar.gz: 7ecedf103e0b66a462a3cfb9f97a7bdb9ec1ea349b3fe7e2824ac716d9a68f68d29f7dd3828099d7ab6569ae90eac573112317c97a3619a7f1072856727fd1c3
+  metadata.gz: 0af13a24439bbab76ce2ae6ddf57e41b86b34c4f81e7d333650675195ab27d2519385e479bc1c41eee3c61f54253812c7e6579fea47bd7d8d17839d76a9808af
+  data.tar.gz: d25a43b1637a9dd1d79c6c0686ccc9bc2bb69dfbf0667c5a8775b1ac3fffab4c3d2233a955a17d676a0ee17b1af1a583449ac39dea220bbc02df3f82e9df6275

data/README.md

@@ -18,12 +18,11 @@ and controllers thin.
   - [Conditions](#conditions)
   - [Allow nil](#allow-nil)
   - [Types](#types)
-  - [Result](#result)
+  - [Fail](#fail)
 - [Play actors in a sequence](#play-actors-in-a-sequence)
   - [Rollback](#rollback)
   - [Lambdas](#lambdas)
   - [Play conditions](#play-conditions)
-- [Use with Rails](#use-with-rails)
 - [Testing](#testing)
 - [Build your own actor](#build-your-own-actor)
 - [Influences](#influences)
@@ -34,13 +33,21 @@ and controllers thin.
 
 ## Installation
 
-Add these lines to your application's Gemfile:
+Add these lines to your application’s Gemfile:
 
 ```rb
 # Composable service objects
 gem 'service_actor'
 ```
 
+When using Rails, you can include the
+[service_actor-rails](https://github.com/sunny/actor-rails) gem:
+
+```ruby
+# Composable service objects
+gem "service_actor-rails"
+```
+
 ## Usage
 
 Actors are single-purpose actions in your application that represent your
@@ -96,7 +103,7 @@ class BuildGreeting < Actor
   output :greeting
 
   def call
-    self.greeting = 'Have a wonderful day!'
+    self.greeting = "Have a wonderful day!"
   end
 end
 ```
@@ -115,8 +122,8 @@ Inputs can be marked as optional by providing a default:
 ```rb
 class BuildGreeting < Actor
   input :name
-  input :adjective, default: 'wonderful'
-  input :length_of_time, default: -> { ['day', 'week', 'month'].sample }
+  input :adjective, default: "wonderful"
+  input :length_of_time, default: -> { ["day", "week", "month"].sample }
 
   output :greeting
 
@@ -129,7 +136,7 @@ end
 This lets you call the actor without specifying those keys:
 
 ```rb
-result = BuildGreeting.call(name: 'Jim')
+result = BuildGreeting.call(name: "Jim")
 result.greeting # => "Have a wonderful week Jim!"
 ```
 
@@ -142,8 +149,7 @@ result = BuildGreeting.call
 
 ### Conditions
 
-You can ensure an input is included in a collection by using `in` (unreleased
-yet):
+You can ensure an input is included in a collection by using `in`:
 
 ```rb
 class Pay < Actor
@@ -185,12 +191,12 @@ end
 
 ### Types
 
-Sometimes it can help to have a quick way of making sure we didn't mess up our
+Sometimes it can help to have a quick way of making sure we didn’t mess up our
 inputs.
 
 For that you can use the `type` option and giving a class or an array
-of possible classes. If the input or output doesn't match is not an instance of
-these types, an error is raised.
+of possible classes. If the input or output doesn’t match these types, an
+error is raised.
 
 ```rb
 class UpdateUser < Actor
@@ -205,10 +211,9 @@ You may also use strings instead of constants, such as `type: 'User'`.
 
 When using a type condition, `allow_nil` defaults to `false`.
 
-### Result
+### Fail
 
-All actors return a successful result by default. To stop the execution and
-mark an actor as having failed, use `fail!`:
+To stop the execution and mark an actor as having failed, use `fail!`:
 
 ```rb
 class UpdateUser
@@ -218,7 +223,7 @@ class UpdateUser
   def call
     user.attributes = attributes
 
-    fail!(error: 'Invalid user') unless user.valid?
+    fail!(error: "Invalid user") unless user.valid?
 
     # …
   end
@@ -228,7 +233,8 @@ end
 This will raise an error in your app with the given data added to the result.
 
 To test for the success of your actor instead of raising an exception, use
-`.result` instead of `.call` and call `success?` or `failure?` on the result.
+`.result` instead of `.call`. You can then call `success?` or `failure?` on
+the result.
 
 For example in a Rails controller:
 
@@ -246,7 +252,7 @@ class UsersController < ApplicationController
 end
 ```
 
-Any keys you add to `fail!` will be added to the result, for example you could
+The keys you add to `fail!` will be added to the result, for example you could
 do: `fail!(error_type: "validation", error_code: "uv52", …)`.
 
 ## Play actors in a sequence
@@ -295,8 +301,8 @@ anything to clean up if they call `fail!`.
 
 ### Lambdas
 
-You can use inline actions using lambdas. Inside these lambdas, you don't have
-getters and setters but have access to the shared result:
+You can use inline actions using lambdas. Inside these lambdas you have access to
+the shared result:
 
 ```rb
 class Pay < Actor
@@ -308,15 +314,15 @@ end
 ```
 
 Like in this example, lambdas can be useful for small work or preparing the
-result for the next actors. If you want to do more work before, or after the
-whole `play`, you can also override the `call` method. For example:
+result for the next actors. If you want to do more work before, after or around
+the whole `play`, you can also override the `call` method. For example:
 
 ```rb
 class Pay < Actor
   # …
 
   def call
-    Time.with_timezone('Paris') do
+    Time.with_timezone("Paris") do
       super
     end
   end
@@ -337,10 +343,21 @@ end
 
 You can use this to trigger an early success.
 
-## Use with Rails
+### Fail on argument error
 
-The [service_actor-rails](https://github.com/sunny/actor-rails/) gem includes a
-Rails generator to create an actor and its spec.
+By default, errors on inputs will raise an error, even when using `.result`
+instead of `.call`. If instead you want to mark the actor as failed, you can
+catch the exception to treat it as an actor failure:
+
+```rb
+class PlaceOrder < Actor
+  fail_on ServiceActor::ArgumentError
+
+  input :currency, in: ["EUR", "USD"]
+
+  # …
+end
+```
 
 ## Testing
 
@@ -352,11 +369,11 @@ make it easier for you to test your application.
 
 ## Build your own actor
 
-If you application already uses an "Actor" class, you can build your own by
-changing the gem's require statement:
+If you application already uses a class called “Actor”, you can build your own
+by changing the gem’s require statement:
 
 ```rb
-gem 'service_actor', require: 'service_actor/base'
+gem "service_actor", require: "service_actor/base"
 ```
 
 And building your own class to inherit from:
@@ -371,7 +388,7 @@ end
 
 This gem is heavily influenced by
 [Interactor](https://github.com/collectiveidea/interactor) ♥.
-However there are a few key differences which make `actor` unique:
+Some key differences make Actor unique:
 
 - Does not [hide errors when an actor fails inside another
   actor](https://github.com/collectiveidea/interactor/issues/170).
@@ -381,7 +398,7 @@ However there are a few key differences which make `actor` unique:
   and failures are not hidden away because you forgot to use `!`.
 - Allows defaults, type checking, requirements and conditions on inputs.
 - Delegates methods on the context: `foo` vs `context.foo`, `self.foo =` vs
-  `context.foo = `, fail!` vs `context.fail!`.
+  `context.foo = `, `fail!` vs `context.fail!`.
 - Shorter setup syntax: inherit from `< Actor` vs having to `include Interactor`
   and `include Interactor::Organizer`.
 - Organizers allow lambdas, being called multiple times, and having conditions.
@@ -402,14 +419,16 @@ Photo by [Lloyd Dirks](https://unsplash.com/photos/4SLz_RCk6kQ).
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake` to run the tests and linting. You can also run `bin/console` for an
+`bin/rake` to run the tests and linting. You can also run `bin/console` for an
 interactive prompt.
 
 To release a new version, update the version number in `version.rb`, and in the
 `CHANGELOG.md`. Update the `README.md` if there are missing segments, make sure
-tests and linting are pristine by calling `rake`, then create a commit for this
-version. You can then run `rake release`, which will create a git tag, push
-using git, and push the gem to [rubygems.org](https://rubygems.org).
+tests and linting are pristine by calling `bundle && bin/rake`, then create a
+commit for this version.
+
+You can then run `rake release`, which will assign a git tag, push using git,
+and push the gem to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/lib/service_actor/attributable.rb

@@ -27,6 +27,9 @@ module ServiceActor
           result[name]
         end
 
+        # For avoid method redefined warning messages.
+        alias_method name, name if method_defined?(name)
+
         protected name
       end
 

data/lib/service_actor/base.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'service_actor/core'
-
 # Exceptions
 require 'service_actor/error'
 require 'service_actor/failure'
@@ -19,6 +17,7 @@ require 'service_actor/nil_checkable'
 require 'service_actor/conditionable'
 require 'service_actor/defaultable'
 require 'service_actor/collectionable'
+require 'service_actor/failable'
 
 module ServiceActor
   module Base
@@ -32,8 +31,9 @@ module ServiceActor
       base.include(TypeCheckable)
       base.include(NilCheckable)
       base.include(Conditionable)
-      base.include(Defaultable)
       base.include(Collectionable)
+      base.include(Defaultable)
+      base.include(Failable)
     end
   end
 end

data/lib/service_actor/collectionable.rb

@@ -22,7 +22,8 @@ module ServiceActor
           next if options[:in].include?(result[key])
 
           raise ArgumentError,
-                "Input #{key} must be included in #{options[:in].inspect}"
+                "Input #{key} must be included in #{options[:in].inspect} " \
+                "but instead was #{result[key].inspect}"
         end
 
         super

data/lib/service_actor/conditionable.rb

@@ -29,7 +29,7 @@ module ServiceActor
             next if check.call(value)
 
             raise ArgumentError,
-                  "Input #{key} must #{name} but was #{value.inspect}."
+                  "Input #{key} must #{name} but was #{value.inspect}"
           end
         end
 

data/lib/service_actor/core.rb

@@ -38,12 +38,15 @@ module ServiceActor
     # To implement in your actors.
     def rollback; end
 
+    # This method is used internally to override behavior on call. Overriding
+    # `call` instead would mean that end-users have to call `super` in their
+    # actors.
     # :nodoc:
     def _call
       call
     end
 
-    private
+    protected
 
     # Returns the current context from inside an actor.
     attr_reader :result

data/lib/service_actor/defaultable.rb

@@ -27,7 +27,7 @@ module ServiceActor
             next
           end
 
-          raise(ArgumentError, "Input #{name} on #{self.class} is missing.")
+          raise(ArgumentError, "Input #{name} on #{self.class} is missing")
         end
 
         super

data/lib/service_actor/error.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module ServiceActor
-  # Standard exception from which other inherit.
+  # Standard exception from which others inherit.
   class Error < StandardError; end
 end

data/lib/service_actor/failable.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ServiceActor
+  # Adds the `fail_on` DSL to actors. This allows you to call `.result` and get
+  # back a failed actor instead of raising an exception.
+  #
+  #   class ApplicationActor < Actor
+  #     fail_on ServiceActor::ArgumentError
+  #   end
+  module Failable
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.prepend(PrependedMethods)
+    end
+
+    module ClassMethods
+      def inherited(child)
+        super
+
+        child.fail_ons.push(*fail_ons)
+      end
+
+      def fail_on(*exceptions)
+        fail_ons.push(*exceptions)
+      end
+
+      def fail_ons
+        @fail_ons ||= []
+      end
+    end
+
+    module PrependedMethods
+      def _call
+        super
+      rescue *self.class.fail_ons => e
+        fail!(error: e.message)
+      end
+    end
+  end
+end

data/lib/service_actor/nil_checkable.rb

@@ -31,20 +31,15 @@ module ServiceActor
 
           raise ArgumentError,
                 "The #{origin} \"#{name}\" on #{self.class} does not allow " \
-                'nil values.'
+                'nil values'
         end
       end
 
       def allow_nil?(options)
-        if options.key?(:allow_nil)
-          options[:allow_nil]
-        elsif options.key?(:default) && options[:default].nil?
-          true
-        elsif options[:type]
-          false
-        else
-          true
-        end
+        return options[:allow_nil] if options.key?(:allow_nil)
+        return true if options.key?(:default) && options[:default].nil?
+
+        !options[:type]
       end
     end
   end

data/lib/service_actor/playable.rb

@@ -48,7 +48,7 @@ module ServiceActor
       end
 
       def rollback
-        return unless @played
+        return unless defined?(@played)
 
         @played.each do |actor|
           next unless actor.respond_to?(:rollback)
@@ -60,16 +60,27 @@ module ServiceActor
       private
 
       def play_actor(actor)
-        if actor.is_a?(Class) && actor.ancestors.include?(Actor)
-          actor = actor.new(result)
-          actor._call
-        else
-          new_result = actor.call(result)
-          result.merge!(new_result.to_h) if new_result.respond_to?(:to_h)
-        end
+        play_service_actor(actor) ||
+          play_interactor(actor) ||
+          actor.call(result)
+      end
+
+      def play_service_actor(actor)
+        return unless actor.is_a?(Class)
+        return unless actor.ancestors.include?(ServiceActor::Core)
+
+        actor = actor.new(result)
+        actor._call
 
         (@played ||= []).unshift(actor)
       end
+
+      def play_interactor(actor)
+        return unless actor.is_a?(Class)
+        return unless actor.ancestors.map(&:name).include?('Interactor')
+
+        result.merge!(actor.call(result).to_h)
+      end
     end
   end
 end

data/lib/service_actor/result.rb

@@ -28,7 +28,7 @@ module ServiceActor
     end
 
     def failure?
-      super || false
+      self[:failure?] || false
     end
 
     def merge!(result)
@@ -47,7 +47,7 @@ module ServiceActor
       to_h[name]
     end
 
-    # Redefined here to override the method on `Object`.
+    # Defined here to override the method on `Object`.
     def display
       to_h.fetch(:display)
     end

data/lib/service_actor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ServiceActor
-  VERSION = '3.0.0'
+  VERSION = '3.1.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: service_actor
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.3
 platform: ruby
 authors:
 - Sunny Ripert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-20 00:00:00.000000000 Z
+date: 2022-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: code-scanning-rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -128,6 +142,7 @@ files:
 - lib/service_actor/core.rb
 - lib/service_actor/defaultable.rb
 - lib/service_actor/error.rb
+- lib/service_actor/failable.rb
 - lib/service_actor/failure.rb
 - lib/service_actor/nil_checkable.rb
 - lib/service_actor/playable.rb
@@ -141,6 +156,7 @@ metadata:
   homepage_uri: https://github.com/sunny/actor
   source_code_uri: https://github.com/sunny/actor
   changelog_uri: https://github.com/sunny/actor/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -149,17 +165,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.7
-  - - "<"
-    - !ruby/object:Gem::Version
-      version: 2.8.0
+      version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Service objects for your application logic