service_actor 3.1.3 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40bbf17640409642508a6cb2dc7bd7197a49266ae9639c4a97c5cf52a3696ddd
-  data.tar.gz: 6b2627086780fcbead6e4ce3feff3565eab1bc5e3181a743296e8a7099e22480
+  metadata.gz: 8bde0ceb526951927f7349b5bd80dc2d6ca036e40e7dbc3ca98bc027f47fbd4c
+  data.tar.gz: cd90e8762fe61eccd643fcdb318ebb27b79a561dbc8075ae4e2c802734ace9f7
 SHA512:
-  metadata.gz: 0af13a24439bbab76ce2ae6ddf57e41b86b34c4f81e7d333650675195ab27d2519385e479bc1c41eee3c61f54253812c7e6579fea47bd7d8d17839d76a9808af
-  data.tar.gz: d25a43b1637a9dd1d79c6c0686ccc9bc2bb69dfbf0667c5a8775b1ac3fffab4c3d2233a955a17d676a0ee17b1af1a583449ac39dea220bbc02df3f82e9df6275
+  metadata.gz: 2cddbccf7794088dc4a25b011cdb1155d0b6e855abd4a83630402ec90d4fe2f6c4c7fa4a0935ddca7faee58e49b2ff3d1f9f99b430c76dcc2990452d06d16ded
+  data.tar.gz: 81444f049effd685780bd4904c3513c7d7adf220c2ecf4ca6a3bf18e077d1b207786f6b85eeb02597e23700bf2a661c3a83f2c4602333bf85c6adf7e810652ef

data/README.md

