plumb 0.0.18 → 0.2.0.beta.2

data/bench/compare_dry_schema.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Plumb vs Dry::Schema — the apples-to-apples comparison.
+#
+# Unlike Dry::Types (bare values, raises on first error), Dry::Schema shares
+# Plumb's model: validate + coerce, collect ALL errors, return a Result, never
+# raise. It goes one step further and resolves human-readable messages via
+# `errors.to_h`. We measure both the happy path (validate + collect, no errors)
+# and the error path (validate + resolve every message), since message
+# resolution only does real work when there ARE errors.
+
+require 'benchmark/ips'
+require 'money'
+::Money.default_currency = ::Money::Currency.new('GBP')
+
+$LOAD_PATH.unshift File.expand_path(__dir__)
+require 'sample_data'
+require 'plumb_hash'
+require 'dry_schema_hash'
+
+VALID = SAMPLE_DATA
+
+# A copy of the payload with ~9 type errors scattered across the tree (top-level,
+# nested-hash, array-element). Chosen so BOTH libraries reject them and NONE hit
+# the Money constructor (which raises rather than returning a clean error).
+INVALID = Marshal.load(Marshal.dump(SAMPLE_DATA)).tap do |d|
+  d[:supplier_name] = nil
+  d[:name] = ''
+  d[:tv_channels_count] = 'abc'
+  d[:tv_included] = 'nope'
+  d[:terms][0][:name] = 123
+  d[:broadband_components][0][:download_speed] = 'fast'
+  d[:broadband_components][0][:contract_length] = 'soon'
+  d[:discounts][0][:period] = 'ptwelve'
+  d[:max_broadband_download_speed] = 'lots'
+end.freeze
+
+# ---- sanity ---------------------------------------------------------------
+
+def count_leaves(errors)
+  case errors
+  when ::Hash  then errors.values.sum { |v| count_leaves(v) }
+  when ::Array then errors.sum { |v| v.is_a?(::Hash) || v.is_a?(::Array) ? count_leaves(v) : 1 }
+  else 1
+  end
+end
+
+plumb_ok  = PlumbHash::Record.resolve(VALID)
+dry_ok    = DrySchemaHash::Record.call(VALID)
+plumb_bad = PlumbHash::Record.resolve(INVALID)
+dry_bad   = DrySchemaHash::Record.call(INVALID)
+
+puts '=== sanity ==='
+puts "Plumb  valid data -> valid?:   #{plumb_ok.valid?}"
+puts "Dry    valid data -> success?: #{dry_ok.success?}"
+puts "Plumb  invalid data -> valid?: #{plumb_bad.valid?}  (#{count_leaves(plumb_bad.errors)} error leaves)"
+puts "Dry    invalid data -> success?: #{dry_bad.success?}  (#{count_leaves(dry_bad.errors.to_h)} error leaves)"
+puts "Dry    messages: #{dry_bad.errors.to_h}"
+puts "Plumb  errors:   #{plumb_bad.errors}"
+puts
+
+# ---- happy path: validate + collect (no errors) ---------------------------
+
+puts '=== happy path: validate + collect errors ==='
+Benchmark.ips do |x|
+  x.report('Plumb') { PlumbHash::Record.resolve(VALID).errors }
+  x.report('Dry::Schema') { DrySchemaHash::Record.call(VALID).errors.to_h }
+  x.compare!
+end
+
+# ---- error path: validate + resolve ALL messages --------------------------
+
+puts
+puts '=== error path: validate + resolve all messages ==='
+Benchmark.ips do |x|
+  x.report('Plumb') { PlumbHash::Record.resolve(INVALID).errors }
+  x.report('Dry::Schema') { DrySchemaHash::Record.call(INVALID).errors.to_h }
+  x.compare!
+end

data/bench/compare_dry_types.rb

