smart_types 0.1.0.alpha5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cf6671b5ed2aa8bc547ce1efce8ec61ea44c7e800ddec0a28424d38097f6113
-  data.tar.gz: 5dd3e4e7203652b353133b1c8ba9795b5623c7ec329801a2417b4d24c40a97bd
+  metadata.gz: a77f7989b137f4e3e7c319ad0f825f4484329ec4ff87ad04d31b9decae9bdce7
+  data.tar.gz: 7e05552fb246042a12a708089065f0916eac5565bcc4de61e4bbea5cb4d76c21
 SHA512:
-  metadata.gz: 8ebf37ceefbb4f96985e0e252b8bebf6a9c07e6d730e2c85cb065dd72cfec4473c012e6a4a1da846633e85a4701fcbeeaf57a13f97de21d6f7bc0a8d2c817ce2
-  data.tar.gz: d0318bc8233d6deca43d6b2d9cce852961385cbfbb2bc8c78c87a36e02fb45b9eed6c559a4605da1debef47d407bd4454f16aa4492f5b2e64255ed45214cca48
+  metadata.gz: 800dc2c99f6eeee87f522576483cb7583e8f63a21a98aa5ed6b7106499406336d31b4414a4146a33bd3be251268cf3f916236662398199c2e17ba5c11c4ab0d6
+  data.tar.gz: b771a4a428498a0bad62fc8f2cf67728117f3d47822da01086e70f386f822c4e001bb73ad609bc9ef049d06743ee3dfe13744db4d13964d4def5b058a323ad66

data/.rubocop.yml

@@ -5,7 +5,8 @@ inherit_gem:
     - lib/rubocop.rspec.yml
 
 AllCops:
-  TargetRubyVersion: 2.4.9
+  TargetRubyVersion: 3.0.0
+  NewCops: enable
   Include:
     - lib/**/*.rb
     - spec/**/*.rb
@@ -13,3 +14,11 @@ AllCops:
     - Rakefile
     - smart_types.gemspec
     - bin/console
+
+# NOTE: support for old ruby versions
+Style/RedundantBegin:
+  Enabled: false
+
+# NOTE: used only in specs and it is ok in specs
+Lint/EmptyBlock:
+  Enabled: false

data/CHANGELOG.md

@@ -1,2 +1,48 @@
 # Changelog
 All notable changes to this project will be documented in this file.
+
+# [0.4.0] - 2021-01-18
+### Added
+- Support for *Ruby 3*;
+
+## [0.3.0] - 2020-12-22
+### Added
+- Extended **Type Definition API**: support for **runtime attributes**:
+  - Type checkers, type casters and type invariants now receives runtime attributes (you can omit these);
+  - Type definitioning extended with `runtime_attribute_checker`-checker definition (runtime attributes validator);
+  - Types with incorrect runtime attributes will raise `SmartCore::Types::IncorrectRuntimeAttributesError` exception;
+  - Types which has no support for runtime attributes will raise `SmartCore::Types::RuntimeAttributesUnsupportedError` excpetion;
+  - All types by default has a method alias (`()`) which does not allow runtime attributes (for example: `SmartCore::Types::Value::String` has
+    a runtime-based alias `SmartCore::Types::Value::String()` which does not accept any attribute
+    (`SmartCore::Types::Value::String('test')` will raise `SmartCore::Types::RuntimeAttributesUnsupportedError` respectively));
+- Extended Internal **Type Development API**:
+  - all types has a reference to it's type category;
+- Brand new `SmartCore::Types::Protocol` type category and new types:
+  - `SmartCore::Types::Protocol::InstanceOf` (runtime-based type);
+- Brand new `SmartCore::Types::Variadic` type category and new types:
+  - `SmartCore::Types::Variadic::Tuple` (runtime-based type);
+- New types of `SmartCore::Types::Value` category:
+  - `SmartCore::Types::Value::Set` (based on `Set` type with a support for type casting);
+- Support for BasicObject values inside type checkers that can not be checked correctly via `#is_a?/#kind_of?` before;
+
+### Changed
+- Updated development dependencies;
+- Drop `Travis CI` (TODO: migrate to `Github Actions`);
+- **Ruby@2.4** is no longer supported;
+
+## [0.2.0] - 2020-11-21
+### Added
+- Brand new **Type invariant API**:
+  - globally refactored validation logic (with backward compatability for `#valid?(value)` method);
+  - new type definition DSL: `.invariant(name)` and `.invariant_chain(name)`;
+  - chained invariants will be invoked according to the definition order (second invokation
+    depends on previous successful invariant check);
+  - new validation API: `validate(value)` (with `#errors` support based on invariant names);
+  - at this moment Invariant API is supported only by primitive types (type sum and type multiplication support coming soon);
+
+### Changed
+
+- Updated `smart_engine` dependency (to `~> 0.7`) (need `SmartCore::Engine::Atom`);
+
+## [0.1.0] - 2020-05-05
+- Release :)

