service_actor 2.0.0 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e103cfa965d8a142d4d47ad910bd4411f90392ab4057b8536a265e12febbf42b
-  data.tar.gz: cf297af32084c0a7ff7d3f85ecab5f52137516d5fc2d2c0aa1f5a1fb1aceccfd
+  metadata.gz: 182079e8ce5159c685b472dcecec697cd640e2006266f9f8e71b1fe829e24743
+  data.tar.gz: 28522d5045e623f0fb55ac77519720e3d76168f070c108a1785c46b322a04a9f
 SHA512:
-  metadata.gz: 76cc57cc0c3eca0c951f3bf046e7132bd28157081ff7a815fa44b9ef6375180f035aecee14bf735d0a655e72fa48f840610694c505f90e81cb72e84bc67ea7b7
-  data.tar.gz: 77c0cae0fe870e7a771023a45fbe919eeda92b8ed6e6d32187b4a85ddf906fbae27b1b615830d659214754914a7c0038ecdbba4a7b88b81234e2b96cdc08486c
+  metadata.gz: 6c4ae5e139ac02cc1244c24c8b245161cebe2246112bdfe25646c38d09f5b83d34d68f902ded72477149c1f6a928a617d1bbfbf5dd7479ee35d0d6f87c0b08a8
+  data.tar.gz: 2f0d5c297e68ba61db4467d6ef83e14ec92e12b839a5bea78d0fdd072ae08f7077676fd88cd8ad22f7e1e5790e987be69695c8bb0c465eea58d0e3a59cac7c04

data/README.md

@@ -6,6 +6,8 @@ This Ruby gem lets you move your application logic into into small composable
 service objects. It is a lightweight framework that helps you keep your models
 and controllers thin.
 
