plumb 0.0.4 → 0.0.6

data/lib/plumb/composable.rb

@@ -13,7 +13,7 @@ module Plumb
     def empty? = true
   end
 
-  TypeError = Class.new(::TypeError)
+  ParseError = Class.new(::TypeError)
   Undefined = UndefinedClass.new.freeze
 
   BLANK_STRING = ''
@@ -29,7 +29,7 @@ module Plumb
 
     def parse(value = Undefined)
       result = resolve(value)
-      raise TypeError, result.errors if result.invalid?
+      raise ParseError, result.errors if result.invalid?
 
       result.value
     end
@@ -87,6 +87,7 @@ module Plumb
   #  Composable mixes in composition methods to classes.
   # such as #>>, #|, #not, and others.
   # Any Composable class can participate in Plumb compositions.
+  # A host object only needs to implement the Step interface `call(Result::Valid) => Result::Valid | Result::Invalid`
   module Composable
     include Callable
 
@@ -96,11 +97,35 @@ module Plumb
       base.send(:include, Naming)
     end
 
+    # Wrap an object in a Composable instance.
+    # Anything that includes Composable is a noop.
+    # A Hash is assumed to be a HashClass schema.
+    # An Array with zero or 1 element is assumed to be an ArrayClass.
+    # Any `#call(Result) => Result` interface is wrapped in a Step.
+    # Anything else is assumed to be something you want to match against via `#===`.
+    #
+    # @example
+    #   ten = Composable.wrap(10)
+    #   ten.resolve(10) # => Result::Valid
+    #   ten.resolve(11) # => Result::Invalid
+    #
+    # @param callable [Object]
+    # @return [Composable]
     def self.wrap(callable)
       if callable.is_a?(Composable)
         callable
       elsif callable.is_a?(::Hash)
         HashClass.new(schema: callable)
+      elsif callable.is_a?(::Array)
+        element_type = case callable.size
+                       when 0
+                         Types::Any
+                       when 1
+                         callable.first
+                       else
+                         raise ArgumentError, '[element_type] syntax allows a single element type'
+                       end
+        Types::Array[element_type]
       elsif callable.respond_to?(:call)
         Step.new(callable)
       else
@@ -108,26 +133,66 @@ module Plumb
       end
     end
 
+    # A helper to wrap a block in a Step that will defer execution.
+    # This so that types can be used recursively in compositions.
+    # @example
+    #   LinkedList = Types::Hash[
+    #     value: Types::Any,
+    #     next: Types::Any.defer { LinkedList }
+    #   ]
     def defer(definition = nil, &block)
       Deferred.new(definition || block)
     end
 
+    # Chain two composable objects together.
+    # A.K.A "and" or "sequence"
+    # @example
+    #   Step1 >> Step2 >> Step3
+    #
+    # @param other [Composable]
+    # @return [And]
     def >>(other)
       And.new(self, Composable.wrap(other))
     end
 
+    # Chain two composable objects together as a disjunction ("or").
+    #
+    # @param other [Composable]
+    # @return [Or]
     def |(other)
       Or.new(self, Composable.wrap(other))
     end
 
+    # Transform value. Requires specifying the resulting type of the value after transformation.
+    # @example
+    #   Types::String.transform(Types::Symbol, &:to_sym)
+    #
+    # @param target_type [Class] what type this step will transform the value to
+    # @param callable [#call, nil] a callable that will be applied to the value, or nil if block provided
+    # @param block [Proc] a block that will be applied to the value, or nil if callable provided
+    # @return [And]
     def transform(target_type, callable = nil, &block)
       self >> Transform.new(target_type, callable || block)
     end
 
+    # Pass the value through an arbitrary validation
+    # @example
+    #   type = Types::String.check('must start with "Role:"') { |value| value.start_with?('Role:') }
+    #
+    # @param errors [String] error message to use when validation fails
+    # @param block [Proc] a block that will be applied to the value
+    # @return [And]
     def check(errors = 'did not pass the check', &block)
       self >> MatchClass.new(block, error: errors, label: errors)
     end
 
