plumb 0.0.3 → 0.0.5

data/lib/plumb/composable.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+require 'plumb/metadata_visitor'
+
+module Plumb
+  class UndefinedClass
+    def inspect
+      %(Undefined)
+    end
+
+    def to_s = inspect
+    def node_name = :undefined
+    def empty? = true
+  end
+
+  ParseError = Class.new(::TypeError)
+  Undefined = UndefinedClass.new.freeze
+
+  BLANK_STRING = ''
+  BLANK_ARRAY = [].freeze
+  BLANK_HASH = {}.freeze
+  BLANK_RESULT = Result.wrap(Undefined)
+  NOOP = ->(result) { result }
+
+  module Callable
+    def resolve(value = Undefined)
+      call(Result.wrap(value))
+    end
+
+    def parse(value = Undefined)
+      result = resolve(value)
+      raise ParseError, result.errors if result.invalid?
+
+      result.value
+    end
+
+    def call(result)
+      raise NotImplementedError, "Implement #call(Result) => Result in #{self.class}"
+    end
+  end
+
+  # This module gets included by Composable,
+  # but only when Composable is `included` in classes, not `extended`.
+  # The rule of this module is to assign a name to constants that point to Composable instances.
+  module Naming
+    attr_reader :name
+
+    # When including this module,
+    # define a #node_name method on the Composable instance
+    # #node_name is used by Visitors to determine the type of node.
+    def self.included(base)
+      nname = base.name.split('::').last
+      nname.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+      nname.downcase!
+      nname.gsub!(/_class$/, '')
+      nname = nname.to_sym
+      base.define_method(:node_name) { nname }
+    end
+
+    class Name
+      def initialize(name)
+        @name = name
+      end
+
+      def to_s = @name
+
+      def set(n)
+        @name = n
+        self
+      end
+    end
+
+    def freeze
+      return self if frozen?
+
+      @name = Name.new(_inspect)
+      super
+    end
+
+    private def _inspect = self.class.name
+
+    def inspect = name.to_s
+
+    def node_name = self.class.name.split('::').last.to_sym
+  end
+
+  #  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
+
+    # This only runs when including Composable,
+    # not extending classes with it.
+    def self.included(base)
+      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.
+    # 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.respond_to?(:call)
+        Step.new(callable)
+      else
+        MatchClass.new(callable)
+      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)
+      else
+        self >> Metadata.new(data)
+      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
+
+      attr_reader :node_name, :type, :attributes
+
+      def initialize(node_name, type, attributes = BLANK_HASH)
+        @node_name = node_name
+        @type = type
+        @attributes = attributes
+        freeze
+      end
+
+      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
+
+    # Register a policy for this step.
+    # Mode 1.a: #policy(:name, arg) a single policy with an argument
+    # Mode 1.b: #policy(:name) a single policy without an argument
+    # Mode 2: #policy(p1: value, p2: value) multiple policies with arguments
+    # The latter mode will be expanded to multiple #policy calls.
+    # @return [Step]
+    def policy(*args, &blk)
+      case args
+      in [::Symbol => name, *rest] # #policy(:name, arg)
+        types = Array(metadata[:type]).uniq
+
+        bargs = [self]
+        arg = Undefined
+        if rest.size.positive?
+          bargs << rest.first
+          arg = rest.first
+        end
+        block = Plumb.policies.get(types, name)
+        pol = block.call(*bargs, &blk)
+
+        Policy.new(name, arg, pol)
+      in [::Hash => opts] # #policy(p1: value, p2: value)
+        opts.reduce(self) { |step, (name, value)| step.policy(name, value) }
+      else
+        raise ArgumentError, "expected a symbol or hash, got #{args.inspect}"
+      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
+        other == self
+      else
+        resolve(other).valid?
+      end
+    end
+
+    def ==(other)
+      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
+
+    def to_s
+      inspect
+    end
+
+    # @option root [Boolean] whether to include JSON Schema $schema property
+    # @return [Hash]
+    def to_json_schema(root: false)
+      JSONSchemaVisitor.call(self, root:)
+    end
+
+    # Build a step that will invoke one or more methods on the value.
+    # Ex 1: Types::String.invoke(:downcase)
+    # Ex 2: Types::Array.invoke(:[], 1)
+    # Ex 3 chain of methods: Types::String.invoke([:downcase, :to_sym])
+    # @return [Step]
+    def invoke(*args, &block)
+      case args
+      in [::Symbol => method_name, *rest]
+        self >> Step.new(
+          ->(result) { result.valid(result.value.public_send(method_name, *rest, &block)) },
+          [method_name.inspect, rest.inspect].join(' ')
+        )
+      in [Array => methods] if methods.all? { |m| m.is_a?(Symbol) }
+        methods.reduce(self) { |step, method| step.invoke(method) }
+      else
+        raise ArgumentError, "expected a symbol or array of symbols, got #{args.inspect}"
+      end
+    end
+  end
+end
+
+require 'plumb/deferred'
+require 'plumb/transform'
+require 'plumb/policy'
+require 'plumb/build'
+require 'plumb/metadata'

