pipeable 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e0aa08638b53d5dc7005d8754db2e991a9529d439ebedef96baa7fb4ef0e67b
-  data.tar.gz: 16cab1671faa230b629f19c68d2b16835e3b2e9406085b8e08ae1281194c2273
+  metadata.gz: 2467c8bb8dda8efd0a2e4fc5a78765f8abaeab65c288c380d9c7358244ba5aaf
+  data.tar.gz: 96c96e5e12d25f81dd9c7e83b59850691036513b8456acab4868b93a71083f22
 SHA512:
-  metadata.gz: b4a029e0fe184140e2ccb0649753d19c2250e5231df82ef2fd8961e74e622330090891288db8654e5d0282ff41b459587901b14dba37426407d6fd31ba6b53cc
-  data.tar.gz: 31a1d08c5c4f068fdf04bfcc92b21308ff1eee4e551da94db16557d7b6c2b3621c90728519addf1ac0e101134b2056450017f1e0f7cab83ee098dcc0cb2e5174
+  metadata.gz: 94f1002860d093423864900306a266a8c5d452f186f40e6053c326fc9a689cf0b7edded0a60f92d00dd1de14f906315f6b88a7987fb0b67511f9a92fdd73f160
+  data.tar.gz: 767a44496263b160871c38a7bef274eacc089dbf641fdb60a7879f07e584603c0fc125cf9b285c156a75daff4e6cc856c5b027307f87a8f1f34c0876dcba33ce

data/README.adoc

@@ -10,11 +10,12 @@
 :dry_validation_link: link:https://dry-rb.org/gems/dry-validation[Dry Validation]
 :function_composition_link: link:https://alchemists.io/articles/ruby_function_composition[Function Composition]
 :infusible_link: link:https://alchemists.io/projects/infusible[Infusible]
+:method_parameters_and_arguments_link: link:https://alchemists.io/articles/ruby_method_parameters_and_arguments[Method Parameters And Arguments]
 :railway_pattern_link: link:https://fsharpforfunandprofit.com/posts/recipe-part2[Railway Pattern]
 
 = Pipeable
 
-A DSL for workflows built atop native {function_composition_link} which leverages the {railway_pattern_link}. This allows you to write a sequence of _steps_ that cleanly read from left-to-right or top-to-bottom which results in a success or a failure without having to rely on exceptions which are expensive and should not be used for control flow.
+A DSL for workflows built atop native {function_composition_link} which leverages the {railway_pattern_link}. This allows you to write a sequence of _steps_ that cleanly read from top-to-bottom or left-to-right resulting in a single success or a failure. This allows you to avoid relying on exceptions for expensive control flows and/or complex conditional logic in general.
 
 toc::[]
 
@@ -29,7 +30,7 @@ toc::[]
 == Requirements
 
 . link:https://www.ruby-lang.org[Ruby].
-. A strong understanding of {function_composition_link}.
+. A strong understanding of {function_composition_link} and {method_parameters_and_arguments_link}.
 
 == Setup
 
@@ -65,7 +66,7 @@ require "pipeable"
 
 == Usage
 
-You can turn any object into a _transaction_ by requiring and including this gem as follows:
+You can turn any object into a _pipe_ by requiring and including this gem as follows:
 
 [source,ruby]
 ----
@@ -100,7 +101,7 @@ class Demo
 end
 ----
 
-The above allows `Demo#call` to be a sequence steps which may pass or fail due to all step being {dry_monads_link}. This is the essence of the {railway_pattern_link}.
+The above allows `Demo#call` to be a sequence of steps which may pass or fail due to all steps using {dry_monads_link} for input and output. This is the essence of the {railway_pattern_link}.
 
 To execute the above example, you'd only need to pass CSV content to it:
 
@@ -151,19 +152,44 @@ Then the above would look like this using native Ruby:
 ).call Success(csv)
 ----
 
-The problem with native function composition is that it reads backwards by passing your input at the end of all sequential steps. With the `#pipe` method, you have the benefit of allowing your eye to read the code from top to bottom in addition to not having to type multiple _forward composition_ operators.
+The problem with native function composition is that it reads backwards by passing input at the end of all sequential steps. With the `#pipe` method, you have the benefit of allowing your eyes to read from top to bottom while not having to type multiple _forward composition_ operators.
 
 === Steps
 
