kind 4.0.0 → 5.3.0

data/Gemfile

@@ -18,24 +18,31 @@ activemodel = case activemodel_version
 
 simplecov_version =
   case RUBY_VERSION
-  when /\A2.[23]/ then '0.17.1'
+  when /\A2.[123]/ then '0.17.1'
   when /\A2.4/ then '~> 0.18.5'
   else '~> 0.19'
   end
 
+is_ruby_2_1 = RUBY_VERSION <= '2.2.0'
+
+minitest_version =
+  if activemodel_version
+    activemodel_version < '4.1' ? '~> 4.2' : '~> 5.0'
+  else
+    is_ruby_2_1 ? '~> 4.2' : '~> 5.0'
+  end
+
 group :test do
   if activemodel_version
     gem 'activesupport', activemodel, require: false
-    gem 'activemodel', activemodel, require: false
-    gem 'minitest', activemodel_version < '4.1' ? '~> 4.2' : '~> 5.0'
-  else
-    gem 'minitest', '~> 5.0'
+    gem 'activemodel'  , activemodel, require: false
   end
 
+  gem 'minitest' , minitest_version
   gem 'simplecov', simplecov_version, require: false
 end
 
-gem 'rake', '~> 13.0'
+gem 'rake', is_ruby_2_1 ? '~> 12.3' : '~> 13.0'
 
 # Specify your gem's dependencies in type_validator.gemspec
 gemspec

data/README.md

@@ -1,12 +1,9 @@
 <p align="center">
   <h1 align="center">🤷 kind</h1>
   <p align="center"><i>A simple type system (at runtime) for Ruby - free of dependencies.</i></p>
-  <br>
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/ruby->%3D%202.2.0-ruby.svg?colorA=99004d&colorB=cc0066" alt="Ruby">
-
   <a href="https://rubygems.org/gems/kind">
     <img alt="Gem" src="https://img.shields.io/gem/v/kind.svg?style=flat-square">
   </a>
@@ -15,6 +12,14 @@
     <img alt="Build Status" src="https://travis-ci.com/serradura/kind.svg?branch=master">
   </a>
 
+  <br />
+
+  <img src="https://img.shields.io/badge/ruby%20%3E=%202.1,%20%3C%203.1-ruby.svg?colorA=99004d&colorB=cc0066" alt="Ruby">
+
+  <img src="https://img.shields.io/badge/rails%20%3E=%203.2.0,%20%3C%207.0-rails.svg?colorA=8B0000&colorB=FF0000" alt="Rails">
+
+  <br />
+
   <a href="https://codeclimate.com/github/serradura/kind/maintainability">
     <img alt="Maintainability" src="https://api.codeclimate.com/v1/badges/711329decb2806ccac95/maintainability">
   </a>
