service_actor 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f46ecd0093a05e45fe0bc3ba11a69a8b282b82f4945ab05ff9f5cd1cd32e35e
-  data.tar.gz: 91f2c49e081eba4abbebceaef9abc131c3e8ad1c84a723846d144e2c8a890dff
+  metadata.gz: e103cfa965d8a142d4d47ad910bd4411f90392ab4057b8536a265e12febbf42b
+  data.tar.gz: cf297af32084c0a7ff7d3f85ecab5f52137516d5fc2d2c0aa1f5a1fb1aceccfd
 SHA512:
-  metadata.gz: bee18ffff2ffbf4eb185b28ab16c519ca30e09af6ba61773009d553c563e9dbdf903aa7c5d6a66b3a4c8a49886f00337b474e1e1376f207f81d1cbe268f3f29b
-  data.tar.gz: 68e99c61d126b23877cfc4497a4c830b343e1170f49b027013da7a68062d85f644f689ad389d4c584e5b39206cac66a4cb6ab9e359ac9f65a309832c14dab060
+  metadata.gz: 76cc57cc0c3eca0c951f3bf046e7132bd28157081ff7a815fa44b9ef6375180f035aecee14bf735d0a655e72fa48f840610694c505f90e81cb72e84bc67ea7b7
+  data.tar.gz: 77c0cae0fe870e7a771023a45fbe919eeda92b8ed6e6d32187b4a85ddf906fbae27b1b615830d659214754914a7c0038ecdbba4a7b88b81234e2b96cdc08486c

data/README.md

@@ -2,19 +2,41 @@
 
 ![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.
+
+## 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)
+- [Build your own actor](#build-your-own-actor)
+- [Testing](#testing)
+- [Influences](#influences)
+- [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 +52,18 @@ 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.
+
 ### 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 +75,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 +83,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,17 +105,18 @@ result.greeting # => "Have a wonderful day!"
 
 ### Defaults
 
-Inputs can have defaults:
+Inputs can be marked as optional by providing a default:
 
 ```rb
 class BuildGreeting < Actor
-  input :adjective, default: "wonderful"
-  input :length_of_time, default: -> { ["day", "week", "month"].sample }
+  input :name
+  input :adjective, default: 'wonderful'
+  input :length_of_time, default: -> { ['day', 'week', 'month'].sample }
 
   output :greeting
 
   def call
-    context.greeting = "Have a #{adjective} #{length_of_time}!"
+    self.greeting = "Have a #{adjective} #{length_of_time} #{name}!"
   end
 end
 ```
@@ -98,52 +124,73 @@ end
 This lets you call the actor without specifying those keys:
 
 ```rb
-BuildGreeting.call.greeting # => "Have a wonderful week!"
+result = BuildGreeting.call(name: 'Jim')
+result.greeting # => "Have a wonderful week Jim!"
 ```
 
-### Types
+If an input does not have a default, it will raise a error:
+
+```rb
+result = BuildGreeting.call
+=> ServiceActor::ArgumentError: Input name on BuildGreeting is missing.
+```
 
-Inputs can define a type, or an array of possible types it must match:
+### Conditions
+
+You can add simple conditions that the inputs must verify, with the name of your
+choice under `must`:
 
 ```rb
-class UpdateUser < Actor
-  input :user, type: 'User'
-  input :age, type: %w[Integer Float]
+class UpdateAdminUser < Actor
+  input :user,
+        must: {
+          be_an_admin: ->(user) { user.admin? }
+        }
 
   # …
 end
 ```
 
-### Required
+In case the input does not match, it will raise an argument error.
 
-To check that an input must not be `nil`, flag it as required.
+### Allow nil
+
+By default inputs accept `nil` values. To raise an error instead:
 
 ```rb
 class UpdateUser < Actor
-  input :user, required: true
+  input :user, allow_nil: false
 
   # …
 end
 ```
 
-### Conditions
+### Types
 
-You can also add conditions that the inputs must verify, with the name of your
-choice under `must`:
+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 UpdateAdminUser < Actor
-  input :user,
-        must: {
-          be_an_admin: ->(user) { user.admin? }
-        }
+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 the execution and mark an actor 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
@@ -153,17 +200,20 @@ class UpdateUser
   def call
     user.attributes = attributes
 
-    fail!(error: "Invalid user") unless user.valid?
+    fail!(error: 'Invalid user') unless user.valid?
 
     # …
   end
 end
 ```
 
-This will raise an error in your app.
+This will raise an error in your app with the given data added to the result.
 
-To test for the success instead of raising, you can use `.result` instead of
-`.call`. For example in a Rails controller:
+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.
+
+For example in a Rails controller:
 
 ```rb
 # app/controllers/users_controller.rb
@@ -179,10 +229,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 same 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
@@ -193,51 +246,56 @@ 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.
+
 ### 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, all the _previous_ actors that succeeded will have their `rollback`
-method triggered. For example:
+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!` to stop the execution of the following
-actors, 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 use 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
@@ -250,63 +308,90 @@ 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.
+
+## 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
+```
+
+## 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 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.
-- [Fixes issues with `OpenStruct`](https://github.com/collectiveidea/interactor/issues/183)
+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`.
+
+Thank you to @nicoolas25, @AnneSottise & @williampollet for the early thoughts
+and feedback on this gem.
 
 ## 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`, 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).
 
 ## 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/master/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).