-There are several ways to compose steps for your pipe. As long as all steps succeed, you'll get a successful response. Otherwise, the first step to fail will pass the failure down by skipping all subsequent steps (unless you dynamically attempt to turn the failure into a success). The following sections detail how to mix and match steps for building a robust implementation.
+There are several ways to compose steps for your pipe. As long as all steps succeed, you'll get a successful response. Otherwise, the first step to fail will pass the failure down by skipping all subsequent steps (unless you dynamically turn the failure into a success).
+
+Each step expects a {dry_monads_link} `Result` object as input and answers either the same or new `Result` object for consumption by the next step in the pipe. Additionally, each step will either unwrap the `Result` or pass the `Result` through depending on the step's implementation. These details are noted in each step's documentation below complete with _i/o_ (input/output) and _example_ sections.
 
 ==== Basic
 
-The following are the basic (default) steps for building for more advanced functionality.
+The following are the basic (default) steps for building custom pipes for which you can mix and match within your own implementation.
+
+===== Alt
+
+Allows you to operate on a failure and produce either a success or another failure. This is a convenience wrapper to native {dry_monads_link} `#or` functionality.
+
+*I/O*
+
+Processes a failure only while expecting you to answer a success or failure.
+
+*Example*
+
+[source,ruby]
+----
+pipe %i[a b c], alt { |object| Success object.join("-") }          # Success [:a, :b, :c]
+pipe Failure("Danger!"), alt { Success "Resolved" }                # Success "Resolved"
+pipe Failure("Danger!"), alt { |object| Failure "Big #{object}" }  # Failure "Big Danger!"
+----
 
 ===== As
 
-Allows you to message the input as different output. Example:
+Allows you to message an object as a different result. The first argument is the method but additional positional and/or keyword arguments can be passed along if the method accepts them.
+
+*I/O*
+
+Processes and answers a success only.
+
+*Example*
 
 [source,ruby]
 ----
@@ -174,18 +200,30 @@ pipe Failure("Danger!"), as(:inspect)  # Failure "Danger!"
 
 ===== Bind
 
-Allows you to perform operations on a successful result only. You are then responsible for answering a success or failure accordingly. This is a convenience wrapper to native {dry_monads_link} `#bind` functionality. Example:
+Allows you to perform operations upon success only. You are then responsible for answering a success or failure accordingly. This is a convenience wrapper to native {dry_monads_link} `#bind` functionality.
+
+*I/O*
+
+Processes a success only while expecting you to answer a success or failure in return.
+
+*Example*
 
 [source,ruby]
 ----
-pipe %i[a b c], bind { |input| Success input.join("-") }           # Success "a-b-c"
-pipe %i[a b c], bind { |input| Failure input }                     # Failure [:a, :b, :c]
-pipe Failure("Danger!"), bind { |input| Success input.join("-") }  # Failure "Danger!"
+pipe %i[a b c], bind { |object| Success object.join("-") }           # Success "a-b-c"
+pipe %i[a b c], bind { |object| Failure object }                     # Failure [:a, :b, :c]
+pipe Failure("Danger!"), bind { |object| Success object.join("-") }  # Failure "Danger!"
 ----
 
 ===== Check
 
-Allows you to check if the input and messaged object evaluate to `true` or `Success`. When successful, input is passed through as a `Success`. When false, input is passed through as a `Failure`. Example:
+Allows you to check if an object matches the proof (with message). The first argument is your proof while the second argument is the message to send to your proof. A check only passes if the messaged object evaluates to `true` or `Success`. When successful, the object is passed through as a `Success`. When false, the object is passed through as a `Failure`.
+
+*I/O*
+
+Processes a success only while answering a success or failure depending on whether unwrapped object checks against the proof.
+
+*Example*
 
 [source,ruby]
 ----
@@ -196,17 +234,29 @@ pipe Failure("Danger!"), check(%i[a b], :include?)  # Failure "Danger!"
 
 ===== Fmap
 
-Allows you to unwrap a successful operation, make a modification, and rewrap the modification as a new success. This is a convenience wrapper to native {dry_monads_link} `#fmap` functionality. Example:
+Allows you to unwrap a success, make a modification, and rewrap the modification as a new success. This is a convenience wrapper to native {dry_monads_link} `#fmap` functionality.
+
+*I/O*
+
+Processes and answers a success only.
+
+*Example*
 
 [source,ruby]
 ----
-pipe %i[a b c], fmap { |input| input.join "-" }           # Success "a-b-c"
-pipe Failure("Danger!"), fmap { |input| input.join "-" }  # Failure "Danger!"
+pipe %i[a b c], fmap { |object| object.join "-" }           # Success "a-b-c"
+pipe Failure("Danger!"), fmap { |object| object.join "-" }  # Failure "Danger!"
 ----
 
 ===== Insert
 
