plumb 0.0.3 → 0.0.5

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

data/bench/parametric_schema.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'parametric'
+require 'money'
+require 'monetize'
+
+PARAMETRIC_MONEY_EXP = /(\W{1}|\w{3})?[\d+,.]/
+
+Parametric.policy(:nullable_money) do
+  coerce do |value, _key, _context|
+    money = case value
+            when String
+              value = value.strip
+              if value.blank?
+                nil
+              elsif value =~ PARAMETRIC_MONEY_EXP
+                Monetize.parse!(value.gsub(',', ''))
+              else
+                raise ArgumentError, "#{value} is not a monetary amount"
+              end
+            when Numeric
+              Monetize.parse!(value.to_s)
+            when Money
+              value
+            when NilClass
+              nil
+            else
+              raise ArgumentError, "don't know how to coerce #{value.inspect} into Money"
+            end
+
+    if money && money.currency != Money.default_currency
+      raise ArgumentError,
+            "expected #{Money.default_currency.name} as currency, but got #{money.currency.name}"
+    end
+
+    money
+  end
+
+  meta_data do
+    { type: :number, config_type: :nullable_money }
+  end
+end
+
+Parametric.policy(:nullable_date) do
+  # rubocop:disable Style/RedundantBegin
+  coerce do |value, _key, _context|
+    begin
+      value = value.to_s.strip
+      value == '' ? nil : Date.parse(value)
+    rescue Date::Error
+      nil
+    end
+  end
+  # rubocop:enable Style/RedundantBegin
+
+  meta_data do
+    { type: :date, config_type: :nullable_date }
+  end
+end
+
+PARAMETRIC_DATE_EXP = /\A\d{4}-\d{2}-\d{2}\z/
+PARAMETRIC_DATE_INFINITY = 'infinity'
+PARAMETRIC_IS_DATE = ->(value) { value.is_a?(::Date) || (value.is_a?(::String) && value =~ PARAMETRIC_DATE_EXP) }
+PARAMETRIC_PARSE_DATE = ->(value) { value.is_a?(::Date) ? value : ::Date.parse(value) }
+
+Parametric.policy :nullable_date_range do
+  validate do |value, _key, _context|
+    if value.blank? || value.is_a?(Switcher::DateRange)
+      true
+    else
+      value.is_a?(Hash) && !!(PARAMETRIC_IS_DATE.call(value[:min]) && (value[:max].nil? || PARAMETRIC_IS_DATE.call(value[:max] || value[:max] == PARAMETRIC_DATE_INFINITY)))
+    end
+  end
+
+  coerce do |value, _key, _context|
+    if value.is_a?(Switcher::DateRange)
+      value
+    elsif value.blank? || (value[:min].blank? && value[:max].blank?)
+      nil
+    else
+      min = value[:min].present? ? PARAMETRIC_PARSE_DATE.call(value[:min]) : nil
+      max = value[:max].present? && value[:max] != PARAMETRIC_DATE_INFINITY ? PARAMETRIC_PARSE_DATE.call(value[:max]) : nil
+      Switcher::DateRange.new(min, max)
+    end
+  end
+
+  meta_data do
+    { type: :object, config_type: :nullable_date_range }
+  end
+end
+
+PARAMETRIC_INT_EXP = /^\d+$/
+
+Parametric.policy(:nullable_integer) do
+  coerce do |value, _key, _context|
+    if value.to_s =~ PARAMETRIC_INT_EXP
+      value.to_i
+    else
+      nil
+    end
+  end
+
+  meta_data do
+    { type: :integer, config_type: :nullable_integer }
+  end
+end
+
+PARAMETRIC_FLOAT_EXP = /^\d+(\.\d+)?$/
+
+Parametric.policy(:nullable_number) do
+  coerce do |value, _key, _context|
+    if value.to_s =~ PARAMETRIC_FLOAT_EXP
+      value.to_f
+    else
+      nil
+    end
+  end
+
+  meta_data do
+    { type: :number, config_type: :nullable_number }
+  end
+end
+
+Parametric.policy :size do
+  message do |opts, object|
+    "must have size of #{opts}, but got #{object.size}"
+  end
+
+  validate do |opts, object, _key, _payload|
+    size = object.size
+    (opts[:min].nil? || size >= opts[:min]) && (opts[:max].nil? || size <= opts[:max])
+  end
+end
+
+Parametric.policy(:nullable_string) do
+  coerce do |value, _key, _context|
+    if value.to_s.strip != ''
+      value.to_s
+    else
+      nil
+    end
+  end
+
+  meta_data do
+    { type: :string, config_type: :nullable_string }
+  end
+end
+
+module ParametricSchema
+  TERM = Parametric::Schema.new do
+    field(:name).type(:string).default('')
+    field(:url).type(:string).default('')
+    field(:terms_text).type(:string).default('')
+    field(:start_date).type(:nullable_date)
+    field(:end_date).type(:nullable_date)
+  end
+  TV_COMPONENT = Parametric::Schema.new do
+    field(:slug).type(:string) # .policy(:parameterize).present
+    field(:name).type(:string).present
+    field(:search_tags).type(:array).default([])
+    field(:description).type(:string)
+    field(:channels).type(:integer).default(0)
+    field(:discount_price).type(:nullable_money).default(Money.zero)
+    field(:discount_period).type(:nullable_integer)
+    field(:ongoing_price).type(:nullable_money)
+    field(:contract_length).type(:nullable_integer)
+    field(:upfront_cost).type(:nullable_money)
+    field(:commission).type(:nullable_money)
+  end
+  RECORD = Parametric::Schema.new do
+    field(:supplier_name).type(:string).present
+    field(:start_date).type(:nullable_date).meta(example: nil, admin_ui: true)
+    field(:end_date).type(:nullable_date).meta(example: nil, admin_ui: true)
+    field(:countdown_date).type(:nullable_date).meta(example: nil)
+    field(:name).type(:string).present.meta(example: 'Visa Platinum', admin_ui: true)
+    field(:upfront_cost_description).type(:string).default('')
+    field(:tv_channels_count).type(:integer).default(0)
+    field(:terms).type(:array).policy(:size, min: 1).default([]).schema TERM
+    field(:tv_included).type(:boolean)
+    field(:additional_info).type(:string)
+    field(:product_type).type(:nullable_string) # computed on ingestion
+    field(:annual_price_increase_applies).type(:boolean).default(false)
+    field(:annual_price_increase_description).type(:string).default('')
+    field(:broadband_components).type(:array).default([]).schema do
+      field(:name).type(:string)
+      field(:technology).type(:string)
+      field(:technology_tags).type(:array).default([])
+      field(:is_mobile).type(:boolean).default(false) # computed on ingestion based on technology
+      field(:description).type(:string)
+      field(:download_speed_measurement).type(:string).default('')
+      field(:download_speed).type(:nullable_number).default(0)
+      field(:upload_speed_measurement).type(:string)
+      field(:upload_speed).type(:nullable_number).default(0)
+      field(:download_usage_limit).type(:nullable_integer).default(nil)
+      field(:discount_price).type(:nullable_money)
+      field(:discount_period).type(:nullable_integer)
+      field(:speed_description).type(:string).default('')
+      field(:ongoing_price).type(:nullable_money)
+      field(:contract_length).type(:nullable_integer)
+      field(:upfront_cost).type(:nullable_money)
+      field(:commission).type(:nullable_money)
+    end
+    field(:tv_components).type(:array).default([]).schema TV_COMPONENT
+    field(:call_package_types).type(:array).default([]).meta(example: ['Everything']) # computed on ingestion
+    field(:phone_components).type(:array).default([]).schema do
+      field(:name).type(:string)
+      field(:description).type(:string)
+      field(:discount_price).type(:nullable_money)
+      field(:discount_period).type(:nullable_integer)
+      field(:ongoing_price).type(:nullable_money)
+      field(:contract_length).type(:nullable_integer)
+      field(:upfront_cost).type(:nullable_money)
+      field(:commission).type(:nullable_money)
+      field(:call_package_type).type(:array).default([])
+    end
+    field(:payment_methods).type(:array).default([])
+    field(:discounts).type(:array).default([]).schema do
+      field(:period).type(:integer)
+      field(:price).type(:nullable_money)
+    end
+    field(:ongoing_price).type(:nullable_money).meta(admin_ui: true)
+    field(:contract_length).type(:nullable_integer)
+    field(:upfront_cost).type(:nullable_money)
+    field(:year_1_price).type(:nullable_money).meta(admin_ui: true)
+    field(:savings).type(:nullable_money).meta(admin_ui: true)
+    field(:commission).type(:nullable_money)
+    field(:max_broadband_download_speed).type(:integer).default(0)
+  end
+end

