pipeable 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e0aa08638b53d5dc7005d8754db2e991a9529d439ebedef96baa7fb4ef0e67b
-  data.tar.gz: 16cab1671faa230b629f19c68d2b16835e3b2e9406085b8e08ae1281194c2273
+  metadata.gz: 4c03f09d3e8268f1786faa5907fe4f9dbc4beaf02c874bec73b683fd1e4a51de
+  data.tar.gz: 29943bc0fed70a2661cee558e5a4d23090af2fe216ba085ec1ff00e3da435ea3
 SHA512:
-  metadata.gz: b4a029e0fe184140e2ccb0649753d19c2250e5231df82ef2fd8961e74e622330090891288db8654e5d0282ff41b459587901b14dba37426407d6fd31ba6b53cc
-  data.tar.gz: 31a1d08c5c4f068fdf04bfcc92b21308ff1eee4e551da94db16557d7b6c2b3621c90728519addf1ac0e101134b2056450017f1e0f7cab83ee098dcc0cb2e5174
+  metadata.gz: ebaeb186fb3c672501fa3b5414b2d4fe381a45fa22004ae2f128b80abc15d012f0ff70befb900ad75d82b760af33fa4a35c7db5d3113e7f3f261782f01e7dd24
+  data.tar.gz: 41fe4361d2a0226ceeb8796d1edc9e6fd0e19bc00539c3d3c4e87c57d09a871818d051d7a8d881b294c0f3ea8e73f2575a0ead5dcaaf3d44dbbb0dd53065d749

data/README.adoc

@@ -10,17 +10,18 @@
 :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::[]
 
 == Features
 
-* Built atop of native {function_composition_link}.
+* Built atop native {function_composition_link}.
 * Adheres to the {railway_pattern_link}.
 * Provides built-in and customizable domain-specific steps.
 * Provides chainable _pipes_ which can be used to build more complex workflows.
@@ -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:
 
@@ -130,7 +131,7 @@ pipe(input, *steps)
 
 The first argument is your input which can be a Ruby primitive or a monad. Regardless, the input will be automatically wrapped as a `Success` -- but only if not a `Result` to begin with -- before passing to the first step. From there, all steps are _required_ to answer a monad in order to adhere to the {railway_pattern_link}.
 
-Behind the scenes, the `#pipe` method is syntactic sugar on top of {function_composition_link} which means if this code were to be rewritten:
+Behind the scenes, the `#pipe` method is syntactic sugar built atop {function_composition_link} which means if this code were to be rewritten:
 
 [source,ruby]
 ----
@@ -140,7 +141,7 @@ pipe csv,
      map { |item| "#{item[:book]}: #{item[:price]}" }
 ----
 
-Then the above would look like this using native Ruby:
+...then the above would look like the following (as rewritten in native Ruby):
 
 [source,ruby]
 ----
@@ -151,19 +152,53 @@ 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.
+Visually, the pipe can be diagramed as follows:
+
+image::https://alchemists.io/images/projects/pipeable/diagrams/pipe.png[A diagram of pipe steps,width=591,height=734,role=focal_point]
+
+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 can be initialized and called:
+
+* `+#initialize+`: Arguments vary per step but can be positional, keyword, and/or block arguments. This is how you _customize_ the behavior of each step.
+* `+#call+`: Expects a {dry_monads_link} `Result` object as input. The output is 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 (as detailed below).
 
 ==== 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.
+
+Accepts a failure while answering either 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!"
+----
+
+===== amap
 
-===== As
+Allows you to unwrap a failure, make a modification, and wrap the modification as a new failure. This is a convenience wrapper to native {dry_monads_link} `#alt_map` functionality.
 
-Allows you to message the input as different output. Example:
+Accepts and answers a failure. Example:
+
+[source,ruby]
+----
+pipe Failure("Danger"), amap { |object| "#{object}!" }  # Failure "Danger!"
+pipe Success("Pass"), amap { |object| "#{object}!" }    # Success "Pass"
+----
+
+===== as
+
+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.
+
+Accepts and answers a success. Example:
 
 [source,ruby]
 ----
@@ -172,20 +207,24 @@ pipe %i[a b c], as(:dig, 1)            # Success :b
 pipe Failure("Danger!"), as(:inspect)  # Failure "Danger!"
 ----
 
-===== Bind
+===== bind
+
+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.
 
-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:
+Accepts a success while answering either a success or failure. 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
+===== check
+
+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`.
 
-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:
+Accepts a success while answering a success or failure depending on whether unwrapped object checks against the proof. Example:
 
 [source,ruby]
 ----
@@ -194,19 +233,23 @@ pipe :a, check(%i[b c], :include?)                  # Failure :a
 pipe Failure("Danger!"), check(%i[a b], :include?)  # Failure "Danger!"
 ----
 
-===== Fmap
+===== 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 wrap the modification as a new success. This is a convenience wrapper to native {dry_monads_link} `#fmap` functionality.
+
+Accepts and answers a success. 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
+===== insert
+
+Allows you to insert an element after an object (default behavior) as a single array. 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 _positional_ arguments for passing as an array to a subsequent step.
 
-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:
+Accepts and answers a success. Example:
 
 [source,ruby]
 ----
@@ -216,9 +259,11 @@ pipe %i[a c], insert(:b, at: 1)      # Success [:a, :b, :c]
 pipe Failure("Danger!"), insert(:b)  # Failure "Danger!"
 ----
 
-===== Map
+===== map
+
+Allows you to map over an object (enumerable) by wrapping native link:https://rubyapi.org/o/enumerable#method-i-map[Enumerable#map] functionality.
 