-Allows you to insert an element after the input (default behavior) and wraps native link:https://rubyapi.org/o/array#method-i-insert[Array#insert] functionality. If the input is not an array, it will be cast as one. You can use the `:at` key to specify where you want insertion to happen. This step is most useful when needing to assemble arguments for passing to a subsequent step. Example:
+Allows you to insert an element after an object (default behavior). This step wraps native link:https://rubyapi.org/o/array#method-i-insert[Array#insert] functionality. If the object is not an array, it will be cast as one. You can use the `:at` key to specify where you want insertion to happen. This step is most useful when needing to assemble arguments for passing to a subsequent step.
+
+*I/O*
+
+Processes and answers a success only.
+
+*Example*
 
 [source,ruby]
 ----
@@ -218,7 +268,13 @@ pipe Failure("Danger!"), insert(:b)  # Failure "Danger!"
 
 ===== Map
 
-Allows you to map over an enumerable and wraps native link:https://rubyapi.org/o/enumerable#method-i-map[Enumerable#map] functionality.
+Allows you to map over an object (enumerable) by wrapping native link:https://rubyapi.org/o/enumerable#method-i-map[Enumerable#map] functionality.
+
+*I/O*
+
+Processes and answers a success only.
+
+*Example*
 
 [source,ruby]
 ----
@@ -228,7 +284,13 @@ pipe Failure("Danger!"), map(&:inspect)  # Failure "Danger!"
 
 ===== Merge
 
-Allows you to merge the input with additional attributes as a single hash. If the input is not a hash, then the input will be merged with the attributes using `step` as the key. The default `step` key can be renamed to a different key by using the `:as` key. Like the _Insert_ step, this is most useful when needing to assemble arguments and/or data for consumption by subsequent steps. Example:
+Allows you to merge an object with additional attributes as a single hash. If the input is not a hash, then the object will be merged with `step` as the key. The default `step` key can be renamed to a different key by using the `:as` key. Like the _Insert_ step, this is most useful when assembling arguments and/or data for consumption by subsequent steps
+
+*I/O*
+
+Processes and answers a success only.
+
+*Example*
 
 [source,ruby]
 ----
@@ -238,24 +300,15 @@ pipe "test", merge(as: :a, b: 2)      # Success {a: "test", b: 2}
 pipe Failure("Danger!"), merge(b: 2)  # Failure "Danger!"
 ----
 
-===== Orr
-
-Allows you to operate on a failure and produce either a success or another failure. This is a convenience wrapper to native {dry_monads_link} `#or` functionality.
-
-ℹ️ Syntactically, `or` can't be used for this step since `or` is a native Ruby keyword so `orr` is used instead.
+===== Tee
 
-Example:
+Allows you to run an operation and ignore the response while input is passed through as output. This behavior is similar in nature to the link:https://www.gnu.org/savannah-checkouts/gnu/gawk/manual/html_node/Tee-Program.html[tee] program in Bash.
 
-[source,ruby]
-----
-pipe %i[a b c], orr { |input| Success input.join("-") }          # Success [:a, :b, :c]
-pipe Failure("Danger!"), orr { Success "Resolved" }              # Success "Resolved"
-pipe Failure("Danger!"), orr { |input| Failure "Big #{input}" }  # Failure "Big Danger!"
-----
+*I/O*
 
-===== Tee
+Passes the result through while allowing you to execute arbitrary behavior.
 
-Allows you to run an operation and ignore the response while input is passed through as output. This behavior is similar in nature to the link:https://www.gnu.org/savannah-checkouts/gnu/gawk/manual/html_node/Tee-Program.html[tee] program in Bash. Example:
+*Example*
 
 [source,ruby]
 ----
@@ -272,14 +325,20 @@ pipe Failure("Danger!"), tee(Kernel, :puts, "Example.")
 
 ===== To
 
-Allows you to delegate to an object -- which doesn't have a callable interface and may or may not answer a result -- for processing of input. If the response is not a monad, it'll be automatically wrapped as a `Success`. Example:
+Allows you to delegate to an object which doesn't have a callable interface and may or may not answer a result. If the response is not a monad, it'll be automatically wrapped as a `Success`.
+
+*I/O*
+
+Processes a success only while sending the unwrapped object to the given object's corresponding method. The object is expected to answer either a plain Ruby object which will be automatically wrapped as a success or a {dry_monads_link} `Result`.
+
+*Example*
 
 [source,ruby]
 ----