data/bench/plumb_hash.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'plumb'
+require 'date'
+require 'money'
+require 'monetize'
+
+module PlumbHash
+  include Plumb::Types
+
+  BLANK_ARRAY = [].freeze
+  BLANK_STRING = ''
+  MONEY_EXP = /(\W{1}|\w{3})?[\d+,.]/
+
+  PARSE_DATE = proc do |result|
+    date = ::Date.parse(result.value)
+    result.valid(date)
+  rescue ::Date::Error
+    result.invalid(errors: 'invalid date')
+  end
+
+  PARSE_MONEY = proc do |result|
+    value = Monetize.parse!(result.value.to_s.gsub(',', ''))
+    result.valid(value)
+  end
+
+  Date = Any[::Date] \
+    | (String[MONEY_EXP] >> PARSE_DATE)
+
+  BlankStringOrDate = Forms::Nil | Date
+
+  Money = Any[::Money] \
+    | (String.present >> PARSE_MONEY) \
+    | (Numeric >> PARSE_MONEY)
+
+  Term = Hash[
+    name: String.default(BLANK_STRING),
+    url: String.default(BLANK_STRING),
+    terms_text: String.default(BLANK_STRING),
+    start_date?: BlankStringOrDate.nullable,
+    end_date?: BlankStringOrDate.nullable
+  ]
+
+  TvComponent = Hash[
+    slug: String,
+    name: String.present,
+    search_tags: Array[String].default(BLANK_ARRAY),
+    description: String.default(BLANK_STRING),
+    channels: Integer.default(0),
+    discount_price: Money.default(::Money.zero.freeze)
+  ]
+
+  Record = Hash[
+    supplier_name: String.present,
+    start_date: BlankStringOrDate.nullable.metadata(admin_ui: true),
+    end_date: BlankStringOrDate.nullable.metadata(admin_ui: true),
+    countdown_date: BlankStringOrDate.nullable,
+    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),
+    tv_included: Boolean,
+    additional_info: String,
+    product_type: String.nullable,
+    annual_price_increase_applies: Boolean.default(false),
+    annual_price_increase_description: String.default(BLANK_STRING),
+    broadband_components: Array[
+      name: String,
+      technology: String,
+      is_mobile: Boolean.default(false),
+      desciption: String,
+      technology_tags: Array[String].default(BLANK_ARRAY),
+      download_speed_measurement: String.default(BLANK_STRING),
+      download_speed: Numeric.default(0),
+      upload_speed_measurement: String.default(BLANK_STRING),
+      upload_speed: Numeric.default(0),
+      download_usage_limit: Integer.nullable,
+      discount_price: Money.nullable,
+      discount_period: Integer.nullable,
+      speed_description: String.default(BLANK_STRING),
+      ongoing_price: Money.nullable,
+      contract_length: Integer.nullable,
+      upfront_cost: Money.nullable,
+      commission: Money.nullable
+    ],
+    tv_components: Array[TvComponent].default(BLANK_ARRAY),
+    call_package_types: Array[String].default(BLANK_ARRAY).metadata(example: ['Everything']),
+    phone_components: Array[
+      name: String,
+      description: String,
+      discount_price: Money.nullable,
+      discount_period: Integer.nullable,
+      ongoing_price: Money.nullable,
+      contract_length: Integer.nullable,
+      upfront_cost: Money.nullable,
+      commission: Money.nullable,
+      call_package_type: Array[String].default(BLANK_ARRAY)
+    ].default(BLANK_ARRAY),
+    payment_methods: Array[String].default(BLANK_ARRAY),
+    discounts: Array[period: Integer, price: Money.nullable],
+    ongoing_price: Money.nullable.metadata(admin_ui: true),
+    contract_length: Integer.nullable,
+    upfront_cost: Money.nullable,
+    year_1_price: Money.nullable.metadata(admin_ui: true),
+    savings: Money.nullable.metadata(admin_ui: true),
+    commission: Money.nullable,
+    max_broadband_download_speed: Integer.default(0)
+  ]
+end