data/Gemfile.lock

@@ -1,77 +1,105 @@
 PATH
   remote: .
   specs:
-    smart_types (0.1.0.alpha3)
-      smart_engine (~> 0.5)
+    smart_types (0.4.0)
+      smart_engine (~> 0.11)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    armitage-rubocop (0.79.0)
-      rubocop (= 0.79.0)
-      rubocop-performance (= 1.5.2)
-      rubocop-rails (= 2.4.1)
-      rubocop-rake (= 0.5.0)
-      rubocop-rspec (= 1.37.1)
-    ast (2.4.0)
-    diff-lcs (1.3)
-    docile (1.3.2)
-    jaro_winkler (1.5.4)
-    json (2.3.0)
-    parallel (1.19.1)
-    parser (2.7.0.2)
-      ast (~> 2.4.0)
-    rack (2.1.1)
+    activesupport (6.1.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    armitage-rubocop (1.7.0.1)
+      rubocop (= 1.7.0)
+      rubocop-performance (= 1.9.1)
+      rubocop-rails (= 2.9.1)
+      rubocop-rake (= 0.5.1)
+      rubocop-rspec (= 2.1.0)
+    ast (2.4.1)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.7)
+    diff-lcs (1.4.4)
+    docile (1.3.5)
+    i18n (1.8.7)
+      concurrent-ruby (~> 1.0)
+    method_source (1.0.0)
+    minitest (5.14.3)
+    parallel (1.20.1)
+    parser (3.0.0.0)
+      ast (~> 2.4.1)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rack (2.2.3)
     rainbow (3.0.0)
-    rake (13.0.1)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.1)
-      rspec-support (~> 3.9.1)
-    rspec-expectations (3.9.0)
+    rake (13.0.3)
+    regexp_parser (2.0.3)
+    rexml (3.2.4)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.2)
-    rubocop (0.79.0)
-      jaro_winkler (~> 1.5.1)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.1)
+    rubocop (1.7.0)
       parallel (~> 1.10)
