dry-types 0.15.0 → 1.0.0

data/lib/dry/types/meta.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Dry
+  module Types
+    # Storage for meta-data
+    #
+    # @api public
+    module Meta
+      def initialize(*args, meta: EMPTY_HASH, **options)
+        super(*args, **options)
+        @meta = meta.freeze
+      end
+
+      # @param [Hash] new_options
+      #
+      # @return [Type]
+      #
+      # @api public
+      def with(options)
+        super(meta: @meta, **options)
+      end
+
+      # @overload meta
+      #   @return [Hash] metadata associated with type
+      #
+      # @overload meta(data)
+      #   @param [Hash] new metadata to merge into existing metadata
+      #   @return [Type] new type with added metadata
+      #
+      # @api public
+      def meta(data = nil)
+        if !data
+          @meta
+        elsif data.empty?
+          self
+        else
+          with(meta: @meta.merge(data))
+        end
+      end
+
+      # Resets meta
+      #
+      # @return [Dry::Types::Type]
+      #
+      # @api public
+      def pristine
+        with(meta: EMPTY_HASH)
+      end
+    end
+  end
+end

data/lib/dry/types/module.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/core/deprecations'
 require 'dry/types/builder_methods'
 
@@ -6,12 +8,15 @@ module Dry
     # Export types registered in a container as module constants.
     # @example
     #   module Types
-    #     include Dry::Types.module(:strict, :coercible, :nominal, default: :strict)
+    #     include Dry::Types(:strict, :coercible, :nominal, default: :strict)
     #   end
-    #   # Types.constants
+    #
+    #   Types.constants
     #   # => [:Class, :Strict, :Symbol, :Integer, :Float, :String, :Array, :Hash,
     #   #     :Decimal, :Nil, :True, :False, :Bool, :Date, :Nominal, :DateTime, :Range,
     #   #     :Coercible, :Time]
+    #
+    # @api public
     class Module < ::Module
       def initialize(registry, *args)
         @registry = registry

data/lib/dry/types/nominal.rb

@@ -1,13 +1,22 @@
+# frozen_string_literal: true
+
 require 'dry/core/deprecations'
 require 'dry/types/builder'
 require 'dry/types/result'
 require 'dry/types/options'
+require 'dry/types/meta'
 
 module Dry
   module Types
+    # Nominal types define a primitive class and do not apply any constructors or constraints
+    #
+    # Use these types for annotations and the base for building more complex types on top of them.
+    #
+    # @api public
     class Nominal
       include Type
       include Options
+      include Meta
       include Builder
       include Printable
       include Dry::Equalizer(:primitive, :options, :meta, inspect: false)
@@ -16,7 +25,10 @@ module Dry
       attr_reader :primitive
 
       # @param [Class] primitive
+      #
       # @return [Type]
+      #
+      # @api private
       def self.[](primitive)
         if primitive == ::Array
           Types::Array
@@ -27,8 +39,12 @@ module Dry
         end
       end
 
+      ALWAYS = proc { true }
+
       # @param [Type,Class] primitive
       # @param [Hash] options
+      #
+      # @api private
       def initialize(primitive, **options)
         super
         @primitive = primitive
@@ -36,76 +52,152 @@ module Dry
       end
 
       # @return [String]
+      #
+      # @api public
       def name
         primitive.name
       end
 
       # @return [false]
+      #
+      # @api public
       def default?
         false
       end
 
       # @return [false]
+      #
+      # @api public
       def constrained?
         false
       end
 
       # @return [false]
+      #
+      # @api public
       def optional?
         false
       end
 
       # @param [BasicObject] input
+      #
+      # @return [BasicObject]
+      #
+      # @api private
+      def call_unsafe(input)
+        input
+      end
+
+      # @param [BasicObject] input
+      #
       # @return [BasicObject]
-      def call(input)
+      #
+      # @api private
+      def call_safe(input)
         input
       end
-      alias_method :[], :call
 
       # @param [Object] input
       # @param [#call,nil] block
+      #
       # @yieldparam [Failure] failure
       # @yieldreturn [Result]
+      #
       # @return [Result,Logic::Result] when a block is not provided
       # @return [nil] otherwise
-      def try(input, &block)
-        if valid?(input)
-          success(input)
-        else
-          failure = failure(input, "#{input.inspect} must be an instance of #{primitive}")
-          block ? yield(failure) : failure
-        end
+      #
+      # @api public
+      def try(input)
+        success(input)
       end
 
       # @param (see Dry::Types::Success#initialize)
+      #
       # @return [Result::Success]
+      #
+      # @api public
       def success(input)
         Result::Success.new(input)
       end
 
       # @param (see Failure#initialize)
+      #
       # @return [Result::Failure]
+      #
+      # @api public
       def failure(input, error)
