axn 0.1.0.pre.alpha.1.1 → 0.1.0.pre.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a4820a9fbbd271a71be8a06320e362372d87590246931da17c48bb2299eb4fc
-  data.tar.gz: 18d6743feaaa914640bf3eaac95c67e79ad059179191a0987896c6fd49ead8d0
+  metadata.gz: d6ba4df4f3ce11e1a31eb8dfadde856141ed9dc6d10002efe1b544abcb580431
+  data.tar.gz: 0a27844c8b7c341315c8a1d9212fa0745866086cd3fbb65140b813a125ac8496
 SHA512:
-  metadata.gz: 459807c65792ef1d0624638750f7f14b66150525c9e643d5f48536b98424be935a4548969cc337d1d226cd9b062b6404968f31e95e43da8284b100450aac0d54
-  data.tar.gz: 2fec14a17957558f16bf1f813789b61a54b7b7f84a911acd8d80bffa794f8f1f6e559ee6b66b4668691ff360ed0d916ee28f6af2e5428a55c4428add5b6cd4a4
+  metadata.gz: 250b751b9a583d7206c9ada4e162ce8d2ee96816466515812e187e3dcdeb50f7024a595968c4e42f3f91a63909a38074e59b738a4f0216a0aaf1f15154e99452
+  data.tar.gz: cba3bee954fb153a99a65ff30478ae1d048fd49fe7834d4ba2446e4ff5e6ff70b3cfe588bc20a5d042665aa5bd9797cc4df10a4483cd59ce5b5d99b85bc4f645

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
   SuggestExtensions: false
   NewCops: enable
 

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.3.6

data/CHANGELOG.md

@@ -1,11 +1,19 @@
 # Changelog
 
 ## UNRELEASED
-
 * N/A
 
+
+## 0.1.0-alpha.2
+* Renamed `.rescues` to `.error_from`
+* Implemented new `.rescues` (like `.error_from`, but avoids triggering on_exception handler)
+* Prevented `expect`ing and `expose`ing fields that conflict with internal method names
+* [Action::Result] Removed `failure?` from public interface (prefer negating `ok?`)
+* Reorganized internals into Core vs (newly added) Attachable
+* Add some meta-functionality: Axn::Factory + Attachable (subactions + steps support)
+
 ## 0.1.0-alpha.1.1
-* revert `gets` / `sets` back to `expects` / `exposes`
+* Reverted `gets` / `sets` back to `expects` / `exposes`
 
 ## 0.1.0-alpha.1
 * Initial implementation

data/CONTRIBUTING.md

@@ -23,7 +23,7 @@ For the best chance of having your changes merged, please:
 
 ## Bug Reports
 