-      parser (>= 2.7.0.1)
+      parser (>= 2.7.1.5)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.2.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.7)
-    rubocop-performance (1.5.2)
-      rubocop (>= 0.71.0)
-    rubocop-rails (2.4.1)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.4.0)
+      parser (>= 2.7.1.5)
+    rubocop-performance (1.9.1)
+      rubocop (>= 0.90.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rails (2.9.1)
+      activesupport (>= 4.2.0)
       rack (>= 1.1)
-      rubocop (>= 0.72.0)
-    rubocop-rake (0.5.0)
+      rubocop (>= 0.90.0, < 2.0)
+    rubocop-rake (0.5.1)
       rubocop
-    rubocop-rspec (1.37.1)
-      rubocop (>= 0.68.1)
-    ruby-progressbar (1.10.1)
-    simplecov (0.17.1)
+    rubocop-rspec (2.1.0)
+      rubocop (~> 1.0)
+      rubocop-ast (>= 1.1.0)
+    ruby-progressbar (1.11.0)
+    simplecov (0.21.2)
       docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
-    smart_engine (0.5.0)
-    unicode-display_width (1.6.0)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.2)
+    smart_engine (0.11.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (1.7.0)
+    zeitwerk (2.4.2)
 
 PLATFORMS
-  ruby
+  x86_64-darwin-19
+  x86_64-darwin-20
 
 DEPENDENCIES
-  armitage-rubocop (~> 0.78)
+  armitage-rubocop (~> 1.7)
   bundler (~> 2.1)
+  pry (~> 0.13)
   rake (~> 13.0)
-  rspec (~> 3.9)
-  simplecov (~> 0.17)
+  rspec (~> 3.10)
+  simplecov (~> 0.21)
   smart_types!
 
 BUNDLED WITH
-   2.1.2
+   2.2.3

data/README.md

@@ -1,13 +1,11 @@
-# SmartCore::Types · [![Gem Version](https://badge.fury.io/rb/smart_types.svg)](https://badge.fury.io/rb/smart_types) [![Build Status](https://travis-ci.org/smart-rb/smart_types.svg?branch=master)](https://travis-ci.org/smart-rb/smart_types)
+# SmartCore::Types · [![Gem Version](https://badge.fury.io/rb/smart_types.svg)](https://badge.fury.io/rb/smart_types)
 
 > A set of objects that acts like types (type checking and type casting) with a support for basic type algebra.
 
-Full-featured type system for any ruby project. Supports custom type definitioning,
+Minimalistic type system for any ruby project. Supports custom type definitioning,
 type validation, type casting and type categorizing. Provides a set of commonly used type
 categories and general purpose types. Has a flexible and simplest type definition toolchain.
 
-Just add and use :) Enjoy! :)
-
 ## Installation
 
 ```ruby
@@ -26,7 +24,28 @@ require 'smart_core/types'
 
 ---
 
-## Type Interface
+## Usage
+
+- [Type interface and basic type algebra](#type-interface-and-basic-type-algebra)
+- [Supported types](#supported-types)
+  - [Primitives](#primitives) (`SmartCore::Types::Value`)
+  - [Protocols](#protocols) (`SmartCore::Types::Protocol`)
+  - [Variadic](#variadic) (`SmartCore::Types::Variadic`)
+- [Nilable types](#nilable-types)
+- [Custom type definition](#custom-type-definition)
+  - [Primitive type definition](#primitive-type-definition)
+  - [With type invariants](#with-type-invariants)
+- [Type validation](#type-validation)
+- [Type casting](#type-casting)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [Build](#build)
+- [License](#license)
+- [Authors](#authors)
+
+---
+
+## Type Interface and basic type algebra
 
 ```ruby
 # documentation is coming
@@ -39,70 +58,224 @@ type3 = type1 | type2
 type4 = type1 & type2
 ```
 
+Types with runtime:
+
+```ruby
+# get a type object with a custom runtime (instances of String or Symbol):
+type = SmartCore::Types::Protocol::InstanceOf(::String, ::Symbol)
+type.valid?(:test) # => true
+type.valid?('test') # => true
+type.valid?(123.456) # => false
+
+# another type object with a custom runtime (tuple (String, Integer, Time)):
+type = SmartCore::Types::Variadic::Tuple(::String, ::Integer, ::DateTime)
+type.valid?(['test', 1, DateTime.new]) # => true
+type.valid?([:test, 2]) # => false
+```
+
 ## Supported types
 
-- Primitive Value Types:
+#### Primitives:
 
 ```ruby
 SmartCore::Types::Value::Any
+SmartCore::Types::Value::Nil
 SmartCore::Types::Value::String
 SmartCore::Types::Value::Symbol
 SmartCore::Types::Value::Text
 SmartCore::Types::Value::Integer
 SmartCore::Types::Value::Float
 SmartCore::Types::Value::Numeric
+SmartCore::Types::Value::BigDecimal
 SmartCore::Types::Value::Boolean
 SmartCore::Types::Value::Array
