pathway 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2a1f9207d8b2db81dbf655234010e4cb8c622299cb69c1dfaa9486f824a7e86
-  data.tar.gz: 25e380e764a1b1585b86ae847b2cbc107a83fa23f1a1205e4e1e5e1a2c021c50
+  metadata.gz: 45170fed25a15c1d3b5b04630a9829a0a82d3a5f9423a3442445502252a1bb34
+  data.tar.gz: 424438af1eed0c2a93ca3be3dbe1923033f827809fa67d3b8aac31168402069e
 SHA512:
-  metadata.gz: 393014838fece86b27409c08ef0f5ccb9d7dacf5f5012d956bbf0e7ca3869175e4090c6dd23cf6c8f61bfcecd15839a738b87afcf911c226a06ea36e8cb91dc3
-  data.tar.gz: 1dd63c594d299837fb1b595f14fd2056ac39f81fdd508254c331fb9ef4b3a67262e0f47683bb5e0296708076d88c12aef0dd981c8864391d43f0bc6083ad9422
+  metadata.gz: 1a2c4671a9482af68487fa0298bd81cb93940906969e4cf3ecdf170f2332d4b5b988eb77653e71b095619bb1a9e70473a3a94a0eca6462e1aee4cb0d11d8fc88
+  data.tar.gz: d6dfa471b5d28317b23ae7e671cb1a12052ba11c02a52cd639e4635505c3843c4b7bddf84a7afb3af616bcaae2a067b3f622432d6bf623902b7c7be56a3daa87

data/.github/workflows/tests.yml

@@ -11,18 +11,19 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: [2.6, 2.7, 3.0, 3.1]
+        ruby-version: [2.6, 2.7, 3.0, 3.1, 3.2, 3.3]
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
+        bundler: '2.4.22'
         bundler-cache: true
     - name: Run tests
       run: bundle exec rake
     - name: Coveralls GitHub Action
-      if: matrix.ruby-version == '3.1'
-      uses: coverallsapp/github-action@1.1.3
+      if: matrix.ruby-version == '3.2'
+      uses: coverallsapp/github-action@v2
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}

data/CHANGELOG.md

@@ -1,6 +1,12 @@
+## [0.12.1] - 2024-06-23
+### Added
+- Add support for pattern matching on `Result`, `State` and `Error` instances
+- Add `Pathway::Result::Mixin` to allow easy constant lookup for `Result::Success` and `Result::Failure`
+
 ## [0.12.0] - 2022-05-31
 ### Changed
 - Improve compatibility with Ruby 3.0
+### Added
 - Add plugin `:auto_deconstruct_state` to help migrating old apps to Ruby 3.0
 
 ## [0.11.3] - 2020-07-22
@@ -16,7 +22,7 @@
 - Improve custom `rspec` matchers for testing field presence on schemas
 
 ## [0.11.0] - 2020-01-02
-### Changed
+### Added
 - Add support for `dry-validation` 1.0 and above
 
 ## [0.10.0] - 2019-10-06

data/README.md

