service_actor 1.0.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a16f2ccd8bf0d2e83d5cb9ec163c81b9df3be06515cb716138049f9d33420759
-  data.tar.gz: bfb6c4dca34cb64fa3c8ce84b085faa85547c1a554f241ccf49d92a7a67d012b
+  metadata.gz: c9d2367f70743f81df7df55ba4bc9a7fbcb5c27c08c2219abad25139763914f3
+  data.tar.gz: 107897dcd684becef83e44d9f07a2061b41a36d726120a92ebfef5ba549b4375
 SHA512:
-  metadata.gz: 18df62d093865eefd2acd8a9d3567c1379be5c097c087b6c2d2eee1dc8cf0485e5b0b6f712b11a19492eca3465b48ba0281de7b88130e170681923ec3cc2086c
-  data.tar.gz: 80df1b4cc8269802cfe217663fa16ed907103a1b3e4b8ee42d1d01ac08c47a571f4993439f27d1065fbbb38738132be459b042aadfd04bdfe229bb6a2a4dbc27
+  metadata.gz: 335b5893e4cc4bc8c506c0503700f2617ba845fcf9d819a70fd4e42e67116c9cd3fbf9570a4ab2660f54c00b112a49108581d1858a65bbfa3e77f97417b8336f
+  data.tar.gz: d450f69555986cf33a96fe52b5fa254e768c3c96f60e7c9dbcd345906c3c66bd4f92149e0de66d87c78059c5ecf5ba6b936705a57cbec2a773136b18bdab22ff

data/README.md