+        unless error.is_a?(CoercionError)
+          raise ArgumentError, "error must be a CoercionError"
+        end
         Result::Failure.new(input, error)
       end
 
       # Checks whether value is of a #primitive class
+      #
       # @param [Object] value
+      #
       # @return [Boolean]
+      #
+      # @api public
       def primitive?(value)
         value.is_a?(primitive)
       end
-      alias_method :valid?, :primitive?
-      alias_method :===, :primitive?
+
+      # @api private
+      def coerce(input, &_block)
+        if primitive?(input)
+          input
+        elsif block_given?
+          yield
+        else
+          raise CoercionError, "#{input.inspect} must be an instance of #{primitive}"
+        end
+      end
+
+      # @api private
+      def try_coerce(input)
+        result = success(input)
+
+        coerce(input) do
+          result = failure(
+            input,
+            CoercionError.new("#{input.inspect} must be an instance of #{primitive}")
+          )
+        end
+
+        if block_given?
+          yield(result)
+        else
+          result
+        end
+      end
 
       # Return AST representation of a type nominal
       #
-      # @api public
-      #
       # @return [Array]
+      #
+      # @api public
       def to_ast(meta: true)
         [:nominal, [primitive, meta ? self.meta : EMPTY_HASH]]
       end
+
+      # Return self. Nominal types are lax by definition
+      #
+      # @return [Nominal]
+      #
+      # @api public
+      def lax
+        self
+      end
+
+      # Wrap the type with a proc
+      #
+      # @return [Proc]
+      #
+      # @api public
+      def to_proc
+        ALWAYS
+      end
     end
 
     extend Dry::Core::Deprecations[:'dry-types']

data/lib/dry/types/options.rb

@@ -1,42 +1,29 @@
+# frozen_string_literal: true
+
 module Dry
   module Types
+    # Common API for types with options
+    #
+    # @api private
     module Options
       # @return [Hash]
       attr_reader :options
 
       # @see Nominal#initialize
-      def initialize(*args, meta: EMPTY_HASH, **options)
+      #
+      # @api private
+      def initialize(*args, **options)
         @__args__ = args.freeze
         @options = options.freeze
-        @meta = meta.freeze
       end
 
       # @param [Hash] new_options
+      #
       # @return [Type]
-      def with(**new_options)
-        self.class.new(*@__args__, **options, meta: @meta, **new_options)
-      end
-
-      # @overload meta
-      #   @return [Hash] metadata associated with type
       #
-      # @overload meta(data)
-      #   @param [Hash] new metadata to merge into existing metadata
-      #   @return [Type] new type with added metadata
-      def meta(data = nil)
-        if !data
-          @meta
-        elsif data.empty?
-          self
-        else
-          with(meta: @meta.merge(data))
-        end
-      end
-
-      # Resets meta
-      # @return [Dry::Types::Type]
-      def pristine
-        with(meta: EMPTY_HASH)
+      # @api private
+      def with(**new_options)
+        self.class.new(*@__args__, **options, **new_options)
       end
     end
   end

data/lib/dry/types/params.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dry/types/coercions/params'
 
 module Dry
@@ -27,7 +29,7 @@ module Dry
     end
 
     register('params.bool') do
-      (self['params.true'] | self['params.false']).safe
+      self['params.true'] | self['params.false']
     end
 
     register('params.integer') do
@@ -43,11 +45,11 @@ module Dry
     end
 
     register('params.array') do
-      self['nominal.array'].constructor(Coercions::Params.method(:to_ary)).safe
+      self['nominal.array'].constructor(Coercions::Params.method(:to_ary))
     end
 
     register('params.hash') do
-      self['nominal.hash'].constructor(Coercions::Params.method(:to_hash)).safe
+      self['nominal.hash'].constructor(Coercions::Params.method(:to_hash))
     end
   end
 end

data/lib/dry/types/printable.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 module Dry
   module Types
+    # @api private
     module Printable
       # @return [String]
-      # @api public
+      #
+      # @api private
       def to_s
         PRINTER.(self) { super }
       end

data/lib/dry/types/printer.rb

@@ -16,7 +16,7 @@ module Dry
         Map => :visit_map,
         Array => :visit_array,
         Array::Member => :visit_array_member,
-        Safe => :visit_safe,
+        Lax => :visit_lax,
         Enum => :visit_enum,
         Default => :visit_default,
         Default::Callable => :visit_default,
@@ -28,7 +28,7 @@ module Dry
       def call(type)
         output = "".dup
         visit(type) { |str| output << str }
-        "#<Dry::Types[#{ output }]>"
+        "#<Dry::Types[#{output}]>"
       end
 
       def visit(type, &block)
@@ -36,7 +36,7 @@ module Dry
           if type.is_a?(Type)
             return yield type.inspect
           else