+SmartCore::Types::Value::Set
 SmartCore::Types::Value::Hash
 SmartCore::Types::Value::Proc
 SmartCore::Types::Value::Class
 SmartCore::Types::Value::Module
+SmartCore::Types::Value::Time
+SmartCore::Types::Value::DateTime
+SmartCore::Types::Value::Date
+SmartCore::Types::Value::TimeBased
 ```
 
 ---
 
-## Nilable types
+#### Protocols:
 
 ```ruby
-SmartCore::Types::Value::Any.nilable
-SmartCore::Types::Value::String.nilable
-SmartCore::Types::Value::Symbol.nilable
-SmartCore::Types::Value::Text.nilable
-SmartCore::Types::Value::Integer.nilable
-SmartCore::Types::Value::Float.nilable
-SmartCore::Types::Value::Numeric.nilable
-SmartCore::Types::Value::Boolean.nilable
-SmartCore::Types::Value::Array.nilable
-SmartCore::Types::Value::Hash.nilable
-SmartCore::Types::Value::Proc.nilable
-SmartCore::Types::Value::Class.nilable
-SmartCore::Types::Value::Module.nilable
+SmartCore::Types::Protocol::InstanceOf
+```
+
+```ruby
+# examples (SmartCore::Types::Protocol::InstanceOf):
+SmartCore::Types::Protocol::InstanceOf(::Integer) # only integer
+SmartCore::Types::Protocol::InstanceOf(::String, ::Symbol) # string or symbol
+SmartCore::Types::Protocol::InstanceOf(::Time, ::DateTime, ::Date) # time or datetime or date
 ```
 
 ---
 
-## Constrained types
+#### Variadic:
 
 ```ruby
-# documentation is coming
+SmartCore::Types::Variadic::Tuple
+```
+
+```ruby
+# examples (SmartCore::Types::Variadic::Tuple):
+SmartCore::Types::Variadic::Tuple(::String, ::Integer, ::Time) # array with signature [<string>, <integer>, <time>]
+SmartCore::Types::Variadic::Tuple(::Symbol, ::Float) # array with signature [<symbol>, <float>]
 ```
 
 ---
 
-## Type validation and type casting
+## Nilable types
+
+- invoke `.nilable` on any type object:
 
 ```ruby
-# documentation is coming
+SmartCore::Types::Value::String.nilable
+# -- or --
+SmartCore::Types::Value::Time.nilable
+# and etc.
 ```
 
 ---
 
 ## Custom type definition
 
+Type definition is a composition of:
+
+- type checker (required);
+- type caster (optional);
+- type invariants (optional);
+- type invariant chains (optional);
+
+Invariant is a custom validation block that will work as a logical value checker. You can have as much invariants as you want.
+
+Type invariants does not depends on each other (invariant defined out from chain does not depends on other invariants);
+
+Invariants inside invariant chains will be invoked in order they was defined and each internal invariant depends on the valid previous invairant check.
+
+**!IMPORTANT!** Type sum and type multiplication does not support invariant checking and custom invariant definitioning at this moment.
+Type sum and type mult ignores type invariants in their validation logic (currently this functionality in development yet).
+
+Invariant checking is a special validation layer (see [#type validation](#type-validation) readme section). Invariant error code pattern:
+  - for invariant chains: `TypeName.invariant_chain_name.invariant_name`;
+  - for single invariant: `TypeName.invariant_name`;
+
+#### Primitive type definition
+
 ```ruby
 # documentation is coming
 
 # example:
+SmartCore::Types::Value.define_type(:String) do |type|
+  type.define_checker do |value, runtime_attrs| # runtime attributes are optional
+    value.is_a?(::String)
+  end
+
+  type.define_caster do |value, runtime_attrs| # runtime attributes are optional
+    value.to_s
+  end
+end
+
+# get a type object:
+SmartCore::Types::Value::String
+# --- or ---
+SmartCore::Types::Value::String() # without runtime attributes
+# --- or ---
+SmartCore::Types::Value::String('some_attr', :another_attr) # with runtime attributes
+
+# work with type object: see documentation below
+```
+
+#### With type invariants
+
+```ruby
+SmartCore::Types::Value.define_type(:String) do |type|
+  type.define_checker do |value, runtime_attrs|
+    value.is_a?(::String)
+  end
+
+  type.define_caster do |value, runtime_attrs|
+    value.to_s
+  end
+
+  # NOTE:
+  #    invariant defined out from chain does not depends on other invariants
+  type.invariant(:uncensored_content) do |value, runtime_attrs|
+    !value.include?('uncensored_word')
+  end
+
+  type.invariant(:filled) do |value, runtime_attrs|
+    value != ''
+  end
+
+  type.invariant_chain(:password) do
+    invariant(:should_present) do |value, runtime_attrs|
+      value != ''
+    end
+
+    invariant(:should_have_numbers) do |value, runtime_attrs|
+      v.match?(/[0-9]+/)
+    end
+
+    # NOTE:
+    #   inside a chain each next invariant invokation
+    #   depends on previous successful invariant check
+  end
+end
+```
+
+---
+
+## Type validation
+
+Type validation reflects on two APIs:
+
+- type checker ([how to define type checkers](#custom-type-definition));
+- type invariants (invariants and invariant chains) ([how to define type invariants](#custom-type-definition));
+
+Type invariants does not depends on each other (invariant defined out from the chain does not depends on other invariants);
+
+Invariants inside invariant chains will be invoked in order they was defined and each internal invariant depends on the valid previous invairant check.
+
+**!IMPORTANT!** Type sum and type multiplication does not support invariant checking and custom invariant definitioning at this moment.
+Type sum and type mult ignores type invariants in their validation logic (currently this functionality in development yet).
+
+Invariant checking is a special validation layer (see [#type validation](#type-validation) readme section) and represents a set of error codes in result object;
+
+Type valdiation interface:
+
+- `valid?(value)` - validates value and returns `true` or `false`;
+  - returns `ture` only if the type checker returns `true` and all invariants are valid;
+- `validate(value)` - validates value and returns the monadic result object:
+  - `SmartCore::Types::Primitive::Validator::Result` for primitive types;
+  - `SmartCore::Types::Primitive::SumValidator::Result` for sum-based types;
+  - `SmartCore::Types::Primitive::MultValidator::Result` for mult-based types;
+  - `SmartCore::Types::Primitive::NilableValidator::Result` for nilable types;
+- `validate!(value)` - validates value and returns nothing (for successful validation) or
+  raises an exception (`SmartCore::Types::TypeError`) (for unsuccessful validation);
+
+Validation result object interface:
+
+- `#success?` / `#failure?` (`#success?` is a combination of `valid_check? && valid_invariants?`; `#failure?` - is an opposite of `#success?`);
+- `#valid_check?` (valid type checker or not);
+- `#valid_invariants?` (`false` if at least one invariant is invalid);
+- `#errors` (the same as `#invariant_errors` and the same as `#error_codes`) - an array of failed invariant names;
+  - error code patterns:
+    - for invariant chains: `TypeName.invariant_chain_name.invariant_name`;
+    - for single invariant: `TypeName.invariant_name`;
+- `#checked_value` (the same as `#value`) - checked value :)
+
+---
+
+Imagine that we have `String` type like this:
+
+```ruby
 SmartCore::Types::Value.define_type(:String) do |type|
   type.define_checker do |value|
     value.is_a?(::String)
@@ -111,27 +284,238 @@ SmartCore::Types::Value.define_type(:String) do |type|
   type.define_caster do |value|
     value.to_s
   end
+
+  type.invariant(:uncensored_content) do |value|
+    !value.include?('uncensored_word')
+  end
+
+  type.invariant(:filled) do |value|
+    value != ''
+  end
+
+  type.invariant_chain(:password) do
+    invariant(:should_present) { |value| value != '' }
+    invariant(:should_have_numbers) { |value| v.match?(/[0-9]+/) }
+  end
 end
 ```
 