-Model = Struct.new :label, keyword_init: true do
+Model = Struct.new :label do
   include Dry::Monads[:result]
 
-  def self.for(...) = Success new(...)
+  def self.for(**) = Success new(**)
 end
 
 pipe({label: "Test"}, to(Model, :for))    # Success #<struct Model label="Test">
@@ -288,22 +347,42 @@ pipe Failure("Danger!"), to(Model, :for)  # Failure "Danger!"
 
 ===== Try
 
-Allows you to try an operation which may fail while catching the exception as a failure for further processing. Example:
+Allows you to try an operation which may fail while catching any exceptions as a failure for further processing. You can catch a single exception by providing the exception as a single value or multiple exceptions as an array of values.
+
+*I/O*
+
+Processes and answers a success only if there are no exceptions. Otherwise, captures any error as a failure.
+
+*Example*
 
 [source,ruby]
 ----
-pipe "test", try(:to_json, catch: JSON::ParserError)     # Success "\"test\""
-pipe "test", try(:invalid, catch: NoMethodError)         # Failure "undefined method..."
-pipe Failure("Danger!"), try(:to_json, catch: JSON::ParserError)  # Failure "Danger!"
+pipe "test", try(:to_json, catch: JSON::ParserError)
+# Success "\"test\""
+
+pipe "test", try(:to_json, catch: [JSON::ParserError, StandardError])
+# Success "\"test\""
+
+pipe "test", try(:invalid, catch: NoMethodError)
+# Failure(#<NoMethodError: undefined method `invalid' for an instance of String>)
+
+pipe Failure("Danger!"), try(:to_json, catch: JSON::ParserError)
+# Failure "Danger!"
 ----
 
 ===== Use
 
-Allows you to use another transaction which might have multiple steps of it's own, use an object that adheres to the {command_pattern_link}, or any function which answers a {dry_monads_link} `Result` object. In other words, you can use _use_ any object which responds to `#call` and answers a {dry_monads_link} `Result` object. This is great for chaining multiple transactions together.
+Allows you to use another pipe to build a superpipe, use an object that adheres to the {command_pattern_link}, or any function which answers a {dry_monads_link} `Result` object. In other words, you can use _use_ any object which responds to `#call` that answers a {dry_monads_link} `Result` object. This is great for chaining multiple pipes together (i.e. superpipes).
+
+*I/O*
+
+Processes a success only while sending the unwrapped object to the command (or pipe) for further processing. A {dry_monads_link} `Result` is expected to be answered by the command.
+
+*Example*
 
 [source,ruby]
 ----
-function = -> input { Success input * 3 }
+function = -> number { Success number * 3 }
 
 pipe 3, use(function)                   # Success 9
 pipe Failure("Danger!"), use(function)  # Failure "Danger!"
@@ -311,17 +390,30 @@ pipe Failure("Danger!"), use(function)  # Failure "Danger!"
 
 ===== Validate
 
-Allows you to use an operation that will validate the input. This is especially useful when using {dry_schema_link}, {dry_validation_link}, or any operation that can respond to `#call` while answering a result that can be converted into a hash.
+Allows you to use an contract for validating an object. This is especially useful when using {dry_schema_link}, {dry_validation_link}, or any contract that responds to `#call` and answers a `Result`.
+
+💡 Ensure you enable the {dry_monads_link} extension for {dry_schema_link} and/or {dry_validation_link} when using this step since this step expects the contract to respond to the `#to_monad` message.
+
+By default, the `:as` key's value is `nil``. Use `:to_h`, for example, as the value for automatic casting to a `Hash`. You can also pass in any value to the `:as` key which is a valid method that the contract's result will respond to.
 
-By default, the `:as` key uses `:to_h` as it's value so you get automatic casting to a `Hash`. Use `nil`, as the value, to disable this behavior. You can also pass in any value to the `:as` key which is a valid method that the result will respond to.
+*I/O*
+
+Processes a success only. A success will be rewrapped as a success if the `:as` keyword is supplied. Otherwise, any failure is immediately passed through.
+
+*Example*
 
 [source,ruby]
 ----
 schema = Dry::Schema.Params { required(:label).filled :string }
 
