transactable 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 404d0f0a1a1fb991362a94978a3c75d0867bbbe89d929760c367ccac052199fb
-  data.tar.gz: 0e4ecc36c6a2d5c7ec907b07b89725603441f597e8b1e420e9547ea2fb9572ca
+  metadata.gz: d17683ad67f8fca4a79b13497ad7e19c46b1dd0614783e4296cbe551bae7f6be
+  data.tar.gz: 22c0954b70991d59a4637548580f692db6413236e35393b5d352bc8ef9acebee
 SHA512:
-  metadata.gz: 0e5c5320afa0b195e513caff0ca9e00f2a03671c5aa3816104f0e45f93f01ac5ebb0afb72e40a32a747652e39a651e0f4891c76de6a6794080e0cbc2918f81a0
-  data.tar.gz: 1ce19a3efd0c0585b01f8cc2c1558d875af07fe05e32042d993522655c3c0bcb50ff1ba4622a5249be2d994339893828e2dfff7cfb1a492758706c0fa6d96fff
+  metadata.gz: 26348144c79119b8eeb8748ca30f6af243a1bb8f554bfda111dbcf037440338573c14610ae7138b977edbac4db8375cfd9797409012a871087ee5c6aa51eab4a
+  data.tar.gz: 7ade67cf3843ad63694575e27269269fe5cb4043673465a254095a8468c6cf59e74a1e7455d6e34aa63a0934b4ab380ece8cbd3971ee2124f660d551e3b715bf

data/README.adoc

@@ -3,26 +3,31 @@
 :figure-caption!:
 
 :command_pattern_link: link:https://alchemists.io/articles/command_pattern[Command Pattern]
-:function_composition_link: link:https://alchemists.io/articles/ruby_function_composition[Function Composition]
 :debug_link: link:https://github.com/ruby/debug[Debug]
 :dry_container_link: link:https://dry-rb.org/gems/dry-container[Dry Container]
 :dry_events_link: link:https://dry-rb.org/gems/dry-events[Dry Events]
 :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]
 
 = Transactable
 
-A DSL for transactional workflows built atop function composition. This allows you to write in a syntax that builds upon -- and abstracts away -- native function composition support while allowing you to cleanly read the code from left-to-right or top-to-bottom sequentially.
+A DSL for transactional 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.
 
 toc::[]
 
 == Features
 
-* Built on top of native function composition capabilities.
-* Customizable with additional or entirely different steps.
-* Chainable where you can couple together multiple transactions to build more complex architectures.
-* Instrumentable so you can track metrics, log usage, and much more.
+* 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.
+* Supports instrumentation for tracking metrics, logging usage, and much more.
+* Compatible with {dry_monads_link}.
+* Compatible with {infusible_link}.
 
 == Requirements
 
@@ -80,7 +85,7 @@ class Demo
   def call data
     pipe data,
          check(/Book.+Price/, :match?),
-         method(:parse),
+         :parse,
          map { |item| "#{item[:book]}: #{item[:price]}" }
   end
 
@@ -98,21 +103,17 @@ class Demo
 end
 ----
 
-The above allows the `Demo#call` method to be a _transactional_ series of composed steps which may pass or fail where each step is piped together via {dry_monads_link}. This is the essence of the _Railway Pattern_.
+The above allows `Demo#call` to be a _transactional_ 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]
 ----
-csv = <<~CSV
+Demo.new.call <<~CSV
   Book,Author,Price,At
   Mystics,urGoh,10.50,2022-01-01
   Skeksis,skekSil,20.75,2022-02-13
 CSV
-
-demo = Demo.new
-
-demo.call csv
 ----
 
 The computed result is a success with each book listing a price:
@@ -123,22 +124,22 @@ Success ["Mystics: 10.50", "Skeksis: 20.75"]
 
 === Pipe
 
-Once you've included the `Transactable` module within your class, the `#pipe` method is available to you and is how you build a series of steps for processing. The method signature is:
+Once you've included the `Transactable` 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_.
+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 which means if this code were to be rewritten:
+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?),
-     method(:parse),
+     :parse,
      map { |item| "#{item[:book]}: #{item[:price]}" }
 ----
 
@@ -153,7 +154,7 @@ Then the above would look like this using native Ruby:
 ).call Success(csv)
 ----
 
-The only problem with native function composition is that it reads backwards by passing in 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 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
 
@@ -379,7 +380,7 @@ class Demo
   def call input
     pipe :a,
          insert(:b),
-         method(:join),
+         :join,
          as(:to_sym)
   end
 
@@ -391,6 +392,8 @@ 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.
+
 ℹ️ You won't be able to instrument these method calls (unless you inject instrumentation) but are great when needing additional behavior between the default steps.
 
 ===== Custom
@@ -406,8 +409,6 @@ Here's what this would look like:
 ----
 module MySteps
   class Join < Transactable::Steps::Abstract
-    prepend Transactable::Instrumentable
-
     def initialize(delimiter = "_", **)
       super(**)
       @delimiter = delimiter