@@ -34,11 +39,12 @@ One of the goals of this project is to do simple type checking like `"some strin
 
 Version    | Documentation
 ---------- | -------------
-unreleased | https://github.com/serradura/u-case/blob/main/README.md
-4.0.0      | https://github.com/serradura/u-case/blob/v4.x/README.md
-3.1.0      | https://github.com/serradura/u-case/blob/v3.x/README.md
-2.3.0      | https://github.com/serradura/u-case/blob/v2.x/README.md
-1.9.0      | https://github.com/serradura/u-case/blob/v1.x/README.md
+unreleased | https://github.com/serradura/kind/blob/main/README.md
+5.3.0      | https://github.com/serradura/kind/blob/v5.x/README.md
+4.1.0      | https://github.com/serradura/kind/blob/v4.x/README.md
+3.1.0      | https://github.com/serradura/kind/blob/v3.x/README.md
+2.3.0      | https://github.com/serradura/kind/blob/v2.x/README.md
+1.9.0      | https://github.com/serradura/kind/blob/v1.x/README.md
 
 ## Table of Contents <!-- omit in toc -->
 - [Compatibility](#compatibility)
@@ -51,17 +57,18 @@ unreleased | https://github.com/serradura/u-case/blob/main/README.md
   - [Kind::\<Type\>.or_undefined()](#kindtypeor_undefined)
   - [Kind::\<Type\>.or()](#kindtypeor)
   - [Kind::\<Type\>.value()](#kindtypevalue-1)
+  - [Kind::\<Type\>.maybe](#kindtypemaybe)
   - [Kind::\<Type\>?](#kindtype-2)
-  - [Kind::{Array,Hash,String,Set}.value_or_empty()](#kindarrayhashstringsetvalue_or_empty)
-  - [List of all type checkers (Kind::<Type>)](#list-of-all-type-checkers-kindtype)
+  - [Kind::{Array,Hash,String,Set}.empty_or()](#kindarrayhashstringsetempty_or)
+  - [List of all type handlers](#list-of-all-type-handlers)
     - [Core](#core)
     - [Stdlib](#stdlib)
     - [Custom](#custom)
-  - [Creating type checkers](#creating-type-checkers)
+  - [Creating type handlers](#creating-type-handlers)
     - [Dynamic creation](#dynamic-creation)
       - [Using a class or a module](#using-a-class-or-a-module)
       - [Using an object which responds to ===](#using-an-object-which-responds-to-)
-    - [Kind::<Type> module](#kindtype-module)
+    - [Kind::<Type> object](#kindtype-object)
   - [Utility methods](#utility-methods)
     - [Kind.of_class?()](#kindof_class)
     - [Kind.of_module?()](#kindof_module)
@@ -92,11 +99,19 @@ unreleased | https://github.com/serradura/u-case/blob/main/README.md
   - [Kind::Maybe#try!](#kindmaybetry-1)
   - [Kind::Maybe#dig](#kindmaybedig)
   - [Kind::Maybe#check](#kindmaybecheck)
+  - [Kind::Maybe#presence](#kindmaybepresence)
 - [Kind::Empty](#kindempty)
+  - [Defining Empty as Kind::Empty an alias](#defining-empty-as-kindempty-an-alias)
 - [Kind::Validator (ActiveModel::Validations)](#kindvalidator-activemodelvalidations)
   - [Usage](#usage-1)
-    - [Defining the default validation strategy](#defining-the-default-validation-strategy)
-    - [Using the `allow_nil` and `strict` options](#using-the-allow_nil-and-strict-options)
+    - [Object#===](#object)
+    - [Kind.is](#kindis-1)
+    - [Object#instance_of?](#objectinstance_of)
+    - [Object#respond_to?](#objectrespond_to)
+    - [Array.new.all? { |item| item.kind_of?(Class) }](#arraynewall--item-itemkind_ofclass-)
+    - [Array.new.all? { |item| expected_values.include?(item) }](#arraynewall--item-expected_valuesincludeitem-)
+  - [Defining the default validation strategy](#defining-the-default-validation-strategy)
+  - [Using the `allow_nil` and `strict` options](#using-the-allow_nil-and-strict-options)
 - [Similar Projects](#similar-projects)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -105,10 +120,11 @@ unreleased | https://github.com/serradura/u-case/blob/main/README.md
 
 ## Compatibility
 
-| u-case         | branch  | ruby     |  activemodel   |
+| kind           | branch  | ruby     |  activemodel   |
 | -------------- | ------- | -------- | -------------- |
-| unreleased     | main    | >= 2.2.0 | >= 3.2, <= 6.1 |
-| 4.0.0          | v4.x    | >= 2.2.0 | >= 3.2, <= 6.1 |
+| unreleased     | main    | >= 2.1.0 | >= 3.2, <= 6.1 |
+| 5.3.0          | v5.x    | >= 2.1.0 | >= 3.2, <= 6.1 |
+| 4.1.0          | v4.x    | >= 2.2.0 | >= 3.2, <= 6.1 |
 | 3.1.0          | v3.x    | >= 2.2.0 | >= 3.2, <= 6.1 |
 | 2.3.0          | v2.x    | >= 2.2.0 | >= 3.2, <= 6.0 |
 | 1.9.0          | v1.x    | >= 2.2.0 | >= 3.2, <= 6.0 |
@@ -257,6 +273,39 @@ Kind::String.value('1', default: 1)  # Kind::Error (1 expected to be a kind of S
 
 [⬆️ &nbsp;Back to Top](#table-of-contents-)
 
+### Kind::\<Type\>.maybe
+
+This method exposes a [typed `Kind::Maybe`](#kindmaybetype) and using it will be possible to apply a sequence of operations in the case of the wrapped value has the expected kind.
+
+```ruby
+Double = ->(value) do
+  Kind::Numeric.maybe(value)
+               .then { |number| number * 2 }
+               .value_or(0)
+end
+
+Double.('2') # 0
+Double.(2)   # 4
+```
+
+If it is invoked without arguments, it returns the typed Maybe. But, if it receives arguments, it will behave like the `Kind::Maybe.wrap` method. e.g.
+
+```ruby
+Kind::Integer.maybe #<Kind::Maybe::Typed:0x0000... @kind=Kind::Integer>
+
+Kind::Integer.maybe(0).some?               # true
+Kind::Integer.maybe { 1 }.some?            # true
+Kind::Integer.maybe(2) { |n| n * 2 }.some? # true
+
+Kind::Integer.maybe { 2 / 0 }.none?          # true
+Kind::Integer.maybe(2) { |n| n / 0 }.none?   # true
+Kind::Integer.maybe('2') { |n| n * n }.none? # true
+```
+
+> **Note:** You can use `Kind::\<Type\>.optional` as an alias for `Kind::\<Type\>.maybe`.
+
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
 ### Kind::\<Type\>?
 
 There is a second way to do a type verification and know if one or multiple values has the expected type. You can use the predicate kind methods (`Kind::Hash?`). e.g:
@@ -279,17 +328,17 @@ collection.select(&Kind::Enumerable?) # [{:number=>1}, {:number=>3}, [:number, 5
 
 [⬆️ &nbsp;Back to Top](#table-of-contents-)
 
-### Kind::{Array,Hash,String,Set}.value_or_empty()
+### Kind::{Array,Hash,String,Set}.empty_or()
 
-This method is available for some type checkers (`Kind::Array`, `Kind::Hash`, `Kind::String`, `Kind::Set`), and it will return an empty frozen value if the given one hasn't the expected kind.
+This method is available for some type handlers (`Kind::Array`, `Kind::Hash`, `Kind::String`, `Kind::Set`), and it will return an empty frozen value if the given one hasn't the expected kind.
 ```ruby
