plumb 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6e1738eecc88a18de722a0411d2abb34fcad6bfe9dea7722d49b808b2d040d4
-  data.tar.gz: 2038adbc2b2eacea52a6651d7e4f4332d6a280ce90f2725ea9fd91c9761f527c
+  metadata.gz: 308e76909c6466b0a6c2cc9443498a267186344b9508b8f485975479e0ff165a
+  data.tar.gz: 8498e5a4619437b8f91b3baae4b2d208c27031a5617dba174d52893cd4e3a54a
 SHA512:
-  metadata.gz: ad40a1e6a2f1f1c4ae49f67448b210f87e0d23c3edf3fbd8b1ba5d408040dfc05801e15c4ef4126a373a94ea808cadad022528473cc3d5e5036e35b1b3c526ae
-  data.tar.gz: 5a3aab711081e9a5b9531b7d792ebbe11b140bd39192fea1f64365c65aae5adbb24649bd56c395ac13accf50c377b7d1c6d94654077cef59e00e91af2d9a444f
+  metadata.gz: d41ebdf232099770d04abc85f81ead1e8dc1d4f55eb1bc9265484401cfd0418e984d7cf97a67a6ef452d67f05c3f92e66e3e3fe64f11622acbb89e5c223c73b1
+  data.tar.gz: 5e2749e954fae81753d63d6d27b95a53f239b5ac6ad776755646d794fe7819b56087f48bd99394aeab2f40c64d45606cc413a1475512f6943279d51a7dd7d2b2

data/README.md