@@ -2,19 +2,45 @@
 
 ![Tests](https://github.com/sunny/actor/workflows/Tests/badge.svg)
 
-Ruby service objects. Lets you move your application logic into small
-building blocs to keep your controllers and your models thin.
+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)
+- [Usage](#usage)
+  - [Inputs](#inputs)
+  - [Outputs](#outputs)
+  - [Defaults](#defaults)
+  - [Conditions](#conditions)
+  - [Allow nil](#allow-nil)
+  - [Types](#types)
+  - [Result](#result)
+- [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)
+- [Thanks](#thanks)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#contributing)
 
 ## Installation
 
 Add these lines to your application's Gemfile:
 
 ```rb
-# Service objects to keep the business logic
+# Composable service objects
 gem 'service_actor'
 ```
 
-
 ## Usage
 
 Actors are single-purpose actions in your application that represent your
@@ -30,15 +56,19 @@ class SendNotification < Actor
 end
 ```
 
-Use `.call` to use them in your application:
+Trigger them in your application with `.call`:
 
 ```rb
-SendNotification.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.
+
 ### Inputs
 
-Actors can accept arguments with `input`:
+To accept arguments, use `input` to create a method named after this input:
 
 ```rb
 class GreetUser < Actor
@@ -50,7 +80,7 @@ class GreetUser < Actor
 end
 ```
 
-And receive them as arguments to `call`:
+You can now call your actor by providing the correct arguments:
 
 ```rb
 GreetUser.call(user: User.first)
@@ -58,20 +88,20 @@ GreetUser.call(user: User.first)
 
 ### Outputs
 
-Use `output` to declare what your actor can return, then assign them to your
-context.
+An actor can return multiple arguments. Declare them using `output`, which adds
+a setter method to let you modify the result from your actor:
 
 ```rb
 class BuildGreeting < Actor
   output :greeting
 
   def call
-    context.greeting = "Have a wonderful day!"
+    self.greeting = 'Have a wonderful day!'
   end
 end
 ```
 
-Calling an actor returns a context:
+The result you get from calling an actor will include the outputs you set:
 
 ```rb
 result = BuildGreeting.call
@@ -80,39 +110,53 @@ result.greeting # => "Have a wonderful day!"
 
 ### Defaults
 
-Inputs can have defaults:
+Inputs can be marked as optional by providing a default:
 
 ```rb
-class PrintWelcome < Actor
-  input :user
-  input :adjective, default: "wonderful"
-  input :length_of_time, default: -> { ["day", "week", "month"].sample }
+class BuildGreeting < Actor
+  input :name
+  input :adjective, default: 'wonderful'
+  input :length_of_time, default: -> { ['day', 'week', 'month'].sample }
 
   output :greeting
 
   def call
-    context.greeting = "Hello #{name}! Have a #{adjective} #{length_of_time}!"
+    self.greeting = "Have a #{adjective} #{length_of_time} #{name}!"
   end
 end
 ```
 
-### Types
+This lets you call the actor without specifying those keys:
 
-Inputs can define a type, or an array of possible types it must match:
+```rb
+result = BuildGreeting.call(name: 'Jim')
+result.greeting # => "Have a wonderful week Jim!"
+```
+
+If an input does not have a default, it will raise a error:
 
 ```rb
-class UpdateUser < Actor
-  input :user, type: 'User'
-  input :age, type: %w[Integer Float]
+result = BuildGreeting.call
+=> ServiceActor::ArgumentError: Input name on BuildGreeting is missing.
+```
+
+### Conditions
+
+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
 ```
 
-### Conditions
+This raises an argument error if the input does not match one of the given
+values.
 
-If types don't cut it, you can add small conditions with the name of your choice
-under `must`:
+You can also add custom conditions with the name of your choice by using `must`:
 
 ```rb
 class UpdateAdminUser < Actor
@@ -120,13 +164,51 @@ class UpdateAdminUser < Actor
         must: {
           be_an_admin: ->(user) { user.admin? }
         }
+
+  # …
 end
 ```
 
+This raises an argument error if the given lambda returns a falsey value.
+
+### Allow nil
+
+By default inputs accept `nil` values. To raise an error instead:
+
+```rb
+class UpdateUser < Actor
+  input :user, allow_nil: false
+
+  # …
+end
+```
+
+### Types
+
+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.
+
+```rb
+class UpdateUser < Actor
+  input :user, type: User
+  input :age, type: [Integer, Float]
+
+  # …
+end
+```
+
+You may also use strings instead of constants, such as `type: 'User'`.
+
+When using a type condition, `allow_nil` defaults to `false`.
+
 ### Result
 
-All actors are successful by default. To stop its execution and mark is as
-having failed, use `fail!`:
+All actors return a successful result by default. To stop the execution and
+mark an actor as having failed, use `fail!`:
 
 ```rb
 class UpdateUser
@@ -136,16 +218,17 @@ class UpdateUser
   def call
     user.attributes = attributes
 
-    fail!(error: "Invalid user") unless user.valid?
+    fail!(error: 'Invalid user') unless user.valid?
 
     # …
   end
 end
 ```
 
-You can then test for the success by calling your actor with `.result` instead
-of `.call`. This will let you test for `success?` or `failure?` on the context
-instead of raising an exception.
+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.
 
 For example in a Rails controller:
 
@@ -163,10 +246,13 @@ class UsersController < ApplicationController
 end
 ```
 
-### Play
+Any 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
 
-An actor can call actors in sequence by using `play`. Each actor will hand over
-the context to the next actor.
+To help you create actors that are small, single-responsibility actions, an
+actor can use `play` to call other actors:
 
 ```rb
 class PlaceOrder < Actor
@@ -177,51 +263,56 @@ class PlaceOrder < Actor
 end
 ```
 
+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
 
-When using `play`, if one of the actors calls `fail!`, the following actors will
-not be called.
+When using `play`, when an actor calls `fail!`, the following actors will not be
+called.
 
-Also, any _previous_ actor that succeeded will call the `rollback` method, if
-you defined one.
+Instead, all the actors that succeeded will have their `rollback` method called
+in reverse order. This allows actors a chance to cleanup, for example:
 
 ```rb
 class CreateOrder < Actor
+  output :order
+
   def call
-    context.order = Order.create!(…)
+    self.order = Order.create!(…)
   end
 
   def rollback
-    context.order.destroy
+    order.destroy
   end
 end
 ```
 
-### Early success
-
-When using `play` you can use `succeed!` so that the following actors will not
-be called, but still consider the actor to be successful.
+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
 
-You can call inline actions using 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:
 
 ```rb
-class Pay
-  play ->(ctx) { ctx.payment_provider = "stripe" },
+class Pay < Actor
+  play ->(result) { result.payment_provider = "stripe" },
        CreatePayment,
-       ->(ctx) { ctx.user_to_notify = ctx.payment.user },
+       ->(result) { result.user_to_notify = result.payment.user },
        SendNotification
 end
 ```
 
-### Before, after and around
-
-To do actions before or after actors, use lambdas or simply override `call` and
-use `super`. For example:
+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:
 
 ```rb
-class Pay
+class Pay < Actor
   # …
 
   def call
@@ -234,13 +325,59 @@ end
 
 ### Play conditions
 
-Some actors in a play can be called conditionaly:
+Actors in a play can be called conditionally:
 
 ```rb
 class PlaceOrder < Actor
   play CreateOrder,
        Pay
-  play NotifyAdmins, if: ->(ctx) { ctx.order.amount > 42 }
+  play NotifyAdmins, if: ->(result) { result.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`
+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
+```
+
+## 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
+changing the gem's require statement:
+
+```rb
+gem 'service_actor', require: 'service_actor/base'
+```
+
+And building your own class to inherit from:
+
+```rb
+class ApplicationActor
+  include ServiceActor::Base
 end
 ```
 
@@ -248,51 +385,57 @@ end
 
 This gem is heavily influenced by
 [Interactor](https://github.com/collectiveidea/interactor) ♥.
-However there a a few key differences which make `actor` unique:
-
-- 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.
-- Does not [hide errors when an actor fails inside another actor](https://github.com/collectiveidea/interactor/issues/170).
-- You can use lambdas inside organizers.
-- Requires you to document the arguments with `input` and `output`.
-- Type checking of inputs and outputs.
-- Inputs and outputs can be required.
-- Defaults for inputs.
-- Conditions on inputs.
-- Shorter fail syntax: `fail!` vs `context.fail!`.
-- Trigger early success in organisers with `succeed!`.
-- Shorter setup syntax: inherit from `< Actor` vs having to `include Interactor` or `include Interactor::Organizer`.
-- Multiple organizers.
-- Conditions inside organizers.
-- No `before`, `after` and `around` hooks. Prefer simply overriding `call` with `super` which allows wrapping the whole method.
-- [Does not rely on `OpenStruct`](https://github.com/collectiveidea/interactor/issues/183)
-- Does not print warnings on Ruby 2.7.
-
+However there are a few key differences which 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`.
+- 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 `!`.
+- 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!`.
+- 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.
+- Allows early success with conditions inside organizers.
+- 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. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment.
+`rake` to run the tests and linting. You can also run `bin/console` for an
+interactive prompt.
 
-To install this gem onto your local machine, run `bundle exec rake install`.
-To release a new version, update the version number in `version.rb`, and then
-run `bundle exec rake release`, which will create a git tag for the version,
-push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+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 && 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
 
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/sunny/actor. This project is intended to be a safe,
-welcoming space for collaboration, and contributors are expected to adhere to
-the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+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).
 
 ## License
 
 The gem is available as open source under the terms of the
 [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Test project’s codebases, issue trackers, chat
-rooms and mailing lists is expected to follow the
-[code of conduct](https://github.com/sunny/actor/blob/master/CODE_OF_CONDUCT.md).