-pipe({label: "Test"}, validate(schema))           # Success label: "Test"
-pipe({label: "Test"}, validate(schema, as: nil))  # Success #<Dry::Schema::Result{:label=>"Test"} errors={} path=[]>
-pipe Failure("Danger!"), validate(schema)         # Failure "Danger!"
+pipe({label: "Test"}, validate(schema))
+# Success label: "Test"
+
+pipe({label: "Test"}, validate(schema, as: nil))
+# Success #<Dry::Schema::Result{:label=>"Test"} errors={} path=[]>
+
+pipe Failure("Danger!"), validate(schema)
+# Failure "Danger!"
 ----
 
 ==== Advanced
@@ -334,8 +426,8 @@ You can always use a `Proc` as a custom step. Example:
 
 [source,ruby]
 ----
-include Pipeable
 include Dry::Monads[:result]
+include Pipeable
 
 pipe :a,
      insert(:b),
@@ -355,7 +447,7 @@ include Pipeable
 
 pipe :a,
      insert(:b),
-     -> result { result.fmap { |input| input.join "_" } },
+     -> result { result.fmap { |items| items.join "_" } },
      as(:to_sym)
 
 # Yields: Success :a_b
@@ -363,35 +455,30 @@ pipe :a,
 
 ===== Methods
 
-Methods -- in addition to procs and lambdas -- are the _preferred_ way to add custom steps due to the concise syntax. Example:
+Methods, in addition to procs and lambdas, are the _preferred_ way to add custom steps due to the concise syntax. Example:
 
 [source,ruby]
 ----
 class Demo
   include Pipeable
 
-  def call input
-    pipe :a,
-         insert(:b),
-         :join,
-         as(:to_sym)
-  end
+  def call(input) = pipe input, insert(:b), :join, as(:to_sym)
 
   private
 
-  def join(result) = result.fmap { |input| input.join "_" }
+  def join(result) = result.fmap { |items| items.join "_" }
 end
 
-Demo.new.call :a  # Yields: Success :a_b
+Demo.new.call :a  # Success :a_b
 ----
 
-All methods can be referenced by symbol as shown via `:join` above. Using a symbol is syntactic sugar for link:https://rubyapi.org/o/object#method-i-method[Object#method] so the use of the `:join` symbol is the same as using `method(:join)`. Both work but the former requires less typing than the latter.
+All methods can be referenced by symbol as shown via `:join` above. Using a symbol is syntactic sugar for link:https://rubyapi.org/o/object#method-i-method[Object#method] so `:join` (symbol) is the same as using `method(:join)`. Both work but the former requires less typing.
 
 ===== Custom
 
 If you'd like to define permanent and reusable steps, you can register a custom step which requires you to:
 
-. Define a custom step as a new class.
+. Define a custom step as a class, lambda, or proc.
 . Register your custom step along side the existing default steps.
 
 Here's what this would look like:
@@ -405,7 +492,7 @@ module CustomSteps
       @delimiter = delimiter
     end
 
-    def call(result) = result.fmap { |input| input.join delimiter }
+    def call(result) = result.fmap { |items| items.join delimiter }
 
     private
 
@@ -418,12 +505,82 @@ Pipeable::Steps::Container.register :join, CustomSteps::Join
 include Pipeable
 
 pipe :a, insert(:b), join, as(:to_sym)
-# Yields: Success :a_b
+# Success :a_b
 
 pipe :a, insert(:b), join(""), as(:to_sym)
-# Yields: Success :ab
+# Success :ab
+----
+
+A lambda or proc can be used too (albeit in limited capacity). Here's a version of the above using a lambda:
+
+[source,ruby]
+----
+module CustomSteps
+  Join = -> result { result.fmap { |items| items.join "_" } }
+end
+
+Pipeable::Steps::Container.register :join, CustomSteps::Join
+
+include Pipeable
+
+puts pipe(:a, insert(:b), join, as(:to_sym))
+# Success :a_b
 ----
 