@@ -0,0 +1,37 @@
+# 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 './sample_data'
+require_relative './plumb_hash'
+require_relative './dry_types_hash'
+
+data = SAMPLE_DATA
+
+# Sanity-check that both do equivalent (successful) work before timing, so we're
+# not comparing a happy path against an error path.
+plumb_result = PlumbHash::Record.resolve(data)
+warn "Plumb valid?: #{plumb_result.valid?}"
+warn "Plumb errors: #{plumb_result.errors.inspect}" unless plumb_result.valid?
+begin
+  DryTypesHash::Record.call(data)
+  warn 'Dry::Types valid?: true'
+rescue StandardError => e
+  warn "Dry::Types FAILED: #{e.class}: #{e.message}"
+end
+
+Benchmark.ips do |x|
+  x.report('Plumb') do
+    PlumbHash::Record.resolve(data)
+  end
+  x.report('Dry::Types') do
+    DryTypesHash::Record.call(data)
+  end
+  x.compare!
+end

data/bench/compare_parametric_schema.rb

@@ -7,90 +7,12 @@ require 'benchmark/ips'
 require 'money'
 Money.rounding_mode = BigDecimal::ROUND_HALF_EVEN
 Money.default_currency = 'GBP'
+require_relative './sample_data'
 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
-}
+data = SAMPLE_DATA
 
-# 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)

data/bench/dry_schema_hash.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'dry/schema'
+require 'date'
+require 'money'
+require 'monetize'
+
+# Dry::Schema port of PlumbHash::Record (see bench/plumb_hash.rb), for an
+# apples-to-apples comparison: like Plumb (and unlike raw Dry::Types), a
+# Dry::Schema returns a Result carrying ALL errors and never raises — and it
+# additionally resolves human-readable messages via `result.errors.to_h`.
+#
+# Params schema so string dates coerce to Date and the native ints/bools pass
+# through. Plumb `.default(x)` fields are provided by the sample data, so they
+# map to `required`. Numeric maps to :integer (the sample values are integers).
+module DrySchemaHash
+  module T
+    include Dry.Types()
+  end
+
+  # Same coercion as PlumbHash::Money — a single constructor, not a union.
+  # STUB_MONEY swaps it for an identity passthrough (see plumb_hash.rb).
+  MoneyType = if ENV['STUB_MONEY']
+                T::Any
+              else
+                T.Constructor(::Money) do |v|
+                  v.is_a?(::Money) ? v : Monetize.parse!(v.to_s.gsub(',', ''))
+                end
+              end
+
+  Record = Dry::Schema.Params do
+    required(:supplier_name).filled(:string)
+    required(:start_date).maybe(:date)
+    required(:end_date).maybe(:date)
+    required(:countdown_date).maybe(:date)
+    required(:name).filled(:string)
+    required(:upfront_cost_description).value(:string)
+    required(:tv_channels_count).value(:integer)
+    required(:terms).array(:hash) do
+      required(:name).value(:string)
+      required(:url).value(:string)
+      required(:terms_text).value(:string)
+      optional(:start_date).maybe(:date)
+      optional(:end_date).maybe(:date)
+    end
+    required(:tv_included).value(:bool)
+    required(:additional_info).value(:string)
+    required(:product_type).maybe(:string)
+    required(:annual_price_increase_applies).value(:bool)
+    required(:annual_price_increase_description).value(:string)
+    required(:broadband_components).array(:hash) do
+      required(:name).value(:string)
+      required(:technology).value(:string)
+      required(:is_mobile).value(:bool)
+      required(:description).value(:string)
+      required(:technology_tags).array(:string)
+      required(:download_speed_measurement).value(:string)
+      required(:download_speed).value(:integer)
+      required(:upload_speed_measurement).value(:string)
+      required(:upload_speed).value(:integer)
+      required(:download_usage_limit).maybe(:integer)
+      required(:discount_price).maybe(MoneyType)
+      required(:discount_period).maybe(:integer)
+      required(:speed_description).value(:string)
+      required(:ongoing_price).maybe(MoneyType)
+      required(:contract_length).maybe(:integer)
+      required(:upfront_cost).maybe(MoneyType)
+      required(:commission).maybe(MoneyType)
+    end
+    required(:tv_components).array(:hash) do
+      required(:slug).value(:string)
+      required(:name).filled(:string)
+      required(:search_tags).array(:string)
+      required(:description).value(:string)
+      required(:channels).value(:integer)
+      required(:discount_price).value(MoneyType)
+    end
+    required(:call_package_types).array(:string)
+    required(:phone_components).array(:hash) do
+      required(:name).value(:string)
+      required(:description).value(:string)
+      required(:discount_price).maybe(MoneyType)
+      required(:discount_period).maybe(:integer)
+      required(:ongoing_price).maybe(MoneyType)
+      required(:contract_length).maybe(:integer)
+      required(:upfront_cost).maybe(MoneyType)
+      required(:commission).maybe(MoneyType)
+      optional(:call_package_type).array(:string)
+    end
+    required(:payment_methods).array(:string)
+    required(:discounts).array(:hash) do
+      required(:period).value(:integer)
+      required(:price).maybe(MoneyType)
+    end
+    required(:ongoing_price).maybe(MoneyType)
+    required(:contract_length).maybe(:integer)
+    required(:upfront_cost).maybe(MoneyType)
+    required(:year_1_price).maybe(MoneyType)
+    required(:savings).maybe(MoneyType)
+    required(:commission).maybe(MoneyType)
+    required(:max_broadband_download_speed).value(:integer)
+  end
+end

