pipeable 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27d7116b19ded0ad3f247500aed8260a70132154dcd1e5df7a372e3c5c8a6dac
-  data.tar.gz: 23a044ebbc9a350c513e6ed369f02b25159d017aef9ce449c1f97889de323ae8
+  metadata.gz: a09d8c73240d45d6a6a4219a6871a69ceb9ee77aa9387ac90b394571e2bfd24e
+  data.tar.gz: 3f0453d8efc7751c29c1f9ddd4f6aa7f5803478efa855d00ce913a434f2c4480
 SHA512:
-  metadata.gz: 1eb4c1308d2635ef89d5fc0cc7355b657a0527687108a2af1b2967ad87e659b7417a0e3c53ee4fdb30ce7d3346d7aff58914fc38adb25a39f4d4743f6296c2dd
-  data.tar.gz: 90a2b478afbc7bb3895cd5478365de3d00e7f4ebbaa6be401c6145cdb2757030d8b29a658acbf554146b337542591a0f03a195143b52bc36efe91e75caf6a5c8
+  metadata.gz: bb6a5ff6689c93114eec07926f389d643ea26dcde8f157dda4a444a9236c25b959d2e52ae7d6479c0f3fd1911b208bbdaf148317d2915d68a99497b80b22329c
+  data.tar.gz: 610564b7b2de774b517996d524d189cf4ce9439a25df29a24c48ab0adf7fdd3da8acbb9bee573ba4a13fd12713124e6f6a4525627127876a8886607271c623c5

data/README.adoc

@@ -171,20 +171,20 @@ The following are the basic (default) steps for building custom pipes for which
 
 ===== 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.
+Short for _alternate_ which is the `or` branch of conditional logic. This 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 %i[a b c], alt { |object| Success "Pass!" }                   # Success [:a, :b, :c]
 pipe Failure("Danger!"), alt { Success "Resolved" }                # Success "Resolved"
 pipe Failure("Danger!"), alt { |object| Failure "Big #{object}" }  # Failure "Big Danger!"
 ----
 
 ===== amap
 
-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.
+Short for _alternate map_ which 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.
 
 Accepts and answers a failure. Example:
 
@@ -196,7 +196,7 @@ 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.
+Allows you to message an object _as_ a different result. The first argument is always the method to message but additional positional and/or keyword arguments can be passed along if the method accepts them.
 
 Accepts and answers a success. Example:
 
@@ -209,7 +209,7 @@ pipe Failure("Danger!"), as(:inspect)  # Failure "Danger!"
 
 ===== 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 upon success only. You are responsible for answering a success or failure accordingly. This is a convenience wrapper to native {dry_monads_link} `#bind` functionality.
 
 Accepts a success while answering either a success or failure. Example:
 
@@ -235,7 +235,7 @@ pipe Failure("Danger!"), check(%i[a b], :include?)  # Failure "Danger!"
 
 ===== fmap
 
-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.
+Short for _function map_ which 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:
 
@@ -247,7 +247,9 @@ pipe Failure("Danger!"), fmap { |object| object.join "-" }  # Failure "Danger!"
 
 ===== 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 one or more elements 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 to a subsequent step.
+
+⚠️ If given an array from the previous step, this step will mutate it.
 
 Accepts and answers a success. Example:
 
@@ -256,6 +258,9 @@ Accepts and answers a success. Example:
 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 :a, insert(:b, :c)              # Success [:a, :b, :c]
+pipe :a, insert([:b])                # Success [:a, [:b]]
+pipe :a, insert({b: 2})              # Success [:a, {b: 2}]
 pipe Failure("Danger!"), insert(:b)  # Failure "Danger!"
 ----
 
@@ -268,6 +273,7 @@ Accepts and answers a success. Example:
 [source,ruby]
 ----
 pipe %i[a b c], map(&:inspect)           # Success [":a", ":b", ":c"]
+pipe %i[a b c], map { "#{it}1" }         # Success ["a1", "b1", "c1"]
 pipe Failure("Danger!"), map(&:inspect)  # Failure "Danger!"
 ----
 
@@ -275,19 +281,22 @@ pipe Failure("Danger!"), map(&:inspect)  # Failure "Danger!"
 
 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.
 
+⚠️ If given a hash from the previous step, this step will mutate it.
+
 Accepts and answers a success. 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({a: 1}, merge(b: 2, c: 3))       # Success {a: 1, b: 2, c: 3}
+pipe "demo", merge(b: 2)              # Success {step: "demo", b: 2}
+pipe "demo", merge(as: :a, b: 2)      # Success {a: "demo", b: 2}
 pipe Failure("Danger!"), merge(b: 2)  # Failure "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.
+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] Bash program.
 
 Accepts either a success or failure and passes the result through while allowing you to execute arbitrary behavior. Example:
 
@@ -361,7 +370,7 @@ pipe Failure("Danger!"), use(function)  # Failure "Danger!"
 
 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`.
 
-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's value is `nil`. Use `:to_h`, for example, as the value for automatic casting to a `Hash`. You can also pass any value to the `:as` key which is a valid method that the contract's 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:
 
@@ -637,7 +646,7 @@ The following might be of aid to as you implement your own pipes.
 If you get a `TypeError: Step must be functionally composable and answer a monad`, it means:
 
 . 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`).
+. The step doesn't answer a result monad (i.e. `Success` or `Failure`).
 
 ==== No Method Errors
 

data/lib/pipeable/steps/insert.rb

@@ -6,22 +6,21 @@ module Pipeable
     class Insert < Abstract
       LAST = -1
 
-      def initialize(*positionals, at: LAST, **)
-        super(*positionals, **)
-        @value = positionals.empty? ? base_keywords : positionals.flatten
+      def initialize(*, at: LAST)
+        super(*)
         @at = at
       end
 
       def call result
         result.fmap do |object|
           cast = object.is_a?(Array) ? object : [object]
-          value.is_a?(Array) ? cast.insert(at, *value) : cast.insert(at, value)
+          cast.insert(at, *base_positionals)
         end
       end
 
       private
 
-      attr_reader :value, :at
+      attr_reader :at
     end
   end
 end

data/pipeable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "pipeable"
-  spec.version = "1.0.0"
+  spec.version = "1.1.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/pipeable"
@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = "~> 3.4"
   spec.add_dependency "containable", "~> 1.0"
   spec.add_dependency "dry-monads", "~> 1.6"
-  spec.add_dependency "marameters", "~> 4.0"
+  spec.add_dependency "marameters", "~> 4.1"
   spec.add_dependency "refinements", "~> 13.0"
   spec.add_dependency "zeitwerk", "~> 2.7"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pipeable
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -34,7 +34,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-12-28 00:00:00.000000000 Z
+date: 2025-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: containable
@@ -70,14 +70,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.1'
 - !ruby/object:Gem::Dependency
   name: refinements
   requirement: !ruby/object:Gem::Requirement