-Kind::Array.value_or_empty({})         # []
-Kind::Array.value_or_empty({}).frozen? # true
+Kind::Array.empty_or({})         # []
+Kind::Array.empty_or({}).frozen? # true
 ```
 
 [⬆️ &nbsp;Back to Top](#table-of-contents-)
 
-### List of all type checkers (Kind::<Type>)
+### List of all type handlers
 
 #### Core
 
@@ -328,9 +377,9 @@ Kind::Array.value_or_empty({}).frozen? # true
 
 [⬆️ &nbsp;Back to Top](#table-of-contents-)
 
-### Creating type checkers
+### Creating type handlers
 
-There are two ways to do this, you can create type checkers dynamically or defining a module.
+There are two ways to do this, you can create type handlers dynamically or defining a module.
 
 #### Dynamic creation
 
@@ -346,7 +395,7 @@ kind_of_user = Kind::Of(User)
 
 # kind_of_user.name
 # kind_of_user.kind
-# The type checker can return its kind and its name
+# The type handler can return its kind and its name
 kind_of_user.name # "User"
 kind_of_user.kind # User
 
@@ -396,6 +445,10 @@ kind_of_user.value(User.new, default: User.new) # #<User:0x0000...>
 kind_of_user.value('1', default: User.new)      # #<User:0x0000...>
 
 kind_of_user.value('1', default: 1)  # Kind::Error (1 expected to be a kind of User)
+
+# kind_of_user.maybe
+# This method returns a typed Kind::Maybe.
+kind_of_user.maybe('1').value_or(User.new) # #<User:0x0000...>
 ```
 
 [⬆️ &nbsp;Back to Top](#table-of-contents-)
@@ -412,7 +465,7 @@ PositiveInteger = Kind::Of(
 
 # PositiveInteger.name
 # PositiveInteger.kind
-# The type checker can return its kind and its name
+# The type handler can return its kind and its name
 PositiveInteger.name # "PositiveInteger"
 PositiveInteger.kind # #<Proc:0x0000.... >
 
@@ -463,13 +516,19 @@ PositiveInteger.value(2, default: 1)   # 2
 PositiveInteger.value('1', default: 1) # 1
 
 PositiveInteger.value('1', default: 0) # Kind::Error (0 expected to be a kind of PositiveInteger)
+
+# PositiveInteger.maybe
+# This method returns a typed Kind::Maybe.
+PositiveInteger.maybe(0).value_or(1) # 1
+
+PositiveInteger.maybe(2).value_or(1) # 2
 ```
 
 [⬆️ &nbsp;Back to Top](#table-of-contents-)
 
-#### Kind::<Type> module
+#### Kind::<Type> object
 
-The idea here is to create a type checker inside of the `Kind` namespace, so to do this, you will only need to use pure Ruby. e.g:
+The idea here is to create a type handler inside of the `Kind` namespace and to do this you will only need to use pure Ruby. e.g:
 
 ```ruby
 class User
@@ -477,9 +536,9 @@ end
 
 module Kind
   module User
-    extend self, TypeChecker
+    extend self, ::Kind::Object
 
-    # Define the expected kind of this type checker.
+    # Define the expected kind of this type handler.
     def kind; ::User; end
   end
 
@@ -489,7 +548,7 @@ module Kind
   end
 end
 
-# Doing this you will have the same methods of a standard type checker (like: `Kind::Symbol`).
+# Doing this you will have the same methods of a standard type handler (like: `Kind::Symbol`).
 
 user = User.new
 
@@ -507,7 +566,7 @@ The advantages of this approach are:
 
 The disadvantage is:
 
-1. You could overwrite some standard type checker or constant. I believe that this will be hard to happen, but must be your concern if you decide to use this kind of approach.
+1. You could overwrite some standard type handler or constant. I believe that this will be hard to happen, but must be your concern if you decide to use this kind of approach.
 
 [⬆️ &nbsp;Back to Top](#table-of-contents-)
 
@@ -1099,7 +1158,7 @@ def person_name(params)
 
   return default if names.size != 2
 
-  first_name, last_name = default
+  first_name, last_name = names
 
   "#{first_name} #{last_name}"
 end
@@ -1126,7 +1185,7 @@ module PersonIntroduction1
     end
 
     def age(optional)
-      optional.map { |hash| hash[:age] }.value_or(0)
+      optional.dig(:age).value_or(0)
     end
 end
 
@@ -1336,6 +1395,18 @@ Kind::Maybe(Array)
 
 [⬆️ &nbsp;Back to Top](#table-of-contents-)
 
+### Kind::Maybe#presence
+
+This method will return None if the wrapped value wasn't present.
+
+```ruby
+result = Kind::Maybe(Hash).wrap(foo: '').dig(:foo).presence
+result.none? # true
+result.value # nil
+```
+
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
 ## Kind::Empty
 
 When you define a method that has default arguments, for certain data types, you will always create a new object in memory. e.g:
@@ -1366,7 +1437,11 @@ def do_something(value, with_options: Kind::Empty::HASH)
 end
 ```
 
-One last thing, if there is no constant declared as Empty, the `kind` gem will define `Empty` as an alias for `Kind::Empty`. Knowing this, the previous example could be written like this:
+### Defining Empty as Kind::Empty an alias
+
+You can require `kind/empty/constant` to define `Empty` as a `Kind::Empty` alias. But, a `LoadError` will be raised if there is an already defined constant `Empty`.
+
+So if you required this file, the previous example could be written like this:
 
 ```ruby
 def do_something(value, with_options: Empty::HASH)
@@ -1374,7 +1449,7 @@ def do_something(value, with_options: Empty::HASH)
 end
 ```
 
-Follows the list of constants, if the alias is available to be created:
+Follows the list of constants if the alias was defined:
 
 - `Empty::SET`
 - `Empty::HASH`
@@ -1385,7 +1460,7 @@ Follows the list of constants, if the alias is available to be created:
 
 ## Kind::Validator (ActiveModel::Validations)
 
-This module enables the capability to validate types via [`ActiveModel::Validations >= 3.2, < 6.1.0`](https://api.rubyonrails.org/classes/ActiveModel/Validations.html). e.g
+This module enables the capability to validate types via [`ActiveModel::Validations >= 3.2, < 7.0`](https://api.rubyonrails.org/classes/ActiveModel/Validations.html). e.g
 
 ```ruby
 class Person
@@ -1401,26 +1476,37 @@ And to make use of it, you will need to do an explicitly require. e.g:
 
 ```ruby
 # In some Gemfile
-gem 'kind', require: 'kind/active_model/validation'
+gem 'kind', require: 'kind/validator'
 
 # In some .rb file
-require 'kind/active_model/validation'
+require 'kind/validator'
 ```
 
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
 ### Usage
 
-**[Object#kind_of?](https://ruby-doc.org/core-2.6.4/Object.html#method-i-kind_of-3F)**
+#### [Object#===](https://ruby-doc.org/core-3.0.0/Object.html#method-i-3D-3D-3D)
 
 ```ruby
 validates :name, kind: { of: String }
+```
 
-# Use an array to verify if the attribute
-# is an instance of one of the classes/modules.
+Use an array to verify if the attribute is an instance of one of the classes/modules.
 
+```ruby
 validates :status, kind: { of: [String, Symbol]}
 ```
 
-**[Kind.is](#verifying-the-kind-of-some-classmodule)**
+Because of kind verification be made via `===` you can use type handlers as the expected kinds.
+
+```ruby
+validates :alive, kind: Kind::Boolean
+```
+
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
+#### [Kind.is](#verifying-the-kind-of-some-classmodule)
 
 ```ruby
 #
@@ -1456,7 +1542,9 @@ validates :human_kind, kind: { is: Human }
 validates :human_kind, kind: { is: [Person, User] }
 ```
 
-**[Object#instance_of?](https://ruby-doc.org/core-2.6.4/Object.html#method-i-instance_of-3F)**
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
+#### [Object#instance_of?](https://ruby-doc.org/core-3.0.0/Object.html#method-i-instance_of-3F)
 
 ```ruby
 validates :name, kind: { instance_of: String }
@@ -1467,13 +1555,23 @@ validates :name, kind: { instance_of: String }
 validates :name, kind: { instance_of: [String, Symbol] }
 ```
 
-**[Object#respond_to?](https://ruby-doc.org/core-2.6.4/Object.html#method-i-respond_to-3F)**
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
+#### [Object#respond_to?](https://ruby-doc.org/core-3.0.0/Object.html#method-i-respond_to-3F)
 
 ```ruby
 validates :handler, kind: { respond_to: :call }
 ```
 
-**Array.new.all? { |item| item.kind_of?(Class) }**
+This validation can verify one or multiple methods.
+
+```ruby
+validates :params, kind: { respond_to: [:[], :values_at] }
+```
+
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
+#### Array.new.all? { |item| item.kind_of?(Class) }
 
 ```ruby
 validates :account_types, kind: { array_of: String }
@@ -1484,7 +1582,9 @@ validates :account_types, kind: { array_of: String }
 validates :account_types, kind: { array_of: [String, Symbol] }
 ```
 
-**Array.new.all? { |item| expected_values.include?(item) }**
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
+#### Array.new.all? { |item| expected_values.include?(item) }
 
 ```ruby
 # Verifies if the attribute value
@@ -1493,7 +1593,9 @@ validates :account_types, kind: { array_of: [String, Symbol] }
 validates :account_types, kind: { array_with: ['foo', 'bar'] }
 ```
 
-#### Defining the default validation strategy
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
+### Defining the default validation strategy
 
 By default, you can define the attribute type directly (without a hash). e.g.
 
@@ -1515,7 +1617,9 @@ And these are the available options to define the default strategy:
 -  `kind_of` *(default)*
 -  `instance_of`
 
-#### Using the `allow_nil` and `strict` options
+[⬆️ &nbsp;Back to Top](#table-of-contents-)
+
+### Using the `allow_nil` and `strict` options
 
 You can use the `allow_nil` option with any of the kind validations. e.g.