data/examples/concurrent_downloads.rb

@@ -15,8 +15,8 @@ module Types
   # Turn a string into an URI
   URL = String[/^https?:/].build(::URI, :parse)
 
-  # a Struct to holw image data
-  Image = Data.define(:url, :io)
+  # a Struct to hold image data
+  Image = ::Data.define(:url, :io)
 
   # A (naive) step to download files from the internet
   # and return an Image struct.
@@ -38,7 +38,7 @@ module Types
     # Wrap the #reader and #wruter methods into Plumb steps
     # A step only needs #call(Result) => Result to work in a pipeline,
     # but wrapping it in Plumb::Step provides the #>> and #| methods for composability,
-    # as well as all the other helper methods provided by the Steppable module.
+    # as well as all the other helper methods provided by the Composable module.
     def read = Plumb::Step.new(method(:reader))
     def write = Plumb::Step.new(method(:writer))
 

data/examples/env_config.rb

@@ -32,10 +32,10 @@ module Types
   end
 
   # A dummy S3 client
-  S3Client = Data.define(:bucket, :region)
+  S3Client = ::Data.define(:bucket, :region)
 
   # A dummy SFTP client
-  SFTPClient = Data.define(:host, :username, :password)
+  SFTPClient = ::Data.define(:host, :username, :password)
 
   # Map these fields to an S3 client
   S3Config = Types::Hash[

data/examples/event_registry.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'plumb'
+require 'time'
+require 'uri'
+require 'securerandom'
+require 'debug'
+
+# Bring Plumb into our own namespace
+# and define some basic types
+module Types
+  include Plumb::Types
+
+  # Turn an ISO8601 string into a Time object
+  ISOTime = String.build(::Time, :parse).policy(:rescue, ArgumentError)
+
+  # A type that can be a Time object or an ISO8601 string >> Time
+  Time = Any[::Time] | ISOTime
+
+  # A UUID string, or generate a new one
+  AutoUUID = UUID::V4.default { SecureRandom.uuid }
+end
+
+# A superclass and registry to define event types
+# for example for an event-driven or event-sourced system.
+# All events have an "envelope" set of attributes,
+# including unique ID, stream_id, type, timestamp, causation ID,
+# event subclasses have a type string (ex. 'users.name.updated') and an optional payload
+# This class provides a `.define` method to create new event types with a type and optional payload struct,
+# a `.from` method to instantiate the correct subclass from a hash, ex. when deserializing from JSON or a web request.
+# and a `#follow` method to produce new events based on a previous event's envelope, where the #causation_id and #correlation_id
+# are set to the parent event
+# @example
+#
+#  # Define event struct with type and payload
+#  UserCreated = Event.define('users.created') do
+#    attribute :name, Types::String
+#    attribute :email, Types::Email
+#  end
+#
+#  # Instantiate a full event with .new
+#  user_created = UserCreated.new(stream_id: 'user-1', payload: { name: 'Joe', email: '...' })
+#
+#  # Use the `.from(Hash) => Event` factory to lookup event class by `type` and produce the right instance
+#  user_created = Event.from(type: 'users.created', stream_id: 'user-1', payload: { name: 'Joe', email: '...' })
+#
+#  # Use #follow(payload Hash) => Event to produce events following a command or parent event
+#  create_user = CreateUser.new(...)
+#  user_created = create_user.follow(UserCreated, name: 'Joe', email: '...')
+#  user_created.causation_id == create_user.id
+#  user_created.correlation_id == create_user.correlation_id
+#  user_created.stream_id == create_user.stream_id
+#
+# ## JSON Schemas
+# Plumb data structs support `.to_json_schema`, so you can document all events in the registry with something like
+#
+#   Event.registry.values.map(&:to_json_schema)
+#
+class Event < Types::Data
+  attribute :id, Types::AutoUUID
+  attribute :stream_id, Types::String.present
+  attribute :type, Types::String
+  attribute(:created_at, Types::Time.default { ::Time.now })
+  attribute? :causation_id, Types::UUID::V4
+  attribute? :correlation_id, Types::UUID::V4
+  attribute :payload, Types::Static[nil]
+
+  def self.registry
+    @registry ||= {}
+  end
+
+  # Custom node_name to trigger specialiesed JSON Schema visitor handler.
+  def self.node_name = :event
+
+  def self.define(type_str, &payload_block)
+    type_str.freeze unless type_str.frozen?
+    registry[type_str] = Class.new(self) do
+      def self.node_name = :data
+
+      attribute :type, Types::Static[type_str]
+      attribute :payload, &payload_block if block_given?
+    end
+  end
+
+  def self.from(attrs)
+    klass = registry[attrs[:type]]
+    raise ArgumentError, "Unknown event type: #{attrs[:type]}" unless klass
+
+    klass.new(attrs)
+  end
+
+  def follow(event_class, payload_attrs = nil)
+    attrs = { stream_id:, causation_id: id, correlation_id: }
+    attrs[:payload] = payload_attrs if payload_attrs
+    event_class.new(attrs)
+  end
+end
+
+# Example command and events for a simple event-sourced system
+#
+# ## Commands
+CreateUser = Event.define('users.create') do
+  attribute :name, Types::String.present
+  attribute :email, Types::Email
+end
+
+UpdateUserName = Event.define('users.update_name') do
+  attribute :name, Types::String.present
+end
+#
+# ## Events
+UserCreated = Event.define('users.created') do
+  attribute :name, Types::String
+  attribute :email, Types::Email
+end
+
+UserNameUpdated = Event.define('users.name_updated') do
+  attribute :name, Types::String
+end
+
+# Register a JSON Schema visitor handlers to render Event.registry as a "AnyOf" list of event types
+Plumb::JSONSchemaVisitor.on(:event) do |node, props|
+  props.merge('type' => 'object', 'anyOf' => node.registry.values.map { |v| visit(v) })
+end
+
+p Plumb::JSONSchemaVisitor.call(Event)
+# debugger

data/examples/weekdays.rb

@@ -52,7 +52,7 @@ p Types::DayName.parse('TueSday')                   # => "tuesday
 p Types::Week.parse([3, 2, 1, 4, 5, 6, 7])          # => [1, 2, 3, 4, 5, 6, 7]
 p Types::Week.parse([1, 'Tuesday', 3, 4, 5, 'saturday', 7]) # => [1, 2, 3, 4, 5, 6, 7]
 
-# p Types::Week[[1, 1, 3, 4, 5, 6, 7]] # raises Plumb::TypeError: repeated days
+# p Types::Week[[1, 1, 3, 4, 5, 6, 7]] # raises Plumb::ParseError: repeated days
 #
 # Or use these types as part of other composite types, ex.
 #

data/lib/plumb/and.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-require 'plumb/steppable'
+require 'plumb/composable'
 
 module Plumb
   class And
-    include Steppable
+    include Composable
 
-    attr_reader :left, :right
+    attr_reader :children
 
     def initialize(left, right)
       @left = left
       @right = right
+      @children = [left, right].freeze
       freeze
     end