+Validation interface and usage:
+
+```ruby
+SmartCore::Types::Value::String.valid?('test123') # => true
+SmartCore::Types::Value::String.valid?(123.45) # => false
+```
+
+```ruby
+result = SmartCore::Types::Value::String.validate('test')
+
+result.checked_value # => 'test'
+# --- same as: ---
+result.value
+
+result.success? # => false (valid_check? && valid_invariants?)
+result.failure? # => true
+
+result.valid_check? # => true
+result.valid_invariants? # => false
+
+# invariant errors:
+result.errors # => ['String.password.should_have_numbers']
+# -- same as: ---
+result.invariant_errors
+# -- same as: ---
+result.error_codes
+```
+
+```ruby
+result = SmartCore::Types::Value::String.validate('test1234')
+result.success? # => true
+result.errors # => []
+```
+
+```ruby
+SmartCore::Types::Value::String.validate!('test') # => SmartCore::Types::TypeError
+```
+
 ---
 
-## Basic type algebra
+## Type casting
 
 ```ruby
-# documentation is coming
+SmartCore::Types::Value::String.cast(123) # => "123"
+SmartCore::Types::Value::Float.cast('55') # => 55.0
 ```
 
 ---
 
-## Type system integration
+## Basic type algebra
+
+> (type sum and type multiplication does not support invariants at this moment (in development yet));
 
 ```ruby
 # documentation is coming
+
+# how to define primitive type sum:
+SmartCore::Types::Value::Text = SmartCore::Types::Value::String | SmartCore::Types::Value::Symbol
+SmartCore::Types::Value::Numeric = SmartCore::Types::Value::Float | SmartCore::Types::Value::Integer
+
+# how to define primitive type multiplication:
+SmartCore::Types::Value::CryptoString = SmartCore::Types::Value::NumberdString & SmartCore::Types::Value::SymbolicString
 ```
 
 ---
 