data/bench/dry_types_hash.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'dry/types'
+require 'date'
+require 'money'
+require 'monetize'
+
+# Dry::Types port of PlumbHash::Record (see bench/plumb_hash.rb) — the same
+# nested record with the same coercions/defaults/nullability, built with
+# dry-types hash schemas so the comparison is apples-to-apples.
+module DryTypesHash
+  module T
+    include Dry.Types()
+  end
+
+  BLANK_ARRAY = [].freeze
+  BLANK_STRING = ''
+
+  # Custom Money type: pass a Money through, else parse via Monetize (mirrors
+  # PlumbHash::Money). STUB_MONEY swaps it for an identity passthrough (see
+  # plumb_hash.rb) so the benchmark can measure the schema WITHOUT the shared
+  # money-parsing cost that both libraries otherwise pay.
+  Money = if ENV['STUB_MONEY']
+            T::Any
+          else
+            T.Constructor(::Money) do |value|
+              value.is_a?(::Money) ? value : Monetize.parse!(value.to_s.gsub(',', ''))
+            end
+          end
+
+  # Blank string -> nil, otherwise coerce to a Date (mirrors Forms::Nil | Forms::Date).
+  BlankStringOrDate = T::Params::Date.optional
+
+  PresentString = T::Strict::String.constrained(min_size: 1)
+  Integer0 = T::Coercible::Integer.default(0)
+  NullableInteger = T::Coercible::Integer.optional
+  NullableMoney = Money.optional
+  DefaultString = T::String.default(BLANK_STRING)
+
+  Term = T::Hash.schema(
+    name: DefaultString,
+    url: DefaultString,
+    terms_text: DefaultString,
+    start_date?: BlankStringOrDate,
+    end_date?: BlankStringOrDate
+  )
+
+  TvComponent = T::Hash.schema(
+    slug: T::String,
+    name: PresentString,
+    search_tags: T::Array.of(T::String).default(BLANK_ARRAY),
+    description: DefaultString,
+    channels: Integer0,
+    discount_price: Money.default(::Money.zero.freeze)
+  )
+
+  BroadbandComponent = T::Hash.schema(
+    name: T::String,
+    technology: T::String,
+    is_mobile: T::Strict::Bool.default(false),
+    description: T::String,
+    technology_tags: T::Array.of(T::String).default(BLANK_ARRAY),
+    download_speed_measurement: DefaultString,
+    download_speed: T::Coercible::Float.default(0.0),
+    upload_speed_measurement: DefaultString,
+    upload_speed: T::Coercible::Float.default(0.0),
+    download_usage_limit: NullableInteger,
+    discount_price: NullableMoney,
+    discount_period: NullableInteger,
+    speed_description: DefaultString,
+    ongoing_price: NullableMoney,
+    contract_length: NullableInteger,
+    upfront_cost: NullableMoney,
+    commission: NullableMoney
+  )
+
+  PhoneComponent = T::Hash.schema(
+    name: T::String,
+    description: T::String,
+    discount_price: NullableMoney,
+    discount_period: NullableInteger,
+    ongoing_price: NullableMoney,
+    contract_length: NullableInteger,
+    upfront_cost: NullableMoney,
+    commission: NullableMoney,
+    call_package_type: T::Array.of(T::String).default(BLANK_ARRAY)
+  )
+
+  Discount = T::Hash.schema(
+    period: T::Coercible::Integer,
+    price: NullableMoney
+  )
+
+  Record = T::Hash.schema(
+    supplier_name: PresentString,
+    start_date: BlankStringOrDate,
+    end_date: BlankStringOrDate,
+    countdown_date: BlankStringOrDate,
+    name: PresentString,
+    upfront_cost_description: DefaultString,
+    tv_channels_count: Integer0,
+    # Plumb's `.where(size: 1..).default([])` (default bypasses the size check)
+    # has no direct dry equivalent — dry rejects a default that violates the
+    # constraint. The data always provides `terms`, so keep the size check.
+    terms: T::Array.of(Term).constrained(min_size: 1),
+    tv_included: T::Strict::Bool,
+    additional_info: T::String,
+    product_type: T::String.optional,
+    annual_price_increase_applies: T::Strict::Bool.default(false),
+    annual_price_increase_description: DefaultString,
+    broadband_components: T::Array.of(BroadbandComponent),
+    tv_components: T::Array.of(TvComponent).default(BLANK_ARRAY),
+    call_package_types: T::Array.of(T::String).default(BLANK_ARRAY),
+    phone_components: T::Array.of(PhoneComponent).default(BLANK_ARRAY),
+    payment_methods: T::Array.of(T::String).default(BLANK_ARRAY),
+    discounts: T::Array.of(Discount),
+    ongoing_price: NullableMoney,
+    contract_length: NullableInteger,
+    upfront_cost: NullableMoney,
+    year_1_price: NullableMoney,
+    savings: NullableMoney,
+    commission: NullableMoney,
+    max_broadband_download_speed: Integer0
+  )
+end

