pipeable 0.0.1 → 0.2.0

data/README.adoc

@@ -0,0 +1,572 @@
+:toc: macro
+:toclevels: 5
+:figure-caption!:
+
+:command_pattern_link: link:https://alchemists.io/articles/command_pattern[Command Pattern]
+:containable_link: link:https://alchemists.io/projects/containable[Containable]
+:debug_link: link:https://github.com/ruby/debug[Debug]
+:dry_monads_link: link:https://dry-rb.org/gems/dry-monads[Dry Monads]
+:dry_schema_link: link:https://dry-rb.org/gems/dry-schema[Dry Schema]
+: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]
+: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.
+
+toc::[]
+
+== Features
+
+* Built atop of 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.
+* Compatible with the {containable_link}, {infusible_link}, and {dry_monads_link} gems.
+
+== Requirements
+
+. link:https://www.ruby-lang.org[Ruby].
+. A strong understanding of {function_composition_link}.
+
+== Setup
+
+To install _with_ security, run:
+
+[source,bash]
+----
+# 💡 Skip this line if you already have the public certificate installed.
+gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
+gem install pipeable --trust-policy HighSecurity
+----
+
+To install _without_ security, run:
+
+[source,bash]
+----
+gem install pipeable
+----
+
+You can also add the gem directly to your project:
+
+[source,bash]
+----
+bundle add pipeable
+----
+
+Once the gem is installed, you only need to require it:
+
+[source,ruby]
+----
+require "pipeable"
+----
+
+== Usage
+
+You can turn any object into a _transaction_ by requiring and including this gem as follows:
+
+[source,ruby]
+----
+require "csv"
+require "pipeable"
+
+class Demo
+  include Pipeable
+
+  def initialize client: CSV
+    @client = client
+  end
+
+  def call data
+    pipe data,
+         check(/Book.+Price/, :match?),
+         :parse,
+         map { |item| "#{item[:book]}: #{item[:price]}" }
+  end
+
+  private
+
+  attr_reader :client
+
+  def parse result
+    result.fmap do |data|
+      client.instance(data, headers: true, header_converters: proc { |key| key.downcase.to_sym })
+            .to_a
+            .map(&:to_h)
+    end
+  end
+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}.
+
+To execute the above example, you'd only need to pass CSV content to it:
+
+[source,ruby]
+----
+Demo.new.call <<~CSV
+  Book,Author,Price,At
+  Mystics,urGoh,10.50,2022-01-01
+  Skeksis,skekSil,20.75,2022-02-13
+CSV
+----
+
+The computed result is a success with each book listing a price:
+
+....
+Success ["Mystics: 10.50", "Skeksis: 20.75"]
+....
+
+=== Pipe
+
+Once you've included the `Pipeable` module within your class, the `#pipe` method is available to you and is how you build a sequence of steps for processing. The method signature is:
+
+[source,ruby]
+----
+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:
+
+[source,ruby]
+----
+pipe csv,
+     check(/Book.+Price/, :match?),
+     :parse,
+     map { |item| "#{item[:book]}: #{item[:price]}" }
+----
+
+Then the above would look like this using native Ruby:
+
+[source,ruby]
+----
+(
+  check(/Book.+Price/, :match?) >>
+  method(:parse) >>
+  map { |item| "#{item[:book]}: #{item[:price]}" }
+).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.
+
+=== 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.
+
+==== Basic
+
+The following are the basic (default) steps for building for more advanced functionality.
+
+===== As
+
+Allows you to message the input as different output. Example:
+
+[source,ruby]
+----
+pipe :a, as(:inspect)                  # Success ":a"
+pipe %i[a b c], as(:dig, 1)            # Success :b
+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:
+
+[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!"
+----
+
+===== 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:
+
+[source,ruby]
+----
+pipe :a, check(%i[a b], :include?)                  # Success :a
+pipe :a, check(%i[b c], :include?)                  # Failure :a
+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:
+
+[source,ruby]
+----
+pipe %i[a b c], fmap { |input| input.join "-" }           # Success "a-b-c"
+pipe Failure("Danger!"), fmap { |input| input.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:
+
+[source,ruby]
+----
+pipe :a, insert(:b)                  # Success [:a, :b]
+pipe :a, insert(:b, at: 0)           # Success [:b, :a]
+pipe %i[a c], insert(:b, at: 1)      # Success [:a, :b, :c]
+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.
+
+[source,ruby]
+----
+pipe %i[a b c], map(&:inspect)           # Success [":a", ":b", ":c"]
+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:
+
+[source,ruby]
+----
+pipe({a: 1}, merge(b: 2))             # Success {a: 1, b: 2}
+pipe "test", merge(b: 2)              # Success {step: "test", b: 2}
+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
+
+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:
+
+[source,ruby]
+----
+pipe "test", tee(Kernel, :puts, "Example.")
+
+# Example.
+# Success "test"
+
+pipe Failure("Danger!"), tee(Kernel, :puts, "Example.")
+
+# Example.
+# Failure "Danger!"
+----
+
+===== 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:
+
+[source,ruby]
+----
+Model = Struct.new :label, keyword_init: true do
+  include Dry::Monads[:result]
+
+  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
+
+Allows you to try an operation which may fail while catching the exception as a failure for further processing. 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!"
+----
+
+===== 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.
+
+[source,ruby]
+----
+function = -> input { Success input * 3 }
+
+pipe 3, use(function)                   # Success 9
+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.
+
+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.
+
+[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!"
+----
+
+==== Advanced
+
+Several options are available should you need to advance beyond the basic steps. Each is described in detail below.
+
+===== Procs
+
+You can always use a `Proc` as a custom step. Example:
+
+[source,ruby]
+----
+include Pipeable
+include Dry::Monads[:result]
+
+pipe :a,
+     insert(:b),
+     proc { Success "input_ignored" },
+     as(:to_sym)
+
+# Yields: Success :input_ignored
+----
+
+===== Lambdas
+
+In addition to procs, lambdas can be used too. Example:
+
+[source,ruby]
+----
+include Pipeable
+
+pipe :a,
+     insert(:b),
+     -> result { result.fmap { |input| input.join "_" } },
+     as(:to_sym)
+
+# Yields: Success :a_b
+----
+
+===== Methods
+
+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
+
+  private
+
+  def join(result) = result.fmap { |input| input.join "_" }
+end
+
+Demo.new.call :a  # Yields: 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.
+
+===== 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.
+. Register your custom step along side the existing default steps.
+
+Here's what this would look like:
+
+[source,ruby]
+----
+module CustomSteps
+  class Join < Pipeable::Steps::Abstract
+    def initialize(delimiter = "_", **)
+      super(**)
+      @delimiter = delimiter
+    end
+
+    def call(result) = result.fmap { |input| input.join delimiter }
+
+    private
+
+    attr_reader :delimiter
+  end
+end
+
+Pipeable::Steps::Container.register :join, CustomSteps::Join
+
+include Pipeable
+
+pipe :a, insert(:b), join, as(:to_sym)
+# Yields: Success :a_b
+
+pipe :a, insert(:b), join(""), as(:to_sym)
+# Yields: Success :ab
+----
+
+=== 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:
+
+[source,ruby]
+----
+require "containable"
+
+module CustomContainer
+  extend Containable
+
+  register :echo, -> result { result }
+  register :insert, Pipeable::Steps::Insert
+end
+
+include Pipeable[CustomContainer]
+
+pipe :a, echo, insert(:b)
+
+# Yields: Success [:a, :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.
+
+=== Composition
+
+Should you ever need to make a plain old Ruby object functionally composable, then you can _include_ the `Pipeable::Composable` module which will give you the necessary `\#>>`, `#<<`, and `#call` methods where you only need to implement the `#call` method.
+
+== Development
+
+To contribute, run:
+
+[source,bash]
+----
+git clone https://github.com/bkuhlmann/pipeable
+cd pipeable
+bin/setup
+----
+
+You can also use the IRB console for direct access to all objects:
+
+[source,bash]
+----
+bin/console
+----
+
+=== Architecture
+
+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.
+
+=== 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.
+* *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.
+** 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.
+
+=== Debugging
+
+If you need to debug (i.e. {debug_link}) your pipe, use a lambda. Example:
+
+[source,ruby]
+----
+pipe data,
+     check(/Book.+Price/, :match?),
+     -> result { binding.break },  # Breakpoint
+     :parse
+----
+
+The above breakpoint will allow you inspect the result of the `#check` step and/or build a modified result for passing to the subsequent `:parse` method step.
+
+=== Troubleshooting
+
+The following might be of aid to as you implement your own transactions.
+
+==== 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`).
+
+==== 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:
+
+[source,ruby]
+----
+# Valid
+pipe "https://www.wikipedia.org",
+     to(client, :get),
+     try(:parse, catch: HTTP::Error)
+
+# Invalid
+pipe "https://www.wikipedia.org",
+     to(client, :get)  # Missing comma.
+     try(:parse, catch: HTTP::Error)
+----
+
+== Tests
+
+To test, run:
+
+[source,bash]
+----
+bin/rake
+----
+
+== Benchmarks
+
+To view/compare performance, run:
+
+[source,bash]
+----
+bin/benchmark
+----
+
+💡 You can view current benchmarks at the end of the above file if you don't want to manually run them.
+
+== link:https://alchemists.io/policies/license[License]
+
+== link:https://alchemists.io/policies/security[Security]
+
+== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]
+
+== link:https://alchemists.io/policies/contributions[Contributions]
+
+== link:https://alchemists.io/projects/pipeable/versions[Versions]
+
+== link:https://alchemists.io/community[Community]
+
+== Credits
+
+* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].
+* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

data/lib/pipeable/composable.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pipeable
+  # Allows objects to be functionally composable.
+  module Composable
+    def >>(other) = method(:call) >> other
+
+    def <<(other) = method(:call) << other
+
+    def call = fail NotImplementedError, "`#{self.class.name}##{__method__}` must be implemented."
+  end
+end

data/lib/pipeable/definer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require "refinements/array"
+
+module Pipeable
+  # Defines the pipe and and associated step methods for an object.
+  class Definer < Module
+    include Dry::Monads[:result]
+
+    using Refinements::Array
+
+    def initialize container = Steps::Container, pipe: Pipe
+      super()
+      @container = container
+      @pipe = pipe
+      @instance_module = Class.new(Module).new
+    end
+
+    def included descendant
+      super
+      define_pipe
+      define_steps
+      descendant.include instance_module
+    end
+
+    private
+
+    attr_reader :container, :pipe, :instance_module
+
+    def define_pipe pipeline = pipe
+      instance_module.define_method :pipe do |input, *steps|
+        steps.each { |step| steps.supplant step, method(step) if step.is_a? Symbol }
+        pipeline.call(input, *steps)
+      end
+    end
+
+    def define_steps
+      instance_module.class_exec container do |dependencies|
+        dependencies.each_key do |name|
+          define_method name do |*positionals, **keywords, &block|
+            step = dependencies[name]
+            step.is_a?(Proc) ? step : step.new(*positionals, **keywords, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pipeable/pipe.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Pipeable
+  # Provids low-level functionality processing a sequence of steps.
+  Pipe = lambda do |input, *steps|
+    fail ArgumentError, "Pipe must have at least one step." if steps.empty?
+
+    result = input.is_a?(Dry::Monads::Result) ? input : Dry::Monads::Success(input)
+
+    steps.reduce(&:>>).call result
+  rescue NoMethodError
+    raise TypeError, "Step must be functionally composable and answer a monad."
+  end
+end

data/lib/pipeable/steps/abstract.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require "marameters"
+
+module Pipeable
+  module Steps
+    # Provides a custom step blueprint.
+    class Abstract
+      include Dry::Monads[:result]
+      include Composable
+
+      def initialize *positionals, **keywords, &block
+        @base_positionals = positionals
+        @base_keywords = keywords
+        @base_block = block
+        @marameters = Marameters
+      end
+
+      protected
+
+      attr_reader :base_positionals, :base_keywords, :base_block, :marameters
+    end
+  end
+end

data/lib/pipeable/steps/as.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pipeable
+  module Steps
+    # Allows result to be messaged as a callable.
+    class As < Abstract
+      def call result
+        result.fmap { |operation| operation.public_send(*base_positionals, **base_keywords) }
+      end
+    end
+  end
+end

data/lib/pipeable/steps/bind.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+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 }
+    end
+  end
+end