-            raise ArgumentError, "Do not know how to print #{ type.class }"
+            raise ArgumentError, "Do not know how to print #{type.class}"
           end
         end
         send(print_with, type, &block)
@@ -52,18 +52,18 @@ module Dry
 
       def visit_array_member(array)
         visit(array.member) do |type|
-          yield "Array<#{ type }>"
+          yield "Array<#{type}>"
         end
       end
 
       def visit_constructor(constructor)
         visit(constructor.type) do |type|
-          visit_callable(constructor.fn) do |fn|
+          visit_callable(constructor.fn.fn) do |fn|
             options = constructor.options.dup
             options.delete(:fn)
 
-            visit_options(options, constructor.meta) do |opts|
-              yield "Constructor<#{ type } fn=#{ fn }#{ opts }>"
+            visit_options(options) do |opts|
+              yield "Constructor<#{type} fn=#{fn}#{opts}>"
             end
           end
         end
@@ -74,8 +74,8 @@ module Dry
           options = constrained.options.dup
           rule = options.delete(:rule)
 
-          visit_options(options, constrained.meta) do |opts|
-            yield "Constrained<#{ type } rule=[#{ rule.to_s }]>"
+          visit_options(options) do |opts|
+            yield "Constrained<#{type} rule=[#{rule}]>"
           end
         end
       end
@@ -83,37 +83,38 @@ module Dry
       def visit_schema(schema)
         options = schema.options.dup
         size = schema.count
-        key_fn_str = ""
-        type_fn_str = ""
-        strict_str = ""
+        key_fn_str = ''
+        type_fn_str = ''
+        strict_str = ''
 
-        strict_str = "strict " if options.delete(:strict)
+        strict_str = 'strict ' if options.delete(:strict)
 
         if key_fn = options.delete(:key_transform_fn)
           visit_callable(key_fn) do |fn|
-            key_fn_str = "key_fn=#{ fn } "
+            key_fn_str = "key_fn=#{fn} "
           end
         end
 
         if type_fn = options.delete(:type_transform_fn)
           visit_callable(type_fn) do |fn|
-            type_fn_str = "type_fn=#{ fn } "
+            type_fn_str = "type_fn=#{fn} "
           end
         end
 
         keys = options.delete(:keys)
 
         visit_options(options, schema.meta) do |opts|
-          schema_parameters = "#{ key_fn_str }#{ type_fn_str }#{ strict_str }#{ opts }"
+          opts = "#{opts[1..-1]} " unless opts.empty?
+          schema_parameters = "#{key_fn_str}#{type_fn_str}#{strict_str}#{opts}"
 
-          header = "Schema<#{ schema_parameters }keys={"
+          header = "Schema<#{schema_parameters}keys={"
 
           if size.zero?
             yield "#{ header}}>"
           else
             yield header.dup << keys.map { |key|
               visit(key) { |type| type }
-            }.join(" ") << "}>"
+            }.join(' ') << '}>'
           end
         end
       end
@@ -125,8 +126,8 @@ module Dry
             options.delete(:key_type)
             options.delete(:value_type)
 
-            visit_options(options, map.meta) do |opts|
-              yield "Map<#{ key } => #{ value }>"
+            visit_options(options) do |opts|
+              yield "Map<#{key} => #{value}>"
             end
           end
         end
@@ -135,9 +136,9 @@ module Dry
       def visit_key(key)
         visit(key.type) do |type|
           if key.required?
-            yield "#{ key.name }: #{ type }"
+            yield "#{key.name}: #{type}"
           else
-            yield "#{ key.name }?: #{ type }"
+            yield "#{key.name}?: #{type}"
           end
         end
       end
@@ -145,7 +146,7 @@ module Dry
       def visit_sum(sum)
         visit_sum_constructors(sum) do |constructors|
           visit_options(sum.options, sum.meta) do |opts|
-            yield "Sum<#{ constructors }#{ opts }>"
+            yield "Sum<#{constructors}#{opts}>"
           end
         end
       end
@@ -157,11 +158,11 @@ module Dry
             case sum.right
             when Sum
               visit_sum_constructors(sum.right) do |right|
-                yield "#{ left } | #{ right }"
+                yield "#{left} | #{right}"
               end
             else
               visit(sum.right) do |right|
-                yield "#{ left } | #{ right }"
+                yield "#{left} | #{right}"
               end
             end
           end
@@ -170,11 +171,11 @@ module Dry
             case sum.right
             when Sum
               visit_sum_constructors(sum.right) do |right|
-                yield "#{ left } | #{ right }"
+                yield "#{left} | #{right}"
               end
             else
               visit(sum.right) do |right|
-                yield "#{ left } | #{ right }"
+                yield "#{left} | #{right}"
               end
             end
           end