data/bench/json_schema_profile.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Profiles JSON Schema GENERATION (the JSONSchemaVisitor traversal) for a
+# realistic, deeply nested REST API payload — an e-commerce "Order" resource
+# with a customer, addresses, line items, enums, coercing composite types
+# (a Forms-coerced date and boolean, Lax::Integer/Decimal/String) and unions.
+#
+# Compositions are reduced at build time (union absorption/factoring,
+# refinement/where collapse), so the type GRAPH the visitor walks is smaller and
+# the emitted schema is flatter (folded anyOf, factored enums). This measures the
+# resulting generation cost — run it before and after a change to compare.
+#
+# Public API only. NB: there is no Types::Lax::Date; a coercing date/boolean is
+# `real type | the matching Codec::Forms encoder` (see FormsDate / FormsBoolean).
+
+require 'plumb'
+require 'json'
+require 'date'
+
+ITERS = 20_000
+
+module T
+  include Plumb::Types
+end
+
+EMAIL = /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/
+SKU   = /\A[A-Z0-9\-]+\z/
+REF   = /\A[A-Z0-9]{8,}\z/
+
+# Coercing scalars: "accept the parsed Ruby value, or decode the stringly form" —
+# the same shape as `Types::Lax::*`, built from the Forms codec's encoders. Both
+# branches matter here: a coercing field is exactly what makes the visitor fold a
+# union into one field spec.
+FORMS = Plumb::Codec::Forms
+FormsDate = T::Date | FORMS::DateEncoder
+FormsBoolean = T::Boolean | FORMS::TrueEncoder | FORMS::FalseEncoder
+
+# Enums built as unions of literal String constraints — factoring pulls the shared
+# `String` gate out into one `anyOf`.
+Currency = T::String['USD'] | T::String['EUR'] | T::String['GBP']
+Status   = T::String['pending'] | T::String['paid'] | T::String['shipped'] | T::String['cancelled']
+
+Address = T::Hash[
+  street: T::String.where(size: 1..200),
+  city: T::String,
+  postal_code: T::Lax::String,
+  country_code: T::String.where(size: 2)
+]
+
+LineItem = T::Hash[
+  sku: T::String[SKU],
+  description: (T::String | T::Nil),
+  quantity: T::Lax::Integer,
+  unit_price: T::Lax::Decimal,
+  currency: Currency,
+  tags: T::Array[T::String]
+]
+
+Customer = T::Hash[
+  id: T::Integer,
+  name: T::String.where(size: 1..100),
+  email: T::String[EMAIL],
+  phone: (T::String | T::Nil),
+  verified: FormsBoolean,
+  loyalty_points: (T::Integer | T::Numeric), # value-preserving union -> absorbs to Numeric
+  address: Address,
+  billing_address: Address
+]
+
+ORDER = T::Hash[
+  id: T::Integer,
+  reference: T::String[REF],
+  status: Status,
+  currency: Currency,
+  created_at: FormsDate,
+  updated_at: FormsDate,
+  shipped_at: (FormsDate | T::Nil),
+  subtotal: T::Lax::Decimal,
+  tax: T::Lax::Decimal,
+  total: T::Lax::Decimal,
+  customer: Customer,
+  items: T::Array[LineItem],
+  metadata: T::Hash[T::String, T::Lax::String],
+  notes: (T::String | T::Nil)
+].freeze
+
+def measure_generation(type, iters = ITERS)
+  type.to_json_schema(root: true) # warm up
+  GC.start
+  a0 = GC.stat(:total_allocated_objects)
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  iters.times { type.to_json_schema(root: true) }
+  t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  a1 = GC.stat(:total_allocated_objects)
+  [(t1 - t0) * 1e9 / iters, (a1 - a0).to_f / iters]
+end
+
+schema = ORDER.to_json_schema(root: true)
+json_bytes = JSON.generate(schema).bytesize
+us_per, allocs_per = measure_generation(ORDER)
+
+puts "== plumb JSON Schema generation — Ruby #{RUBY_VERSION} =="
+puts format('%-26s %s', 'payload', 'REST "Order" (nested: customer, 2 addresses, line items, enums, coercers)')
+puts format('%-26s %.1f', 'us / generation', us_per / 1000.0)
+puts format('%-26s %.0f', 'allocs / generation', allocs_per)
+puts format('%-26s %d bytes', 'emitted schema size', json_bytes)
+puts format('%-26s %d', 'top-level properties', (schema['properties'] || {}).size)

