service_actor 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e103cfa965d8a142d4d47ad910bd4411f90392ab4057b8536a265e12febbf42b
-  data.tar.gz: cf297af32084c0a7ff7d3f85ecab5f52137516d5fc2d2c0aa1f5a1fb1aceccfd
+  metadata.gz: 1ce3e96190aef06e630c4e930ad942876f27b8f0dc6a00b33c0ff2104d9be9be
+  data.tar.gz: 7badaaa07f340dfd66924417d214f070fc50346ec3d9805c4d115757b2845e22
 SHA512:
-  metadata.gz: 76cc57cc0c3eca0c951f3bf046e7132bd28157081ff7a815fa44b9ef6375180f035aecee14bf735d0a655e72fa48f840610694c505f90e81cb72e84bc67ea7b7
-  data.tar.gz: 77c0cae0fe870e7a771023a45fbe919eeda92b8ed6e6d32187b4a85ddf906fbae27b1b615830d659214754914a7c0038ecdbba4a7b88b81234e2b96cdc08486c
+  metadata.gz: f186543f09b78804ea899b57bc8c78e174de83fa205d0a36d74b3089a17b1e6e71f2ddc6c285ae673b5e796b69ab76f327879b57ff6d97a95c4473aa62d1f763
+  data.tar.gz: 7ecedf103e0b66a462a3cfb9f97a7bdb9ec1ea349b3fe7e2824ac716d9a68f68d29f7dd3828099d7ab6569ae90eac573112317c97a3619a7f1072856727fd1c3

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,9 +23,11 @@ and controllers thin.
   - [Rollback](#rollback)
   - [Lambdas](#lambdas)
   - [Play conditions](#play-conditions)
-- [Build your own actor](#build-your-own-actor)
+- [Use with Rails](#use-with-rails)
 - [Testing](#testing)
+- [Build your own actor](#build-your-own-actor)
 - [Influences](#influences)
+- [Thanks](#thanks)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#contributing)
@@ -59,7 +63,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 +142,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 +169,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 +228,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 +263,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 +337,19 @@ end
 
 You can use this to trigger an early success.
 
+## Use with Rails
+
+The [service_actor-rails](https://github.com/sunny/actor-rails/) gem includes a
+Rails generator to create an actor and its spec.
+
+## 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,14 +367,6 @@ 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
@@ -367,9 +389,16 @@ 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
@@ -377,9 +406,10 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 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 `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).
 
 ## Contributing
 
@@ -389,7 +419,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

@@ -5,32 +5,35 @@ 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'
 
 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(Defaultable)
+      base.include(Collectionable)
     end
   end
 end

data/lib/service_actor/collectionable.rb

@@ -0,0 +1,32 @@
+# 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}"
+        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:
   #

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/nil_checkable.rb

@@ -27,8 +27,6 @@ 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,
@@ -37,20 +35,9 @@ module ServiceActor
         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,16 +23,6 @@ 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

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.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: service_actor
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Sunny Ripert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-24 00:00:00.000000000 Z
+date: 2020-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -80,6 +80,34 @@ dependencies:
     - - ">="
       - !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,6 +123,7 @@ 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
@@ -103,7 +132,6 @@ files:
 - 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 +140,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,7 +149,10 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.3.7
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 2.8.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

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