+    # Return a new Step with added metadata, or build step metadata if no argument is provided.
+    # @example
+    #   type = Types::String.metadata(label: 'Name')
+    #   type.metadata # => { type: String, label: 'Name' }
+    #
+    # @param data [Hash] metadata to add to the step
+    # @return [Hash, And]
     def metadata(data = Undefined)
       if data == Undefined
         MetadataVisitor.call(self)
@@ -136,24 +201,54 @@ module Plumb
       end
     end
 
+    # Negate the result of a step.
+    # Ie. if the step is valid, it will be invalid, and vice versa.
+    # @example
+    #   type = Types::String.not
+    #   type.resolve('foo') # invalid
+    #   type.resolve(10) # valid
+    #
+    # @return [Not]
     def not(other = self)
       Not.new(other)
     end
 
+    # Like #not, but with a custom error message.
+    #
+    # @option errors [String] error message to use when validation fails
+    # @return [Not]
     def invalid(errors: nil)
       Not.new(self, errors:)
     end
 
+    #  Match a value using `#==`
+    # Normally you'll build matchers via ``#[]`, which uses `#===`.
+    # Use this if you want to match against concrete instances of things that respond to `#===`
+    # @example
+    #   regex = Types::Any.value(/foo/)
+    #   regex.resolve('foo') # invalid. We're matching against the regex itself.
+    #   regex.resolve(/foo/) # valid
+    #
+    # @param value [Object]
+    # @rerurn [And]
     def value(val)
       self >> ValueClass.new(val)
     end
 
+    # Alias of `#[]`
+    # Match a value using `#===`
+    # @example
+    #   email = Types::String['@']
+    #
+    # @param args [Array<Object>]
+    # @return [And]
     def match(*args)
       self >> MatchClass.new(*args)
     end
 
     def [](val) = match(val)
 
+    #  Support #as_node.
     class Node
       include Composable
 
@@ -169,6 +264,14 @@ module Plumb
       def call(result) = type.call(result)
     end
 
+    #  Wrap a Step in a node with a custom #node_name
+    # which is expected by visitors.
+    # So that we can define special visitors for certain compositions.
+    # Ex. Types::Boolean is a compoition of Types::True | Types::False, but we want to treat it as a single node.
+    #
+    # @param node_name [Symbol]
+    # @param metadata [Hash]
+    # @return [Node]
     def as_node(node_name, metadata = BLANK_HASH)
       Node.new(node_name, self, metadata)
     end
@@ -186,7 +289,7 @@ module Plumb
 
         bargs = [self]
         arg = Undefined
-        if rest.any?
+        if rest.size.positive?
           bargs << rest.first
           arg = rest.first
         end
@@ -201,6 +304,9 @@ module Plumb
       end
     end
 
+    # `#===` equality. So that Plumb steps can be used in case statements and pattern matching.
+    # @param other [Object]
+    # @return [Boolean]
     def ===(other)
       case other
       when Composable
@@ -211,15 +317,39 @@ module Plumb
     end
 
     def ==(other)
-      other.is_a?(self.class) && other.children == children
+      other.is_a?(self.class) && other.respond_to?(:children) && other.children == children
     end
 
+    # Visitors expect a #node_name and #children interface.
+    # @return [Array<Composable>]
     def children = BLANK_ARRAY
 
+    # Compose a step that instantiates a class.
+    # @example
+    #   type = Types::String.build(MyClass, :new)
+    #   thing = type.parse('foo') # same as MyClass.new('foo')
+    #
+    # It sets the class as the output type of the step.
+    # Optionally takes a block.
+    #
+    #   type = Types::String.build(Money) { |value| Monetize.parse(value) }
+    #
+    # @param cns [Class] constructor class or object.
+    # @param factory_method [Symbol] method to call on the class to instantiate it.
+    # @return [And]
     def build(cns, factory_method = :new, &block)
       self >> Build.new(cns, factory_method:, &block)
     end
 