data/bench/plumb_hash.rb

@@ -12,16 +12,22 @@ module PlumbHash
   BLANK_STRING = ''
   MONEY_EXP = /(\W{1}|\w{3})?[\d+,.]/
 
-  PARSE_MONEY = proc do |result|
-    value = Monetize.parse!(result.value.to_s.gsub(',', ''))
-    result.valid(value)
-  end
+  # Blank string (or a valueless param) -> nil, otherwise an ISO date string -> Date.
+  # Mirrors DryTypesHash's `T::Params::Date.optional`, which is what this file is
+  # benchmarked against.
+  FormEncoders = Plumb::Codec::Forms
+  BlankStringOrDate = FormEncoders::NilEncoder | FormEncoders::DateEncoder
 
-  BlankStringOrDate = Forms::Nil | Forms::Date
-
-  Money = Any[::Money] \
-    | (String.present >> PARSE_MONEY) \
-    | (Numeric >> PARSE_MONEY)
+  # STUB_MONEY swaps the Monetize-parsing constructor for an identity
+  # passthrough, so the benchmark can measure the schema WITHOUT the (shared)
+  # money-parsing cost that both Plumb and Dry pay equally.
+  Money = if ENV['STUB_MONEY']
+            Any
+          else
+            Any.build(::Money) do |v|
+              v.is_a?(::Money) ? v : Monetize.parse!(v.to_s.gsub(',', ''))
+            end
+          end
 
   Term = Hash[
     name: String.default(BLANK_STRING),
@@ -48,7 +54,7 @@ module PlumbHash
     name: String.present,
     upfront_cost_description: String.default(BLANK_STRING),
     tv_channels_count: Integer.default(0),
-    terms: Array[Term].policy(size: 1..).default(BLANK_ARRAY),
+    terms: Array[Term].where(size: 1..).default(BLANK_ARRAY),
     tv_included: Boolean,
     additional_info: String,
     product_type: String.nullable,
@@ -58,7 +64,7 @@ module PlumbHash
       name: String,
       technology: String,
       is_mobile: Boolean.default(false),
-      desciption: String,
+      description: String,
       technology_tags: Array[String].default(BLANK_ARRAY),
       download_speed_measurement: String.default(BLANK_STRING),
       download_speed: Numeric.default(0),