+=== Superpipes
+
+Superpipes, as first hinted at in the `use` step above, are a combination of _pipeable_ objects chained together as individual steps. This allows you to reuse existing pipeable objects in new and interesting ways. Here's an contrived, but simple, example of what a superpipe looks like when built from pipeable objects:
+
+[source,ruby]
+----
+class One
+  include Pipeable
+
+  def initialize label = "one"
+    @label = label
+  end
+
+  def call(item) = pipe item, insert(label, at: 0)
+
+  private
+
+  attr_reader :label
+end
+
+class Two
+  include Pipeable
+
+  def initialize label = "two"
+    @label = label
+  end
+
+  def call(item) = pipe item, insert(label)
+
+  private
+
+  attr_reader :label
+end
+
+class Three
+  include Pipeable
+
+  def initialize one: One.new, two: Two.new
+    @one = one
+    @two = two
+  end
+
+  def call(item) = pipe item, use(one), use(two)
+
+  private
+
+  attr_reader :one, :two
+end
+----
+
+Notice, `One` and `Two` are standard pipeable objects with their own individual steps while `Three` injects both `One` and `Two` as dependencies and then subsequently pipes them together within it's own `#call` method via the `use` step. This is essence of a superpipe. ...and, yes, a superpipe can be an individual step too in some other object. Turtles all the way down (or up). 😉
+
+Again, the above is contrived but hopefully this illustrates how you can build more complex architectures from smaller pipes.
+
 === Containers
 
 Should you not want the basic steps, need custom steps, or a hybrid of default and custom steps, you can define your own container and provide it as an argument to `.[]` when including pipeable behavior. Example:
@@ -448,7 +605,7 @@ pipe :a, echo, insert(:b)
 
 The above is a hybrid example where the `CustomContainer` registers a custom `echo` step along with the default `insert` step to make a new container. This is included when passed in as an argument via `.[]` (i.e. `include Pipeable[CustomContainer]`).
 
-Whether you use default, custom, or hybrid steps, you have maximum flexibility using this approach.
+Whether you use default, custom, or hybrid steps, you have maximum flexibility when using containers.
 
 === Composition
 
@@ -483,14 +640,14 @@ The architecture of this gem is built on top of the following concepts and gems:
 
 === Style Guide
 
-* *Transactions*
-** Use a single method (i.e. `#call`) which is public and adheres to the {command_pattern_link} so transactions can be piped together if desired.
+* *Pipes*
+** Use a single method (i.e. `#call`) which is public and adheres to the {command_pattern_link} so multiple pipes can be piped together (i.e. superpipes) if desired.
 * *Steps*
 ** Inherit from the `Abstract` class to gain monad, composition, and dependency behavior. This allows subclasses to have direct access to the base positional, keyword, and block arguments. These variables are prefixed with `base_*` in order to not conflict with subclasses which might only want to use non-prefixed variables for convenience.
-** All filtered arguments -- in other words, the unused arguments -- need to be passed up to the superclass from the subclass (i.e. `super(*positionals, **keywords, &block)`). Doing so allows the superclass (i.e. `Abstract`) to provide access to `base_positionals`, `base_keywords`, and `base_block` for use if desired by the subclass.
+** All filtered arguments -- in other words, unused arguments -- need to be passed up to the superclass from the subclass (i.e. `super(*positionals, **keywords, &block)`). Doing so allows the superclass (i.e. `Abstract`) to provide access to `base_positionals`, `base_keywords`, and `base_block` for use if desired by the subclass.
 ** The `#call` method must define a single positional `result` parameter since a monad will be passed as an argument. Example: `def call(result) = # Implementation`.
-** Each block within the `#call` method should use the `input` parameter to be consistent. More specific parameters like `argument` or `operation` should be used to improve readability when possible. Example: `def call(result) = result.bind { |input| # Implementation }`.
-** Use implicit blocks sparingly. Most of the default steps shy away from using blocks because it can make the code more complex. Use private methods, custom steps, and/or separate transactions if the code becomes too complex because you might have a smaller object which needs extraction.
+** Each block within the `#call` method should use the `object` parameter to be consistent. More specific parameters like `operation` or `contract` should be used to improve readability when context allows. Example: `def call(result) = result.bind { |object| # Implementation }`.
+** Use implicit blocks sparingly. Most of the default steps shy away from using blocks because the code becomes more complex. Use private methods, custom steps, and/or separate pipes if the code becomes too complex because you might have a smaller object which needs extraction.
 
 === Debugging
 
@@ -508,7 +665,7 @@ The above breakpoint will allow you inspect the result of the `#check` step and/
 
 === Troubleshooting
 
-The following might be of aid to as you implement your own transactions.
+The following might be of aid to as you implement your own pipes.
 
 ==== Type Errors
 

data/lib/pipeable/steps/abstract.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "dry/monads"
-require "marameters"
 
 module Pipeable
   module Steps
@@ -14,12 +13,11 @@ module Pipeable
         @base_positionals = positionals
         @base_keywords = keywords
         @base_block = block
-        @marameters = Marameters
       end
 
       protected
 
-      attr_reader :base_positionals, :base_keywords, :base_block, :marameters
+      attr_reader :base_positionals, :base_keywords, :base_block
     end
   end
 end