@@ -425,18 +426,10 @@ Transactable::Steps::Container.register(:join) { MySteps::Join }
 
 include Transactable
 
-pipe :a,
-     insert(:b),
-     join,
-     as(:to_sym)
-
+pipe :a, insert(:b), join, as(:to_sym)
 # Yields: Success :a_b
 
-pipe :a,
-     insert(:b),
-     join(""),
-     as(:to_sym)
-
+pipe :a, insert(:b), join(""), as(:to_sym)
 # Yields: Success :ab
 ----
 
@@ -505,7 +498,7 @@ step: {:name=>"Transactable::Steps::Map", :arguments=>[[], {}, #<Proc:0x00000001
 step.success: {:name=>"Transactable::Steps::Map", :value=>["Mystics: 10.50", "Skeksis: 20.75"], :arguments=>[[], {}, #<Proc:0x0000000106405900 (irb):15>]}
 ....
 
-Finally, the `Transactable::Instrumentable` module is available should you need to _prepend_ instrumentation to any of your classes.
+Finally, the `Transactable::Instrumentable` module is available should you need to _prepend_ instrumentation to any of your class' `#call` methods.
 
 There is a lot you can do with instrumentation so check out the {dry_events_link} documentation for further details.
 
@@ -532,12 +525,12 @@ bin/console
 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.
-* {dry_container_link} - Allows related dependencies to be grouped together for injection.
-* {dry_events_link} - Allows all steps to be observable so you can subscribe to any/all events for metric, logging, and other capabilities.
-* {dry_monads_link} - Critical to ensuring the entire pipeline of steps adhere to the _Railway Pattern_ and leans heavily on the `Result` object.
-* link:https://dry-rb.org/gems/dry-transaction[Dry Transaction] - Specifically the concept of a _step_ where each step can have an _operation_ and/or _input_ to be processed. Instrumentation is used as well so you can have rich metrics, logging, or any other kind of observer wired up as desired.
-* link:https://alchemists.io/projects/infusible[Infusible] - Coupled with {dry_container_link}, allows dependencies to be automatically injected.
-* 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.
+* {dry_container_link}: Allows related dependencies to be grouped together for injection as desired.
+* {dry_events_link}: Allows all steps to be observable so you can subscribe to any/all events for metric, logging, and other capabilities.
+* {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://dry-rb.org/gems/dry-transaction[Dry Transaction]: Specifically the concept of a _step_ where each step can have an _operation_ and/or _input_ to be processed. Instrumentation is used as well so you can have rich metrics, logging, or any other kind of observer wired up as desired.
+* link:https://alchemists.io/projects/infusible[Infusible]: Coupled with {dry_container_link}, allows dependencies to be automatically injected.
+* 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
 
@@ -546,7 +539,6 @@ The architecture of this gem is built on top of the following concepts and gems:
 * *Steps*
 ** Inherit from the `Abstract` class in order to gain monad, composition, and dependency behavior. Any dependencies injected are automatically filtered out so all subclasses have direct and clean 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.
-** Prepend `Instrumentable` to gain instrumentation behavior and remain consistent with existing steps. This includes adding the `with instrumentation` RSpec shared context when testing too.
 ** 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.
@@ -560,7 +552,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
-     method(:parse),
+     :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 `#method` step.
@@ -573,7 +565,7 @@ The following might be of aid to as you implement your own transactions.
 
 If you get a `TypeError: Step must be functionally composable and answer a monad`, it means:
 
-. The step must be a `Proc` or some object which responds to `\#>>`, `#<<`, and `#call`.
+. 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

data/lib/transactable/pipe.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Transactable
+  # Provids low-level functionality that can process 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/transactable/pipeable.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 require "dry/monads"
+require "refinements/arrays"
 
 module Transactable
   # Allows any object to pipe sequential steps together which can be composed into a single result.
   class Pipeable < Module
-    def initialize steps = Steps::Container
+    include Dry::Monads[:result]
+
+    using Refinements::Arrays
+
+    def initialize steps = Steps::Container, pipe: Pipe
       super()
       @steps = steps
+      @pipe = pipe
       @instance_module = Class.new(Module).new
     end
 
@@ -20,17 +26,14 @@ module Transactable
 
     private
 
-    attr_reader :steps, :instance_module
+    attr_reader :steps, :pipe, :instance_module
 
     def define_pipe
-      instance_module.define_method :pipe do |input, *steps|
-        fail ArgumentError, "Transaction must have at least one step." if steps.empty?
+      local_pipe = pipe
 
-        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."
+      instance_module.define_method :pipe do |input, *steps|
+        steps.each { |step| steps.supplant step, method(step) if step.is_a? Symbol }
+        local_pipe.call(input, *steps)
       end
     end
 

data/lib/transactable/steps/abstract.rb

@@ -12,6 +12,11 @@ module Transactable
       include Dry::Monads[:result]
       include Composable
 
+      def self.inherited descendant
+        super
+        descendant.prepend Instrumentable
+      end
+
       def initialize *positionals, **keywords, &block
         super(**keywords.slice(*DEPENDENCIES))
         @base_positionals = positionals

data/lib/transactable/steps/as.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Allows result to be messaged as a callable.
     class As < Abstract
-      prepend Instrumentable
-
       def call result
         result.fmap { |operation| operation.public_send(*base_positionals, **base_keywords) }
       end

data/lib/transactable/steps/bind.rb

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

data/lib/transactable/steps/check.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Checks if operation is true and then answers success (passthrough) or failure (with argument).
     class Check < Abstract
-      prepend Instrumentable
-
       def initialize(operation, message, **)
         super(**)
         @operation = operation

data/lib/transactable/steps/fmap.rb

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

data/lib/transactable/steps/insert.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Inserts elements before, after, or around input.
     class Insert < Abstract
-      prepend Instrumentable
-
       LAST = -1
 
       def initialize(*positionals, at: LAST, **)

data/lib/transactable/steps/map.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Maps over a collection, processing each element, and answering a new result.
     class Map < Abstract
-      prepend Instrumentable
-
       def call(result) = result.fmap { |collection| collection.map(&base_block) }
     end
   end

data/lib/transactable/steps/merge.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Merges initialized attributes with step argument for use by a subsequent step.
     class Merge < Abstract
-      prepend Instrumentable
-
       def initialize as: :step, **keywords
         super(**keywords)
         @as = as

data/lib/transactable/steps/or.rb

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

data/lib/transactable/steps/tee.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Messages operation, without any response checks, while passing input through as output.
     class Tee < Abstract
-      prepend Instrumentable
-
       def initialize(operation, *, **)
         super(*, **)
         @operation = operation

data/lib/transactable/steps/to.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Delegates to a non-callable operation which automatically wraps the result if necessary.
     class To < Abstract
-      prepend Instrumentable
-
       def initialize(operation, message, **)
         super(**)
         @operation = operation

data/lib/transactable/steps/try.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Messages a risky operation which may pass or fail.
     class Try < Abstract
-      prepend Instrumentable
-
       def initialize *positionals, catch:, **keywords
         super(*positionals, **keywords)
         @catch = catch

data/lib/transactable/steps/use.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Use another transaction -- or any command -- which answers a result.
     class Use < Abstract
-      prepend Instrumentable
-
       def initialize(operation, **)
         super(**)
         @operation = operation

data/lib/transactable/steps/validate.rb

@@ -4,8 +4,6 @@ module Transactable
   module Steps
     # Validates a result via a callable operation.
     class Validate < Abstract
-      prepend Instrumentable
-
       def initialize(operation, as: :to_h, **)
         super(**)
         @operation = operation

data/lib/transactable.rb

@@ -6,7 +6,7 @@ Zeitwerk::Loader.for_gem.setup
 
 # Main namespace.
 module Transactable
-  def self.included(klass) = klass.include Pipeable.new
+  def self.included(descendant) = descendant.include Pipeable.new
 
   def self.with(...) = Pipeable.new(...)
 end

data/transactable.gemspec

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transactable
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  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: 2023-07-23 00:00:00.000000000 Z
+date: 2023-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-container
@@ -152,6 +152,7 @@ files:
 - lib/transactable/import.rb
 - lib/transactable/instrument.rb
 - lib/transactable/instrumentable.rb
+- lib/transactable/pipe.rb
 - lib/transactable/pipeable.rb
 - lib/transactable/steps/abstract.rb
 - lib/transactable/steps/as.rb
@@ -195,7 +196,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.17
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: A domain specific language for functionally composable transactional workflows.

metadata.gz.sig

@@ -1,4 +1 @@
-SHW�[�9�"��q�j�A�F�zM��#��,5���)����E�[�iN�'|�q:��3�_�~d8�'��E6[�(ڂ�j�F��Q��[y��u*>0��)�� әC�&R~BLGP��
-��d>�-�_y!�g��o��pP�:��.a1&�z���"eF7P���[ ��r��r�%d�/=��1>�P`Je����"��"�&w��nR?g�	��1���\�������~�;~��
-*�'N?�_g�n��hsU�^�/	��pҷ�;U��jP6h���C_4KS^'��n���9^V�����輇XC���y��u8���"`��ARx���0�Ջ�M��]vkU�~�{f
-�,�m�*&�j�e2fͨI��4���v
+}��6��,�������-Kش�aP�&d���Dž����x��)���`����[Y��#�r��y��k�s1r�ծ8�Y	��-�����_L� �0�Ԗ09�Z��m�G�ﳦ0p���q+�U���K(
&l��&�GKi��Ph��e��r䞪��n`5��ޯb|�eY��ˑxP��K`g�Q��x~ΰ�Xu��*����G���7��P�תuql�C����_�}O�y;��B���g�h#��)���[.p3�_��������bEm���P��x0W��q5��0�.a������d;�qKfbe���$ !2��2���N�o�Mɷ'�8G1-�g��vB��'���#ؼR�"�NL�F�p*���]��?˘A��ڪ��