+![Photo of theater seats](https://user-images.githubusercontent.com/132/78340166-e7567000-7595-11ea-97c0-b3e5da2de7a1.png)
+
 ## Contents
 
 - [Installation](#installation)
@@ -21,22 +23,31 @@ and controllers thin.
   - [Rollback](#rollback)
   - [Lambdas](#lambdas)
   - [Play conditions](#play-conditions)
-- [Build your own actor](#build-your-own-actor)
 - [Testing](#testing)
+- [Build your own actor](#build-your-own-actor)
 - [Influences](#influences)
+- [Thanks](#thanks)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#contributing)
 
 ## 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
@@ -59,7 +70,8 @@ SendNotification.call # => <ServiceActor::Result…>
 ```
 
 When called, actors return a Result. Reading and writing to this result allows
-actors to accept and return multiple arguments. Let's find out how to do that.
+actors to accept and return multiple arguments. Let's find out how to do that
+and then we'll see how to chain multiple actors togethor.
 
 ### Inputs
 
@@ -137,8 +149,21 @@ result = BuildGreeting.call
 
 ### Conditions
 
-You can add simple conditions that the inputs must verify, with the name of your
-choice under `must`:
+You can ensure an input is included in a collection by using `in` (unreleased
+yet):
+
+```rb
+class Pay < Actor
+  input :currency, in: %w[EUR USD]
+
+  # …
+end
+```
+
+This raises an argument error if the input does not match one of the given
+values.
+
+You can also add custom conditions with the name of your choice by using `must`:
 
 ```rb
 class UpdateAdminUser < Actor
@@ -151,7 +176,7 @@ class UpdateAdminUser < Actor
 end
 ```
 
-In case the input does not match, it will raise an argument error.
+This raises an argument error if the given lambda returns a falsey value.
 
 ### Allow nil
 
@@ -210,8 +235,7 @@ 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`. This lets you use `success?` and `failure?` on the
-result.
+`.result` instead of `.call` and call `success?` or `failure?` on the result.
 
 For example in a Rails controller:
 
@@ -246,9 +270,9 @@ class PlaceOrder < Actor
 end
 ```
 
-This creates a `call` method where each actor will be called, taking their
-arguments from the previous actor's result. In fact, every actor along shares
-the same result instance to help shape the final result your application needs.
+This creates a `call` method that will call every actor along the way. Inputs
+and outputs will go from one actor to the next, all sharing the same result set
+until it is finally returned.
 
 ### Rollback
 
@@ -320,6 +344,28 @@ end
 
 You can use this to trigger an early success.
 
+### Fail on argument error
+
+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
+
+  # …
+end
+```
+
+## Testing
+
+In your application, add automated testing to your actors as you would do to any
+other part of your applications.
+
+You will find that cutting your business logic into single purpose actors will
+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
@@ -337,19 +383,11 @@ class ApplicationActor
 end
 ```
 
-## Testing
-
-In your application, add automated testing to your actors as you would do to any
-other part of your applications.
-
-You will find that cutting your business logic into single purpose actors makes
-your application much simpler to test.
-
 ## Influences
 
 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).
@@ -359,7 +397,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.
@@ -367,19 +405,29 @@ However there are a few key differences which make `actor` unique:
 - No `before`, `after` and `around` hooks, prefer using `play` with lambdas or
   overriding `call`.
 
+Actor supports mixing actors & interactors when using `play` for a smooth
+migration.
+
+## Thanks
+
 Thank you to @nicoolas25, @AnneSottise & @williampollet for the early thoughts
 and feedback on this gem.
 
+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`, run `rake`, and create a commit for this version. You can then
-run `rake release`, which will create a git tag for the version, push git
-commits and tags, and push the gem to [rubygems.org](https://rubygems.org).
+`CHANGELOG.md`. Update the `README.md` if there are missing segments, make sure
+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
 
@@ -389,7 +437,7 @@ Bug reports and pull requests are welcome
 This project is intended to be a safe, welcoming space for collaboration, and
 everyone interacting in the project’s codebase and issue tracker is expected to
 adhere to the [Contributor Covenant code of
-conduct](https://github.com/sunny/actor/blob/master/CODE_OF_CONDUCT.md).
+conduct](https://github.com/sunny/actor/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

data/lib/service_actor/base.rb

@@ -1,36 +1,39 @@
 # frozen_string_literal: true
 
-require 'service_actor/core'
-
 # Exceptions
 require 'service_actor/error'
 require 'service_actor/failure'
-require 'service_actor/success'
 require 'service_actor/argument_error'
 
 # Core
-require 'service_actor/result'
+require 'service_actor/core'
 require 'service_actor/attributable'
 require 'service_actor/playable'
-require 'service_actor/core'
+require 'service_actor/result'
 
 # Concerns
 require 'service_actor/type_checkable'
 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
     def self.included(base)
       # Core
       base.include(Core)
+      base.include(Attributable)
+      base.include(Playable)
 
       # Concerns
       base.include(TypeCheckable)
       base.include(NilCheckable)
       base.include(Conditionable)
+      base.include(Collectionable)
       base.include(Defaultable)
+      base.include(Failable)
     end
   end
 end

data/lib/service_actor/collectionable.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ServiceActor
+  # Add checks to your inputs, by specifying what values are authorized
+  # under the "in" key.
+  #
+  # Example:
+  #
+  #   class Pay < Actor
+  #     input :provider, in: ['MANGOPAY', 'PayPal', 'Stripe']
+  #   end
+  module Collectionable
+    def self.included(base)
+      base.prepend(PrependedMethods)
+    end
+
+    module PrependedMethods
+      def _call
+        self.class.inputs.each do |key, options|
+          next unless options[:in]
+
+          next if options[:in].include?(result[key])
+
+          raise ArgumentError,
+                "Input #{key} must be included in #{options[:in].inspect} " \
+                "but instead was #{result[key].inspect}"
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/service_actor/conditionable.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 module ServiceActor
-  # Add checks to your inputs, by calling lambdas with the name of you choice.
-  # Will raise an error if any check does return a truthy value.
+  # Add checks to your inputs, by calling lambdas with the name of you choice
+  # under the "must" key.
+  #
+  # Will raise an error if any check returns a truthy value.
   #
   # Example:
   #
@@ -27,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

@@ -1,13 +1,9 @@
 # frozen_string_literal: true
 
 module ServiceActor
-  # Actors should start with a verb, inherit from Actor and implement a `call`
-  # method.
   module Core
     def self.included(base)
       base.extend(ClassMethods)
-      base.include(Attributable)
-      base.include(Playable)
     end
 
     module ClassMethods
@@ -18,15 +14,6 @@ module ServiceActor
         result = Result.to_result(options).merge!(arguments)
         new(result)._call
         result
-      # DEPRECATED
-      rescue Success
-        result
-      end
-
-      # :nodoc:
-      def call!(**arguments)
-        warn "DEPRECATED: Prefer `#{name}.call` to `#{name}.call!`."
-        call(**arguments)
       end
 
       # Call an actor with arguments. Returns the result and does not raise on
@@ -61,20 +48,9 @@ module ServiceActor
     # Returns the current context from inside an actor.
     attr_reader :result
 
-    def context
-      warn "DEPRECATED: Prefer `result.` to `context.` in #{self.class.name}."
-
-      result
-    end
-
     # Can be called from inside an actor to stop execution and mark as failed.
     def fail!(**arguments)
       result.fail!(**arguments)
     end
-
-    # DEPRECATED
-    def succeed!(**arguments)
-      result.succeed!(**arguments)
-    end
   end
 end

data/lib/service_actor/defaultable.rb

@@ -20,13 +20,14 @@ module ServiceActor
         self.class.inputs.each do |name, input|
           next if result.key?(name)
 
-          unless input.key?(:default)
-            raise ArgumentError, "Input #{name} on #{self.class} is missing."
+          if input.key?(:default)
+            default = input[:default]
+            default = default.call if default.respond_to?(:call)
+            result[name] = default
+            next
           end
 
-          default = input[:default]
-          default = default.call if default.respond_to?(:call)
-          result[name] = default
+          raise(ArgumentError, "Input #{name} on #{self.class} is missing")
         end
 
         super

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

@@ -27,30 +27,17 @@ module ServiceActor
 
       def check_context_for_nil(definitions, origin:)
         definitions.each do |name, options|
-          warn_of_deprecated_required_option(options, name, origin)
-
           next if !result[name].nil? || allow_nil?(options)
 
           raise ArgumentError,
                 "The #{origin} \"#{name}\" on #{self.class} does not allow " \
-                'nil values.'
+                'nil values'
         end
       end
 
-      def warn_of_deprecated_required_option(options, name, origin)
-        return unless options.key?(:required)
-
-        warn 'DEPRECATED: The "required" option is deprecated. Replace ' \
-            "`#{origin} :#{name}, required: #{options[:required]}` by " \
-            "`#{origin} :#{name}, allow_nil: #{!options[:required]}` in " \
-            "#{self.class}."
-      end
-
       def allow_nil?(options)
         if options.key?(:allow_nil)
           options[:allow_nil]
-        elsif options.key?(:required)
-          !options[:required]
         elsif options.key?(:default) && options[:default].nil?
           true
         elsif options[:type]

data/lib/service_actor/playable.rb

@@ -64,7 +64,8 @@ module ServiceActor
           actor = actor.new(result)
           actor._call
         else
-          actor.call(result)
+          new_result = actor.call(result)
+          result.merge!(new_result.to_h) if new_result.respond_to?(:to_h)
         end
 
         (@played ||= []).unshift(actor)

data/lib/service_actor/result.rb

@@ -3,7 +3,8 @@
 require 'ostruct'
 
 module ServiceActor
-  # Represents the result of an actor.
+  # Represents the context of an actor, holding the data from both its inputs
+  # and outputs.
   class Result < OpenStruct
     def self.to_result(data)
       return data if data.is_a?(self)
@@ -22,22 +23,12 @@ module ServiceActor
       raise Failure, self
     end
 
-    def succeed!(result = {})
-      warn 'DEPRECATED: Early success with `succeed!` is deprecated in favor ' \
-           'of adding conditions to `play` calls.'
-
-      merge!(result)
-      merge!(failure?: false)
-
-      raise Success, self
-    end
-
     def success?
       !failure?
     end
 
     def failure?
-      super || false
+      self[:failure?] || false
     end
 
     def merge!(result)

data/lib/service_actor/type_checkable.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 module ServiceActor
-  # Adds `type:` checking to inputs and outputs. Accepts classes or class names
+  # Adds `type:` checking to inputs and outputs. Accepts class names or classes
   # that should match an ancestor. Also accepts arrays.
   #
   # Example:
   #
   #   class ReduceOrderAmount < Actor
-  #     input :order, type: Order
-  #     input :coupon, type: 'Coupon'
+  #     input :order, type: 'Order'
   #     input :amount, type: [Integer, Float]
   #     input :bonus_applied, type: [TrueClass FalseClass]
   #   end

data/lib/service_actor/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: service_actor
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.1.2
 platform: ruby
 authors:
 - Sunny Ripert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-24 00:00:00.000000000 Z
+date: 2021-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -80,6 +80,48 @@ 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
+    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: interactor
+  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'
 description: Service objects for your application logic
 email:
 - sunny@sunfox.org
@@ -95,15 +137,16 @@ files:
 - lib/service_actor/argument_error.rb
 - lib/service_actor/attributable.rb
 - lib/service_actor/base.rb
+- lib/service_actor/collectionable.rb
 - lib/service_actor/conditionable.rb
 - 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
 - lib/service_actor/result.rb
-- lib/service_actor/success.rb
 - lib/service_actor/type_checkable.rb
 - lib/service_actor/version.rb
 homepage: https://github.com/sunny/actor
@@ -112,7 +155,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/sunny/actor
   source_code_uri: https://github.com/sunny/actor
-  changelog_uri: https://github.com/sunny/actor/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/sunny/actor/blob/main/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -121,14 +164,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '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.4
 signing_key: 
 specification_version: 4
 summary: Service objects for your application logic

data/lib/service_actor/success.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module ServiceActor
-  # Raised when using `succeed!` to halt the progression of an organizer.
-  # DEPRECATED in favor of adding conditions to your play.
-  class Success < Error; end
-end