-If you are experiencing unexpected behavior and, after having read [our documentation](https://teamshares.github.io/axn/guide/), are convinced this behavior is a bug, please:
+If you are experiencing unexpected behavior and, after having read [our documentation](https://teamshares.github.io/axn/), are convinced this behavior is a bug, please:
 
 1. [Search](https://github.com/teamshares/axn/issues) existing issues.
 2. Collect enough information to reproduce the issue:

data/README.md

@@ -4,7 +4,7 @@ Just spinning this up -- not yet released (i.e. doc updates in flight).
 
 ## Installation & Usage
 
-See our [User Guide](https://teamshares.github.io/axn/guide/) for details.
+See our [User Guide](https://teamshares.github.io/axn/) for details.
 
 ## [!!] Inheritance Support
 

data/docs/.vitepress/config.mjs

@@ -9,29 +9,29 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'User Guide', link: '/guide' }
+      { text: 'Overview', link: '/intro/overview' },
+      { text: 'Guide', link: '/usage/setup' },
+      { text: 'Reference', link: '/reference/configuration' }
     ],
 
     sidebar: [
       {
         text: 'Introduction',
         items: [
-          { text: 'About', link: '/about/' },
-          { text: 'Summary Overview', link: '/guide/' },
+          { text: 'About', link: '/intro/about' },
+          { text: 'Overview', link: '/intro/overview' },
         ]
       },
       {
-        text: 'Getting Started',
+        text: 'Usage Guide',
         items: [
-          { text: 'Setup', link: '/usage/setup' },
+          { text: 'Getting Started', link: '/usage/setup' },
           { text: 'Writing Actions', link: '/usage/writing' },
           { text: 'Using Actions', link: '/usage/using' },
-          { text: 'Testing Actions', link: '/usage/testing' },
-          { text: 'Conventions', link: '/usage/conventions' },
         ]
       },
       {
-        text: 'Reference',
+        text: 'DSL Reference',
         items: [
           { text: 'Configuration', link: '/reference/configuration' },
           { text: 'Class Interface', link: '/reference/class' },
@@ -40,10 +40,18 @@ export default defineConfig({
         ]
       },
       {
-        text: 'Advanced Usage',
+        text: 'Recipes',
+        items: [
+          { text: 'Memoization', link: '/recipes/memoization' },
+          { text: 'Validating User Input', link: '/recipes/validating-user-input' },
+          { text: 'Testing Actions', link: '/recipes/testing' },
+        ]
+      },
+      {
+        text: 'Additional Notes',
         items: [
           { text: 'ROUGH NOTES', link: '/advanced/rough' },
-          { text: 'Validating User Input', link: '/advanced/validating-user-input' },
+          { text: 'Conventions', link: '/advanced/conventions' },
         ]
       },
     ],

data/docs/advanced/rough.md

@@ -6,6 +6,8 @@
 
 * General note: the inbound/outbound contexts are views into an underlying shared object (passed down through organize calls) -- modifications of one will affect the other (e.g. preprocessing inbound args implicitly transforms them on the underlying context, which is echoed if you also expose it on outbound).
 
+* `context_for_logging` (and decent #inspect support)
+
 * Configuring logging (will default to Rails.logger if available, else fall back to basic Logger (but can explicitly set via e.g. `Action.config.logger = Logger.new($stdout`))
 
     * Note `context_for_logging` is available (filtered to accessible attrs, filtering out sensitive values). Automatically passed into `on_exception` hook.

data/docs/index.md

@@ -8,8 +8,14 @@ hero:
   tagline: "**ALPHA release -- everything subject to change**"
   actions:
     - theme: brand
-      text: User Guide
-      link: /guide
+      text: Overview
+      link: /intro/overview
+    - theme: alt
+      text: Usage
+      link: /usage/setup
+    - theme: alt
+      text: DSL Reference
+      link: /reference/class
     # - theme: alt
     #   text: API Examples
     #   link: /api-examples
@@ -23,4 +29,6 @@ features:
     details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
 ---
 
-
+::: danger ALPHA RELEASE
+Axn is used in production at [Teamshares](https://teamshares.com/), but is still in alpha and is undergoing active development.
+:::

data/docs/{guide/index.md → intro/overview.md}

@@ -8,7 +8,7 @@ This library provides a set of conventions for writing business logic in Rails (
 
   * Clear calling semantics: `Foo.call`
   * A declarative interface
-  * A [consistent return interface](./#return-interface)
+  * A [consistent return interface](/intro/overview#return-interface)
     * Exception swallowing + clear distinction between internal and user-facing errors
 
 ### Minimal example
@@ -27,8 +27,6 @@ end
 
 ## Inputs and Outflows
 
-### Overview
-
 Most actions require inputs, and many return values to the caller; no need for any `def initialize` boilerplate, just add:
 
   * `expects :foo` to declare inputs the class expects to receive.
@@ -43,25 +41,14 @@ Most actions require inputs, and many return values to the caller; no need for a
 By design you _cannot access anything you do not explicitly `expose` from outside the action itself_.  Making the external interface explicit helps maintainability by ensuring you can refactor internals without breaking existing callsites.
 :::
 
-### Details
-Both `expects` and `exposes` support a variety of options:
-
-| Option | Example (same for `exposes`) | Meaning |
-| -- | -- | -- |
-| `sensitive` | `expects :password, sensitive: true` | Filters the fields value when logging, reporting errors, or calling `inspect`
-| `default` | `expects :foo, default: 123` | If `foo` isn't provided, it'll default to this value
-| `allow_blank` | `expects :foo, allow_blank: true` | Don't fail if the value is blank
-| `type` | `expects :foo, type: String` | Custom type validation -- fail unless `foo.is_a?(String)`
-| anything else | `expects :foo, inclusion: { in: [:apple, :peach] }` | Any other arguments will be processed [as ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html) (i.e. as if passed to `validate :foo, <...>` on an ActiveRecord model)
-
 ::: warning
-The declarative interface (`expects` and `exposes`) constitutes a contract you are making _with yourself_ (and your fellow developers). **This is _not_ for validating user input** -- [there's a Form Object pattern for that](/advanced/validating-user-input).
+The declarative interface (`expects` and `exposes`) constitutes a contract you are making _with yourself_ (and your fellow developers). **This is _not_ for validating user input** -- [there's a Form Object pattern for that](/recipes/validating-user-input).
 :::
 
-If any expectations fail, the action will fail early and set `error` to a generic error message (because a failed validation means _you_ called _your own_ service wrong; there's nothing the end user can do about that).
+If any declared expectations or exposures are _not_ met the action will fail, setting `error` to a generic error message (because a failed validation means _you_ called _your own_ service wrong; there's nothing the end user can do about that).
 
 
-### Putting it together
+### Example
 
 ```ruby
 class Actions::Slack::Post
@@ -88,23 +75,16 @@ end
 
 ## Return interface {#return-interface}
 
-### Overview
 
 The return value of an Action call is always an `Action::Result`, which provides a consistent interface:
 
-| Method | Description |
-| -- | -- |
-| `ok?` | `true` if the call succeeded, `false` if not.
-| `error` | Will _always_ be set to a safe-to-show-users string if not `ok?`
-| any `expose`d values | guaranteed to be set if `ok?` (since they have outgoing presence validations by default; any missing would have failed the action)
+* `ok?` will return a boolean (false if any errors or exceptions occurred, otherwise true)
+  * if OK, `success` will return a string that is _safe to show end users_
+  * if _not_ OK, `error` will return an error string that is _safe to show end users_
+* `message` is a helper to return the relevant message in either case (defined as `ok? ? success : error`)
 
-### Details
-
-::: danger ALPHA
-* TODO: link to a reference page for the full interface.
-:::
 
-### Putting it together
+### Example
 
 This interface yields a common usage pattern:
 
@@ -139,7 +119,7 @@ Note this simple pattern handles multiple levels of "failure" ([details below](#
 ::: tip BIG IDEA
 By design, `result.error` is always safe to show to the user.
 
-:star_struck: The calling code usually only cares about `ok?` and `error` -- no complex error handling needed.
+Calling code _usually_ only cares about `ok?` and `error` -- no complex error handling needed. :star_struck:
 :::
 
 
@@ -151,7 +131,6 @@ For _known_ failure modes, you can call `fail!("Some user-facing explanation")`
 
 ### Internal errors (uncaught `raise`)
 
-Any exceptions will be swallowed and the action failed (i.e. _not_ `ok?`). `result.error` will be set to a generic error message ("Something went wrong" by default, but highly configurable).
-<!-- TODO: link to messaging configs -->
+Any exceptions will be swallowed and the action failed (i.e. _not_ `ok?`). `result.error` will be set to a generic error message ("Something went wrong" by default, but [highly configurable](/reference/class#messages)).
 
 The swallowed exception will be available on `result.exception` for your introspection, but it'll also be passed to your `on_exception` handler so, [with a bit of configuration](/usage/setup), you can trust that any exceptions have been logged to your error tracking service automatically (one more thing the dev doesn't need to think about).

data/docs/recipes/memoization.md

@@ -0,0 +1,46 @@
+### Adding memoization
+
+For a practical example of [the `additional_includes` configuration](/reference/configuration#additional-includes) in practice, consider adding new functionality to all Actions.
+
+For instance, at Teamshares we automatically add memoization support (via [memo_wise](https://github.com/panorama-ed/memo_wise)) to all Actions.  But we didn't want to add another dependency to the core library, so we've implemented this by:
+
+
+```ruby
+  Action.configure do |c|
+    c.additional_includes = [TS::Memoization]
+  end
+```
+
+```ruby
+module TS::Memoization
+  extend ActiveSupport::Concern
+
+  included do
+    prepend MemoWise
+  end
+
+  class_methods do
+    def memo(...) = memo_wise(...)
+  end
+end
+```
+
+And with those pieces in place `memo` is available in all Actions:
+
+```ruby
+class ContrivedExample
+  include Action
+
+  exposes :nums
+
+  def call
+    expose nums: Array.new(10) { random_number }
+  end
+
+  private
+
+  memo def random_number = rand(1..100) # [!code focus]
+end
+```
+
+Because of the `memo` usage, `ContrivedExample.call.nums` will be a ten-element array of _the same number_, rather than re-calling `rand` for each element.

data/docs/{usage → recipes}/testing.md

@@ -7,7 +7,9 @@
 Configuring rspec to treat files in spec/actions as service specs:
 
 ```ruby
-config.define_derived_metadata(file_path: %r{spec/actions}) do |metadata|
-  metadata[:type] = :service
+RSpec.configure do |config|
+  config.define_derived_metadata(file_path: "spec/actions") do |metadata|
+    metadata[:type] = :service
+  end
 end
 ```

data/docs/reference/action-result.md

@@ -1,12 +1,35 @@
-::: danger ALPHA
-* TODO: convert this rough outline into actual documentation
-:::
+# `Action::Result`
 
+Every `call` invocation on an Action will return an `Action::Result` instance, which provides a consistent interface:
 
-`Action::Result`
+| Method | Description |
+| -- | -- |
+| `ok?` | `true` if the call succeeded, `false` if not.
+| `error` | User-facing error message (string), if not `ok?` (else nil)
+| `success` | User-facing success message (string), if `ok?` (else nil)
+| `message` | User-facing message (string), always defined (`ok? ? success : error`)
+| `exception` | If not `ok?` because an exception was swallowed, will be set to the swallowed exception (note: rarely used outside development; prefer to let the library automatically handle exception handling for you)
+| any `expose`d values | guaranteed to be set if `ok?` (since they have outgoing presence validations by default; any missing would have failed the action)
 
-  * ok?
-  * error
-  * exception
-  * success
-  * message
+NOTE: `success` and `error` (and so implicitly `message`) can be configured per-action via [the `messages` declaration](/reference/class#messages).
+
+### Clarification of exposed values
+
+In addition to the core interface, your Action's Result class will have methods defined to read the values of any attributes that were explicitly exposed.  For example, given this action and result:
+
+
+```ruby
+class Foo
+  include Action
+
+  exposes :bar, :baz # [!code focus]
+
+  def call
+    expose bar: 1, baz: 2
+  end
+end
+
+result = Foo.call # [!code focus]
+```
+
+`result` will have both `bar` and `baz` reader methods (which will return 1 and 2, respectively).

data/docs/reference/class.md

@@ -1,18 +1,75 @@
-::: danger ALPHA
-* TODO: convert this rough outline into actual documentation
+# Class Methods
+
+## `.expects` and `.exposes`
+
+Actions have a _declarative interface_, whereby you explicitly declare both inbound and outbound arguments.  Specifically, variables you expect to receive are specified via `expects`, and variables you intend to expose are specified via `exposes`.
+
+Both `expects` and `exposes` support the same core options:
+
+| Option | Example (same for `exposes`) | Meaning |
+| -- | -- | -- |
+| `sensitive` | `expects :password, sensitive: true` | Filters the field's value when logging, reporting errors, or calling `inspect`
+| `default` | `expects :foo, default: 123` | If `foo` isn't explicitly set, it'll default to this value
+| `allow_blank` | `expects :foo, allow_blank: true` | Don't fail if the value is blank
+| `type` | `expects :foo, type: String` | Custom type validation -- fail unless `name.is_a?(String)`
+| anything else | `expects :foo, inclusion: { in: [:apple, :peach] }` | Any other arguments will be processed [as ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html) (i.e. as if passed to `validates :foo, <...>` on an ActiveRecord model)
+
+
+### Validation details
+
+::: warning
+While we _support_ complex interface validations, in practice you usually just want a `type`, if anything.  Remember this is your validation about how the action is called, _not_ pretty user-facing errors (there's [a different pattern for that](/recipes/validating-user-input)).
 :::
 
-## Class-level interface
+In addition to the [standard ActiveModel validations](https://guides.rubyonrails.org/active_record_validations.html), we also support three additional custom validators:
+* `type: Foo` - fails unless the provided value `.is_a?(Foo)`
+* `boolean: true` - wrapper to handle a boolean field (since ruby doesn't have a Boolean class, so we can't use `type:` directly)
+* `validate: [callable]` - Support custom validations (fails if any string is returned OR if it raises an exception)
+  * Example:
+    ```ruby
+    expects :foo, validate: ->(value) { "must be pretty big" unless value > 10 }
+    ```
+
+
+
+### Details specific to `.expects`
+
+`expects` also supports a `preprocess` option that, if set to a callable, will be executed _before_ applying any validations.  This can be useful for type coercion, e.g.:
+
+```ruby
+expects :date, type: Date, preprocess: ->(d) { d.is_a?(Date) ? d : Date.parse(d) }
+```
+
+will succeed if given _either_ an actual Date object _or_ a string that Date.parse can convert into one.  If the preprocess callable raises an exception, that'll be swallowed and the action failed.
+
+### Details specific to `.exposes`
+
+Remember that you'll need [a corresponding `expose` call](/reference/instance#expose) for every variable you declare via `exposes`.
+
+
+## `.messages`
+
+The `messages` declaration allows you to customize the `error` and `success` messages on the returned result.
+
+Accepts `error` and/or `success` keys.  Values can be a string (returned directly) or a callable (evaluated in the action's context, so can access instance methods).  If `error` is provided with a callable that expects a positional argument, the exception that was raised will be passed in as that value.
+
+```ruby
+messages success: "All good!", error: ->(e) { "Bad news: #{e.message}" }
+```
+
+## `error_for` and `rescues`
+
+While `.messages` sets the _default_ error/success messages and is more commonly used, there are times when you want specific error messages for specific failure cases.
 
-* `expects`
-* `exposes`
-* `messages`
+`error_for` and `rescues` both register a matcher (exception class, exception class name (string), or callable) and a message to use if the matcher succeeds.  They act exactly the same, except if a matcher registered with `rescues` succeeds, the exception _will not_ trigger the configured global error handler.
 
-### `expects` and `exposes`
-* setting `sensitive: true` on any param will filter that value out when inspecting or passing to on_exception
-* Note we have two custom validations: boolean: true and the implicit type: foo.  (maybe with array of types?)
-    Note a third allows custom validations: `expects :foo, validate: ->(value) { "must be pretty big" unless value > 10 }` (error raised if any string returned OR if it raises an exception)
+```ruby
+messages error: "bad"
 
-### #call and #rollback
+# Note this will NOT trigger Action.config.on_exception
+rescues ActiveRecord::InvalidRecord => "Invalid params provided"
 
-### hooks
+# These WILL trigger error handler (second demonstrates callable matcher AND message)
+error_for ArgumentError, ->(e) { "Argument error: #{e.message}"
+error_for -> { name == "bad" }, -> { "was given bad name: #{name}" }
+```

data/docs/reference/configuration.md

@@ -5,27 +5,15 @@ Somewhere at boot (e.g. `config/initializers/actions.rb` in Rails), you can call
 
 ```ruby
   Action.configure do |c|
-    c.global_debug_logging = false
-
     c.on_exception = ...
 
     c.top_level_around_hook = ...
 
     c.additional_includes = []
-  end
-```
-
-## `global_debug_logging`
-
-By default, every `action.call` will emit _debug_ log lines when it is called (including the action class and any arguments it was provided) and after it completes (including the execution time and the outcome).
-
-You can bump the log level from `debug` to `info` for specific actions by including their class name (comma separated, if multiple) in a `SA_DEBUG_TARGETS` ENV variable.
 
-You can also turn this on _globally_ by setting `global_debug_logging = true`.
+    c.global_debug_logging = false
 
-```ruby
-  Action.configure do |c|
-    c.global_debug_logging = true
+    c.logger = ...
   end
 ```
 
@@ -42,7 +30,7 @@ For example, if you're using Honeybadger this could look something like:
       message = "[#{action.class.name}] Failing due to #{e.class.name}: #{e.message}"
 
       Rails.logger.warn(message)
-      Honeybadger.notify(message, context:)
+      Honeybadger.notify(message, context: { axn_context: context })
     end
   end
 ```
@@ -77,6 +65,10 @@ A couple notes:
   * `TS::Metrics` is a custom implementation to set a Datadog count metric, but the relevant part to note is that outcome (`success`, `failure`, `exception`) of the action is reported so you can easily track e.g. success rates per action.
 
 
+## `logger`
+
+Defaults to `Rails.logger`, if present, otherwise falls back to `Logger.new($stdout)`.  But can be set to a custom logger as necessary.
+
 ## `additional_includes`
 
 This is much less critical than the preceding options, but on the off chance you want to add additional customization to _all_ your actions you can set additional modules to be included alongside `include Action`.
@@ -88,3 +80,24 @@ For example:
     c.additional_includes = [SomeFancyCustomModule]
   end
 ```
+
+For a practical example of this in practice, see [our 'memoization' recipe](/recipes/memoization).
+
+## `global_debug_logging`
+
+By default, every `action.call` will emit _debug_ log lines when it is called and after it completes:
+
+  ```
+    [YourCustomAction] About to execute with: {:foo=>"bar"}
+    [YourCustomAction] Execution completed (with outcome: success) in 0.957 milliseconds
+  ```
+
+You can bump the log level from `debug` to `info` for specific actions by including their class name (comma separated, if multiple) in a `SA_DEBUG_TARGETS` ENV variable.
+
+You can also turn this on _globally_ by setting `global_debug_logging = true`.
+
+```ruby
+  Action.configure do |c|
+    c.global_debug_logging = true
+  end
+```

data/docs/reference/instance.md

@@ -1,17 +1,100 @@
-::: danger ALPHA
-* TODO: convert this rough outline into actual documentation
-:::
+# Instance Methods
 
+## `#expose`
 
-While coding:
-* `expose`
-* `fail!`
-* `log`
-* `try` - any exceptions raised by the block will trigger the on_exception handler, but then will be swallowed (the action is _not_ failed)
-    * Edge case: explicit `fail!` calls _will_ still fail the action
-* `hoist_errors`
-    * Edge case: intent is a single action call in the block -- if there are multiple calls, only the last one will be checked (anything explicitly _raised_ will still be handled).
-    <!-- TODO: is there difference between `SubAction.call!` and `hoist_errors { SubAction.call }`?? -->
-* `context_for_logging` (and decent #inspect support)
+Used to set a value on the Action::Result. Remember you can only `expose` keys that you have declared in [the class-level interface](/reference/class).
 
+* Accepts two positional arguments (the key and value to set, respectively): `expose :some_key, 123`
+* Accepts a hash with one or more key/value pairs: `expose some_key: 123, another: 456`
 
+Primarily used for its side effects, but it does return a Hash with the key/value pair(s) you exposed.
+
+
+## `#fail!`
+
+Called with a string, it immediately halts execution (including triggering any [rollback handler](/reference/class#rollback) you have defined) and sets `result.error` to the provided string.
+
+## `#log`
+
+Helper method to log (via the [configurable](/reference/configuration#logger) `Action.config.logger`) the string you provide (prefixed with the Action's class name).
+
+* First argument (required) is a string message to log
+* Also accepts a `level:` keyword argument to change the log level (defaults to `info`)
+
+Primarily used for its side effects; returns whatever the underlying `Action.config.logger` instance returns but it does return a Hash with the key/value pair(s) you exposed.
+
+## `#try`
+
+Accepts a block.  Any exceptions raised within that block will be swallowed, but _they will NOT fail the action_!
+
+A few details:
+* An explicit `fail!` call _will_ still fail the action
+* Any exceptions swallowed _will_ still be reported via the `on_exception` handler
+
+This is primarily useful in an after block, e.g. trigger notifications after an action has been taken.  If the notification fails to send you DO want to log the failure somewhere to investigate, but since the core action has already been taken often you do _not_ want to fail and roll back.
+
+Example:
+
+```ruby
+class Foo
+  include Action
+
+  after do
+    try { send_slack_notifications } # [!code focus]
+  end
+
+  def call = ...
+
+  private
+
+  def send_slack_notifications = ...
+end
+```
+
+## `#hoist_errors`
+
+Useful when calling one Action from within another.  By default the nested action call will return an Action::Result, but it's up to you to check if the result is `ok?` and to handle potential failure modes... and in practice this is easy to miss.
+
+By wrapping your nested call in `hoist_errors`, it will _automatically_ fail the parent action if the nested call fails.
+
+Accepts a `prefix` keyword argument -- when set, prefixes the `error` message from any failures in the block (useful to return different error messages for each if you're calling multiple sub-actions in a single service).
+
+NOTE: expects a single action call in the block -- if there are multiple calls, only the last one will be checked for `ok?` (although anything _raised_ in the block will still be handled).
+
+### Example
+
+```ruby
+class SubAction
+  include Action
+
+  def call
+    fail! "bad news"
+  end
+end
+
+class MainAction
+  include Action
+
+  def call
+    SubAction.call
+  end
+end
+```
+
+_Without_ `hoist_errors`, `MainAction.call` returns an `ok?` result, even though `SubAction.call` always fails, because we haven't explicitly handled the nested call.
+
+By adding `hoist_errors`, though:
+
+```ruby
+class MainAction
+  include Action
+
+  def call
+    hoist_errors(prefix: "From subaction:") do
+      SubAction.call
+    end
+  end
+end
+```
+
+`MainAction.call` now returns a _failed_ result, and `result.error` is "From subaction: bad news".

data/docs/usage/setup.md

@@ -6,8 +6,6 @@ outline: deep
 ## Installation
 
 Adding `axn` to your Gemfile is enough to start using `include Action`.
-<!-- todo bundler -->
-
 
 ## Global Configuration