data/lib/pipeable/steps/as.rb

@@ -2,10 +2,10 @@
 
 module Pipeable
   module Steps
-    # Allows result to be messaged as a callable.
+    # Messages object, with optional arguments, as different result.
     class As < Abstract
       def call result
-        result.fmap { |operation| operation.public_send(*base_positionals, **base_keywords) }
+        result.fmap { |object| object.public_send(*base_positionals, **base_keywords) }
       end
     end
   end

data/lib/pipeable/steps/bind.rb

@@ -4,7 +4,7 @@ module Pipeable
   module Steps
     # Wraps Dry Monads `#bind` method as a step.
     class Bind < Abstract
-      def call(result) = result.bind { |input| base_block.call input }
+      def call(result) = result.bind { |object| base_block.call object }
     end
   end
 end

data/lib/pipeable/steps/check.rb

@@ -1,29 +1,31 @@
 # frozen_string_literal: true
 
+require "marameters"
+
 module Pipeable
   module Steps
-    # Checks if operation is true and then answers success (passthrough) or failure (with argument).
+    # Checks if proof is true and answers success (passthrough) or failure (with optional argument).
     class Check < Abstract
-      def initialize(operation, message, **)
-        super(**)
-        @operation = operation
+      def initialize proof, message
+        super()
+        @proof = proof
         @message = message
       end
 
       def call result
-        result.bind do |arguments|
-          answer = question arguments
-          answer == true || answer.is_a?(Success) ? result : Failure(arguments)
+        result.bind do |object|
+          answer = question object
+          answer == true || answer.is_a?(Success) ? result : Failure(object)
         end
       end
 
       private
 
-      attr_reader :operation, :message
+      attr_reader :proof, :message
 
-      def question arguments
-        splat = marameters.categorize operation.method(message).parameters, arguments
-        operation.public_send(message, *splat.positionals, **splat.keywords, &splat.block)
+      def question object
+        splat = Marameters.categorize proof.method(message).parameters, object
+        proof.public_send(message, *splat.positionals, **splat.keywords, &splat.block)
       end
     end
   end

data/lib/pipeable/steps/container.rb

@@ -8,6 +8,7 @@ module Pipeable
     module Container
       extend Containable
 
+      register :alt, Or
       register :as, As
       register :bind, Bind
       register :check, Check
@@ -15,7 +16,6 @@ module Pipeable
       register :insert, Insert
       register :map, Map
       register :merge, Merge
-      register :orr, Or
       register :tee, Tee
       register :to, To
       register :try, Try

data/lib/pipeable/steps/fmap.rb

@@ -4,7 +4,7 @@ module Pipeable
   module Steps
     # Wraps Dry Monads `#fmap` method as a step.
     class Fmap < Abstract
-      def call(result) = result.fmap { |input| base_block.call input }
+      def call(result) = result.fmap { |object| base_block.call object }
     end
   end
 end

data/lib/pipeable/steps/insert.rb

@@ -2,7 +2,7 @@
 
 module Pipeable
   module Steps
-    # Inserts elements before, after, or around input.
+    # Inserts elements before or after an object.
     class Insert < Abstract
       LAST = -1
 
@@ -13,8 +13,8 @@ module Pipeable
       end
 
       def call result
-        result.fmap do |input|
-          cast = input.is_a?(Array) ? input : [input]
+        result.fmap do |object|
+          cast = object.is_a?(Array) ? object : [object]
           value.is_a?(Array) ? cast.insert(at, *value) : cast.insert(at, value)
         end
       end

data/lib/pipeable/steps/map.rb

@@ -2,7 +2,7 @@
 
 module Pipeable
   module Steps
-    # Maps over a collection, processing each element, and answering a new result.
+    # Maps over an enumerable, processes each element, and answers a new enumerable.
     class Map < Abstract
       def call(result) = result.fmap { |collection| collection.map(&base_block) }
     end

data/lib/pipeable/steps/merge.rb

@@ -2,19 +2,19 @@
 
 module Pipeable
   module Steps
-    # Merges initialized attributes with step argument for use by a subsequent step.
+    # Merges initialized attributes with step object for use by subsequent step.
     class Merge < Abstract
-      def initialize as: :step, **keywords
-        super(**keywords)
+      def initialize(as: :step, **)
+        super(**)
         @as = as
       end
 
       def call result
-        result.fmap do |input|
-          if input.is_a? Hash
-            input.merge! base_keywords
+        result.fmap do |object|
+          if object.is_a? Hash
+            object.merge! base_keywords
           else