data/lib/plumb/decorator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Plumb
+  # A class to help decorate all or some types in a
+  # type composition.
+  # Example:
+  #   Type = Types::Array[Types::String | Types::Integer]
+  #   Decorated = Plumb::Decorator.(Type) do |type|
+  #     if type.is_a?(Plumb::ArrayClass)
+  #       LoggerType.new(type, 'array')
+  #     else
+  #       type
+  #     end
+  #   end
+  class Decorator
+    def self.call(type, &block)
+      new(block).visit(type)
+    end
+
+    def initialize(block)
+      @block = block
+    end
+
+    # @param type [Composable]
+    # @return [Composable]
+    def visit(type)
+      type = case type
+             when And
+               left, right = visit_children(type)
+               And.new(left, right)
+             when Or
+               left, right = visit_children(type)
+               Or.new(left, right)
+             when Not
+               child = visit_children(type).first
+               Not.new(child, errors: type.errors)
+             when Policy
+               child = visit_children(type).first
+               Policy.new(type.policy_name, type.arg, child)
+             else
+               type
+             end
+
+      decorate(type)
+    end
+
+    private
+
+    def visit_children(type)
+      type.children.map { |child| visit(child) }
+    end
+
+    def decorate(type)
+      @block.call(type)
+    end
+  end
+end

data/lib/plumb/deferred.rb

@@ -4,7 +4,7 @@ require 'thread'
 
 module Plumb
   class Deferred
-    include Steppable
+    include Composable
 
     def initialize(definition)
       @lock = Mutex.new

data/lib/plumb/hash_class.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'plumb/steppable'
+require 'plumb/composable'
 require 'plumb/key'
 require 'plumb/static_class'
 require 'plumb/hash_map'
@@ -8,7 +8,9 @@ require 'plumb/tagged_hash'
 
 module Plumb
   class HashClass
-    include Steppable
+    include Composable
+
+    NOT_A_HASH = { _: 'must be a Hash' }.freeze
 
     attr_reader :_schema
 
@@ -31,7 +33,7 @@ module Plumb
       in [::Hash => hash]
         self.class.new(schema: _schema.merge(wrap_keys_and_values(hash)), inclusive: @inclusive)
       in [key_type, value_type]
-        HashMap.new(Steppable.wrap(key_type), Steppable.wrap(value_type))
+        HashMap.new(Composable.wrap(key_type), Composable.wrap(value_type))
       else
         raise ::ArgumentError, "unexpected value to Types::Hash#schema #{args.inspect}"
       end
@@ -44,9 +46,14 @@ module Plumb
     # we need to keep the right-side key, because even if the key name is the same,
     # it's optional flag might have changed
     def +(other)
-      raise ArgumentError, "expected a HashClass, got #{other.class}" unless other.is_a?(HashClass)
-
-      self.class.new(schema: merge_rightmost_keys(_schema, other._schema), inclusive: @inclusive)
+      other_schema = case other
+                     when HashClass then other._schema
+                     when ::Hash then other
+                     else
+                       raise ArgumentError, "expected a HashClass or Hash, got #{other.class}"
+                     end
+
+      self.class.new(schema: merge_rightmost_keys(_schema, other_schema), inclusive: @inclusive)
     end
 
     def &(other)
@@ -97,7 +104,7 @@ module Plumb
     end
 
     def call(result)
-      return result.invalid(errors: 'must be a Hash') unless result.value.is_a?(::Hash)
+      return result.invalid(errors: NOT_A_HASH) unless result.value.is_a?(::Hash)
       return result unless _schema.any?
 
       input = result.value
@@ -121,6 +128,10 @@ module Plumb
       errors.any? ? result.invalid(output, errors:) : result.valid(output)
     end
 
+    def ==(other)
+      other.is_a?(self.class) && other._schema == _schema
+    end
+
     private
 
     def _inspect
@@ -138,7 +149,7 @@ module Plumb
       when Callable
         hash
       else #  leaf values
-        Steppable.wrap(hash)
+        Composable.wrap(hash)
       end
     end
 

data/lib/plumb/hash_map.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-require 'plumb/steppable'
+require 'plumb/composable'
 
 module Plumb
   class HashMap
-    include Steppable
+    include Composable
 
-    attr_reader :key_type, :value_type
+    attr_reader :children
 
     def initialize(key_type, value_type)
       @key_type = key_type
       @value_type = value_type
+      @children = [key_type, value_type].freeze
       freeze
     end
 
@@ -35,19 +36,20 @@ module Plumb
     end
 
     def filtered
-      FilteredHashMap.new(key_type, value_type)
+      FilteredHashMap.new(@key_type, @value_type)
     end
 
     private def _inspect = "HashMap[#{@key_type.inspect}, #{@value_type.inspect}]"
 
     class FilteredHashMap
-      include Steppable
+      include Composable
 
-      attr_reader :key_type, :value_type
+      attr_reader :children
 
       def initialize(key_type, value_type)
         @key_type = key_type
         @value_type = value_type
+        @children = [key_type, value_type].freeze
         freeze
       end
 

data/lib/plumb/interface_class.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'plumb/steppable'
+require 'plumb/composable'
 
 module Plumb
   class InterfaceClass
-    include Steppable
+    include Composable
 
     attr_reader :method_names
 
@@ -13,6 +13,10 @@ module Plumb
       freeze
     end
 
+    def ==(other)
+      other.is_a?(self.class) && other.method_names == method_names
+    end
+
     def of(*args)
       case args
       in Array => symbols if symbols.all? { |s| s.is_a?(::Symbol) }