+## Roadmap
+
+- migrate to `Github Actions`;
+
+- support for `block`-attribute in runtime attributes;
+
+- type configuration:
+
+```ruby
+SmartCore::Types::Value.type(:Time) do |type|
+  type.configuration do |config| # config definition
+    setting :iso, :rfc2822
+    # TODO: think about a more convinient DSL
+  end
+
+  type.define_caster do |value, config| # config usage
+    case config.standard
+    when :rfc2822
+      ::Time.rfc2822(value)
+    else
+      # ...
+    end
+  end
+end
+```
+
+- pipelined type caster definition for the sum-based types:
+
+```ruby
+SmartCore::Types::Value::TimeLike = SmartCore::Types::System.type_sum(
+  SmartCore::Types::Time,
+  SmartCore::Types::DateTime,
+  SmartCore::Types::Date,
+) do |type|
+  type.define_caster(:pipelined) # try Time.cast => try DateTime.cast => try Date.cast
+end
+```
+
+- namespaced type errors:
+
+```ruby
+# before:
+SmartCore::Types::Value::Boolean.validate!(123)
+# => SmartCore::Types::TypeError
+SmartCore::Types::Value::Class.cast(123)
+# => SmartCore::Types::TypeCastingError
+
+# after:
+SmartCore::Types::Value::Boolean.validate!(123)
+# => SmartCore::Types::Value::Boolean::TypeError
+# (inheritance tree: Types::Value::<Type>::TypeError => Types::Value::TypeError => Types::TypeError)
+
+SmartCore::Types::Value::Class.cast(123)
+# => SmartCore::Types::Value::Class::TypeCastingError
+# (inheritance tree: the same as above)
+```
+
+- type refinements:
+
+```ruby
+SmartCore::Types::Value::Time.refine_checker do |value, original_checker|
+  # new type checker
+end
+
+SmartCore::Types::Value::Time.refine_caster do |value, original_caster|
+  # new type caster
+end
+
+SmartCore::Types::Value::Time.refine_runtime_attributes_checker do |value, original_checker|
+  # new runtime attribute checker
+end
+
+SmartCore::Types::Value::Time.refine_invariant(:name) do |value|
+  # new invariant
+end
+
+SmartCore::Types::Value::Time.refine_invariant_chain(:chain_name) do
+  # new invariant chain
+end
+```
+
+- options for type casters:
+
+```ruby
+SmartCore::Types::Value.define_type(:Date) do |type|
+  type.define_caster do |value, options = {}| # options goes here
+    iso = options.fetch(:iso, nil)
+    iso ? ::Date.pasre(value, iso) : ::Date.parse(value)
+  end
+end
+
+# usage:
+SmartCore::Types::Value::Date.cast('2020-01-01', { iso: :rfc3339 })
+```
+
+- new types:
+
+```ruby
+SmartCore::Types::Value::Method
+SmartCore::Types::Value::UnboundMethod
+SmartCore::Types::Value::Enumerable
+SmartCore::Types::Value::Comparable
+SmartCore::Types::Value::Enumerator
+SmartCore::Types::Value::EnumeratorChain
+SmartCore::Types::Value::Range
+SmartCore::Types::Value::Rational
+SmartCore::Types::Value::SortedSet
+SmartCore::Types::Value::IO
+SmartCore::Types::Value::StringIO
+SmartCore::Types::Value::BasicObject
+SmartCore::Types::Struct::Schema
+SmartCore::Types::Struct::JSONSchema
+SmartCore::Types::Struct::StrictArray
+SmartCore::Types::Struct::StrictHash
+SmartCore::Types::Struct::Map
+SmartCore::Types::Variadic::Enum
+SmartCore::Types::Protocol::Interface
+SmartCore::Types::Protocol::Ancestors
+SmartCore::Types::Protocol::Enumerable
+SmartCore::Types::Protocol::Comparable
+SmartCore::Types::Protocol::Forwardable
+SmartCore::Types::Protocol::Callable
+```
+
+- `#sum` alias for `|` and `#mult` alias for `&` (with a support for type name definition and other API);
+
+- type category in invariant error codes:
+```ruby
+# before:
+'String.password.should_contain_numbers' # `String` type from `Value` category
+
+# after:
+'Value.String.password.should_contain_numbers' # `Value::String`
+```
+
+- support for type of empty non-defined type (`SmartCore::Types::Primitive::Undefined`);
+- constrained types;
+- moudle-based type system integration;
+- constructor implementation and support;
+- support for invariant checking (and custom definitioning) in sum-types;
+  - to provide a type comparability and compatability between all passed types
+    you should provide `type.reconcilable { |value, *types| .... }`  setting;
+  - `type.reconcilable` should be accesible for type sum and type mult definitions;
+  - (**preliminarily**) invariants of the concrete passed type should be valid for sucessful invariant check;
+- support for invariant checking (and definitioning) in mult-types;
+  - to provide a type comparability and compatability between all passed types
+    you should provide `type.reconcilable { |value, *types| .... }`  setting;
+  - `type.reconcilable` should be accesible for type sum and type mult definitions;
+  - (**preliminarily**) all invariants of all types should be valid for sucessful invariant check;
+
 ## Contributing
 
 - Fork it ( https://github.com/smart-rb/smart_types )
@@ -140,6 +524,32 @@ end
 - Push to the branch (`git push origin feature/my-new-feature`)
 - Create new Pull Request
 
+## Build
+
+- run tests:
+
+```shell
+bundle exec rake rspec
+# --- or ---
+bundle exec rspec
+```
+
+- run code stye linting:
+
+```shell
+bundle exec rake rubocop
+# --- or ---
+bundle exec rubocop
+```
+
+- run code style linting with auto-correction:
+
+```shell
+bundle exec rake rubcoop -A
+# --- or ---
+bundle exec rubocop -A
+```
+
 ## License
 
 Released under MIT License.