-            {as => input}.merge!(base_keywords)
+            {as => object}.merge!(base_keywords)
           end
         end
       end

data/lib/pipeable/steps/or.rb

@@ -4,7 +4,7 @@ module Pipeable
   module Steps
     # Wraps Dry Monads `#or` method as a step.
     class Or < Abstract
-      def call(result) = result.or { |input| base_block.call input }
+      def call(result) = result.or { |object| base_block.call object }
     end
   end
 end

data/lib/pipeable/steps/tee.rb

@@ -2,7 +2,7 @@
 
 module Pipeable
   module Steps
-    # Messages operation, without any response checks, while passing input through as output.
+    # Messages operation, without any checks, while passing input through as output.
     class Tee < Abstract
       def initialize(operation, *, **)
         super(*, **)

data/lib/pipeable/steps/to.rb

@@ -1,25 +1,27 @@
 # frozen_string_literal: true
 
+require "marameters"
+
 module Pipeable
   module Steps
-    # Delegates to a non-callable operation which automatically wraps the result if necessary.
+    # Delegates to a non-callable object which automatically wraps the result if necessary.
     class To < Abstract
-      def initialize(operation, message, **)
+      def initialize(object, message, **)
         super(**)
-        @operation = operation
+        @object = object
         @message = message
       end
 
       def call result
         result.bind do |arguments|
-          splat = marameters.categorize operation.method(message).parameters, arguments
-          wrap operation.public_send(message, *splat.positionals, **splat.keywords, &splat.block)
+          splat = Marameters.categorize object.method(message).parameters, arguments
+          wrap object.public_send(message, *splat.positionals, **splat.keywords, &splat.block)
         end
       end
 
       private
 
-      attr_reader :operation, :message
+      attr_reader :object, :message
 
       def wrap(result) = result.is_a?(Dry::Monads::Result) ? result : Success(result)
     end

data/lib/pipeable/steps/try.rb

@@ -2,17 +2,17 @@
 
 module Pipeable
   module Steps
-    # Messages a risky operation which may pass or fail.
+    # Sends a risky message to an object which may pass or fail.
     class Try < Abstract
-      def initialize *positionals, catch:, **keywords
-        super(*positionals, **keywords)
+      def initialize(*, catch:, **)
+        super(*, **)
         @catch = catch
       end
 
       def call result
-        result.fmap { |operation| operation.public_send(*base_positionals, **base_keywords) }
+        result.fmap { |object| object.public_send(*base_positionals, **base_keywords) }
       rescue *Array(catch) => error
-        Failure error.message
+        Failure error
       end
 
       private

data/lib/pipeable/steps/use.rb

@@ -2,18 +2,18 @@
 
 module Pipeable
   module Steps
-    # Use another transaction -- or any command -- which answers a result.
+    # Messages a command (or pipe) which answers a result.
     class Use < Abstract
-      def initialize(operation, **)
+      def initialize(command, **)
         super(**)
-        @operation = operation
+        @command = command
       end
 
-      def call(result) = result.bind { |input| operation.call input }
+      def call(result) = result.bind { |input| command.call input }
 
       private
 
-      attr_reader :operation
+      attr_reader :command
     end
   end
 end

data/lib/pipeable/steps/validate.rb

@@ -2,27 +2,23 @@
 
 module Pipeable
   module Steps
-    # Validates a result via a callable operation.
+    # Validates result via a callable contract.
     class Validate < Abstract
-      def initialize(operation, as: :to_h, **)
-        super(**)
-        @operation = operation
+      def initialize contract, as: nil
+        super()
+        @contract = contract
         @as = as
       end
 
-      def call result
-        result.bind do |payload|
-          value = operation.call payload
-
-          return Failure value if value.failure?
-
-          Success(as ? value.public_send(as) : value)
-        end
-      end
+      def call(result) = result.bind { |payload| cast payload }
 
       private
 
-      attr_reader :operation, :as
+      attr_reader :contract, :as
+
+      def cast payload
+        contract.call(payload).to_monad.fmap { |data| as ? data.public_send(as) : data }
+      end
     end
   end
 end

data/pipeable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "pipeable"
-  spec.version = "0.4.0"
+  spec.version = "0.5.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/pipeable"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pipeable
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-04-30 00:00:00.000000000 Z
+date: 2024-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: containable
@@ -164,7 +164,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.10
 signing_key:
 specification_version: 4
 summary: A domain specific language for building functionally composable steps.