+    # Build a Plumb::Pipeline with this object as the starting step.
+    # @example
+    #   pipe = Types::Data[name: String].pipeline do |pl|
+    #     pl.step Validate
+    #     pl.step Debug
+    #     pl.step Log
+    # end
+    #
+    # @return [Pipeline]
     def pipeline(&block)
       Pipeline.new(self, &block)
     end

data/lib/plumb/hash_class.rb

@@ -139,17 +139,8 @@ module Plumb
     end
 
     def wrap_keys_and_values(hash)
-      case hash
-      when ::Array
-        hash.map { |e| wrap_keys_and_values(e) }
-      when ::Hash
-        hash.each.with_object({}) do |(k, v), ret|
-          ret[Key.wrap(k)] = wrap_keys_and_values(v)
-        end
-      when Callable
-        hash
-      else #  leaf values
-        Composable.wrap(hash)
+      hash.each.with_object({}) do |(k, v), ret|
+        ret[Key.wrap(k)] = Composable.wrap(v)
       end
     end
 

data/lib/plumb/json_schema_visitor.rb

@@ -24,6 +24,7 @@ module Plumb
     MAX_ITEMS = 'maxItems'
     MIN_LENGTH = 'minLength'
     MAX_LENGTH = 'maxLength'
+    FORMAT = 'format'
     ENVELOPE = {
       '$schema' => 'https://json-schema.org/draft-08/schema#'
     }.freeze
@@ -192,6 +193,14 @@ module Plumb
       props.merge(TYPE => 'boolean')
     end
 
+    on(:uuid) do |_node, props|
+      props.merge(TYPE => 'string', FORMAT => 'uuid')
+    end
+
+    on(:email) do |_node, props|
+      props.merge(TYPE => 'string', FORMAT => 'email')
+    end
+
     on(::String) do |_node, props|
       props.merge(TYPE => 'string')
     end
@@ -239,11 +248,23 @@ module Plumb
     end
 
     on(::Time) do |_node, props|
-      props.merge(TYPE => 'string', 'format' => 'date-time')
+      props.merge(TYPE => 'string', FORMAT => 'date-time')
     end
 
     on(::Date) do |_node, props|
-      props.merge(TYPE => 'string', 'format' => 'date')
+      props.merge(TYPE => 'string', FORMAT => 'date')
+    end
+
+    on(::URI::Generic) do |_node, props|
+      props.merge(TYPE => 'string', FORMAT => 'uri')
+    end
+
+    on(::URI::HTTP) do |_node, props|
+      props.merge(TYPE => 'string', FORMAT => 'uri')
+    end
+
+    on(::URI::File) do |_node, props|
+      props.merge(TYPE => 'string', FORMAT => 'uri')
     end
 
     on(::Hash) do |_node, props|

data/lib/plumb/match_class.rb

@@ -9,7 +9,7 @@ module Plumb
     attr_reader :children
 
     def initialize(matcher = Undefined, error: nil, label: nil)
-      raise TypeError 'matcher must respond to #===' unless matcher.respond_to?(:===)
+      raise ParseError 'matcher must respond to #===' unless matcher.respond_to?(:===)
 
       @matcher = matcher
       @error = error.nil? ? build_error(matcher) : (error % matcher)

data/lib/plumb/pipeline.rb

@@ -19,12 +19,28 @@ module Plumb
       end
     end
 
+    class << self
+      def around_blocks
+        @around_blocks ||= []
+      end
+
+      def around(callable = nil, &block)
+        around_blocks << (callable || block)
+        self
+      end
+
+      def inherited(subclass)
+        around_blocks.each { |block| subclass.around(block) }
+        super
+      end
+    end
+
     attr_reader :children
 
     def initialize(type = Types::Any, &setup)
       @type = type
       @children = [type].freeze
-      @around_blocks = []
+      @around_blocks = self.class.around_blocks.dup
       return unless block_given?
 
       configure(&setup)
