safe_type 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eca25594ac5b8d10503472a6adc49dba43091c3f
+  data.tar.gz: c469b2f8539bc78995b69b200757c0c420997b75
+SHA512:
+  metadata.gz: 8f56662fd4b888c637db732c23d9248d14691af30d95499fd73e511d1cff836c5816f22b816960c9c0bcbb65aecc08f7a11f037cb9023a762d58b5bb925b3e3d
+  data.tar.gz: 4b3bc19ab41437031109d8922a9187623a5912e0dd295ab3461e26c80a44e98b5f031d0a4c15e14e1da7f552d401ab60589c14bac1cc0c5a692493b5fa3f76e9

data/README.md

@@ -0,0 +1,141 @@
+# SafeType
+[![Gem Version](https://badge.fury.io/rb/safe_type.svg)](https://badge.fury.io/rb/safe_type)
+[![Build Status](https://travis-ci.org/chanzuckerberg/safe_type.svg?branch=master)](https://travis-ci.org/chanzuckerberg/safe_type)
+[![Maintainability](https://api.codeclimate.com/v1/badges/7fbc9a4038b86ef639e1/maintainability)](https://codeclimate.com/github/chanzuckerberg/safe_type/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/7fbc9a4038b86ef639e1/test_coverage)](https://codeclimate.com/github/chanzuckerberg/safe_type/test_coverage)
+
+While working with environment variables, routing parameters, JSON objects,
+  or other Hash-like objects require parsing,
+  we often require type coercion to assure expected behaviors.
+
+***SafeType*** provides an intuitive type coercion interface and type enhancement.
+
+## Install
+
+We can install `safe_type` using `gem install`: 
+
+```bash
+gem install safe_type
+```
+
+Or we can add it as a dependency in the `Gemfile` and run `bundle install`:
+
+```ruby
+gem 'safe_type'
+```
+
+## Usage
+Using `SafeType` namespace:
+```ruby
+require 'safe_type'
+
+SafeType::coerce("SafeType", SafeType::Required::String)
+```
+
+### Coercion with Default Value
+```ruby
+SafeType::coerce("true", SafeType::Default::Boolean(false))   # => true
+SafeType::coerce(nil, SafeType::Default::Boolean(false))      # => false
+SafeType::coerce("a", SafeType::Default::Symbol(:a))          # => :a
+SafeType::coerce("123", SafeType::Default::Integer(nil))      # => 123
+SafeType::coerce("1.0", SafeType::Default::Float(nil))        # => 1.0
+SafeType::coerce("2018-06-01", SafeType::Default::Date(nil))
+# => #<Date: 2018-06-01 ((2458271j,0s,0n),+0s,2299161j)>
+```
+### Coercion with Required Value
+```ruby
+SafeType::coerce("true", SafeType::Required::Boolean)         # => true
+SafeType::coerce(nil, SafeType::Required::Boolean)            # => SafeType::CoercionError 
+SafeType::coerce("123!", SafeType::Required::Integer)         # => SafeType::CoercionError
+```
+
+### Coercion Rule
+Under the hood, all `SafeType::Required` and `SafeType::Default` modules are just
+methods for creating coercion rules. A coercion rule has to be described as a hash, 
+with a required key `type`.
+```ruby
+r = Rule.new(type: Integer)
+```
+A coercion rules support other parameters such as:
+- `required`: If a value is `nil` and has a rule with `required`,
+    it will raise an exception.
+- `default`: If a value is `nil` (not present or failed to convert),
+    it will be filled with the default.
+- `before`: A method will be called before the coercion,
+    which takes the value to coerce as input.
+- `after`: A method will be called after the coercion,
+    which takes the coercion result as input. 
+- `validate`: A method will be called to validate the input,
+    which takes the value to coerce as input. It returns `true` or `false`.
+    It will empty the value to `nil` if the validation method returns `false`.
+
+### Coerce By Rules
+Coercion can by defined a set of coercion rules.
+If the input is hash-like, then the rules shall be described as the values,
+  for each key we want to coerce in the input. 
+
+`coerce!` is a mutating method, which modifies the values in place.
+
+```ruby
+RequiredRecentDate = SafeType::Rule.new(
+  type: Date, required: true, after: lambda { |date|
+    date if date >= Date.new(2000, 1, 1) && date <= Date.new(2020, 1, 1)
+  })
+
+# => <Date: 2015-01-01 ((2457024j,0s,0n),+0s,2299161j)> 
+SafeType::coerce("2015-01-01", RequiredRecentDate) 
+# SafeType::CoercionError
+SafeType::coerce("3000-01-01", RequiredRecentDate)
+```
+Note mutating coercion can only be applied on a hash-like object.
+
+```ruby
+# ArgumentError: mutating coercion can only be applied on a hash-like object
+SafeType::coerce!("1", Rule.new(type: Integer))
+```
+
+### Coerce Environment Variables
+We have to use `String` key and values in `ENV`. 
+Here is an example of type coercion on `ENV`.
+
+```ruby
+ENV["FLAG_0"] = "true"
+ENV["FLAG_1"] = "false"
+ENV["NUM_0"] = "123"
+
+h = SafeType::coerce(ENV, {
+  FLAG_0: SafeType::Default::Boolean(false),
+  FLAG_1: SafeType::Default::Boolean(false),
+  NUM_0: SafeType::Default::Integer(0),
+}.stringify_keys).symbolize_keys 
+
+h[:FLAG_0]   # => true
+h[:FLAG_1]   # => false
+h[:NUM_0]    # => 123
+```
+
+### Coerce Hash-like Objects
+```ruby
+params = {
+  scores: ["5.0", "3.5", "4.0", "2.2"],
+  names: ["a", "b", "c", "d"],
+}
+
+SafeType::coerce!(params, {
+  scores: [SafeType::Required::Float],
+  names: [SafeType::Required::String],
+})
+
+params[:scores]   # => [5.0, 3.5, 4.0, 2.2]
+params[:names]    # => ["a", "b", "c", "d"]
+```
+
+## Prior Art
+This gem was inspired by [rails_param](https://github.com/nicolasblanco/rails_param)
+and [dry-types](https://github.com/dry-rb/dry-types). `dry-types` forces on setting
+constrains when creating new object instances. `rails_param` replies on Rails and it is
+only for the `params`. Therefore, `safe_type` was created. It integrated some ideas from both
+gems, and it was designed specifically for type checking to provide an clean and easy-to-use interface.
+
+## License
+`safe_type` is released under an MIT license.

data/lib/safe_type.rb

@@ -0,0 +1,249 @@
+require 'date'
+require 'time'
+
+module SafeType
+  module Boolean; end
+
+  module HashHelper
+    def stringify_keys
+      Hash[self.map{ |key, val| [key.to_s, val] }]
+    end
+    def symbolize_keys
+      Hash[self.map{ |key, val| [key.to_sym, val] }]
+    end
+  end
+
+  class Converter
+    @@TRUE_VALUES = %w[on On ON t true True TRUE T y yes Yes YES Y].freeze
+    @@FALSE_VALUES = %w[off Off OFF f false False FALSE F n no No NO N].freeze
+    @@METHODS = [:to_true, :to_false, :to_int, :to_float, :to_date, :to_date_time,
+      :to_time].freeze
+
+    def self.to_true(input)
+      true if @@TRUE_VALUES.include?(input.to_s)
+    end
+
+    def self.to_false(input)
+      false if @@FALSE_VALUES.include?(input.to_s)
+    end
+
+    def self.to_bool(input)
+      return true unless self.to_true(input).nil?
+      return false unless self.to_false(input).nil?
+    end
+
+    def self.to_int(input)
+      Integer(input, base=10)
+    end
+
+    def self.to_float(input)
+      Float(input)
+    end
+
+    def self.to_date(input)
+      return input unless input.respond_to?(:to_str)
+      Date.parse(input)
+    end
+
+    def self.to_date_time(input)
+      return input unless input.respond_to?(:to_str)
+      DateTime.parse(input)
+    end
+
+    def self.to_time(input)
+      return input unless input.respond_to?(:to_str)
+      Time.parse(input)
+    end
+
+    def self.to_type(input, type)
+      return input if input.is_a?(type)
+      return input.to_s if type == String
+      return input.to_sym if type == Symbol
+      return self.to_true(input) if type == TrueClass
+      return self.to_false(input) if type == FalseClass
+      return self.to_bool(input) if type == Boolean
+      return self.to_int(input) if type == Integer
+      return self.to_float(input) if type == Float
+      return self.to_date(input) if type == Date
+      return self.to_date_time(input) if type == DateTime
+      return self.to_time(input) if type == Time
+      return type.try_convert(input) if type.respond_to?(:try_convert)
+      return type.new(input) if type.respond_to?(:new)
+    end
+  end
+
+  class CoercionError < TypeError
+    def initialize(msg="unable to transform the input into the requested type.")
+      super
+    end
+  end
+
+  class Rule
+    attr_reader :type, :default, :before, :after, :validate
+    def initialize(r)
+      raise ArgumentError, "SafeType::Rule has to be descried as a hash" \
+        unless r.class == ::Hash
+      raise ArgumentError, ":type key is required" \
+        unless r.has_key?(:type)
+      raise ArgumentError, ":type has to a class or module" \
+        unless r[:type].class == ::Class || r[:type].class == ::Module
+      @type = r[:type]
+      @required = false
+      @required = true if r.has_key?(:required) && r[:required]
+      @has_default = r.has_key?(:default)
+      @default = r[:default]
+      @before = r[:before]
+      @after = r[:after]
+      @validate = r[:validate]
+    end
+
+    def required?; @required; end
+
+    def has_default?; @has_default; end
+
+    def apply(input)
+      input = @before[input] unless @before.nil?
+      begin
+        result = Converter.to_type(input, @type) \
+          if @validate.nil? || (!@validate.nil? && @validate[input])
+      rescue
+        return @default if @has_default
+        return nil unless @required
+      end
+      result = @after[result] unless @after.nil?
+      raise CoercionError if result.nil? && @required
+      return @default if result.nil?
+      result
+    end
+  end
+
+  module Default
+    def self.String(val, validate: nil, before: nil, after: nil)
+      Rule.new(type: String, default: val, validate: validate, before: before, after: after)
+    end
+
+    def self.Symbol(val, validate: nil, before: nil, after: nil)
+      Rule.new(type: Symbol, default: val, validate: validate, before: before, after: after)
+    end
+
+    def self.Boolean(val, validate: nil, before: nil, after: nil)
+      Rule.new(type: Boolean, default: val, validate: validate, before: before, after: after)
+    end
+
+    def self.Integer(val, validate: nil, before: nil, after: nil)
+      Rule.new(type: Integer, default: val, validate: validate, before: before, after: after)
+    end
+
+    def self.Float(val, validate: nil, before: nil, after: nil)
+      Rule.new(type: Float, default: val, validate: validate, before: before, after: after)
+    end
+
+    def self.Date(val, validate: nil, before: nil, after: nil)
+      Rule.new(type: Date, default: val, validate: validate, before: before, after: after)
+    end
+
+    def self.DateTime(val, validate: nil, before: nil, after: nil)
+      Rule.new(type: DateTime, default: val, validate: validate, before: before, after: after)
+    end
+
+    def self.Time(val, validate: nil, before: nil, after: nil)
+      Rule.new(type: Time, default: val, validate: validate, before: before, after: after)
+    end
+  end
+
+  module Required
+    def self.String(validate: nil, before: nil, after: nil)
+      Rule.new(type: ::String, required: true, validate: validate, before: before, after: after)
+    end
+
+    def self.Symbol(validate: nil, before: nil, after: nil)
+      Rule.new(type: ::Symbol, required: true, validate: validate, before: before, after: after)
+    end
+
+    def self.Boolean(validate: nil, before: nil, after: nil)
+      Rule.new(type: SafeType::Boolean, required: true, validate: validate,
+               before: before, after: after)
+    end
+
+    def self.Integer(validate: nil, before: nil, after: nil)
+      Rule.new(type: ::Integer, required: true, validate: validate, before: before, after: after)
+    end
+
+    def self.Float(validate: nil, before: nil, after: nil)
+      Rule.new(type: ::Float, required: true, validate: validate, before: before, after: after)
+    end
+
+    def self.Date(validate: nil, before: nil, after: nil)
+      Rule.new(type: ::Date, required: true, validate: validate, before: before, after: after)
+    end
+
+    def self.DateTime(validate: nil, before: nil, after: nil)
+      Rule.new(type: ::DateTime, required: true, validate: validate, before: before, after: after)
+    end
+
+    def self.Time(validate: nil, before: nil, after: nil)
+      Rule.new(type: ::Time, required: true, validate: validate, before: before, after: after)
+    end
+
+    String = Rule.new(type: ::String, required: true)
+    Symbol = Rule.new(type: ::Symbol, required: true)
+    Boolean = Rule.new(type: SafeType::Boolean, required: true)
+    Integer = Rule.new(type: ::Integer, required: true)
+    Float = Rule.new(type: ::Float, required: true)
+    Date = Rule.new(type: ::Date, required: true)
+    DateTime = Rule.new(type: ::DateTime, required: true)
+    Time = Rule.new(type: ::Time, required: true)
+  end
+
+  def coerce(input, params)
+    return params.apply(input) if params.class == Rule
+    if params.class == ::Hash
+      result = {}
+      params.each do |key, val|
+        result[key] = coerce(input[key], val)
+      end
+      return result
+    end
+    if params.class == ::Array
+      return [] if input.nil?
+      result = Array.new(input.length)
+      i = 0
+      while i < input.length
+        result[i] = coerce(input[i], params[i % params.length])
+        i += 1
+      end
+      return result
+    end
+    raise ArgumentError, "invalid coercion rule"
+  end
+
+  def coerce!(input, params)
+    if params.class == ::Hash
+      params.each do |key, val|
+        if val.class == ::Hash
+          coerce!(input[key], val)
+        else
+          input[key] = coerce(input[key], val)
+        end
+      end
+      return nil
+    end
+    if params.class == ::Array
+      i = 0
+      while i < input.length
+        input[i] = coerce(input[i], params[i % params.length])
+        i += 1
+      end
+      return nil
+    end
+    raise ArgumentError, "invalid coercion rule"
+  end
+
+  class << self
+    include SafeType
+  end
+end
+
+class TrueClass; include SafeType::Boolean; end
+class FalseClass; include SafeType::Boolean; end
+class Hash; include SafeType::HashHelper; end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: safe_type
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Donald Dong
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-06-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: " \n    Type coercion & Type Enhancement\n  "
+email: mail@ddong.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/safe_type.rb
+homepage: https://github.com/chanzuckerberg/safe_type
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--charset=UTF-8"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2.1
+signing_key: 
+specification_version: 4
+summary: Type coercion & Type Enhancement
+test_files: []