-Allows you to map over an enumerable and wraps native link:https://rubyapi.org/o/enumerable#method-i-map[Enumerable#map] functionality.
+Accepts and answers a success. Example:
 
 [source,ruby]
 ----
@@ -226,9 +271,11 @@ pipe %i[a b c], map(&:inspect)           # Success [":a", ":b", ":c"]
 pipe Failure("Danger!"), map(&:inspect)  # Failure "Danger!"
 ----
 
-===== Merge
+===== 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. This step wraps native link:https://rubyapi.org/o/hash#method-i-merge[Hash#merge] functionality. 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 step is most useful when assembling _keyword_ arguments and/or a hash for a subsequent steps.
+
+Accepts and answers a success. Example:
 
 [source,ruby]
 ----
@@ -238,24 +285,11 @@ 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.
-
-Example:
-
-[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!"
-----
+===== tee
 
-===== Tee
+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.
 
-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:
+Accepts either a success or failure and passes the result through while allowing you to execute arbitrary behavior. Example:
 
 [source,ruby]
 ----
@@ -270,60 +304,83 @@ pipe Failure("Danger!"), tee(Kernel, :puts, "Example.")
 # Failure "Danger!"
 ----
 
-===== To
+===== 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`.
+
+Accepts a success 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">
 pipe Failure("Danger!"), to(Model, :for)  # Failure "Danger!"
 ----
 
-===== Try
+===== try
+
+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.
 
-Allows you to try an operation which may fail while catching the exception as a failure for further processing. Example:
+Accepts and answers a success 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
+===== 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).
+
+Accepts a success 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!"
 ----
 
-===== Validate
+===== validate
+
+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`.
 
-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.
+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.
+Accepts a success and rewraps 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!"
 ----
 
+💡 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.
+
 ==== Advanced
 
 Several options are available should you need to advance beyond the basic steps. Each is described in detail below.
@@ -334,8 +391,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 +412,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 +420,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 +457,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,15 +470,85 @@ 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 normal pipeable objects with individual steps while `Three` injects both `One` and `Two` as dependencies and then subsequently pipes them together in the `#call` method via the `use` step. This is the power of a superpipe. ...and, yes, a superpipe can be an individual step in some other object. Turtles all the way down (or up). 😉
+
+Again, the above is contrived but hopefully 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:
+Should you not want the basic steps, need custom steps, or a hybrid of default and custom steps, you can define your own container -- using the {containable_link} gem -- and provide the container as an argument to `.[]` when including pipeable behavior. Example:
 
 [source,ruby]
 ----
@@ -448,7 +570,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
 
@@ -479,18 +601,18 @@ The architecture of this gem is built on top of the following concepts and gems:
 * {function_composition_link}: Made possible through the use of the `\#>>` and `#<<` methods on the link:https://rubyapi.org/3.1/o/method[Method] and link:https://rubyapi.org/3.1/o/proc[Proc] objects.
 * {containable_link}: Allows related dependencies to be grouped together for injection as desired.
 * {dry_monads_link}: Critical to ensuring the entire pipeline of steps adhere to the {railway_pattern_link} and leans heavily on the `Result` object.
-* link:https://alchemists.io/projects/marameters[Marameters]: Through the use of the `.categorize` method, dynamic message passing is possible by inspecting the operation method's parameters.
+* link:https://alchemists.io/projects/marameters[Marameters]: Through the use of the `.categorize` method, dynamic message passing is possible by inspecting the object's method parameters.
 
 === 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
 
@@ -500,7 +622,7 @@ If you need to debug (i.e. {debug_link}) your pipe, use a lambda. Example:
 ----
 pipe data,
      check(/Book.+Price/, :match?),
-     -> result { binding.break },  # Breakpoint
+     -> result { binding.break; result }, # Breakpoint
      :parse
 ----
 
@@ -508,18 +630,18 @@ 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
 
 If you get a `TypeError: Step must be functionally composable and answer a monad`, it means:
 
-. The step must be a `Proc`, `Method`, or some object which responds to `\#>>`, `#<<`, and `#call`.
-. The step doesn't answer a result monad (i.e. `Success some_value` or `Failure some_value`).
+. The step must be a `Proc`, `Method`, or any object which responds to `\#>>`, `#<<`, and `#call`.
+. The step doesn't answer a result monad (i.e. `Success object` or `Failure object`).
 
 ==== No Method Errors
 
-If you get a `NoMethodError: undefined method `success?` exception, this might mean that you forgot to add a comma after one of your steps. Example:
+If you get a `NoMethodError: undefined method success?` exception, this might mean that you forgot to add a comma after one of your steps. Example:
 
 [source,ruby]
 ----
@@ -530,7 +652,7 @@ pipe "https://www.wikipedia.org",
 
 # Invalid
 pipe "https://www.wikipedia.org",
-     to(client, :get)  # Missing comma.
+     to(client, :get) # Missing comma.
      try(:parse, catch: HTTP::Error)
 ----
 

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/amap.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pipeable
+  module Steps
+    # Wraps Dry Monads `#alt_map` method as a step.
+    class Amap < Abstract
+      def call(result) = result.alt_map { |object| base_block.call object }
+    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,8 @@ module Pipeable
     module Container
       extend Containable
 
+      register :alt, Or
+      register :amap, Amap
       register :as, As
       register :bind, Bind
       register :check, Check
@@ -15,7 +17,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.6.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.6.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-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: containable
@@ -123,6 +123,7 @@ files:
 - lib/pipeable/composable.rb
 - lib/pipeable/pipe.rb
 - lib/pipeable/steps/abstract.rb
+- lib/pipeable/steps/amap.rb
 - lib/pipeable/steps/as.rb
 - lib/pipeable/steps/bind.rb
 - lib/pipeable/steps/check.rb
@@ -164,7 +165,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.