@@ -42,7 +58,8 @@ module Plumb
               "#step expects an interface #call(Result) Result, but got #{callable.inspect}"
       end
 
-      callable = @around_blocks.reduce(callable) { |cl, bl| AroundStep.new(cl, bl) } if @around_blocks.any?
+      callable = prepare_step(callable)
+      callable = @around_blocks.reverse.reduce(callable) { |cl, bl| AroundStep.new(cl, bl) } if @around_blocks.any?
       @type >>= callable
       self
     end
@@ -70,5 +87,7 @@ module Plumb
 
       true
     end
+
+    def prepare_step(callable) = callable
   end
 end

data/lib/plumb/tagged_hash.rb

@@ -21,7 +21,7 @@ module Plumb
       # types are assumed to have literal values for the index field :key
       @index = @children.each.with_object({}) do |t, memo|
         key_type = t.at_key(@key)
-        raise TypeError, "key type at :#{@key} #{key_type} must be a Match type" unless key_type.is_a?(MatchClass)
+        raise ParseError, "key type at :#{@key} #{key_type} must be a Match type" unless key_type.is_a?(MatchClass)
 
         memo[key_type.children[0]] = t
       end

data/lib/plumb/types.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require 'bigdecimal'
+require 'uri'
+require 'date'
+require 'time'
 
 module Plumb
   # Define core policies
@@ -104,6 +107,18 @@ module Plumb
     (Types::Undefined >> val_type) | type
   end
 
+  # Wrap a step execution in a rescue block.
+  # Expect a specific exception class, and return an invalid result if it is raised.
+  # Usage:
+  #   type = Types::String.build(Date, :parse).policy(:rescue, Date::Error)
+  policy :rescue do |type, exception_class|
+    Step.new(nil, 'Rescue') do |result|
+      type.call(result)
+    rescue exception_class => e
+      result.invalid(errors: e.message)
+    end
+  end
+
   # Split a string into an array. Default separator is /\s*,\s*/
   # Usage:
   #   type = Types::String.split
@@ -145,6 +160,19 @@ module Plumb
     Tuple = TupleClass.new
     Hash = HashClass.new
     Interface = InterfaceClass.new
+    Email = String[URI::MailTo::EMAIL_REGEXP].as_node(:email)
+    Date = Any[::Date]
+    Time = Any[::Time]
+
+    module UUID
+      V4 = String[/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i].as_node(:uuid)
+    end
+
+    module URI
+      Generic = Any[::URI::Generic]
+      HTTP = Any[::URI::HTTP]
+      File = Any[::URI::File]
+    end
 
     class Data
       extend Composable
@@ -190,6 +218,20 @@ module Plumb
       Boolean = True | False
 
       Nil = Nil | (String[BLANK_STRING] >> nil)
+
+      # Accept a Date, or a string that can be parsed into a Date
+      # via Date.parse
+      Date = Date | (String >> Any.build(::Date, :parse).policy(:rescue, ::Date::Error))
+      Time = Time | (String >> Any.build(::Time, :parse).policy(:rescue, ::ArgumentError))
+
+      # Turn strings into different URI types
+      module URI
+        # URI.parse is very permisive - a blank string is valid.
+        # We want to ensure that a generic URI at least starts with a scheme as per RFC 3986
+        Generic = Types::URI::Generic | (String[/^([a-z][a-z0-9+\-.]*)/].build(::URI, :parse))
+        HTTP = Generic[::URI::HTTP]
+        File = Generic[::URI::File]
+      end
     end
   end
 end

data/lib/plumb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumb
-  VERSION = '0.0.4'
+  VERSION = '0.0.6'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plumb
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.6
 platform: ruby
 authors:
 - Ismael Celis
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-05 00:00:00.000000000 Z
+date: 2024-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -50,6 +50,10 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bench/compare_parametric_schema.rb
+- bench/compare_parametric_struct.rb
+- bench/parametric_schema.rb
+- bench/plumb_hash.rb
 - examples/command_objects.rb
 - examples/concurrent_downloads.rb
 - examples/csv_stream.rb