@@ -186,15 +187,15 @@ module Dry
           options = enum.options.dup
           mapping = options.delete(:mapping)
 
-          visit_options(options, enum.meta) do |opts|
+          visit_options(options) do |opts|
             if mapping == enum.inverted_mapping
-              values = mapping.values.map(&:inspect).join(", ")
-              yield "Enum<#{ type } values={#{ values }}#{ opts }>"
+              values = mapping.values.map(&:inspect).join(', ')
+              yield "Enum<#{type} values={#{values}}#{opts}>"
             else
               mapping_str = mapping.map { |key, value|
-                "#{ key.inspect }=>#{ value.inspect }"
-              }.join(", ")
-              yield "Enum<#{ type } mapping={#{ mapping_str }}#{ opts }>"
+                "#{ key.inspect }=>#{value.inspect}"
+              }.join(', ')
+              yield "Enum<#{type} mapping={#{mapping_str}}#{opts}>"
             end
           end
         end
@@ -202,13 +203,13 @@ module Dry
 
       def visit_default(default)
         visit(default.type) do |type|
-          visit_options(default.options, default.meta) do |opts|
+          visit_options(default.options) do |opts|
             if default.is_a?(Default::Callable)
               visit_callable(default.value) do |fn|
-                yield "Default<#{ type } value_fn=#{ fn }#{ opts }>"
+                yield "Default<#{type} value_fn=#{fn}#{opts}>"
               end
             else
-              yield "Default<#{ type } value=#{ default.value.inspect }#{ opts }>"
+              yield "Default<#{type} value=#{default.value.inspect}#{opts}>"
             end
           end
         end
@@ -216,31 +217,31 @@ module Dry
 
       def visit_nominal(type)
         visit_options(type.options, type.meta) do |opts|
-          yield "Nominal<#{ type.primitive }#{ opts }>"
+          yield "Nominal<#{type.primitive}#{opts}>"
         end
       end
 
-      def visit_safe(safe)
-        visit(safe.type) do |type|
-          yield "Safe<#{ type }>"
+      def visit_lax(lax)
+        visit(lax.type) do |type|
+          yield "Lax<#{type}>"
         end
       end
 
       def visit_hash(hash)
         options = hash.options.dup
-        type_fn_str = ""
+        type_fn_str = ''
 
         if type_fn = options.delete(:type_transform_fn)
           visit_callable(type_fn) do |fn|
-            type_fn_str = "type_fn=#{ fn }"
+            type_fn_str = "type_fn=#{fn}"
           end
         end
 
         visit_options(options, hash.meta) do |opts|
           if opts.empty? && type_fn_str.empty?
-            yield "Hash"
+            yield 'Hash'
           else
-            yield "Hash<#{ type_fn_str }#{ opts }>"
+            yield "Hash<#{type_fn_str}#{opts}>"
           end
         end
       end
@@ -255,36 +256,36 @@ module Dry
           path, line = fn.source_location
 
           if line && line.zero?
-            yield ".#{ path }"
+            yield ".#{path}"
           elsif path
-            yield "#{ path.sub(Dir.pwd + "/", EMPTY_STRING) }:#{ line }"
+            yield "#{path.sub(Dir.pwd + '/', EMPTY_STRING) }:#{line}"
           elsif fn.lambda?
-            yield "(lambda)"
+            yield '(lambda)'
           else
             match = fn.to_s.match(/\A#<Proc:0x\h+\(&:(\w+)\)>\z/)
 
             if match
-              yield ".#{ match[1] }"
+              yield ".#{match[1]}"
             else
-              yield "(proc)"
+              yield '(proc)'
             end
           end
         else
           call = fn.method(:call)
 
           if call.owner == fn.class
-            yield "#{ fn.class.to_s }#call"
+            yield "#{fn.class}#call"
           else
-            yield "#{ fn.to_s }.call"
+            yield "#{fn}.call"
           end
         end
       end
 
-      def visit_options(options, meta)
+      def visit_options(options, meta = EMPTY_HASH)
         if options.empty? && meta.empty?
-          yield ""
+          yield ''
         else
-          opts = options.empty? ? "" : " options=#{ options.inspect }"
+          opts = options.empty? ? '' : " options=#{options.inspect}"
 
           if meta.empty?
             yield opts
@@ -292,13 +293,13 @@ module Dry
             values = meta.map do |key, value|
               case key
               when Symbol
-                "#{ key }: #{ value.inspect }"
+                "#{key}: #{value.inspect}"
               else
-                "#{ key.inspect }=>#{ value.inspect }"
+                "#{key.inspect}=>#{value.inspect}"
               end
             end
 
-            yield "#{ opts } meta={#{ values.join(", ") }}"
+            yield "#{opts} meta={#{values.join(', ')}}"
           end
         end
       end