@@ -12,22 +12,28 @@ Pathway encapsulates your business logic into simple operation objects (AKA appl
 
 ## Description
 
-Pathway helps you separate your business logic from the rest of your application; regardless if is an HTTP backend, a background processing daemon, etc.
-The main concept Pathway relies upon to build domain logic modules is the operation, this important concept will be explained in detail the following sections.
+Pathway helps you separate your business logic from the rest of your application; regardless of is an HTTP backend, a background processing daemon, etc.
+The main concept Pathway relies upon to build domain logic modules is the operation, this important concept will be explained in detail in the following sections.
 
-Pathway also aims to be easy to use, stay lightweight and extensible (by the use of plugins), avoid unnecessary dependencies, keep the core classes clean from monkey patching and help yielding an organized and uniform codebase.
+Pathway also aims to be easy to use, stay lightweight and extensible (by the use of plugins), avoid unnecessary dependencies, keep the core classes clean from monkey patching and help yield an organized and uniform codebase.
+
+<!--
+## Migrating to Ruby 3.x
+
+TODO: small comment and link to `auto_deconstruct_state` plugin
+-->
 
 ## Usage
 
 ### Main concepts and API
 
-As mentioned earlier the operation is a crucial concept Pathway leverages upon. Operations not only structure your code (using steps as will be explained later) but also express meaningful business actions. Operations can be thought as use cases too: they represent an activity -to be perform by an actor interacting with the system- which should be understandable by anyone familiar with the business regardless of their technical expertise.
+As mentioned earlier the operation is an essential concept Pathway is built around. Operations not only structure your code (using steps as will be explained later) but also express meaningful business actions. Operations can be thought of as use cases too: they represent an activity -to be performed by an actor interacting with the system- which should be understandable by anyone familiar with the business regardless of their technical expertise.
 
-Operations should ideally don't contain any business rules but instead orchestrate and delegate to other more specific subsystems and services. The only logic present then should be glue code or any adaptations required to make interactions with the inner system layers possible.
+Operations shouldn't ideally contain any business rules but instead, orchestrate and delegate to other more specific subsystems and services. The only logic present then should be glue code or any data transformations required to make interactions with the inner system layers possible.
 
 #### Function object protocol (the `call` method)
 
-Operations works as function objects, they are callable and hold no state, as such, any object that responds to `call` and returns a result object can be a valid operation and that's the minimal protocol they needs to follow.
+Operations work as function objects, they are callable and hold no state, as such, any object that responds to `call` and returns a result object can be a valid operation and that's the minimal protocol they need to follow.
 The result object must follow its protocol as well (and a helper class is provided for that end) but we'll talk about that in a minute.
 
 Let's see an example:
@@ -53,30 +59,28 @@ else
 end
 ```
 
-Note first we are not inheriting from any class nor including any module. This won't be the case in general as `pathway` provides classes to help build your operations, but it serves to illustrate how little is needed to implement one.
+Note first, we are not inheriting from any class nor including any module. This won't be the case in general as `pathway` provides classes to help build your operations, but it serves to illustrate how little is needed to implement one.
 
-Also, let's ignore the specifics about `Repository.create(...)`, we just need to know that is some backend service which can return a value.
+Also, let's ignore the specifics about `Repository.create(...)`, we just need to know that is some backend service from which a value is returned.
 
 
-We then define a `call` method for the class. It only checks if the result is available and then wrap it into a successful `Result` object when is ok, or a failing one when is not.
-And that is all is needed, you can then call the operation object, check whether it was completed correctly with `success?` and get the resulting value.
+We then define a `call` method for the class. It only checks if the result is available and then wraps it into a successful `Result` object when is ok, or a failing one when is not.
+And basically, that's all is needed, you can then call the operation object, check whether it was completed correctly with `success?` and get the resulting value.
 
-By following this protocol, you will be able to uniformly apply the same pattern on every HTTP endpoint (or whatever means your app has to communicates with the outside world). The upper layer of the application will offload all the domain logic to the operation and only will need to focus on the HTTP transmission details.
+By following this protocol, you will be able to uniformly apply the same pattern on every HTTP endpoint (or whatever means your app has to communicate with the outside world). The upper layer of the application will offload all the domain logic to the operation and only will need to focus on the HTTP transmission details.
 
 Maintaining always the same operation protocol will also be very useful when composing them.
 
-
 #### Operation result
 
-As should be evident by now an operation should always return either a successful or failed result. This concepts are represented by following a simple protocol, which `Pathway::Result` subclasses comply.
+As should be evident by now an operation should always return either a successful or failed result. These concepts are represented by following a simple protocol, which `Pathway::Result` subclasses comply with.
 
-As we seen before, by querying `success?` on the result we can see if the operation we just ran went well, or you can also call to `failure?` for a negated version.
+As we've seen before, by querying `success?` on the result we can see if the operation we just ran went well, or call to `failure?` to see if it failed.
 
 The actual result value produced by the operation is accessible at the `value` method and the error description (if there's any) at `error` when the operation fails.
-To return wrapped values or errors from your operation you must call to `Pathway::Result.success(value)` or `Pathway::Result.failure(error)`.
-
-It is worth mentioning that when you inherit from `Pathway::Operation` you'll have helper methods at your disposal to create result objects easier, for instance the previous section's example could be written as follows:
+To return wrapped values or errors from your operation you must call `Pathway::Result.success(value)` or `Pathway::Result.failure(error)`.
 
+It is worth mentioning that when you inherit from `Pathway::Operation` you'll have helper methods at your disposal to create result objects easily. For instance, the previous section's example could be written as follows:
 
 ```ruby
 class MyFirstOperation < Pathway::Operation
@@ -90,8 +94,8 @@ end
 
 #### Error objects
 
-`Pathway::Error` is a helper class to represent the error description from an failed operation execution (and can be used also for pattern matching as we'll see later).
-Its use is completely optional, but provides you with a basic schema to communicate what when wrong. You can instantiate it by calling `new` on the class itself or using the helper method `error` provided by the operation class:
+`Pathway::Error` is a helper class to represent the error description from a failed operation execution (and also supports pattern matching as we'll see later).
+Its use is completely optional but provides you with a basic schema to communicate what went wrong. You can instantiate it by calling `new` on the class itself or using the helper method `error` provided by the operation class:
 
 ```ruby
 class CreateNugget < Pathway::Operation
@@ -125,11 +129,11 @@ If you decide to use `Pathway::Error.new(...)` directly, you will have to pass a
 
 #### Initialization context
 
-It was previously mentioned that operations should work like functions, that is, they don't hold state and you should be able to execute the same instance all the times you need, on the other hand there will be some values that won't change during the operation life time and won't make sense to pass as `call` parameters, you can provide these values on initialization as context data.
+It was previously mentioned that operations should work like functions, that is, they don't hold state and you should be able to execute the same instance all the times you need, on the other hand, there will be some values that won't change during the operation lifetime and won't make sense to pass as `call` parameters, you can provide these values on initialization as context data.
 
-Context data can be thought as 'request data' on an HTTP endpoint, values that aren't global but won't change during the executing of the request. Examples of this kind of data are the current user, the current device, a CSRF token, other configuration parameters, etc. You will want to pass this values on initialization, and probably pass them along to other operations down the line.
+Context data can be thought of as 'request data' on an HTTP endpoint, values that aren't global but won't change during the execution of the request. Examples of this kind of data are the current user, the current device, a CSRF token, other configuration parameters, etc. You will want to pass these values on initialization, and probably pass them along to other operations down the line.
 
-You must define your initializer to accept a `Hash` with this values, which is what every operation is expected to do, but as before, when inheriting from `Operation` you have the helper class method `context` handy to make it easier for you:
+You must define your initializer to accept a `Hash` with these values, which is what every operation is expected to do, but as before, when inheriting from `Operation` you have the helper class method `context` handy to make it easier for you:
 
 ```ruby
 class CreateNugget < Pathway::Operation
@@ -154,9 +158,9 @@ op = CreateNugget.new(current_user: user)
 op.call(foo: 'foobar')
 ```
 
-On the example above `context` is defining `:current_user` as a mandatory argument (it will raise an error if not provided) and `:notify` as an optional config argument, since it has a default value. Note that any extra non-defined value provided will be simply ignored.
+In the example above `context` is defining `:current_user` as a mandatory argument (it will raise an error if not provided) and `:notify` as an optional config argument, since it has a default value. Note that any extra non-defined value provided will be simply ignored.
 
-Both of these parameters are available through accessors (and instance variables) inside the operation. Also there is a `context` private method you use to get all the initialization values as a frozen hash, in order to pass then along easily.
+Both of these parameters are available through accessors (and instance variables) inside the operation. Also, there is a `context` private method you use to get all the initialization values as a frozen hash, in order to pass them along easily.
 
 #### Alternative invocation syntax
 
@@ -168,24 +172,23 @@ context = { current_user: user }
 
 CreateNugget.call(context, params[:nugget]) # Using 'call' on the class
 ```
-
-Also you have Ruby's alternative syntax to invoke the `call` method: `CreateNugget.(context, params[:nugget])`. On any case you'll get the operation result like when invoking `call` on the operation's instance.
+Also, you have Ruby's alternative syntax to invoke the `call` method: `CreateNugget.(context, params[:nugget])`. In both cases, you'll get the operation result like when invoking `call` on the operation's instance.
 
 Mind you that a context must always be provided for this syntax, if you don't need any initialization use an empty hash.
 
-There's also third way to execute an operation, made available through a plugin, and will be explained later.
+There's also a third way to execute an operation, made available through a plugin, that will be explained later.
 
 #### Steps
 
-Finally the steps, these are the heart of the `Operation` class and the main reason you will want to inherit your own classes from `Pathway::Operation`.
+Finally, the steps are the heart of the `Operation` class and the main reason you will want to inherit your own classes from `Pathway::Operation`.
 
-So far we know that every operation needs to implement a `call` method and return a valid result object, `pathway` provides another option: the `process` block DSL, this method will define `call` behind the scenes for us, while also providing a way to define a business oriented set of steps to describe our operation's behavior.
+So far we know that every operation needs to implement a `call` method and return a valid result object, `pathway` provides another option: the `process` block DSL, this method will define `call` behind the scenes for us, while also providing a way to define a business-oriented set of steps to describe our operation's behavior.
 
-Every step should be cohesive and focused on a single responsibly, ideally by offloading work to other subsystems. Designing steps this way is the developer's responsibility, but is made much simpler by the use of custom steps provided by plugins as we'll see later.
+Every step should be cohesive and focused on a single responsibility, ideally by offloading work to other subsystems. Designing steps this way is the developer's responsibility but is made much simpler by the use of custom steps provided by plugins as we'll see later.
 
 ##### Process DSL
 
-Lets start by showing some actual code:
+Let's start by showing some actual code:
 
 ```ruby
 # ...
@@ -199,44 +202,48 @@ Lets start by showing some actual code:
 # ...
 ```
 
-To define your `call` method using the DSL just call to `process` and pass a block, inside it the DSL will be available.
-Each `step` (or `set`) call is referring to a method inside the operation class, superclasses or available through a plugin, these methods will be eventually invoked by `call`.
+To define your `call` method using the DSL just call to `process` and pass a block, inside it, the DSL will be available.
+Each `step` (or `set`) call is referring to a method inside the operation class, superclasses, or available through a plugin, these methods will be eventually invoked by `call`.
 All of the steps constitute the operation use case and follow a series of conventions in order to carry the process state along the execution process.
 
-When you run the `call` method, the auto-generated code will save the provided argument at the `input` key within the execution state. Subsequent steps will receive this state and will be able to modify it, setting the result value or auxiliary keys to communicate with the next steps on the execution path.
+When you run the `call` method, the auto-generated code will save the provided argument at the `input` key within the execution state. Subsequent steps will receive this state and will be able to modify it, setting the result or auxiliary values, in order to communicate with the next steps on the execution path.
 
-Each step (as the operation as whole) can succeed of fail, when the latter happens execution is halted, and the operation `call` method returns immediately.
+Each step (as the operation as a whole) can succeed or fail, when the latter happens execution is halted, and the operation `call` method returns immediately.
 To signal a failure you must return a `failure(...)` or `error(...)` in the same fashion as when defining `call` directly.
 
-If you return a `success(...)` or anything that's not a failure the execution carries on but the value is ignored. If you want to save the result value, you must use `set` instead of `step` at the process block, that will save your wrapped value, into the key provided at `to:`.
-Also non-failure return values inside steps are automatically wrapped so you can use `success` for clarity sake but it's optional.
+If you return a `success(...)` or anything that's not a failure the execution carries on but the value is ignored. If you want to save the result value, you must use `set` instead of `step` at the process block, which will save your wrapped value, into the key provided at `to:`.
+Also, non-failure return values inside steps are automatically wrapped so you can use `success` for clarity's sake but it's optional.
 If you omit the `to:` keyword argument when defining a `set` step, the result key will be used by default, but we'll explain more on that later.
 
 ##### Operation execution state
 
-In order to operate with the execution state, every step method receives a structure representing the current state. This structure is similar to a `Hash` and responds to its main methods (`:[]`, `:[]=`, `:fetch`, `:store`, `:include?` and `to_hash`).
+To operate with the execution state, every step method receives a structure representing the current state. This structure is similar to a `Hash` and responds to its main methods (`:[]`, `:[]=`, `:fetch`, `:store`, `:include?` and `to_hash`).
 
 When an operation is executed, before running the first step, an initial state is created by copying all the values from the initialization context (and also including `input`).
-Note that these values can be replaced on later steps but it won't mutate the context object itself since is always frozen.
+Note that these values can be replaced in later steps but it won't mutate the context object itself since is always frozen.
 
-A state object can be splatted on method definition in the same fashion as a `Hash`, thus, allowing to cherry pick the attributes we are interested on any given step:
+A state object can be splatted on method definition in the same fashion as a `Hash`, thus, allowing us to cherry-pick the attributes we are interested in any given step:
 
 ```ruby
 # ...
   # This step only takes the values it needs and doesn't change the state.
-  def send_emails(user:, report:, **)
+  def send_emails(state)
+    user, report = state[:user], state[:report]
     ReportMailer.send_report(user.email, report)
   end
 # ...
 ```
+<!--
+TODO: explain Ruby 2.7 and 3.0 state deconstruction alternatives
 
 Note the empty double splat at the end of the parameter list, this Ruby-ism means: grab the mentioned keys and ignore all the rest. If you omit the `**` when you have outstanding keys, Ruby's `Hash` destructing will fail.
+-->
 
 ##### Successful operation result
 
-On each step you can access or change the operation result for a successful execution.
+On each step, you can access or change the result the operation will produce on a successful execution.
 The value will be stored at one of the attributes within the state.
-By default the state's key `:value` will hold the result, but if you prefer to use another name you can specify it through the `result_at` operation class method.
+By default, the state's key `:value` will hold the result, but if you prefer to use another name you can specify it through the `result_at` operation class method.
 
 ##### Full example
 
@@ -271,36 +278,36 @@ class CreateNugget < Pathway::Operation
     end
   end
 
-  def create_nugget(:params, **)
-    Nugget.create(owner: current_user, **params)
+  def create_nugget(state)
+    Nugget.create(owner: current_user, **state[:params])
   end
 
-  def notify(:nugget, **)
-    Notifier.notify(:new_nugget, nugget)
+  def notify(state)
+    Notifier.notify(:new_nugget, state[:nugget])
   end
 end
 ```
 
-The example above the operation will produce a nugget (whatever that is...).
+In the example above the operation will produce a nugget (whatever that is...).
 
-As you can see in the code, we are using the previously mentioned methods to indicate we need a current user to be present on initialization: `context: current_user`, a `call` method (defined by `process do ... end`), and that the result value should be stored at the `:nugget` key (`result_at :nugget`).
+As you can see in the code, we are using the previously mentioned methods to indicate we need the current user to be present on initialization: `context: current_user`, a `call` method (defined by `process do ... end`), and the result value should be stored at the `:nugget` key (`result_at :nugget`).
 
-Lets delve into the `process` block: it defines three steps using the `step` method and `create_nugget` using `set`, as we said before, this last step will set the result key (`:nugget`) since the `to:` keyword argument is absent.
+Let's delve into the `process` block: it defines three steps using the `step` method and `create_nugget` using `set`, as we said before, this last step will set the result key (`:nugget`) since the `to:` keyword argument is absent.
 
 Now, for each of the step methods:
 
-- `:authorize` doesn't need the state so just ignores it, then checks if the current user is allowed to perform the operation and halts the execution by returning a `:forbidden` error type if is not, otherwise does nothing and the execution goes on.
+- `:authorize` doesn't need the state so just ignores it, then checks if the current user is allowed to run the operation and halts the execution by returning a `:forbidden` error type if is not, otherwise does nothing and the execution goes on.
 - `:validate` gets the state, checks the validity of the `:input` value which as we said is just the `call` method input, returns an `error(...)` when there's a problem, and if the validation is correct it updates the state but saving the sanitized values in `:params`. Note that on success the return value is `state[:params]`, but is ignored like on `:authorize`, since this method was also specified using `step`.
-- `:create_nugget` first takes the `:params` attribute from the state (ignoring everything else), and calls `create` on the `Nugget` model with the sanitized params and the current user. The return value is saved to the result key (`:nugget` in this case) as the step is defined using `step` without `to:`.
+- `:create_nugget` first takes the `:params` attribute from the state, and calls `create` on the `Nugget` model with the sanitized params and the current user. The return value is saved to the result key (`:nugget` in this case) as the step is defined using `step` without `to:`.
 - `:notify` grabs the `:nugget` from the state, and simply emits a notification with it, it has no meaningful return value, so is ignored.
 
-This example basically touches all the essential concepts needed for defining an operation class. If you can grasp it you've already a good understanding on how to implement one. There are still some very important bits to cover (like testing), and we'll tackle them on later sections.
+The previous example goes through all the essential concepts needed for defining an operation class. If you can grasp it, you already have a good understanding on how to implement one. There are still some very important bits to cover (like testing), and we'll tackle them in the latter sections.
 
-On a final note, you may be thinking the code could be bit less verbose; also, shouldn't very common stuff like validation or authorization be simpler to use?; and maybe, why specify the result key name?, it could be possible infer it from the surrounding code. We will address all those issues on the next section using plugins, `pathway`'s extension mechanism.
+On a final note, you may be thinking the code could be a bit less verbose; also, shouldn't very common stuff like validation or authorization be simpler to use? and why always specify the result key name? maybe is possible to infer it from the surrounding code. We will address all those issues in the next section using plugins, `pathway`'s extension mechanism.
 
 ### Plugins
 
-Pathway operations can be extended with plugins. They are very similar as the ones found in [Roda](http://roda.jeremyevans.net/) or [Sequel](http://sequel.jeremyevans.net/). So if you are already familiar with any of those gems you shouldn't have any problem with `pathway`'s plugin system.
+Pathway operations can be extended with plugins. They are very similar to the ones found in [Roda](http://roda.jeremyevans.net/) or [Sequel](http://sequel.jeremyevans.net/). So if you are already familiar with any of those gems you shouldn't have any problem with `pathway`'s plugin system.
 
 To activate a plugin just call the `plugin` method on the operation class:
 
@@ -321,9 +328,9 @@ Mind you, if you wish to activate a plugin for a number of operations you can ac
 
 #### `DryValidation` plugin
 
-This plugin provides integration with the [dry-validation](http://dry-rb.org/gems/dry-validation/) gem. I won't explain in detail how to use this library since is already extensively documented on its official website, but instead I'll assume certain knowledge of it, nonetheless, as you'll see in a moment, its API pretty self-explanatory.
+This plugin provides integration with the [dry-validation](http://dry-rb.org/gems/dry-validation/) gem. I won't explain in detail how to use this library since is already extensively documented on its official website, but instead, I'll assume certain knowledge of it, nonetheless, as you'll see in a moment, its API is pretty self-explanatory.
 
-`dry-validation` provides a very simple way to define contract objects (conceptually very similar to form objects) to process and validate input. The provided custom `:validate` step allows you to run your input though a contract to check if your data is valid before carrying on. When the input is invalid it will return an error object of type `:validation` and the reasons the validation failed will be available at the `details` attribute. Is usually the first step an operation runs.
+`dry-validation` provides a very simple way to define contract objects (conceptually very similar to form objects) to process and validate input. The provided custom `:validate` step allows you to run your input through a contract to check if your data is valid before carrying on. When the input is invalid it will return an error object of type `:validation` and the reasons the validation failed will be available at the `details` attribute. Is usually the first step an operation runs.
 
 When using this plugin we can provide an already defined contract to the step to use or we can also define it within the operation.
 Let's see a few examples:
@@ -350,7 +357,7 @@ class CreateNugget < Pathway::Operation
 end
 ```
 
-As is is shown above, the contract is defined first, then is configured it will be used by the operation by calling `contract NuggetContract`, and validate the input at the process block by placing the step `step :validate` inside the `process` block.
+As is shown above, the contract is defined first, then configured to be used by the operation by calling `contract NuggetContract`, and validate the input at the process block by placing the step `step :validate` inside the `process` block.
 
 ```ruby
 class CreateNugget < Pathway::Operation
@@ -372,11 +379,11 @@ class CreateNugget < Pathway::Operation
 end
 ```
 
-Now, this second example is equivalent to the first one, but here we call `contract` with a block instead and no parameter; this block will be used as definition body for a contract class that will be stored internally. Thus keeping the contract and operation code at the same place, this is convenient when you have a rather simpler contract and don't need to reuse it.
+Now, this second example is equivalent to the first one, but here we call `contract` with a block instead of an object parameter; this block will be used as the definition body for a contract class that will be stored internally. Thus keeping the contract and operation code in the same place, this is convenient when you have a rather simpler contract and don't need to reuse it.
 
 One interesting nuance to keep in mind regarding the inline block contract is that, when doing operation inheritance, if the parent operation already has a contract, the child operation will define a new one inheriting from the parent's. This is very useful to share validation logic among related operations in the same class hierarchy.
 
-As a side note, if your contract is simple enough and only have params, you can call the `params` method directly instead, the following code is essentially equivalent to previous example:
+As a side note, if your contract is simple enough and has parameters and not extra validations rules, you can call the `params` method directly instead, the following code is essentially equivalent to the previous example:
 
 ```ruby
 class CreateNugget < Pathway::Operation
@@ -400,7 +407,7 @@ end
 
 If you are familiar with `dry-validation` you probably know it provides a way to [inject options](https://dry-rb.org/gems/dry-validation/1.4/external-dependencies/) before calling the contract.
 
-On those scenarios you must either use the `auto_wire_options: true` plugin argument, or specify how to map options from the execution state to the contract when calling `step :validate`.
+In those scenarios, you must either set the `auto_wire_options: true` plugin argument or specify how to map options from the execution state to the contract when calling `step :validate`.
 Lets see and example for the first case:
 
 ```ruby
@@ -465,11 +472,11 @@ class CreateNugget < Pathway::Operation
 end
 ```
 
-The `with:` parameter can always be specified, at `step :validate`, and allows you to override the default mapping regardless if auto-wiring is active or not.
+The `with:` parameter can always be specified for `step :validate`, and allows you to override the default mapping regardless if auto-wiring is active or not.
 
 ##### Older versions of `dry-validation`
 
-Pathway supports the `dry-validation` gem down to version `0.11` (inclusive) in case you still have unmigrated code. When using versions bellow `1.0` the concept of contract is not present and instead of calling the `contract` method to setup your validation logic you must use the `form` method. Everything else remains the same except, obviously, that you would have to use `dry-definition`'s [old API](https://dry-rb.org/gems/dry-validation/0.13/) which is a bit different from the current one.
+Pathway supports the `dry-validation` gem down to version `0.11` (inclusive) in case you still have unmigrated code. When using versions below `1.0` the concept of contract is not present and instead of calling the `contract` method to set up your validation logic, you must use the `form` method. Everything else remains the same except, obviously, that you would have to use `dry-definition`'s [old API](https://dry-rb.org/gems/dry-validation/0.13/) which is a bit different from the current one.
 
 #### `SimpleAuth` plugin
 
@@ -495,7 +502,7 @@ end
 
 #### `SequelModels` plugin
 
-The `sequel_models` plugin helps integrating operations with the [Sequel](http://sequel.jeremyevans.net/) ORM, by adding a few custom steps.
+The `sequel_models` plugin helps integrate operations with the [Sequel](http://sequel.jeremyevans.net/) ORM, by adding a few custom steps.
 
 This plugin expects you to be using `Sequel` model classes to access your DB. In order to exploit it, you need to indicate which model your operation is going to work with, hence you must specify said model when activating the plugin with the `model:` keyword argument, or later using the `model` class method.
 This configuration will then be used on the operation class and all its descendants.
@@ -520,15 +527,15 @@ class MyOperation < Pathway::Operation
 end
 ```
 
-As you can see above you can also customize the search field (`:search_by`) and indicate if you want to override the result key (`:set_result_key`) when calling to `model`.
-These two options aren't mandatory, and by default Pathway will set the search field to the class model primary key, and override the result key to a snake cased version of the model name (ignoring namespaces if contained inside a class or module).
+As you can see above you can also customize the search field (`:search_by`) and indicate if you want to override or not the result key (`:set_result_key`) when calling the `model` method.
+These two options aren't mandatory, and by default, Pathway will set the search field to the class model primary key, and override the result key to a snake-cased version of the model name (ignoring namespaces if contained inside a class or module).
 
 Let's now take a look at the provided extensions:
 
 ##### `:fetch_model` step
 
 This step will fetch a model from the DB, by extracting the search field from the `call` method input parameter stored at `:input` in the execution state. If the model cannot be fetched from the DB it will halt the execution with a `:not_found` error, otherwise it will simply save the model into the result key (which will be `:nugget` for the example below).
-You can latter access the fetched model from that attribute and if the operation finish successfuly, it will be the operation result.
+You can later access the fetched model from that attribute and if the operation finishes successfully, it will be used as its result.
 
 ```ruby
 class UpdateNugget < Pathway::Operation
@@ -545,11 +552,11 @@ class UpdateNugget < Pathway::Operation
 end
 ```
 
-As a side note, and as shown on the 3rd step, `:fetch_model` allows you to override the search column (`search_by:`), the input parameter to extract from `input` (`using:`), the attribute to store the result (`to:`) and even the default search class (`from:`). If the current defaults doesn't fit your needs and you'll have these options available. This is commonly usefuly when you need some extra object, besides the main one, to execute your operation.
+As a side note, and as shown in the 3rd step, `:fetch_model` allows you to override the search column (`search_by:`), the input parameter to extract from `input` (`using:`), the attribute to store the result (`to:`) and even the default search class (`from:`). If the current defaults don't fit your needs and you'll have these options available. This is commonly useful when you need some extra object, besides the main one, to execute your operation.
 
 ##### `transaction` and `after_commit`
 
-These two are bit special since they aren't actually custom steps but just new methods that extend the process DSL itself.
+These two are a bit special since they aren't actually custom steps but just new methods that extend the process DSL itself.
 These methods will take a block as an argument within which you can define inner steps.
 Keeping all that in mind the only thing `transaction` and `after_commit` really do is surround the inner steps with `SEQUEL_DB.transaction { ... }` and `SEQUEL_DB.after_commit { ... }` blocks, respectively.
 
@@ -572,17 +579,17 @@ class CreateNugget < Pathway::Operation
 end
 ```
 
-When won't get into the details for each step in the example above, but the important thing to take away is that `:create_nugget` and `:attach_history_note` will exists withing a single transaction and `send_mails` (and any steps you add in the `after_commit` block) will only run after the transaction has finished successfuly.
+When won't get into the details for each step in the example above, but the important thing to take away is that `:create_nugget` and `:attach_history_note` will exists within a single transaction and `send_mails` (and any steps you add in the `after_commit` block) will only run after the transaction has finished successfully.
 
 Another nuance to take into account is that calling `transaction` will start a new savepoint, since, in case you're already inside a transaction, it will be able to properly notify that the transaction failed by returning an error object when that happens.
 
 #### `Responder` plugin
 
-This plugin extend the `call` class method on the operation in order to accept a block. You can then use this block for flow control on success and failure and to pattern match different type of errors.
+This plugin extends the `call` class method on the operation to accept a block. You can then use this block for flow control on success, failure, and also different types of failures.
 
-There are two way to use this plugin: by discriminating between success and failure, and when by also discriminating according to the specific failure reason.
+There are two ways to use this plugin: by discriminating between success and failure, and also discriminating according to the specific failure type.
 
-On each case you must provide the action to execute for every outcome using blocks:
+In each case you must provide the action to execute for every outcome using blocks:
 
 ```ruby
 MyOperation.plugin :responder # 'plugin' is actually a public method
@@ -592,10 +599,18 @@ MyOperation.(context, params) do
   failure { |error| r.halt(403) }
 end
 ```
+<!--
+```ruby
+case MyOperation.(context, params)
+in Success(value) then r.halt(200, value.to_json)
+in Failure(_)     then r.halt(403)
+end
+```
+-->
 
-On example above we provide a block for both the success and the failure case. On each block the result value or the error object error will be provided at the blocks' argument, the result of corresponding block will be the result of the whole expression.
+In the example above we provide a block for both the success and the failure case. On each block, the result value or the error object error will be provided at the blocks' argument, and the result of the corresponding block will be the result of the whole expression.
 
-Lets now show an example with pattern matching:
+Lets now show an example with the error type specified:
 
 ```ruby
 MyOperation.plugin :responder
@@ -607,19 +622,34 @@ MyOperation.(context, params) do
   failure(:not_found)  { |error| r.halt(404) }
 end
 ```
+<!--
+```ruby
+case MyOperation.(context, params)
+in Success(value)                       then r.halt(200, value.to_json)
+in Failure(type: :forbidden)            then r.halt(403)
+in failure(type: :validation, details:) then r.halt(422, details.to_json)
+in failure(type: :not_found)            then r.halt(404)
+end
+```
+-->
+
+As you can see is almost identical to the previous example only that this time you provide the error type on each `failure` call.
 
-As you can see is almost identical as the previous example only that this time you provide the error type on each `failure` call.
+<!--
+#### `AutoDeconstructState` plugin
 
+TODO: Explain reason, how to migrate, how to activate
+-->
 ### Plugin architecture
 
-Going a bit deeper now, we'll explain how to implement your own plugins. As was mention before `pathway` follows a very similar approach to the [Roda](http://roda.jeremyevans.net/) or [Sequel](http://sequel.jeremyevans.net/) plugin systems, which is reflected on its implementation.
+Going a bit deeper now, we'll explain how to implement your own plugins. As was mentioned before `pathway` follows a very similar approach to the [Roda](http://roda.jeremyevans.net/) or [Sequel](http://sequel.jeremyevans.net/) plugin systems, which is reflected at its implementation.
 
-Each plugin must be defined in a file placed within the `pathway/plugins/` directory of your gem or application, so `pathway` can require the file; and must be implemented as a module inside the `Pathway::Plugins` namespace module. Inside your plugin module, three extra modules can be define to extend the operation API `ClassMethods`, `InstanceMethods` and `DSLMethods`; plus a class method `apply` for plugin initialization when needed.
+Each plugin must be defined in a file placed within the `pathway/plugins/` directory of your gem or application, so `pathway` can require the file; and must be implemented as a module inside the `Pathway::Plugins` namespace module. Inside your plugin module, three extra modules can be defined to extend the operation API `ClassMethods`, `InstanceMethods` and `DSLMethods`; plus a class method `apply` for plugin initialization when needed.
 
-If you are familiar with the aforementioned plugin mechanism (or other as well), the function of each module is probably starting to feel evident: `ClassMethods` will be used to extend the operation class, so any class methods should be defined here; `InstanceMethods` will be included on the operation so all the instance methods you need to add to the operation should be here, this include every custom step you need to add; and finally `DSLMethods` will be included on the `Operation::DSL` class, which holds all the DSL methods like `step` or `set`.
+If you are familiar with the aforementioned plugin mechanism (or others as well), the function of each module is probably starting to feel evident: `ClassMethods` will be used to extend the operation class, so any class methods should be defined here; `InstanceMethods` will be included on the operation so all the instance methods you need to add to the operation should be here, this includes every custom step you need to add; and finally `DSLMethods` will be included on the `Operation::DSL` class, which holds all the DSL methods like `step` or `set`.
 The `apply` method will simply be run whenever the plugin is included, taking the operation class on the first argument and all then arguments the call to `plugin` received (excluding the plugin name).
 
-Lets explain with more detail using a complete example:
+Let's explain with more detail using a complete example:
 
 ```ruby
 # lib/pathway/plugins/active_record.rb
@@ -678,31 +708,31 @@ end
 The code above implements a plugin to provide basic interaction with the [ActiveRecord](http://guides.rubyonrails.org/active_record_basics.html) gem.
 Even though is a very simple plugin, it shows all the essentials to develop more complex ones.
 
-As is pointed out in the code, some of the methods implemented here (`fetch_model` and `transmission`) collide with methods defined for `:sequel_models`, so as a consequence, these two plugin's are not compatible with each other and cannot be activated for the same operation (although you can still do it for different operations within the same application).
-You must be mindful about colliding method names when mixing plugins, since `Pathway` can't bookkeep compatibility among every plugin that exists of will ever exist.
+As is pointed out in the code, some of the methods implemented here (`fetch_model` and `transmission`) collide with methods defined for `:sequel_models`, so as a consequence, these two plugins are not compatible with each other and cannot be activated for the same operation (although you can still do it for different operations within the same application).
+You must be mindful about colliding method names when mixing plugins since `Pathway` can't bookkeep compatibility among every plugin that exists or will ever exist.
 Is a good practice to document known incompatibilities on the plugin definition itself when they are known.
 
-The whole plugin is completely defined within the `ActiveRecord` module inside the `Pathway::Plugins` namespace, also the file is placed at the load path in `pathway/plugin/active_record.rb` (assuming `lib/` is listed in `$LOAD_PATH`). This will ensure, when calling `plugin :active_record` inside an operation, the correct file will be loaded and the correct plugin module will be applied to the current operation.
+The whole plugin is completely defined within the `ActiveRecord` module inside the `Pathway::Plugins` namespace, also the file is placed at the load path in `pathway/plugin/active_record.rb` (assuming `lib/` is listed in `$LOAD_PATH`). This will ensure when calling `plugin :active_record` inside an operation, the correct file will be loaded and the correct plugin module will be applied to the current operation.
 
 Moving on to the `ClassMethods` module, we can see the accessors `model` and `pk` are defined for the operation's class to allow configuration.
-Also, the `inherited` hook is defined, this will simply be another class method at the operation and as such will be executed normally when the operation class is inherited. In our implementation we just call to `super` (which is extremely important since other modules or parent classes could be using this hook), and then copy the `model` and `pk` options from the parent to the subclass in order to propagate the configuration downwards.
+Also, the `inherited` hook is defined, this will simply be another class method at the operation and as such will be executed normally when the operation class is inherited. In our implementation, we just call to `super` (which is extremely important since other modules or parent classes could be using this hook) and then copy the `model` and `pk` options from the parent to the subclass in order to propagate the configuration downwards.
 
-At the end of the `ActiveRecord` module definition you can see the `apply` method. It will receive the operation class and the parameters passed when the `plugin` method is invoked. This method is usually used for loading dependencies of just setting up config parameters as we do in this particular example.
+At the end of the `ActiveRecord` module definition, you can see the `apply` method. It will receive the operation class and the parameters passed when the `plugin` method is invoked. This method is usually used for loading dependencies or just setting up config parameters as we do in this particular example.
 
-`InstanceMethods` first defines a few delegator methods to the class itself to use later.
-Then the `fetch_model` step is defined (remember steps are but operation instance methods). Its first parameter is the state itself, as in the other steps we've seen before, and the remaining parameters are the options we can pass when calling `step :fetch_model` (mind you, this is also valid for steps defined in operations classes). Here we only take a single keyword argument: `column: pk`, with a default value; this will allow us to change the look up column when using the step, and is the only parameter we can use, passing other keyword arguments or extra positional parameters when invoking the step will raise errors.
+`InstanceMethods` first defines a few delegator methods to the class itself for later use.
+Then the `fetch_model` step is defined (remember steps are but operation instance methods). Its first parameter is the state itself, as in the other steps we've seen before, and the remaining parameters are the options we can pass when calling `step :fetch_model` (mind you, this is also valid for steps defined in operations classes). Here we only take a single keyword argument: `column: pk`, with a default value; this will allow us to change the look-up column when using the step and is the only parameter we can use, passing other keyword arguments or extra positional parameters when invoking the step will raise errors.
 
-Let's now examine the `fetch_model` step body, is not really that much different from other steps, here we extract the model primary key from `state[:input][column]` and use it to perform a search. If nothing is found an error is returned, otherwise the state is updated on the result key to hold the model we just fetched from the DB.
+Let's now examine the `fetch_model` step body, it's not really that much different from other steps, here we extract the model primary key from `state[:input][column]` and use it to perform a search. If nothing is found an error is returned, otherwise the state is updated in the result key, to hold the model that was just fetched from the DB.
 
 We finally see a `DSLMethods` module defined to extend the process DSL.
-For this plugin we'll define a way to group steps within an `ActiveRecord` transaction, much in the same way the `:sequel_models` plugin already does for `Sequel`.
-To this end we define a `transaction` method to expect a steps block and pass it down to the `around` helper below which expects a callable (like a `Proc`) and a step list block. As you can see the lambda we pass on the first parameter is the one that makes sure the steps are being run inside a transaction and to abort the transaction if the intermediate result is a failure.
+For this plugin, we'll define a way to group steps within an `ActiveRecord` transaction, much in the same way the `:sequel_models` plugin already does for `Sequel`.
+To this end, we define a `transaction` method to expect a steps block and pass it down to the `around` helper below which expects a callable (like a `Proc`) and a step list block. As you can see the lambda we pass on the first parameter makes sure the steps are being run inside a transaction or aborts the transaction if the intermediate result is a failure.
 
-The `around` method is a low level tool available to help extending the process DSL and it may seem a bit daunting at first glance but it usage is quite simple, the block is just a step list like the ones we find inside the `process` call; and the parameter is a callable (usually a lambda), that will take 2 arguments, an object from which we can run the step list by invoking `call` (and is the only thing it can do), and the current state. From here we can examine the state and decide upon whether to run the steps, how many times (if any) or run some code before and/or after doing so, like what we need to do in our example to surround the steps within a DB transaction.
+The `around` method is a low-level tool available to help extend the process DSL and it may seem a bit daunting at first glance but its usage is quite simple, the block is just a step list like the ones we find inside the `process` call; and the parameter is a callable (usually a lambda), that will take 2 arguments, an object from which we can run the step list by invoking `call` (and is the only thing it can do), and the current state. From here we can examine the state and decide upon whether to run the steps, how many times (if any), or run some code before and/or after doing so, like what we need to do in our example to surround the steps within a DB transaction.
 
 ### Testing tools
 
-As of right now only `rspec` is supported, that is, you can obviously test your operations with any framework you want, but all the provided matchers are designed for `rspec`.
+As of right now, only `rspec` is supported, that is, you can obviously test your operations with any framework you want, but all the provided matchers are designed for `rspec`.
 
 #### Rspec config
 
@@ -714,8 +744,8 @@ require 'pathway/rspec'
 
 #### Rspec matchers
 
-Pathway provides a few matchers in order to tests your operation easier.
-Let's go through a full example and break it up in the following subsections:
+Pathway provides a few matchers in order to test your operation easier.
+Let's go through a full example:
 
 ```ruby
 # create_nugget.rb
@@ -734,8 +764,8 @@ class CreateNugget < Pathway::Operation
     set  :create_nugget
   end
 
-  def create_nugget(params:,**)
-    Nugget.create(params)
+  def create_nugget(state)
+    Nugget.create(state[:params])
   end
 end
 
@@ -774,7 +804,7 @@ end
 ##### `succeed_on` matcher
 
 This first matcher works on the operation itself and that's why we could set `subject` with the operation instance and use `is_expected.to succeed_on(...)` on the example.
-The assertion it performs is simply is that the operation was successful, also you can optionally chain `returning(...)` if you want to test the returning value, this method allows nesting matchers as is the case in the example.
+The assertion it performs is simply that the operation was successful, also you can optionally chain `returning(...)` if you want to test the returning value, this method allows nesting matchers as is the case in the example.
 
 ##### `fail_on` matcher
 
@@ -782,7 +812,7 @@ This second matcher is analog to `succeed_on` but it asserts that operation exec
 
 ##### contract/form matchers
 
-Finally we can see that we are also testing the operation's contract (or form), implemented here with the `dry-validation` gem.
+Finally, we can see that we are also testing the operation's contract (or form), implemented here with the `dry-validation` gem.
 
 Two more matchers are provided: `require_fields` (aliased `require_field`) to test when a contract is expected to define a required set of fields, and `accept_optional_fields` (aliased `accept_optional_field`) to test when a contract must define a certain set of optional fields, both the contract class (at operation class method `contract_class`) or an instance (operation class method `build_contract`) can be provided.
 

data/Rakefile

@@ -3,6 +3,10 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |t|
+  unless RUBY_VERSION =~ /^2\.7|^3\./
+    t.exclude_pattern = 'spec/operation_call_pattern_matching_spec.rb,spec/state_pattern_matching_spec.rb'
+  end
+end
 
 task :default => :spec

data/lib/pathway/result.rb

@@ -22,6 +22,10 @@ module Pathway
         follow = self.then(bl, &block)
         follow.failure? ? follow : self
       end
+
+      private
+
+      alias :value_for_deconstruct :value
     end
 
     class Failure < Result
@@ -40,6 +44,27 @@ module Pathway
       def tee(_=nil)
         self
       end
+
+      private
+
+      alias :value_for_deconstruct :error
+    end
+
+    module Mixin
+      Success = Result::Success
+      Failure = Result::Failure
+    end
+
+    def deconstruct
+      [value_for_deconstruct]
+    end
+
+    def deconstruct_keys(keys)
+      if value_for_deconstruct.respond_to?(:deconstruct_keys)
+        value_for_deconstruct.deconstruct_keys(keys)
+      else
+        {}
+      end
     end
 
     def failure?

data/lib/pathway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pathway
-  VERSION = '0.12.0'
+  VERSION = '0.12.1'
 end

data/lib/pathway.rb

@@ -45,6 +45,14 @@ module Pathway
       @details = details || {}
     end
 
+    def deconstruct
+      [type, message, details]
+    end
+
+    def deconstruct_keys(_)
+      { type: type, message: message, details: details }
+    end
+
     private
 
     def default_message_for(type)
@@ -60,7 +68,7 @@ module Pathway
       @result_key = operation.result_key
     end
 
-    delegate %i([] []= fetch store include? values_at) => :@hash
+    delegate %i([] []= fetch store include? values_at deconstruct_keys) => :@hash
 
     def update(kargs)
       @hash.update(kargs)
@@ -116,7 +124,7 @@ module Pathway
         end
 
         def error(type, message: nil, details: nil)
-          failure Error.new(type: type, message: message, details: details)
+          failure(Error.new(type: type, message: message, details: details))
         end
 
         def wrap_if_present(value, type: :not_found, message: nil, details: {})

data/pathway.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "ruby2_keywords"
 
   spec.add_development_dependency "dry-validation", ">= 0.11"
-  spec.add_development_dependency "bundler", "~> 2.3.7"
+  spec.add_development_dependency "bundler", ">= 2.4.10"
   spec.add_development_dependency "sequel", "~> 5.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.11"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pathway
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Pablo Herrero
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-18 00:00:00.000000000 Z
+date: 2024-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-inflector
@@ -70,16 +70,16 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.7
+        version: 2.4.10
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.7
+        version: 2.4.10
 - !ruby/object:Gem::Dependency
   name: sequel
   requirement: !ruby/object:Gem::Requirement
@@ -240,7 +240,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/pabloh/pathway/issues
   source_code_uri: https://github.com/pabloh/pathway
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -255,8 +255,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key: 
+rubygems_version: 3.5.10
+signing_key:
 specification_version: 4
 summary: Define your business logic in simple steps.
 test_files: []