@@ -1,4 +1,4 @@
-# Actor
+# ServiceActor
 
 ![Tests](https://github.com/sunny/actor/workflows/Tests/badge.svg)
 
@@ -21,31 +21,37 @@ and controllers thin.
   - [Fail](#fail)
 - [Play actors in a sequence](#play-actors-in-a-sequence)
   - [Rollback](#rollback)
-  - [Lambdas](#lambdas)
+  - [Inline actors](#inline-actors)
   - [Play conditions](#play-conditions)
 - [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 the gem to your application’s Gemfile by executing:
 
-```rb
-# Composable service objects
-gem 'service_actor'
+```sh
+bundle add service_actor
 ```
 
-When using Rails, you can include the
+### Extensions
+
+For **Rails generators**, you can use the
 [service_actor-rails](https://github.com/sunny/actor-rails) gem:
 
-```ruby
-# Composable service objects
-gem "service_actor-rails"
+```sh
+bundle add service_actor-rails
+```
+
+For **TTY prompts**, you can use the
+[service_actor-promptable](https://github.com/pboling/service_actor-promptable) gem:
+
+```sh
+bundle add service_actor-promptable
 ```
 
 ## Usage
@@ -69,9 +75,10 @@ Trigger them in your application with `.call`:
 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
-and then we'll see how to chain multiple actors togethor.
+When called, an actor returns a result. Reading and writing to this result allows
+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](#play-actors-in-a-sequence).
 
 ### Inputs
 
@@ -111,8 +118,19 @@ end
 The result you get from calling an actor will include the outputs you set:
 
 ```rb
-result = BuildGreeting.call
-result.greeting # => "Have a wonderful day!"
+actor = BuildGreeting.call
+actor.greeting # => "Have a wonderful day!"
+```
+
+For every output there is also a boolean method ending with `?` to test its
+presence:
+
+```rb
+if actor.greeting?
+  puts "Greetings is truthy"
+else
+  puts "Greetings is falsey"
+end
 ```
 
 ### Defaults
@@ -136,14 +154,14 @@ end
 This lets you call the actor without specifying those keys:
 
 ```rb
-result = BuildGreeting.call(name: "Jim")
-result.greeting # => "Have a wonderful week Jim!"
+actor = BuildGreeting.call(name: "Jim")
+actor.greeting # => "Have a wonderful week Jim!"
 ```
 
 If an input does not have a default, it will raise a error:
 
 ```rb
-result = BuildGreeting.call
+BuildGreeting.call
 => ServiceActor::ArgumentError: Input name on BuildGreeting is missing.
 ```
 
@@ -168,7 +186,7 @@ You can also add custom conditions with the name of your choice by using `must`:
 class UpdateAdminUser < Actor
   input :user,
         must: {
-          be_an_admin: ->(user) { user.admin? }
+          be_an_admin: -> user { user.admin? }
         }
 
   # …
@@ -207,7 +225,7 @@ class UpdateUser < Actor
 end
 ```
 
-You may also use strings instead of constants, such as `type: 'User'`.
+You may also use strings instead of constants, such as `type: "User"`.
 
 When using a type condition, `allow_nil` defaults to `false`.
 
@@ -242,11 +260,11 @@ For example in a Rails controller:
 # app/controllers/users_controller.rb
 class UsersController < ApplicationController
   def create
-    result = UpdateUser.result(user: user, attributes: user_attributes)
-    if result.success?
-      redirect_to result.user
+    actor = UpdateUser.result(user: user, attributes: user_attributes)
+    if actor.success?
+      redirect_to actor.user
     else
-      render :new, notice: result.error
+      render :new, notice: actor.error
     end
   end
 end
@@ -263,7 +281,7 @@ actor can use `play` to call other actors:
 ```rb
 class PlaceOrder < Actor
   play CreateOrder,
-       Pay,
+       PayOrder,
        SendOrderConfirmation,
        NotifyAdmins
 end
@@ -299,26 +317,51 @@ Rollback is only called on the _previous_ actors in `play` and is not called on
 the failing actor itself. Actors should be kept to a single purpose and not have
 anything to clean up if they call `fail!`.
 
-### Lambdas
+### Inline actors
 
-You can use inline actions using lambdas. Inside these lambdas you have access to
-the shared result:
+For small work or preparing the result set for the next actors, you can create
+inline actors by using lambdas. Each lambda has access to the shared result. For
+example:
 
 ```rb
-class Pay < Actor
-  play ->(result) { result.payment_provider = "stripe" },
+class PayOrder < Actor
+  input :order
+
+  play -> actor { actor.order.currency ||= "EUR" },
        CreatePayment,
-       ->(result) { result.user_to_notify = result.payment.user },
-       SendNotification
+       UpdateOrderBalance,
+       -> actor { Logger.info("Order #{actor.order.id} paid") }
 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, after or around
-the whole `play`, you can also override the `call` method. For example:
+You can also call instance methods. For example:
 
 ```rb
-class Pay < Actor
+class PayOrder < Actor
+  input :order
+
+  play :assign_default_currency,
+       CreatePayment,
+       UpdateOrderBalance,
+       :log_payment
+
+  private
+
+  def assign_default_currency
+    order.currency ||= "EUR"
+  end
+
+  def log_payment
+    Logger.info("Order #{order.id} paid")
+  end
+end
+```
+
+If you want to do work around the whole actor, you can also override the `call`
+method. For example:
+
+```rb
+class PayOrder < Actor
   # …
 
   def call
@@ -337,12 +380,10 @@ Actors in a play can be called conditionally:
 class PlaceOrder < Actor
   play CreateOrder,
        Pay
-  play NotifyAdmins, if: ->(result) { result.order.amount > 42 }
+  play NotifyAdmins, if: -> actor { actor.order.amount > 42 }
 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`
@@ -392,7 +433,7 @@ Some key differences make Actor unique:
 
 - Does not [hide errors when an actor fails inside another
   actor](https://github.com/collectiveidea/interactor/issues/170).
-- Requires you to document all arguments with `input` and `output`.
+- Requires you to document arguments with `input` and `output`.
 - Defaults to raising errors on failures: actor uses `call` and `result`
   instead of `call!` and `call`. This way, the _default_ is to raise an error
   and failures are not hidden away because you forgot to use `!`.
@@ -401,7 +442,8 @@ Some key differences make Actor unique:
   `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.
+- Organizers allow lambdas, instance methods, being called multiple times,
+  and having conditions.
 - Allows early success with conditions inside organizers.
 - No `before`, `after` and `around` hooks, prefer using `play` with lambdas or
   overriding `call`.
@@ -414,33 +456,17 @@ migration.
 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
+Thank you to the wonderful
+[contributors](https://github.com/sunny/actor/graphs/contributors).
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`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 `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).
+Photo by [Lloyd Dirks](https://unsplash.com/photos/4SLz_RCk6kQ).
 
 ## Contributing
 
-Bug reports and pull requests are welcome
-[on GitHub](https://github.com/sunny/actor).
-
-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/main/CODE_OF_CONDUCT.md).
+See
+[CONTRIBUTING.md](https://github.com/sunny/actor/blob/main/CONTRIBUTING.md).
 
 ## License
 
 The gem is available as open source under the terms of the
-[MIT License](https://opensource.org/licenses/MIT).
+[MIT License](https://choosealicense.com/licenses/mit/).

data/lib/service_actor/base.rb

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
 # Exceptions
-require 'service_actor/error'
-require 'service_actor/failure'
-require 'service_actor/argument_error'
+require "service_actor/error"
+require "service_actor/failure"
+require "service_actor/argument_error"
 
 # Core
-require 'service_actor/core'
-require 'service_actor/attributable'
-require 'service_actor/playable'
-require 'service_actor/result'
+require "service_actor/core"
+require "service_actor/attributable"
+require "service_actor/playable"
+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'
+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

data/lib/service_actor/collectionable.rb

@@ -7,7 +7,7 @@ module ServiceActor
   # Example:
   #
   #   class Pay < Actor
-  #     input :provider, in: ['MANGOPAY', 'PayPal', 'Stripe']
+  #     input :provider, in: ["MANGOPAY", "PayPal", "Stripe"]
   #   end
   module Collectionable
     def self.included(base)

data/lib/service_actor/conditionable.rb

@@ -11,7 +11,7 @@ module ServiceActor
   #   class Pay < Actor
   #     input :provider,
   #           must: {
-  #             exist: ->(provider) { PROVIDERS.include?(provider) }
+  #             exist: -> provider { PROVIDERS.include?(provider) },
   #           }
   #   end
   module Conditionable

data/lib/service_actor/core.rb

@@ -9,9 +9,9 @@ module ServiceActor
     module ClassMethods
       # Call an actor with a given result. Returns the result.
       #
-      #   CreateUser.call(name: 'Joe')
-      def call(options = nil, **arguments)
-        result = Result.to_result(options).merge!(arguments)
+      #   CreateUser.call(name: "Joe")
+      def call(result = nil, **arguments)
+        result = Result.to_result(result).merge!(arguments)
         new(result)._call
         result
       end
@@ -19,9 +19,9 @@ module ServiceActor
       # Call an actor with arguments. Returns the result and does not raise on
       # failure.
       #
-      #   CreateUser.result(name: 'Joe')
-      def result(data = nil, **arguments)
-        call(data, **arguments)
+      #   CreateUser.result(name: "Joe")
+      def result(result = nil, **arguments)
+        call(result, **arguments)
       rescue Failure => e
         e.result
       end

data/lib/service_actor/nil_checkable.rb

@@ -16,11 +16,11 @@ module ServiceActor
 
     module PrependedMethods
       def _call
-        check_context_for_nil(self.class.inputs, origin: 'input')
+        check_context_for_nil(self.class.inputs, origin: "input")
 
         super
 
-        check_context_for_nil(self.class.outputs, origin: 'output')
+        check_context_for_nil(self.class.outputs, origin: "output")
       end
 
       private
@@ -31,7 +31,7 @@ module ServiceActor
 
           raise ArgumentError,
                 "The #{origin} \"#{name}\" on #{self.class} does not allow " \
-                'nil values'
+                "nil values"
         end
       end
 

data/lib/service_actor/playable.rb

@@ -2,7 +2,7 @@
 
 module ServiceActor
   # Play class method to call a series of actors with the same result. On
-  # failure, calls rollback on any actor that succeeded.
+  # failure, calls rollback on actors that succeeded.
   #
   #   class CreateUser < Actor
   #     play SaveUser,
@@ -16,14 +16,6 @@ module ServiceActor
     end
 
     module ClassMethods
-      def inherited(child)
-        super
-
-        play_actors.each do |actor|
-          child.play_actors << actor
-        end
-      end
-
       def play(*actors, **options)
         actors.each do |actor|
           play_actors.push({ actor: actor, **options })
@@ -33,6 +25,14 @@ module ServiceActor
       def play_actors
         @play_actors ||= []
       end
+
+      def inherited(child)
+        super
+
+        play_actors.each do |actor|
+          child.play_actors << actor
+        end
+      end
     end
 
     module PrependedMethods
@@ -61,6 +61,7 @@ module ServiceActor
 
       def play_actor(actor)
         play_service_actor(actor) ||
+          play_symbol(actor) ||
           play_interactor(actor) ||
           actor.call(result)
       end
@@ -75,9 +76,17 @@ module ServiceActor
         (@played ||= []).unshift(actor)
       end
 
+      def play_symbol(actor)
+        return unless actor.is_a?(Symbol)
+
+        send(actor)
+
+        true
+      end
+
       def play_interactor(actor)
         return unless actor.is_a?(Class)
-        return unless actor.ancestors.map(&:name).include?('Interactor')
+        return unless actor.ancestors.map(&:name).include?("Interactor")
 
         result.merge!(actor.call(result).to_h)
       end

data/lib/service_actor/result.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'ostruct'
+require "ostruct"
 
 module ServiceActor
   # Represents the context of an actor, holding the data from both its inputs
@@ -51,5 +51,28 @@ module ServiceActor
     def display
       to_h.fetch(:display)
     end
+
+    private
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name.to_s.end_with?("?") || super
+    end
+
+    def method_missing(symbol, *args)
+      attribute = symbol.to_s.chomp("?")
+
+      if symbol.to_s.end_with?("?") && respond_to?(attribute)
+        define_singleton_method symbol do
+          attribute_value = send(attribute.to_sym)
+
+          # Same as ActiveSupport’s #present?
+          attribute_value.respond_to?(:empty?) ? !attribute_value.empty? : !!attribute_value
+        end
+
+        return send(symbol)
+      end
+
+      super symbol, *args
+    end
   end
 end

data/lib/service_actor/type_checkable.rb

@@ -7,7 +7,7 @@ module ServiceActor
   # Example:
   #
   #   class ReduceOrderAmount < Actor
-  #     input :order, type: 'Order'
+  #     input :order, type: "Order"
   #     input :amount, type: [Integer, Float]
   #     input :bonus_applied, type: [TrueClass FalseClass]
   #   end
@@ -18,11 +18,11 @@ module ServiceActor
 
     module PrependedMethods
       def _call
-        check_type_definitions(self.class.inputs, kind: 'Input')
+        check_type_definitions(self.class.inputs, kind: "Input")
 
         super
 
-        check_type_definitions(self.class.outputs, kind: 'Output')
+        check_type_definitions(self.class.outputs, kind: "Output")
       end
 
       private

data/lib/service_actor/version.rb

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

data/lib/service_actor.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'service_actor/base'
+require "service_actor/base"
 
 # Class to inherit from in your application.
 class Actor

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: service_actor
 version: !ruby/object:Gem::Version
-  version: 3.1.3
+  version: 3.2.0
 platform: ruby
 authors:
 - Sunny Ripert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-01-21 00:00:00.000000000 Z
+date: 2022-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -53,19 +53,25 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: rubocop-lts
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 12.0.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 12.0.1
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement