transactable 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1273b58f01b4687af4c24782ecd585c4c57ce7bbb434195e8390d84c7561ad1b
-  data.tar.gz: 2b60852cb72d7039c12f27314dae85950c78a896339a2cd15372df7476f8dbc5
+  metadata.gz: c58179b7d8fa50cf463e7cbbf0fbaf83382d10478df233121400f110fcfee5dd
+  data.tar.gz: 417af3965b8ab1fb1421b619aa117abc129e173cea03e5931204e277250086c5
 SHA512:
-  metadata.gz: 7c388a05f4f11b7cd5106679ddb77a0fcd60de068f528f4922cb27b85286e3e0d04aa4b457e4bacc423f178542876896c722b0bf203a0621565bfc199db7828a
-  data.tar.gz: c91bf7b5d36bea0ebf70481d1c62e45db30be3afc5f5dc5425ab2eda9be65cafc5d032efad630e942a4902b135d92c491543e798058119b9808b150c56f8d933
+  metadata.gz: '029ca350dbfd66cf6e076887456434903c76c302b4906ea6f6c93371d2be0ed5c51b5035445e3519c7c6f72114c62f6285704c5ff520eb6af822d6f27ffc484c'
+  data.tar.gz: 6801347ce93c433a9a8a3fa28b03ce1ac47b9ee8c68bb5b37cab1b3fd222abd3d461af7164de2e99f85000ae977401c00943c094787f10c6a77871256a2f73a6

data/README.adoc

@@ -1,14 +1,16 @@
+:toc: macro
+:toclevels: 5
+:figure-caption!:
+
 :command_pattern_link: link:https://www.alchemists.io/articles/command_pattern[Command Pattern]
+:function_composition_link: link:https://www.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]
 
-:toc: macro
-:toclevels: 5
-:figure-caption!:
-
 = 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.
@@ -25,6 +27,7 @@ toc::[]
 == Requirements
 
 . link:https://www.ruby-lang.org[Ruby].
+. A strong understanding of {function_composition_link}.
 
 == Setup
 
@@ -138,9 +141,13 @@ The only problem with native function composition is that it reads backwards by
 
 === Steps
 
-There are multiple, default, steps you can use to compose your transactional 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 describes each step in detail where you can mix and match as makes sense.
+There are several ways to compose steps for your transactional 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
 
-==== As
+The following are the basic (default) steps for building for more advanced functionality.
+
+===== As
 
 Allows you to message the input as different output. Example:
 
@@ -151,7 +158,7 @@ pipe %i[a b c], as(:dig, 1)            # Success :b
 pipe Failure("Danger!"), as(:inspect)  # Failure "Danger!"
 ----
 
-==== Bind
+===== 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:
 
@@ -162,7 +169,7 @@ pipe %i[a b c], bind { |input| Failure input }                     # Failure [:a
 pipe Failure("Danger!"), bind { |input| Success input.join("-") }  # Failure "Danger!"
 ----
 
-==== Check
+===== 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:
 
@@ -173,7 +180,7 @@ 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:
 
@@ -183,7 +190,7 @@ pipe %i[a b c], fmap { |input| input.join "-" }           # Success "a-b-c"
 pipe Failure("Danger!"), fmap { |input| input.join "-" }  # Failure "Danger!"
 ----
 
-==== Insert
+===== 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:
 
@@ -195,7 +202,7 @@ 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 enumerable and wraps native link:https://rubyapi.org/o/enumerable#method-i-map[Enumerable#map] functionality.
 
@@ -205,7 +212,7 @@ 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:
 
@@ -217,7 +224,7 @@ pipe "test", merge(as: :a, b: 2)      # Success {a: "test", b: 2}
 pipe Failure("Danger!"), merge(b: 2)  # Failure "Danger!"
 ----
 
-==== Orr
+===== 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.
 
@@ -232,7 +239,7 @@ pipe Failure("Danger!"), orr { Success "Resolved" }              # Success "Reso
 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. Example:
 
@@ -249,7 +256,7 @@ 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:
 
@@ -265,7 +272,7 @@ 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 the exception as a failure for further processing. Example:
 
@@ -276,7 +283,7 @@ pipe "test", try(:invalid, catch: NoMethodError)         # Failure "undefined me
 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.
 
@@ -288,7 +295,7 @@ pipe 3, use(function)                   # Success 9
 pipe Failure("Danger!"), use(function)  # Failure "Danger!"
 ----
 
-==== Validate
+===== 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.
 
@@ -303,11 +310,11 @@ pipe({label: "Test"}, validate(schema, as: nil))  # Success #<Dry::Schema::Resul
 pipe Failure("Danger!"), validate(schema)         # Failure "Danger!"
 ----
 
-=== Customization
+==== Advanced
 
-Should none of the above default steps be to your liking, you have several alternatives available for further customization. Each is described in detail below.
+Several options are available should you need to advance beyond the basic steps. Each is described in detail below.
 
-==== Procs
+===== Procs
 
 You can always use a `Proc` as a custom step. Example:
 
@@ -326,7 +333,7 @@ pipe :a,
 
 ℹ️ While procs are effective, you are limited in what you can do with them in terms of additional behavior and instrumentation support.
 
-==== Lambdas
+===== Lambdas
 
 In addition to procs, lambdas can be used too. Example:
 
@@ -344,7 +351,7 @@ pipe :a,
 
 ℹ️ Lambdas are a step up from procs but, like procs, you are limited in what you can do with them in terms of additional behavior and instrumentation support.
 
-==== Methods
+===== Methods
 
 Methods -- in addition to procs and lambdas -- are the _preferred_ way to add custom steps due to the concise syntax. Example:
 
@@ -370,9 +377,9 @@ Demo.new.call :a  # Yields: Success :a_b
 
 ℹ️ 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.
 
-==== Steps
+===== Custom
 
-If you'd like to define a more permanent and reusable step, you can register a custom step which requires you to:
+If you'd like to define permanent and reusable step, 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.
@@ -386,7 +393,7 @@ module MySteps
     prepend Transactable::Instrumentable
 
     def initialize delimiter = "_", **dependencies
-      super
+      super(**dependencies)
       @delimiter = delimiter
     end
 
@@ -417,9 +424,9 @@ pipe :a,
 # Yields: Success :ab
 ----
 
-==== Containers
+=== Containers
 
-Should you not want the default 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 `.with` when including transactable behavior. Example:
+Should you not want the basic steps, need custom steps, or a hybrid of basic and custom steps, you can define your own container and provide it as an argument to `.with` when including transactable behavior. Example:
 
 [source,ruby]
 ----
@@ -488,10 +495,12 @@ There is a lot you can do with instrumentation so check out the {dry_events_link
 
 == Development
 
-To set up the project, run:
+To contribute, run:
 
 [source,bash]
 ----
+git clone https://github.com/bkuhlmann/transactable
+cd transactable
 bin/setup
 ----
 
@@ -506,7 +515,7 @@ bin/console
 
 The architecture of this gem is built on top of the following concepts and gems:
 
-* *Function Composition*: 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.
+* {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.
@@ -519,34 +528,39 @@ The architecture of this gem is built on top of the following concepts and gems:
 * *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 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 initial positional, keyword, and block arguments. These variables are prefixed with `initial_*` in order to not conflict with subclasses which might only want to use non-prefixed variables for convenience.
+** 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.
 
-== Tests
+=== Debugging
 
-To test, run:
+If you need to debug (i.e. {debug_link}) your pipe, use a lambda. Example:
 
-[source,bash]
+[source,ruby]
 ----
-bundle exec rake
+pipe data,
+     check(/Book.+Price/, :match?),
+     -> result { binding.break },    # Breakpoint
+     method(:parse),
 ----
 
-== Troubleshooting
+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.
+
+=== Troubleshooting
 
 The following might be of aid to as you implement your own transactions.
 
-=== Type Errors
+==== Type Errors
 
 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 doesn't answer a result monad (i.e. `Success some_value` or `Failure some_value`).
 
-=== No Method Errors
+==== No Method Errors
 
 If you get a `NoMethodError: undefined method `success?` exception, it might mean that you forgot to add a comma after one of your steps. Example:
 
@@ -563,6 +577,15 @@ pipe "https://www.wikipedia.org",
      try(:parse, catch: HTTP::Error)
 ----
 
+== Tests
+
+To test, run:
+
+[source,bash]
+----
+bundle exec rake
+----
+
 == link:https://www.alchemists.io/policies/license[License]
 
 == link:https://www.alchemists.io/policies/security[Security]

data/lib/transactable/steps/abstract.rb

@@ -8,9 +8,7 @@ module Transactable
     class Abstract
       DEPENDENCIES = %i[instrument marameters].freeze
 
-      # rubocop:todo Layout/ClassStructure
       include Import[*DEPENDENCIES]
-      # rubocop:enable Layout/ClassStructure
       include Dry::Monads[:result]
       include Composable
 

data/transactable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "transactable"
-  spec.version = "0.0.0"
+  spec.version = "0.1.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://www.alchemists.io/projects/transactable"
@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = "~> 3.1"
 
-  spec.add_dependency "dry-container", "~> 0.10"
+  spec.add_dependency "dry-container", "~> 0.11"
   spec.add_dependency "dry-events", "~> 0.3"
   spec.add_dependency "dry-monads", "~> 1.4"
   spec.add_dependency "infusible", "~> 0.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transactable
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,7 +28,7 @@ cert_chain:
   CxDe2+VuChj4I1nvIHdu+E6XoEVlanUPKmSg6nddhkKn2gC45Kyzh6FZqnzH/CRp
   RFE=
   -----END CERTIFICATE-----
-date: 2022-09-10 00:00:00.000000000 Z
+date: 2022-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-container
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.11'
 - !ruby/object:Gem::Dependency
   name: dry-events
   requirement: !ruby/object:Gem::Requirement