@@ -10,6 +10,8 @@ If you're after raw performance and versatility I strongly recommend you use the
 
 For a description of the core architecture you can read [this article](https://ismaelcelis.com/posts/composable-pipelines-in-ruby/).
 
+Some use cases in the [examples directory](https://github.com/ismasan/plumb/tree/main/examples)
+
 ## Installation
 
 Install in your environment with `gem install plumb`, or in your `Gemfile` with
@@ -58,7 +60,7 @@ module Types
 end
 
 Types::String.parse("hello") # => "hello"
-Types::String.parse(10) # raises "Must be a String" (Plumb::TypeError)
+Types::String.parse(10) # raises "Must be a String" (Plumb::ParseError)
 ```
 
 Plumb ships with basic types already defined, such as `Types::String` and `Types::Integer`. See the full list below.
@@ -75,7 +77,7 @@ Email.parse('hello@server.com') # 'hello@server.com'
 # Or a Range
 AdultAge = Types::Integer[18..]
 AdultAge.parse(20) # 20
-AdultAge.parse(17) # raises "Must be within 18.."" (Plumb::TypeError)
+AdultAge.parse(17) # raises "Must be within 18.."" (Plumb::ParseError)
 
 # Or literal values
 Twenty = Types::Integer[20]
@@ -113,7 +115,7 @@ result.errors # 'must be an Integer'
 
 ```ruby
 Types::Integer.parse(10) # 10
-Types::Integer.parse('10') # raises Plumb::TypeError
+Types::Integer.parse('10') # raises Plumb::ParseError
 ```
 
 
@@ -133,7 +135,7 @@ joe = User.parse({ name: 'Joe', email: 'joe@email.com', age: 20}) # returns vali
 Users.parse([joe]) # returns valid array of user hashes
 ```
 
-More about [Types::Array](#typeshash) and [Types::Array](#typesarray). There's also [tuples](#typestuple), [hash maps](#hash-maps) and [data structs](#typesdata), and it's possible to create your own composite types.
+More about [Types::Hash](#typeshash) and [Types::Array](#typesarray). There's also [tuples](#typestuple), [hash maps](#hash-maps), [data structs](#typesdata) and [streams](#typesstream), and it's possible to create your own composite types.
 
 ### Type composition
 
@@ -161,7 +163,7 @@ In other words, `A >> B` means "if A succeeds, pass its result to B. Otherwise r
 StringOrInt = Types::String | Types::Integer
 StringOrInt.parse('hello') # "hello"
 StringOrInt.parse(10) # 10
-StringOrInt.parse({}) # raises Plumb::TypeError
+StringOrInt.parse({}) # raises Plumb::ParseError
 ```
 
 Custom default value logic for non-emails
@@ -230,6 +232,13 @@ You can see more use cases in [the examples directory](https://github.com/ismasa
 * `Types::Numeric`
 * `Types::String`
 * `Types::Hash`
+* `Types::UUID::V4`
+* `Types::Email`
+* `Types::Date`
+* `Types::Time`
+* `Types::URI::Generic`
+* `Types::URI::HTTP`
+* `Types::URI::File`
 * `Types::Lax::Integer`
 * `Types::Lax::String`
 * `Types::Lax::Symbol`
@@ -237,8 +246,13 @@ You can see more use cases in [the examples directory](https://github.com/ismasa
 * `Types::Forms::Nil`
 * `Types::Forms::True`
 * `Types::Forms::False`
+* `Types::Forms::Date`
+* `Types::Forms::Time`
+* `Types::Forms::URI::Generic`
+* `Types::Forms::URI::HTTP`
+* `Types::Forms::URI::File`
 
-TODO: date and datetime, UUIDs, Email, others.
+TODO: datetime, others.
 
 ### Policies
 
@@ -261,7 +275,7 @@ Allow `nil` values.
 nullable_str = Types::String.nullable
 nullable_srt.parse(nil) # nil
 nullable_str.parse('hello') # 'hello'
-nullable_str.parse(10) # TypeError
+nullable_str.parse(10) # ParseError
 ```
 
 Note that this just encapsulates the following composition:
@@ -522,7 +536,52 @@ CSVLine = Types::String.split(/\s*;\s*/)
 CSVLine.parse('a;b;c') # => ['a', 'b', 'c']
 ```
 
+#### `:rescue`
+
+Wraps a step's execution, rescues a specific exception and returns an invalid result.
+
+Useful for turning a 3rd party library's exception into an invalid result that plays well with Plumb's type compositions.
+
+Example: this is how `Types::Forms::Date` uses the `:rescue` policy to parse strings with `Date.parse` and turn `Date::Error` exceptions into Plumb errors.
+
+```ruby
+# Accept a string that can be parsed into a Date
+# via Date.parse
+# If Date.parse raises a Date::Error, return a Result::Invalid with
+# the exception's message as error message.
+type = Types::String
+	.build(::Date, :parse)
+	.policy(:rescue, ::Date::Error)
+
+type.resolve('2024-02-02') # => Result::Valid with Date object
+type.resolve('2024-') # => Result::Invalid with error message
+```
+
+### `Types::Interface`
 
+Use this for objects that must respond to one or more methods.
+
+```ruby
+Iterable = Types::Interface[:each, :map]
+Iterable.parse([1,2,3]) # => [1,2,3]
+Iterable.parse(10) # => raises error
+```
+
+This can be useful combined with `case` statements, too:
+
+```ruby
+value = [1,2,3]
+case value
+when Iterable
+  # do something with array
+when Stringable
+  # do something with string
+when Readable
+  # do something with IO or similar
+end
+```
+
+TODO: make this a bit more advanced. Check for method arity.
 
 ### `Types::Hash`
 
@@ -773,13 +832,15 @@ Images = Types::Array[ImageDownload].concurrent
 Images.parse(['https://images.com/1.png', 'https://images.com/2.png'])
 ```
 
+See the [concurrent downloads example](https://github.com/ismasan/plumb/blob/main/examples/concurrent_downloads.rb).
+
 TODO: pluggable concurrency engines (Async?)
 
 #### `#stream`
 
 Turn an Array definition into an enumerator that yields each element wrapped in `Result::Valid` or `Result::Invalid`.
 
-See `Types::Stream` below for more.
+See [`Types::Stream`](#typesstream) below for more.
 
 #### `#filtered`
 
@@ -848,6 +909,8 @@ stream.each.with_index(1) do |result, line|
 end
 ```
 
+See a more complete the [CSV Stream example](https://github.com/ismasan/plumb/blob/main/examples/csv_stream.rb)
+
 #### `Types::Stream#filtered`
 
 Use `#filtered` to turn a `Types::Stream` into a stream that only yields valid elements.
@@ -904,6 +967,13 @@ person.valid? # false
 person.errors[:age] # 'must be an integer'
 ```
 
+Data structs can also be defined from `Types::Hash` instances.
+
+```ruby
+PersonHash = Types::Hash[name: String, age?: Integer]
+PersonStruct = Types::Data[PersonHash]
+```
+
 #### `#with`
 
 Note that these instances cannot be mutated (there's no attribute setters), but they can be copied with partial attributes with `#with`
@@ -995,7 +1065,25 @@ Note that this does NOT work with union'd or piped structs.
 attribute :company, Company | Person do
 ```
 
+#### Shorthand array syntax
+
+```ruby
+attribute :things, [] # Same as attribute :things, Types::Array
+attribute :numbers, [Integer] # Same as attribute :numbers, Types::Array[Integer]
+attribute :people, [Person] # same as attribute :people, Types::Array[Person]
+attribute :friends, [Person] do # same as attribute :friends, Types::Array[Person] do...
+  attribute :phone_number, Integer
+end
+```
+
+Note that, if you want to match an attribute value against a literal array, you need to use `#value`
+
+```ruby
+attribute :one_two_three, Types::Array.value[[1, 2, 3]])
+```
+
 #### Optional Attributes
+
 Using `attribute?` allows for optional attributes. If the attribute is not present, these attribute values will be `nil`
 
 ```ruby
@@ -1062,13 +1150,168 @@ person.friend.name # 'joan'
 person.friend.friend # nil
 ```
 
+### Plumb::Pipeline
 
+`Plumb::Pipeline` offers a sequential, step-by-step syntax for composing processing steps, as well as a simple middleware API to wrap steps for metrics, logging, debugging, caching and more. See the [command objects](https://github.com/ismasan/plumb/blob/main/examples/command_objects.rb) example for a worked use case.
 
-### Plumb::Schema
+#### `#pipeline` helper
 
-TODO
+All plumb steps have a `#pipeline` helper.
 
-### Plumb::Pipeline
+```ruby
+User = Types::Data[name: String, age: Integer]
+
+CreateUser = User.pipeline do |pl|
+  # Add steps as #call(Result) => Result interfaces
+  pl.step ValidateUser.new
+  
+  # Or as procs
+  pl.step do |result|
+    Logger.info "We have a valid user #{result.value}"
+    result
+  end
+  
+  # Or as other Plumb steps
+  pl.step User.transform(User) { |user| user.with(name: user.name.upcase) }
+  
+  pl.step do |result|
+    DB.create(result.value)
+  end
+end
+
+# Use normally as any other Plumb step
+result = CreateUser.resolve(name: 'Joe', age: 40)
+# result.valid?
+# result.errors
+# result.value => User
+```
+
+Pipelines are Plumb steps, so they can be composed further.
+
+```ruby
+IsJoe = User.check('must be named joe') { |user| 
+  result.value.name == 'Joe' 
+}
+
+CreateIfJoe = IsJoe >> CreateUser
+```
+
+##### `#around`
+
+Use `#around` in a pipeline definition to add a middleware step that wraps all other steps registered.
+
+```ruby
+# The #around interface is #call(Step, Result::Valid) => Result::Valid | Result::Invalid
+StepLogger = proc do |step, result|
+  Logger.info "Processing step #{step}"
+  step.call(result)
+end
+
+CreateUser = User.pipeline do |pl|
+  # Around middleware will wrap all other steps registered below
+  pl.around StepLogger
+  
+  pl.step ValidateUser.new
+  pl.step ...etc
+end
+```
+
+Note that order matters: an _around_ step will only wrap steps registered _after it_.
+
+```ruby
+# This step will not be wrapped by StepLogger
+pl.step Step1
+
+pl.around StepLogger
+# This step WILL be wrapped
+pl.step Step2
+```
+
+Like regular steps, `around` middleware can be a class, an instance, a proc, or anything that implements the middleware interface.
+
+```ruby
+# As class instance
+#   pl.around StepLogger.new(:warn)
+class StepLogger
+  def initialize(level = :info)
+    @level = level
+  end
+  
+  def call(step, result)
+    Logger.send(@level) "Processing step #{step}"
+    step.call(result)
+  end
+end
+
+# As proc
+pl.around do |step, result|
+  Logger.info "Processing step #{step}"
+  step.call(result)
+end
+```
+
+#### As stand-alone `Plumb::Pipeline` class
+
+`Plumb::Pipeline` can also be used on its own, sub-classed, and it can take class-level `around` middleware.
+
+```ruby
+class LoggedPipeline < Plumb::Pipeline
+  # class-level midleware will be inherited by sub-classes
+  around StepLogger
+end
+
+# Subclass inherits class-level middleware stack,
+# and it can also add its own class or instance-level middleware
+class ChildPipeline < LoggedPipeline
+  # class-level middleware
+  around Telemetry.new
+end
+
+# Instantiate and add instance-level middleware
+pipe = ChildPipeline.new do |pl|
+  pl.around NotifyErrors
+  pl.step Step1
+  pl.step Step2
+end
+```
+
+Sub-classing `Plumb::Pipeline` can be useful to add helpers or domain-specific functionality
+
+```ruby
+class DebuggablePipeline < LoggedPipeline
+  # Use #debug! for inserting a debugger between steps
+  def debug!
+    step do |result|
+      debugger
+      result
+    end
+  end
+end
+
+pipe = DebuggablePipeline.new do |pl|
+  pl.step Step1
+  pl.debug!
+  pl.step Step2
+end
+```
+
+#### Pipelines all the way down :turtle:
+
+Pipelines are full Plumb steps, so they can themselves be used as steps.
+
+```ruby
+Pipe1 = DebuggablePipeline.new do |pl|
+  pl.step Step1
+  pl.step Step2
+end
+
+Pipe2 = DebuggablePipeline.new do |pl|
+  pl.step Pipe1 # <= A pipeline instance as step
+  pl.step Step3
+end
+```
+
+### Plumb::Schema
 
 TODO
 
@@ -1388,7 +1631,7 @@ Types::DateTime.to_json_schema
 - [ ] benchmarks and performace. Compare with `Parametric`, `ActiveModel::Attributes`, `ActionController::StrongParameters`
 - [ ] flesh out `Plumb::Schema`
 - [x] `Plumb::Struct`
-- [ ] flesh out and document `Plumb::Pipeline`
+- [x] flesh out and document `Plumb::Pipeline`
 - [ ] document custom visitors
 - [ ] Improve errors, support I18n ?
 

data/bench/compare_parametric_schema.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'bundler'
+Bundler.setup(:benchmark)
+
+require 'benchmark/ips'
+require 'money'
+Money.rounding_mode = BigDecimal::ROUND_HALF_EVEN
+Money.default_currency = 'GBP'
+require_relative './parametric_schema'
+require_relative './plumb_hash'
+
+data = {
+  supplier_name: 'Vodafone',
+  start_date: '2020-01-01',
+  end_date: '2021-01-11',
+  countdown_date: '2021-01-11',
+  name: 'Vodafone TV',
+  upfront_cost_description: 'Upfront cost description',
+  tv_channels_count: 100,
+  terms: [
+    { name: 'Foo', url: 'http://foo.com', terms_text: 'Foo terms', start_date: '2020-01-01', end_date: '2021-01-01' },
+    { name: 'Foo2', url: 'http://foo2.com', terms_text: 'Foo terms', start_date: '2020-01-01', end_date: '2021-01-01' }
+  ],
+  tv_included: true,
+  additional_info: 'Additional info',
+  product_type: 'TV',
+  annual_price_increase_applies: true,
+  annual_price_increase_description: 'Annual price increase description',
+  broadband_components: [
+    {
+      name: 'Broadband 1',
+      technology: 'FTTP',
+      technology_tags: ['FTTP'],
+      is_mobile: false,
+      description: 'Broadband 1 description',
+      download_speed_measurement: 'Mbps',
+      download_speed: 100,
+      upload_speed_measurement: 'Mbps',
+      upload_speed: 100,
+      download_usage_limit: 1000,
+      discount_price: 100,
+      discount_period: 12,
+      speed_description: 'Speed description',
+      ongoing_price: 100,
+      contract_length: 12,
+      upfront_cost: 100,
+      commission: 100
+    }
+  ],
+  tv_components: [
+    {
+      slug: 'vodafone-tv',
+      name: 'Vodafone TV',
+      search_tags: %w[Vodafone TV],
+      description: 'Vodafone TV description',
+      channels: 100,
+      discount_price: 100
+    }
+  ],
+  call_package_types: ['Everything'],
+  phone_components: [
+    {
+      name: 'Phone 1',
+      description: 'Phone 1 description',
+      discount_price: 100,
+      disount_period: 12,
+      ongoing_price: 100,
+      contract_length: 12,
+      upfront_cost: 100,
+      commission: 100,
+      call_package_types: ['Everything']
+    }
+  ],
+  payment_methods: ['Credit Card', 'Paypal'],
+  discounts: [
+    { period: 12, price: 100 }
+  ],
+  ongoing_price: 100,
+  contract_length: 12,
+  upfront_cost: 100,
+  year_1_price: 100,
+  savings: 100,
+  commission: 100,
+  max_broadband_download_speed: 100
+}
+
+# p V1Schemas::RECORD.resolve(data).errors
+# p V2Schemas::Record.resolve(data)
+# result = Parametric::V2::Result.wrap(data)
+
+# p result
+# p V2Schema.call(result)
+Benchmark.ips do |x|
+  x.report('Parametric::Schema') do
+    ParametricSchema::RECORD.resolve(data)
+  end
+  x.report('Plumb') do
+    PlumbHash::Record.resolve(data)
+  end
+  x.compare!
+end

data/bench/compare_parametric_struct.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'bundler'
+Bundler.setup(:benchmark)
+
+require 'benchmark/ips'
+require 'parametric/struct'
+require 'plumb'
+
+module ParametricStruct
+  class User
+    include Parametric::Struct
+
+    schema do
+      field(:name).type(:string).present
+      field(:friends).type(:array).schema do
+        field(:name).type(:string).present
+        field(:age).type(:integer)
+      end
+    end
+  end
+end
+
+module PlumbStruct
+  include Plumb::Types
+
+  class User < Data
+    attribute :name, String.present
+    attribute :friends, Array do
+      attribute :name, String.present
+      attribute :age, Integer
+    end
+  end
+end
+
+module DataBaseline
+  Friend = Data.define(:name, :age)
+  User = Data.define(:name, :friends) do
+    def self.build(data)
+      data = data.merge(friends: data[:friends].map { |friend| Friend.new(**friend) })
+      new(**data)
+    end
+  end
+end
+
+data = {
+  name: 'John',
+  friends: [
+    { name: 'Jane', age: 30 },
+    { name: 'Joan', age: 38 }
+  ]
+}
+
+Benchmark.ips do |x|
+  # x.report('Ruby Data') do
+  #   user = DataBaseline::User.build(data)
+  #   user.name
+  # end
+  x.report('Parametric::Struct') do
+    user = ParametricStruct::User.new(data)
+    user.name
+  end
+  x.report('Plumb::Types::Data') do
+    user = PlumbStruct::User.new(data)
+    user.name
+  end
+  x.compare!
+end