Skip to content

Commit

Permalink
Refer to dry-rb gem names without code formatting
Browse files Browse the repository at this point in the history
The name “dry-operation” is not a piece of code, but the name of the gem, so we don’t need any special formatting for it.
  • Loading branch information
timriley committed Oct 30, 2024
1 parent 1370743 commit 4ac0421
Show file tree
Hide file tree
Showing 4 changed files with 12 additions and 11 deletions.
2 changes: 1 addition & 1 deletion docsite/source/configuration.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ layout: gem-single
name: dry-operation
---

By default, `dry-operation` automatically wraps the `#call` method of your operations with failure tracking and error handling (the `#on_failure` hook). This means you can use `#step` directly in your `#call` method without explicitly wrapping it in an otherwise necessary `steps do ... end` block.
By default, dry-operation automatically wraps the `#call` method of your operations with failure tracking and error handling (the `#on_failure` hook). This means you can use `#step` directly in your `#call` method without explicitly wrapping it in an otherwise necessary `steps do ... end` block.

```ruby
class CreateUser < Dry::Operation
Expand Down
8 changes: 4 additions & 4 deletions docsite/source/design-pattern.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ layout: gem-single
name: dry-operation
---

`dry-operation` implements a pattern that closely resembles monadic composition, particularly the `Result` monad, and the Railway-oriented Programming pattern. Understanding these monadic concepts can provide deeper insight into how `dry-operation` works and why it's designed this way.
dry-operation implements a pattern that closely resembles monadic composition, particularly the `Result` monad, and the Railway-oriented Programming pattern. Understanding these monadic concepts can provide deeper insight into how dry-operation works and why it's designed this way.

### Monadic Composition

In functional programming, a monad is a structure that represents computations defined as sequences of steps. A key feature of monads is their ability to chain operations, with each operation depending on the result of the previous one.

`dry-operation` emulates this monadic behavior through its `#step` method and the overall structure of operations.
dry-operation emulates this monadic behavior through its `#step` method and the overall structure of operations.

In monadic terms, the `#step` method in `Dry::Operation` acts similarly to the `bind` operation:

Expand All @@ -24,7 +24,7 @@ This behavior allows for clean composition of operations while handling potentia

### Railway-oriented Programming

The design of `dry-operation` closely follows the concept of Railway-oriented Programming, a way of structuring code that's especially useful for dealing with a series of operations that may fail.
The design of dry-operation closely follows the concept of Railway-oriented Programming, a way of structuring code that's especially useful for dealing with a series of operations that may fail.

In this model:

Expand All @@ -34,4 +34,4 @@ In this model:

Each step is like a switch on the railway, potentially diverting from the success track to the failure track.

`dry-operation` implements this pattern by allowing the success case to continue down the method, while immediately returning any failure, effectively "switching tracks".
dry-operation implements this pattern by allowing the success case to continue down the method, while immediately returning any failure, effectively "switching tracks".
2 changes: 1 addition & 1 deletion docsite/source/error-handling.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ layout: gem-single
name: dry-operation
---

When using `dry-operation`, errors are handled through the `Failure` type from [`dry-monads`](/gems/dry-monads/). Each step in your operation should return either a `Success` or `Failure` result. When a step returns a `Failure`, the operation short-circuits, skipping the remaining steps and returning the failure immediately.
When using dry-operation, errors are handled through the `Failure` type from [dry-monads](/gems/dry-monads/). Each step in your operation should return either a `Success` or `Failure` result. When a step returns a `Failure`, the operation short-circuits, skipping the remaining steps and returning the failure immediately.

You'll usually handle the failure from the call site, where you can pattern match on the result to handle success and failure cases. However, sometimes it's useful to encapsulate some error handling logic within the operation itself.

Expand Down
11 changes: 6 additions & 5 deletions docsite/source/index.html.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,16 @@ sections:
- extensions
- design-pattern
---
`dry-operation` is a lightweight DSL that wraps around [`dry-monads`](/gems/dry-monads/), allowing you to chain operations with a focus on the happy path while elegantly handling failures.

dry-operation is a lightweight DSL that wraps around [dry-monads](/gems/dry-monads/), allowing you to chain operations with a focus on the happy path while elegantly handling failures.

### Introduction

In complex business logic, it's common to have a series of operations that depend on each other. Traditionally, this leads to deeply nested conditional statements or a series of guard clauses. `dry-operation` provides a more elegant solution by allowing you to define a linear flow of operations, automatically short-circuiting on failure.
In complex business logic, it's common to have a series of operations that depend on each other. Traditionally, this leads to deeply nested conditional statements or a series of guard clauses. dry-operation provides a more elegant solution by allowing you to define a linear flow of operations, automatically short-circuiting on failure.

### Basic Usage

To use `dry-operation`, create a class that inherits from `Dry::Operation` and define your flow in the `#call` method:
To use dry-operation, create a class that inherits from `Dry::Operation` and define your flow in the `#call` method:

```ruby
class CreateUser < Dry::Operation
Expand All @@ -44,15 +45,15 @@ class CreateUser < Dry::Operation
end
```

In this example, each step (`validate`, `persist`, `notify`) is expected to return either a `Success` or `Failure` from [`dry-monads`](/gems/dry-monads/).
In this example, each step (`validate`, `persist`, `notify`) is expected to return either a `Success` or `Failure` from [dry-monads](/gems/dry-monads/).

### The step method

The step method is the core of `Dry::Operation`. It does two main things:

- If the result is a `Success`, it unwraps the value and returns it.

- If the result is a `Failure`, it halts the execution throwing the failure up the call stack.
- If the result is a `Failure`, it halts the execution throwing the failure up the call stack.

This behavior allows you to write your happy path in a linear fashion, without worrying about handling failures at each step.

Expand Down

0 comments on commit 4ac0421

Please sign in to comment.